|
| 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