build(typescript): move root project references into tsconfig.typecheck.json

package.json

@@ -171,15 +171,15 @@
     "check:packaged-runner-swift": "node --experimental-strip-types scripts/check-packaged-runner-swift.ts",
     "check:tmpdir-leaks": "node --experimental-strip-types scripts/check-tmpdir-leaks.ts",
     "check:tmpdir-leaks:test": "node --experimental-strip-types scripts/node-test-tmpdir.ts --experimental-strip-types --test --test-concurrency=1 scripts/check-tmpdir-leaks-model.test.ts scripts/vitest-tmpdir-global-setup.test.ts scripts/node-test-tmpdir.test.ts scripts/swift-toolchain-tmpdir.test.ts",
-    "check:freerange": "cd scripts/freerange && fr",
+    "check:freerange": "fr",
     "check:quick": "pnpm lint && pnpm typecheck",
     "sync:mcp-metadata": "node scripts/sync-mcp-metadata.mjs",
     "check:mcp-metadata": "node scripts/sync-mcp-metadata.mjs --check",
     "check:tooling": "pnpm format:check && pnpm lint && pnpm typecheck && pnpm check:layering && pnpm depgraph:test && pnpm check:gate-manifest:test && pnpm check:gate-manifest && pnpm check:production-exports && pnpm check:tmpdir-leaks:test && pnpm check:xctest-selection && pnpm check:packaged-runner-swift && pnpm check:mcp-metadata && pnpm check:doc-prose && pnpm check:doc-links && pnpm build && pnpm check:bundle-owner-files && pnpm check:package",
     "check:unit": "pnpm test:unit && pnpm check:tmpdir-leaks && pnpm test:smoke",
     "check": "pnpm check:tooling && pnpm check:fallow && pnpm check:unit",
     "prepack": "npm_config_dry_run=false pnpm release:prepare",
-    "typecheck": "tsc -b tsconfig.json examples/sdk/tsconfig.json",
+    "typecheck": "tsc -b tsconfig.typecheck.json examples/sdk/tsconfig.json",
     "test-app:install": "pnpm install --dir examples/test-app",
     "test-app:start": "pnpm --dir examples/test-app start",
     "test-app:ios": "pnpm --dir examples/test-app ios",

scripts/check-affected/model.ts

@@ -133,6 +133,7 @@ const ROOT_TOOLING = new Set([
   'pnpm-workspace.yaml',
   'tsconfig.json',
   'tsconfig.lib.json',
+  'tsconfig.typecheck.json',
   'tsdown.config.ts',
   'vitest.config.ts',
   '.fallowrc.json',

scripts/layering/project-references.test.ts

@@ -1,8 +1,9 @@
 // The TypeScript project graph is three hand-written views of one fact: the workspace package
-// set, the root manifest's `workspace:*` declarations, and the `references` lists in the root,
-// examples/sdk, and per-package tsconfigs. `tsc -b` fails loudly on a MISSING reference it
-// needs but silently tolerates EXTRA ones (#3289 review), so a package added to the workspace
-// while a references list goes un-updated keeps building a stale graph that still exits 0.
+// set, the root manifest's `workspace:*` declarations, and the `references` lists in the root
+// build node (tsconfig.typecheck.json), examples/sdk, and per-package tsconfigs. `tsc -b` fails
+// loudly on a MISSING reference it needs but silently tolerates EXTRA ones (#3289 review), so a
+// package added to the workspace while a references list goes un-updated keeps building a stale
+// graph that still exits 0.
 // These tests read the committed declarations against each other so the four views cannot
 // drift: an added, renamed, or removed workspace package must edit every list or fail here.
 
@@ -53,10 +54,36 @@ test('root and examples/sdk reference exactly the workspace package set', () =>
   const expected = workspacePackageDirs();
   assert.ok(expected.length >= 25, 'expected the 25+ workspace packages to be enumerable');
 
-  assert.deepEqual(referencedPackageDirs('tsconfig.json', '.'), expected);
+  assert.deepEqual(referencedPackageDirs('tsconfig.typecheck.json', '.'), expected);
   assert.deepEqual(referencedPackageDirs('examples/sdk/tsconfig.json', 'examples/sdk'), expected);
 });
 
+test('the root build node is tsconfig.json plus references, and tsconfig.json has none', () => {
+  // fallow >=3.20 walks the references of the tsconfig that owns each file on every import, which
+  // made its resolve stage ~14x slower here, and `fr` loads every referenced project as its own
+  // ts.Program, which exhausts Node's default heap (#3289 CI). `extends` does not inherit
+  // references, so the typecheck node carries them without fallow, fr, editors, or tsdown seeing them.
+  const rootConfig = readTsconfig('tsconfig.json');
+  assert.equal(
+    rootConfig.references,
+    undefined,
+    'references on tsconfig.json slow every fallow gate and OOM freerange',
+  );
+  const typecheckConfig = readTsconfig('tsconfig.typecheck.json');
+  assert.equal(typecheckConfig.extends, './tsconfig.json');
+  assert.equal(
+    typecheckConfig.include,
+    undefined,
+    'the build node must not narrow the root program',
+  );
+  assert.equal(
+    typecheckConfig.exclude,
+    undefined,
+    'the build node must not narrow the root program',
+  );
+  assert.deepEqual(Object.keys(typecheckConfig.compilerOptions ?? {}), ['tsBuildInfoFile']);
+});
+
 test('the compiled-set predicate is licensed by the tsconfig include/exclude shape it mirrors', () => {
   // Scripts retain full R11 checks even when the compiler also checks them.
   const rootConfig = readTsconfig('tsconfig.json');
@@ -117,21 +144,6 @@ test('the root manifest declares every workspace package as a workspace dependen
   );
 });
 
-test('the freerange config stays a reference-free view of the root program', () => {
-  // `fr` loads every `references` project as a full simultaneous ts.Program (~26 programs,
-  // >2.8 GB heap before analysis) and OOMs Node's default 4 GB on this workspace (#3289 CI).
-  // The wrapper at scripts/freerange/tsconfig.json exists only because `extends` does not
-  // inherit references (planted with --showConfig); if someone adds references to it, the
-  // gate reintroduces the OOM, so the absence is pinned here rather than trusted to the comment.
-  const config = readTsconfig('scripts/freerange/tsconfig.json');
-  assert.equal(config.references, undefined, 'references on the freerange config OOM gate');
-  assert.equal(
-    config.extends,
-    '../../tsconfig.json',
-    'the freerange view must stay the root program itself (no include/exclude drift)',
-  );
-});
-
 test('every package tsconfig references exactly its manifest workspace dependencies', () => {
   // The per-package half of the same single-source-of-truth claim (#3279 requirement 1):
   // references are DERIVED from the manifest DAG, so an import a manifest gains must add the

tsconfig.json

@@ -31,35 +31,5 @@
     "scripts/vitest-coverage-run-stamp-reporter.ts",
     "scripts/vitest-coverage-run-stamp-reporter.test.ts",
     "packages/command-registry/src/global.d.ts"
-  ],
-  "references": [
-    { "path": "packages/ad-replay" },
-    { "path": "packages/ad-script" },
-    { "path": "packages/capture-kit" },
-    { "path": "packages/command-registry" },
-    { "path": "packages/contracts" },
-    { "path": "packages/daemon" },
-    { "path": "packages/daemon-contracts" },
-    { "path": "packages/device-selection" },
-    { "path": "packages/host-kit" },
-    { "path": "packages/kernel" },
-    { "path": "packages/maestro" },
-    { "path": "packages/platform-android" },
-    { "path": "packages/platform-apple" },
-    { "path": "packages/platform-harmonyos" },
-    { "path": "packages/platform-linux" },
-    { "path": "packages/platform-vega" },
-    { "path": "packages/platform-web" },
-    { "path": "packages/provider-limrun" },
-    { "path": "packages/provider-testmu" },
-    { "path": "packages/provider-webdriver" },
-    { "path": "packages/provision-kit" },
-    { "path": "packages/proxy" },
-    { "path": "packages/replay-port" },
-    { "path": "packages/replay-test" },
-    { "path": "packages/selectors" },
-    { "path": "packages/session-journal" },
-    { "path": "packages/test-kit" },
-    { "path": "packages/xml" }
   ]
 }

tsconfig.typecheck.json

@@ -0,0 +1,37 @@
+{
+  // The `tsc -b` node for the root program. References live here, not in tsconfig.json, because
+  // fallow and freerange read tsconfig.json and slow down or run out of memory on references.
+  // Its own build info keeps a `tsc -p tsconfig.json` run from marking this build up to date.
+  "extends": "./tsconfig.json",
+  "compilerOptions": { "tsBuildInfoFile": "./.tmp/tsconfig.typecheck.tsbuildinfo" },
+  "references": [
+    { "path": "packages/ad-replay" },
+    { "path": "packages/ad-script" },
+    { "path": "packages/capture-kit" },
+    { "path": "packages/command-registry" },
+    { "path": "packages/contracts" },
+    { "path": "packages/daemon" },
+    { "path": "packages/daemon-contracts" },
+    { "path": "packages/device-selection" },
+    { "path": "packages/host-kit" },
+    { "path": "packages/kernel" },
+    { "path": "packages/maestro" },
+    { "path": "packages/platform-android" },
+    { "path": "packages/platform-apple" },
+    { "path": "packages/platform-harmonyos" },
+    { "path": "packages/platform-linux" },
+    { "path": "packages/platform-vega" },
+    { "path": "packages/platform-web" },
+    { "path": "packages/provider-limrun" },
+    { "path": "packages/provider-testmu" },
+    { "path": "packages/provider-webdriver" },
+    { "path": "packages/provision-kit" },
+    { "path": "packages/proxy" },
+    { "path": "packages/replay-port" },
+    { "path": "packages/replay-test" },
+    { "path": "packages/selectors" },
+    { "path": "packages/session-journal" },
+    { "path": "packages/test-kit" },
+    { "path": "packages/xml" }
+  ]
+}