Skip to content

Make --check graphviz-version-independent; guard both committed diagrams in CI - #19

Merged
inth3shadows merged 2 commits into
masterfrom
claude-forage
Jul 19, 2026
Merged

Make --check graphviz-version-independent; guard both committed diagrams in CI#19
inth3shadows merged 2 commits into
masterfrom
claude-forage

Conversation

@inth3shadows

Copy link
Copy Markdown
Owner

What

--check byte-compared the rendered SVG, which is graphviz-version-specific, so it false-failed whenever the committed image and the checking machine used different graphviz builds (this repo's committed diagrams are graphviz 15.0.0; ubuntu-latest apt ships 2.42.2). That made the drift-guard unusable in CI — the exact place it was built for. Its own code even hedged this ("the same-generator caveat every regenerate-and-diff artifact check carries").

Fix: for svg output, --check now compares the graph structure — the sorted set of node ids and directed edges, parsed from the SVG's <title> elements — instead of raw bytes:

  • Graphviz-version independent (titles are the semantic ids; layout/version stamp are ignored).
  • Order-insensitive (codegraph's enumeration order isn't guaranteed stable run-to-run).
  • Fails only on structural drift (a caller/callee/edge appearing or disappearing); a cosmetic-only change with the identical graph is tolerated by design.
  • Non-svg formats keep the byte-compare and its documented same-version caveat.

No new flag, no new committed artifact type. ~67 lines (svgStructure, decodeXmlEntities).

Dogfood it — new diagrams CI job

Installs codegraph (pinned @1.4.1), builds a fresh index, and runs --check on both committed diagrams, so a PR that changes the code but not the diagram fails.

Note for reviewers: this is the first CI job that installs codegraph + builds an index. If that step is flaky on GitHub's runners, the intended fallback is continue-on-error: true (advisory instead of blocking). Watching this PR's diagrams job is the real test of codegraph-in-CI.

It immediately caught real rot

docs/buildDot-callgraph.svg was already stale — missing the nodeIdentities node/edge that #13 added to buildDot, because nothing ever re-checked it. Regenerated it, wrapped it in codeshot:buildDot markers so it's now guardable, and fixed the now-wrong "five callees" prose in TECHNICAL.md.

Tests

83 pass (was 77). New tests cover entity decoding, order-insensitivity, attribute-order tolerance, cosmetic-vs-structural drift, and a real dot -Tsvg render whose parsed structure is asserted against the DOT — proving the parser matches actual graphviz output.

…ams in CI

--check byte-compared the rendered SVG, so it false-failed whenever the
committed image and the checking machine used different graphviz versions
(committed diagrams are graphviz 15.0.0; ubuntu-latest apt is 2.42.2) — which
made the drift-guard unusable in CI, the very place it was built for.

For svg output, --check now compares the graph STRUCTURE (the set of node ids
and directed edges, parsed from the SVG's <title> elements) instead of raw
bytes: version-independent, order-insensitive (codegraph's enumeration order
isn't guaranteed stable run-to-run), and it fails only on structural drift — a
caller/callee/edge appearing or disappearing — not cosmetic recolors. Non-svg
formats keep the byte-compare and its same-graphviz-version caveat.

A new CI `diagrams` job dogfoods this: installs codegraph, builds a fresh
index, and runs --check on both committed diagrams, so a PR that changes the
code but not the diagram fails.

Building it immediately caught real rot: docs/buildDot-callgraph.svg was stale,
missing the nodeIdentities node/edge that #13 added to buildDot. Regenerated
it, wrapped it in codeshot:buildDot markers so it's guardable, and fixed the
now-wrong "five callees" prose in TECHNICAL.md.
… 'index'

'codegraph index' rebuilds an existing index and errors when the repo was never
initialized — which a CI checkout, with no committed .codegraph, never was. The
diagrams job hit '✗ CodeGraph not initialized'. 'init' builds the initial index.
@inth3shadows
inth3shadows merged commit a0be5ab into master Jul 19, 2026
5 checks passed
@inth3shadows
inth3shadows deleted the claude-forage branch July 19, 2026 12:28
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant