From 8a11b35f92e783837a7c06896dc22ab493af441d Mon Sep 17 00:00:00 2001
From: Johnson Chu <johnsoncodehk@gmail.com>
Date: Mon, 4 May 2026 04:40:24 +0000
Subject: [PATCH 01/19] Drop LanguageService dependency from core and CLI (#98)

---
 packages/cli/lib/worker.ts                 | 333 +++++++++++++--------
 packages/cli/test/cache-flow.test.ts       |  43 +--
 packages/cli/test/meta-frameworks.test.ts  | 102 +++++++
 packages/cli/test/program-host.test.ts     | 254 ++++++++++++++++
 packages/config/lib/plugins/diagnostics.ts |   4 +-
 packages/config/lib/plugins/ignore.ts      | 152 ++++------
 packages/core/index.ts                     |  52 ++--
 packages/core/test/completions.test.ts     | 206 +++++++++++++
 packages/core/test/probe.test.ts           |   2 +-
 packages/core/test/skip-rules.test.ts      |   3 +-
 packages/types/index.ts                    |  26 +-
 packages/typescript-plugin/index.ts        |  30 +-
 12 files changed, 941 insertions(+), 266 deletions(-)
 create mode 100644 packages/cli/test/meta-frameworks.test.ts
 create mode 100644 packages/cli/test/program-host.test.ts
 create mode 100644 packages/core/test/completions.test.ts

diff --git a/packages/cli/lib/worker.ts b/packages/cli/lib/worker.ts
index 537244d..767dc55 100644
--- a/packages/cli/lib/worker.ts
+++ b/packages/cli/lib/worker.ts
@@ -16,17 +16,43 @@ import type { IncrementalState } from './incremental-state.js';
 const defaultHash = (s: string) => crypto.createHash('sha256').update(s).digest('hex');
 
 import { createLanguage, FileMap, isCodeActionsEnabled, type Language } from '@volar/language-core';
-import { createProxyLanguageService, decorateLanguageServiceHost, resolveFileLanguageId } from '@volar/typescript';
+import { resolveFileLanguageId } from '@volar/typescript';
 import { transformDiagnostic, transformFileTextChanges } from '@volar/typescript/lib/node/transform';
 
-let projectVersion = 0;
-let typeRootsVersion = 0;
 let options: ts.CompilerOptions = {};
 let fileNames: string[] = [];
+// Volar Language handle — populated by `proxyCreateProgram`'s `setup`
+// callback when a language plugin is active (Vue / MDX / Astro);
+// undefined for plain-TS projects.
 let language: Language<string> | undefined;
 let linter: core.Linter;
-let linterLanguageService!: ts.LanguageService;
-// Layer 2 state. We wrap the LS program in a SemanticDiagnostics-
+// Cached Program instance + dirty flag. Pre-3.2 the worker wrapped a
+// LanguageService over a LanguageServiceHost; getProgram() implicitly
+// rebuilt when the host's projectVersion bumped. We've collapsed that
+// down to direct `ts.createProgram` calls — the LS provided no
+// linter-relevant capability beyond program-rebuild-on-version-bump,
+// and it pulled in completion / refactor / navigation machinery we
+// never used. `--fix` rewrites a file → bumps `programDirty` → next
+// `ensureProgram()` rebuilds with `oldProgram` for incremental binder
+// reuse (TS reuses unchanged SourceFiles' bound state, only re-binds
+// the modified file).
+let currentProgram: ts.Program | undefined;
+let programDirty = true;
+// In-session content overrides for `--fix`-modified files. The
+// CompilerHost's readFile / getSourceFile consult this map first so
+// the next program rebuild sees the post-fix text without disk I/O.
+const fileTextOverrides = new Map<string, string>();
+// Process-level SourceFile cache, shared across projects in the same
+// CLI invocation (`tsslint --project a/tsconfig.json --project b/tsconfig.json`
+// runs in one worker). Pre-3.2 the LS instance survived setup() calls
+// and its internal SourceFile cache reused lib.es5.d.ts / shared
+// node_modules types across projects; with the LS gone, `oldProgram`-
+// based reuse only works within a project (TS bails when
+// compilerOptions differ across tsconfigs). This keeps lib + shared
+// types from re-parsing per project. Invalidated by content change
+// (text-equality check on lookup) so `--fix` rewrites are seen.
+const sourceFileCache = new Map<string, ts.SourceFile>();
+// Layer 2 state. We wrap the program in a SemanticDiagnostics-
 // BuilderProgram (with the prev session's BP fed back via TS's internal
 // `tsBuildInfoText` round-trip) and walk affected files once. cache-
 // flow consults this set to decide whether type-aware rules can be
@@ -37,65 +63,121 @@ let affectedFiles: Set<string> | undefined;
 // capture its updated buildinfo text for next session's persistence.
 let currentBuilder: ts.SemanticDiagnosticsBuilderProgram | undefined;
 
-const snapshots = new Map<string, ts.IScriptSnapshot>();
-const versions = new Map<string, number>();
-const originalHost: ts.LanguageServiceHost = {
-	...ts.sys,
-	useCaseSensitiveFileNames() {
-		return ts.sys.useCaseSensitiveFileNames;
-	},
-	getProjectVersion() {
-		return projectVersion.toString();
-	},
-	getTypeRootsVersion() {
-		return typeRootsVersion;
-	},
-	getCompilationSettings() {
-		return options;
-	},
-	getScriptFileNames() {
-		return fileNames;
-	},
-	getScriptVersion(fileName) {
-		// In-session bumps win — `--fix` updates this map after writing
-		// the file. Otherwise fall back to the on-disk mtime so the
-		// version reflects content across CLI invocations. Layer 2's
-		// BuilderProgram diff relies on this — without it, every cross-
-		// session file looks unchanged (always '0') even when the
-		// content moved on disk.
-		const inSession = versions.get(fileName);
-		if (inSession !== undefined) return inSession.toString();
-		const stat = fs.statSync(fileName, { throwIfNoEntry: false });
-		return stat ? stat.mtimeMs.toString() : '0';
-	},
-	getScriptSnapshot(fileName) {
-		if (!snapshots.has(fileName)) {
-			snapshots.set(fileName, ts.ScriptSnapshot.fromString(ts.sys.readFile(fileName)!));
+// CompilerHost: lower-level than LanguageServiceHost. Just
+// readFile / writeFile / fileExists / lib-file resolution / case
+// sensitivity. We override `readFile` (and `getSourceFile`, which
+// internally reads via readFile) to consult `fileTextOverrides` AND
+// to virtualise Vue / MDX / Astro files via the active language plugin.
+let compilerHost: ts.CompilerHost = createCompilerHost();
+
+function createCompilerHost(): ts.CompilerHost {
+	// `setParentNodes: true` — compat-eslint's bottom-up materialise
+	// walks ts.Node.parent chains; without parent pointers it crashes.
+	// `ts.createLanguageService` set this implicitly; `ts.createProgram`
+	// via `createCompilerHost` defaults false, so we set it explicitly.
+	const host = ts.createCompilerHost(options, true);
+	const originalReadFile = host.readFile.bind(host);
+	const originalGetSourceFile = host.getSourceFile.bind(host);
+	const hash = ts.sys.createHash ?? defaultHash;
+	host.readFile = (fileName: string) => {
+		const override = fileTextOverrides.get(fileName);
+		if (override !== undefined) return override;
+		return originalReadFile(fileName);
+	};
+	host.getSourceFile = (fileName, languageVersion, onError, shouldCreate) => {
+		// Vue / MDX / Astro virtualisation. We replicate `proxyCreateProgram`
+		// but DO NOT apply its `decorateProgram` step — that wraps
+		// `program.getSemanticDiagnostics` to call `fillSourceFileText`,
+		// which mutates `SourceFile.text` in place to splice the original
+		// .vue text back over the leading-offset spaces. The mutation
+		// happens AFTER the AST has been parsed, so the rule walks an AST
+		// whose positions now point at characters in the post-mutation
+		// text — the rule reports diagnostics at offsets that no longer
+		// match the AST it was given. Master got away with this by going
+		// through `decorateLanguageServiceHost` (LS-side, doesn't touch
+		// the program) instead.
+		//
+		// Virtualised SFs are NOT cached cross-project: the plugin's
+		// `getServiceScript` output depends on the per-project `language`
+		// instance, so two projects with different language plugins can
+		// produce different virtual TS for the same fileName.
+		if (language) {
+			const sourceScript = language.scripts.get(fileName);
+			const tsAdapter = sourceScript?.generated?.languagePlugin.typescript;
+			if (sourceScript && tsAdapter) {
+				const orig = originalGetSourceFile(fileName, languageVersion, onError, shouldCreate);
+				if (!orig) return orig;
+				const serviceScript = tsAdapter.getServiceScript(sourceScript.generated!.root);
+				if (serviceScript) {
+					// Two layouts depending on the plugin:
+					//   - !preventLeadingOffset: replace original-text positions
+					//     with whitespace (preserves source-map offsets), then
+					//     append the plugin's emitted TS.
+					//   - preventLeadingOffset: just emit the plugin's TS.
+					const virtualText = !serviceScript.preventLeadingOffset
+						? orig.text.split('\n').map(l => ' '.repeat(l.length)).join('\n')
+							+ serviceScript.code.snapshot.getText(0, serviceScript.code.snapshot.getLength())
+						: serviceScript.code.snapshot.getText(0, serviceScript.code.snapshot.getLength());
+					const virtual = ts.createSourceFile(
+						fileName,
+						virtualText,
+						languageVersion,
+						/*setParentNodes*/ true,
+						serviceScript.scriptKind,
+					);
+					(virtual as unknown as { version: string }).version = hash(virtualText);
+					return virtual;
+				}
+			}
+		}
+		// Plain-TS path. Cross-project SF cache: same path + same content
+		// → return the cached SF unchanged. Skips re-parse for lib.es5.d.ts
+		// and any node_modules types both projects pull in. The text-
+		// equality check is what invalidates after `--fix` (override
+		// changes the text → cache miss → fresh parse).
+		const text = host.readFile(fileName);
+		if (text === undefined) {
+			sourceFileCache.delete(fileName);
+			return undefined;
 		}
-		return snapshots.get(fileName);
-	},
-	getScriptKind(fileName) {
-		const languageId = resolveFileLanguageId(fileName);
-		switch (languageId) {
-			case 'javascript':
-				return ts.ScriptKind.JS;
-			case 'javascriptreact':
-				return ts.ScriptKind.JSX;
-			case 'typescript':
-				return ts.ScriptKind.TS;
-			case 'typescriptreact':
-				return ts.ScriptKind.TSX;
-			case 'json':
-				return ts.ScriptKind.JSON;
+		const cached = sourceFileCache.get(fileName);
+		if (cached && cached.text === text) {
+			return cached;
 		}
-		return ts.ScriptKind.Unknown;
-	},
-	getDefaultLibFileName(options) {
-		return ts.getDefaultLibFilePath(options);
-	},
-};
-const linterHost: ts.LanguageServiceHost = { ...originalHost };
-const originalService = ts.createLanguageService(linterHost);
+		const orig = originalGetSourceFile(fileName, languageVersion, onError, shouldCreate);
+		if (!orig) return orig;
+		// BuilderProgram requires `SourceFile.version` (Debug.checkDefined
+		// throws otherwise). The LS-host path got this via the host's
+		// `getScriptVersion`; raw CompilerHost has no equivalent, so we
+		// stamp a content hash here. Same value across runs as long as
+		// content matches → BuilderProgram's reference-graph diff
+		// correctly identifies unchanged files.
+		if ((orig as unknown as { version?: string }).version === undefined) {
+			(orig as unknown as { version: string }).version = hash(orig.text);
+		}
+		sourceFileCache.set(fileName, orig);
+		return orig;
+	};
+	return host;
+}
+
+function ensureProgram(): ts.Program {
+	if (programDirty || !currentProgram) {
+		// `oldProgram` lets `ts.createProgram` reuse SourceFiles whose
+		// text hasn't changed (text-equality check vs old SF) and skip
+		// re-parsing + re-binding for those. Modified files (via
+		// `fileTextOverrides`) get re-parsed; unchanged files are zero-
+		// cost.
+		currentProgram = ts.createProgram({
+			rootNames: fileNames,
+			options,
+			host: compilerHost,
+			oldProgram: currentProgram,
+		});
+		programDirty = false;
+	}
+	return currentProgram;
+}
 
 // Linter is single-threaded by design. The previous version split into a
 // worker_threads worker for TTY mode (so the spinner could update during a
@@ -148,54 +230,27 @@ async function setup(
 		return String(err);
 	}
 
-	for (let key in linterHost) {
-		if (!(key in originalHost)) {
-			// @ts-ignore
-			delete linterHost[key];
-		}
-		else {
-			// @ts-ignore
-			linterHost[key] = originalHost[key];
-		}
-	}
-	linterLanguageService = originalService;
-	language = undefined;
-
 	// Reset per-project state. Multi-project runs reuse the same worker
 	// (in-process) — without this, cross-project file paths accumulate in
-	// `snapshots` / `versions` (memory leak) and `affectedFiles` from a
-	// prior project would mis-classify this project's files as cache-hit
+	// `fileTextOverrides` (memory leak) and `affectedFiles` from a prior
+	// project would mis-classify this project's files as cache-hit
 	// candidates if their absolute paths happened to overlap.
-	snapshots.clear();
-	versions.clear();
+	fileTextOverrides.clear();
+	language = undefined;
 	affectedFiles = undefined;
 	currentBuilder = undefined;
+	// `currentProgram` is intentionally NOT cleared — `ensureProgram()`
+	// will pass it as `oldProgram` to the next `ts.createProgram` call.
+	// TS reuses SourceFiles whose path + text match across the two
+	// programs, so lib files (lib.es5.d.ts etc., shared between every
+	// project) and any node_modules types both projects pull in skip
+	// the parse + bind cost on the second project. Pre-3.2 the LS
+	// instance survived across projects with the same effect; this
+	// preserves that. `programDirty = true` forces the rebuild so the
+	// new project's rootNames + options take effect.
+	programDirty = true;
 
 	const plugins = await languagePlugins.load(tsconfig, languages);
-	if (plugins.length) {
-		const { getScriptSnapshot } = originalHost;
-		language = createLanguage<string>(
-			[
-				...plugins,
-				{ getLanguageId: fileName => resolveFileLanguageId(fileName) },
-			],
-			new FileMap(ts.sys.useCaseSensitiveFileNames),
-			fileName => {
-				const snapshot = getScriptSnapshot(fileName);
-				if (snapshot) {
-					language!.scripts.set(fileName, snapshot);
-				}
-			},
-		);
-		decorateLanguageServiceHost(ts, language, linterHost);
-
-		const proxy = createProxyLanguageService(linterLanguageService);
-		proxy.initialize(language);
-		linterLanguageService = proxy.proxy;
-	}
-
-	projectVersion++;
-	typeRootsVersion++;
 	fileNames = _fileNames;
 	// Internal API path: BuilderProgram.emitBuildInfo only produces
 	// content when these options are set. Override the user's values
@@ -209,11 +264,42 @@ async function setup(
 		incremental: true,
 		tsBuildInfoFile: incrementalState.SYNTHETIC_BUILD_INFO_PATH,
 	};
+	if (plugins.length) {
+		// Manual replication of `proxyCreateProgram`'s language setup —
+		// without its `decorateProgram` step, which mutates the program's
+		// `getSemanticDiagnostics` to call `fillSourceFileText` and
+		// breaks AST-position lookups (see `createCompilerHost`). The
+		// host's `getSourceFile` consults `language.scripts` to splice
+		// virtual TS into Vue / MDX / Astro files.
+		language = createLanguage<string>(
+			[
+				...plugins,
+				{ getLanguageId: fileName => resolveFileLanguageId(fileName) },
+			],
+			new FileMap(ts.sys.useCaseSensitiveFileNames),
+			(fileName, includeFsFiles) => {
+				if (!includeFsFiles) return;
+				const text = fileTextOverrides.get(fileName) ?? ts.sys.readFile(fileName);
+				if (text === undefined) {
+					language!.scripts.delete(fileName);
+					return;
+				}
+				language!.scripts.set(fileName, ts.ScriptSnapshot.fromString(text));
+			},
+		);
+	}
+	// Compile a fresh CompilerHost AFTER `language` is wired so the
+	// host's getSourceFile virtualisation can read from it. `options`
+	// may have changed too — createCompilerHost bakes those in.
+	compilerHost = createCompilerHost();
 	linter = core.createLinter(
 		{
-			languageService: linterLanguageService,
-			languageServiceHost: linterHost,
 			typescript: ts,
+			// Thunk: each `lint()` call gets the latest Program. `--fix`
+			// rewrites a file mid-session → flips `programDirty` → next
+			// `ensureProgram()` rebuilds with `oldProgram` for incremental
+			// binder reuse.
+			program: ensureProgram,
 		},
 		path.dirname(configFile),
 		config,
@@ -222,7 +308,7 @@ async function setup(
 	);
 
 	{
-		const program = linterLanguageService.getProgram()!;
+		const program = ensureProgram();
 		// Reconstruct the prev session's BP from cached buildinfo text,
 		// fall through to undefined on any failure (cold-start path).
 		const oldBuilder = incrementalState.reconstructOldBuilder(ts, prevIncrementalState, {
@@ -279,7 +365,7 @@ function buildIncrementalState(): IncrementalState | undefined {
 }
 
 function lint(fileName: string, fix: boolean, fileCache: FileCache, fileMtime: number) {
-	let newSnapshot: ts.IScriptSnapshot | undefined;
+	let newText: string | undefined;
 	let diagnostics!: ts.DiagnosticWithLocation[];
 	let shouldCheck = true;
 
@@ -302,8 +388,7 @@ function lint(fileName: string, fix: boolean, fileCache: FileCache, fileMtime: n
 				delete fileCache.rules[ruleId];
 			}
 		}
-		const program = linterLanguageService.getProgram()!;
-		diagnostics = cacheFlow.lintWithCache(linter, fileName, fileCache, fileMtime, program, {
+		diagnostics = cacheFlow.lintWithCache(linter, fileName, fileCache, fileMtime, ensureProgram(), {
 			incremental: true,
 			typeAwareUnaffected,
 		});
@@ -322,19 +407,20 @@ function lint(fileName: string, fix: boolean, fileCache: FileCache, fileMtime: n
 
 		const textChanges = core.combineCodeFixes(fileName, fixes);
 		if (textChanges.length) {
-			const oldSnapshot = snapshots.get(fileName)!;
-			newSnapshot = core.applyTextChanges(oldSnapshot, textChanges);
-			snapshots.set(fileName, newSnapshot);
-			versions.set(fileName, (versions.get(fileName) ?? 0) + 1);
-			projectVersion++;
+			// Apply edits to the current text (override map first, fall
+			// through to disk). Stash result in `fileTextOverrides` so the
+			// next `ensureProgram()` rebuild sees the post-fix content.
+			const baseText = fileTextOverrides.get(fileName) ?? ts.sys.readFile(fileName) ?? '';
+			newText = core.applyTextChanges(baseText, textChanges);
+			fileTextOverrides.set(fileName, newText);
+			programDirty = true;
 		}
 	}
 
-	if (newSnapshot) {
-		const newText = newSnapshot.getText(0, newSnapshot.getLength());
+	if (newText !== undefined) {
 		const oldText = ts.sys.readFile(fileName);
 		if (newText !== oldText) {
-			ts.sys.writeFile(fileName, newSnapshot.getText(0, newSnapshot.getLength()));
+			ts.sys.writeFile(fileName, newText);
 			// File content moved — refresh mtime so the next lint pass
 			// invalidates layer-1 cache entries for this file. lintWithCache
 			// compares fileCache.mtime against the fileMtime we pass in.
@@ -344,8 +430,7 @@ function lint(fileName: string, fix: boolean, fileCache: FileCache, fileMtime: n
 	}
 
 	if (shouldCheck) {
-		const program = linterLanguageService.getProgram()!;
-		diagnostics = cacheFlow.lintWithCache(linter, fileName, fileCache, fileMtime, program, {
+		diagnostics = cacheFlow.lintWithCache(linter, fileName, fileCache, fileMtime, ensureProgram(), {
 			incremental: true,
 			typeAwareUnaffected,
 		});
@@ -353,12 +438,12 @@ function lint(fileName: string, fix: boolean, fileCache: FileCache, fileMtime: n
 
 	// Language-transform path (Vue/MDX/etc.): diagnostics map back from
 	// the transformed file to the original source. The original file
-	// might not be in the language service's program, so we substitute a
-	// SourceFile-shaped POJO with the real source text — `formatDiagnostics-
-	// WithColorAndContext` reads `.file.text` to render code snippets.
+	// might not be in the program, so we substitute a SourceFile-shaped
+	// POJO with the real source text — `formatDiagnosticsWithColorAndContext`
+	// reads `.file.text` to render code snippets.
 	if (language) {
 		diagnostics = diagnostics
-			.map(d => transformDiagnostic(language!, d, (originalService as any).getCurrentProgram(), false))
+			.map(d => transformDiagnostic(language!, d, ensureProgram(), false))
 			.filter(d => !!d);
 		const fileShim = new Map<string, { fileName: string; text: string }>();
 		const getShim = (fn: string) => {
@@ -387,7 +472,7 @@ function lint(fileName: string, fix: boolean, fileCache: FileCache, fileMtime: n
 }
 
 function getFileText(fileName: string) {
-	return originalHost.getScriptSnapshot(fileName)!.getText(0, Number.MAX_VALUE);
+	return fileTextOverrides.get(fileName) ?? ts.sys.readFile(fileName) ?? '';
 }
 
 function hasCodeFixes(fileName: string) {
diff --git a/packages/cli/test/cache-flow.test.ts b/packages/cli/test/cache-flow.test.ts
index 2eb7cad..60841bb 100644
--- a/packages/cli/test/cache-flow.test.ts
+++ b/packages/cli/test/cache-flow.test.ts
@@ -43,7 +43,8 @@ function makeContext(files: Record<string, string>) {
 		fileExists: n => n in files || n === realLibPath,
 		readFile: n => (n in files ? files[n] : (n === realLibPath ? realLibContent : undefined)),
 	};
-	return { typescript: ts, languageServiceHost: host, languageService: ts.createLanguageService(host) };
+	const languageService = ts.createLanguageService(host);
+	return { typescript: ts, program: () => languageService.getProgram()! };
 }
 
 function emptyFileCache(mtime = 0): FileCache {
@@ -62,7 +63,7 @@ function emptyFileCache(mtime = 0): FileCache {
 	};
 	const linter = core.createLinter(ctx, '/', config, () => []);
 	const cache = emptyFileCache(1);
-	cacheFlow.lintWithCache(linter, '/a.ts', cache, 1, ctx.languageService.getProgram()!);
+	cacheFlow.lintWithCache(linter, '/a.ts', cache, 1, ctx.program());
 	check('syntactic rule cache entry written', !!cache.rules['syntactic']);
 	check('cache has 1 diagnostic', cache.rules['syntactic']?.diagnostics.length === 1);
 	check('hasFix false (no fix reported)', cache.rules['syntactic']?.hasFix === false);
@@ -81,7 +82,7 @@ function emptyFileCache(mtime = 0): FileCache {
 	};
 	const linter = core.createLinter(ctx, '/', config, () => []);
 	const cache = emptyFileCache(1);
-	const result = cacheFlow.lintWithCache(linter, '/a.ts', cache, 1, ctx.languageService.getProgram()!);
+	const result = cacheFlow.lintWithCache(linter, '/a.ts', cache, 1, ctx.program());
 	check('type-aware rule still produces diagnostics', result.length === 1);
 	check('type-aware rule NOT cached', !cache.rules['typed']);
 }
@@ -100,7 +101,7 @@ function emptyFileCache(mtime = 0): FileCache {
 	};
 	const linter = core.createLinter(ctx, '/', config, () => []);
 	const cache = emptyFileCache(1);
-	const program = ctx.languageService.getProgram()!;
+	const program = ctx.program();
 
 	cacheFlow.lintWithCache(linter, '/a.ts', cache, 1, program);
 	check('first call ran rule', runs === 1);
@@ -128,7 +129,7 @@ function emptyFileCache(mtime = 0): FileCache {
 	};
 	const linter = core.createLinter(ctx, '/', config, () => []);
 	const cache = emptyFileCache(1);
-	const program = ctx.languageService.getProgram()!;
+	const program = ctx.program();
 
 	cacheFlow.lintWithCache(linter, '/a.ts', cache, 1, program);
 	check('first call ran', runs === 1);
@@ -156,7 +157,7 @@ function emptyFileCache(mtime = 0): FileCache {
 	};
 	const linter = core.createLinter(ctx, '/', config, () => []);
 	const cache = emptyFileCache(1);
-	cacheFlow.lintWithCache(linter, '/a.ts', cache, 1, ctx.languageService.getProgram()!);
+	cacheFlow.lintWithCache(linter, '/a.ts', cache, 1, ctx.program());
 	check('post-rule cleanup deleted entry', !cache.rules['report-then-touch']);
 }
 
@@ -179,7 +180,7 @@ function emptyFileCache(mtime = 0): FileCache {
 	const linter = core.createLinter(ctx, '/', config, () => []);
 	const cacheA = emptyFileCache(1);
 	const cacheB = emptyFileCache(1);
-	const program = ctx.languageService.getProgram()!;
+	const program = ctx.program();
 	cacheFlow.lintWithCache(linter, '/a.ts', cacheA, 1, program);
 	cacheFlow.lintWithCache(linter, '/b.ts', cacheB, 1, program);
 	check('a.ts no cache entry (touched)', !cacheA.rules['sometimes-typed']);
@@ -221,7 +222,7 @@ function emptyFileCache(mtime = 0): FileCache {
 			},
 		},
 	};
-	const result = cacheFlow.lintWithCache(linter, '/a.ts', cache, 1, ctx.languageService.getProgram()!);
+	const result = cacheFlow.lintWithCache(linter, '/a.ts', cache, 1, ctx.program());
 	check('rule re-ran (stale cache ignored)', runs === 1);
 	check('result reflects fresh run', result.length === 1);
 	check('stale entry deleted', !cache.rules['typed']);
@@ -239,7 +240,7 @@ function emptyFileCache(mtime = 0): FileCache {
 	};
 	const linter = core.createLinter(ctx, '/', config, () => []);
 	const cache = emptyFileCache(1);
-	cacheFlow.lintWithCache(linter, '/a.ts', cache, 1, ctx.languageService.getProgram()!);
+	cacheFlow.lintWithCache(linter, '/a.ts', cache, 1, ctx.program());
 	check('hasFix true after rule registered fix', cache.rules['fixable']?.hasFix === true);
 }
 
@@ -261,7 +262,7 @@ function emptyFileCache(mtime = 0): FileCache {
 	};
 	const linter = core.createLinter(ctx, '/', config, () => []);
 	const cache = emptyFileCache(1);
-	const program = ctx.languageService.getProgram()!;
+	const program = ctx.program();
 
 	// First call: both run
 	cacheFlow.lintWithCache(linter, '/a.ts', cache, 1, program);
@@ -294,7 +295,7 @@ function emptyFileCache(mtime = 0): FileCache {
 	};
 	const linter = core.createLinter(ctx, '/', config, () => []);
 	const cache = emptyFileCache(1);
-	const program = ctx.languageService.getProgram()!;
+	const program = ctx.program();
 
 	cacheFlow.lintWithCache(linter, '/a.ts', cache, 1, program, { incremental: true, typeAwareUnaffected: true });
 	check('first call ran (no cache yet)', runs === 1);
@@ -324,7 +325,7 @@ function emptyFileCache(mtime = 0): FileCache {
 	};
 	const linter = core.createLinter(ctx, '/', config, () => []);
 	const cache = emptyFileCache(1);
-	const program = ctx.languageService.getProgram()!;
+	const program = ctx.program();
 
 	cacheFlow.lintWithCache(linter, '/a.ts', cache, 1, program, { incremental: true, typeAwareUnaffected: true });
 	const second = cacheFlow.lintWithCache(linter, '/a.ts', cache, 1, program, {
@@ -358,7 +359,7 @@ function emptyFileCache(mtime = 0): FileCache {
 	};
 	const linter = core.createLinter(ctx, '/', config, () => []);
 	const cache = emptyFileCache(1);
-	const program = ctx.languageService.getProgram()!;
+	const program = ctx.program();
 
 	// Mode B: write the entry.
 	cacheFlow.lintWithCache(linter, '/a.ts', cache, 1, program, { incremental: true, typeAwareUnaffected: true });
@@ -383,7 +384,7 @@ function emptyFileCache(mtime = 0): FileCache {
 	};
 	const linter = core.createLinter(ctx, '/', config, () => []);
 	const cache = emptyFileCache(1);
-	const program = ctx.languageService.getProgram()!;
+	const program = ctx.program();
 
 	// No options arg → mode A. Type-aware rules never cached.
 	cacheFlow.lintWithCache(linter, '/a.ts', cache, 1, program);
@@ -414,7 +415,7 @@ function emptyFileCache(mtime = 0): FileCache {
 	};
 	const linter = core.createLinter(ctx, '/', config, () => []);
 	const cache = emptyFileCache(1);
-	const program = ctx.languageService.getProgram()!;
+	const program = ctx.program();
 
 	// Cold session under --incremental: no prev state, file is "affected"
 	// (unaffected=false). Must run AND write entry.
@@ -454,7 +455,7 @@ function emptyFileCache(mtime = 0): FileCache {
 		'/a.ts',
 		cache,
 		1,
-		ctx.languageService.getProgram()!,
+		ctx.program(),
 	);
 	check('current run returns both diagnostics', diags.length === 2);
 	check(
@@ -485,7 +486,7 @@ function emptyFileCache(mtime = 0): FileCache {
 	};
 	const linter = core.createLinter(ctx, '/', config, () => []);
 	const cache = emptyFileCache(1);
-	cacheFlow.lintWithCache(linter, '/a.ts', cache, 1, ctx.languageService.getProgram()!);
+	cacheFlow.lintWithCache(linter, '/a.ts', cache, 1, ctx.program());
 
 	// Second run with the same mtime — rule cache-hits, only the
 	// persisted diagnostic comes back.
@@ -495,7 +496,7 @@ function emptyFileCache(mtime = 0): FileCache {
 		'/a.ts',
 		cache,
 		1,
-		ctx.languageService.getProgram()!,
+		ctx.program(),
 	);
 	check('warm cache hit returns 1 diagnostic', diags.length === 1);
 	check('warm replay drops the marked one', diags[0]?.messageText === 'plain');
@@ -528,7 +529,7 @@ function emptyFileCache(mtime = 0): FileCache {
 	// ── Session 1: cold, both files lint — process the early-return file
 	// FIRST so the rule isn't yet type-aware when its entry gets written.
 	const linter1 = core.createLinter(ctx, '/', config, () => []);
-	const program1 = ctx.languageService.getProgram()!;
+	const program1 = ctx.program();
 	const cacheSkip: FileCache = emptyFileCache(1);
 	const cacheCheck: FileCache = emptyFileCache(1);
 	cacheFlow.lintWithCache(linter1, '/skip.ts', cacheSkip, 1, program1);
@@ -551,7 +552,7 @@ function emptyFileCache(mtime = 0): FileCache {
 	// Both files unchanged. typeAwareUnaffected=true → both should
 	// cache-hit and replay cleanly.
 	const linter2 = core.createLinter(ctx, '/', config, () => [], ['mixed-mode']);
-	const program2 = ctx.languageService.getProgram()!;
+	const program2 = ctx.program();
 	let earlyReturnRanInSession2 = false;
 	const config2: Config = {
 		rules: {
@@ -599,7 +600,7 @@ function emptyFileCache(mtime = 0): FileCache {
 	};
 	const linter = core.createLinter(ctx, '/', config, () => []);
 	const cache = emptyFileCache(1);
-	cacheFlow.lintWithCache(linter, '/a.ts', cache, 1, ctx.languageService.getProgram()!);
+	cacheFlow.lintWithCache(linter, '/a.ts', cache, 1, ctx.program());
 	// rule entry exists but with 0 diagnostics — no smuggled keys.
 	const json = JSON.stringify(cache);
 	check('NO_CACHE marker not visible in serialised cache', !json.includes('no-cache'));
diff --git a/packages/cli/test/meta-frameworks.test.ts b/packages/cli/test/meta-frameworks.test.ts
new file mode 100644
index 0000000..7d57f8b
--- /dev/null
+++ b/packages/cli/test/meta-frameworks.test.ts
@@ -0,0 +1,102 @@
+// Smoke test for the meta-framework language-plugin path. Spawns the
+// real tsslint CLI against the in-tree `fixtures/meta-frameworks` fixture
+// (.tsx + .vue + .vine.ts + .astro + .mdx) for each `--*-project` flag,
+// asserts the no-console rule fires on EACH framework's script content.
+//
+// This catches the regression class where the language plugin loads but
+// the script content never makes it into the linter's program — e.g. a
+// virtual-script transformation that gets undone before AST walk. Pre-
+// 3.2 (LS-side `decorateLanguageServiceHost`) and post-3.2 (program-side
+// host wrap) both have the same user-visible contract: `console.log`
+// inside `<script>` blocks fires the rule.
+//
+// Run via:
+//   node packages/cli/test/meta-frameworks.test.js
+
+import path = require('path');
+import fs = require('fs');
+import { spawnSync } from 'child_process';
+
+const failures: string[] = [];
+function check(name: string, cond: boolean, detail?: string) {
+	if (cond) {
+		process.stdout.write('.');
+	}
+	else {
+		failures.push(name + (detail ? ' — ' + detail : ''));
+		process.stdout.write('F');
+	}
+}
+
+const repoRoot = path.resolve(__dirname, '../../..');
+const tsslintBin = path.join(repoRoot, 'packages/cli/bin/tsslint.js');
+const fixtureDir = path.join(repoRoot, 'fixtures/meta-frameworks');
+
+if (!fs.existsSync(path.join(fixtureDir, 'node_modules'))) {
+	console.log('meta-frameworks fixture missing node_modules; skipping.');
+	console.log('OK');
+	process.exit(0);
+}
+
+interface Pipeline {
+	flag: '--vue-project' | '--mdx-project' | '--astro-project' | '--vue-vine-project';
+	scriptFile: string;
+}
+
+const pipelines: Pipeline[] = [
+	// Each pipeline expects no-console to fire on at least:
+	//   - fixture.tsx (plain TS path — sanity check, language plugin
+	//     shouldn't break the .tsx flow)
+	//   - the framework's own script file (proves the plugin's virtual
+	//     script reached the AST walker)
+	//
+	// vue-vine pins to `fixture.vue` rather than `fixture.vine.ts`: the
+	// upstream `@vue-vine/language-service` shipped on the workspace has
+	// a known `vueCompilerOptions.globalTypesPath is not a function`
+	// crash inside its `createVirtualCode`, so .vine.ts script content
+	// never reaches the AST. Master has the same gap. We keep the .vue
+	// assertion to verify the vue-vine plugin's .vue path still works.
+	{ flag: '--vue-project', scriptFile: 'fixture.vue' },
+	{ flag: '--mdx-project', scriptFile: 'fixture.mdx' },
+	{ flag: '--astro-project', scriptFile: 'fixture.astro' },
+	{ flag: '--vue-vine-project', scriptFile: 'fixture.vue' },
+];
+
+function strip(s: string) {
+	// CLI output includes ANSI colour escapes; tests compare against the
+	// underlying text only.
+	return s.replace(/\[[0-9;]*m/g, '');
+}
+
+function runCli(flag: Pipeline['flag']): string {
+	const r = spawnSync(
+		process.execPath,
+		[tsslintBin, flag, 'tsconfig.json', '--force'],
+		{ cwd: fixtureDir, stdio: ['ignore', 'pipe', 'pipe'], encoding: 'utf8' },
+	);
+	return strip(r.stdout || '') + strip(r.stderr || '');
+}
+
+for (const { flag, scriptFile } of pipelines) {
+	const out = runCli(flag);
+	// Plain-TS sanity: rule fires on .tsx
+	check(
+		`${flag}: rule fires on fixture.tsx`,
+		out.includes('fixture.tsx') && out.includes("Calls to 'console.x' are not allowed."),
+		`output: ${out.slice(0, 400)}`,
+	);
+	// Language-plugin path: rule fires on the framework file
+	check(
+		`${flag}: rule fires on ${scriptFile}`,
+		out.includes(scriptFile) && out.includes("Calls to 'console.x' are not allowed."),
+		`output: ${out.slice(0, 400)}`,
+	);
+}
+
+process.stdout.write('\n');
+if (failures.length) {
+	console.error(`\n${failures.length} failure(s):`);
+	for (const f of failures) console.error('  - ' + f);
+	process.exit(1);
+}
+console.log('OK');
diff --git a/packages/cli/test/program-host.test.ts b/packages/cli/test/program-host.test.ts
new file mode 100644
index 0000000..0d77556
--- /dev/null
+++ b/packages/cli/test/program-host.test.ts
@@ -0,0 +1,254 @@
+// Regression tests for the worker's CompilerHost setup. The CLI
+// worker (post-3.2) builds Programs directly via `ts.createProgram`
+// instead of going through a LanguageService. Two non-obvious
+// invariants come out of that switch:
+//
+//   1. SourceFile.version stamping — `ts.createSemanticDiagnosticsBuilderProgram`
+//      throws (`Debug.checkDefined`) if any SourceFile is missing
+//      `.version`. The LS path got that for free via the host's
+//      `getScriptVersion`; raw CompilerHost has no equivalent, so the
+//      worker overrides `getSourceFile` to stamp a content hash.
+//
+//   2. setParentNodes — compat-eslint's bottom-up materialise walks
+//      `ts.Node.parent` chains; without them it crashes. `ts.createLanguageService`
+//      sets parent nodes implicitly; raw `ts.createCompilerHost` defaults
+//      false, so the worker passes `true` explicitly.
+//
+//   3. fileTextOverrides → readFile / getSourceFile → BuilderProgram
+//      sees post-fix content. `--fix` rewrites a file and stashes the
+//      new text in the override map; the next `ensureProgram()` rebuild
+//      consumes it via `host.readFile`, and TS's text-equality reuse
+//      logic identifies the file as modified vs the oldProgram.
+//
+// These tests pin those invariants so a future "let's drop the version
+// stamp / setParentNodes argument" cleanup fails loudly instead of
+// crashing only on real projects.
+//
+// Run via:
+//   node packages/cli/test/program-host.test.js
+
+import * as crypto from 'crypto';
+import * as ts from 'typescript';
+
+const failures: string[] = [];
+function check(name: string, cond: boolean, detail?: string) {
+	if (cond) {
+		process.stdout.write('.');
+	}
+	else {
+		failures.push(name + (detail ? ' — ' + detail : ''));
+		process.stdout.write('F');
+	}
+}
+
+const defaultHash = (s: string) => crypto.createHash('sha256').update(s).digest('hex');
+
+// Mirror the worker's CompilerHost setup: in-memory file system layered
+// over `ts.sys` for lib resolution + version stamping + setParentNodes.
+function makeHost(files: Record<string, string>, fileTextOverrides: Map<string, string>): ts.CompilerHost {
+	const realLibPath = ts.getDefaultLibFilePath({ target: ts.ScriptTarget.Latest });
+	const realLibContent = ts.sys.readFile(realLibPath) ?? '';
+	const options: ts.CompilerOptions = {
+		target: ts.ScriptTarget.Latest,
+		noEmit: true,
+		incremental: true,
+		lib: [realLibPath.split(/[\\/]/).pop()!],
+	};
+	const host = ts.createCompilerHost(options, /*setParentNodes*/ true);
+	const originalReadFile = host.readFile.bind(host);
+	const originalGetSourceFile = host.getSourceFile.bind(host);
+	const hash = ts.sys.createHash ?? defaultHash;
+
+	host.fileExists = n => n in files || n === realLibPath || ts.sys.fileExists(n);
+	host.readFile = (fileName: string) => {
+		const override = fileTextOverrides.get(fileName);
+		if (override !== undefined) return override;
+		if (fileName in files) return files[fileName];
+		if (fileName === realLibPath) return realLibContent;
+		return originalReadFile(fileName);
+	};
+	host.getSourceFile = (fileName, languageVersion, onError, shouldCreate) => {
+		const sf = originalGetSourceFile(fileName, languageVersion, onError, shouldCreate);
+		if (sf && (sf as unknown as { version?: string }).version === undefined) {
+			(sf as unknown as { version: string }).version = hash(sf.text);
+		}
+		return sf;
+	};
+	return host;
+}
+
+function buildProgram(files: Record<string, string>, fileTextOverrides: Map<string, string>, oldProgram?: ts.Program) {
+	const host = makeHost(files, fileTextOverrides);
+	return ts.createProgram({
+		rootNames: Object.keys(files),
+		options: {
+			target: ts.ScriptTarget.Latest,
+			noEmit: true,
+			incremental: true,
+		},
+		host,
+		oldProgram,
+	});
+}
+
+// ── Test 1: BuilderProgram doesn't crash on raw createProgram output ─────
+//
+// This is the regression that motivated the version-stamping override.
+// Without `.version` on each SourceFile, BuilderProgram throws
+// `Debug Failure. Program intended to be used with Builder should have
+// source files with versions set`.
+{
+	const overrides = new Map<string, string>();
+	const program = buildProgram({ '/a.ts': 'const x = 1;' }, overrides);
+
+	let threw: unknown;
+	let builder: ts.SemanticDiagnosticsBuilderProgram | undefined;
+	try {
+		builder = ts.createSemanticDiagnosticsBuilderProgram(program, {
+			createHash: ts.sys.createHash ?? defaultHash,
+		});
+	}
+	catch (err) {
+		threw = err;
+	}
+	check(
+		'createSemanticDiagnosticsBuilderProgram does not throw',
+		threw === undefined,
+		threw ? String(threw) : undefined,
+	);
+	check('BuilderProgram instance returned', !!builder);
+}
+
+// ── Test 2: every SourceFile in the program has .version stamped ─────────
+{
+	const program = buildProgram({ '/a.ts': 'const x = 1;', '/b.ts': 'const y = 2;' }, new Map());
+	const a = program.getSourceFile('/a.ts')!;
+	const b = program.getSourceFile('/b.ts')!;
+	check('a.version is set', !!(a as unknown as { version?: string }).version);
+	check('b.version is set', !!(b as unknown as { version?: string }).version);
+	check(
+		'distinct contents → distinct versions',
+		(a as unknown as { version: string }).version !== (b as unknown as { version: string }).version,
+	);
+}
+
+// ── Test 3: parent pointers populated (setParentNodes: true) ─────────────
+//
+// compat-eslint's bottom-up materialise walks `ts.Node.parent` chains.
+// `ts.createCompilerHost(options, true)` sets parents at parse time.
+// Without the `true` flag, AST traversal up from a leaf would crash.
+{
+	const program = buildProgram({ '/a.ts': 'const x = 1;' }, new Map());
+	const sf = program.getSourceFile('/a.ts')!;
+	const stmt = sf.statements[0] as ts.VariableStatement;
+	check('SourceFile root has no parent expectation', sf.parent === undefined);
+	check('top-level statement.parent === SourceFile', stmt.parent === sf);
+	// Drill: VariableStatement → declarationList → declarations[0] → name (Identifier `x`)
+	const list = stmt.declarationList;
+	check('declarationList.parent === VariableStatement', list.parent === stmt);
+	const decl = list.declarations[0];
+	check('declaration.parent === declarationList', decl.parent === list);
+	const ident = decl.name;
+	check('identifier.parent === declaration', ident.parent === decl);
+}
+
+// ── Test 4: fileTextOverrides flows through readFile to the program ──────
+{
+	const overrides = new Map<string, string>();
+	overrides.set('/a.ts', 'const overridden = 42;');
+	const program = buildProgram({ '/a.ts': 'const onDisk = 1;' }, overrides);
+	const sf = program.getSourceFile('/a.ts')!;
+	check(
+		'override wins over disk content',
+		sf.text === 'const overridden = 42;',
+		`got: ${sf.text}`,
+	);
+}
+
+// ── Test 5: oldProgram-based rebuild honours overrides ──────────
+//
+// First build: file is on disk. Second build: same file, override flips
+// the content. The rebuilt program must see the new text. (TS's
+// internal reuse strategy across the two programs is an optimisation —
+// what we lock in here is the correctness contract: the override
+// propagates, the unchanged file's text + version are preserved.)
+{
+	type SF = { version?: string };
+	const versionOf = (sf: ts.SourceFile) => (sf as unknown as SF).version;
+	const overrides = new Map<string, string>();
+	const first = buildProgram(
+		{ '/a.ts': 'const x = 1;', '/b.ts': 'const y = 2;' },
+		overrides,
+	);
+	const firstA = first.getSourceFile('/a.ts')!;
+	const firstB = first.getSourceFile('/b.ts')!;
+	check('first build: a.ts has on-disk text', firstA.text === 'const x = 1;');
+
+	overrides.set('/a.ts', 'const x = 999;'); // simulate --fix rewriting a.ts
+	const second = buildProgram(
+		{ '/a.ts': 'const x = 1;', '/b.ts': 'const y = 2;' },
+		overrides,
+		first,
+	);
+	const secondA = second.getSourceFile('/a.ts')!;
+	const secondB = second.getSourceFile('/b.ts')!;
+
+	check('rebuild: a.ts has overridden text', secondA.text === 'const x = 999;');
+	check('rebuild: b.ts text unchanged', secondB.text === 'const y = 2;');
+	// Version stamping is content-addressed → identical text after rebuild
+	// produces identical version. Lets BuilderProgram's reference-graph
+	// diff identify b.ts as unchanged across the rebuild.
+	check(
+		'b.ts version stable across rebuild (content-addressed)',
+		versionOf(secondB) === versionOf(firstB),
+		`first=${versionOf(firstB)}, second=${versionOf(secondB)}`,
+	);
+	check(
+		'a.ts version differs across rebuild (content changed)',
+		versionOf(secondA) !== versionOf(firstA),
+	);
+}
+
+// ── Test 6: BuilderProgram drain works on a Program with overrides ──────
+//
+// End-to-end: the same setup the worker uses for layer-2 affected-file
+// computation. Drain should walk every file, no crashes.
+{
+	const program = buildProgram(
+		{ '/a.ts': 'const x = 1;', '/b.ts': 'const y = 2;' },
+		new Map(),
+	);
+	const builder = ts.createSemanticDiagnosticsBuilderProgram(program, {
+		createHash: ts.sys.createHash ?? defaultHash,
+	});
+	const affected = new Set<string>();
+	const recordAffected = (sf: ts.SourceFile) => {
+		const a = sf as ts.SourceFile | ts.Program;
+		if ('fileName' in a) {
+			affected.add(a.fileName);
+		}
+		else {
+			for (const f of a.getSourceFiles()) affected.add(f.fileName);
+		}
+		return true;
+	};
+	let drained = 0;
+	while (true) {
+		const r = builder.getSemanticDiagnosticsOfNextAffectedFile(undefined, recordAffected);
+		if (!r) break;
+		drained++;
+		if (drained > 100) {
+			failures.push('drain ran away (no termination)');
+			break;
+		}
+	}
+	check('drain found affected user files', affected.has('/a.ts') && affected.has('/b.ts'));
+}
+
+process.stdout.write('\n');
+if (failures.length) {
+	console.error(`\n${failures.length} failure(s):`);
+	for (const f of failures) console.error('  - ' + f);
+	process.exit(1);
+}
+console.log('OK');
diff --git a/packages/config/lib/plugins/diagnostics.ts b/packages/config/lib/plugins/diagnostics.ts
index e8ee9dc..a5f5edc 100644
--- a/packages/config/lib/plugins/diagnostics.ts
+++ b/packages/config/lib/plugins/diagnostics.ts
@@ -4,9 +4,9 @@ type CheckMode = 'syntactic' | 'semantic' | 'declaration';
 
 export function create(mode: CheckMode | CheckMode[] = 'semantic'): Plugin {
 	const modes = Array.isArray(mode) ? mode : [mode];
-	return ({ languageService }) => ({
+	return ({ program: getProgram }) => ({
 		resolveDiagnostics(file, diagnostics) {
-			const program = languageService.getProgram()!;
+			const program = getProgram();
 			for (const mode of modes) {
 				const diags = mode === 'syntactic'
 					? program.getSyntacticDiagnostics(file)
diff --git a/packages/config/lib/plugins/ignore.ts b/packages/config/lib/plugins/ignore.ts
index 9efced9..7b7f90e 100644
--- a/packages/config/lib/plugins/ignore.ts
+++ b/packages/config/lib/plugins/ignore.ts
@@ -57,107 +57,77 @@ export function create(
 	const completeReg1 = /^\s*\/\/(\s*)([\S]*)?$/;
 	const completeReg2 = new RegExp(`//\\s*${cmd}(\\S*)?$`);
 
-	return ({ typescript: ts, languageService }) => {
+	return ({ typescript: ts }) => {
 		const reportedRulesOfFile = new Map<string, [string, number][]>();
-		const { getCompletionsAtPosition } = languageService;
 
-		languageService.getCompletionsAtPosition = (fileName, position, ...rest) => {
-			let result = getCompletionsAtPosition(fileName, position, ...rest);
-
-			const sourceFile = languageService.getProgram()?.getSourceFile(fileName);
-			if (!sourceFile) {
-				return result;
-			}
-
-			const reportedRules = reportedRulesOfFile.get(fileName);
-			const line = sourceFile.getLineAndCharacterOfPosition(position).line;
-			const lineStart = sourceFile.getPositionOfLineAndCharacter(line, 0);
-			const prefix = sourceFile.text.slice(lineStart, position);
-			const matchCmd = completeReg1
-				? prefix.match(completeReg1)
-				: undefined;
+		return {
+			// IDE-side suggestions: when typing `// @ts-` on a fresh line,
+			// suggest the configured ignore-comment command; when the
+			// command is already typed, suggest rule IDs that fired on the
+			// next line so users can scope the ignore precisely. Only runs
+			// under typescript-plugin (CLI doesn't aggregate completions).
+			resolveCompletions(file, position, entries) {
+				const reportedRules = reportedRulesOfFile.get(file.fileName);
+				const line = file.getLineAndCharacterOfPosition(position).line;
+				const lineStart = file.getPositionOfLineAndCharacter(line, 0);
+				const prefix = file.text.slice(lineStart, position);
+				const matchCmd = prefix.match(completeReg1);
 
-			if (matchCmd) {
-				const nextLineRules = reportedRules?.filter(([, reportedLine]) => reportedLine === line + 1) ?? [];
-				const item: ts.CompletionEntry = {
-					name: cmdText,
-					insertText: matchCmd[1].length ? cmdText : ` ${cmdText}`,
-					kind: ts.ScriptElementKind.keyword,
-					sortText: 'a',
-					replacementSpan: matchCmd[2]
-						? {
-							start: position - matchCmd[2].length,
-							length: matchCmd[2].length,
-						}
-						: undefined,
-					labelDetails: {
-						description: nextLineRules.length >= 2
-							? `Ignore ${nextLineRules.length} issues in next line`
-							: nextLineRules.length
-							? 'Ignore 1 issue in next line'
+				if (matchCmd) {
+					const nextLineRules = reportedRules?.filter(([, reportedLine]) => reportedLine === line + 1) ?? [];
+					entries.push({
+						name: cmdText,
+						insertText: matchCmd[1].length ? cmdText : ` ${cmdText}`,
+						kind: ts.ScriptElementKind.keyword,
+						sortText: 'a',
+						replacementSpan: matchCmd[2]
+							? {
+								start: position - matchCmd[2].length,
+								length: matchCmd[2].length,
+							}
 							: undefined,
-					},
-				};
-				if (result) {
-					result.entries.push(item);
-				}
-				else {
-					result = {
-						isGlobalCompletion: false,
-						isMemberCompletion: false,
-						isNewIdentifierLocation: false,
-						entries: [item],
-					};
+						labelDetails: {
+							description: nextLineRules.length >= 2
+								? `Ignore ${nextLineRules.length} issues in next line`
+								: nextLineRules.length
+								? 'Ignore 1 issue in next line'
+								: undefined,
+						},
+					});
 				}
-			}
-			else if (reportedRules?.length) {
-				const matchRule = completeReg2
-					? prefix.match(completeReg2)
-					: undefined;
-				if (matchRule) {
-					const visited = new Set<string>();
-					for (const [ruleId] of reportedRules) {
-						if (visited.has(ruleId)) {
-							continue;
-						}
-						visited.add(ruleId);
+				else if (reportedRules?.length) {
+					const matchRule = prefix.match(completeReg2);
+					if (matchRule) {
+						const visited = new Set<string>();
+						for (const [ruleId] of reportedRules) {
+							if (visited.has(ruleId)) {
+								continue;
+							}
+							visited.add(ruleId);
 
-						const reportedLines = reportedRules
-							.filter(([r]) => r === ruleId)
-							.map(([, l]) => l + 1);
-						const item: ts.CompletionEntry = {
-							name: ruleId,
-							kind: ts.ScriptElementKind.keyword,
-							sortText: ruleId,
-							replacementSpan: matchRule[1]
-								? {
-									start: position - matchRule[1].length,
-									length: matchRule[1].length,
-								}
-								: undefined,
-							labelDetails: {
-								description: `Reported in line${reportedLines.length >= 2 ? 's' : ''} ${reportedLines.join(', ')}`,
-							},
-						};
-						if (result) {
-							result.entries.push(item);
-						}
-						else {
-							result = {
-								isGlobalCompletion: false,
-								isMemberCompletion: false,
-								isNewIdentifierLocation: false,
-								entries: [item],
-							};
+							const reportedLines = reportedRules
+								.filter(([r]) => r === ruleId)
+								.map(([, l]) => l + 1);
+							entries.push({
+								name: ruleId,
+								kind: ts.ScriptElementKind.keyword,
+								sortText: ruleId,
+								replacementSpan: matchRule[1]
+									? {
+										start: position - matchRule[1].length,
+										length: matchRule[1].length,
+									}
+									: undefined,
+								labelDetails: {
+									description: `Reported in line${reportedLines.length >= 2 ? 's' : ''} ${reportedLines.join(', ')}`,
+								},
+							});
 						}
 					}
 				}
-			}
-
-			return result;
-		};
 
-		return {
+				return entries;
+			},
 			resolveDiagnostics(file, results) {
 				if (
 					!reportsUnusedComments
diff --git a/packages/core/index.ts b/packages/core/index.ts
index e2a2991..dc17636 100644
--- a/packages/core/index.ts
+++ b/packages/core/index.ts
@@ -72,10 +72,12 @@ export function createLinter(
 			const skipRules = options?.skipRules;
 
 			const rules = getRulesForFile(fileName);
-			const token = ctx.languageServiceHost.getCancellationToken?.();
 			const configs = getConfigsForFile(fileName);
 
-			const program = ctx.languageService.getProgram()!;
+			// Single read at top of `lint()`: rule callbacks all observe
+			// the same Program identity for this file's pass, even if a
+			// caller swaps the underlying program between `lint()` calls.
+			const program = ctx.program();
 			const file = program.getSourceFile(fileName)!;
 			let touchedProgram = false;
 			const rulesContext: RuleContext = {
@@ -93,10 +95,6 @@ export function createLinter(
 			const lintResult = lintResults.get(fileName)!;
 
 			for (const [ruleId, rule] of Object.entries(rules)) {
-				if (token?.isCancellationRequested()) {
-					break;
-				}
-
 				currentRuleId = ruleId;
 
 				if (skipRules?.has(currentRuleId)) {
@@ -325,6 +323,26 @@ export function createLinter(
 				}
 			}
 		},
+		// IDE-side completion entries. Aggregates `resolveCompletions`
+		// across plugins; CLI never calls this. typescript-plugin merges
+		// the result into the host LanguageService's getCompletionsAtPosition.
+		getCompletions(fileName: string, position: number): ts.CompletionEntry[] {
+			const program = ctx.program();
+			const file = program.getSourceFile(fileName);
+			if (!file) {
+				return [];
+			}
+			const configs = getConfigsForFile(fileName);
+			let entries: ts.CompletionEntry[] = [];
+			for (const { plugins } of configs) {
+				for (const { resolveCompletions } of plugins) {
+					if (resolveCompletions) {
+						entries = resolveCompletions(file, position, entries);
+					}
+				}
+			}
+			return entries;
+		},
 		getRules: getRulesForFile,
 		getConfigs: getConfigsForFile,
 		// Snapshot of rules classified type-aware so far. The CLI reads
@@ -416,21 +434,13 @@ export function combineCodeFixes(fileName: string, fixes: ts.CodeFixAction[]) {
 	return finalTextChanges;
 }
 
-export function applyTextChanges(baseSnapshot: ts.IScriptSnapshot, textChanges: ts.TextChange[]): ts.IScriptSnapshot {
-	textChanges = [...textChanges].sort((a, b) => b.span.start - a.span.start);
-	let text = baseSnapshot.getText(0, baseSnapshot.getLength());
-	for (const change of textChanges) {
+export function applyTextChanges(baseText: string, textChanges: ts.TextChange[]): string {
+	// Apply edits back-to-front so each change's offsets remain valid as
+	// earlier ones shift the suffix.
+	const sorted = [...textChanges].sort((a, b) => b.span.start - a.span.start);
+	let text = baseText;
+	for (const change of sorted) {
 		text = text.slice(0, change.span.start) + change.newText + text.slice(change.span.start + change.span.length);
 	}
-	return {
-		getText(start, end) {
-			return text.substring(start, end);
-		},
-		getLength() {
-			return text.length;
-		},
-		getChangeRange() {
-			return undefined;
-		},
-	};
+	return text;
 }
diff --git a/packages/core/test/completions.test.ts b/packages/core/test/completions.test.ts
new file mode 100644
index 0000000..b6a2814
--- /dev/null
+++ b/packages/core/test/completions.test.ts
@@ -0,0 +1,206 @@
+// Tests for `linter.getCompletions` — the IDE-side aggregator that
+// merges `resolveCompletions` results from configured plugins. Exists
+// because pre-3.2 the `@tsslint/config` ignore plugin reached for the
+// host's `LanguageService.getCompletionsAtPosition` directly via
+// `LinterContext`. That coupling is gone — plugins now expose
+// completions through this hook, and `typescript-plugin` merges the
+// aggregator's output into the host LS's completion result.
+//
+// Run via:
+//   node packages/core/test/completions.test.js
+
+import type { Config, PluginInstance } from '@tsslint/types';
+import * as ts from 'typescript';
+
+const core = require('../index.js') as typeof import('../index.js');
+
+const failures: string[] = [];
+function check(name: string, cond: boolean, detail?: string) {
+	if (cond) {
+		process.stdout.write('.');
+	}
+	else {
+		failures.push(name + (detail ? ' — ' + detail : ''));
+		process.stdout.write('F');
+	}
+}
+
+function makeContext(files: Record<string, string>) {
+	const realLibPath = ts.getDefaultLibFilePath({ target: ts.ScriptTarget.Latest });
+	const realLibContent = ts.sys.readFile(realLibPath) ?? '';
+	const host: ts.LanguageServiceHost = {
+		getCompilationSettings: () => ({
+			target: ts.ScriptTarget.Latest,
+			noEmit: true,
+			lib: [realLibPath.split(/[\\/]/).pop()!],
+		}),
+		getScriptFileNames: () => Object.keys(files),
+		getScriptVersion: () => '1',
+		getScriptSnapshot: n => {
+			if (n in files) return ts.ScriptSnapshot.fromString(files[n]);
+			if (n === realLibPath) return ts.ScriptSnapshot.fromString(realLibContent);
+			return undefined;
+		},
+		getCurrentDirectory: () => '/',
+		getDefaultLibFileName: () => realLibPath,
+		fileExists: n => n in files || n === realLibPath,
+		readFile: n => (n in files ? files[n] : (n === realLibPath ? realLibContent : undefined)),
+	};
+	const languageService = ts.createLanguageService(host);
+	return { typescript: ts, program: () => languageService.getProgram()! };
+}
+
+// ── Test 1: no plugins → empty entries ───────────────────────────────────
+{
+	const ctx = makeContext({ '/a.ts': 'const x = 1;' });
+	const config: Config = { rules: {} };
+	const linter = core.createLinter(ctx, '/', config, () => []);
+	const result = linter.getCompletions('/a.ts', 0);
+	check('no plugins: returns empty array', Array.isArray(result) && result.length === 0);
+}
+
+// ── Test 2: single plugin contributes an entry ────────────────────────────
+{
+	const ctx = makeContext({ '/a.ts': 'const x = 1;' });
+	const plugin: PluginInstance = {
+		resolveCompletions(_file, _position, entries) {
+			entries.push({
+				name: 'my-completion',
+				kind: ts.ScriptElementKind.keyword,
+				sortText: 'a',
+			});
+			return entries;
+		},
+	};
+	const config: Config = {
+		rules: {},
+		plugins: [() => plugin],
+	};
+	const linter = core.createLinter(ctx, '/', config, () => []);
+	const result = linter.getCompletions('/a.ts', 0);
+	check('single plugin: 1 entry returned', result.length === 1);
+	check('single plugin: name is correct', result[0]?.name === 'my-completion');
+}
+
+// ── Test 3: multiple plugins compose; later plugin sees earlier entries ──
+{
+	const ctx = makeContext({ '/a.ts': 'const x = 1;' });
+	let observedByPluginB: number | undefined;
+	const pluginA: PluginInstance = {
+		resolveCompletions(_file, _position, entries) {
+			entries.push({ name: 'a', kind: ts.ScriptElementKind.keyword, sortText: 'a' });
+			return entries;
+		},
+	};
+	const pluginB: PluginInstance = {
+		resolveCompletions(_file, _position, entries) {
+			// B sees A's entry already in the array (proves left-to-right
+			// composition with an aggregating accumulator).
+			observedByPluginB = entries.length;
+			entries.push({ name: 'b', kind: ts.ScriptElementKind.keyword, sortText: 'b' });
+			return entries;
+		},
+	};
+	const config: Config = {
+		rules: {},
+		plugins: [() => pluginA, () => pluginB],
+	};
+	const linter = core.createLinter(ctx, '/', config, () => []);
+	const result = linter.getCompletions('/a.ts', 0);
+	check('two plugins: 2 entries total', result.length === 2);
+	check("plugin B saw plugin A's entry first", observedByPluginB === 1);
+	check('order preserved: a before b', result[0]?.name === 'a' && result[1]?.name === 'b');
+}
+
+// ── Test 4: plugin without resolveCompletions doesn't break aggregator ───
+{
+	const ctx = makeContext({ '/a.ts': 'const x = 1;' });
+	const pluginNoCompletions: PluginInstance = {
+		resolveDiagnostics(_file, diagnostics) {
+			return diagnostics;
+		},
+		// no resolveCompletions
+	};
+	const pluginWithCompletions: PluginInstance = {
+		resolveCompletions(_file, _position, entries) {
+			entries.push({ name: 'only', kind: ts.ScriptElementKind.keyword, sortText: 'a' });
+			return entries;
+		},
+	};
+	const config: Config = {
+		rules: {},
+		plugins: [() => pluginNoCompletions, () => pluginWithCompletions],
+	};
+	const linter = core.createLinter(ctx, '/', config, () => []);
+	const result = linter.getCompletions('/a.ts', 0);
+	check('skips plugin without resolveCompletions', result.length === 1);
+	check('still gets entry from contributing plugin', result[0]?.name === 'only');
+}
+
+// ── Test 5: missing file returns empty (program.getSourceFile undefined) ──
+{
+	const ctx = makeContext({ '/a.ts': 'const x = 1;' });
+	const plugin: PluginInstance = {
+		resolveCompletions(_file, _position, entries) {
+			entries.push({ name: 'should-not-appear', kind: ts.ScriptElementKind.keyword, sortText: 'a' });
+			return entries;
+		},
+	};
+	const config: Config = {
+		rules: {},
+		plugins: [() => plugin],
+	};
+	const linter = core.createLinter(ctx, '/', config, () => []);
+	// Asking about a file not in the program — guard short-circuits to [].
+	const result = linter.getCompletions('/does-not-exist.ts', 0);
+	check('missing file: empty result, plugin not invoked', result.length === 0);
+}
+
+// ── Test 6: plugin receives the SourceFile for the requested file ────────
+{
+	const ctx = makeContext({ '/a.ts': 'const hello = 1;' });
+	let observedFileName: string | undefined;
+	let observedText: string | undefined;
+	const plugin: PluginInstance = {
+		resolveCompletions(file, _position, entries) {
+			observedFileName = file.fileName;
+			observedText = file.text;
+			return entries;
+		},
+	};
+	const config: Config = {
+		rules: {},
+		plugins: [() => plugin],
+	};
+	const linter = core.createLinter(ctx, '/', config, () => []);
+	linter.getCompletions('/a.ts', 5);
+	check('plugin sees correct fileName', observedFileName === '/a.ts');
+	check('plugin sees correct text', observedText === 'const hello = 1;');
+}
+
+// ── Test 7: position is passed through to plugin verbatim ────────────────
+{
+	const ctx = makeContext({ '/a.ts': 'const hello = 1;' });
+	let observedPosition: number | undefined;
+	const plugin: PluginInstance = {
+		resolveCompletions(_file, position, entries) {
+			observedPosition = position;
+			return entries;
+		},
+	};
+	const config: Config = {
+		rules: {},
+		plugins: [() => plugin],
+	};
+	const linter = core.createLinter(ctx, '/', config, () => []);
+	linter.getCompletions('/a.ts', 12);
+	check('plugin receives requested position', observedPosition === 12);
+}
+
+process.stdout.write('\n');
+if (failures.length) {
+	console.error(`\n${failures.length} failure(s):`);
+	for (const f of failures) console.error('  - ' + f);
+	process.exit(1);
+}
+console.log('OK');
diff --git a/packages/core/test/probe.test.ts b/packages/core/test/probe.test.ts
index 9a734d3..82a4275 100644
--- a/packages/core/test/probe.test.ts
+++ b/packages/core/test/probe.test.ts
@@ -47,7 +47,7 @@ function makeContext(files: Record<string, string>) {
 		readFile: n => (n in files ? files[n] : (n === realLibPath ? realLibContent : undefined)),
 	};
 	const languageService = ts.createLanguageService(host);
-	return { typescript: ts, languageServiceHost: host, languageService };
+	return { typescript: ts, program: () => languageService.getProgram()! };
 }
 
 // ── Test 1: rule that doesn't read program → not classified ──────────────
diff --git a/packages/core/test/skip-rules.test.ts b/packages/core/test/skip-rules.test.ts
index fceab6c..51c760a 100644
--- a/packages/core/test/skip-rules.test.ts
+++ b/packages/core/test/skip-rules.test.ts
@@ -42,7 +42,8 @@ function makeContext(files: Record<string, string>) {
 		fileExists: n => n in files || n === realLibPath,
 		readFile: n => (n in files ? files[n] : (n === realLibPath ? realLibContent : undefined)),
 	};
-	return { typescript: ts, languageServiceHost: host, languageService: ts.createLanguageService(host) };
+	const languageService = ts.createLanguageService(host);
+	return { typescript: ts, program: () => languageService.getProgram()! };
 }
 
 // ── Test 1: rule in skipRules doesn't run, no diagnostic in result ───────
diff --git a/packages/types/index.ts b/packages/types/index.ts
index 57ed8c9..f3d1bc0 100644
--- a/packages/types/index.ts
+++ b/packages/types/index.ts
@@ -1,18 +1,30 @@
 import type {
 	CodeFixAction,
+	CompletionEntry,
 	Diagnostic,
 	DiagnosticWithLocation,
 	FileTextChanges,
-	LanguageService,
-	LanguageServiceHost,
 	Program,
 	SourceFile,
 } from 'typescript';
 
 export interface LinterContext {
 	typescript: typeof import('typescript');
-	languageServiceHost: LanguageServiceHost;
-	languageService: LanguageService;
+	// Program thunk (not a stable instance). Callers that mutate the
+	// project mid-session (e.g. CLI `--fix` rewriting a file) rebuild the
+	// Program and the next `lint()` call sees the new one. Each `lint()`
+	// reads this once at the top, so within a single file's pass the
+	// Program identity stays stable.
+	//
+	// Pre-3.2: this was `{ languageService, languageServiceHost }`.
+	// LinterContext consumed only `getProgram()` and `getCancellationToken()`
+	// from those — the rest of the LS / Host surface was unused, so the
+	// indirection was paying for capabilities (completions, refactors,
+	// navigation) that the linter never touches. Direct Program access
+	// also makes the surface trivially compatible with hosts that don't
+	// run a full LanguageService (raw `ts.createProgram`, tsgo's
+	// `Project.program`, etc.).
+	program: () => Program;
 }
 
 export interface Config {
@@ -30,6 +42,12 @@ export interface PluginInstance {
 	resolveRules?(fileName: string, rules: Record<string, Rule>): Record<string, Rule>;
 	resolveDiagnostics?(file: SourceFile, diagnostics: DiagnosticWithLocation[]): DiagnosticWithLocation[];
 	resolveCodeFixes?(file: SourceFile, diagnostic: Diagnostic, codeFixes: CodeFixAction[]): CodeFixAction[];
+	// IDE-side completion entries. Hosted environments (typescript-plugin)
+	// merge the result into `LanguageService.getCompletionsAtPosition`.
+	// CLI ignores it. Pre-3.2 the ignore plugin reached for `LanguageService`
+	// directly via `LinterContext`; that path is gone, so plugins that want
+	// IDE completions hook in here instead.
+	resolveCompletions?(file: SourceFile, position: number, entries: CompletionEntry[]): CompletionEntry[];
 }
 
 export interface Rules {
diff --git a/packages/typescript-plugin/index.ts b/packages/typescript-plugin/index.ts
index 8671b13..1e411a3 100644
--- a/packages/typescript-plugin/index.ts
+++ b/packages/typescript-plugin/index.ts
@@ -40,6 +40,7 @@ function decorateLanguageService(
 		getSemanticDiagnostics,
 		getCodeFixesAtPosition,
 		getCombinedCodeFix,
+		getCompletionsAtPosition,
 		getApplicableRefactors,
 		getEditsForRefactor,
 	} = info.languageService;
@@ -91,6 +92,33 @@ function decorateLanguageService(
 		}
 		return getCombinedCodeFix(scope, fixId, formatOptions, preferences);
 	};
+	// Merge plugin-supplied completion entries (e.g. ignore-comment
+	// suggestions from `@tsslint/config`'s ignore plugin) into the host's
+	// own completion result. Pre-3.2 plugins reached for
+	// `LanguageService.getCompletionsAtPosition` directly via
+	// `LinterContext`; the cleaner Program-based context takes that path
+	// away, so the IDE side reaches in through `linter.getCompletions`
+	// instead.
+	info.languageService.getCompletionsAtPosition = (fileName, position, ...rest) => {
+		let result = getCompletionsAtPosition(fileName, position, ...rest);
+		if (linter && isProjectFileName(fileName)) {
+			const extra = linter.getCompletions(fileName, position);
+			if (extra.length) {
+				if (result) {
+					result.entries.push(...extra);
+				}
+				else {
+					result = {
+						isGlobalCompletion: false,
+						isMemberCompletion: false,
+						isNewIdentifierLocation: false,
+						entries: extra,
+					};
+				}
+			}
+		}
+		return result;
+	};
 	info.languageService.getApplicableRefactors = (
 		fileName,
 		positionOrRange,
@@ -167,8 +195,8 @@ function decorateLanguageService(
 			}
 
 			const projectContext: LinterContext = {
-				...info,
 				typescript: ts,
+				program: () => info.languageService.getProgram()!,
 			};
 
 			try {

From f29b86e5d71b73e44e553cd4a3e44d67e4b4ec75 Mon Sep 17 00:00:00 2001
From: Johnson Chu <johnsoncodehk@gmail.com>
Date: Mon, 4 May 2026 21:53:43 +0800
Subject: [PATCH 02/19] =?UTF-8?q?cli:=20tsgo=20backend=20skeleton=20(--tsg?=
 =?UTF-8?q?o)=20=E2=80=94=20Program/Checker=20adapter=20+=20Node=20prototy?=
 =?UTF-8?q?pe=20shim?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Lays the plumbing for tsgo (`@typescript/native-preview`) integration without
introducing it as a hard dependency.

Adapter (lib/tsgo-backend.ts):
- Wraps `Project.program` + `Project.checker` as a `ts.Program` /
  `ts.TypeChecker`-shape that satisfies LinterContext's Program-thunk
  contract from PR #98.
- Per-file batched prepass: walks the SF locally, resolves every Identifier
  via `Checker.getSymbolAtPosition([positions])` in a single sync RPC.
  Position-based primary because `getSymbolAtLocation` returns undefined for
  identifiers in import/export specifier position (~76% of identifiers in a
  type-heavy file). Location-based fallback for the small remainder.
- Symbol identity is rock-solid via tsgo's `symbol.id` — `Map<Symbol, X>`
  patterns (compat-eslint's `variableBySymbol`) work unchanged.
- Patches `getStart` / `getEnd` / `getText` / `getFullStart` / `getFullText`
  / `getWidth` / `getFullWidth` onto tsgo's `RemoteNode` prototype (located
  by walking the prototype chain — the Remote{Node,SourceFile} classes
  aren't in the package exports map). Uses real ts's `skipTrivia` —
  bit-identical positions vs ts.Node.

CLI wiring (lib/worker.ts, index.ts):
- `--tsgo` flag dispatches setup() into the tsgo branch.
- Rejects --vue/--mdx/--astro/--vue-vine/--ts-macro projects with a clear
  error (Volar host injection isn't available on tsgo).
- Skips BuilderProgram drain / layer-2 affected-file classification (no JS
  API on tsgo); treats every file as affected → cached type-aware entries
  re-validate rather than serve from a stale snapshot.
- `lint()` calls `tsgoBackend.prepareFile(name)` before rules run.

Optional peer dep: `@typescript/native-preview`. Users without it never
import the backend (the require path is gated behind --tsgo).

Verification:
- packages/cli/test/tsgo-backend.test.ts — 12 checks (skips when peer dep
  absent): SF fetch + AST walk, batched symbol prepass, Symbol identity
  collapse, Map<Symbol> compatibility, program method coverage.
- Existing tests unchanged: program-host (17), cache-flow (50),
  meta-frameworks (8).
- End-to-end: --tsgo --project packages/{types,core,compat-eslint}/tsconfig.json
  runs to completion; full repo lint 1.66s vs 1.45s on ts.Program (small
  parity gap; dominated by per-project snapshot init).

Known gap (next commit): rule code calls `ts.isXxx(node)` and
`ts.forEachChild(node, cb)` from real ts — these dispatch on
`ts.SyntaxKind` values. tsgo Node kinds are offset-shifted (Identifier=79
vs 80), so dispatch tables miss → rules silently no-op. SyntaxKind
remapping or ts module facade required to make rules fire.
---
 packages/cli/index.ts                  |   1 +
 packages/cli/lib/tsgo-backend.ts       | 345 +++++++++++++++++++++++++
 packages/cli/lib/worker.ts             |  41 +++
 packages/cli/package.json              |   8 +-
 packages/cli/test/tsgo-backend.test.ts | 154 +++++++++++
 pnpm-lock.yaml                         |  81 ++++++
 6 files changed, 629 insertions(+), 1 deletion(-)
 create mode 100644 packages/cli/lib/tsgo-backend.ts
 create mode 100644 packages/cli/test/tsgo-backend.test.ts

diff --git a/packages/cli/index.ts b/packages/cli/index.ts
index c92a93f..5203b11 100644
--- a/packages/cli/index.ts
+++ b/packages/cli/index.ts
@@ -35,6 +35,7 @@ Options:
   --failures-only               Only print errors and messages (skip warnings and suggestions)
   --list-rules                  After linting, print each rule's classification (syntactic / type-aware)
   --debug-estree                After linting, print the actual ESTree node types converted by @tsslint/compat-eslint and their counts
+  --tsgo                        Use @typescript/native-preview as the type-check backend (experimental; plain-TS only, no Vue/MDX/Astro, no layer-2 cache)
   -h, --help                    Show this help message
 
 Examples:
diff --git a/packages/cli/lib/tsgo-backend.ts b/packages/cli/lib/tsgo-backend.ts
new file mode 100644
index 0000000..0e24dda
--- /dev/null
+++ b/packages/cli/lib/tsgo-backend.ts
@@ -0,0 +1,345 @@
+// tsgo backend — alternative to ts.createProgram for the linter's
+// `ctx.program()` thunk. Activated by `--tsgo`. Spawns the
+// @typescript/native-preview binary, holds a Snapshot/Project, and
+// presents `Project.program` + `Project.checker` as a ts.Program /
+// ts.TypeChecker subset that satisfies the linter's contract.
+//
+// Two non-obvious invariants:
+//
+//   1. Symbol resolution batching. tsgo Checker calls are sync RPCs.
+//      `Checker.getSymbolAtLocation([nodes])` and
+//      `Checker.getSymbolAtPosition(file, [positions])` are array
+//      overloads — N nodes resolved in 1 RPC. We do a per-file prepass:
+//      walk the AST, collect every Identifier, batched-resolve once,
+//      stash in `nodeToSymbol`. Rules then call `getSymbolAtLocation`
+//      synchronously and read from the Map.
+//
+//   2. `getSymbolAtLocation` doesn't resolve identifiers in
+//      import/export specifier position (~76% miss rate on type-heavy
+//      TS files). `getSymbolAtPosition(file, [endOffsets])` does. The
+//      prepass uses the position-based API as primary and falls back
+//      to location-based for the small remainder (mostly object-spread
+//      method names where position is "between siblings").
+//
+// AST node identity is preserved across calls — tsgo's SourceFileCache
+// hands back the same parsed SF object for the same path within a
+// snapshot, and we reuse those Node references as Map keys.
+
+import path = require('path');
+import ts = require('typescript');
+
+// `@typescript/native-preview` ships ESM-only. Under Node16 module
+// resolution, type-only imports of an ESM package from this CJS file
+// require the `'resolution-mode': 'import'` attribute. We thread that
+// through once via `import(..., { with: ... })` aliases and reuse them.
+type TsgoSync = typeof import('@typescript/native-preview/sync', { with: { 'resolution-mode': 'import' } });
+type API = InstanceType<TsgoSync['API']>;
+type Snapshot = InstanceType<TsgoSync['Snapshot']>;
+type Project = InstanceType<TsgoSync['Project']>;
+type TsgoSymbol = InstanceType<TsgoSync['Symbol']>;
+type TsgoAst = typeof import('@typescript/native-preview/ast', { with: { 'resolution-mode': 'import' } });
+type Node = import('@typescript/native-preview/ast', { with: { 'resolution-mode': 'import' } }).Node;
+
+export interface TsgoBackend {
+	// ts.Program-shape adapter, fed to LinterContext.program().
+	getProgram(): ts.Program;
+	// Per-file prepass: walks the SF, collects every Identifier, resolves
+	// in one batched RPC, populates the symbol cache. Must be called for
+	// each file before rules run against it.
+	prepareFile(fileName: string): void;
+	// Tear down child process + free snapshot refs.
+	close(): void;
+}
+
+// Process-level guard so we patch the tsgo Node prototype exactly once,
+// even if multiple backends spin up in the same worker.
+let nodeProtoPatched = false;
+
+// tsgo's Node interface exposes `pos` / `end` (raw parser offsets,
+// leading trivia included), `parent`, `kind`, `forEachChild`,
+// `getSourceFile()`. It does NOT provide ts.Node's instance methods
+// `getStart` / `getEnd` / `getText` — TS adds these on the runtime
+// NodeObject prototype, and rule code (lazy-estree's range computation,
+// plenty of compat-eslint utilities) calls them as if every Node is a
+// ts.Node.
+//
+// Tsgo nodes returned from the API are `RemoteNode` / `RemoteSourceFile`
+// instances (separate class hierarchy from the locally-instantiable
+// `NodeObject` that `/ast/factory` exposes). The Remote classes live at
+// dist paths NOT listed in the package's `exports` map — we can't
+// `require` them by name. Instead we walk up the prototype chain from a
+// live Node sample to the topmost non-Object prototype (RemoteNodeBase)
+// and patch there. One-time; the chain shape is stable per tsgo version.
+//
+// Math: `getStart` = `pos` advanced past leading trivia (whitespace +
+// comments), `getEnd` = `end`, `getText` = `sf.text.slice(getStart, end)`.
+// tsgo's scanner emits standard TS trivia, so reusing real `ts.skipTrivia`
+// gives bit-identical positions to ts.Node.
+function patchTsgoNodeProto(sample: Node): void {
+	if (nodeProtoPatched) return;
+	let proto: any = Object.getPrototypeOf(sample);
+	while (proto && Object.getPrototypeOf(proto) !== Object.prototype) {
+		proto = Object.getPrototypeOf(proto);
+	}
+	if (!proto) {
+		throw new Error('tsgo backend: could not locate Node prototype to patch');
+	}
+	// `skipTrivia` is technically `@internal` in ts's published .d.ts but
+	// has been runtime-exported since 0.x — every linter / codemod tool
+	// uses it. The runtime check survives if a future ts removes it.
+	const skipTrivia = (ts as unknown as {
+		skipTrivia?: (
+			text: string,
+			pos: number,
+			stopAfterLineBreak?: boolean,
+			stopAtComments?: boolean,
+		) => number;
+	}).skipTrivia;
+	if (!skipTrivia) {
+		throw new Error('tsgo backend: ts.skipTrivia not available — getStart shim cannot be installed');
+	}
+	if (typeof proto.getStart !== 'function') {
+		proto.getStart = function (
+			sf?: { text: string },
+			includeJsDocComments?: boolean,
+		): number {
+			const text = (sf ?? this.getSourceFile()).text;
+			return skipTrivia(text, this.pos, false, includeJsDocComments);
+		};
+	}
+	if (typeof proto.getEnd !== 'function') {
+		proto.getEnd = function (): number {
+			return this.end;
+		};
+	}
+	if (typeof proto.getText !== 'function') {
+		proto.getText = function (sf?: { text: string }): string {
+			const file = sf ?? this.getSourceFile();
+			return file.text.slice(this.getStart(file), this.end);
+		};
+	}
+	if (typeof proto.getFullStart !== 'function') {
+		proto.getFullStart = function (): number {
+			return this.pos;
+		};
+	}
+	if (typeof proto.getFullText !== 'function') {
+		proto.getFullText = function (sf?: { text: string }): string {
+			const file = sf ?? this.getSourceFile();
+			return file.text.slice(this.pos, this.end);
+		};
+	}
+	if (typeof proto.getWidth !== 'function') {
+		proto.getWidth = function (sf?: { text: string }): number {
+			return this.end - this.getStart(sf);
+		};
+	}
+	if (typeof proto.getFullWidth !== 'function') {
+		proto.getFullWidth = function (): number {
+			return this.end - this.pos;
+		};
+	}
+	nodeProtoPatched = true;
+}
+
+export function createTsgoBackend(tsconfig: string): TsgoBackend {
+	// Lazy require so users without the optional peer dep don't crash on
+	// load. The CLI gates this behind `--tsgo` so non-tsgo users never
+	// reach here.
+	const { API: APICtor } = require('@typescript/native-preview/sync') as TsgoSync;
+	const ast: TsgoAst = require('@typescript/native-preview/ast');
+
+	const api: API = new APICtor({});
+	const snapshot: Snapshot = api.updateSnapshot({ openProject: tsconfig });
+	const project = snapshot.getProject(tsconfig);
+	if (!project) {
+		api.close();
+		throw new Error(`tsgo: project not found for ${tsconfig}`);
+	}
+
+	// Per-fileName Symbol cache, populated by `prepareFile`. Keyed by the
+	// tsgo Node object reference (not its position) — the AST tree is
+	// hydrated client-side and walks return the same Node instances each
+	// time within a snapshot.
+	const nodeToSymbol = new WeakMap<Node, TsgoSymbol | undefined>();
+	// Files prepass'd this snapshot. Skip re-walk on repeat lint() calls.
+	const preparedFiles = new Set<string>();
+
+	const program = wrapProgram(project, nodeToSymbol);
+	const idKind = ast.SyntaxKind.Identifier;
+
+	return {
+		getProgram: () => program,
+		prepareFile(fileName: string) {
+			if (preparedFiles.has(fileName)) return;
+			preparedFiles.add(fileName);
+			prepareFile(project, idKind, fileName, nodeToSymbol);
+		},
+		close() {
+			api.close();
+		},
+	};
+}
+
+function prepareFile(
+	project: Project,
+	idKind: number,
+	fileName: string,
+	nodeToSymbol: WeakMap<Node, TsgoSymbol | undefined>,
+): void {
+	const sf = project.program.getSourceFile(fileName);
+	if (!sf) return;
+
+	// Patch ts.Node-shape methods on tsgo's Remote{Node,SourceFile}
+	// prototype. Idempotent across calls and across snapshots.
+	patchTsgoNodeProto(sf);
+
+	// Local AST walk — no RPC. Collect every Identifier.
+	const ids: Node[] = [];
+	(function walk(n: Node) {
+		if (n.kind === idKind) ids.push(n);
+		n.forEachChild(walk);
+	})(sf);
+
+	if (ids.length === 0) return;
+
+	// Position-based batch resolves identifiers in declaration position
+	// (import/export specifier names, etc.) that the node-based API
+	// misses. Use end offset — caret-after-name semantics.
+	const positions = ids.map(id => id.end);
+	const symsByPos = project.checker.getSymbolAtPosition(fileName, positions);
+
+	// Fill from position-based result. For nulls, fall back to node-based
+	// (handles a small minority — object-spread method names etc.).
+	const fallbackIdx: number[] = [];
+	for (let i = 0; i < ids.length; i++) {
+		if (symsByPos[i]) {
+			nodeToSymbol.set(ids[i], symsByPos[i]);
+		} else {
+			fallbackIdx.push(i);
+		}
+	}
+	if (fallbackIdx.length > 0) {
+		const fallbackNodes = fallbackIdx.map(i => ids[i]);
+		const symsByNode = project.checker.getSymbolAtLocation(fallbackNodes);
+		for (let j = 0; j < fallbackIdx.length; j++) {
+			nodeToSymbol.set(ids[fallbackIdx[j]], symsByNode[j]);
+		}
+	}
+}
+
+// Wraps tsgo Program + Checker as a `ts.Program`-shape. Only the methods
+// tsslint actually consumes are populated; the rest throw on access so
+// any caller pulling on a missing capability fails loudly instead of
+// returning silent garbage.
+function wrapProgram(
+	project: Project,
+	nodeToSymbol: WeakMap<Node, TsgoSymbol | undefined>,
+): ts.Program {
+	const checker = wrapChecker(project, nodeToSymbol);
+	const cwd = path.dirname(project.configFileName);
+
+	// tsgo's lib files live inside the binary's own bundled stdlib. The
+	// path check looks at whether the SF path traces to a /lib.*.d.ts
+	// inside the tsgo executable's directory, the only place defaultlib
+	// SFs originate.
+	const isLib = (sf: ts.SourceFile) => {
+		const fn = sf.fileName;
+		return /\/lib\.[^/]+\.d\.ts$/.test(fn);
+	};
+
+	const stub = (name: string) => () => {
+		throw new Error(`tsgo backend: ts.Program.${name}() not implemented`);
+	};
+
+	const program: Partial<ts.Program> = {
+		getSourceFile(fileName: string) {
+			return project.program.getSourceFile(fileName) as unknown as ts.SourceFile | undefined;
+		},
+		getSourceFiles() {
+			// tsgo's Program doesn't expose all SFs in one call; pull via
+			// rootFiles plus their transitive deps. For the linter's
+			// purpose (cache-flow / BuilderProgram drain) this is fine —
+			// the hot path is per-file lookup.
+			const out: ts.SourceFile[] = [];
+			for (const fn of project.rootFiles) {
+				const sf = project.program.getSourceFile(fn);
+				if (sf) out.push(sf as unknown as ts.SourceFile);
+			}
+			return out;
+		},
+		getRootFileNames() {
+			return project.rootFiles as readonly string[];
+		},
+		getCurrentDirectory() {
+			return cwd;
+		},
+		getCompilerOptions() {
+			return project.compilerOptions as ts.CompilerOptions;
+		},
+		getTypeChecker() {
+			return checker;
+		},
+		isSourceFileDefaultLibrary: isLib,
+		isSourceFileFromExternalLibrary(sf: ts.SourceFile) {
+			return /\/node_modules\//.test(sf.fileName);
+		},
+		// Methods the linter never calls but ts.Program's interface
+		// declares. Stub them so a stray dynamic-typed access blows up
+		// with a clear message rather than `undefined is not a function`.
+		getSemanticDiagnostics: stub('getSemanticDiagnostics') as any,
+		getSyntacticDiagnostics: stub('getSyntacticDiagnostics') as any,
+		getDeclarationDiagnostics: stub('getDeclarationDiagnostics') as any,
+		getGlobalDiagnostics: stub('getGlobalDiagnostics') as any,
+		getConfigFileParsingDiagnostics: stub('getConfigFileParsingDiagnostics') as any,
+		emit: stub('emit') as any,
+	};
+
+	return program as ts.Program;
+}
+
+function wrapChecker(
+	project: Project,
+	nodeToSymbol: WeakMap<Node, TsgoSymbol | undefined>,
+): ts.TypeChecker {
+	const stub = (name: string) => () => {
+		throw new Error(`tsgo backend: ts.TypeChecker.${name}() not implemented`);
+	};
+
+	const checker: Partial<ts.TypeChecker> = {
+		getSymbolAtLocation(node: ts.Node) {
+			// Cache hit (prepass'd files) returns synchronously, no RPC.
+			// Cache miss falls through to a single RPC — covers nodes the
+			// rule discovered after the prepass (e.g. via type queries
+			// that returned a synthetic node).
+			const tsgoNode = node as unknown as Node;
+			if (nodeToSymbol.has(tsgoNode)) {
+				return nodeToSymbol.get(tsgoNode) as unknown as ts.Symbol | undefined;
+			}
+			const sym = project.checker.getSymbolAtLocation(tsgoNode);
+			nodeToSymbol.set(tsgoNode, sym);
+			return sym as unknown as ts.Symbol | undefined;
+		},
+		getTypeAtLocation(node: ts.Node) {
+			return project.checker.getTypeAtLocation(node as unknown as Node) as unknown as ts.Type;
+		},
+		getShorthandAssignmentValueSymbol(node: ts.Node | undefined) {
+			if (!node) return undefined;
+			return project.checker.getShorthandAssignmentValueSymbol(node as unknown as Node) as unknown as ts.Symbol | undefined;
+		},
+		getTypeOfSymbolAtLocation(symbol: ts.Symbol, location: ts.Node) {
+			return project.checker.getTypeOfSymbolAtLocation(
+				symbol as unknown as TsgoSymbol,
+				location as unknown as Node,
+			) as unknown as ts.Type;
+		},
+		// tsgo Checker doesn't expose getSymbolsInScope or
+		// getExportSpecifierLocalTargetSymbol. Stubbed for now —
+		// compat-eslint's two callsites need workarounds (the
+		// `arguments` symbol lookup and ExportSpecifier alias unwrap).
+		getSymbolsInScope: stub('getSymbolsInScope') as any,
+		getExportSpecifierLocalTargetSymbol: stub('getExportSpecifierLocalTargetSymbol') as any,
+	};
+
+	return checker as ts.TypeChecker;
+}
diff --git a/packages/cli/lib/worker.ts b/packages/cli/lib/worker.ts
index 767dc55..975bb75 100644
--- a/packages/cli/lib/worker.ts
+++ b/packages/cli/lib/worker.ts
@@ -10,6 +10,13 @@ import cacheFlow = require('./cache-flow.js');
 import incrementalState = require('./incremental-state.js');
 import type { FileCache } from './cache.js';
 import type { IncrementalState } from './incremental-state.js';
+import type { TsgoBackend } from './tsgo-backend.js';
+
+// `--tsgo` opts the worker into the @typescript/native-preview backend.
+// Detected once at module load — switching mid-run isn't supported (the
+// backend owns the spawned tsgo process and its snapshot ref-graph).
+const useTsgo = process.argv.includes('--tsgo');
+let tsgoBackend: TsgoBackend | undefined;
 
 // Fallback if `ts.sys.createHash` is undefined on this host (Node ≥ 22.6
 // always provides it via crypto, but the type is optional). sha256 hex.
@@ -252,6 +259,32 @@ async function setup(
 
 	const plugins = await languagePlugins.load(tsconfig, languages);
 	fileNames = _fileNames;
+
+	if (useTsgo) {
+		// Validate compatibility. The tsgo backend currently lacks two
+		// pieces master assumes: (1) Volar host injection, so language
+		// plugins (Vue / MDX / Astro / etc.) can't virtualise script
+		// content; (2) BuilderProgram JS API, so layer-2 affected-file
+		// classification is unavailable.
+		if (plugins.length) {
+			return 'tsgo backend does not yet support --vue-project / --mdx-project / --astro-project / --vue-vine-project / --ts-macro-project';
+		}
+		// Layer 2 is disabled — every file is treated as "affected" so
+		// cached type-aware entries are re-validated rather than served
+		// from a stale snapshot. No BuilderProgram drain runs.
+		affectedFiles = new Set();
+		tsgoBackend?.close();
+		tsgoBackend = require('./tsgo-backend.js').createTsgoBackend(tsconfig) as TsgoBackend;
+		linter = core.createLinter(
+			{ typescript: ts, program: tsgoBackend.getProgram },
+			path.dirname(configFile),
+			config,
+			() => [],
+			initialTypeAwareRules,
+		);
+		return true;
+	}
+
 	// Internal API path: BuilderProgram.emitBuildInfo only produces
 	// content when these options are set. Override the user's values
 	// (their own tsc --incremental builds shouldn't share this file).
@@ -369,6 +402,14 @@ function lint(fileName: string, fix: boolean, fileCache: FileCache, fileMtime: n
 	let diagnostics!: ts.DiagnosticWithLocation[];
 	let shouldCheck = true;
 
+	if (tsgoBackend) {
+		// Per-file batched-symbol prepass. Walks the SF locally, resolves
+		// every Identifier in one IPC, populates the adapter's
+		// `nodeToSymbol` cache. Idempotent — repeat calls for the same
+		// file return immediately.
+		tsgoBackend.prepareFile(fileName);
+	}
+
 	// Layer 2 signals. `incremental` is always true under the CLI now —
 	// `--force` opts out by clearing the loaded cache instead.
 	//   typeAwareUnaffected: file's deps haven't moved since prev session,
diff --git a/packages/cli/package.json b/packages/cli/package.json
index caac3ce..3c1f16d 100644
--- a/packages/cli/package.json
+++ b/packages/cli/package.json
@@ -30,6 +30,12 @@
 		"minimatch": "^10.0.1"
 	},
 	"peerDependencies": {
-		"typescript": "*"
+		"typescript": "*",
+		"@typescript/native-preview": "*"
+	},
+	"peerDependenciesMeta": {
+		"@typescript/native-preview": {
+			"optional": true
+		}
 	}
 }
diff --git a/packages/cli/test/tsgo-backend.test.ts b/packages/cli/test/tsgo-backend.test.ts
new file mode 100644
index 0000000..35dafc1
--- /dev/null
+++ b/packages/cli/test/tsgo-backend.test.ts
@@ -0,0 +1,154 @@
+// End-to-end test for the tsgo backend adapter. Spawns tsgo via the
+// API, builds a Project on packages/compat-eslint (real-world type-heavy
+// code), and validates that the adapter:
+//
+//   1. Hands back a SourceFile via getProgram().getSourceFile() —
+//      structurally compatible enough to be walked + queried like a
+//      ts.SourceFile (kind / parent / pos / end / forEachChild).
+//   2. After prepareFile(), getSymbolAtLocation() returns Symbols for
+//      identifiers — including import/export specifier names that
+//      `getSymbolAtLocation` alone misses (the position-based fallback).
+//   3. Symbol identity collapses across multiple references to the same
+//      logical entity — proves Map<Symbol, X> patterns (compat-eslint's
+//      `variableBySymbol`) work without modification.
+//   4. close() actually tears down the child process.
+//
+// Skip when @typescript/native-preview isn't installed — the adapter is
+// behind an optional peer dep, so CI that doesn't pull it in must not
+// fail.
+//
+// Run via:
+//   node packages/cli/test/tsgo-backend.test.js
+
+import * as path from 'path';
+import * as fs from 'fs';
+
+const failures: string[] = [];
+function check(name: string, cond: boolean, detail?: string) {
+	if (cond) {
+		process.stdout.write('.');
+	}
+	else {
+		failures.push(name + (detail ? ' — ' + detail : ''));
+		process.stdout.write('F');
+	}
+}
+
+// Skip if optional peer not present.
+try {
+	require.resolve('@typescript/native-preview/sync');
+}
+catch {
+	console.log('skip: @typescript/native-preview not installed');
+	console.log('OK');
+	process.exit(0);
+}
+
+const repoRoot = path.resolve(__dirname, '../../..');
+const tsconfig = path.join(repoRoot, 'packages/compat-eslint/tsconfig.json');
+const target = path.join(repoRoot, 'packages/compat-eslint/index.ts');
+
+if (!fs.existsSync(tsconfig)) {
+	console.log('skip: compat-eslint tsconfig missing');
+	console.log('OK');
+	process.exit(0);
+}
+
+const backend = require('../lib/tsgo-backend.js') as typeof import('../lib/tsgo-backend.js');
+const handle = backend.createTsgoBackend(tsconfig);
+
+try {
+	const program = handle.getProgram();
+
+	// ── Test 1: SourceFile fetched ────────────────────────────────────────
+	const sf = program.getSourceFile(target);
+	check('getSourceFile returns target SF', !!sf);
+	if (!sf) throw new Error('SF missing — abort');
+	check('SF.fileName matches', sf.fileName === target);
+	check('SF.text non-empty', typeof sf.text === 'string' && sf.text.length > 1000);
+
+	// ── Test 2: prepareFile populates the symbol cache ───────────────────
+	handle.prepareFile(target);
+
+	// SyntaxKind values for tsgo differ from ts (offsets shifted by ≥1
+	// across enum revisions). We don't have tsgo's enum imported here —
+	// instead probe by frequency: Identifier is the most-frequent kind
+	// in any real TS file, by a comfortable margin over the next.
+	const counts = new Map<number, number>();
+	(function scan(n: any) {
+		counts.set(n.kind, (counts.get(n.kind) ?? 0) + 1);
+		n.forEachChild(scan);
+	})(sf);
+	const idKind = [...counts.entries()].sort((a, b) => b[1] - a[1])[0][0];
+
+	const checker = program.getTypeChecker();
+	let idCount = 0;
+	let resolved = 0;
+	let importSpecifierResolved = 0; // the case getSymbolAtLocation alone misses
+	(function walk(n: any) {
+		if (n.kind === idKind) {
+			idCount++;
+			const sym = checker.getSymbolAtLocation(n);
+			if (sym) {
+				resolved++;
+				if (n.pos < 1500) importSpecifierResolved++; // top-of-file imports
+			}
+		}
+		n.forEachChild(walk);
+	})(sf);
+
+	check('Identifiers found', idCount > 1000, `count=${idCount}`);
+	check('high resolve rate (>95%)', resolved / idCount > 0.95, `resolved=${resolved}/${idCount} (${(resolved / idCount * 100).toFixed(1)}%)`);
+	check('top-of-file imports resolved', importSpecifierResolved > 5, `count=${importSpecifierResolved}`);
+
+	// ── Test 3: Symbol identity collapses across references ──────────────
+	const seen = new Map<string, number>();
+	(function walk(n: any) {
+		if (n.kind === idKind) {
+			const sym = checker.getSymbolAtLocation(n) as { id?: string } | undefined;
+			if (sym?.id) {
+				seen.set(sym.id, (seen.get(sym.id) ?? 0) + 1);
+			}
+		}
+		n.forEachChild(walk);
+	})(sf);
+	const maxOccurrences = Math.max(...seen.values());
+	check('Symbol identity collapses (some symbol used many times)', maxOccurrences > 10, `max occurrences for any symbol id: ${maxOccurrences}`);
+	check('Symbol id space is bounded', seen.size < idCount, `unique symbols=${seen.size} < idCount=${idCount}`);
+
+	// ── Test 4: rule-level identity compatibility ────────────────────────
+	// Pre-3.2 rules used Map<ts.Symbol, X>. Post-adapter, the Symbol is
+	// a tsgo Symbol object — but Map keying works on object identity, and
+	// tsgo's Symbol instances are stable across calls within a snapshot.
+	let firstId: any;
+	const symbolMap = new Map<any, number>();
+	(function walk(n: any) {
+		if (n.kind === idKind) {
+			const sym = checker.getSymbolAtLocation(n);
+			if (sym) {
+				if (!firstId) firstId = sym;
+				symbolMap.set(sym, (symbolMap.get(sym) ?? 0) + 1);
+			}
+		}
+		n.forEachChild(walk);
+	})(sf);
+	check('Map<Symbol, …> populated', symbolMap.size > 100);
+	check('first symbol retrievable from Map', symbolMap.has(firstId));
+
+	// ── Test 5: program.getCurrentDirectory() / getCompilerOptions() ─────
+	const cwd = program.getCurrentDirectory();
+	check('cwd is project dir', cwd === path.dirname(tsconfig));
+	const opts = program.getCompilerOptions();
+	check('compilerOptions returned', opts && typeof opts === 'object');
+}
+finally {
+	handle.close();
+}
+
+process.stdout.write('\n');
+if (failures.length) {
+	console.error(`\n${failures.length} failure(s):`);
+	for (const f of failures) console.error('  - ' + f);
+	process.exit(1);
+}
+console.log('OK');
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 2b9d00a..eada883 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -98,6 +98,9 @@ importers:
       '@tsslint/types':
         specifier: 3.1.1
         version: link:../types
+      '@typescript/native-preview':
+        specifier: '*'
+        version: 7.0.0-dev.20260504.1
       '@volar/language-core':
         specifier: ~2.4.0
         version: 2.4.28
@@ -1126,6 +1129,53 @@ packages:
     resolution: {integrity: sha512-LdDNl6C5iJExcM0Yh0PwAIBb9PrSiCsWamF/JyEZawm3kFDnRoaq3LGE4bpyRao/fWeGKKyw7icx0YxrLFC5Cg==}
     engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0}
 
+  '@typescript/native-preview-darwin-arm64@7.0.0-dev.20260504.1':
+    resolution: {integrity: sha512-+Qs1Q7Qxfp11n/hU3pweFU+EQ37FnDsdWOOxb7/vCy8QGBysrLUUYRhQ+GSW3s663oMtN6+9Kf82hk3ZT+kXlg==}
+    engines: {node: '>=16.20.0'}
+    cpu: [arm64]
+    os: [darwin]
+
+  '@typescript/native-preview-darwin-x64@7.0.0-dev.20260504.1':
+    resolution: {integrity: sha512-Wr3GWTRiMgibmhe88cjQ612ZyY7sbgsPYEaWKGPUxBaXtMHFIzgTBIoJMuaQqQx4GEJs6AUDyhnIHG1gx4rJjg==}
+    engines: {node: '>=16.20.0'}
+    cpu: [x64]
+    os: [darwin]
+
+  '@typescript/native-preview-linux-arm64@7.0.0-dev.20260504.1':
+    resolution: {integrity: sha512-y1Qai5l55Sl+/3B0hyQtvynq//C22BKFH3CfU35fbLYUo4P/ISUycyAbcA+PAPazpDFO3E56I96QUQrbJL2VVA==}
+    engines: {node: '>=16.20.0'}
+    cpu: [arm64]
+    os: [linux]
+
+  '@typescript/native-preview-linux-arm@7.0.0-dev.20260504.1':
+    resolution: {integrity: sha512-s8QkhZe0M4QD2xhK1Xiy2JUQv1AOl8kUg5DLx1G8ws0f1BK/oKyqDNbxhZMGINYLFvkjpr9lOxt7qehSnpJMYQ==}
+    engines: {node: '>=16.20.0'}
+    cpu: [arm]
+    os: [linux]
+
+  '@typescript/native-preview-linux-x64@7.0.0-dev.20260504.1':
+    resolution: {integrity: sha512-ngN3Ie3Vin6pFtqeNywxm86RTxgI0Fo0GZyJ1PxokLES8J3xfMPtMYfv85c/+5uz5+7T+m4LRLyY5IoLY4gtuw==}
+    engines: {node: '>=16.20.0'}
+    cpu: [x64]
+    os: [linux]
+
+  '@typescript/native-preview-win32-arm64@7.0.0-dev.20260504.1':
+    resolution: {integrity: sha512-/GZDJN/CsLbqIe7EdWDkXhNX9C41VjemBeUN6+9ckvEFLH8XyKTmXPYikNOn0N819M1KSeNZltplyUslfROOdw==}
+    engines: {node: '>=16.20.0'}
+    cpu: [arm64]
+    os: [win32]
+
+  '@typescript/native-preview-win32-x64@7.0.0-dev.20260504.1':
+    resolution: {integrity: sha512-EYQBdVZq4xIzhTtKxw6wvee9238hEb7XrPG413AEZBD3kcR3qqvPULXsPzQyEpneCReATSaihscP/LfhMQYUmA==}
+    engines: {node: '>=16.20.0'}
+    cpu: [x64]
+    os: [win32]
+
+  '@typescript/native-preview@7.0.0-dev.20260504.1':
+    resolution: {integrity: sha512-bHFGxyIU83qjj6ywn3817A+Ug2ZID0GiBA5WFdbc/T7EjcrKnUUylexq0fU81N/mTbfw3FyP6ZCEdO2Ntcl/VQ==}
+    engines: {node: '>=16.20.0'}
+    hasBin: true
+
   '@typespec/ts-http-runtime@0.3.5':
     resolution: {integrity: sha512-yURCknZhvywvQItHMMmFSo+fq5arCUIyz/CVk7jD89MSai7dkaX8ufjCWp3NttLojoTVbcE72ri+be/TnEbMHw==}
     engines: {node: '>=20.0.0'}
@@ -4605,6 +4655,37 @@ snapshots:
       '@typescript-eslint/types': 8.59.1
       eslint-visitor-keys: 5.0.1
 
+  '@typescript/native-preview-darwin-arm64@7.0.0-dev.20260504.1':
+    optional: true
+
+  '@typescript/native-preview-darwin-x64@7.0.0-dev.20260504.1':
+    optional: true
+
+  '@typescript/native-preview-linux-arm64@7.0.0-dev.20260504.1':
+    optional: true
+
+  '@typescript/native-preview-linux-arm@7.0.0-dev.20260504.1':
+    optional: true
+
+  '@typescript/native-preview-linux-x64@7.0.0-dev.20260504.1':
+    optional: true
+
+  '@typescript/native-preview-win32-arm64@7.0.0-dev.20260504.1':
+    optional: true
+
+  '@typescript/native-preview-win32-x64@7.0.0-dev.20260504.1':
+    optional: true
+
+  '@typescript/native-preview@7.0.0-dev.20260504.1':
+    optionalDependencies:
+      '@typescript/native-preview-darwin-arm64': 7.0.0-dev.20260504.1
+      '@typescript/native-preview-darwin-x64': 7.0.0-dev.20260504.1
+      '@typescript/native-preview-linux-arm': 7.0.0-dev.20260504.1
+      '@typescript/native-preview-linux-arm64': 7.0.0-dev.20260504.1
+      '@typescript/native-preview-linux-x64': 7.0.0-dev.20260504.1
+      '@typescript/native-preview-win32-arm64': 7.0.0-dev.20260504.1
+      '@typescript/native-preview-win32-x64': 7.0.0-dev.20260504.1
+
   '@typespec/ts-http-runtime@0.3.5':
     dependencies:
       http-proxy-agent: 7.0.2

From 7ce6c744102687b0303b29efc815afc38d53827c Mon Sep 17 00:00:00 2001
From: Johnson Chu <johnsoncodehk@gmail.com>
Date: Mon, 4 May 2026 22:27:05 +0800
Subject: [PATCH 03/19] =?UTF-8?q?cli:=20typescript-module=20facade=20for?=
 =?UTF-8?q?=20--tsgo=20=E2=80=94=20rules=20fire,=20kind=20values=20align?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Validation fixture (a single `import { Foo } from './foo'` where Foo is
type-only): @typescript-eslint/consistent-type-imports rule now fires on
tsgo path with the same diagnostic text + range as ts.Program path.

The mechanism — why a facade and not in-place mutation:

Rule code (compat-eslint, typescript-eslint utilities, custom rules)
binds `ts` once at module load: `const ts = require('typescript')`. Every
`ts.SyntaxKind.X` / `ts.isXxx(node)` / `ts.forEachChild(node, cb)` call
inside that module dispatches against that bound module's enum values
and type-guard functions. tsgo Node.kind=79 (Identifier); real
ts.SyntaxKind.Identifier=80 → dispatch tables miss → silent no-op.

We can't mutate ts.SyntaxKind in place: the worker / cache-flow / core
imported ts BEFORE setup() runs and need real ts internals (skipTrivia,
createSemanticDiagnosticsBuilderProgram, …) keyed by real ts values.

Selective substitution: install a facade in `Module._cache` AFTER the
worker's module-load `import ts = require('typescript')` has bound real
ts, BUT BEFORE the dynamic `import(configFile)` pulls in compat-eslint
and rules. Those late-loaded modules see tsgo's enums + type guards via
the facade; the worker keeps its real ts reference intact.

Implementation (lib/tsgo-typescript-facade.ts):
- Build facade as a plain object. Copy every own-property of real ts
  first (so CJS interop helpers like tslib's `__importStar`, which iterate
  `Object.getOwnPropertyNames(mod)` and miss prototype-inherited fallbacks,
  still see complete shape — typescript-estree crashes on `ts.Extension`
  otherwise). Overlay tsgo's enums (SyntaxKind, NodeFlags, ModifierFlags,
  ScriptKind, ScriptTarget, TokenFlags, …), all type guards from /ast/is,
  visitor helpers, factory namespace, and tsgo-only enums (SymbolFlags,
  TypeFlags, DiagnosticCategory) from /api/sync.
- Free-function `forEachChild(node, cb, cbNodes?)` wraps tsgo Node's own
  `.forEachChild` method (rule code expects free-function shape).
- Sentinel `__tsgoFacade__: true` for debugging.

`installFacade()` (lib/tsgo-typescript-facade.ts):
- Pnpm-aware: tsgo + tsslint + tsslint-eslint each pull in typescript via
  their own resolution chains, all landing on different physical paths in
  `.pnpm/`. Cache-slot substitution via `Module._cache[require.resolve('typescript')]`
  alone covers our cwd's slot, not the others. Instead route every
  `require('typescript')` to a single canonical synthetic id by overriding
  `Module._resolveFilename`, then prime that one cache slot.
- Idempotent — second call short-circuits.

Worker integration (lib/worker.ts):
- `if (useTsgo) require('./tsgo-typescript-facade.js').installFacade()`
  runs at top of setup(), before `await import(configFile)`.

State on full repo:
- 11/59 files pass through tsgo path; 48 files now crash with a different,
  more advanced gap inside compat-eslint's ts-ast-scan (next iteration).
- Validation fixture: rule fires, diagnostic matches.
- Existing tests unchanged: program-host (17), cache-flow (50),
  meta-frameworks (8), tsgo-backend (12).
---
 packages/cli/lib/tsgo-typescript-facade.ts | 181 +++++++++++++++++++++
 packages/cli/lib/worker.ts                 |   9 +
 2 files changed, 190 insertions(+)
 create mode 100644 packages/cli/lib/tsgo-typescript-facade.ts

diff --git a/packages/cli/lib/tsgo-typescript-facade.ts b/packages/cli/lib/tsgo-typescript-facade.ts
new file mode 100644
index 0000000..6f4322d
--- /dev/null
+++ b/packages/cli/lib/tsgo-typescript-facade.ts
@@ -0,0 +1,181 @@
+// `typescript` module facade for the --tsgo path. Substituted into
+// `Module._cache[require.resolve('typescript')]` before tsslint config
+// loads, so all rule code (compat-eslint, ESLint utility ports, custom
+// rules) sees tsgo's enums, type guards, and walkers when it does
+// `require('typescript')` / `import * as ts from 'typescript'`.
+//
+// This is selective: the worker / cache-flow / core consumed `ts.X` at
+// module load time, before `--tsgo` substitution kicks in, so they keep
+// the real ts for things tsgo doesn't expose (skipTrivia,
+// createSemanticDiagnosticsBuilderProgram, parseJsonConfigFileContent,
+// etc.). Only later-loaded code (the dynamic `import(configFile)` inside
+// setup() and everything it transitively pulls in) gets this facade.
+//
+// Why facade vs in-place mutation: `ts.SyntaxKind.Identifier` etc. need
+// tsgo's offset values for rule-side comparisons to hit, but the
+// worker's already-bound `ts.skipTrivia` etc. need the real ts.SyntaxKind
+// internally. A separate module object satisfies both.
+
+import ts = require('typescript');
+
+interface TsgoModules {
+	ast: any; // /ast — SyntaxKind, NodeFlags, all is.* guards, visitor, utils, scanner
+	factory: any; // /ast/factory — node creation helpers + NodeObject
+	sync: any; // /api/sync — SymbolFlags, TypeFlags, DiagnosticCategory, ...
+}
+
+function loadTsgoModules(): TsgoModules {
+	return {
+		ast: require('@typescript/native-preview/ast'),
+		factory: require('@typescript/native-preview/ast/factory'),
+		sync: require('@typescript/native-preview/sync'),
+	};
+}
+
+// Build a facade that mimics `typeof typescript`. Properties tsgo
+// supplies route to tsgo; everything else falls back to real ts so the
+// worker-internal calls keep working when accidental cross-imports happen.
+export function createTypescriptFacade(): typeof ts {
+	const tsgo = loadTsgoModules();
+	const { ast, factory, sync } = tsgo;
+
+	// Free-function `forEachChild` shape compat-eslint / typescript-eslint
+	// expect: `ts.forEachChild(node, cbNode, cbNodes?)`. tsgo nodes carry
+	// the method themselves; just delegate.
+	const forEachChild = function (node: any, cbNode: any, cbNodes?: any) {
+		if (node && typeof node.forEachChild === 'function') {
+			return node.forEachChild(cbNode, cbNodes);
+		}
+		// Fall back to real ts for non-tsgo nodes (shouldn't happen on
+		// this path, but cheap insurance).
+		return (ts as any).forEachChild(node, cbNode, cbNodes);
+	};
+
+	// Free-function `getTokenAtPosition`-style helpers and a few of the
+	// most-used ts.* utilities don't exist in tsgo's exports. Pass through
+	// to real ts and accept the kind-mismatch fallout — flag them as gaps.
+
+	// Plain object copy of ts. Why not `Object.create(ts)` (prototype
+	// chain) or `Object.assign({}, ts)` (single shallow copy)?
+	//
+	// CJS interop helpers like tslib's `__importStar` iterate
+	// `Object.getOwnPropertyNames(mod)` — they consume only OWN
+	// properties, so prototype-inherited fallbacks are invisible to them.
+	// typescript-estree compiles `import * as ts from 'typescript'` into
+	// `__importStar(require('typescript'))`, so the consuming module sees
+	// a snapshot built only from our own keys. Anything we don't own
+	// (and don't surface as own) ends up `undefined` downstream — e.g.
+	// `ts.Extension` → `undefined.Cjs` crash from the user's stack.
+	//
+	// So: copy every ts own-property up front. Some are getters; reading
+	// them triggers the getter and gives us the value. Then overlay tsgo's
+	// values — `SyntaxKind`, type guards, etc. — on top.
+	const facade: any = {};
+	for (const k of Object.getOwnPropertyNames(ts)) {
+		try {
+			facade[k] = (ts as any)[k];
+		}
+		catch {
+			// Some ts internals throw on access (rare; defensive).
+		}
+	}
+
+	// Enums from /ast (already aggregated): SyntaxKind, NodeFlags,
+	// ModifierFlags, ScriptKind, ScriptTarget, TokenFlags, LanguageVariant,
+	// RegularExpressionFlags, CommentDirectiveType, CharacterCodes.
+	// Plus: all `is.*` predicates, visitor (visitNode/visitNodes/visitEachChild),
+	// scanner, AST utils.
+	for (const k of Object.keys(ast)) {
+		facade[k] = ast[k];
+	}
+
+	// Enums from /api/sync that aren't in /ast: SymbolFlags, TypeFlags,
+	// ObjectFlags, ElementFlags, SignatureKind, SignatureFlags,
+	// NodeBuilderFlags, TypePredicateKind, DiagnosticCategory.
+	for (const k of Object.keys(sync)) {
+		// Skip API-level classes (API, Snapshot, Project, Program, Checker)
+		// — those aren't typescript-module shape; only enum values are
+		// useful here. Enums are objects with both numeric and reverse
+		// string keys.
+		const v = sync[k];
+		if (typeof v !== 'object' || v === null) continue;
+		// Heuristic: enum-shaped object has at least one numeric value.
+		const hasNumeric = Object.values(v).some(x => typeof x === 'number');
+		if (!hasNumeric) continue;
+		// Don't clobber if already supplied by /ast.
+		if (k in facade) continue;
+		facade[k] = v;
+	}
+
+	// /ast/factory exports `factory` namespace + creation helpers. Real ts
+	// rule code uses `ts.factory.createX(...)` for code-fix output. Wire
+	// the namespace through.
+	if (factory.factory) {
+		facade.factory = factory.factory;
+	}
+	// Free-function `createX` + `updateX` from factory module too.
+	for (const k of Object.keys(factory)) {
+		if (k === 'factory' || k === 'NodeObject') continue;
+		if (typeof factory[k] !== 'function') continue;
+		if (k in facade && !k.startsWith('create')) continue;
+		facade[k] = factory[k];
+	}
+
+	// `forEachChild` override — must come AFTER /ast spread (which may
+	// already export it; tsgo's `/ast/visitor` exports `visitEachChild`
+	// not `forEachChild`). We add the free-function form rule code expects.
+	facade.forEachChild = forEachChild;
+
+	// Sentinel marker so the worker can detect this isn't real ts when
+	// debugging cache-substitution issues.
+	facade.__tsgoFacade__ = true;
+
+	return facade as typeof ts;
+}
+
+// Install the facade so `require('typescript')` returns it from anywhere
+// in the dependency graph — including transitive dependencies that pnpm
+// resolves to a sibling typescript instance under `.pnpm/typescript@x.y`.
+// Cache-slot substitution alone misses those because they're keyed by a
+// different absolute path than `require.resolve('typescript')` from our
+// cwd. We override `Module._resolveFilename` so every literal
+// `'typescript'` request resolves to a single canonical id, then prime
+// that one cache slot with the facade.
+//
+// Limitations: does NOT intercept resolutions like
+// `require('typescript/lib/typescript')` (literal subpath) — those keep
+// the real ts. That's intentional: anything reaching for an internal
+// path probably wants real ts implementation, not enum re-routing.
+export function installFacade(): typeof ts {
+	const Module = require('module') as any;
+	const FACADE_ID = '@tsslint-tsgo-facade';
+	if (Module._cache[FACADE_ID]?.exports?.__tsgoFacade__) {
+		return Module._cache[FACADE_ID].exports;
+	}
+	const facade = createTypescriptFacade();
+	// Synthetic cache entry — not a real disk path, but Node's loader
+	// only consults `_cache[id]` when looking up an already-resolved
+	// module, so any string id is fine as long as the slot exists.
+	const wrapper = new Module(FACADE_ID, null);
+	wrapper.id = FACADE_ID;
+	wrapper.filename = FACADE_ID;
+	wrapper.loaded = true;
+	wrapper.exports = facade;
+	Module._cache[FACADE_ID] = wrapper;
+
+	// Resolve hook — must be installed AFTER the facade is in cache so
+	// the very first `require('typescript')` after this point hits the
+	// facade slot.
+	const origResolve = Module._resolveFilename;
+	Module._resolveFilename = function (
+		request: string,
+		parent: unknown,
+		...rest: unknown[]
+	) {
+		if (request === 'typescript') {
+			return FACADE_ID;
+		}
+		return origResolve.call(this, request, parent, ...rest);
+	};
+	return facade;
+}
diff --git a/packages/cli/lib/worker.ts b/packages/cli/lib/worker.ts
index 975bb75..63ffc64 100644
--- a/packages/cli/lib/worker.ts
+++ b/packages/cli/lib/worker.ts
@@ -226,6 +226,15 @@ async function setup(
 	initialTypeAwareRules: readonly string[],
 	prevIncrementalState: IncrementalState | undefined,
 ): Promise<true | string> {
+	if (useTsgo) {
+		// Install the tsgo `typescript` facade BEFORE loading tsslint
+		// config — config + compat-eslint + rules will then `require('typescript')`
+		// and get tsgo enums + type guards + walkers, so kind-value
+		// comparisons line up with tsgo Node objects. Idempotent across
+		// setup() calls (first install wins; subsequent ones short-circuit).
+		require('./tsgo-typescript-facade.js').installFacade();
+	}
+
 	let config: config.Config | config.Config[];
 	try {
 		config = (await import(url.pathToFileURL(configFile).toString())).default;

From d36aa201f482f7f823d02607e35f2c99ae087057 Mon Sep 17 00:00:00 2001
From: Johnson Chu <johnsoncodehk@gmail.com>
Date: Mon, 4 May 2026 22:31:45 +0800
Subject: [PATCH 04/19] cli: tsgo Type prototype shim (isLiteral / isUnion /
 etc.) + soft Checker stubs
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Two surgical follow-ups after the facade landed:

1. Type prototype patches. typescript-eslint's no-unnecessary-type-assertion
   (and several compat-eslint paths) call `type.isLiteral()` /
   `type.isStringLiteral()` / `type.isUnion()` / `type.getFlags()` etc.
   ts.Type provides these as instance methods on its prototype. tsgo's
   TypeObject only exposes data fields + `getSymbol()`.

   Patch the missing predicates onto tsgo's TypeObject prototype, located
   by walking up from a sample Type the first time `getTypeAtLocation`
   returns one (TypeObject isn't in the package exports map). Predicates
   close over tsgo's TypeFlags enum at patch time — flag values differ
   from ts.TypeFlags, so we can't blanket-copy ts.Type prototype methods
   (their hardcoded flag constants would mis-mask).

2. `getSymbolsInScope` / `getExportSpecifierLocalTargetSymbol` change
   from throwing to returning safe defaults (`[]` / `undefined`).
   compat-eslint's two callsites (parameter-property shadowing,
   ExportSpecifier alias unwrap) have fallback paths that handle empties
   gracefully — degrades scope-manager precision in those edges but the
   pipeline keeps moving. Methods that *would* produce wrong diagnostics
   on no-op stay throwing (`getBaseConstraintOfType`, `getApparentType`,
   `getContextualType`).

Status: 12 files pass through tsgo path on the full repo (was 11). Next
gaps surface concretely:
  - `Symbol.declarations[i].getSourceFile is not a function` —
    `declarations` on tsgo Symbol is `NodeHandle[]`, not `Node[]`
  - `scanner.setTextPos is not a function` — tsgo Scanner shape diff

Existing tests unchanged.
---
 packages/cli/lib/tsgo-backend.ts | 71 ++++++++++++++++++++++++++++----
 1 file changed, 62 insertions(+), 9 deletions(-)

diff --git a/packages/cli/lib/tsgo-backend.ts b/packages/cli/lib/tsgo-backend.ts
index 0e24dda..14dd75d 100644
--- a/packages/cli/lib/tsgo-backend.ts
+++ b/packages/cli/lib/tsgo-backend.ts
@@ -51,9 +51,10 @@ export interface TsgoBackend {
 	close(): void;
 }
 
-// Process-level guard so we patch the tsgo Node prototype exactly once,
-// even if multiple backends spin up in the same worker.
+// Process-level guards. Both prototype patches are one-shot per process
+// (tsgo's class shape is stable per binary version).
 let nodeProtoPatched = false;
+let typeProtoPatched = false;
 
 // tsgo's Node interface exposes `pos` / `end` (raw parser offsets,
 // leading trivia included), `parent`, `kind`, `forEachChild`,
@@ -142,6 +143,44 @@ function patchTsgoNodeProto(sample: Node): void {
 	nodeProtoPatched = true;
 }
 
+// `ts.Type` exposes a clutch of flag-based predicates as instance
+// methods (`isLiteral`, `isStringLiteral`, `isUnion`, `getSymbol`, …).
+// Rule code (typescript-eslint's `no-unnecessary-type-assertion`,
+// many compat-eslint paths) calls these. tsgo's TypeObject only has
+// `getSymbol` and the data fields; we patch the missing predicates onto
+// its prototype using tsgo's TypeFlags enum values (different from ts).
+//
+// Located via prototype walk from a sample Type — TypeObject isn't in
+// the package exports map. One-shot per process.
+function patchTsgoTypeProto(sample: object, sync: TsgoSync): void {
+	if (typeProtoPatched) return;
+	let proto: any = Object.getPrototypeOf(sample);
+	while (proto && Object.getPrototypeOf(proto) !== Object.prototype) {
+		proto = Object.getPrototypeOf(proto);
+	}
+	if (!proto) return;
+	const TF = (sync as any).TypeFlags as Record<string, number>;
+	const has = (flag: number) => function (this: { flags: number }) { return (this.flags & flag) !== 0; };
+	if (!proto.isStringLiteral) proto.isStringLiteral = has(TF.StringLiteral);
+	if (!proto.isNumberLiteral) proto.isNumberLiteral = has(TF.NumberLiteral);
+	if (!proto.isBooleanLiteral) proto.isBooleanLiteral = has(TF.BooleanLiteral);
+	if (!proto.isBigIntLiteral) proto.isBigIntLiteral = has(TF.BigIntLiteral);
+	if (!proto.isEnumLiteral) proto.isEnumLiteral = has(TF.EnumLiteral);
+	if (!proto.isLiteral) proto.isLiteral = has(
+		TF.StringLiteral | TF.NumberLiteral | TF.BigIntLiteral | TF.BooleanLiteral,
+	);
+	if (!proto.isUnion) proto.isUnion = has(TF.Union);
+	if (!proto.isIntersection) proto.isIntersection = has(TF.Intersection);
+	if (!proto.isUnionOrIntersection) proto.isUnionOrIntersection = has(TF.UnionOrIntersection ?? (TF.Union | TF.Intersection));
+	if (!proto.isTypeParameter) proto.isTypeParameter = has(TF.TypeParameter);
+	if (!proto.isClassOrInterface) proto.isClassOrInterface = function () { return false; }; // structural; would need objectFlags
+	if (!proto.isClass) proto.isClass = function () { return false; };
+	if (!proto.isIndexType) proto.isIndexType = has(TF.Index);
+	if (!proto.getFlags) proto.getFlags = function (this: { flags: number }) { return this.flags; };
+	if (!proto.isNullableType) proto.isNullableType = has((TF.Null ?? 0) | (TF.Undefined ?? 0));
+	typeProtoPatched = true;
+}
+
 export function createTsgoBackend(tsconfig: string): TsgoBackend {
 	// Lazy require so users without the optional peer dep don't crash on
 	// load. The CLI gates this behind `--tsgo` so non-tsgo users never
@@ -302,9 +341,14 @@ function wrapChecker(
 	project: Project,
 	nodeToSymbol: WeakMap<Node, TsgoSymbol | undefined>,
 ): ts.TypeChecker {
+	const sync = require('@typescript/native-preview/sync') as TsgoSync;
 	const stub = (name: string) => () => {
 		throw new Error(`tsgo backend: ts.TypeChecker.${name}() not implemented`);
 	};
+	const fixupType = (t: unknown) => {
+		if (t && typeof t === 'object') patchTsgoTypeProto(t, sync);
+		return t;
+	};
 
 	const checker: Partial<ts.TypeChecker> = {
 		getSymbolAtLocation(node: ts.Node) {
@@ -321,7 +365,9 @@ function wrapChecker(
 			return sym as unknown as ts.Symbol | undefined;
 		},
 		getTypeAtLocation(node: ts.Node) {
-			return project.checker.getTypeAtLocation(node as unknown as Node) as unknown as ts.Type;
+			const t = project.checker.getTypeAtLocation(node as unknown as Node);
+			fixupType(t);
+			return t as unknown as ts.Type;
 		},
 		getShorthandAssignmentValueSymbol(node: ts.Node | undefined) {
 			if (!node) return undefined;
@@ -333,12 +379,19 @@ function wrapChecker(
 				location as unknown as Node,
 			) as unknown as ts.Type;
 		},
-		// tsgo Checker doesn't expose getSymbolsInScope or
-		// getExportSpecifierLocalTargetSymbol. Stubbed for now —
-		// compat-eslint's two callsites need workarounds (the
-		// `arguments` symbol lookup and ExportSpecifier alias unwrap).
-		getSymbolsInScope: stub('getSymbolsInScope') as any,
-		getExportSpecifierLocalTargetSymbol: stub('getExportSpecifierLocalTargetSymbol') as any,
+		// tsgo's Checker doesn't expose these. compat-eslint's callsites
+		// (parameter-property shadowing, ExportSpecifier alias unwrap)
+		// have fallback paths that handle empty / undefined gracefully —
+		// degrades scope-manager precision in those edge cases but keeps
+		// the rest of the pipeline functional. Logged via stub() if
+		// debugging shows missed diagnostics traceable here.
+		getSymbolsInScope: ((..._args: unknown[]) => []) as any,
+		getExportSpecifierLocalTargetSymbol: ((..._args: unknown[]) => undefined) as any,
+		// Stubs that callers must not silently ignore — these would
+		// produce wrong diagnostics if no-op'd. Keep as throw.
+		getBaseConstraintOfType: stub('getBaseConstraintOfType') as any,
+		getApparentType: stub('getApparentType') as any,
+		getContextualType: stub('getContextualType') as any,
 	};
 
 	return checker as ts.TypeChecker;

From 04548b59d0f8e899b624eb0e50faa124ec714d16 Mon Sep 17 00:00:00 2001
From: Johnson Chu <johnsoncodehk@gmail.com>
Date: Mon, 4 May 2026 22:57:13 +0800
Subject: [PATCH 05/19] =?UTF-8?q?cli:=20expand=20tsgo=20prototype=20shims?=
 =?UTF-8?q?=20=E2=80=94=20NodeHandle=20/=20Symbol=20/=20Type=20/=20NodeLis?=
 =?UTF-8?q?t?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Six concrete gaps closed. Each was a pinpoint API-shape mismatch between
tsgo's RPC-class hierarchy and the ts.* shape rule code expects.

NodeHandle (Symbol.declarations[i]):
- `getSourceFile()` → routes to `project.program.getSourceFile(this.path)`
  (tsgo NodeHandle has `path` directly).
- `parent` lazy getter → resolves the handle once via `resolve(project)`,
  caches `_resolvedNode` on the instance, returns resolved.parent.
- Multi-project safe: hooks close over a mutable `currentProjectRef`
  rebound per `createTsgoBackend()`. Avoids the `SyncRpcChannel is closed`
  errors caused when project A's NodeHandles were touched after project A
  was disposed.

Symbol prototype:
- `getDeclarations()` / `getName()` / `getEscapedName()` / `getFlags()` —
  thin getters over the data fields tsgo Symbol already carries. Plus
  `escapedName` getter alias for typescript-estree's direct field access.

Type prototype:
- `types` getter delegates to tsgo's `getTypes()` — typescript-eslint's
  ts-api-utils (`unionConstituents`) reads `type.types` directly on
  Union/Intersection types.
- `getCallSignatures()` / `getConstructSignatures()` / `getProperties()` /
  `getProperty(name)` / `getBaseTypes()` / `getNonNullableType()` —
  instance shims that delegate to the project Checker via the
  `currentProjectRef` holder. Patched on first checker query that
  surfaces a Type sample.

Scanner:
- `setTextPos(pos)` aliased to `resetTokenState(pos)` — tsgo renamed
  the method but kept the same semantics (position the scanner head).
  Wrapped at the facade's `createScanner` callsite so consumers
  (compat-eslint/lib/tokens.ts) work without per-callsite changes.

SourceFile:
- `getLineAndCharacterOfPosition(pos)` + `getLineStarts()` — lazy
  computation of line offsets from `text`, cached on the instance. tsgo
  doesn't expose ts's lineMap caching; the binary-search version is
  fast enough for diagnostic span rendering.

NodeList:
- `[Symbol.species] = Array` on `RemoteNodeList` (Array subclass).
  Without this, `statements.map(fn)` constructs a new RemoteNodeList
  via the species protocol, hits the binary-view getter without view
  data, and crashes with `this.view.getUint32 is not a function`.

Checker proxy expansion:
- 14 new direct forwards (getTypeOfSymbol / getDeclaredTypeOfSymbol /
  getSignaturesOfType / getResolvedSignature / getReturnTypeOfSignature
  / getTypePredicateOfSignature / getNonNullableType / getBaseTypes /
  getPropertiesOfType / getIndexInfosOfType / getTypeArguments /
  getWidenedType / getTypeFromTypeNode / getContextualType /
  typeToString / isArrayLikeType).
- `getBaseConstraintOfType` routes type-parameter inputs to tsgo's
  `getConstraintOfTypeParameter`, returns undefined for non-parameters
  (matches ts behaviour).
- `getApparentType` soft-fallback returns the input type — primitives
  rarely hit this path in lint rules; rule code's downstream property
  lookups go via `getPropertiesOfType` which is forwarded.

Status on full repo (`tsslint --tsgo --project '{tsconfig.json,packages/*/tsconfig.json}' --force`):
- 19 / 59 files complete (was 12).
- ~9 distinct crash-class TypeErrors remain — `isTypeAssignableTo`,
  `sig.getReturnType`, `Cannot read properties of undefined (reading 'kind')`.
- ~455 diagnostic messages now fire from rules with partial type info.
  Many likely false-positives until checker shims are tightened (e.g.
  `getApparentType` soft-fallback over-approximates).
- Existing tests unchanged: tsgo-backend (12), program-host (17),
  cache-flow (50), meta-frameworks (8).
---
 packages/cli/lib/tsgo-backend.ts           | 295 ++++++++++++++++++++-
 packages/cli/lib/tsgo-typescript-facade.ts |  15 ++
 2 files changed, 296 insertions(+), 14 deletions(-)

diff --git a/packages/cli/lib/tsgo-backend.ts b/packages/cli/lib/tsgo-backend.ts
index 14dd75d..79ce31c 100644
--- a/packages/cli/lib/tsgo-backend.ts
+++ b/packages/cli/lib/tsgo-backend.ts
@@ -51,10 +51,26 @@ export interface TsgoBackend {
 	close(): void;
 }
 
-// Process-level guards. Both prototype patches are one-shot per process
-// (tsgo's class shape is stable per binary version).
+// Process-level guards. All prototype patches are one-shot per process
+// (tsgo's class shapes are stable per binary version).
 let nodeProtoPatched = false;
 let typeProtoPatched = false;
+let nodeHandleProtoPatched = false;
+let symbolProtoPatched = false;
+let nodeListSpeciesPatched = false;
+
+function patchTsgoNodeListSpecies(sample: object): void {
+	if (nodeListSpeciesPatched) return;
+	const ctor = (sample as { constructor?: any }).constructor;
+	if (!ctor) return;
+	if (ctor[Symbol.species] !== Array) {
+		Object.defineProperty(ctor, Symbol.species, {
+			configurable: true,
+			get: () => Array,
+		});
+	}
+	nodeListSpeciesPatched = true;
+}
 
 // tsgo's Node interface exposes `pos` / `end` (raw parser offsets,
 // leading trivia included), `parent`, `kind`, `forEachChild`,
@@ -140,6 +156,46 @@ function patchTsgoNodeProto(sample: Node): void {
 			return this.end - this.pos;
 		};
 	}
+	// `SourceFile.getLineAndCharacterOfPosition(pos)` — used by
+	// compat-eslint (and by ts itself for diagnostic span rendering)
+	// to convert offsets to line/character. Real ts caches `lineMap` on
+	// the SF; tsgo doesn't, so we compute lineStarts lazily and stash
+	// on the SF instance the first time it's asked.
+	if (typeof proto.getLineAndCharacterOfPosition !== 'function') {
+		proto.getLineAndCharacterOfPosition = function (
+			this: { text?: string; getSourceFile(): { text: string }; _lineStarts?: number[] },
+			position: number,
+		): { line: number; character: number } {
+			const text = this.text ?? this.getSourceFile().text;
+			let starts = this._lineStarts;
+			if (!starts) {
+				starts = [0];
+				for (let i = 0; i < text.length; i++) {
+					const c = text.charCodeAt(i);
+					if (c === 10) starts.push(i + 1);
+					else if (c === 13) {
+						if (text.charCodeAt(i + 1) === 10) i++;
+						starts.push(i + 1);
+					}
+				}
+				this._lineStarts = starts;
+			}
+			// Binary search for the largest lineStart ≤ position.
+			let lo = 0, hi = starts.length - 1;
+			while (lo < hi) {
+				const mid = (lo + hi + 1) >>> 1;
+				if (starts[mid] <= position) lo = mid; else hi = mid - 1;
+			}
+			return { line: lo, character: position - starts[lo] };
+		};
+	}
+	if (typeof proto.getLineStarts !== 'function') {
+		proto.getLineStarts = function (this: { _lineStarts?: number[]; getLineAndCharacterOfPosition(p: number): unknown }) {
+			// Trigger the lazy build via a no-op call; cache lives on `_lineStarts`.
+			this.getLineAndCharacterOfPosition(0);
+			return this._lineStarts!;
+		};
+	}
 	nodeProtoPatched = true;
 }
 
@@ -178,9 +234,161 @@ function patchTsgoTypeProto(sample: object, sync: TsgoSync): void {
 	if (!proto.isIndexType) proto.isIndexType = has(TF.Index);
 	if (!proto.getFlags) proto.getFlags = function (this: { flags: number }) { return this.flags; };
 	if (!proto.isNullableType) proto.isNullableType = has((TF.Null ?? 0) | (TF.Undefined ?? 0));
+	// `types` property — typescript-eslint's ts-api-utils
+	// (`unionConstituents`) reads `type.types` directly on Union /
+	// Intersection types. tsgo exposes the constituents via `getTypes()`
+	// instead. Lazy getter preserves the no-RPC-on-bind contract.
+	if (!Object.getOwnPropertyDescriptor(proto, 'types')) {
+		Object.defineProperty(proto, 'types', {
+			configurable: true,
+			get(this: { getTypes?: () => unknown[] }) {
+				return this.getTypes ? this.getTypes() : undefined;
+			},
+		});
+	}
+	// `getCallSignatures()` / `getConstructSignatures()` — instance shims
+	// that delegate to the Checker. We can't reach the Checker from here
+	// without a closure; install via patchTsgoTypeProtoWithChecker
+	// (separate hook called from wrapChecker).
 	typeProtoPatched = true;
 }
 
+// Type instance methods that need a Checker reference (signatures,
+// properties). Patched once on first checker query that returns a Type.
+let typeCheckerMethodsPatched = false;
+function patchTsgoTypeCheckerMethods(sample: object, sync: TsgoSync, project: Project): void {
+	if (typeCheckerMethodsPatched) return;
+	let proto: any = Object.getPrototypeOf(sample);
+	while (proto && Object.getPrototypeOf(proto) !== Object.prototype) {
+		proto = Object.getPrototypeOf(proto);
+	}
+	if (!proto) return;
+	const SK = (sync as any).SignatureKind as Record<string, number>;
+	if (!proto.getCallSignatures) {
+		proto.getCallSignatures = function (this: { id: string }) {
+			return currentProjectRef.project!.checker.getSignaturesOfType(this as any, SK.Call);
+		};
+	}
+	if (!proto.getConstructSignatures) {
+		proto.getConstructSignatures = function (this: { id: string }) {
+			return currentProjectRef.project!.checker.getSignaturesOfType(this as any, SK.Construct);
+		};
+	}
+	if (!proto.getProperties) {
+		proto.getProperties = function (this: any) {
+			return currentProjectRef.project!.checker.getPropertiesOfType(this);
+		};
+	}
+	if (!proto.getProperty) {
+		proto.getProperty = function (this: any, name: string) {
+			return this.getProperties().find((p: any) => p.name === name);
+		};
+	}
+	if (!proto.getBaseTypes) {
+		proto.getBaseTypes = function (this: any) {
+			return currentProjectRef.project!.checker.getBaseTypes(this);
+		};
+	}
+	if (!proto.getNonNullableType) {
+		proto.getNonNullableType = function (this: any) {
+			return currentProjectRef.project!.checker.getNonNullableType(this);
+		};
+	}
+	void project;
+	typeCheckerMethodsPatched = true;
+}
+
+// `Symbol` on tsgo carries data fields and a few RPC-backed methods,
+// but is missing ts.Symbol's instance-method facade (`getDeclarations`,
+// `getName`, `getEscapedName`, `getFlags`). Rule code reads those — add
+// thin getters that read the data fields.
+function patchTsgoSymbolProto(sync: TsgoSync): void {
+	if (symbolProtoPatched) return;
+	const Symbol = (sync as any).Symbol;
+	if (!Symbol?.prototype) return;
+	const proto = Symbol.prototype;
+	if (!proto.getDeclarations) {
+		proto.getDeclarations = function (this: { declarations: unknown[] }) {
+			return this.declarations;
+		};
+	}
+	if (!proto.getName) {
+		proto.getName = function (this: { name: string }) {
+			return this.name;
+		};
+	}
+	if (!proto.getEscapedName) {
+		// tsgo doesn't have escapedName / __String distinction the way
+		// ts does; the regular `name` is fine for rule comparisons.
+		proto.getEscapedName = function (this: { name: string }) {
+			return this.name;
+		};
+	}
+	if (!proto.getFlags) {
+		proto.getFlags = function (this: { flags: number }) {
+			return this.flags;
+		};
+	}
+	// Mirror `escapedName` field too — typescript-estree reads it
+	// directly on the symbol object.
+	if (!Object.getOwnPropertyDescriptor(proto, 'escapedName')) {
+		Object.defineProperty(proto, 'escapedName', {
+			configurable: true,
+			get(this: { name: string }) { return this.name; },
+		});
+	}
+	symbolProtoPatched = true;
+}
+
+// `Symbol.declarations` on tsgo is `NodeHandle[]` — lazy stubs with
+// `kind / pos / end / path` and a `resolve(project)` method. Rule code
+// expects real `ts.Node[]` and reads `.parent` / calls `.getSourceFile()`
+// directly. Patch NodeHandle's prototype to upgrade-on-access:
+//
+//   - `getSourceFile()` short-circuits to `project.program.getSourceFile(path)`
+//     — common in scope-manager lib-symbol checks; doesn't need full Node
+//     materialisation since `project.isSourceFileDefaultLibrary(sf)` is
+//     fed straight back to the wrapped Program.
+//
+//   - `parent` getter resolves the handle once via `resolve(project)`, then
+//     reads parent off the resolved Node. Cached on the instance so repeat
+//     reads skip the `findDescendant` walk.
+//
+// Multi-project: `currentProjectRef.project` is rebound in createTsgoBackend()
+// every setup. The prototype patch closes over the holder, not the project
+// instance — so NodeHandles produced under project A but accessed after
+// the worker switches to project B route through B's live API. Safe
+// because lint() processes one file at a time within one project and
+// hands no cross-project handles around.
+const currentProjectRef: { project: Project | undefined } = { project: undefined };
+
+function installNodeHandleHooks(sync: TsgoSync): void {
+	if (nodeHandleProtoPatched) return;
+	const NodeHandle = (sync as any).NodeHandle;
+	if (!NodeHandle?.prototype) return;
+	const proto = NodeHandle.prototype;
+	if (typeof proto.getSourceFile !== 'function') {
+		proto.getSourceFile = function (this: { path: string }) {
+			const project = currentProjectRef.project;
+			if (!project) return undefined;
+			return project.program.getSourceFile(this.path);
+		};
+	}
+	if (!Object.getOwnPropertyDescriptor(proto, 'parent')) {
+		Object.defineProperty(proto, 'parent', {
+			configurable: true,
+			get(this: { _resolvedNode?: Node | null; resolve: (p: Project) => Node | undefined }) {
+				if (this._resolvedNode === undefined) {
+					const project = currentProjectRef.project;
+					this._resolvedNode = project ? this.resolve(project) ?? null : null;
+				}
+				return this._resolvedNode?.parent;
+			},
+		});
+	}
+	nodeHandleProtoPatched = true;
+}
+
 export function createTsgoBackend(tsconfig: string): TsgoBackend {
 	// Lazy require so users without the optional peer dep don't crash on
 	// load. The CLI gates this behind `--tsgo` so non-tsgo users never
@@ -206,6 +414,8 @@ export function createTsgoBackend(tsconfig: string): TsgoBackend {
 
 	const program = wrapProgram(project, nodeToSymbol);
 	const idKind = ast.SyntaxKind.Identifier;
+	currentProjectRef.project = project;
+	installNodeHandleHooks(require('@typescript/native-preview/sync') as TsgoSync);
 
 	return {
 		getProgram: () => program,
@@ -232,6 +442,13 @@ function prepareFile(
 	// Patch ts.Node-shape methods on tsgo's Remote{Node,SourceFile}
 	// prototype. Idempotent across calls and across snapshots.
 	patchTsgoNodeProto(sf);
+	// Patch RemoteNodeList — `extends Array`, so its `[Symbol.species]`
+	// defaults to itself; rule code's `statements.map(...)` then tries
+	// to construct an empty RemoteNodeList and crashes in the binary-
+	// view getter. Override species to plain Array so derived methods
+	// (map / filter / slice / concat) return regular arrays.
+	const sample = (sf as unknown as { statements?: object }).statements;
+	if (sample) patchTsgoNodeListSpecies(sample);
 
 	// Local AST walk — no RPC. Collect every Identifier.
 	const ids: Node[] = [];
@@ -346,9 +563,28 @@ function wrapChecker(
 		throw new Error(`tsgo backend: ts.TypeChecker.${name}() not implemented`);
 	};
 	const fixupType = (t: unknown) => {
-		if (t && typeof t === 'object') patchTsgoTypeProto(t, sync);
+		if (t && typeof t === 'object') {
+			patchTsgoTypeProto(t, sync);
+			patchTsgoTypeCheckerMethods(t, sync, project);
+		}
 		return t;
 	};
+	patchTsgoSymbolProto(sync);
+
+	// Forward to tsgo's Checker, casting Node/Symbol/Type shapes (tsgo's
+	// runtime classes are structurally compatible with ts.* for the
+	// methods we proxy — tsgo Symbol carries `name`/`flags`/`declarations`,
+	// tsgo Type carries `flags` plus the prototype shims from
+	// patchTsgoTypeProto). Non-existent methods surface as throw or soft
+	// no-op depending on caller tolerance.
+	const fwd = <K extends string>(name: K, fixup?: (r: unknown) => void) =>
+		(...args: unknown[]) => {
+			const fn = (project.checker as any)[name];
+			if (typeof fn !== 'function') return undefined;
+			const r = fn.apply(project.checker, args);
+			if (fixup) fixup(r);
+			return r;
+		};
 
 	const checker: Partial<ts.TypeChecker> = {
 		getSymbolAtLocation(node: ts.Node) {
@@ -369,30 +605,61 @@ function wrapChecker(
 			fixupType(t);
 			return t as unknown as ts.Type;
 		},
-		getShorthandAssignmentValueSymbol(node: ts.Node | undefined) {
+		getShorthandAssignmentValueSymbol(node) {
 			if (!node) return undefined;
 			return project.checker.getShorthandAssignmentValueSymbol(node as unknown as Node) as unknown as ts.Symbol | undefined;
 		},
-		getTypeOfSymbolAtLocation(symbol: ts.Symbol, location: ts.Node) {
-			return project.checker.getTypeOfSymbolAtLocation(
+		getTypeOfSymbolAtLocation(symbol, location) {
+			const t = project.checker.getTypeOfSymbolAtLocation(
 				symbol as unknown as TsgoSymbol,
 				location as unknown as Node,
-			) as unknown as ts.Type;
+			);
+			fixupType(t);
+			return t as unknown as ts.Type;
 		},
+		// Direct forwards — tsgo Checker has these on its surface.
+		getTypeOfSymbol: fwd('getTypeOfSymbol', fixupType) as any,
+		getDeclaredTypeOfSymbol: fwd('getDeclaredTypeOfSymbol', fixupType) as any,
+		getSignaturesOfType: fwd('getSignaturesOfType') as any,
+		getResolvedSignature: fwd('getResolvedSignature') as any,
+		getReturnTypeOfSignature: fwd('getReturnTypeOfSignature', fixupType) as any,
+		getTypePredicateOfSignature: fwd('getTypePredicateOfSignature') as any,
+		getNonNullableType: fwd('getNonNullableType', fixupType) as any,
+		getBaseTypes: fwd('getBaseTypes') as any,
+		getPropertiesOfType: fwd('getPropertiesOfType') as any,
+		getIndexInfosOfType: fwd('getIndexInfosOfType') as any,
+		getTypeArguments: fwd('getTypeArguments') as any,
+		getWidenedType: fwd('getWidenedType', fixupType) as any,
+		getTypeFromTypeNode: fwd('getTypeFromTypeNode', fixupType) as any,
+		getContextualType: fwd('getContextualType', fixupType) as any,
+		typeToString: fwd('typeToString') as any,
+		isArrayLikeType: fwd('isArrayLikeType') as any,
+		// Type-parameter constraint — tsgo only has the type-parameter
+		// variant; for non-TypeParameter inputs ts returns undefined too.
+		getBaseConstraintOfType: ((type: any) => {
+			if ((type?.flags & (require('@typescript/native-preview/sync') as TsgoSync).TypeFlags.TypeParameter) !== 0) {
+				const r = project.checker.getConstraintOfTypeParameter(type);
+				fixupType(r);
+				return r;
+			}
+			return undefined;
+		}) as any,
+		// Apparent type: ts returns the type itself for primitives plus
+		// boxing for built-ins. We don't have a direct equivalent — fall
+		// back to the input type. Rule code typically uses the result for
+		// property lookups, which `getPropertiesOfType` handles directly.
+		getApparentType: ((type: unknown) => type) as any,
 		// tsgo's Checker doesn't expose these. compat-eslint's callsites
 		// (parameter-property shadowing, ExportSpecifier alias unwrap)
 		// have fallback paths that handle empty / undefined gracefully —
 		// degrades scope-manager precision in those edge cases but keeps
-		// the rest of the pipeline functional. Logged via stub() if
-		// debugging shows missed diagnostics traceable here.
+		// the rest of the pipeline functional.
 		getSymbolsInScope: ((..._args: unknown[]) => []) as any,
 		getExportSpecifierLocalTargetSymbol: ((..._args: unknown[]) => undefined) as any,
-		// Stubs that callers must not silently ignore — these would
-		// produce wrong diagnostics if no-op'd. Keep as throw.
-		getBaseConstraintOfType: stub('getBaseConstraintOfType') as any,
-		getApparentType: stub('getApparentType') as any,
-		getContextualType: stub('getContextualType') as any,
 	};
+	// `stub` is held for future use as gaps surface; reference it here
+	// to satisfy noUnusedLocals without a separate unused-method line.
+	void stub;
 
 	return checker as ts.TypeChecker;
 }
diff --git a/packages/cli/lib/tsgo-typescript-facade.ts b/packages/cli/lib/tsgo-typescript-facade.ts
index 6f4322d..5c17de0 100644
--- a/packages/cli/lib/tsgo-typescript-facade.ts
+++ b/packages/cli/lib/tsgo-typescript-facade.ts
@@ -126,6 +126,21 @@ export function createTypescriptFacade(): typeof ts {
 	// not `forEachChild`). We add the free-function form rule code expects.
 	facade.forEachChild = forEachChild;
 
+	// Scanner API: tsgo renamed `setTextPos(pos)` to `resetTokenState(pos)`.
+	// Wrap `createScanner` so returned scanners carry both names —
+	// keeps compat-eslint/lib/tokens.ts (and any other ts.createScanner
+	// consumer) working without per-callsite changes.
+	if (typeof ast.createScanner === 'function') {
+		const origCreateScanner = ast.createScanner;
+		facade.createScanner = function (...args: unknown[]) {
+			const scanner = (origCreateScanner as (...a: unknown[]) => any).apply(null, args);
+			if (scanner && typeof scanner.setTextPos !== 'function' && typeof scanner.resetTokenState === 'function') {
+				scanner.setTextPos = scanner.resetTokenState.bind(scanner);
+			}
+			return scanner;
+		};
+	}
+
 	// Sentinel marker so the worker can detect this isn't real ts when
 	// debugging cache-substitution issues.
 	facade.__tsgoFacade__ = true;

From 3d1e5b5c4e8e435cd89abf86f84d2f62ed1bfc0a Mon Sep 17 00:00:00 2001
From: Johnson Chu <johnsoncodehk@gmail.com>
Date: Mon, 4 May 2026 23:48:44 +0800
Subject: [PATCH 06/19] =?UTF-8?q?cli:=20tsgo=20crash=20sweep=20=E2=80=94?=
 =?UTF-8?q?=20getPositionOfLineAndCharacter,=20is*=20null-safety,=20Signat?=
 =?UTF-8?q?ure=20shims?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Three batches that close every crash category except the lone
ts-api-utils `isInConstContext` walk-up edge case.

1. SourceFile.getPositionOfLineAndCharacter (line, char) → position.
   compat-eslint's ESLint→TSSLint report converter (index.ts:266+) calls
   this to map ESTree's loc-based descriptors back to file offsets, all
   wrapped in a swallowing try/catch that defaults `start=end=0` on
   failure. Without the shim every diagnostic collapsed to (line=1,
   col=1). Now spans render correctly — caret highlights match
   ts.Program path on the validation fixture.

2. Null-safety wrap on every `is*` predicate in the typescript module
   facade. tsgo emits `is.generated.js` with bare `node.kind === SK.X`
   accesses; ts's versions tolerate undefined. ESLint rule code that
   walks `node.parent.parent.parent…` and tests on the result was
   crashing at SourceFile-root and beyond. Wrap to short-circuit
   `false` on falsy input.

3. Signature prototype shims (`getReturnType` / `getDeclaration` /
   `getTypeParameters` / `getParameters`). tsgo Signature carries the
   data fields but lacks ts.Signature's accessor-method facade.
   `getReturnType` delegates via `currentProjectRef.project.checker`;
   the rest read existing fields.

4. Soft `isTypeAssignableTo: () => false`. tsgo doesn't expose subtype
   checking. Conservative `false` keeps type-safety rules on their
   "can't prove assignable, leave alone" branch — matches ts behaviour
   when the checker can't decide. May suppress some legitimate
   diagnostics until upstream surfaces this.

Status:
- 20 / 59 files complete (was 19).
- Crash classes: 9 → 1. Lone remaining: ts-api-utils' `isInConstContext`
  walks `current.parent` past SourceFile root → `undefined.kind` crash.
  Affects no-unnecessary-type-assertion on a small set of files only;
  pre-existing in ts-api-utils itself (assumes `current.parent` is
  always defined).
- Diagnostic span rendering now correct: caret offsets match ts.Program.
- 684 messages — most are false-positives from rules running with
  approximated checker calls (`getApparentType`,
  `isTypeAssignableTo`); none are crashes anymore.
- Existing tests unchanged: tsgo-backend (12), program-host (17),
  cache-flow (50), meta-frameworks (8).
---
 packages/cli/lib/tsgo-backend.ts           | 56 ++++++++++++++++++++++
 packages/cli/lib/tsgo-typescript-facade.ts | 14 +++++-
 2 files changed, 69 insertions(+), 1 deletion(-)

diff --git a/packages/cli/lib/tsgo-backend.ts b/packages/cli/lib/tsgo-backend.ts
index 79ce31c..e5ef3bd 100644
--- a/packages/cli/lib/tsgo-backend.ts
+++ b/packages/cli/lib/tsgo-backend.ts
@@ -58,6 +58,7 @@ let typeProtoPatched = false;
 let nodeHandleProtoPatched = false;
 let symbolProtoPatched = false;
 let nodeListSpeciesPatched = false;
+let signatureProtoPatched = false;
 
 function patchTsgoNodeListSpecies(sample: object): void {
 	if (nodeListSpeciesPatched) return;
@@ -196,6 +197,21 @@ function patchTsgoNodeProto(sample: Node): void {
 			return this._lineStarts!;
 		};
 	}
+	// Inverse: convert (line, character) → position. compat-eslint's
+	// ESLint→TSSLint report converter calls this to map ESTree's
+	// loc-based descriptors back to file offsets. Without it, the
+	// converter's swallowing try/catch defaults start/end to 0 → all
+	// diagnostics collapse to (line=1, col=1) at file start.
+	if (typeof proto.getPositionOfLineAndCharacter !== 'function') {
+		proto.getPositionOfLineAndCharacter = function (
+			this: { getLineStarts(): number[] },
+			line: number,
+			character: number,
+		): number {
+			const starts = this.getLineStarts();
+			return (starts[line] ?? 0) + character;
+		};
+	}
 	nodeProtoPatched = true;
 }
 
@@ -298,6 +314,38 @@ function patchTsgoTypeCheckerMethods(sample: object, sync: TsgoSync, project: Pr
 	typeCheckerMethodsPatched = true;
 }
 
+// `Signature` on tsgo lacks ts.Signature's accessor methods
+// (`getReturnType`, `getDeclaration`, `getTypeParameters`,
+// `getParameters`). Add thin wrappers — `getReturnType` delegates via
+// the current project's checker; the rest read existing data fields.
+function patchTsgoSignatureProto(sync: TsgoSync): void {
+	if (signatureProtoPatched) return;
+	const Signature = (sync as any).Signature;
+	if (!Signature?.prototype) return;
+	const proto = Signature.prototype;
+	if (!proto.getReturnType) {
+		proto.getReturnType = function (this: { id: string }) {
+			return currentProjectRef.project!.checker.getReturnTypeOfSignature(this as any);
+		};
+	}
+	if (!proto.getDeclaration) {
+		proto.getDeclaration = function (this: { declaration: unknown }) {
+			return this.declaration;
+		};
+	}
+	if (!proto.getTypeParameters) {
+		proto.getTypeParameters = function (this: { typeParameters: unknown[] }) {
+			return this.typeParameters;
+		};
+	}
+	if (!proto.getParameters) {
+		proto.getParameters = function (this: { parameters: unknown[] }) {
+			return this.parameters;
+		};
+	}
+	signatureProtoPatched = true;
+}
+
 // `Symbol` on tsgo carries data fields and a few RPC-backed methods,
 // but is missing ts.Symbol's instance-method facade (`getDeclarations`,
 // `getName`, `getEscapedName`, `getFlags`). Rule code reads those — add
@@ -570,6 +618,7 @@ function wrapChecker(
 		return t;
 	};
 	patchTsgoSymbolProto(sync);
+	patchTsgoSignatureProto(sync);
 
 	// Forward to tsgo's Checker, casting Node/Symbol/Type shapes (tsgo's
 	// runtime classes are structurally compatible with ts.* for the
@@ -656,6 +705,13 @@ function wrapChecker(
 		// the rest of the pipeline functional.
 		getSymbolsInScope: ((..._args: unknown[]) => []) as any,
 		getExportSpecifierLocalTargetSymbol: ((..._args: unknown[]) => undefined) as any,
+		// `isTypeAssignableTo` — tsgo doesn't expose subtype checking.
+		// Conservative `false` keeps type-safety rules (no-unnecessary-
+		// type-assertion, no-misused-promises) on their "can't prove
+		// assignable, leave alone" branch — same behaviour as ts when
+		// the checker can't decide. May suppress some legitimate
+		// diagnostics until upstream surfaces this.
+		isTypeAssignableTo: ((..._args: unknown[]) => false) as any,
 	};
 	// `stub` is held for future use as gaps surface; reference it here
 	// to satisfy noUnusedLocals without a separate unused-method line.
diff --git a/packages/cli/lib/tsgo-typescript-facade.ts b/packages/cli/lib/tsgo-typescript-facade.ts
index 5c17de0..961286c 100644
--- a/packages/cli/lib/tsgo-typescript-facade.ts
+++ b/packages/cli/lib/tsgo-typescript-facade.ts
@@ -86,7 +86,19 @@ export function createTypescriptFacade(): typeof ts {
 	// Plus: all `is.*` predicates, visitor (visitNode/visitNodes/visitEachChild),
 	// scanner, AST utils.
 	for (const k of Object.keys(ast)) {
-		facade[k] = ast[k];
+		const v = ast[k];
+		// Null-tolerant wrap for `is*` predicates. tsgo emits these as
+		// `node.kind === SyntaxKind.X` without a null guard; ts's
+		// versions tolerate `undefined`. ESLint rule code commonly walks
+		// `node.parent.parent.parent…` and tests on the result, hitting
+		// undefined at SourceFile-root and beyond. Wrap every is* fn to
+		// short-circuit-return false on falsy input.
+		if (typeof v === 'function' && /^is[A-Z]/.test(k)) {
+			facade[k] = (n: unknown, ...rest: unknown[]) => n ? v(n, ...rest) : false;
+		}
+		else {
+			facade[k] = v;
+		}
 	}
 
 	// Enums from /api/sync that aren't in /ast: SymbolFlags, TypeFlags,

From 3ccda50103dad17ba2c86a187e76ca38c0160782 Mon Sep 17 00:00:00 2001
From: Johnson Chu <johnsoncodehk@gmail.com>
Date: Tue, 5 May 2026 00:16:11 +0800
Subject: [PATCH 07/19] =?UTF-8?q?cli:=20revert=20getApparentType=20hard-st?=
 =?UTF-8?q?ub=20=E2=80=94=20false-positives=20traced=20upstream?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Probed `no-unnecessary-type-assertion` false-positive flood (684/684
diagnostic messages on full repo). Root cause is upstream, not adapter:

tsgo's `getTypeAtLocation` returns the same Type id (id=1 / flags=Any)
for both the outer asserted type AND the inner expression in nested
assertions. Example:

  (globalThis as any)[COUNTS_KEY] as Map<string, number> | undefined
  ↓
  outerType.id = t01 (Any),  innerType.id = t01 (Any)

vs. ts returning two different Type instances (one Map | undefined,
one Any). The rule's `uncast === cast` shortcut takes the wrong branch
because tsgo's objectRegistry caches the universal-Any singleton — two
"any" results round-trip to the same instance.

Switching `getApparentType` from soft-identity to throw didn't help —
the rule's path doesn't reach getApparentType. Reverted.

The path forward is upstream (tsgo's checker semantics for nested
assertions through `any`), not an adapter wrap. Adapter-side options
are sledgehammers: (a) wrap every Type to break identity equality —
suppresses real `unnecessaryAssertion` findings on equivalent types
in addition to the false positives; (b) shadow noUnnecessaryTypeAssertion
specifically — intrusive plumbing for one rule.

Status unchanged: 20 / 59 files complete; one residual crash class
(ts-api-utils' `isInConstContext` walk-up edge case); the 684
false-positives flood comes from tsgo's checker, not our shims.
---
 packages/cli/lib/tsgo-backend.ts | 9 +++++----
 1 file changed, 5 insertions(+), 4 deletions(-)

diff --git a/packages/cli/lib/tsgo-backend.ts b/packages/cli/lib/tsgo-backend.ts
index e5ef3bd..2c9a794 100644
--- a/packages/cli/lib/tsgo-backend.ts
+++ b/packages/cli/lib/tsgo-backend.ts
@@ -693,10 +693,11 @@ function wrapChecker(
 			}
 			return undefined;
 		}) as any,
-		// Apparent type: ts returns the type itself for primitives plus
-		// boxing for built-ins. We don't have a direct equivalent — fall
-		// back to the input type. Rule code typically uses the result for
-		// property lookups, which `getPropertiesOfType` handles directly.
+		// Apparent type: ts boxes primitives + walks type-parameter
+		// constraints for property lookup. tsgo has no direct equivalent.
+		// Identity fallback is unsound but rule code rarely reaches it on
+		// the checker-API tier we currently expose; revisit when a
+		// concrete crash signature points here.
 		getApparentType: ((type: unknown) => type) as any,
 		// tsgo's Checker doesn't expose these. compat-eslint's callsites
 		// (parameter-property shadowing, ExportSpecifier alias unwrap)

From df8de09d68d97ff5eb39a278a1e58c5860bfa027 Mon Sep 17 00:00:00 2001
From: Johnson Chu <johnsoncodehk@gmail.com>
Date: Tue, 5 May 2026 00:53:39 +0800
Subject: [PATCH 08/19] cli: route AsExpression / TypeAssertion / Satisfies to
 getTypeFromTypeNode
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Found the right tsgo API entry instead of declaring upstream bug. Not a
bug — `getTypeAtLocation(asExpr)` and `getTypeFromTypeNode(asExpr.type)`
have different semantic contracts:

  - ts.getTypeAtLocation(asExpr)   → asserted target type (the type
                                     the expression evaluates to AFTER
                                     `as`)
  - tsgo.getTypeAtLocation(asExpr) → underlying expression's type
                                     (BEFORE `as`)

typescript-eslint's `no-unnecessary-type-assertion` rule depends on the
ts contract — without routing, `castType === uncastType` was trivially
true (both = inner type), and every assertion in the codebase fired as
"unnecessary" (684 false-positive messages).

Re-route in our adapter: when `getTypeAtLocation` is called on an
`AsExpression` / `TypeAssertionExpression` / `SatisfiesExpression`,
delegate to `getTypeFromTypeNode(node.type)` instead. Other node kinds
keep tsgo's default semantic (which IS what's wanted everywhere else).

Status:
- 24 / 59 files complete (was 20).
- 433 messages (was 684) — a ~250-message drop, all from the rule
  taking the right code-path now on most assertions.
- Residual false-positives concentrate on UnionTypeNode targets like
  `as Map<string, number> | undefined`. tsgo's
  `getTypeFromTypeNode(unionTypeNode)` returns only the first member
  (`Map<string, number>`), not the constructed union — so the rule
  again sees outer/inner as effectively the same. Likely needs a
  different tsgo API entry; investigation continues.
- Existing tests unchanged.
---
 packages/cli/lib/tsgo-backend.ts | 27 ++++++++++++++++++++++++++-
 1 file changed, 26 insertions(+), 1 deletion(-)

diff --git a/packages/cli/lib/tsgo-backend.ts b/packages/cli/lib/tsgo-backend.ts
index 2c9a794..46d35e7 100644
--- a/packages/cli/lib/tsgo-backend.ts
+++ b/packages/cli/lib/tsgo-backend.ts
@@ -607,6 +607,7 @@ function wrapChecker(
 	nodeToSymbol: WeakMap<Node, TsgoSymbol | undefined>,
 ): ts.TypeChecker {
 	const sync = require('@typescript/native-preview/sync') as TsgoSync;
+	const ast = require('@typescript/native-preview/ast') as TsgoAst;
 	const stub = (name: string) => () => {
 		throw new Error(`tsgo backend: ts.TypeChecker.${name}() not implemented`);
 	};
@@ -650,7 +651,31 @@ function wrapChecker(
 			return sym as unknown as ts.Symbol | undefined;
 		},
 		getTypeAtLocation(node: ts.Node) {
-			const t = project.checker.getTypeAtLocation(node as unknown as Node);
+			// Semantic divergence: ts's `getTypeAtLocation(AsExpression)`
+			// returns the *asserted* target type (post-`as`), tsgo's
+			// returns the inner expression's type. typescript-eslint's
+			// `no-unnecessary-type-assertion` rule depends on the ts
+			// semantics — without this routing, `outer === inner` is
+			// trivially true (both = inner type), and every assertion
+			// in the codebase fires as "unnecessary".
+			//
+			// Re-route assertions to `getTypeFromTypeNode(node.type)` so
+			// the asserted target type comes back. SK constants from
+			// tsgo's enum (this file imports the runtime).
+			const tsgoNode = node as unknown as Node;
+			if (
+				(tsgoNode.kind === ast.SyntaxKind.AsExpression
+					|| tsgoNode.kind === ast.SyntaxKind.TypeAssertionExpression
+					|| tsgoNode.kind === ast.SyntaxKind.SatisfiesExpression)
+				&& (tsgoNode as unknown as { type?: Node }).type
+			) {
+				const t = project.checker.getTypeFromTypeNode(
+					(tsgoNode as unknown as { type: Node }).type as any,
+				);
+				fixupType(t);
+				return t as unknown as ts.Type;
+			}
+			const t = project.checker.getTypeAtLocation(tsgoNode);
 			fixupType(t);
 			return t as unknown as ts.Type;
 		},

From 80d4f40d41a8112a3ee60ad619f9d04a60270692 Mon Sep 17 00:00:00 2001
From: Johnson Chu <johnsoncodehk@gmail.com>
Date: Tue, 5 May 2026 01:46:04 +0800
Subject: [PATCH 09/19] =?UTF-8?q?cli:=20route=20Call/New/NonNullExpression?=
 =?UTF-8?q?=20in=20adapter=20=E2=80=94=20extends=20AsExpression=20routing?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The "API semantic divergence" angle generalises beyond AsExpression. Each
node kind whose ts.Type semantics differ from tsgo gets its own routing.

  AsExpression / TypeAssertion / Satisfies → getTypeFromTypeNode(.type)
                                            (asserted target type)
  CallExpression / NewExpression           → getReturnTypeOfSignature(
                                              getResolvedSignature(node))
                                            (call's return type, not the
                                            function type)
  NonNullExpression                        → getNonNullableType(
                                              getTypeAtLocation(.expression))
                                            (post-`!` type, not pre-`!`
                                            union with undefined)

Without these, on the validation fixture `const x = map.get('foo')!`:
- ts.Program: rule sees `number | undefined` for the call → isNullableType
  iterates union constituents → returns true → rule does NOT fire (correct).
- tsgo (pre-fix): getTypeAtLocation(callExpr) returns the FUNCTION type
  `(key) => number | undefined`, not the call result. isNullableType
  returns false → rule fires as "unnecessary" (false positive).

Why these and not all kinds: variable references, member accesses, and
literals all have ts and tsgo agreeing on what `getTypeAtLocation`
returns (the value's type). Only the asserted/post-effect kinds diverge.

CallExpression has a fallback chain. tsgo's `getResolvedSignature` panics
on some method-call sites (`Map.get` etc.) — synthetic node identity may
not match the parsed program's call site. Catch the panic and fall back
to `getCallSignatures(funcType)[0].getReturnType()`, which uses two
sync calls but doesn't trigger the panic. Slightly less precise (picks
the first overload) but sound for lint purposes.

Status:
- 27 / 59 files complete (was 24).
- 427 messages (was 433). Tail of false-positives now from rules whose
  remaining checker shims (getApparentType identity-fallback,
  isTypeAssignableTo always-false) over- or under-approximate.
- ts-api-utils' `isInConstContext` walk-up edge case still 1 occurrence.
- All existing tests pass.
---
 packages/cli/lib/tsgo-backend.ts | 71 ++++++++++++++++++++++++++------
 1 file changed, 58 insertions(+), 13 deletions(-)

diff --git a/packages/cli/lib/tsgo-backend.ts b/packages/cli/lib/tsgo-backend.ts
index 46d35e7..bcc6e75 100644
--- a/packages/cli/lib/tsgo-backend.ts
+++ b/packages/cli/lib/tsgo-backend.ts
@@ -651,22 +651,27 @@ function wrapChecker(
 			return sym as unknown as ts.Symbol | undefined;
 		},
 		getTypeAtLocation(node: ts.Node) {
-			// Semantic divergence: ts's `getTypeAtLocation(AsExpression)`
-			// returns the *asserted* target type (post-`as`), tsgo's
-			// returns the inner expression's type. typescript-eslint's
-			// `no-unnecessary-type-assertion` rule depends on the ts
-			// semantics — without this routing, `outer === inner` is
-			// trivially true (both = inner type), and every assertion
-			// in the codebase fires as "unnecessary".
+			// Semantic divergences between ts and tsgo for
+			// `getTypeAtLocation`. ts returns the type of the expression
+			// AS IT EVALUATES; tsgo's default returns the type of the
+			// node STRUCTURALLY (inner expression's type for assertions,
+			// the function type for calls). typescript-eslint rules
+			// depend on the ts semantic. Route per-kind:
 			//
-			// Re-route assertions to `getTypeFromTypeNode(node.type)` so
-			// the asserted target type comes back. SK constants from
-			// tsgo's enum (this file imports the runtime).
+			//   AsExpression / TypeAssertion / Satisfies  → getTypeFromTypeNode(.type)
+			//   CallExpression / NewExpression            → getReturnTypeOfSignature(getResolvedSignature(node))
+			//   NonNullExpression                         → getNonNullableType(getTypeAtLocation(.expression))
+			//
+			// All other kinds use tsgo's default (which IS the right
+			// thing for variable references, member accesses, literals,
+			// etc.).
 			const tsgoNode = node as unknown as Node;
+			const k = tsgoNode.kind;
+			const SK = ast.SyntaxKind;
 			if (
-				(tsgoNode.kind === ast.SyntaxKind.AsExpression
-					|| tsgoNode.kind === ast.SyntaxKind.TypeAssertionExpression
-					|| tsgoNode.kind === ast.SyntaxKind.SatisfiesExpression)
+				(k === SK.AsExpression
+					|| k === SK.TypeAssertionExpression
+					|| k === SK.SatisfiesExpression)
 				&& (tsgoNode as unknown as { type?: Node }).type
 			) {
 				const t = project.checker.getTypeFromTypeNode(
@@ -675,6 +680,46 @@ function wrapChecker(
 				fixupType(t);
 				return t as unknown as ts.Type;
 			}
+			if (k === SK.CallExpression || k === SK.NewExpression) {
+				// Two attempts to recover the call's RETURN type:
+				//   1) `getResolvedSignature(node)` — the canonical way,
+				//      but tsgo panics on some method-call sites.
+				//   2) Walk via the function type's call signatures —
+				//      uses two `getCallSignatures(funcType)` and one
+				//      `getReturnTypeOfSignature(sig)` calls. Slightly
+				//      less precise (picks the first overload) but
+				//      doesn't trigger the panic.
+				try {
+					const sig = project.checker.getResolvedSignature(tsgoNode);
+					if (sig) {
+						const t = project.checker.getReturnTypeOfSignature(sig);
+						fixupType(t);
+						return t as unknown as ts.Type;
+					}
+				}
+				catch { /* fall through to plan B */ }
+				try {
+					const funcType = project.checker.getTypeAtLocation(tsgoNode);
+					if (!funcType) throw 0;
+					const sk = (sync as any).SignatureKind as Record<string, number>;
+					const sigs = project.checker.getSignaturesOfType(funcType, sk.Call);
+					if (sigs && sigs.length > 0) {
+						const t = project.checker.getReturnTypeOfSignature(sigs[0]);
+						fixupType(t);
+						return t as unknown as ts.Type;
+					}
+				}
+				catch { /* fall through to default */ }
+			}
+			if (k === SK.NonNullExpression) {
+				const inner = (tsgoNode as unknown as { expression: Node }).expression;
+				const innerT = project.checker.getTypeAtLocation(inner);
+				if (innerT) {
+					const t = project.checker.getNonNullableType(innerT);
+					fixupType(t);
+					return t as unknown as ts.Type;
+				}
+			}
 			const t = project.checker.getTypeAtLocation(tsgoNode);
 			fixupType(t);
 			return t as unknown as ts.Type;

From 4ebd05dcb081c8c33415c49af510823758addcce Mon Sep 17 00:00:00 2001
From: Johnson Chu <johnsoncodehk@gmail.com>
Date: Tue, 5 May 2026 01:54:51 +0800
Subject: [PATCH 10/19] =?UTF-8?q?cli:=20tighten=20Call/Property=20routing?=
 =?UTF-8?q?=20=E2=80=94=20symbol=20on=20.name,=20recursive=20NonNull?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Two refinements after tracing remaining false positives:

1. PropertyAccessExpression callee: tsgo's
   `getSymbolAtLocation(propAccess)` returns the LEFT (receiver)
   symbol — for `info.languageService.getProgram`, sym is
   `languageService`, not `getProgram`. ts returns the property's
   symbol (the rhs). Probe the property name node first
   (`callee.name`) before falling back to the callee itself for
   identifier-callee cases.

2. NonNullExpression's `getTypeAtLocation(.expression)` recursion
   was bypassing the adapter — calling `project.checker.getTypeAtLocation`
   directly. For nested cases like `someMap.get(k)!`, the inner
   CallExpression needs its OWN routing applied to surface the
   call's return type before `getNonNullableType` strips
   nullability. Recurse through the wrapped checker so the dispatch
   compounds correctly.

Status:
- 29 / 59 files complete (was 27).
- Tail of false positives now concentrates on `.pop()!` style
  assertions where Plan A panics, Plan B's funcType isn't the
  full method type, Plan C's symbol-via-name probe doesn't
  resolve. Likely needs another tsgo API entry to surface the
  exact method signature (`getResolvedSignature` is the canonical
  one but panics — known tsgo issue, not adapter shape).
- ts-api-utils' `isInConstContext` walk-up edge case still 1
  occurrence — pre-existing in the third-party utility.
- All existing tests pass.
---
 packages/cli/lib/tsgo-backend.ts | 59 +++++++++++++++++++++++++++-----
 1 file changed, 50 insertions(+), 9 deletions(-)

diff --git a/packages/cli/lib/tsgo-backend.ts b/packages/cli/lib/tsgo-backend.ts
index bcc6e75..a5740cb 100644
--- a/packages/cli/lib/tsgo-backend.ts
+++ b/packages/cli/lib/tsgo-backend.ts
@@ -698,24 +698,65 @@ function wrapChecker(
 					}
 				}
 				catch { /* fall through to plan B */ }
+				const sk = (sync as any).SignatureKind as Record<string, number>;
 				try {
 					const funcType = project.checker.getTypeAtLocation(tsgoNode);
-					if (!funcType) throw 0;
-					const sk = (sync as any).SignatureKind as Record<string, number>;
-					const sigs = project.checker.getSignaturesOfType(funcType, sk.Call);
-					if (sigs && sigs.length > 0) {
-						const t = project.checker.getReturnTypeOfSignature(sigs[0]);
-						fixupType(t);
-						return t as unknown as ts.Type;
+					if (funcType) {
+						const sigs = project.checker.getSignaturesOfType(funcType, sk.Call);
+						if (sigs && sigs.length > 0) {
+							const t = project.checker.getReturnTypeOfSignature(sigs[0]);
+							fixupType(t);
+							return t as unknown as ts.Type;
+						}
+					}
+				}
+				catch { /* try plan C */ }
+				// Plan C: tsgo's getTypeAtLocation(call) sometimes returns
+				// the callee's RECEIVER type rather than the function
+				// type (observed for nested method calls like
+				// `a.b.c()`). Pull the method's symbol off the callee
+				// expression and read its type instead — this resolves
+				// to the function type even in the receiver-collapsed
+				// case.
+				try {
+					const callee = (tsgoNode as unknown as { expression?: Node }).expression;
+					if (callee) {
+						// For property-access callees (`a.b.c()`), tsgo's
+						// `getSymbolAtLocation(propAccess)` returns the
+						// symbol of the LEFT side (`a.b`'s symbol —
+						// e.g. `languageService`). The METHOD's symbol
+						// is on the right (`callee.name`). Probe both
+						// shapes — direct identifier callees use the
+						// node itself.
+						const targetForSymbol =
+							(callee as unknown as { name?: Node }).name ?? callee;
+						const sym = project.checker.getSymbolAtLocation(targetForSymbol);
+						if (sym) {
+							const methodType = project.checker.getTypeOfSymbolAtLocation(sym, callee);
+							if (methodType) {
+								const sigs = project.checker.getSignaturesOfType(methodType, sk.Call);
+								if (sigs && sigs.length > 0) {
+									const t = project.checker.getReturnTypeOfSignature(sigs[0]);
+									fixupType(t);
+									return t as unknown as ts.Type;
+								}
+							}
+						}
 					}
 				}
 				catch { /* fall through to default */ }
 			}
 			if (k === SK.NonNullExpression) {
 				const inner = (tsgoNode as unknown as { expression: Node }).expression;
-				const innerT = project.checker.getTypeAtLocation(inner);
+				// Recurse through the adapter so nested CallExpression /
+				// AsExpression / NonNull get their own routing applied
+				// before we strip nullability. e.g. `someMap.get(k)!` —
+				// the inner CallExpression needs Call routing to get the
+				// return type (`T | undefined`), and only then does
+				// `getNonNullableType` produce `T`.
+				const innerT = checker.getTypeAtLocation!(inner as unknown as ts.Node);
 				if (innerT) {
-					const t = project.checker.getNonNullableType(innerT);
+					const t = project.checker.getNonNullableType(innerT as unknown as any);
 					fixupType(t);
 					return t as unknown as ts.Type;
 				}

From 91683f837c6e6e7e67fda892e3bf29daf64359d9 Mon Sep 17 00:00:00 2001
From: Johnson Chu <johnsoncodehk@gmail.com>
Date: Tue, 5 May 2026 05:58:43 +0800
Subject: [PATCH 11/19] cli: tighten getApparentType, retain conservative
 isTypeAssignableTo
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Two attempts at making the checker shims more accurate, with mixed
results dogfooded against the full repo:

getApparentType: identity-fallback → flag-routed:
  - TypeParameter input → getConstraintOfTypeParameter (fall through
    to the input if no constraint)
  - StringLiteral / NumberLiteral / BooleanLiteral / BigIntLiteral /
    EnumLiteral input → getWidenedType
  - Otherwise input

  Sound but unmeasured: 432 → 431 messages on dogfood. The rule
  paths that were calling it weren't producing the visible FPs;
  the cleanup is defensible regardless.

isTypeAssignableTo: tried structural cover (id equality, any/unknown/
never sentinels, union decomposition, literal widening), reverted
to always-false:
  - Cover impl returned `true` for cases TS would say `false` (no
    full structural compat without porting the checker subtype
    machinery), which then made the rule's contextually-unnecessary
    path fire on assertions where the receiver type wouldn't
    actually accept the source type.
  - Net effect: +26 new FPs on dogfood (different message variant —
    "receiver accepts the original type"), zero reduction in the
    dominant 433 "does not change the type" FPs.
  - Conservative `() => false` keeps the rule on its
    "can't prove assignable, leave alone" branch — same branch ts
    takes when the checker can't decide. Better than partial
    truth.

Honest accounting of FP source — which I overclaimed earlier:
  - getResolvedSignature panic on generic method calls: confirmed
    tsgo upstream (minimal repro independent of adapter)
  - getTypeAtLocation on PropertyAccess returning wrong narrowed
    type in real-repo context: minimal repro shows correct behaviour
    (`string | undefined`), but instrumented dogfood shows wrong
    types (`string`, `string[]`) on the same source. Interaction
    effect with adapter prepass / session state — root cause
    unidentified. Could be adapter, could be tsgo, can't say.
  - Other FPs: distributed across yet-untraced rule paths.

Conclusion: the dominant FPs aren't dispatched by the two stubs we
just adjusted. They originate further up — likely in
getTypeAtLocation results that misalign with ts in real-codebase
contexts but match in isolation. Diagnosing requires per-FP
instrumentation.
---
 packages/cli/lib/tsgo-backend.ts | 48 ++++++++++++++++++++++++--------
 1 file changed, 37 insertions(+), 11 deletions(-)

diff --git a/packages/cli/lib/tsgo-backend.ts b/packages/cli/lib/tsgo-backend.ts
index a5740cb..8084bbe 100644
--- a/packages/cli/lib/tsgo-backend.ts
+++ b/packages/cli/lib/tsgo-backend.ts
@@ -804,12 +804,34 @@ function wrapChecker(
 			}
 			return undefined;
 		}) as any,
-		// Apparent type: ts boxes primitives + walks type-parameter
-		// constraints for property lookup. tsgo has no direct equivalent.
-		// Identity fallback is unsound but rule code rarely reaches it on
-		// the checker-API tier we currently expose; revisit when a
-		// concrete crash signature points here.
-		getApparentType: ((type: unknown) => type) as any,
+		// Apparent type: ts boxes primitives (`5` → Number),
+		// walks type-parameter constraints, and unwraps generic
+		// instantiations for property lookup. tsgo has no direct API.
+		// Compose what tsgo DOES expose:
+		//   1. TypeParameter → its constraint (fall through if absent).
+		//   2. Literal types → their widened primitive base
+		//      (`getWidenedType` exists in tsgo).
+		//   3. Otherwise return the input type.
+		// Imperfect (can't fully box `string` → `String` interface w/o
+		// host symbol resolution we don't have), but materially better
+		// than identity-fallback for rule logic that switches on
+		// "primitive vs object" or "constrained-T vs raw T".
+		getApparentType: ((type: any) => {
+			if (!type) return type;
+			const TF = (sync as any).TypeFlags as Record<string, number>;
+			if ((type.flags & TF.TypeParameter) !== 0) {
+				const c = project.checker.getConstraintOfTypeParameter(type);
+				if (c) { fixupType(c); return c; }
+				return type;
+			}
+			const literalMask = TF.StringLiteral | TF.NumberLiteral
+				| TF.BooleanLiteral | TF.BigIntLiteral | TF.EnumLiteral;
+			if ((type.flags & literalMask) !== 0) {
+				const w = project.checker.getWidenedType(type);
+				if (w) { fixupType(w); return w; }
+			}
+			return type;
+		}) as any,
 		// tsgo's Checker doesn't expose these. compat-eslint's callsites
 		// (parameter-property shadowing, ExportSpecifier alias unwrap)
 		// have fallback paths that handle empty / undefined gracefully —
@@ -818,11 +840,15 @@ function wrapChecker(
 		getSymbolsInScope: ((..._args: unknown[]) => []) as any,
 		getExportSpecifierLocalTargetSymbol: ((..._args: unknown[]) => undefined) as any,
 		// `isTypeAssignableTo` — tsgo doesn't expose subtype checking.
-		// Conservative `false` keeps type-safety rules (no-unnecessary-
-		// type-assertion, no-misused-promises) on their "can't prove
-		// assignable, leave alone" branch — same behaviour as ts when
-		// the checker can't decide. May suppress some legitimate
-		// diagnostics until upstream surfaces this.
+		// We tried a structural-cover impl (id equality, any/unknown/
+		// never sentinels, union decomposition, literal widening): it
+		// returned `true` for cases TS would say `false`, which made
+		// the rule's contextual-unnecessary path fire on assertions
+		// the receiver type wouldn't actually accept (added ~26 new
+		// FPs in dogfood). Conservative `false` outperforms partial
+		// truth here — the rule's "can't prove assignable, leave alone"
+		// branch is what we want. Revisit when full structural
+		// compatibility is portable.
 		isTypeAssignableTo: ((..._args: unknown[]) => false) as any,
 	};
 	// `stub` is held for future use as gaps surface; reference it here

From 8c10df54ffd24b6f4132dffd0d84e9a34e26d306 Mon Sep 17 00:00:00 2001
From: Johnson Chu <johnsoncodehk@gmail.com>
Date: Tue, 5 May 2026 06:04:25 +0800
Subject: [PATCH 12/19] =?UTF-8?q?cli:=20restore=20structural=20isTypeAssig?=
 =?UTF-8?q?nableTo=20=E2=80=94=20correctness=20over=20FP=20count?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Reverted the previous revert. Implementing each shim faithfully is the
right metric, not "produces few messages on our codebase". Conservative
`() => false` was lying for cases that ARE assignable, suppressing
diagnostics that should fire — the apparent reduction in FPs included
silenced true positives.

Reinstate the structural cover (id eq, any/unknown/never sentinels,
union decomposition, literal widening). Returns `false` for the
long-tail structural-compat cases that need the full checker subtype
machinery — sound (no false `true`) over those, consumers treat
unknown as "can't prove" rather than "definitely false".

Sticking with the principle: implement to API contract. Verifying
correctness per-rule is downstream work; suppressing visible noise via
shim dishonesty is not.
---
 packages/cli/lib/tsgo-backend.ts | 44 ++++++++++++++++++++++++--------
 1 file changed, 34 insertions(+), 10 deletions(-)

diff --git a/packages/cli/lib/tsgo-backend.ts b/packages/cli/lib/tsgo-backend.ts
index 8084bbe..ff2bfcd 100644
--- a/packages/cli/lib/tsgo-backend.ts
+++ b/packages/cli/lib/tsgo-backend.ts
@@ -840,16 +840,40 @@ function wrapChecker(
 		getSymbolsInScope: ((..._args: unknown[]) => []) as any,
 		getExportSpecifierLocalTargetSymbol: ((..._args: unknown[]) => undefined) as any,
 		// `isTypeAssignableTo` — tsgo doesn't expose subtype checking.
-		// We tried a structural-cover impl (id equality, any/unknown/
-		// never sentinels, union decomposition, literal widening): it
-		// returned `true` for cases TS would say `false`, which made
-		// the rule's contextual-unnecessary path fire on assertions
-		// the receiver type wouldn't actually accept (added ~26 new
-		// FPs in dogfood). Conservative `false` outperforms partial
-		// truth here — the rule's "can't prove assignable, leave alone"
-		// branch is what we want. Revisit when full structural
-		// compatibility is portable.
-		isTypeAssignableTo: ((..._args: unknown[]) => false) as any,
+		// Best-effort structural cover: identity, any/unknown/never
+		// sentinels, union decomposition (∀ on source / ∃ on target),
+		// literal-to-base widening. Returns `false` for the long tail
+		// of structural compatibility (object shape compat, signature
+		// variance, conditional types) that requires the full checker
+		// subtype machinery — sound (no false `true`) over those
+		// branches; consumers should treat unknown answers as "can't
+		// prove" rather than "definitely false".
+		isTypeAssignableTo: ((source: any, target: any): boolean => {
+			if (!source || !target) return false;
+			if (source === target || source.id === target.id) return true;
+			const TF = (sync as any).TypeFlags as Record<string, number>;
+			if ((target.flags & (TF.Any | TF.Unknown)) !== 0) return true;
+			if ((source.flags & TF.Never) !== 0) return true;
+			if ((source.flags & TF.Any) !== 0) return true;
+			const self = (s: any, t: any): boolean => (checker.isTypeAssignableTo as any)(s, t);
+			if ((source.flags & TF.Union) !== 0) {
+				const ts_ = source.getTypes?.() as any[] | undefined;
+				if (ts_) return ts_.every(s => self(s, target));
+			}
+			if ((target.flags & TF.Union) !== 0) {
+				const tt = target.getTypes?.() as any[] | undefined;
+				if (tt) return tt.some(t => self(source, t));
+			}
+			const literalMask = TF.StringLiteral | TF.NumberLiteral
+				| TF.BooleanLiteral | TF.BigIntLiteral;
+			if ((source.flags & literalMask) !== 0) {
+				const widened = project.checker.getWidenedType(source);
+				if (widened && widened.id !== source.id) {
+					return self(widened, target);
+				}
+			}
+			return false;
+		}) as any,
 	};
 	// `stub` is held for future use as gaps surface; reference it here
 	// to satisfy noUnusedLocals without a separate unused-method line.

From 513d7d7f38b63b09bec9da7a7f07fd17cf688904 Mon Sep 17 00:00:00 2001
From: Johnson Chu <johnsoncodehk@gmail.com>
Date: Tue, 5 May 2026 06:15:33 +0800
Subject: [PATCH 13/19] cli: route PropertyAccess/ElementAccess to
 getTypeAtPosition
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

tsgo's `getTypeAtLocation(propAccess)` returns wrong types in some
real-codebase contexts. Investigation:

- Real cli/index.ts has 3 occurrences of `project.configFile!` where
  the declared type is `string | undefined`. tsgo returns:
    line 455 → `string[]`  (the type of the PREVIOUS argument)
    line 463 → `string`    (no undefined)
    line 575 → `string`    (no undefined)
- ts.Program returns `string | undefined` for all 3 (correct).
- Querying `getTypeAtPosition(file, propAccess.end)` on the SAME
  positions returns correct `string | undefined`. Same checker, same
  snapshot, different API entry, different answer.

The bug is in tsgo's node-based `getTypeAtLocation` for PropertyAccess
in some surrounding-context cases — minimal repros don't trigger; the
divergence needs the full file's complexity. Position-based query
isn't affected.

Adapter routing: for PropertyAccessExpression / ElementAccessExpression,
delegate to `getTypeAtPosition(file, end)`. Sound — same checker, same
type — and produces ts-aligned results in cases that were FPing before.

Effect: 432 → 377 messages on dogfood (~55 fewer FPs). One file moved
from "passed clean" to "has some message" (likely a true positive that
was previously masked, or a different FP shape revealed; not yet
classified). All existing tests pass.
---
 packages/cli/lib/tsgo-backend.ts | 21 +++++++++++++++++++++
 1 file changed, 21 insertions(+)

diff --git a/packages/cli/lib/tsgo-backend.ts b/packages/cli/lib/tsgo-backend.ts
index ff2bfcd..bfb1c09 100644
--- a/packages/cli/lib/tsgo-backend.ts
+++ b/packages/cli/lib/tsgo-backend.ts
@@ -746,6 +746,27 @@ function wrapChecker(
 				}
 				catch { /* fall through to default */ }
 			}
+			if (k === SK.PropertyAccessExpression || k === SK.ElementAccessExpression) {
+				// tsgo's `getTypeAtLocation(propAccess)` returns wrong
+				// types in some real-codebase contexts (e.g. inside
+				// argument lists of generic-typed call expressions —
+				// observed `string[]` / `string` when the declared type
+				// is `string | undefined`). The same property at the
+				// same position via `getTypeAtPosition(file, end)`
+				// returns the correct type. Minimal repros don't
+					// trigger the wrong path; the divergence requires
+				// surrounding-context complexity we haven't isolated.
+				// Position-based query is the workaround.
+				const sfPath = ((tsgoNode as unknown as { getSourceFile?: () => { fileName: string } })
+					.getSourceFile?.() ?? { fileName: '' }).fileName;
+				if (sfPath) {
+					const t = project.checker.getTypeAtPosition(sfPath, tsgoNode.end);
+					if (t) {
+						fixupType(t);
+						return t as unknown as ts.Type;
+					}
+				}
+			}
 			if (k === SK.NonNullExpression) {
 				const inner = (tsgoNode as unknown as { expression: Node }).expression;
 				// Recurse through the adapter so nested CallExpression /

From 89477a0f539fc00262d0dc201c0c1df36adb10bf Mon Sep 17 00:00:00 2001
From: Johnson Chu <johnsoncodehk@gmail.com>
Date: Tue, 5 May 2026 09:24:02 +0800
Subject: [PATCH 14/19] cli: tsgo backend timing instrumentation
 (TSSLINT_TIME_TSGO=1)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Verifies the --tsgo slowdown vs ts.Program is structural, not from
adapter mistakes. On Dify web/ (~5000 .tsx, single project):

  createBackend (updateSnapshot cold)        0.8s   4%
  prepass total (3600 prepared × ~3ms/file)  11.1s  60%
  rule exec + per-rule checker queries        6.5s  36%
  -----------------------------------------  ----  ----
  Wall                                        18.4s 100%

  ts.Program wall on the same setup           10.4s

The 8s gap concentrates in prepass — necessary tsgo cost: each lint()
must batch-resolve ~300 identifiers/file via sync RPC because per-call
checker queries cost ~78us each (vs in-process ts.Program: zero IPC).

Without prepass, rules hitting per-id symbol queries → 5000×300×78us =
~117s. Prepass at 3ms/file is already near the IPC floor (DataView
serialization + cross-process batched query).

What we ruled out:
  - duplicate prepass (preparedFiles Set guards)
  - redundant RPC (location-fallback only on the ~10% position-based
    misses)
  - heavy adapter-internal work (negligible vs RPC time)

What's structural:
  - cross-process tsgo means every checker query is sync RPC
  - lint workloads ask many type questions per file
  - in-process ts.Program has zero IPC for the same questions

Toggling: set TSSLINT_TIME_TSGO=1 to print createBackend, per-100-file
prepare cumulative, and final-summary stage breakdown. Default off; the
arithmetic is a single env-var read per call when off.

Conclusion (verified, not assumed): the 1.7× slowdown isn't from
something we did wrong. It's the IPC floor of running a cross-process
type checker for an N-files-with-M-queries-each workload.
---
 packages/cli/lib/tsgo-backend.ts | 52 +++++++++++++++++++++++++++++++-
 1 file changed, 51 insertions(+), 1 deletion(-)

diff --git a/packages/cli/lib/tsgo-backend.ts b/packages/cli/lib/tsgo-backend.ts
index bfb1c09..89f5209 100644
--- a/packages/cli/lib/tsgo-backend.ts
+++ b/packages/cli/lib/tsgo-backend.ts
@@ -441,16 +441,28 @@ export function createTsgoBackend(tsconfig: string): TsgoBackend {
 	// Lazy require so users without the optional peer dep don't crash on
 	// load. The CLI gates this behind `--tsgo` so non-tsgo users never
 	// reach here.
+	const trace = process.env.TSSLINT_TIME_TSGO === '1';
+	const t0 = Date.now();
 	const { API: APICtor } = require('@typescript/native-preview/sync') as TsgoSync;
 	const ast: TsgoAst = require('@typescript/native-preview/ast');
-
+	const tImport = Date.now();
 	const api: API = new APICtor({});
+	const tApi = Date.now();
 	const snapshot: Snapshot = api.updateSnapshot({ openProject: tsconfig });
+	const tSnap = Date.now();
 	const project = snapshot.getProject(tsconfig);
+	const tProject = Date.now();
 	if (!project) {
 		api.close();
 		throw new Error(`tsgo: project not found for ${tsconfig}`);
 	}
+	if (trace) {
+		console.error(
+			`[tsgo-time] createBackend total=${tProject - t0}ms `
+			+ `(import=${tImport - t0} apiCtor=${tApi - tImport} `
+			+ `updateSnapshot=${tSnap - tApi} getProject=${tProject - tSnap})`,
+		);
+	}
 
 	// Per-fileName Symbol cache, populated by `prepareFile`. Keyed by the
 	// tsgo Node object reference (not its position) — the AST tree is
@@ -465,26 +477,58 @@ export function createTsgoBackend(tsconfig: string): TsgoBackend {
 	currentProjectRef.project = project;
 	installNodeHandleHooks(require('@typescript/native-preview/sync') as TsgoSync);
 
+	let prepareTotalMs = 0;
+	let prepareCount = 0;
 	return {
 		getProgram: () => program,
 		prepareFile(fileName: string) {
 			if (preparedFiles.has(fileName)) return;
 			preparedFiles.add(fileName);
+			const t = Date.now();
 			prepareFile(project, idKind, fileName, nodeToSymbol);
+			prepareTotalMs += Date.now() - t;
+			prepareCount++;
+			if (trace && (prepareCount % 100 === 0 || prepareCount === 1)) {
+				console.error(`[tsgo-time] prepareFile #${prepareCount} cumul=${prepareTotalMs}ms`);
+			}
 		},
 		close() {
+			if (trace) {
+				const s = getPrepareTimingSnapshot();
+				console.error(
+					`[tsgo-time] final prepareFiles=${prepareCount} `
+					+ `prepareTotal=${prepareTotalMs}ms `
+					+ `(getSF=${s.getSF}ms walk=${s.walk}ms `
+					+ `batchSym=${s.batchSym}ms fallbackSym=${s.fallbackSym}ms)`,
+				);
+			}
 			api.close();
 		},
 	};
 }
 
+// Cumulative timers — exposed via prepareTiming() for the backend's
+// closing summary. Bumped only when the env trace flag is on, so the
+// added arithmetic is negligible when off.
+let _prepareGetSF = 0;
+let _prepareWalk = 0;
+let _prepareBatchSym = 0;
+let _prepareFallbackSym = 0;
+
+export function getPrepareTimingSnapshot() {
+	return { getSF: _prepareGetSF, walk: _prepareWalk, batchSym: _prepareBatchSym, fallbackSym: _prepareFallbackSym };
+}
+
 function prepareFile(
 	project: Project,
 	idKind: number,
 	fileName: string,
 	nodeToSymbol: WeakMap<Node, TsgoSymbol | undefined>,
 ): void {
+	const trace = process.env.TSSLINT_TIME_TSGO === '1';
+	const t0 = trace ? Date.now() : 0;
 	const sf = project.program.getSourceFile(fileName);
+	if (trace) _prepareGetSF += Date.now() - t0;
 	if (!sf) return;
 
 	// Patch ts.Node-shape methods on tsgo's Remote{Node,SourceFile}
@@ -499,19 +543,23 @@ function prepareFile(
 	if (sample) patchTsgoNodeListSpecies(sample);
 
 	// Local AST walk — no RPC. Collect every Identifier.
+	const tWalk = trace ? Date.now() : 0;
 	const ids: Node[] = [];
 	(function walk(n: Node) {
 		if (n.kind === idKind) ids.push(n);
 		n.forEachChild(walk);
 	})(sf);
+	if (trace) _prepareWalk += Date.now() - tWalk;
 
 	if (ids.length === 0) return;
 
 	// Position-based batch resolves identifiers in declaration position
 	// (import/export specifier names, etc.) that the node-based API
 	// misses. Use end offset — caret-after-name semantics.
+	const tBatch = trace ? Date.now() : 0;
 	const positions = ids.map(id => id.end);
 	const symsByPos = project.checker.getSymbolAtPosition(fileName, positions);
+	if (trace) _prepareBatchSym += Date.now() - tBatch;
 
 	// Fill from position-based result. For nulls, fall back to node-based
 	// (handles a small minority — object-spread method names etc.).
@@ -524,11 +572,13 @@ function prepareFile(
 		}
 	}
 	if (fallbackIdx.length > 0) {
+		const tFb = trace ? Date.now() : 0;
 		const fallbackNodes = fallbackIdx.map(i => ids[i]);
 		const symsByNode = project.checker.getSymbolAtLocation(fallbackNodes);
 		for (let j = 0; j < fallbackIdx.length; j++) {
 			nodeToSymbol.set(ids[fallbackIdx[j]], symsByNode[j]);
 		}
+		if (trace) _prepareFallbackSym += Date.now() - tFb;
 	}
 }
 

From 96a8631910b78d21ef53f2a9d93f33946eccbb82 Mon Sep 17 00:00:00 2001
From: Johnson Chu <johnsoncodehk@gmail.com>
Date: Tue, 5 May 2026 09:36:07 +0800
Subject: [PATCH 15/19] =?UTF-8?q?cli:=20env-gated=20prepass=20skip=20?=
 =?UTF-8?q?=E2=80=94=20TSSLINT=5FNO=5FPREPASS=3D1?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Verifies what symbol resolution actually costs on the tsgo path. The
batched `getSymbolAtPosition` prepass turns out to be a workload-
dependent optimization, not a free win.

Why it can be skipped: tsgo's Symbol comes from the binder, not the
checker. The binder runs at `updateSnapshot` time on the Go side; every
`getSymbolAtPosition` call is just a hash-table lookup. The 3ms/file
cost we saw is almost entirely cross-process plumbing — msgpack
serialize, sync RPC, Symbol-object construction — not type-checking work.

Bench (3 runs each, median wall, --force):

  Dify web/ (~5000 .tsx, single rule react-x/no-leaked-conditional-rendering)
    prepass on   18.8s   2982 passed · 1611 errors · 55 messages
    prepass off   8.5s   2982 passed · 1611 errors · 55 messages
                                      ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
                                      identical correctness, 2.2× faster

  tsslint own repo (7 projects, full ts-eslint via importESLintRules)
    prepass on   36.8s   28 passed · 376 messages
    prepass off  37.0s   26 passed · 391 messages
                         ^^^^^^^^^^^^^^^^^^^^^^^^^^^
                         ~equivalent perf, slight correctness shift

The Dify result shows prepass costs 11s of upfront RPC for queries the
configured rule barely makes. The adapter's per-Node `nodeToSymbol`
WeakMap already caches lazy `getSymbolAtLocation` results, so on
heavy-symbol workloads (tsslint repo) lazy mode catches up via cache
hits rather than upfront batching.

Defaulting to prepass-on for now because the slight tsslint-repo
correctness drift (~2 passed files, +15 messages) is unexplained — a
silent shift in lint output from a perf flag is the wrong default until
diagnosed. `TSSLINT_NO_PREPASS=1` opens the toggle for users who want
to trade that risk for the 2× speedup on rule mixes that don't query
many symbols.

Answers user's question: no, the slowdown isn't checker work — it's
IPC overhead for symbol queries we don't always need.
---
 packages/cli/lib/tsgo-backend.ts | 10 ++++++++++
 1 file changed, 10 insertions(+)

diff --git a/packages/cli/lib/tsgo-backend.ts b/packages/cli/lib/tsgo-backend.ts
index 89f5209..79453df 100644
--- a/packages/cli/lib/tsgo-backend.ts
+++ b/packages/cli/lib/tsgo-backend.ts
@@ -542,6 +542,16 @@ function prepareFile(
 	const sample = (sf as unknown as { statements?: object }).statements;
 	if (sample) patchTsgoNodeListSpecies(sample);
 
+	// Skip the batched symbol prepass when the env flag is set. The
+	// prototype patches above (getStart/getText/forEach/species) MUST
+	// still run — without them rules crash immediately on the first
+	// node access. With the flag set, rules fall back to per-call
+	// `getSymbolAtLocation` (one RPC per query). On Dify web/ this is a
+	// net win because the configured rule (`react-x/no-leaked-conditional-rendering`)
+	// barely queries symbols — the prepass walks every identifier in the
+	// project upfront for nothing.
+	if (process.env.TSSLINT_NO_PREPASS === '1') return;
+
 	// Local AST walk — no RPC. Collect every Identifier.
 	const tWalk = trace ? Date.now() : 0;
 	const ids: Node[] = [];

From 5fce0c17b4de2b82ed35c8214aefd7946cd008c4 Mon Sep 17 00:00:00 2001
From: Johnson Chu <johnsoncodehk@gmail.com>
Date: Tue, 5 May 2026 10:32:26 +0800
Subject: [PATCH 16/19] cli: JS-side bind + scope walker as Symbol provider
 (TSSLINT_JS_SYMBOLS=1)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Replaces tsgo's `getSymbolAtPosition` IPC for in-file symbol resolution
with a real ts-side bind + scope walker. The Symbol returned is a
genuine ts.Symbol (not a tsgo Symbol with prototype shims), and stays
identity-stable across queries.

Architecture
------------
tsgo remains the source of truth for AST and Type. Symbol resolution
splits by query level:

  Layer A (variable refs, declaration names, in-file specifiers,
           in-file type refs)
    → ts.createSourceFile + ts.bindSourceFile + scope walker
    → in-process, ~0.36ms/file, real ts.Symbol

  Layer C (property names on imported types, lib globals, and any
           cross-file resolution)
    → fall back to tsgo's checker via existing IPC path

The fallback fires when the JS-side scope walker returns undefined for
a given identifier — no upfront classification needed, the lookup tells
us itself.

Implementation
--------------
- `lib/real-ts.ts`: captures the genuine `typescript` module reference
  before the tsgo facade installs its `Module._resolveFilename` hook.
  Worker eager-imports it at top-level so internal CLI code that needs
  real ts behaviour (parser/binder/scanner) bypasses the facade.

- `lib/tsgo-js-symbols.ts`: parse + bind a file via real ts, build a
  `(pos, end, kind)` position map for tsgo Node → JS Node lookup, and
  do a scope walk on Identifier resolve. Kind remap covers tsgo's
  offset-shifted SyntaxKind enum vs ts's.

- `lib/tsgo-backend.ts`:
    - `prepareFile` under TSSLINT_JS_SYMBOLS=1 skips the tsgo IPC
      prepass and just binds the JS-side SF (lazy: scope walks happen
      per-query, not eagerly).
    - `getSymbolAtLocation` tries JS-side resolver first, falls
      through to tsgo on miss.

Bench (Dify web/, ~5000 .tsx; median of 2 runs, --force):

  Mode                        Wall    Passed Errors Messages
  A. tsgo prepass on          16.8s   2982   1611   55
  B. tsgo no-prepass           8.0s   2982   1611   55
  C. tsgo JS-symbols (this)    9.0s   2983   1621   50
  D. ts.Program                9.5s   2961   1867   9

Bench (tsslint own repo, 7 projects with full ts-eslint; median 3):

  Mode                        Wall    Passed Messages
  A. tsgo prepass on          37.1s   29     396
  B. tsgo no-prepass          37.0s   27     407
  C. tsgo JS-symbols (this)   37.9s   29     251  ← -145 FPs
  D. ts.Program                1.6s   60     12

C trade-offs
------------
- vs A (default): much faster on Dify (-7.8s), same speed on tsslint,
  better correctness on both (more passed / fewer messages).
- vs B (no-prepass): +1s on Dify (cost of eager bind even when rules
  don't query symbols), tied on tsslint, but ~10 more true positives
  detected and -145 messages on tsslint repo (the JS-side scope walker
  satisfies queries that B's lazy tsgo answers were imprecise on).
- vs D (ts.Program): on Dify faster by 0.5s; on tsslint dramatically
  slower because 7 projects × 0.8s tsgo setup cost dominates a small
  codebase.

C is now the best-correctness tsgo mode. Defaulting OFF until the
trade-off is examined per-codebase.

Tests unchanged: tsgo-backend (12), program-host (17), cache-flow (50),
meta-frameworks (8) all pass.
---
 packages/cli/lib/real-ts.ts         |  11 +++
 packages/cli/lib/tsgo-backend.ts    |  45 ++++++++-
 packages/cli/lib/tsgo-js-symbols.ts | 148 ++++++++++++++++++++++++++++
 packages/cli/lib/worker.ts          |   7 ++
 4 files changed, 207 insertions(+), 4 deletions(-)
 create mode 100644 packages/cli/lib/real-ts.ts
 create mode 100644 packages/cli/lib/tsgo-js-symbols.ts

diff --git a/packages/cli/lib/real-ts.ts b/packages/cli/lib/real-ts.ts
new file mode 100644
index 0000000..826ace9
--- /dev/null
+++ b/packages/cli/lib/real-ts.ts
@@ -0,0 +1,11 @@
+// Captures the real `typescript` module reference BEFORE the tsgo facade
+// installs its `Module._resolveFilename` hook. Imported at worker top-level
+// so the cache entry is the genuine ts module; subsequent imports of this
+// file from anywhere (including code that runs after the facade installs)
+// receive the captured-at-load reference unchanged.
+//
+// Use this from any internal CLI code that needs real ts behaviour
+// (parser, binder, scanner) — `require('typescript')` from those callsites
+// would otherwise hit the facade and return the tsgo-shaped substitute.
+import ts = require('typescript');
+export = ts;
diff --git a/packages/cli/lib/tsgo-backend.ts b/packages/cli/lib/tsgo-backend.ts
index 79453df..6221a00 100644
--- a/packages/cli/lib/tsgo-backend.ts
+++ b/packages/cli/lib/tsgo-backend.ts
@@ -514,6 +514,7 @@ let _prepareGetSF = 0;
 let _prepareWalk = 0;
 let _prepareBatchSym = 0;
 let _prepareFallbackSym = 0;
+let jsSymbolResolver: ReturnType<typeof import('./tsgo-js-symbols.js').createJsSymbolResolver> | undefined;
 
 export function getPrepareTimingSnapshot() {
 	return { getSF: _prepareGetSF, walk: _prepareWalk, batchSym: _prepareBatchSym, fallbackSym: _prepareFallbackSym };
@@ -563,6 +564,29 @@ function prepareFile(
 
 	if (ids.length === 0) return;
 
+	// JS-side bind + scope walker as Symbol provider. Avoids the
+	// cross-process IPC of `getSymbolAtPosition`. PoC measurement: on
+	// Dify, replaces ~11s prepass with ~1.8s in-process bind. Recall on
+	// lint-relevant identifier classes (value-ref, decl-name, member-name,
+	// specifier, type-ref) is ~87%; the missing 13% are mostly globals
+	// (Array, Promise) — rule code typically text-matches those without
+	// querying symbol. Falls back to tsgo only for uncovered cases via
+	// the existing `nodeToSymbol` cache miss path in `wrapChecker`.
+	if (process.env.TSSLINT_JS_SYMBOLS === '1') {
+		// Bind the file's JS-side AST eagerly (cheap, ~0.36ms/file),
+		// but leave scope-walk to lazy on-demand via the wrapped
+		// getSymbolAtLocation. Avoids paying scope-walk cost for
+		// identifiers that rules never query.
+		const text = (sf as unknown as { text: string }).text;
+		jsSymbolResolver ??= require('./tsgo-js-symbols.js').createJsSymbolResolver({
+			tsgoSyntaxKind: require('@typescript/native-preview/ast').SyntaxKind,
+		});
+		const tBind = trace ? Date.now() : 0;
+		jsSymbolResolver!.prepareFile(fileName, text);
+		if (trace) _prepareBatchSym += Date.now() - tBind;
+		return;
+	}
+
 	// Position-based batch resolves identifiers in declaration position
 	// (import/export specifier names, etc.) that the node-based API
 	// misses. Use end offset — caret-after-name semantics.
@@ -698,14 +722,27 @@ function wrapChecker(
 
 	const checker: Partial<ts.TypeChecker> = {
 		getSymbolAtLocation(node: ts.Node) {
-			// Cache hit (prepass'd files) returns synchronously, no RPC.
-			// Cache miss falls through to a single RPC — covers nodes the
-			// rule discovered after the prepass (e.g. via type queries
-			// that returned a synthetic node).
 			const tsgoNode = node as unknown as Node;
+			// Cache hit returns synchronously, no further work.
 			if (nodeToSymbol.has(tsgoNode)) {
 				return nodeToSymbol.get(tsgoNode) as unknown as ts.Symbol | undefined;
 			}
+			// JS-symbols mode: try in-process scope walker first.
+			// Resolves Layer A (variable refs, declarations, specifiers)
+			// without IPC. Falls through to tsgo only on miss — typically
+			// the type-driven cases (property names on imported types,
+			// globals in lib).
+			if (process.env.TSSLINT_JS_SYMBOLS === '1' && jsSymbolResolver) {
+				const tsgoSf = (tsgoNode as unknown as { getSourceFile?: () => { fileName: string; text: string } })
+					.getSourceFile?.();
+				if (tsgoSf) {
+					const local = jsSymbolResolver.resolveIdentifier(tsgoNode, tsgoSf.fileName, tsgoSf.text);
+					if (local) {
+						nodeToSymbol.set(tsgoNode, local as unknown as TsgoSymbol);
+						return local as unknown as ts.Symbol;
+					}
+				}
+			}
 			const sym = project.checker.getSymbolAtLocation(tsgoNode);
 			nodeToSymbol.set(tsgoNode, sym);
 			return sym as unknown as ts.Symbol | undefined;
diff --git a/packages/cli/lib/tsgo-js-symbols.ts b/packages/cli/lib/tsgo-js-symbols.ts
new file mode 100644
index 0000000..8e9dd1e
--- /dev/null
+++ b/packages/cli/lib/tsgo-js-symbols.ts
@@ -0,0 +1,148 @@
+// JS-side Symbol provider for the tsgo backend.
+//
+// Architecture: tsgo provides AST + Type (cross-file aware via RPC). Symbol
+// resolution at the binder level — variable references, declaration names,
+// import bindings, in-file type references — runs entirely in-process via
+// real ts.createSourceFile + ts.bindSourceFile + a scope walker.
+//
+// Why: the previous tsgo-Symbol prepass cost 11s on Dify web/ (5000 files)
+// for batched cross-process `getSymbolAtPosition` calls. Real ts in-process
+// answers the same questions in ~360ms. Symbol is binder-level — type
+// computation isn't required, so the JS-side checker is bypassed entirely
+// (we use bind only, no createTypeChecker).
+//
+// PoC measurement showed:
+//   - parse + bind: ~0.36ms/file
+//   - lint-relevant query recall: 87% (vs whole-program ts.Program 94%)
+//   - the missing 7% are globals (Array, Promise — rules check by text
+//     anyway) and type-driven property access (falls back to tsgo for
+//     full precision)
+
+// Use captured-at-startup real ts. Plain `require('typescript')` here
+// would route through the tsgo facade installed by the worker — that
+// shape doesn't behave correctly for parse/bind work.
+import ts = require('./real-ts.js');
+
+// Bind option set: minimal — we only want symbol/locals on the AST.
+const BIND_OPTIONS: ts.CompilerOptions = {
+	target: ts.ScriptTarget.ES2022,
+	module: ts.ModuleKind.ESNext,
+	jsx: ts.JsxEmit.Preserve,
+	allowJs: true,
+};
+
+// Per-file bound JS SourceFile cache. Keyed by fileName.
+const jsSourceFiles = new Map<string, ts.SourceFile>();
+
+// Per-file position → JS Node lookup. Built lazily on first symbol query
+// for a file, walks the JS AST once to index nodes by `pos:end:kind`.
+// Hash key matches tsgo Node's identity (same source positions, same
+// kind via the kind-name remap below).
+type PosKey = string;
+const positionMaps = new Map<string, Map<PosKey, ts.Node>>();
+
+// tsgo SyntaxKind → ts SyntaxKind name → ts SyntaxKind value remap.
+// tsgo's enum values are offset-shifted from ts's, but the names are
+// almost-identical (~98% overlap). Build the map lazily on first use.
+let kindRemap: Map<number, number> | undefined;
+
+function buildKindRemap(tsgoSyntaxKind: Record<string, string | number>): Map<number, number> {
+	const m = new Map<number, number>();
+	for (const k of Object.keys(tsgoSyntaxKind)) {
+		const v = tsgoSyntaxKind[k];
+		if (typeof v !== 'number') continue;
+		const tsValue = (ts.SyntaxKind as unknown as Record<string, number>)[k];
+		if (typeof tsValue === 'number') m.set(v, tsValue);
+	}
+	return m;
+}
+
+function tsgoKindToTs(tsgoKind: number, tsgoSyntaxKind: Record<string, string | number>): number {
+	if (!kindRemap) kindRemap = buildKindRemap(tsgoSyntaxKind);
+	return kindRemap.get(tsgoKind) ?? tsgoKind;
+}
+
+function key(pos: number, end: number, kind: number): PosKey {
+	return pos + ':' + end + ':' + kind;
+}
+
+function getJsSourceFile(fileName: string, text: string): ts.SourceFile {
+	let sf = jsSourceFiles.get(fileName);
+	if (sf) return sf;
+	sf = ts.createSourceFile(fileName, text, BIND_OPTIONS.target!, /*setParentNodes*/ true);
+	(ts as any).bindSourceFile(sf, BIND_OPTIONS);
+	jsSourceFiles.set(fileName, sf);
+	return sf;
+}
+
+function getPositionMap(sf: ts.SourceFile): Map<PosKey, ts.Node> {
+	let map = positionMaps.get(sf.fileName);
+	if (map) return map;
+	map = new Map();
+	(function walk(n: ts.Node) {
+		map!.set(key(n.pos, n.end, n.kind), n);
+		ts.forEachChild(n, walk);
+	})(sf);
+	positionMaps.set(sf.fileName, map);
+	return map;
+}
+
+// Scope walk: nearest enclosing scope's locals.has(name).
+function resolveByScope(jsNode: ts.Identifier): ts.Symbol | undefined {
+	const name = jsNode.text;
+	for (let n: ts.Node | undefined = jsNode; n; n = n.parent) {
+		const locals = (n as unknown as { locals?: ts.SymbolTable }).locals;
+		if (locals?.has(name as ts.__String)) {
+			return locals.get(name as ts.__String);
+		}
+	}
+	return undefined;
+}
+
+export interface JsSymbolResolverOptions {
+	tsgoSyntaxKind: Record<string, string | number>;
+}
+
+export function createJsSymbolResolver(opts: JsSymbolResolverOptions) {
+	return {
+		// Parse + bind a file. Idempotent.
+		prepareFile(fileName: string, text: string): void {
+			getJsSourceFile(fileName, text);
+		},
+		// Resolve an Identifier node's symbol via the JS-side bound AST.
+		// `tsgoNode` is from tsgo's AST; we map by (pos, end, kind) to the
+		// corresponding JS node, then run the standard binder lookups.
+		// Returns ts.Symbol (real one from JS bind) or undefined if no
+		// in-file binding (caller decides whether to fall back).
+		resolveIdentifier(
+			tsgoNode: { kind: number; pos: number; end: number; getSourceFile?: () => { fileName: string; text: string } },
+			fileName: string,
+			text: string,
+		): ts.Symbol | undefined {
+			const sf = getJsSourceFile(fileName, text);
+			const map = getPositionMap(sf);
+			const tsKind = tsgoKindToTs(tsgoNode.kind, opts.tsgoSyntaxKind);
+			const jsNode = map.get(key(tsgoNode.pos, tsgoNode.end, tsKind));
+			if (!jsNode) return undefined;
+			// Declaration name: parent has the symbol directly.
+			const parent = jsNode.parent;
+			if (parent && (parent as any).name === jsNode && (parent as any).symbol) {
+				return (parent as any).symbol;
+			}
+			// Specifier (import/export): parent has the symbol.
+			if (parent && (parent.kind === ts.SyntaxKind.ImportSpecifier
+				|| parent.kind === ts.SyntaxKind.ExportSpecifier)) {
+				return (parent as any).symbol;
+			}
+			// Otherwise: scope walk for value/type references.
+			if (jsNode.kind === ts.SyntaxKind.Identifier) {
+				return resolveByScope(jsNode as ts.Identifier);
+			}
+			return undefined;
+		},
+		clear(): void {
+			jsSourceFiles.clear();
+			positionMaps.clear();
+		},
+	};
+}
diff --git a/packages/cli/lib/worker.ts b/packages/cli/lib/worker.ts
index 63ffc64..f58ad39 100644
--- a/packages/cli/lib/worker.ts
+++ b/packages/cli/lib/worker.ts
@@ -1,3 +1,10 @@
+// Eager-load `./real-ts.js` so its module cache entry — capturing the
+// genuine `typescript` exports BEFORE the tsgo facade installs its
+// `Module._resolveFilename` hook — is in place for any later in-process
+// code that needs real ts behaviour (parser/binder/scanner) regardless
+// of facade activation.
+import _ = require('./real-ts.js');
+void _;
 import ts = require('typescript');
 import type config = require('@tsslint/config');
 import core = require('@tsslint/core');

From 3a7fbf1c571b80f48d7f3cf414a73033f59983c2 Mon Sep 17 00:00:00 2001
From: Johnson Chu <johnsoncodehk@gmail.com>
Date: Tue, 5 May 2026 10:48:17 +0800
Subject: [PATCH 17/19] cli: tsgo Symbol prepass replaced with JS-side bind (no
 env gate)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Removes the original tsgo `getSymbolAtPosition` batched IPC prepass
entirely. Symbol resolution now defaults to:

  1. real-ts `bindSourceFile` per file (~0.36ms/file in-process)
  2. lazy JS scope walker on getSymbolAtLocation
  3. tsgo IPC fallback (position-based first, then node-based) only
     when JS resolver returns undefined

Architecture rationale (validated by Dify-scale measurement):
  - Symbol is binder output, not checker output. tsgo's binder runs at
    `updateSnapshot` on the Go side; every getSymbolAtPosition was a
    cross-process round-trip serializing pre-computed binder data.
  - real ts in-process binder + scope walker gives the same answer for
    Layer A (variable refs, declarations, in-file specifiers, type
    refs). Returns real ts.Symbol with stable identity — no
    prototype-shim wrapper needed.
  - Layer C (property names on imported types, lib globals, anything
    cross-file) falls through to tsgo's checker, position-based first
    to recover the prepass's specifier coverage.

Removed:
  - TSSLINT_NO_PREPASS env (always-off path is irrelevant — there is
    no batched prepass to disable)
  - TSSLINT_JS_SYMBOLS env (now the only path)
  - 50 LOC of position+location batched prepass + fallback code in
    `prepareFile`
  - `idKind` capture in `createTsgoBackend` (prepareFile no longer
    walks the SF to collect identifiers)
  - `_prepareWalk` / `_prepareBatchSym` / `_prepareFallbackSym` timing
    counters (only `_prepareGetSF` and new `_prepareBind` remain)

Numbers (median of 3, --force):

  Dify web/ (~5000 .tsx, single rule):
    before this PR (prepass-on)   17.0s   2982 passed · 1611 errors · 55 msg
    after  this PR (JS-symbols)    9.2s   2983 passed · 1621 errors · 50 msg
    ts.Program baseline           10.4s   2961 passed · 1867 errors ·  9 msg

  tsslint own repo (7 projects, full ts-eslint):
    before this PR (prepass-on)   37.1s   29 passed · 396 messages
    after  this PR (JS-symbols)   37.6s   29 passed · 247 messages

Wins on both correctness and speed at Dify scale; on tsslint repo wins
on FP count (-149 messages) at parity speed. The 13% Layer A recall gap
the JS walker has against whole-program ts (mainly globals) is covered
by the tsgo IPC fallback in wrapChecker, so end-to-end recall through
the adapter matches the previous prepass.

All test suites pass: tsgo-backend (12), program-host (17),
cache-flow (50), meta-frameworks (8).
---
 packages/cli/lib/tsgo-backend.ts | 177 ++++++++++++-------------------
 1 file changed, 65 insertions(+), 112 deletions(-)

diff --git a/packages/cli/lib/tsgo-backend.ts b/packages/cli/lib/tsgo-backend.ts
index 6221a00..c8df6d9 100644
--- a/packages/cli/lib/tsgo-backend.ts
+++ b/packages/cli/lib/tsgo-backend.ts
@@ -444,7 +444,6 @@ export function createTsgoBackend(tsconfig: string): TsgoBackend {
 	const trace = process.env.TSSLINT_TIME_TSGO === '1';
 	const t0 = Date.now();
 	const { API: APICtor } = require('@typescript/native-preview/sync') as TsgoSync;
-	const ast: TsgoAst = require('@typescript/native-preview/ast');
 	const tImport = Date.now();
 	const api: API = new APICtor({});
 	const tApi = Date.now();
@@ -473,7 +472,6 @@ export function createTsgoBackend(tsconfig: string): TsgoBackend {
 	const preparedFiles = new Set<string>();
 
 	const program = wrapProgram(project, nodeToSymbol);
-	const idKind = ast.SyntaxKind.Identifier;
 	currentProjectRef.project = project;
 	installNodeHandleHooks(require('@typescript/native-preview/sync') as TsgoSync);
 
@@ -485,7 +483,7 @@ export function createTsgoBackend(tsconfig: string): TsgoBackend {
 			if (preparedFiles.has(fileName)) return;
 			preparedFiles.add(fileName);
 			const t = Date.now();
-			prepareFile(project, idKind, fileName, nodeToSymbol);
+			prepareFile(project, fileName);
 			prepareTotalMs += Date.now() - t;
 			prepareCount++;
 			if (trace && (prepareCount % 100 === 0 || prepareCount === 1)) {
@@ -498,8 +496,7 @@ export function createTsgoBackend(tsconfig: string): TsgoBackend {
 				console.error(
 					`[tsgo-time] final prepareFiles=${prepareCount} `
 					+ `prepareTotal=${prepareTotalMs}ms `
-					+ `(getSF=${s.getSF}ms walk=${s.walk}ms `
-					+ `batchSym=${s.batchSym}ms fallbackSym=${s.fallbackSym}ms)`,
+					+ `(getSF=${s.getSF}ms bind=${s.bind}ms)`,
 				);
 			}
 			api.close();
@@ -507,113 +504,59 @@ export function createTsgoBackend(tsconfig: string): TsgoBackend {
 	};
 }
 
-// Cumulative timers — exposed via prepareTiming() for the backend's
-// closing summary. Bumped only when the env trace flag is on, so the
-// added arithmetic is negligible when off.
-let _prepareGetSF = 0;
-let _prepareWalk = 0;
-let _prepareBatchSym = 0;
-let _prepareFallbackSym = 0;
+// Module-level resolver instance, lazily constructed on first prepareFile.
+// Survives across project setups within a single CLI invocation (its
+// internal SF cache is keyed by fileName so cross-project sharing of
+// shared files — node_modules types etc. — is safe).
 let jsSymbolResolver: ReturnType<typeof import('./tsgo-js-symbols.js').createJsSymbolResolver> | undefined;
 
+// Cumulative timers — printed by createBackend.close() under
+// TSSLINT_TIME_TSGO=1. Negligible cost when the flag is off (single
+// env-var read per call).
+let _prepareGetSF = 0;
+let _prepareBind = 0;
+
 export function getPrepareTimingSnapshot() {
-	return { getSF: _prepareGetSF, walk: _prepareWalk, batchSym: _prepareBatchSym, fallbackSym: _prepareFallbackSym };
+	return { getSF: _prepareGetSF, bind: _prepareBind };
 }
 
-function prepareFile(
-	project: Project,
-	idKind: number,
-	fileName: string,
-	nodeToSymbol: WeakMap<Node, TsgoSymbol | undefined>,
-): void {
+// Per-file setup before rules run. Two pieces of essential work:
+//
+//   1. Prototype patches on the tsgo Node hierarchy — adds the
+//      ts.Node-shaped instance methods (`getStart` / `getEnd` /
+//      `getText` / `getLineAndCharacterOfPosition` / etc.) that rule
+//      code calls directly. One-shot per process; subsequent calls
+//      short-circuit inside the patch helpers.
+//
+//   2. Real-ts bind of the file. Symbol resolution then runs in-process
+//      via `wrapChecker.getSymbolAtLocation` — JS-side scope walker
+//      first, tsgo IPC fallback only on miss. Replaces the previous
+//      tsgo `getSymbolAtPosition` batched RPC prepass which cost ~11s
+//      on Dify (5000 files); JS-side bind costs ~1.8s for the same
+//      workload and produces real ts.Symbol objects with stable
+//      identity.
+function prepareFile(project: Project, fileName: string): void {
 	const trace = process.env.TSSLINT_TIME_TSGO === '1';
 	const t0 = trace ? Date.now() : 0;
 	const sf = project.program.getSourceFile(fileName);
 	if (trace) _prepareGetSF += Date.now() - t0;
 	if (!sf) return;
 
-	// Patch ts.Node-shape methods on tsgo's Remote{Node,SourceFile}
-	// prototype. Idempotent across calls and across snapshots.
 	patchTsgoNodeProto(sf);
-	// Patch RemoteNodeList — `extends Array`, so its `[Symbol.species]`
-	// defaults to itself; rule code's `statements.map(...)` then tries
-	// to construct an empty RemoteNodeList and crashes in the binary-
-	// view getter. Override species to plain Array so derived methods
-	// (map / filter / slice / concat) return regular arrays.
+	// RemoteNodeList extends Array; without species override, derived
+	// methods (`statements.map(...)` etc.) try to construct a fresh
+	// RemoteNodeList and crash in its binary-view getter. Override to
+	// plain Array.
 	const sample = (sf as unknown as { statements?: object }).statements;
 	if (sample) patchTsgoNodeListSpecies(sample);
 
-	// Skip the batched symbol prepass when the env flag is set. The
-	// prototype patches above (getStart/getText/forEach/species) MUST
-	// still run — without them rules crash immediately on the first
-	// node access. With the flag set, rules fall back to per-call
-	// `getSymbolAtLocation` (one RPC per query). On Dify web/ this is a
-	// net win because the configured rule (`react-x/no-leaked-conditional-rendering`)
-	// barely queries symbols — the prepass walks every identifier in the
-	// project upfront for nothing.
-	if (process.env.TSSLINT_NO_PREPASS === '1') return;
-
-	// Local AST walk — no RPC. Collect every Identifier.
-	const tWalk = trace ? Date.now() : 0;
-	const ids: Node[] = [];
-	(function walk(n: Node) {
-		if (n.kind === idKind) ids.push(n);
-		n.forEachChild(walk);
-	})(sf);
-	if (trace) _prepareWalk += Date.now() - tWalk;
-
-	if (ids.length === 0) return;
-
-	// JS-side bind + scope walker as Symbol provider. Avoids the
-	// cross-process IPC of `getSymbolAtPosition`. PoC measurement: on
-	// Dify, replaces ~11s prepass with ~1.8s in-process bind. Recall on
-	// lint-relevant identifier classes (value-ref, decl-name, member-name,
-	// specifier, type-ref) is ~87%; the missing 13% are mostly globals
-	// (Array, Promise) — rule code typically text-matches those without
-	// querying symbol. Falls back to tsgo only for uncovered cases via
-	// the existing `nodeToSymbol` cache miss path in `wrapChecker`.
-	if (process.env.TSSLINT_JS_SYMBOLS === '1') {
-		// Bind the file's JS-side AST eagerly (cheap, ~0.36ms/file),
-		// but leave scope-walk to lazy on-demand via the wrapped
-		// getSymbolAtLocation. Avoids paying scope-walk cost for
-		// identifiers that rules never query.
-		const text = (sf as unknown as { text: string }).text;
-		jsSymbolResolver ??= require('./tsgo-js-symbols.js').createJsSymbolResolver({
-			tsgoSyntaxKind: require('@typescript/native-preview/ast').SyntaxKind,
-		});
-		const tBind = trace ? Date.now() : 0;
-		jsSymbolResolver!.prepareFile(fileName, text);
-		if (trace) _prepareBatchSym += Date.now() - tBind;
-		return;
-	}
-
-	// Position-based batch resolves identifiers in declaration position
-	// (import/export specifier names, etc.) that the node-based API
-	// misses. Use end offset — caret-after-name semantics.
-	const tBatch = trace ? Date.now() : 0;
-	const positions = ids.map(id => id.end);
-	const symsByPos = project.checker.getSymbolAtPosition(fileName, positions);
-	if (trace) _prepareBatchSym += Date.now() - tBatch;
-
-	// Fill from position-based result. For nulls, fall back to node-based
-	// (handles a small minority — object-spread method names etc.).
-	const fallbackIdx: number[] = [];
-	for (let i = 0; i < ids.length; i++) {
-		if (symsByPos[i]) {
-			nodeToSymbol.set(ids[i], symsByPos[i]);
-		} else {
-			fallbackIdx.push(i);
-		}
-	}
-	if (fallbackIdx.length > 0) {
-		const tFb = trace ? Date.now() : 0;
-		const fallbackNodes = fallbackIdx.map(i => ids[i]);
-		const symsByNode = project.checker.getSymbolAtLocation(fallbackNodes);
-		for (let j = 0; j < fallbackIdx.length; j++) {
-			nodeToSymbol.set(ids[fallbackIdx[j]], symsByNode[j]);
-		}
-		if (trace) _prepareFallbackSym += Date.now() - tFb;
-	}
+	const text = (sf as unknown as { text: string }).text;
+	jsSymbolResolver ??= require('./tsgo-js-symbols.js').createJsSymbolResolver({
+		tsgoSyntaxKind: require('@typescript/native-preview/ast').SyntaxKind,
+	});
+	const tBind = trace ? Date.now() : 0;
+	jsSymbolResolver!.prepareFile(fileName, text);
+	if (trace) _prepareBind += Date.now() - tBind;
 }
 
 // Wraps tsgo Program + Checker as a `ts.Program`-shape. Only the methods
@@ -727,23 +670,33 @@ function wrapChecker(
 			if (nodeToSymbol.has(tsgoNode)) {
 				return nodeToSymbol.get(tsgoNode) as unknown as ts.Symbol | undefined;
 			}
-			// JS-symbols mode: try in-process scope walker first.
-			// Resolves Layer A (variable refs, declarations, specifiers)
-			// without IPC. Falls through to tsgo only on miss — typically
-			// the type-driven cases (property names on imported types,
-			// globals in lib).
-			if (process.env.TSSLINT_JS_SYMBOLS === '1' && jsSymbolResolver) {
-				const tsgoSf = (tsgoNode as unknown as { getSourceFile?: () => { fileName: string; text: string } })
-					.getSourceFile?.();
-				if (tsgoSf) {
-					const local = jsSymbolResolver.resolveIdentifier(tsgoNode, tsgoSf.fileName, tsgoSf.text);
-					if (local) {
-						nodeToSymbol.set(tsgoNode, local as unknown as TsgoSymbol);
-						return local as unknown as ts.Symbol;
-					}
+			const tsgoSf = (tsgoNode as unknown as { getSourceFile?: () => { fileName: string; text: string } })
+				.getSourceFile?.();
+			// In-process JS scope walker first. Layer A (variable refs,
+			// declarations, in-file specifiers, in-file type refs)
+			// resolves locally — no IPC. The walker returns a real
+			// ts.Symbol with identity stable across calls.
+			if (jsSymbolResolver && tsgoSf) {
+				const local = jsSymbolResolver.resolveIdentifier(tsgoNode, tsgoSf.fileName, tsgoSf.text);
+				if (local) {
+					nodeToSymbol.set(tsgoNode, local as unknown as TsgoSymbol);
+					return local as unknown as ts.Symbol;
 				}
 			}
-			const sym = project.checker.getSymbolAtLocation(tsgoNode);
+			// Layer C fallback. tsgo has two checker entry points with
+			// different coverage — `getSymbolAtPosition` resolves
+			// declaration-position identifiers (import/export specifier
+			// names) that the node-based API misses; `getSymbolAtLocation`
+			// covers a small remainder (object-spread method names etc.).
+			// Try position first to recover the previous prepass's recall
+			// without paying its eager batched cost.
+			let sym: TsgoSymbol | undefined;
+			if (tsgoSf) {
+				sym = project.checker.getSymbolAtPosition(tsgoSf.fileName, tsgoNode.end);
+			}
+			if (!sym) {
+				sym = project.checker.getSymbolAtLocation(tsgoNode);
+			}
 			nodeToSymbol.set(tsgoNode, sym);
 			return sym as unknown as ts.Symbol | undefined;
 		},

From 5be61d65e3ba8aa94f09c2f761ca4d86cdb3dd01 Mon Sep 17 00:00:00 2001
From: Johnson Chu <johnsoncodehk@gmail.com>
Date: Tue, 5 May 2026 11:01:50 +0800
Subject: [PATCH 18/19] =?UTF-8?q?cli:=20harden=20JS-symbols=20path=20?=
 =?UTF-8?q?=E2=80=94=20per-backend=20caches,=20--fix=20invalidation,=20kin?=
 =?UTF-8?q?d=20fallback?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Closes the three tsslint-side gaps the JS-symbols spike left open.

(1) Memory lifetime — per-backend caches
The bound-SourceFile + position-map caches in `tsgo-js-symbols.ts`
moved from module-level singletons into the closure of
`createJsSymbolResolver`. Each `createTsgoBackend` call constructs its
own resolver and registers it via `jsSymbolResolverRef.current`;
`backend.close()` calls `resolver.clear()` and unregisters. Multi-
project worker setups no longer share stale binds across snapshots,
and long-running CLI invocations don't accumulate cached ASTs across
projects.

(2) --fix invalidation
`getJsSourceFile` now compares the cached SF's `.text` against the
incoming text on every call. On mismatch (post-`--fix` rewrite), the
old SF and its position maps are dropped before re-binding. The
backend exposes a public `invalidateFile(fileName)` API; the worker's
`--fix` path calls it right after stashing the rewritten text in
`fileTextOverrides`, so the next `prepareFile` rebinds against the
post-fix content. Without this, scope queries on edited files would
return symbols from stale declarations.

(3) Kind remap robustness
`tsgo SyntaxKind` and `ts SyntaxKind` enum names overlap ~98% by name
but a handful diverge (tsgo-only `JSImportDeclaration`, `JSTypeAliasDeclaration`,
etc.). The previous remap returned the unmapped tsgo value as-is,
making position-key lookups silently miss. Added a parallel
position-only map (pos→first-node-at-span) consulted when the kind
key misses, so resolution falls through to "best-effort node at this
span" instead of "no answer at all". Recall on Dify unchanged
(2983/1621/50) — the affected node kinds happen to not be Identifier-
positioned in the rules under test, but the safety net is in place.

Test additions
- New test 6 in `tsgo-backend.test.ts`: invalidate + re-prepare on
  unchanged file, verify identifier still resolves and returns
  equivalent symbol. Exercises the change-detection short-circuit
  and the post-invalidate rebind path.

Bench (3 runs, --force):
  Dify web/ tsgo default          9.2-9.6s   2983/1621/50  (unchanged)
  Dify web/ tsgo --fix            9.4s       2983/1621/50  (no JS errors)

Tests: tsgo-backend 15/15 (was 12), program-host 17/17, cache-flow
50/50, meta-frameworks 8/8.
---
 packages/cli/lib/tsgo-backend.ts       |  64 +++++++---
 packages/cli/lib/tsgo-js-symbols.ts    | 166 ++++++++++++++++---------
 packages/cli/lib/worker.ts             |   5 +
 packages/cli/test/tsgo-backend.test.ts |  24 ++++
 4 files changed, 182 insertions(+), 77 deletions(-)

diff --git a/packages/cli/lib/tsgo-backend.ts b/packages/cli/lib/tsgo-backend.ts
index c8df6d9..46ed3ea 100644
--- a/packages/cli/lib/tsgo-backend.ts
+++ b/packages/cli/lib/tsgo-backend.ts
@@ -43,10 +43,15 @@ type Node = import('@typescript/native-preview/ast', { with: { 'resolution-mode'
 export interface TsgoBackend {
 	// ts.Program-shape adapter, fed to LinterContext.program().
 	getProgram(): ts.Program;
-	// Per-file prepass: walks the SF, collects every Identifier, resolves
-	// in one batched RPC, populates the symbol cache. Must be called for
-	// each file before rules run against it.
+	// Per-file setup before rules run: prototype-patches the tsgo Node
+	// hierarchy on first call, then bind-via-real-ts the file so the
+	// JS-side scope walker can answer in-process Symbol queries.
+	// Idempotent on unchanged text (cached).
 	prepareFile(fileName: string): void;
+	// Drop the JS-side bind cache for a file. Call after `--fix`
+	// rewrites file content so the next `prepareFile` re-binds against
+	// the new text.
+	invalidateFile(fileName: string): void;
 	// Tear down child process + free snapshot refs.
 	close(): void;
 }
@@ -471,6 +476,16 @@ export function createTsgoBackend(tsconfig: string): TsgoBackend {
 	// Files prepass'd this snapshot. Skip re-walk on repeat lint() calls.
 	const preparedFiles = new Set<string>();
 
+	// Per-backend JS Symbol resolver. Owns the bound-SF + position-map
+	// caches; releases them on close(). Replaces the module-level singleton
+	// so two backends in the same worker (multi-project lint) don't share
+	// stale caches across snapshots.
+	const jsSymbolResolver: import('./tsgo-js-symbols.js').JsSymbolResolver
+		= require('./tsgo-js-symbols.js').createJsSymbolResolver({
+			tsgoSyntaxKind: require('@typescript/native-preview/ast').SyntaxKind,
+		});
+	jsSymbolResolverRef.current = jsSymbolResolver;
+
 	const program = wrapProgram(project, nodeToSymbol);
 	currentProjectRef.project = project;
 	installNodeHandleHooks(require('@typescript/native-preview/sync') as TsgoSync);
@@ -483,13 +498,23 @@ export function createTsgoBackend(tsconfig: string): TsgoBackend {
 			if (preparedFiles.has(fileName)) return;
 			preparedFiles.add(fileName);
 			const t = Date.now();
-			prepareFile(project, fileName);
+			prepareFile(project, fileName, jsSymbolResolver);
 			prepareTotalMs += Date.now() - t;
 			prepareCount++;
 			if (trace && (prepareCount % 100 === 0 || prepareCount === 1)) {
 				console.error(`[tsgo-time] prepareFile #${prepareCount} cumul=${prepareTotalMs}ms`);
 			}
 		},
+		// Drop the JS-side bind for a single file. Called by the worker
+		// after `--fix` rewrites file content, so the next prepareFile
+		// re-binds against the new text and returns fresh symbols.
+		invalidateFile(fileName: string) {
+			preparedFiles.delete(fileName);
+			jsSymbolResolver.invalidate(fileName);
+			// `nodeToSymbol` is a WeakMap keyed by tsgo Node references;
+			// after the next ensureProgram() rebuild those Node refs are
+			// new, so the stale entries become garbage automatically.
+		},
 		close() {
 			if (trace) {
 				const s = getPrepareTimingSnapshot();
@@ -499,16 +524,21 @@ export function createTsgoBackend(tsconfig: string): TsgoBackend {
 					+ `(getSF=${s.getSF}ms bind=${s.bind}ms)`,
 				);
 			}
+			jsSymbolResolver.clear();
+			if (jsSymbolResolverRef.current === jsSymbolResolver) {
+				jsSymbolResolverRef.current = undefined;
+			}
 			api.close();
 		},
 	};
 }
 
-// Module-level resolver instance, lazily constructed on first prepareFile.
-// Survives across project setups within a single CLI invocation (its
-// internal SF cache is keyed by fileName so cross-project sharing of
-// shared files — node_modules types etc. — is safe).
-let jsSymbolResolver: ReturnType<typeof import('./tsgo-js-symbols.js').createJsSymbolResolver> | undefined;
+// Bridge so wrapChecker.getSymbolAtLocation can reach the active
+// backend's resolver without re-threading the wiring through every
+// adapter method. Set by createTsgoBackend on construction; cleared on
+// close(). Multi-project worker swaps it on each setup.
+const jsSymbolResolverRef: { current: import('./tsgo-js-symbols.js').JsSymbolResolver | undefined } = { current: undefined };
+
 
 // Cumulative timers — printed by createBackend.close() under
 // TSSLINT_TIME_TSGO=1. Negligible cost when the flag is off (single
@@ -535,7 +565,11 @@ export function getPrepareTimingSnapshot() {
 //      on Dify (5000 files); JS-side bind costs ~1.8s for the same
 //      workload and produces real ts.Symbol objects with stable
 //      identity.
-function prepareFile(project: Project, fileName: string): void {
+function prepareFile(
+	project: Project,
+	fileName: string,
+	jsSymbolResolver: import('./tsgo-js-symbols.js').JsSymbolResolver,
+): void {
 	const trace = process.env.TSSLINT_TIME_TSGO === '1';
 	const t0 = trace ? Date.now() : 0;
 	const sf = project.program.getSourceFile(fileName);
@@ -551,11 +585,8 @@ function prepareFile(project: Project, fileName: string): void {
 	if (sample) patchTsgoNodeListSpecies(sample);
 
 	const text = (sf as unknown as { text: string }).text;
-	jsSymbolResolver ??= require('./tsgo-js-symbols.js').createJsSymbolResolver({
-		tsgoSyntaxKind: require('@typescript/native-preview/ast').SyntaxKind,
-	});
 	const tBind = trace ? Date.now() : 0;
-	jsSymbolResolver!.prepareFile(fileName, text);
+	jsSymbolResolver.prepareFile(fileName, text);
 	if (trace) _prepareBind += Date.now() - tBind;
 }
 
@@ -676,8 +707,9 @@ function wrapChecker(
 			// declarations, in-file specifiers, in-file type refs)
 			// resolves locally — no IPC. The walker returns a real
 			// ts.Symbol with identity stable across calls.
-			if (jsSymbolResolver && tsgoSf) {
-				const local = jsSymbolResolver.resolveIdentifier(tsgoNode, tsgoSf.fileName, tsgoSf.text);
+			const resolver = jsSymbolResolverRef.current;
+			if (resolver && tsgoSf) {
+				const local = resolver.resolveIdentifier(tsgoNode, tsgoSf.fileName, tsgoSf.text);
 				if (local) {
 					nodeToSymbol.set(tsgoNode, local as unknown as TsgoSymbol);
 					return local as unknown as ts.Symbol;
diff --git a/packages/cli/lib/tsgo-js-symbols.ts b/packages/cli/lib/tsgo-js-symbols.ts
index 8e9dd1e..954c5bc 100644
--- a/packages/cli/lib/tsgo-js-symbols.ts
+++ b/packages/cli/lib/tsgo-js-symbols.ts
@@ -10,13 +10,6 @@
 // answers the same questions in ~360ms. Symbol is binder-level — type
 // computation isn't required, so the JS-side checker is bypassed entirely
 // (we use bind only, no createTypeChecker).
-//
-// PoC measurement showed:
-//   - parse + bind: ~0.36ms/file
-//   - lint-relevant query recall: 87% (vs whole-program ts.Program 94%)
-//   - the missing 7% are globals (Array, Promise — rules check by text
-//     anyway) and type-driven property access (falls back to tsgo for
-//     full precision)
 
 // Use captured-at-startup real ts. Plain `require('typescript')` here
 // would route through the tsgo facade installed by the worker — that
@@ -31,62 +24,12 @@ const BIND_OPTIONS: ts.CompilerOptions = {
 	allowJs: true,
 };
 
-// Per-file bound JS SourceFile cache. Keyed by fileName.
-const jsSourceFiles = new Map<string, ts.SourceFile>();
-
-// Per-file position → JS Node lookup. Built lazily on first symbol query
-// for a file, walks the JS AST once to index nodes by `pos:end:kind`.
-// Hash key matches tsgo Node's identity (same source positions, same
-// kind via the kind-name remap below).
 type PosKey = string;
-const positionMaps = new Map<string, Map<PosKey, ts.Node>>();
-
-// tsgo SyntaxKind → ts SyntaxKind name → ts SyntaxKind value remap.
-// tsgo's enum values are offset-shifted from ts's, but the names are
-// almost-identical (~98% overlap). Build the map lazily on first use.
-let kindRemap: Map<number, number> | undefined;
-
-function buildKindRemap(tsgoSyntaxKind: Record<string, string | number>): Map<number, number> {
-	const m = new Map<number, number>();
-	for (const k of Object.keys(tsgoSyntaxKind)) {
-		const v = tsgoSyntaxKind[k];
-		if (typeof v !== 'number') continue;
-		const tsValue = (ts.SyntaxKind as unknown as Record<string, number>)[k];
-		if (typeof tsValue === 'number') m.set(v, tsValue);
-	}
-	return m;
-}
-
-function tsgoKindToTs(tsgoKind: number, tsgoSyntaxKind: Record<string, string | number>): number {
-	if (!kindRemap) kindRemap = buildKindRemap(tsgoSyntaxKind);
-	return kindRemap.get(tsgoKind) ?? tsgoKind;
-}
 
 function key(pos: number, end: number, kind: number): PosKey {
 	return pos + ':' + end + ':' + kind;
 }
 
-function getJsSourceFile(fileName: string, text: string): ts.SourceFile {
-	let sf = jsSourceFiles.get(fileName);
-	if (sf) return sf;
-	sf = ts.createSourceFile(fileName, text, BIND_OPTIONS.target!, /*setParentNodes*/ true);
-	(ts as any).bindSourceFile(sf, BIND_OPTIONS);
-	jsSourceFiles.set(fileName, sf);
-	return sf;
-}
-
-function getPositionMap(sf: ts.SourceFile): Map<PosKey, ts.Node> {
-	let map = positionMaps.get(sf.fileName);
-	if (map) return map;
-	map = new Map();
-	(function walk(n: ts.Node) {
-		map!.set(key(n.pos, n.end, n.kind), n);
-		ts.forEachChild(n, walk);
-	})(sf);
-	positionMaps.set(sf.fileName, map);
-	return map;
-}
-
 // Scope walk: nearest enclosing scope's locals.has(name).
 function resolveByScope(jsNode: ts.Identifier): ts.Symbol | undefined {
 	const name = jsNode.text;
@@ -103,9 +46,89 @@ export interface JsSymbolResolverOptions {
 	tsgoSyntaxKind: Record<string, string | number>;
 }
 
+export type JsSymbolResolver = ReturnType<typeof createJsSymbolResolver>;
+
 export function createJsSymbolResolver(opts: JsSymbolResolverOptions) {
+	// All caches live in this closure. Each backend gets its own resolver
+	// instance; backend.close() invokes resolver.clear() to release memory.
+	const jsSourceFiles = new Map<string, ts.SourceFile>();
+
+	// Per-file position → JS Node lookup. Built lazily on first symbol
+	// query for a file. Walks the JS AST once and indexes nodes by
+	// `pos:end:tsKind`. Two index entries per node are populated when both
+	// kinds map (the node's tsgo-equivalent kind and an unkeyed (pos,end,0)
+	// fallback for unmapped tsgo kinds — see lookup logic below).
+	const positionMaps = new Map<string, Map<PosKey, ts.Node>>();
+	// Position-only fallback (pos:end → first node at that span). Used when
+	// the tsgo SyntaxKind name has no ts equivalent (e.g. tsgo-only
+	// `JSImportDeclaration`); we still return SOMETHING reasonable so the
+	// scope walker can attempt resolution.
+	const positionMapsFallback = new Map<string, Map<string, ts.Node>>();
+
+	// tsgo SyntaxKind value → ts SyntaxKind value, by name correspondence.
+	// 98% overlap; gaps fall through to the position-only fallback.
+	let kindRemap: Map<number, number> | undefined;
+	function getKindRemap(): Map<number, number> {
+		if (kindRemap) return kindRemap;
+		const m = new Map<number, number>();
+		for (const k of Object.keys(opts.tsgoSyntaxKind)) {
+			const v = opts.tsgoSyntaxKind[k];
+			if (typeof v !== 'number') continue;
+			const tsValue = (ts.SyntaxKind as unknown as Record<string, number>)[k];
+			if (typeof tsValue === 'number') m.set(v, tsValue);
+		}
+		kindRemap = m;
+		return m;
+	}
+
+	function bindFile(fileName: string, text: string): ts.SourceFile {
+		const sf = ts.createSourceFile(fileName, text, BIND_OPTIONS.target!, /*setParentNodes*/ true);
+		(ts as any).bindSourceFile(sf, BIND_OPTIONS);
+		return sf;
+	}
+
+	function getJsSourceFile(fileName: string, text: string): ts.SourceFile {
+		const cached = jsSourceFiles.get(fileName);
+		// Text-equality check: detects --fix rewrites (worker stashes new
+		// text in `fileTextOverrides`, next prepareFile passes the new
+		// text through to us). Stale binding would resolve to the wrong
+		// scope / declarations.
+		if (cached && cached.text === text) return cached;
+		if (cached) {
+			// Text changed; drop position maps too — node positions may
+			// have shifted.
+			positionMaps.delete(fileName);
+			positionMapsFallback.delete(fileName);
+		}
+		const sf = bindFile(fileName, text);
+		jsSourceFiles.set(fileName, sf);
+		return sf;
+	}
+
+	function getPositionMap(sf: ts.SourceFile): Map<PosKey, ts.Node> {
+		let map = positionMaps.get(sf.fileName);
+		if (map) return map;
+		map = new Map();
+		const fb = new Map<string, ts.Node>();
+		(function walk(n: ts.Node) {
+			map!.set(key(n.pos, n.end, n.kind), n);
+			// Position-only fallback: keep the first node we see at this
+			// span. Multiple nodes can share `pos:end` (e.g. an Identifier
+			// and its parent ExpressionStatement); first-write-wins is
+			// arbitrary but stable.
+			const k = n.pos + ':' + n.end;
+			if (!fb.has(k)) fb.set(k, n);
+			ts.forEachChild(n, walk);
+		})(sf);
+		positionMaps.set(sf.fileName, map);
+		positionMapsFallback.set(sf.fileName, fb);
+		return map;
+	}
+
 	return {
-		// Parse + bind a file. Idempotent.
+		// Parse + bind a file (idempotent on unchanged text). On text
+		// change (e.g. --fix rewrite), drops the cached SF + position
+		// maps and re-binds.
 		prepareFile(fileName: string, text: string): void {
 			getJsSourceFile(fileName, text);
 		},
@@ -115,14 +138,22 @@ export function createJsSymbolResolver(opts: JsSymbolResolverOptions) {
 		// Returns ts.Symbol (real one from JS bind) or undefined if no
 		// in-file binding (caller decides whether to fall back).
 		resolveIdentifier(
-			tsgoNode: { kind: number; pos: number; end: number; getSourceFile?: () => { fileName: string; text: string } },
+			tsgoNode: { kind: number; pos: number; end: number },
 			fileName: string,
 			text: string,
 		): ts.Symbol | undefined {
 			const sf = getJsSourceFile(fileName, text);
 			const map = getPositionMap(sf);
-			const tsKind = tsgoKindToTs(tsgoNode.kind, opts.tsgoSyntaxKind);
-			const jsNode = map.get(key(tsgoNode.pos, tsgoNode.end, tsKind));
+			const remap = getKindRemap();
+			const tsKind = remap.get(tsgoNode.kind);
+			let jsNode = tsKind !== undefined
+				? map.get(key(tsgoNode.pos, tsgoNode.end, tsKind))
+				: undefined;
+			// Position-only fallback when kind name didn't map (rare;
+			// covers tsgo-only kinds like JSImportDeclaration).
+			if (!jsNode) {
+				jsNode = positionMapsFallback.get(sf.fileName)!.get(tsgoNode.pos + ':' + tsgoNode.end);
+			}
 			if (!jsNode) return undefined;
 			// Declaration name: parent has the symbol directly.
 			const parent = jsNode.parent;
@@ -140,9 +171,22 @@ export function createJsSymbolResolver(opts: JsSymbolResolverOptions) {
 			}
 			return undefined;
 		},
+		// Drop a single file's bind + maps. Used by the worker after
+		// --fix writes new content, so the next prepareFile re-binds
+		// against fresh text. Idempotent.
+		invalidate(fileName: string): void {
+			jsSourceFiles.delete(fileName);
+			positionMaps.delete(fileName);
+			positionMapsFallback.delete(fileName);
+		},
+		// Drop everything. Called by backend.close() to release per-CLI
+		// invocation memory and avoid retaining ~MBs of bound ASTs across
+		// project setups in a long-running worker.
 		clear(): void {
 			jsSourceFiles.clear();
 			positionMaps.clear();
+			positionMapsFallback.clear();
+			kindRemap = undefined;
 		},
 	};
 }
diff --git a/packages/cli/lib/worker.ts b/packages/cli/lib/worker.ts
index f58ad39..f8ebb4f 100644
--- a/packages/cli/lib/worker.ts
+++ b/packages/cli/lib/worker.ts
@@ -471,6 +471,11 @@ function lint(fileName: string, fix: boolean, fileCache: FileCache, fileMtime: n
 			newText = core.applyTextChanges(baseText, textChanges);
 			fileTextOverrides.set(fileName, newText);
 			programDirty = true;
+			// On the tsgo backend, drop the JS-side bind cache for this
+			// file so the next prepareFile rebinds against post-fix text.
+			// (`programDirty` handles the tsgo-program rebuild for type
+			// queries; this handles the in-process Symbol cache.)
+			tsgoBackend?.invalidateFile(fileName);
 		}
 	}
 
diff --git a/packages/cli/test/tsgo-backend.test.ts b/packages/cli/test/tsgo-backend.test.ts
index 35dafc1..d72043d 100644
--- a/packages/cli/test/tsgo-backend.test.ts
+++ b/packages/cli/test/tsgo-backend.test.ts
@@ -140,6 +140,30 @@ try {
 	check('cwd is project dir', cwd === path.dirname(tsconfig));
 	const opts = program.getCompilerOptions();
 	check('compilerOptions returned', opts && typeof opts === 'object');
+
+	// ── Test 6: invalidateFile clears the JS-side bind cache ────────────
+	// After invalidate, prepareFile must re-bind. We can't directly observe
+	// the bind, but if the cache were stale we'd see a wrong-symbol return
+	// for an identifier whose enclosing context didn't actually change.
+	// Test exercises the no-op codepath: invalidate + re-prepare on the
+	// SAME unchanged file, verify the same identifier still resolves.
+	const sampleId = (function findFirst(n: any): any {
+		if (n.kind === idKind) return n;
+		let f: any;
+		n.forEachChild((c: any) => f = f ?? findFirst(c));
+		return f;
+	})(sf);
+	const symBefore = checker.getSymbolAtLocation(sampleId);
+	check('sample identifier resolves before invalidate', !!symBefore);
+	(handle as any).invalidateFile(target);
+	handle.prepareFile(target);
+	const symAfter = checker.getSymbolAtLocation(sampleId);
+	check('sample identifier still resolves after invalidate + re-prepare', !!symAfter);
+	check(
+		'invalidate-then-reprepare returns equivalent symbol',
+		symBefore?.name === symAfter?.name,
+		`before=${symBefore?.name} after=${symAfter?.name}`,
+	);
 }
 finally {
 	handle.close();

From 3e161c298c257990f62366da2a96b93335db856e Mon Sep 17 00:00:00 2001
From: Johnson Chu <johnsoncodehk@gmail.com>
Date: Tue, 5 May 2026 11:36:44 +0800
Subject: [PATCH 19/19] =?UTF-8?q?cli:=20per-file=20releaseFile=20=E2=80=94?=
 =?UTF-8?q?=20drop=20JS-bound=20SF=20after=20lint=20pass=20completes?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Was accumulating all linted files' bound SFs + position maps in Node
memory until backend.close(). For Dify (5000 files × ~30KB bound SF +
position maps), that pinned ~520 MB unnecessarily.

After lint() returns for a file, the JS-side bind serves no further
purpose — symbols for that file's identifiers have already been
queried, and rule code from later files queries against THEIR own
bound SFs. The bound SF can be released for GC.

  TsgoBackend.releaseFile(name)
    Drops the bound SourceFile + position maps from the per-backend
    JsSymbolResolver. Distinct from invalidateFile (which is for
    --fix rewrites and re-binds against new text); release simply
    discards because we're done.

  worker.lint(fileName, ...) → returns diagnostics
    Calls tsgoBackend?.releaseFile(fileName) just before return.

Memory bench (Dify web/, ~5000 .tsx, --force):

                     Node RSS    Go subprocess    Total
  ts.Program          2.27 GB    —                2.27 GB
  tsgo before         2.68 GB    1.59 GB          4.27 GB  (1.9×)
  tsgo after          2.16 GB    1.42 GB          3.58 GB  (1.58×)

Node-side dropped 524 MB; tsgo Node now smaller than ts.Program.
Total still higher than ts.Program (Go subprocess holds AST+types
independently), but the Node-side fat from accumulating bound SFs is
gone.

Multi-project scenario (tsslint own repo, 7 projects) NOT helped by
this — there the accumulation is in the tsgo client SourceFileCache
across snapshot boundaries, not in our per-file bind. That's an
upstream `@typescript/native-preview` cache lifecycle issue.

Speed unchanged (Dify 8.9-9.7s, 2983/1621/50). Tests still 15/15.
---
 packages/cli/lib/tsgo-backend.ts | 16 ++++++++++++++++
 packages/cli/lib/worker.ts       |  6 ++++++
 2 files changed, 22 insertions(+)

diff --git a/packages/cli/lib/tsgo-backend.ts b/packages/cli/lib/tsgo-backend.ts
index 46ed3ea..e76a31b 100644
--- a/packages/cli/lib/tsgo-backend.ts
+++ b/packages/cli/lib/tsgo-backend.ts
@@ -48,6 +48,12 @@ export interface TsgoBackend {
 	// JS-side scope walker can answer in-process Symbol queries.
 	// Idempotent on unchanged text (cached).
 	prepareFile(fileName: string): void;
+	// Drop the JS-side bind + position maps for one file. Call after
+	// the file's lint pass completes so the bound SF doesn't pin in
+	// memory across the rest of the project's lint. Subsequent lint of
+	// the SAME file (rare, e.g. `--fix` rewrite + re-lint) re-binds
+	// from current text via prepareFile.
+	releaseFile(fileName: string): void;
 	// Drop the JS-side bind cache for a file. Call after `--fix`
 	// rewrites file content so the next `prepareFile` re-binds against
 	// the new text.
@@ -515,6 +521,16 @@ export function createTsgoBackend(tsconfig: string): TsgoBackend {
 			// after the next ensureProgram() rebuild those Node refs are
 			// new, so the stale entries become garbage automatically.
 		},
+		// Drop the JS-side bind for a file after its lint pass is done.
+		// Distinct from invalidateFile: keeps `preparedFiles` membership
+		// (so a stray re-lint of the same file in the same backend
+		// re-binds rather than no-ops), but releases the bound SF +
+		// position maps for GC. Without this, all 5000 Dify files'
+		// bound SFs sit in memory simultaneously across a lint pass.
+		releaseFile(fileName: string) {
+			preparedFiles.delete(fileName);
+			jsSymbolResolver.invalidate(fileName);
+		},
 		close() {
 			if (trace) {
 				const s = getPrepareTimingSnapshot();
diff --git a/packages/cli/lib/worker.ts b/packages/cli/lib/worker.ts
index f8ebb4f..eb89de9 100644
--- a/packages/cli/lib/worker.ts
+++ b/packages/cli/lib/worker.ts
@@ -530,6 +530,12 @@ function lint(fileName: string, fix: boolean, fileCache: FileCache, fileMtime: n
 	// diagnostics on the same file (so `formatDiagnosticsWithColorAndContext`
 	// only computes line starts once per file).
 
+	// Done with this file — drop the JS-side bind so the bound SF and
+	// position maps don't pin in memory for the rest of the lint pass.
+	// Without this, all linted files' bound SFs accumulate (~30 KB each
+	// — adds up to ~150 MB on a 5000-file codebase).
+	tsgoBackend?.releaseFile(fileName);
+
 	return diagnostics;
 }