Skip to content

Commit f19864e

Browse files
thymikeeclaude
andauthored
feat(scripts): dependency-graph report over the layering gate's model (#1410)
* feat(scripts): dependency-graph report over the layering gate's model Reports what the layering gate deliberately does not enforce, as JSON plus a short summary. No renderer: the productive artifact is the JSON. pnpm depgraph # -> .tmp/depgraph/graph.json + summary pnpm depgraph:test 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 The two numbers worth having are the ones CI cannot give you. Transitively redundant value edges — where the target is still reachable at distance >= 2, so the direct import changes nothing about what the module can see — need a real reachability pass, not a grep. And cycle detection over type-only and dynamic edges covers the loops R4 excludes by design. Both are candidate lists, never work lists; at ~1300 the redundancy set is a place to look. It reuses 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 enforced ones. A second extractor would describe a graph nobody gates. Consequence worth having: its R6 count reproduces TYPE_INVERSION_BASELINE, so a mismatch means one of the two is stale. This is the analysis half of a viewer that was built and dropped. The render cost ~2200 lines and needed a Fallow exemption for a 920-line canvas file, and nobody read it. Everything here clears the repo's bar with NO exemption — scripts/depgraph is deliberately absent from ignorePatterns, unlike scripts/layering, scripts/perf and scripts/maestro-conformance. Getting there meant fixing rather than suppressing: extracted `valueSuccessors` (the value-edge adjacency was built identically in two places — a real clone), split `buildGraph` into four named aggregation steps, split `reachableBeyondDirectEdge` out of `markRedundantEdges`, extracted `compareZoneEdges`/`crossedZonePair`, extracted `edgeKindCode`/`edgeFlags` from a nested ternary scoring CRAP 42, and deleted `fileGroup` plus the `group` node field once the cluster layout went. Two additive exports on scripts/layering/model.ts: `zoneRank` and `targetDagZone` (previously module-private). The gate's behaviour is unchanged. `pnpm check` green, 4488 unit tests, 5 model tests. Co-Authored-By: Claude Opus 5 <[email protected]> Claude-Session: https://claude.ai/code/session_01Bfu8HofkhybiAm5LECfqur * ci(layering): assert the depgraph report reproduces the gate's baseline The report reads the same model as the gate, so its inversion count must equal TYPE_INVERSION_BASELINE. That agreement was previously a nice property nobody checked; the Layering Guard job now runs scripts/depgraph/model.test.ts, so the two cannot be green independently. Verified by bumping a baseline entry by one and confirming the job fails with a message naming the fix. The count feeding the check is computed by `typeInversionsByPair`, which applies the gate's rule — once per FILE pair, over the raw resolved edges — rather than reading the collapsed edge list. That matters: `collapseEdges` keeps one edge per pair with the strongest kind winning, and `dynamic` outranks `type`, so a module imported both lazily and for its types would collapse to `dynamic` and drop out of the count. No such pair exists today (measured: 0 of 42 inverting pairs), but a number wired into a CI equality check must not be able to drift for a reason unrelated to layering. Stated honestly in the README and the test: this is a cross-check of the report's extraction and the baseline against the real tree, not two independent algorithms. The gate remains the authority — if they disagree, the baseline or the tree is wrong, never the test. TYPE_INVERSION_BASELINE is now exported for this purpose. Not done here, deliberately: the ~1338 transitively redundant value edges are a candidate for a loose growth-only ratchet later. They are a candidate list, not a work list, and a hard count would be noise. `pnpm check` green, 4488 unit tests, 6 depgraph model tests. Co-Authored-By: Claude Opus 5 <[email protected]> Claude-Session: https://claude.ai/code/session_01Bfu8HofkhybiAm5LECfqur * fix(depgraph): make the source reviewable, and stop overclaiming removability Four review findings, all of them real. P1 - the implementation was binary. scripts/depgraph/model.ts contained two raw NUL bytes used as map-key delimiters, so Git classified a ~346-line file as binary and hid its entire diff behind `- -`. Replaced with a unicode escape: identical at runtime, textual on disk. I had seen the symptom repeatedly - every grep on that file printed "binary file matches" - and worked around it with python instead of asking why, which is how it survived to review. Guarded repo-wide rather than for this one file: a new test asserts no tracked .ts under src/ or scripts/ contains a raw NUL, verified by reintroducing one and watching it fail. Nothing else would catch a recurrence, and the failure mode is silent - the code works, the review does not. P1 - "transitively redundant" claimed removability it cannot support. Module reachability does not carry bindings: if `a` imports `{ c }` while `b` only re-exports it as `{ c as b }`, the path a -> b -> c exists and deleting a -> c still breaks `a`. The fixture in model.test.ts is exactly that shape and its comment said "removable". Reachability also says nothing about when a module's side effects run. Renamed throughout to what it measures - `transitivelyReachable`, `markTransitivelyReachableEdges`, and a summary line reading "value edges whose target is also reachable at distance >= 2 (reachability only - not a removability claim)". The caveats and the counterexample are now stated in the marker function, the fixture comment and the README, and symbol-level analysis is named as what deciding any individual edge would actually require. P2 - build.ts had no coverage. Every test exercised model.ts, so the CLI could break its output path, wire shape or summary silently. Added three subprocess tests: default path plus summary-agrees-with-payload, `--out` honoured and valid JSON written, and a trailing `--out` falling back rather than crashing (pinned so it is a decision, not an accident). `pnpm depgraph:test` now runs inside `check:tooling`, so `pnpm check` covers it. P2 - README was wrong three ways: it queried `.tmp/depgraph/index.json` after the output moved to `graph.json` (the documented command failed as written), it derived inversions from collapsed `zoneEdges`, which can undercount, and it claimed both that the report runs in CI and that nothing here runs in CI. The query now reads `typeInversions` and was run verbatim; the CI sentence names exactly which single test runs and states that nothing else gates a merge. pnpm check green, 4488 unit tests, 10 depgraph tests. Co-Authored-By: Claude Opus 5 <[email protected]> Claude-Session: https://claude.ai/code/session_01Bfu8HofkhybiAm5LECfqur --------- Co-authored-by: Claude <[email protected]>
1 parent 5ef52ad commit f19864e

8 files changed

Lines changed: 947 additions & 3 deletions

File tree

‎.github/workflows/ci.yml‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -113,6 +113,13 @@ jobs:
113113
node --experimental-strip-types --test scripts/layering/model.test.ts
114114
node --experimental-strip-types scripts/layering/check.ts
115115
116+
- name: Check the depgraph report agrees with the gate
117+
# scripts/depgraph reads the same model as the gate, so its inversion count must
118+
# reproduce TYPE_INVERSION_BASELINE. Free two-sources check: if the tree changes
119+
# and only one side is updated, this fails and names the difference. Runs here
120+
# rather than in its own job so the two can never be green independently.
121+
run: node --experimental-strip-types --test scripts/depgraph/model.test.ts
122+
116123
affected-selector:
117124
name: Affected-check Selector
118125
runs-on: ubuntu-latest

‎package.json‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -118,14 +118,16 @@
118118
"check:affected": "node --experimental-strip-types scripts/check-affected/run.ts",
119119
"check:affected:test": "node --experimental-strip-types --test scripts/check-affected/model.test.ts scripts/check-affected/run.test.ts",
120120
"check:layering": "node --experimental-strip-types --test scripts/layering/model.test.ts && node --experimental-strip-types scripts/layering/check.ts",
121+
"depgraph": "node --experimental-strip-types scripts/depgraph/build.ts",
122+
"depgraph:test": "node --experimental-strip-types --test scripts/depgraph/model.test.ts",
121123
"check:production-exports": "fallow dead-code --config fallow-production-exports.json --production --unused-exports --fail-on-issues",
122124
"check:bundle-owner-files": "node --experimental-strip-types scripts/check-bundle-owner-files.ts",
123125
"check:freerange": "fr",
124126
"check:quick": "pnpm lint && pnpm typecheck",
125127
"sync:mcp-metadata": "node scripts/sync-mcp-metadata.mjs",
126128
"check:mcp-metadata": "node scripts/sync-mcp-metadata.mjs --check",
127129
"version": "node scripts/sync-mcp-metadata.mjs && git add server.json",
128-
"check:tooling": "pnpm lint && pnpm typecheck && pnpm check:layering && pnpm check:production-exports && pnpm check:mcp-metadata && pnpm build && pnpm check:bundle-owner-files",
130+
"check:tooling": "pnpm lint && pnpm typecheck && pnpm check:layering && pnpm depgraph:test && pnpm check:production-exports && pnpm check:mcp-metadata && pnpm build && pnpm check:bundle-owner-files",
129131
"check:unit": "pnpm test:unit && pnpm test:smoke",
130132
"check": "pnpm check:tooling && pnpm check:fallow && pnpm check:unit",
131133
"prepack": "pnpm check:mcp-metadata && pnpm build:all && pnpm package:apple-runner:npm && pnpm package:android-snapshot-helper:npm && pnpm package:android-ime-helper:npm",

‎scripts/depgraph/README.md‎

Lines changed: 120 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,120 @@
1+
# Dependency graph report
2+
3+
```sh
4+
pnpm depgraph # -> .tmp/depgraph/graph.json + a text summary
5+
pnpm depgraph --out /tmp/graph.json
6+
pnpm depgraph:test
7+
```
8+
9+
Emits the dependency graph of every production file under `src/` (tests excluded) as JSON,
10+
plus a short summary of what the layering gate does not enforce. There is no renderer: the
11+
productive artifact is the JSON, queried directly.
12+
13+
## When to reach for this
14+
15+
It pays for itself on three questions, and misleads on a fourth.
16+
17+
**"What am I about to break?"** `nodes[].in` is the dependent count — blast radius. Size the
18+
nodes by dependents and the files you should touch carefully are the big ones. Faster than
19+
grepping, and it counts type-only and dynamic edges that a grep for `from '...'` misses.
20+
21+
**"Where is the debt actually concentrated?"** Zone-level counts (`zoneEdges`) answer "which
22+
boundary carries the most traffic" in one query. The pass that produced ADR-adjacent findings
23+
started here.
24+
25+
**"What is wrong that the gate does not enforce?"** This is the part CI cannot give you. The
26+
gate rejects value-import cycles (R4) and spine back-edges (R5); the graph additionally reports:
27+
28+
- **value edges whose target is also reachable at distance >= 2** — static module reachability,
29+
and *only* that. It is **not** a removability claim, and the obvious reading is wrong:
30+
reachability does not carry bindings (if `a` imports `{ c }` while `b` only re-exports it as
31+
`{ c as b }`, the path exists and deleting `a -> c` still breaks `a`), it does not preserve when
32+
a module's side effects run, and a direct import is often deliberately clearer than reaching
33+
through a barrel. Deciding whether any given edge can go needs symbol-level analysis this does
34+
not attempt. ~1300 of them: a place to look, never a work list.
35+
- **type-only and dynamic cycles** — 8 of them, all outside R4 by design (a type-only import is
36+
free at runtime, a dynamic one is a deliberate cold-start seam). Worth reading when a module
37+
feels hard to reason about.
38+
39+
**Where it misleads: a cluster's size is not its difficulty.** This is worth stating plainly
40+
because it already cost a day. The `commands -> client` cluster looked like the obvious win — 28
41+
type-only inversions, all pointing at one file. Moving that file down took the gate from **42 to
42+
48**, because the vocabulary it holds *depends on* `commands/`, `metro/`, `core/` and `remote/`;
43+
declaring it in `contracts/` made the foundation depend on the layers above it. The picture shows
44+
you an edge's weight, not whether it can be reversed.
45+
46+
So: use the render to find a candidate, then answer "can this move?" numerically before planning
47+
anything. The question is always *what does the target itself import, and what rank is that?*
48+
49+
```sh
50+
pnpm depgraph
51+
# Zone pairs that invert the ranked spine. Read `typeInversions` rather than deriving it from
52+
# `zoneEdges`: those counts come from the COLLAPSED edge list, where one edge per file pair
53+
# survives and `dynamic` outranks `type`, so a module imported both lazily and for its types
54+
# would drop out. `typeInversions` is counted by the gate's own rule and is what CI compares
55+
# against TYPE_INVERSION_BASELINE.
56+
node -e "const j=require('./.tmp/depgraph/graph.json');
57+
Object.entries(j.typeInversions)
58+
.sort((a, b) => b[1] - a[1])
59+
.forEach(([pair, n]) => console.log(String(n).padStart(4), pair));"
60+
```
61+
62+
63+
Note `zoneEdges[].backEdge` flags **R5 value** back-edges only, and there are none — filtering on
64+
it returns an empty list, which is the gate passing, not a broken query.
65+
66+
67+
## What is authoritative
68+
69+
`pnpm check:layering` is. The viewer reads the same model, so the numbers should agree — and that
70+
agreement is now enforced rather than hoped for: the **Layering Guard job runs
71+
`scripts/depgraph/model.test.ts`**, whose last test asserts this report's inversion count reproduces
72+
`TYPE_INVERSION_BASELINE`. If the tree changes and only one side is updated, CI fails and names the
73+
difference. The two cannot be green independently.
74+
75+
What that check proves precisely: the report's graph build, over the real tree, agrees with the
76+
gate's baseline. It is a cross-check of the extraction and the baseline against reality, not two
77+
independent algorithms — `typeInversionsByPair` deliberately applies the gate's counting rule (once
78+
per file pair, over raw edges) so the numbers cannot diverge for a reason unrelated to layering. In
79+
particular it does NOT count from the collapsed edge list, where `dynamic` outranks `type` and a
80+
module imported both lazily and for its types would drop out.
81+
82+
If they ever disagree, the gate is right and the baseline or the tree is wrong.
83+
84+
### Notes
85+
86+
87+
`pnpm check:layering` is. This reads the same model, so the numbers should agree — its R6
88+
count matching `TYPE_INVERSION_BASELINE` is a useful self-check — but if they ever diverge, the
89+
gate is right and the graph is stale.
90+
91+
One thing here DOES run in CI, and only one: the Layering Guard job runs
92+
`scripts/depgraph/model.test.ts`, whose parity test asserts this report's inversion count equals
93+
`TYPE_INVERSION_BASELINE`. Nothing else here gates a merge — the report itself is an instrument, not
94+
a rule, and no finding it produces is enforced.
95+
96+
## Why it reuses the layering gate
97+
98+
The graph is extracted with `scripts/layering/model.ts`, the same module
99+
`scripts/layering/check.ts` uses in CI. File set, zone partition, edge kinds
100+
(value / type-only / dynamic), and cycle definition are therefore identical to the rules
101+
the gate enforces — a separate extractor with its own resolution behaviour would draw a
102+
graph nobody is enforcing. Cross-checked once against `dependency-cruiser` 3.1.1 (at the commit it was written): same
103+
modules and edges, plus 88 dynamic/type-only edges dependency-cruiser fails to resolve.
104+
105+
## What the JSON carries
106+
107+
- `zones[]` — id, spine `rank` (`null` when intentionally unranked), `classification`, file
108+
count, LOC.
109+
- `zoneEdges[]` — per zone pair: total `count`, `valueCount`, and `backEdge` (R5 value
110+
back-edges only — see the note above).
111+
- `nodes[]` — per file: zone index, LOC, `in`/`out` degree, `lvl` (longest path to a sink over
112+
value edges; R4 guarantees that subgraph is a DAG), and `cyc` (index into `cycles`, or `-1`).
113+
- `edges[]` — index-addressed `[from, to, kind, flags]`. Kind: `0` value, `1` type-only, `2`
114+
dynamic. Flags bitfield: `1` spine back-edge, `2` target also reachable at distance >= 2, `4` type-only
115+
inversion.
116+
- `cycles[]` — each with `kind` (`value` / `type` / `dynamic`) and its node path.
117+
118+
Bit `2` means the target is reachable from the source at distance >= 2 over value edges. That is
119+
module reachability, not removability — see the caveats above. Treat it as a question ("why is
120+
this imported directly as well?"), never as an instruction.

‎scripts/depgraph/build.ts‎

Lines changed: 151 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,151 @@
1+
// Dependency-graph report — the numbers the layering gate does not enforce.
2+
//
3+
// node --experimental-strip-types scripts/depgraph/build.ts [--out <path>]
4+
//
5+
// Emits a JSON graph plus a short text summary. It reuses scripts/layering/model.ts, the same
6+
// module check.ts uses in CI, so the file set, zone partition, edge kinds and cycle definition
7+
// are the ones actually enforced — a second extractor would describe a graph nobody gates.
8+
//
9+
// What it adds over `pnpm check:layering`: value edges whose target is also reachable at distance
10+
// >= 2 (module reachability, NOT a removability claim), cycles that are
11+
// deliberately outside R4 (type-only and dynamic), per-zone size, and per-file fan-in/fan-out.
12+
// See README.md for which question each field answers.
13+
14+
import { execFileSync } from 'node:child_process';
15+
import fs from 'node:fs';
16+
import path from 'node:path';
17+
import { pathToFileURL } from 'node:url';
18+
import { listSourceFiles } from '../layering/check.ts';
19+
import { resolveImportEdges, zoneRank } from '../layering/model.ts';
20+
import { buildGraph, computeLevels, type GraphData } from './model.ts';
21+
22+
const repoRoot = execFileSync('git', ['rev-parse', '--show-toplevel'], {
23+
encoding: 'utf8',
24+
}).trim();
25+
26+
/** Compact wire form. Nodes and edges are index-addressed to keep the payload small. */
27+
type Payload = {
28+
generated: { commit: string; files: number; edges: number };
29+
zones: { id: string; rank: number | null; classification: string; files: number; loc: number }[];
30+
zoneEdges: GraphData['zoneEdges'];
31+
nodes: {
32+
id: string;
33+
z: number;
34+
loc: number;
35+
in: number;
36+
out: number;
37+
lvl: number;
38+
cyc: number;
39+
}[];
40+
/**
41+
* `[fromIndex, toIndex, kind, flags]`; kind 0=value 1=type 2=dynamic,
42+
* flags bit0=R5 back-edge, bit1=target also reachable at distance >= 2, bit2=R6 type inversion.
43+
*/
44+
edges: [number, number, number, number][];
45+
cycles: { kind: string; path: number[] }[];
46+
/** Type-only spine inversions per zone pair, by the gate's counting rule. */
47+
typeInversions: Record<string, number>;
48+
};
49+
50+
function headCommit(): string {
51+
try {
52+
return execFileSync('git', ['rev-parse', '--short', 'HEAD'], {
53+
cwd: repoRoot,
54+
encoding: 'utf8',
55+
}).trim();
56+
} catch {
57+
return 'unknown';
58+
}
59+
}
60+
61+
const EDGE_KIND_CODES = { value: 0, type: 1, dynamic: 2 } as const;
62+
63+
/** Wire code for an edge kind, so the payload carries a number rather than a string per edge. */
64+
function edgeKindCode(kind: GraphData['edges'][number]['kind']): number {
65+
return EDGE_KIND_CODES[kind];
66+
}
67+
68+
/**
69+
* Bitfield: 1 = spine back-edge (R5), 2 = target also reachable at distance >= 2, 4 = type-only
70+
* inversion (R6). Bit 2 is reachability, NOT removability — see markTransitivelyReachableEdges.
71+
*/
72+
function edgeFlags(edge: GraphData['edges'][number]): number {
73+
return (
74+
(edge.backEdge ? 1 : 0) |
75+
(edge.transitivelyReachable ? 2 : 0) |
76+
(edge.typeInversion ? 4 : 0)
77+
);
78+
}
79+
80+
function buildPayload(): Payload {
81+
const files = listSourceFiles();
82+
const sources = new Map(
83+
files.map((file) => [file, fs.readFileSync(path.join(repoRoot, file), 'utf8')]),
84+
);
85+
const resolved = resolveImportEdges(sources);
86+
const graph = buildGraph(sources, resolved);
87+
const levels = computeLevels(graph.nodes, graph.edges);
88+
89+
const zoneIndex = new Map(graph.zones.map((zone, index) => [zone.id, index]));
90+
const nodeIndex = new Map(graph.nodes.map((node, index) => [node.id, index]));
91+
92+
return {
93+
generated: { commit: headCommit(), files: graph.nodes.length, edges: graph.edges.length },
94+
zones: graph.zones.map((zone) => ({ ...zone, rank: zoneRank(zone.id) })),
95+
zoneEdges: graph.zoneEdges,
96+
nodes: graph.nodes.map((node) => ({
97+
id: node.id.replace(/^src\//, ''),
98+
z: zoneIndex.get(node.zone)!,
99+
loc: node.loc,
100+
in: node.fanIn,
101+
out: node.fanOut,
102+
lvl: levels.get(node.id) ?? 0,
103+
cyc: node.cycle,
104+
})),
105+
edges: graph.edges.map((edge) => [
106+
nodeIndex.get(edge.from)!,
107+
nodeIndex.get(edge.to)!,
108+
edgeKindCode(edge.kind),
109+
edgeFlags(edge),
110+
]),
111+
cycles: graph.cycles.map((cycle) => ({
112+
kind: cycle.kind,
113+
path: cycle.path.map((file) => nodeIndex.get(file)!),
114+
})),
115+
typeInversions: graph.typeInversions,
116+
};
117+
}
118+
119+
function main(argv: readonly string[]): number {
120+
const outFlag = argv.indexOf('--out');
121+
const jsonPath =
122+
outFlag >= 0 && argv[outFlag + 1]
123+
? path.resolve(argv[outFlag + 1]!)
124+
: path.join(repoRoot, '.tmp/depgraph/graph.json');
125+
126+
const payload = buildPayload();
127+
fs.mkdirSync(path.dirname(jsonPath), { recursive: true });
128+
fs.writeFileSync(jsonPath, `${JSON.stringify(payload, null, 2)}\n`);
129+
130+
const valueCycles = payload.cycles.filter((cycle) => cycle.kind === 'value').length;
131+
const otherCycles = payload.cycles.length - valueCycles;
132+
const backEdges = payload.edges.filter(([, , , flags]) => flags & 1).length;
133+
const transitivelyReachable = payload.edges.filter(([, , , flags]) => flags & 2).length;
134+
const typeInversions = Object.values(payload.typeInversions).reduce((sum, n) => sum + n, 0);
135+
process.stdout.write(
136+
`Dependency graph: ${payload.generated.files} files, ${payload.generated.edges} edges, ` +
137+
`${payload.zones.length} zones\n` +
138+
` value-import cycles (R4): ${valueCycles}\n` +
139+
` type-only/dynamic cycles (not gate-rejected): ${otherCycles}\n` +
140+
` spine back-edges (R5): ${backEdges}\n` +
141+
` type-only spine inversions (R6): ${typeInversions}\n` +
142+
` value edges whose target is also reachable at distance >= 2: ${transitivelyReachable}\n` +
143+
` (reachability only — not a removability claim, see scripts/depgraph/README.md)\n` +
144+
` wrote ${path.relative(repoRoot, jsonPath)}\n`,
145+
);
146+
return 0;
147+
}
148+
149+
if (import.meta.url === pathToFileURL(process.argv[1] ?? '').href) {
150+
process.exit(main(process.argv.slice(2)));
151+
}

0 commit comments

Comments
 (0)