TypeScript 7.0 (Go Compiler) Migration Plan

Documentation Index

Fetch the complete documentation index at: https://docs.encoreos.io/llms.txt

Use this file to discover all available pages before exploring further.

​

TL;DR

​

Inputs to this plan (already established by ADR-018)

• TS 7.0 Beta = same diagnostics as TS 6.0 on this commit (validated: 0 errors → 0 errors).
• tsgo cold typecheck on this repo: 53 s vs tsc (TS 6.0.3) cold: 478 s (~9× faster).
• tsgo warm typecheck (no cache configured): 3.6 s vs tsc warm-cache target: ~8 s (per .github/workflows/build.yml comment).
• Currently 0 uses of ignoreDeprecations in any tsconfig (the most common 6→7 break) — see tsconfig.json, tsconfig.app.json, tsconfig.node.json, packages/docs/tsconfig.json, supabase/functions/tsconfig.json.
• Internal TS Compiler API consumers: 3 audit scripts.
  • scripts/audit/doc-comment-coverage/parser.ts
  • scripts/audit/audit-appicon-tones.ts
  • scripts/audit/audit-page-spacing.ts
• Third-party TS-API consumers in node_modules (peer ranges as of writing):
  • typescript-eslint@8.58.x / @typescript-eslint/parser@8.58.x → typescript >=4.8.4 <6.1.0
  • eslint-plugin-tsdoc@0.5.2 (via @typescript-eslint/utils@8.56) → same range
  • ts-node@10.9.2 → typescript: >=2.7 (compatible)
  • tsx@4.21.x (esbuild-based; no TS Compiler API peer)
  • fallow@2.66.x → standalone Rust binary (no TS Compiler API peer dependency)
  • msw@2.13.2 → typescript: >=4.8
  • @vitest/coverage-v8@4.1.5 / @vitest/ui@4.1.5 (no direct TS API peer; bundles its own)
  • vite-plugin-checker@0.13.0 → spawns tsc/vue-tsc from the project’s typescript
• Current package.json declares typescript@^6.0.3; lockfile resolved 6.0.3; in node_modules actually deduped to 5.9.3 (because peer ranges in installed minor versions of typescript-eslint cap <6.1.0 and the deduper picked the lower-but-satisfying version after a fresh npm ci --legacy-peer-deps).
• The packages/docs/ workspace pins its own typescript@~5.2.2; isolated from this plan.
• .github/workflows/build.yml step “Cache TypeScript incremental build info” caches node_modules/.cache/tsc keyed on tsconfig*.json + package-lock.json + src/integrations/supabase/types.ts.
• Husky pre-commit runs npm run typecheck (full project); changing this script changes pre-commit behavior.

​

Phase 1 — Opt-in tsgo for local development

​

Diff 1.1 — package.json

   "devDependencies": {
     "@biomejs/biome": "^2.4.11",
+    "@typescript/native-preview": "7.0.0-dev.20260421.2",
     ...
     "typescript": "^6.0.3",
     "typescript-eslint": "^8.59.0",
     ...
   }

​

Diff 1.2 — package.json scripts

   "scripts": {
     ...
     "typecheck": "cross-env NODE_OPTIONS=--max-old-space-size=8192 tsc --noEmit -p tsconfig.app.json --incremental --tsBuildInfoFile node_modules/.cache/tsc/app.tsbuildinfo",
+    "typecheck:fast": "tsgo --noEmit -p tsconfig.app.json",
     ...
   }

• tsgo does not require --incremental to be fast (warm 3.6s without one in our test). Omitting it keeps the script simple and avoids creating a second cache directory.
• No NODE_OPTIONS=--max-old-space-size=8192 because tsgo is a Go binary (not Node) and uses far less memory; the env flag is harmless if a wrapper Node entry point is involved, but adding it would imply Node memory tuning that doesn’t apply.

​

Diff 1.3 — AGENTS.md “Pre-Flight Checklist → Before commit”

 **Before commit (required):** `npm run format:check && npm run typecheck && npm run lint && npm run build` (or `npm run validate`). ...
+
+**Faster local typecheck (developer ergonomics):** `npm run typecheck:fast` (uses the TypeScript 7.0 native compiler `tsgo`; ~9× faster cold, ~2× faster warm; same diagnostics as `tsc`; opt-in). The authoritative pre-commit / CI gate remains `npm run typecheck`. See `docs/development/TYPESCRIPT_7_MIGRATION_PLAN.md`.

​

Diff 1.4 — docs/development/CI_PIPELINE.md

 Or the same steps individually: `npm run format:check`, `npm run typecheck`, `npm run lint`, `npm run build`, `npm run test`, `npm run test:rls:smoke` (or full RLS as needed). See [TESTING_SETUP_AND_RUN.md](../testing/TESTING_SETUP_AND_RUN.md) for E2E and env requirements.
+
+**Tip:** For inner-loop iteration, `npm run typecheck:fast` runs the TypeScript 7.0 (Go) compiler and is roughly 9× faster on cold runs. It produces the same diagnostics as `npm run typecheck`. CI continues to use `tsc` until [Phase 2 of the TS 7 migration plan](TYPESCRIPT_7_MIGRATION_PLAN.md#phase-2--cut-ci-typecheck-over-to-tsgo) lands.

​

Diff 1.5 — docs/development/DEVELOPMENT_QUICK_REFERENCE.md

​

Verification (Phase 1)

npm ci --legacy-peer-deps
node -e "console.log(require('@typescript/native-preview/package.json').version)"
./node_modules/.bin/tsgo --version          # → Version 7.0.0-dev.20260421.2

# Existing path still works and still gates the same as before
npm run typecheck
npm run validate

# Fast path returns identical diagnostics
npm run typecheck:fast

# Ergonomics check: cold time
rm -rf node_modules/.cache/tsc
time npm run typecheck         # baseline
time npm run typecheck:fast    # should be ~9× faster cold

​

Acceptance criteria (Phase 1)

• npm run typecheck exit code, output, and timing unchanged (within 5%) — existing CI gate is unaffected.
• npm run typecheck:fast exits 0 with byte-identical diagnostic count to npm run typecheck on the same commit. (Diagnostic messages are expected to be identical too — TS 7 is a port, not a rewrite — but byte-identity of the ordered diagnostics list is the meaningful gate.)
• npm run validate and npm run validate:governance still pass.
• Husky pre-commit hook still runs the existing tsc path.
• No changes to .github/workflows/build.yml.
• No changes to tsconfig*.json.
• No changes to the linter, audit scripts, MSW, Vitest, Fallow, vite-plugin-checker, or eslint-plugin-tsdoc configurations.

​

Rollback (Phase 1)

​

Phase 2 — Cut CI typecheck over to tsgo

​

Gating criteria (BOTH must hold before opening the Phase 2 PR)

1. Microsoft has shipped TypeScript 7.0 RC or GA. Track via the TypeScript blog and npm view @typescript/native-preview dist-tags (looking for a non--dev tag, or a typescript@7.x publication on the latest channel).
2. typescript-eslint ships a release whose installed peerDependencies.typescript range opens beyond <6.1.0 (verified via npm view typescript-eslint peerDependencies and npm view @typescript-eslint/parser peerDependencies). The cleanest signal is an explicit “TypeScript 7 support” line in their changelog; otherwise verify the peer range alone.

​

Diff 2.1 — package.json

   "devDependencies": {
     ...
     "@typescript/native-preview": "7.0.0-dev.20260421.2",
     ...
-    "typescript": "^6.0.3",
+    "typescript": "npm:@typescript/typescript6@^6.0.0",
+    "@typescript/typescript-7": "npm:typescript@^7.0.0",
     "typescript-eslint": "^8.59.0",
     ...
   }

• typescript resolves to @typescript/typescript6 so any tool that does import ts from 'typescript' (linter, msw, vitest, ts-node, vite-plugin-checker, eslint-plugin-tsdoc, and our 3 audit scripts) keeps the TS 6 Compiler API. This matches Microsoft’s documented compatibility recipe.
• @typescript/typescript-7 (alias of stable typescript@^7) provides the binary we want to invoke directly. By the time Phase 2 ships, the published typescript@7.x package will own the tsc binary; we keep @typescript/native-preview installed only as long as we still need a beta channel.

​

Diff 2.2 — package.json scripts

-    "typecheck": "cross-env NODE_OPTIONS=--max-old-space-size=8192 tsc --noEmit -p tsconfig.app.json --incremental --tsBuildInfoFile node_modules/.cache/tsc/app.tsbuildinfo",
+    "typecheck": "tsgo --noEmit -p tsconfig.app.json",
+    "typecheck:legacy": "cross-env NODE_OPTIONS=--max-old-space-size=8192 tsc6 --noEmit -p tsconfig.app.json --incremental --tsBuildInfoFile node_modules/.cache/tsc/app.tsbuildinfo",
     "typecheck:fast": "tsgo --noEmit -p tsconfig.app.json",

• tsc6 is the binary the @typescript/typescript6 package exposes (per Microsoft’s compatibility docs). Keep typecheck:legacy available for ~1 release cycle as an escape hatch if a tsgo regression is discovered post-cutover.
• typecheck:fast is now redundant with typecheck; keep the alias for one release for muscle memory, then remove in Phase 3.

​

Diff 2.3 — .github/workflows/build.yml

-      - name: Cache TypeScript incremental build info
-        uses: actions/cache@v4
-        with:
-          # Survives across runs so warm `npm run typecheck` finishes in
-          # ~8s instead of the 7m+ cold compile against the 100k-line
-          # generated Supabase types file.
-          path: node_modules/.cache/tsc
-          key: tsc-${{ runner.os }}-${{ hashFiles('tsconfig.json', 'tsconfig.app.json', 'tsconfig.node.json', 'package-lock.json', 'src/integrations/supabase/types.ts') }}
-          restore-keys: |
-            tsc-${{ runner.os }}-
-
       - name: Typecheck
         run: npm run typecheck

​

Diff 2.4 — .husky/pre-commit

​

Diff 2.5 — Documentation refresh

​

Verification (Phase 2)

# Lockfile health
npm ci --legacy-peer-deps
node -e "const v=require('typescript/package.json').version; console.log('typescript=', v); if(!/^6\\./.test(v)) process.exit(1)"
./node_modules/.bin/tsc --version    # via the TS 7 alias entry → Version 7.x.y (or `tsgo --version` if not yet published)
./node_modules/.bin/tsc6 --version   # via the alias → Version 6.0.x

# Authoritative gate
npm run typecheck                    # → expect < 90 s cold, < 10 s warm, 0 errors
npm run typecheck:legacy             # → still works; 0 errors; same as old gate
npm run validate                     # full pipeline

# Linter unchanged
npm run lint
npm run lint:ci

# Audit scripts that import 'typescript' still work
npx tsx scripts/audit/audit-appicon-tones.ts --help 2>&1 | head -5
npx tsx scripts/audit/audit-page-spacing.ts --help 2>&1 | head -5
npx tsx scripts/audit/doc-comment-coverage/audit.ts --help 2>&1 | head -5  # entry that uses parser.ts

# Tests
npm run test
npm run test:integration
npm run test:rls:smoke
npm run test:e2e:smoke

• Build workflow (with the new tsgo-based typecheck step)
• governance-weekly workflow (if it runs on PR; otherwise verify it succeeds on first scheduled run after merge)
• db-advisor-quarterly, db-migration-guard, e2e-full, fhir-validate, supabase-deploy-*, supabase-drift-check workflows must continue to pass — none of these invoke tsc directly, so no diff is expected.

​

Acceptance criteria (Phase 2)

• CI Build workflow Typecheck step runs in < 90 seconds cold and ideally < 10 seconds warm (from cache restore alone if any).
• CI Build workflow has identical pass/fail outcome as prod baseline on the same commit.
• npm run lint exit code unchanged (linter still resolves the TS 6 Compiler API).
• All 3 internal audit scripts (audit-appicon-tones.ts, audit-page-spacing.ts, doc-comment-coverage/parser.ts consumers) execute without import resolution errors.
• npm run test, npm run test:integration, npm run test:rls:smoke, npm run test:e2e:smoke all pass.
• Husky pre-commit hook runs npm run typecheck (now tsgo) successfully on a sample commit.
• Lockfile diff in the PR contains only the expected typescript/@typescript/typescript6/@typescript/typescript-7 (and possibly removed @typescript/native-preview) changes — no unexpected transitive bumps.

​

Rollback (Phase 2)

1. git revert the Phase 2 commit on prod.
2. npm ci --legacy-peer-deps restores TS 6.0.3 as the resolved typescript.
3. CI Build reverts to the old typecheck step automatically (cache step is restored by the same revert).
4. Pre-commit hook reverts to the old tsc invocation.
5. Open an issue capturing the regression with reproduction steps. File upstream against microsoft/typescript-go if it’s a tsgo bug.

​

Phase 3 — Drop the alias; let typescript resolve to 7.x natively

​

Gating criteria (ALL must hold)

• typescript-eslint (and @typescript-eslint/parser, @typescript-eslint/utils) advertise typescript peer ranges that include ^7.
• eslint-plugin-tsdoc ditto (it consumes via @typescript-eslint/utils).
• msw, ts-node, vite-plugin-checker, tsx, @vitest/* ditto (verify by npm view <pkg> peerDependencies).
• Our 3 internal audit scripts have either:
  • (a) been verified to work against the TS 7 Compiler API (run their tests; for audit-appicon-tones see tests/unit/scripts/audit-appicon-tones.test.ts), OR
  • (b) been explicitly pinned to @typescript/typescript6 via direct import path if a TS 7 incompatibility is found.

​

Diff 3.1 — package.json

   "devDependencies": {
     ...
-    "@typescript/native-preview": "7.0.0-dev.20260421.2",     // already removed in Phase 2 if stable shipped
-    ...
-    "typescript": "npm:@typescript/typescript6@^6.0.0",
-    "@typescript/typescript-7": "npm:typescript@^7.0.0",
+    "typescript": "^7.0.0",
     "typescript-eslint": "^8.59.0",   // bump to whatever explicit-TS-7 version is current
     ...
   }

​

Diff 3.2 — package.json scripts

-    "typecheck": "tsgo --noEmit -p tsconfig.app.json",
-    "typecheck:legacy": "cross-env NODE_OPTIONS=--max-old-space-size=8192 tsc6 --noEmit -p tsconfig.app.json --incremental --tsBuildInfoFile node_modules/.cache/tsc/app.tsbuildinfo",
-    "typecheck:fast": "tsgo --noEmit -p tsconfig.app.json",
+    "typecheck": "tsc --noEmit -p tsconfig.app.json",

​

Diff 3.3 — Internal audit scripts

-import ts from 'typescript';
+import ts from '@typescript/typescript6';   // pin TS 6 API for legacy AST shape

​

Diff 3.4 — Documentation refresh

• docs/architecture/decisions/ADR-018-typescript-7-go-compiler-evaluation.md → add a “Phase 3 completed in PR #NNN” line.
• Any remaining mention of tsgo in dev docs → simplify to “TypeScript 7 (tsc)”.

​

Verification (Phase 3)

npm ci --legacy-peer-deps
./node_modules/.bin/tsc --version    # → Version 7.x.y
node -e "console.log(require('typescript/package.json').version)"  # → 7.x.y
npm run typecheck
npm run lint
npm run validate
npm run test

​

Acceptance criteria (Phase 3)

• typescript package resolves to a TS 7 version in node_modules.
• No @typescript/typescript6 or @typescript/native-preview in the lockfile (unless retained in Diff 3.3 as an explicit per-script pin).
• All Phase 2 acceptance criteria still hold.

​

Rollback (Phase 3)

​

Cross-cutting concerns

​

Renovate / Dependabot

• During Phase 1, allow renovate to bump @typescript/native-preview within the 7.0.0-dev.* train at most weekly; require manual approval for jumps across train boundaries (e.g., dev → rc → 7.0.0).
• During Phase 2, pin typescript to the alias literal; renovate cannot upgrade an alias automatically but can flag a PR when @typescript/typescript6 itself publishes a new minor.

​

Editor / IDE guidance

• Phase 1: VS Code “TypeScript Native Preview” extension is opt-in per developer. Workspace settings already use the workspace TypeScript via node_modules/typescript, so Cursor / VS Code default behavior is unchanged.
• Phase 2: Recommend developers uninstall the Native Preview extension and rely on the workspace TS 7 install instead (avoids the bundled-vs-workspace mismatch).

​

packages/docs/ workspace

​

supabase/functions/

​

Test-completeness audit interactions

​

tsx, ts-node script runtime

• tsx is esbuild-based and ignores the installed typescript version for its transform — out of scope.
• ts-node consumes the typescript package at runtime. With Phase 2’s alias, it sees TS 6, which matches today’s runtime behavior — out of scope.

​

Lint warning budget

​

Risk register

​

Tracking artifacts

• Phase 1 PR title: feat(toolchain): add opt-in TypeScript 7 (tsgo) typecheck:fast script — link this plan and ADR-018 in the body.
• Phase 2 PR title: feat(toolchain): cut CI typecheck over to TypeScript 7 (tsgo) with @typescript/typescript6 alias — link this plan and ADR-018; mention the gating-criteria evidence (RC/GA URL, typescript-eslint peer range output).
• Phase 3 PR title: chore(toolchain): drop @typescript/typescript6 alias; let typescript resolve to 7.x natively.

​

Related documents

• ADR-018: TypeScript 7.0 (Go compiler) Evaluation and Adoption
• Microsoft: Announcing TypeScript 7.0 Beta
• .github/workflows/build.yml
• docs/development/CI_PIPELINE.md
• tsconfig.app.json
• package.json