feat(scripts): interactive dependency-graph viewer, with when-to-use guidance

[thymikee]

Summary

An interactive, pannable graph of every production file under src/, rendered into one
self-contained HTML file — no external requests, no build step, no runtime dependency. Layouts are
precomputed at build time and shipped as coordinates, so the viewer never runs a physics simulation
on the reader's device and a given commit always renders identically.

pnpm depgraph                       # -> .tmp/depgraph/index.html (+ index.json)
pnpm depgraph --out /tmp/graph.html
pnpm depgraph:test

Tooling only. Nothing here runs in CI and nothing here gates a merge.

It reuses the layering gate's model

The graph is extracted with scripts/layering/model.ts — the same module check.ts uses in CI — so
the file set, zone partition, edge kinds (value / type-only / dynamic) and cycle definition are
identical to the rules actually enforced. A separate extractor with its own resolution behaviour
would draw a graph nobody is enforcing.

That shared model gives a free self-check: the viewer's R6 count reproduces
TYPE_INVERSION_BASELINE exactly. Verified against current main — 898 files, 4627 edges, 25 zones,
42 type-only inversions.

When it is productive — and when it misleads

This is the part the README now spells out, because the honest answer is "three questions, and it
misleads on a fourth."

Worth reaching for:

Question	What answers it
What am I about to break?	nodes[].in — dependent count. Counts type-only and dynamic edges a grep for from '...' misses.
Where is the debt concentrated?	zoneEdges — which boundary carries the most traffic, in one query.
What's wrong that CI doesn't enforce?	~1300 transitively redundant value edges, 8 type-only/dynamic cycles — both outside the gate by design.

A "redundant" edge means the target is still reachable at distance ≥ 2 over value edges, so the
direct import changes nothing about what the module can see. That makes it a candidate, not a
defect — a direct import is often clearer than a re-export chain. At ~1300 it is a place to look,
never a work list.

Where it misleads — a cluster's size is not its difficulty. Stated plainly in the README because
it already cost real time: commands -> client looked like the obvious win at 28 type-only
inversions all pointing at one file. Moving that file down took the gate from 42 to 48, because
the vocabulary it holds depends on commands/, metro/, core/ and remote/ — declaring it in
contracts/ made the foundation depend on the layers above it. The render shows you an edge's
weight, not whether it can be reversed.

So the README pairs the visual question with the numeric one that answers "can this actually move?",
including a worked query over index.json that reproduces the gate's R6 breakdown. Both examples
were run against real output rather than written from memory — the first draft's example filtered on
zoneEdges[].backEdge and returned an empty list, which is the R5 gate passing rather than a useful
result. That footgun is now documented next to the query.

What is authoritative

pnpm check:layering. The viewer reads the same model so the numbers should agree, but if they ever
diverge the gate is right and the graph is stale.

Two things to know before merging

scripts/depgraph/** joins Fallow's ignorePatterns, alongside scripts/layering/**,
scripts/perf/** and scripts/maestro-conformance/** — how this repo already treats tooling trees
(not baselined, not inline-suppressed). Worth knowing rather than discovering: that exempts
viewer.js from the complexity gate, and its draw function would fail it. If you'd rather this
code met the same bar as src/, say so and I'll split it instead of exempting it.

Two exports added to scripts/layering/model.ts: zoneRank (the viewer colours nodes by rank,
so an inversion reads as an edge pointing the wrong way down the ramp) and targetDagZone,
previously module-private. Both are additive; the gate's behaviour is unchanged.

Validation

pnpm check green — lint, typecheck, R1–R8, production exports, MCP metadata, build, bundle owner
files, Fallow, 4488 unit tests. pnpm depgraph:test covers the graph model (5 tests).

This branch was rebuilt from current main rather than rebased: the earlier version was cut from a
pre-#1405 base and carried stray oxfmt output across 69 unrelated files. Only the viewer's own
files are in this diff.

---

Generated by Claude Code

[github-actions]

Size Report

Metric	Base	Current	Diff
JS raw	1.85 MB	1.85 MB	0 B
JS gzip	592.4 kB	592.4 kB	0 B
npm tarball	706.5 kB	706.5 kB	+21 B
npm unpacked	2.47 MB	2.47 MB	+171 B

Startup median (7 runs, lower is better):

Scenario	Base	Current	Diff
CLI --version	28.9 ms	27.2 ms	-1.8 ms
CLI --help	59.9 ms	57.0 ms	-2.9 ms

Top changed chunks: no changes in the largest emitted chunks.

[github-actions]

PR Preview Action v1.8.1
Preview removed because the pull request was closed.
2026-07-27 08:40 UTC

[thymikee]

Not ready to merge; four actionable findings:

• P1 — primary implementation is hidden as binary. scripts/depgraph/model.ts and layout.ts contain literal U+0000 delimiters, so Git/GitHub render both as Binary files differ. Replace them with textual escapes (for example \0) or structured keys so the implementation is reviewable.
• P1 — --out can destroy its own HTML output. build.ts writes HTML to outPath, then derives the JSON path by replacing only a terminal .html suffix with .json. For pnpm depgraph --out /tmp/graph, both paths are identical and JSON overwrites the HTML. Require/normalize .html or always derive a distinct sibling, and add a CLI/build regression test.
• P1 — the redundant-edge claim is semantically false. A module path A → B → C does not make C's exports lexically available in A, so removing A's direct import of C can break the program. The added test demonstrates this: B re-exports c as b, while A directly imports c. Reframe the metric as runtime module-reachability only (including side-effect/order caveats), or make the analysis symbol/export-aware before advertising ~1,300 simplification candidates.
• P2 — the viewer bypasses repository maintainability policy. The new viewer.js is 920 lines (and layout.ts is 415), while AGENTS.md requires extraction past 500 LOC. Adding scripts/depgraph/** to Fallow's ignore list explicitly removes complexity enforcement. Split the viewer into focused modules and keep the new tooling under the normal quality gate rather than exempting it.

All ordinary checks are green, but depgraph:test only covers five model tests and does not exercise build/render/layout/CLI behavior; a green exact-head regression for the output-path case is required.

[thymikee]

Closing — not merging this. The visual was a one-time aid to get an overview, and it did not earn ongoing maintenance: neither @thymikee nor I drew a conclusion from the render itself. Every finding in the boundary work came from numeric queries against scripts/layering/model.ts, which is already on main.

The honest cost/benefit, measured rather than asserted:

	this PR	analysis-only, no exemption
Fallow complexity findings	23 (one CRITICAL)	2
Unused files / exports / clones	2 / 3 / 1	0 / 0 / 0
Lines	2811	~590

So 2200 lines and a Fallow exemption bought a rendering nobody read. Even the analysis-only variant was not load-bearing — the ad-hoc one-liners that produced every actual result imported the gate's model directly and needed none of this package.

Nothing is lost from main: the layering gate (R1–R8) is the enforcement, and docs/dependency-graph-findings.md keeps the analysis record. That doc pointed at this branch for the tooling, so it is being made self-contained with the re-derivation recipe inline — a few lines of query instead of a package.

The experiment that produced the table above is on scratch/depgraph-report if anyone wants to reproduce it; both it and claude/depgraph-viewer are being deleted.

---

Generated by Claude Code