Skip to content

Commit d24fb18

Browse files
authored
feat(docs): add interactive dependency graph (#4069)
* feat(docs): add interactive dependency graph * fix(docs): preserve dependency graph direction * test(depgraph): run viewer model regression * test(docs): run graph regression in website build * refactor(depgraph): separate layout and rendering tasks * chore(gates): declare dependency graph entry points * fix(depgraph): address viewer review findings * fix(depgraph): highlight visible cycle paths * refactor(depgraph): align viewer with graph data * fix(depgraph): tighten viewer rendering and simulation * fix(depgraph): show all selected dependencies * refactor(depgraph): consolidate viewer data * fix(website): shorten dependency graph route * style(depgraph): match website design * fix(depgraph): address review feedback * fix(depgraph): clarify cycle and edge display * refactor(depgraph): simplify build assets
1 parent 18d1058 commit d24fb18

30 files changed

Lines changed: 2439 additions & 43 deletions

‎.fallowrc.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,7 @@
22
"$schema": "https://raw.githubusercontent.com/fallow-rs/fallow/main/schema.json",
33
"entry": [
44
"tsdown.config.ts",
5+
"tools/depgraph-view/app.js",
56
"scripts/check-provider-plugin.mjs",
67
"scripts/check-affected/command.ts",
78
"packages/provider-testmu/test/package-smoke.mjs",

‎oxlint.config.ts‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -198,6 +198,22 @@ export default defineConfig({
198198
output: 'writable',
199199
},
200200
},
201+
{
202+
// The dependency-graph viewer is a browser page, not a Node entry point.
203+
files: ['tools/depgraph-view/*.js'],
204+
env: { browser: true },
205+
globals: {
206+
window: 'readonly',
207+
document: 'readonly',
208+
fetch: 'readonly',
209+
requestAnimationFrame: 'readonly',
210+
performance: 'readonly',
211+
PointerEvent: 'readonly',
212+
KeyboardEvent: 'readonly',
213+
Event: 'readonly',
214+
Blob: 'readonly',
215+
},
216+
},
201217
{
202218
// Product tests get scratch from the package tmp-dir helpers, which honor the run's
203219
// redirected TMPDIR; reading node:os reuses a fixed path across the suite. A file with a

‎package.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -162,7 +162,7 @@
162162
"check:layering": "node --experimental-strip-types scripts/node-test-tmpdir.ts --experimental-strip-types --test scripts/layering/*.test.ts && node --experimental-strip-types scripts/layering/check.ts",
163163
"check:di-seams": "node --experimental-strip-types scripts/node-test-tmpdir.ts --experimental-strip-types --test scripts/di-seams/*.test.ts && node --experimental-strip-types scripts/di-seams/check.ts",
164164
"depgraph": "node --experimental-strip-types scripts/depgraph/build.ts",
165-
"depgraph:test": "node --experimental-strip-types scripts/node-test-tmpdir.ts --experimental-strip-types --test scripts/depgraph/model.test.ts scripts/depgraph/import-graph.test.ts scripts/depgraph/affected.test.ts scripts/depgraph/structure-summary.test.ts",
165+
"depgraph:test": "node --experimental-strip-types scripts/node-test-tmpdir.ts --experimental-strip-types --test scripts/depgraph/model.test.ts scripts/depgraph/entries.test.ts scripts/depgraph/import-graph.test.ts scripts/depgraph/affected.test.ts scripts/depgraph/structure-summary.test.ts tools/depgraph-view/*.test.mjs",
166166
"check:production-exports": "fallow dead-code --config fallow-production-exports.json --production --unused-exports --fail-on-issues",
167167
"check:bundle-owner-files": "node --experimental-strip-types scripts/check-bundle-owner-files.ts",
168168
"check:package": "node --experimental-strip-types scripts/check-package.ts",

‎scripts/build-entries.ts‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
export const buildEntries = {
2+
index: 'src/sdk/index.ts',
3+
io: 'src/sdk/io.ts',
4+
artifacts: 'src/sdk/artifacts.ts',
5+
batch: 'src/sdk/batch.ts',
6+
metro: 'src/sdk/metro.ts',
7+
'remote-config': 'src/sdk/remote-config.ts',
8+
'install-source': 'src/sdk/install-source.ts',
9+
'android-adb': 'src/sdk/android-adb.ts',
10+
limrun: 'src/sdk/limrun.ts',
11+
plugins: 'src/sdk/plugins.ts',
12+
'plugins/webdriver': 'src/sdk/plugin-webdriver.ts',
13+
contracts: 'src/sdk/contracts.ts',
14+
selectors: 'src/sdk/selectors.ts',
15+
finders: 'src/sdk/finders.ts',
16+
'ai-sdk': 'src/ai-sdk/index.ts',
17+
'internal/bin': 'src/bin.ts',
18+
'internal/companion-tunnel': 'packages/react-native/src/companion/companion-tunnel.ts',
19+
'internal/daemon': 'src/daemon.ts',
20+
'internal/run-script-http-child': 'packages/maestro/src/daemon-port/run-script-http-child.ts',
21+
'internal/png-worker': 'packages/capture-kit/src/png-worker.ts',
22+
'internal/update-check-entry': 'src/cli/update-check-entry.ts',
23+
} as const;

‎scripts/depgraph/README.md‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -7,8 +7,9 @@ pnpm depgraph:test
77
```
88

99
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.
10+
plus a short summary of what the layering gate does not enforce. The interactive viewer is at
11+
`/depgraph/` on the website. Run `pnpm --dir website build` and `pnpm --dir website preview`
12+
to view the generated graph locally.
1213

1314
## Blast radius of one file
1415

‎scripts/depgraph/build.ts‎

Lines changed: 36 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -18,10 +18,11 @@ import { pathToFileURL } from 'node:url';
1818
import { zoneRank } from '../layering/model.ts';
1919
import { runAffected } from './affected-run.ts';
2020
import { loadGraph } from './load.ts';
21+
import { graphEntries, type EntryManifest } from './entries.ts';
2122
import { computeLevels, markTransitivelyReachableEdges, type GraphData } from './model.ts';
2223
import {
2324
computeCohesionSummary,
24-
computeDominatorSummary,
25+
createDominatorAnalyzer,
2526
computeZoneSccSummary,
2627
type CohesionSummary,
2728
type DominatorSummary,
@@ -67,17 +68,22 @@ type Payload = {
6768
* Report-only structural summaries (scripts/depgraph/structure-summary.ts): no layering or
6869
* check-affected gate reads these fields today.
6970
*/
71+
entries: EntryManifest;
72+
entrySummaries: Record<string, DominatorSummary>;
7073
dominatorSummary: DominatorSummary;
7174
zoneSccSummary: ZoneSccSummary;
7275
cohesionSummary: CohesionSummary;
7376
};
7477

7578
function headCommit(): string {
79+
if (process.env.VERCEL_GIT_COMMIT_SHA) return process.env.VERCEL_GIT_COMMIT_SHA.slice(0, 10);
7680
try {
77-
return execFileSync('git', ['rev-parse', '--short', 'HEAD'], {
81+
return execFileSync('git', ['rev-parse', 'HEAD'], {
7882
cwd: repoRoot,
7983
encoding: 'utf8',
80-
}).trim();
84+
})
85+
.trim()
86+
.slice(0, 10);
8187
} catch {
8288
return 'unknown';
8389
}
@@ -107,11 +113,35 @@ function hasValueCycle(graph: Pick<GraphData, 'cycles'>): boolean {
107113

108114
function buildPayload(dominatorEntry: string): Payload {
109115
const graph = loadGraph(repoRoot);
116+
const dominatorsOf = createDominatorAnalyzer(graph);
117+
const dominatorSummary = dominatorsOf(dominatorEntry);
110118
if (!hasValueCycle(graph)) markTransitivelyReachableEdges(graph.edges);
111119
const levels = computeLevels(graph.nodes, graph.edges);
112120

113121
const zoneIndex = new Map(graph.zones.map((zone, index) => [zone.id, index]));
114122
const nodeIndex = new Map(graph.nodes.map((node, index) => [node.id, index]));
123+
const entries = graphEntries(repoRoot, new Set(nodeIndex.keys()));
124+
const hot = graph.nodes
125+
.filter((n) => n.fanIn > 0)
126+
.sort((a, b) => b.fanIn + b.fanOut - (a.fanIn + a.fanOut))
127+
.slice(0, 300);
128+
const selected = new Set([
129+
...Object.values(entries)
130+
.flat()
131+
.map((e) => e.id),
132+
...hot.map((n) => n.id.replace(/^src\//, '')),
133+
dominatorEntry.replace(/^src\//, ''),
134+
]);
135+
const originalIds = new Map(graph.nodes.map((n) => [n.id.replace(/^src\//, ''), n.id]));
136+
const entrySummaries = Object.fromEntries(
137+
[...selected].map((id) => {
138+
const original = originalIds.get(id);
139+
if (!original)
140+
throw new Error(`Graph entry ${id} does not identify a production source file.`);
141+
const summary = original === dominatorEntry ? dominatorSummary : dominatorsOf(original);
142+
return [id, { ...summary, bottlenecks: summary.bottlenecks.slice(0, 8) }];
143+
}),
144+
);
115145

116146
return {
117147
generated: { commit: headCommit(), files: graph.nodes.length, edges: graph.edges.length },
@@ -139,7 +169,9 @@ function buildPayload(dominatorEntry: string): Payload {
139169
path: cycle.path.map((file) => nodeIndex.get(file)!),
140170
})),
141171
typeInversions: graph.typeInversions,
142-
dominatorSummary: computeDominatorSummary(dominatorEntry, graph),
172+
entries,
173+
entrySummaries,
174+
dominatorSummary,
143175
zoneSccSummary: computeZoneSccSummary(graph),
144176
cohesionSummary: computeCohesionSummary(graph),
145177
};

‎scripts/depgraph/entries.test.ts‎

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
import assert from 'node:assert/strict';
2+
import { execFileSync } from 'node:child_process';
3+
import fs from 'node:fs';
4+
import os from 'node:os';
5+
import path from 'node:path';
6+
import { test } from 'node:test';
7+
import { graphEntries } from './entries.ts';
8+
9+
test('maps declared root and workspace exports to graph source files', () => {
10+
const repo = fs.mkdtempSync(path.join(os.tmpdir(), 'depgraph-entries-'));
11+
fs.mkdirSync(path.join(repo, 'packages/example'), { recursive: true });
12+
fs.writeFileSync(
13+
path.join(repo, 'package.json'),
14+
JSON.stringify({
15+
exports: {
16+
'.': { default: './dist/src/index.js' },
17+
'./io': { require: './dist/src/io.js' },
18+
},
19+
}),
20+
);
21+
fs.writeFileSync(
22+
path.join(repo, 'packages/example/package.json'),
23+
JSON.stringify({
24+
name: '@agent-device/example',
25+
exports: { '.': { require: './src/index.js' }, './alias': './src/index.ts' },
26+
}),
27+
);
28+
execFileSync('git', ['init', '-q'], { cwd: repo });
29+
execFileSync('git', ['add', 'package.json', 'packages/example/package.json'], { cwd: repo });
30+
const entries = graphEntries(
31+
repo,
32+
new Set(['src/sdk/index.ts', 'src/sdk/io.ts', 'packages/example/src/index.ts']),
33+
);
34+
assert.deepEqual(entries['src (agent-device)'], [
35+
{ id: 'sdk/index.ts', subpath: '.' },
36+
{ id: 'sdk/io.ts', subpath: './io' },
37+
]);
38+
assert.deepEqual(entries['packages/example'], [
39+
{ id: 'packages/example/src/index.ts', subpath: '.' },
40+
{ id: 'packages/example/src/index.ts', subpath: './alias' },
41+
]);
42+
fs.writeFileSync(
43+
path.join(repo, 'package.json'),
44+
JSON.stringify({ exports: { './missing': { import: './dist/src/missing.js' } } }),
45+
);
46+
assert.throws(
47+
() => graphEntries(repo, new Set()),
48+
/Root export \.\/missing points to unknown build entry/,
49+
);
50+
});

‎scripts/depgraph/entries.ts‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
import fs from 'node:fs';
2+
import path from 'node:path';
3+
import { buildEntries } from '../build-entries.ts';
4+
import { readWorkspacePackages, runtimeExportTarget } from '../layering/package-boundaries.ts';
5+
6+
export type EntryManifest = Record<string, { id: string; subpath: string }[]>;
7+
8+
export function graphEntries(repoRoot: string, ids: ReadonlySet<string>): EntryManifest {
9+
const entries: EntryManifest = {};
10+
const add = (pkg: string, id: string, subpath: string) => {
11+
const source = ids.has(id) ? id : id.replace(/\.js$/, '.ts');
12+
if (ids.has(source)) (entries[pkg] ??= []).push({ id: source.replace(/^src\//, ''), subpath });
13+
};
14+
const root = JSON.parse(fs.readFileSync(path.join(repoRoot, 'package.json'), 'utf8')) as {
15+
exports:
16+
| string
17+
| Record<string, { default?: string; import?: string; require?: string } | string>;
18+
};
19+
const rootExports = typeof root.exports === 'string' ? { '.': root.exports } : root.exports;
20+
for (const [subpath, value] of Object.entries(rootExports)) {
21+
const target = runtimeExportTarget(value);
22+
if (!target) continue;
23+
const name = target.replace(/^\.\/dist\/src\//, '').replace(/\.js$/, '');
24+
const source = (buildEntries as Record<string, string>)[name];
25+
if (!source) throw new Error(`Root export ${subpath} points to unknown build entry ${target}.`);
26+
add('src (agent-device)', source, subpath);
27+
}
28+
for (const pkg of readWorkspacePackages(repoRoot)) {
29+
for (const [specifier, target] of pkg.exportTargets) {
30+
add(pkg.dir, target, specifier === pkg.name ? '.' : `.${specifier.slice(pkg.name.length)}`);
31+
}
32+
}
33+
return entries;
34+
}

‎scripts/depgraph/model.test.ts‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -531,6 +531,8 @@ test('build.ts writes the default path and a summary consistent with the JSON',
531531
edgeAuthorities: string[][];
532532
authorityCounts: Record<string, number>;
533533
typeInversions: Record<string, number>;
534+
entries: Record<string, { id: string; subpath: string }[]>;
535+
entrySummaries: Record<string, { reachableFiles: number; reachableLoc: number }>;
534536
dominatorSummary: { entry: string; reachableFiles: number; totalFiles: number };
535537
zoneSccSummary: { zones: number; components: { zones: string[]; size: number }[] };
536538
cohesionSummary: {
@@ -549,6 +551,8 @@ test('build.ts writes the default path and a summary consistent with the JSON',
549551
'edges',
550552
'cycles',
551553
'typeInversions',
554+
'entries',
555+
'entrySummaries',
552556
'dominatorSummary',
553557
'zoneSccSummary',
554558
'cohesionSummary',
@@ -568,6 +572,15 @@ test('build.ts writes the default path and a summary consistent with the JSON',
568572

569573
// Report-only fields (#3283): no gate reads these, so this pins only the wire shape.
570574
assert.equal(payload.dominatorSummary.entry, 'src/daemon.ts');
575+
assert.ok(
576+
payload.entries['src (agent-device)'].some(
577+
(entry) => entry.subpath === '.' && entry.id === 'sdk/index.ts',
578+
),
579+
);
580+
assert.equal(
581+
payload.entrySummaries['daemon.ts'].reachableFiles,
582+
payload.dominatorSummary.reachableFiles,
583+
);
571584
assert.ok(payload.dominatorSummary.reachableFiles > 0);
572585
assert.ok(payload.dominatorSummary.reachableFiles <= payload.dominatorSummary.totalFiles);
573586
assert.ok(payload.zoneSccSummary.zones > 0);

‎scripts/depgraph/structure-summary.test.ts‎

Lines changed: 18 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -4,15 +4,15 @@ import { resolveImportEdges } from '../layering/model.ts';
44
import { buildGraph } from './model.ts';
55
import {
66
computeCohesionSummary,
7-
computeDominatorSummary,
7+
createDominatorAnalyzer,
88
computeZoneSccSummary,
99
} from './structure-summary.ts';
1010

1111
function sources(entries: Record<string, string>): Map<string, string> {
1212
return new Map(Object.entries(entries));
1313
}
1414

15-
test('computeDominatorSummary excludes the dynamic-import seam and ranks bottlenecks by dominated subtree size', () => {
15+
test('the dominator analyzer excludes dynamic imports and ranks dominated subtrees', () => {
1616
const files = sources({
1717
'src/core/entry.ts': [
1818
"import { a } from './a.ts';",
@@ -30,7 +30,7 @@ test('computeDominatorSummary excludes the dynamic-import seam and ranks bottlen
3030
});
3131
const graph = buildGraph(files, resolveImportEdges(files));
3232

33-
const summary = computeDominatorSummary('src/core/entry.ts', graph);
33+
const summary = createDominatorAnalyzer(graph)('src/core/entry.ts');
3434

3535
// `lazy.ts` is reached only through a dynamic import, so it never joins the eager closure —
3636
// reachableFiles counts entry + a + b + shared + only-a, not the dynamically-loaded sixth file.
@@ -51,16 +51,29 @@ test('computeDominatorSummary excludes the dynamic-import seam and ranks bottlen
5151
);
5252
});
5353

54-
test('computeDominatorSummary rejects an entry outside the layering graph', () => {
54+
test('the dominator analyzer rejects an entry outside the layering graph', () => {
5555
const files = sources({ 'src/core/entry.ts': 'export const entry = 1;' });
5656
const graph = buildGraph(files, resolveImportEdges(files));
5757

5858
assert.throws(
59-
() => computeDominatorSummary('src/core/missing.ts', graph),
59+
() => createDominatorAnalyzer(graph)('src/core/missing.ts'),
6060
/src\/core\/missing\.ts is not a production source file/,
6161
);
6262
});
6363

64+
test('one analyzer computes independent summaries for connected and isolated entries', () => {
65+
const files = sources({
66+
'src/core/a.ts': "import { b } from './b.ts';",
67+
'src/core/b.ts': 'export const b = 1;',
68+
'src/core/isolated.ts': 'export const isolated = 1;',
69+
});
70+
const analyze = createDominatorAnalyzer(buildGraph(files, resolveImportEdges(files)));
71+
assert.equal(analyze('src/core/a.ts').reachableFiles, 2);
72+
assert.equal(analyze('src/core/b.ts').reachableFiles, 1);
73+
assert.equal(analyze('src/core/isolated.ts').reachableFiles, 1);
74+
assert.equal(analyze('src/core/a.ts').bottlenecks[0]?.file, 'src/core/b.ts');
75+
});
76+
6477
test('computeZoneSccSummary finds a zone-level cycle built from value edges across distinct files', () => {
6578
// No single file pair cycles — R4 would reject that — but the zone pairs commands -> core ->
6679
// daemon-server -> commands close a loop because the last edge targets a different commands

0 commit comments

Comments
 (0)