diagram-drift

Detect drift between a Mermaid architecture diagram and the codebase it describes.

架构图漂移检测器：给 Agent 一份 Mermaid 架构图（graph/flowchart）和一个代码库，check 会精准报告「图里画的节点代码里还有没有、图中断言的依赖关系代码里是否成立」。

Before / After

Before — An architecture diagram is decoration. Nobody re-checks it against
the code, so it slowly lies: a deleted module is still drawn, an edge claims a
dependency that no longer exists.

After — A precise drift report: which nodes in the diagram have no matching
definition in code, which diagram edges the code doesn't actually honor, and
which real modules the diagram forgot to draw.

What it does

• check — parse a Mermaid graph/flowchart, scan the codebase for
  definitions (class/def/module names) and import/call relationships, then
  classify every node and edge.
• report — re-render the last DRIFT_REPORT.md from the store.
• Output — DRIFT_REPORT.md (human) + drift-state.json (machine-readable, so
  an agent can read it directly).
• Zero third-party dependencies — pure standard library; Python uses ast,
  JS/TS/Go and other languages use regex heuristics. No pip install.

Drift types

Install

Clone into your agent's skills directory. No pip install required.

Codex

git clone https://github.com/whaojie797-design/diagram-drift ~/.codex/skills/diagram-drift

Claude Code

git clone https://github.com/whaojie797-design/diagram-drift ~/.claude/skills/diagram-drift

Cursor

git clone https://github.com/whaojie797-design/diagram-drift ~/.cursor/skills/diagram-drift

Quick start

# 1. point at a diagram (a .md with a ```mermaid block, or a .mmd) and a codebase
python scripts/drift.py check --diagram arch.md --root ./src --store .driftstore

# 2. later, re-check after the code changed
python scripts/drift.py check --diagram arch.md --root ./src --store .driftstore

# 3. re-render the last report
python scripts/drift.py report --store .driftstore

--ignore dir1,dir2 skips extra directories on top of the built-in ignores
(node_modules, dist, tests, __pycache__, …).

Sample report (real)

$ python scripts/drift.py check --diagram arch.md --root code_drifted --store .ds
Parsed diagram: 5 nodes, 5 edges
[OK]   node — Gateway
[OK]   node — AuthService
[OK]   node — BillingService
[HIGH] node — NotifyService — no definition or module matches 'Notify Service'
[OK]   node — Database
[OK]   edge — Gateway -> AuthService
[OK]   edge — Gateway -> BillingService
[OK]   edge — AuthService -> Database
[OK]   edge — BillingService -> Database
[HIGH] edge — BillingService -> NotifyService — BillingService does not import/call NotifyService
[INFO] module — analytics — module 'analytics' exists in code but is absent from the diagram

5 nodes · 5 edges · 2 drift (HIGH) · 8 consistent

Against a codebase that still matches the diagram, the same command reports
0 drift (HIGH) · 10 consistent.

How it works

1. Extract the diagram source (a fenced ```mermaid block, or a raw
   graph/flowchart string).
2. Parse nodes and edges with a small Mermaid subset parser (square/round/
   diamond/cylinder shapes, -->, -.->, ==>, labeled and & chains).
3. Walk the codebase, collecting definitions and per-module import/call tokens.
   Python via ast; other languages via regex.
4. For each node, check whether any of its id/label tokens matches a code
   definition or module name. For each edge, check whether the source module
   actually imports/calls the target. Cross-language name matching normalizes
   case and separators (AuthService ≡ auth_service).
5. Write DRIFT_REPORT.md + drift-state.json.

Everything is deterministic; the test suite runs entirely against local
fixtures (tests/fixtures/code_clean vs code_drifted).

Limitations

• It matches on names and import/call tokens, not full data-flow. A node
  whose name was renamed (but behavior preserved) is still flagged as
  missing-in-code.
• Edge validation is heuristic: it confirms the source module references the
  target module/identifier, not that the call is on the specific path drawn.
• Non-Python languages rely on regex; unusual import styles may be missed.
  Extend scanner.py if you need deeper coverage for a specific language.

License

MIT © 2026 whaojie797-design