deps: TypeScript 7 migration (JS adapter off createSourceFile)

[rowkav09]

deliberate-work

Dependabot proposed TypeScript 5.9.3 -> 7.0.2 (#502). Triage verdict (gd-security-1): hard-blocked for now - TS 7 removes the programmatic createSourceFile API the JS adapter's usage scanning depends on, and hosted gates failed on the bump with real causes, not flakes.

Held at 5.9.x via a Dependabot ignore rule until this migration is done deliberately: evaluate the TS 7 API surface, port the adapter's import/require/dynamic-import scanning, and re-run the full fixture suite before unblocking.

[rowkav09]

#505 research spike: what replaces createSourceFile in TS 7 (verified 2026-09-28 against typescript@7.0.2)

Method: inspected the published 7.0.2 package (npm pack + registry install), ran a working parse-and-walk proof of concept through the new API, micro-tested the tsconfig failure from #502's CI, and mapped the adapter's full compiler-API surface. No repo changes.

What TS 7.0.2 ships. The npm package is the native (Go) port: bin/tsc is tsgo via a platform binary (@typescript/typescript-linux-x64 etc., pulled as optional platform deps). The root export is only ./lib/version.cjs - the entire legacy JS compiler API is gone from import ts from "typescript". The JS-facing surface lives under explicitly unstable/* subpaths: unstable/ast (node types, all enums, 326 generated is* guards, scanner, visitor, factory, astnav), unstable/sync + unstable/async (session APIs that spawn the bundled tsgo binary and talk to it over IPC), unstable/fs, unstable/proto.

What replaces createSourceFile for us (PoC verified). There is no standalone parse function in 7.0.2. The working path: one API instance (typescript/unstable/sync), updateSnapshot({ openFiles: [...] }) (LSP didOpen semantics; files without a tsconfig land in an inferred project), getDefaultProjectForFile(file).program.getSourceFile(file) - returns a real SourceFile from the shared ast module. My PoC parsed one file and walked it with node.forEachChild + ast.is*: all five import forms the adapter detects came out correctly (static import, bare specifier, require(), dynamic import(), re-export). In-memory text is supported via the virtual-fs option on the API constructor. Mechanical mapping for the port: ts.createSourceFile(f, text, target, true, kind) -> session-backed helper; ts.forEachChild(node, cb) -> node.forEachChild(cb) (now a method on node objects); ts.isX -> ast.isX (same names); ts.SyntaxKind/ScriptKind -> same enums from unstable/ast.

Adapter surface. Five createSourceFile call sites - usage/scan.ts:91, usage/embedded.ts (via scriptKindFor), native/pattern-inspections.ts:198, native/matched-apis.ts:588, native/semantic-inspections.ts:346, references/config.ts:548 - across 7 files, 5,627 lines importing typescript (matched-apis alone 2,486). Almost all of that is guard/walk logic that ports 1:1; the parsing entry points collapse into one shared session wrapper (~100-150 lines: one API per scan run, batched openFiles, virtual fs for synthetic text, dispose lifecycle). ADR 0004's "parse-only, no Program, nothing evaluated" needs a doc note: we now ride an inferred project to get the AST, but still never typecheck or evaluate - the AST shape and our usage of it are unchanged.

The #502 gate failure is two separable problems.

1. Toolchain flood (346 of 556 errors, all TS2591 "@types/node not found"): tsgo 7.0.2 does not auto-include @types under our tsconfig. Verified fix: adding "types": ["node"] to tsconfig.base.json clears it (repro: same file, same flags, error with auto-include, clean with the explicit line). One-line change; per-package verification still needed where @types/node isn't a direct dep.
2. API removal + stricter checks (the remaining ~210): the ts. namespace breakage is the 5-file surface above; the rest (TS2339 x93, TS18048 x31, TS18046 x5, TS7006 x14, TS2552 x7, TS2694 x5, TS2769 x2) partly collapses once node globals resolve (Buffer/URL/process/AbortSignal were 46 of the TS2304s) and the remainder is genuine TS7 strictness differences to fix per file during the port. That tail is real but bounded, and only the core package's log was captured before the job died - expect more across other packages.

Risks. The unstable/* namespace is explicitly unstable - churn across 7.x minors is likely until it graduates; pinning exact versions and watching release notes is mandatory. Platform binaries must resolve on every CI runner OS/arch. Session IPC performance for corpus-scale scans needs measuring (PoC was instant on one file; batch openFiles per snapshot, don't snapshot per file).

Effort estimate. Toolchain fix: XS (one line + verification). Adapter port: M - one session-wrapper module + five entry-point swaps + mechanical guard/forEachChild conversion across 5,627 lines, with the adapter's 22 usage/native fixture tests as the safety net, plus the strictness tail (S-M, per-file). Realistically 3-5 reviewable PRs: (1) tsconfig types line (landable any time, harmless under 5.9), (2) parse-session wrapper behind the existing scriptKindFor seam, (3-4) per-file ports, (5) strictness tail + dependabot ignore removal. Recommendation: keep the hold while the API is unstable/*; the path is now proven end-to-end, so the migration is a known quantity whenever TS 7 stabilizes or 5.9.x becomes a liability. PR (1) is worth landing ahead - it de-risks the eventual bump for free.

[rowkav09]

Arbiter ruling on the spike (comment-5875934450), which is verified and complete - the migration path is now a known quantity with a working PoC, exactly what the hold needed.

1. The tsconfig "types": ["node"] line is a GO as a tiny standalone PR. Independent check: @types/node is the ONLY @types dependency anywhere in the workspace, so making the include explicit cannot silently drop another auto-included types package; CI's workspace typecheck proves the rest. Harmless under 5.9, clears 346 of Bump the production-dependencies group across 2 directories with 1 update #502's 556 errors whenever the bump eventually happens.
2. The migration itself stays HELD while the API surface is unstable/. The session-API path is proven, the port is mostly 1:1 mechanical across a bounded 5-file surface, and the 3-5 PR sequence is the right shape - but pinning to an explicitly unstable namespace with expected churn across 7.x minors is churn we'd pay twice. Trigger to revisit: the surface graduates out of unstable/, or 5.9.x becomes a liability (security fix we can't take, toolchain forcing).
3. When the migration does happen, the spike's ADR-0004 note gets written into the adapter docs: we ride an inferred project to get the AST but still never typecheck or evaluate - parse-only semantics unchanged.

Issue stays open as the tracking record for the hold.

[rowkav09]

#505 perf spike: session-IPC cost at corpus scale (typescript@7.0.2, measured 2026-09-28)

Setup: 282 real files copied from this repo's scannable surface (fixtures/, corpus/, packages/*/src - .ts/.tsx/.js/.mjs/.cjs/.jsx, 2.0 MB, 214,036 AST nodes) into a tsconfig-free tree so every file lands in the inferred project, same as parse-only scanning today. Each path does a full recursive walk of every SourceFile so parsing and node materialization are fully forced, not just top-level fetches. Median-ish of 3 runs on this workspace (numbers were stable, spread under 10%).

path	total	per file	notes
TS 5.9.3 ts.createSourceFile (today's path)	~730 ms	~2.5 ms	pure JS, no server
TS 7 unstable/sync, one snapshot, batch openFiles	~500-580 ms	~1.0 ms after snapshot	API spawn ~4 ms, snapshot 215-242 ms (all 282 files), getSourceFile+full walk 255-330 ms
TS 7 unstable/sync, one snapshot per file	~2,230-2,500 ms	~8-8.9 ms	the anti-pattern: snapshot churn dominates

Read: the session-IPC concern is a non-issue for the migration if the wrapper batches. The batched TS7 path is already faster than today's TS 5.9 path at this scale (native parser, and node objects stream efficiently - 214k nodes walked in ~300 ms). The trap is snapshotting per file: 4-5x slower than today's path. So the session wrapper sketched above should open files in batches per scan run (one snapshot per repo scan, or per directory chunk), never per file.

Caveats: 282 files is a moderate corpus; the batch curve looked linear, so a 5k-file node_modules-scale scan projects to single-digit seconds - acceptable, but worth re-measuring during the actual port. Numbers are one machine, no cold-cache run; tsgo binary spawn is one-time per process (~4 ms here). This closes the perf unknown from the spike above - the remaining hold reasons are API stability (unstable/*) and the port itself, not speed.