feat(scripts): dependency-graph report over the layering gate's model

[thymikee]

Summary

The analysis half of the graph tooling, without the renderer. Emits the production import graph as
JSON plus a short summary of what the layering gate deliberately does not enforce.

$ pnpm depgraph
Dependency graph: 898 files, 4627 edges, 25 zones
  value-import cycles (R4): 0
  type-only/dynamic cycles (not gate-rejected): 8
  spine back-edges (R5): 0
  type-only spine inversions (R6): 42
  transitively redundant value edges: 1338
  wrote .tmp/depgraph/graph.json

392 lines, pnpm check green, and — the part that matters — it needs no Fallow exemption.

Why keep this when the viewer was dropped

#1409 rendered the same data and was closed: ~2200 lines plus an exemption for a 920-line canvas
file, and nobody drew a conclusion from the picture. This is the half that computes things you
cannot get another way:

• Transitively redundant value edges — the target is still reachable from the source at distance
  ≥ 2, so the direct import changes nothing about what the module can see. That needs a real
  reachability pass, not a grep. A candidate list, not a defect list: a direct import is often
  clearer than a re-export chain, and at ~1300 it is a place to look, never a work list.
• Cycles over type-only and dynamic edges — the loops R4 excludes by design (a type-only import
  is free at runtime; a dynamic one is a deliberate cold-start seam). 8 of them.
• Per-file fan-in/fan-out and lvl (longest path to a sink), per-zone size — blast radius and
  "which boundary is big", in one query.

It reuses the gate's model

Extraction is scripts/layering/model.ts, the same module check.ts uses in CI, so the file set,
zone partition, edge kinds and cycle definition are the ones actually enforced. A separate extractor
would describe a graph nobody gates.

That gives a free consistency check: the R6 count reproduces TYPE_INVERSION_BASELINE. If they
disagree, one of the two is stale — and the gate is the one that wins.

No exemption, and what that took

scripts/depgraph/** is deliberately absent from Fallow's ignorePatterns, unlike
scripts/layering/**, scripts/perf/** and scripts/maestro-conformance/**. Getting there meant
fixing findings rather than suppressing them:

Finding	Fix
clone group	extracted valueSuccessors — the value-edge adjacency was built identically in markRedundantEdges and computeLevels
buildGraph 81 lines / 20 cyclomatic	split into indexCyclesByFile, buildNodes, aggregateZones, aggregateZoneEdges
markRedundantEdges 20 cognitive	split out reachableBeyondDirectEdge
aggregateZoneEdges CRAP 31.6	extracted compareZoneEdges and crossedZonePair
CRAP 42 nested ternary	extracted edgeKindCode / edgeFlags
3 unused exports, 2 unused files	un-exported buildPayload/main; deleted fileGroup and the group node field, both dead once the layout went

Two additive exports

scripts/layering/model.ts gains zoneRank (so a consumer can tell an inversion from an ordinary
edge without re-deriving the spine) and exports targetDagZone, previously module-private. The
gate's own behaviour is unchanged.

Validation

pnpm check green — lint, typecheck, R1–R8, production exports, MCP metadata, build, bundle owner
files, Fallow with no exemption, 4488 unit tests, plus 5 tests on the graph model.

Note docs/dependency-graph-findings.md on main documents an inline throwaway probe for the same
queries, added when the viewer was dropped. That stays useful for one-off questions; this is for the
two computations a probe cannot cheaply reproduce. If you would rather keep only the probe, this PR
is the thing to drop — the doc does not depend on it.

---

Generated by Claude Code

[github-actions]

Size Report

Metric	Base	Current	Diff
JS raw	1.85 MB	1.85 MB	-806 B
JS gzip	592.7 kB	592.4 kB	-333 B
npm tarball	706.9 kB	706.5 kB	-409 B
npm unpacked	2.47 MB	2.47 MB	-1.3 kB

Startup median (7 runs, lower is better):

Scenario	Base	Current	Diff
CLI --version	26.8 ms	26.6 ms	-0.2 ms
CLI --help	56.9 ms	57.7 ms	+0.8 ms

Top changed chunks:

Chunk	Raw diff	Gzip diff
dist/src/cli-help.js	-806 B	-333 B

[github-actions]

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

[thymikee]

Not ready to merge. The renderer/Fallow-exemption removal is a good scope reduction, and #1409's HTML/JSON overwrite bug is structurally gone, but two P1s remain:

• P1 — primary implementation is still binary/unreviewable. scripts/depgraph/model.ts contains literal U+0000 delimiters, so Git/GitHub reports the new ~346-line file as binary (- -) and hides its diff. Replace them with textual escapes or structured keys and add a raw-NUL guard.
• P1 — “transitively redundant” still overclaims removability. Module reachability A → B → C does not make C's exports available in A or preserve side-effect/evaluation semantics. The test itself proves the gap: A directly imports c, while B re-exports it as b; deleting A → C removes A's c binding. Reframe this strictly as static module-reachability with caveats, or implement symbol/export-aware analysis before calling ~1,300 edges simplification candidates.

Two P2 validation/docs issues also need correction:

• The five tests cover only model.ts; no test invokes build.ts, and depgraph:test is not part of pnpm check. Add subprocess coverage for default and explicit --out, JSON/output shape, invalid/missing arguments, and summary/count consistency, then run it plus pnpm check on the exact head.
• README's worked query still loads .tmp/depgraph/index.json, but pnpm depgraph now writes .tmp/depgraph/graph.json; the documented command fails as written.

Keep ready-for-human withheld until these are resolved and required CI is green.

[thymikee]

Re-reviewed exact head e1271cac. The new Layering Guard count check is directionally useful, but prior blockers remain:

• P1: scripts/depgraph/model.ts still contains literal NUL bytes, so Git treats the primary implementation as binary and hides its diff. Replace them with escaped delimiters and add a guard.
• P1: “transitively redundant” still overclaims safe removability. Module reachability does not preserve lexical bindings, re-export names, evaluation timing, or side effects; the existing A/B/C test itself loses the direct c binding if A→C is removed. Reframe as reachability-only or implement symbol/export-aware analysis.
• P2: neither depgraph:test nor CI invokes build.ts; there is still no subprocess coverage for output paths, JSON/wire shape (including typeInversions), summary consistency, or bad arguments. The new test checks only model-derived inversion counts against the baseline.
• P2: README still queries index.json although the tool writes graph.json, overstates what collapsed zoneEdges can reproduce, and now says both that the report runs in CI and that nothing here runs in CI.

Keep ready-for-human withheld.

[thymikee]

All four addressed in aeecf65. pnpm check green, 4488 unit tests, 10 depgraph tests.

P1 — binary source. Two raw NUL bytes used as map-key delimiters, now a unicode escape: identical at runtime, textual on disk. git diff origin/main...HEAD -- scripts/depgraph/model.ts reports 386 0 instead of - -, so the whole implementation is reviewable.

Worth admitting how this survived: I saw the symptom repeatedly — every grep on that file printed binary file matches — and routed around it with python each time instead of asking why. Guarded repo-wide rather than for this one file, since nothing else would catch a recurrence and the failure mode is silent (the code works, the review doesn't). Verified by reintroducing a NUL and watching the test fail.

P1 — removability overclaim. You're right, and my own fixture proved it: a imports { c } while b re-exports it as { c as b }, so the path exists and deleting a -> c still breaks a. The comment on that fixture said "removable".

Renamed to what it measures — transitivelyReachable, markTransitivelyReachableEdges — and the summary now reads:

value edges whose target is also reachable at distance >= 2: 1338
  (reachability only — not a removability claim, see scripts/depgraph/README.md)

The three caveats (bindings aren't carried, side-effect timing isn't preserved, a direct import is often deliberate) are stated at the marker function, on the fixture, and in the README, with your c/c as b counterexample written out. Symbol-level analysis is named as what deciding any individual edge would actually take. No count is presented as a work list.

P2 — no build.ts coverage. Correct, all five tests hit model.ts only. Added three subprocess tests: default path with the summary asserted against the payload it was derived from, --out honoured with valid JSON at the target, and a trailing --out falling back rather than crashing — pinned so that's a decision rather than an accident. pnpm depgraph:test now runs inside check:tooling, so pnpm check covers it.

P2 — README. Three errors, all real: it queried index.json after the output moved to graph.json (so the documented command failed as written), it derived inversions from collapsed zoneEdges which can undercount, and it asserted both that the report runs in CI and that nothing here does. The query now reads typeInversions and I ran it verbatim against real output. The CI paragraph names the single test that runs (model.test.ts, in the Layering Guard job) and states plainly that nothing else here gates a merge.

One thing I did not change, flagged in case you disagree: zoneEdges still carries count/valueCount from the collapsed list. I documented the undercount hazard next to the query rather than removing the field, because the aggregate is still the right answer for "which boundary carries the most traffic" — it's only unsafe as a route to the inversion count. Happy to drop valueCount if you'd rather it not be derivable at all.

---

Generated by Claude Code

[thymikee]

Re-reviewed exact head aeecf656. The four prior blockers are fixed and the implementation/tests/checks are otherwise clean. P2 docs: scripts/depgraph/README.md says there is no renderer and JSON is the productive artifact, but later tells users “use the render,” refers to “the picture,” and calls it “the viewer.” Replace those stale renderer/viewer references with the JSON/report workflow so the documented instructions are internally consistent and executable. Keep ready-for-human withheld until that is corrected.