ArchGuard: The Visual Architecture Linter for Open-Source Repositories

Описание и применение

ArchGuard автоматически проверяет соответствие кода визуальной архитектуре, извлекая зависимости из изображения диаграммы и сравнивая их с реальными импортами, выдавая отчёт о нарушениях.

Задача

Architecture diagrams in README files become stale, leading to undeclared code imports that violate architectural boundaries and cause codebase rot.

Результат

ArchGuard detected a single undeclared edge (order_service → database) in a demo repository, reported it in CI, and after commenting out the line, the repository conformed to the diagram with exit 0.

Рабочий процесс

• 1. Provide architecture.png and repository path to ArchGuard CLI
• 2. ArchGuard uses Gemma 4 to extract declared edges from the diagram
• 3. ArchGuard scans Python source files with the stdlib ast module to collect actual imports
• 4. ArchGuard diffs declared vs actual edges to find undeclared imports
• 5. If undeclared edges exist, ArchGuard exits with code 1, flags file/line, and generates drift_report.md and drift_report.html
• 6. Fix the drift (e.g., comment out offending line) and re-run to achieve exit 0

Доказательства

The architecture diagram in your README is the contract. Undeclared code imports are drift.

Источник

ArchGuard bridges the visual diagram and executable code.

Источник

⚠️ Architectural drift detected: 1 undeclared edge(s) ! order_service -> database in order_service/checkout.py:2 Reports generated: drift_report.md, drift_report.html

Источник

✅ 0 undeclared edges. Codebase conforms 100% to architecture.png. (Exit Code: 0)

Источник