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)

来源