@shipispec/tsfix 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 owgreen-dev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,120 @@
+# TSC Defense Stack — `@shipispec/tsfix`
+
+Standalone npm package implementing **Layers 0–1** of the TypeScript error-recovery stack: in-process tsc validation + deterministic LSP auto-fix. Layers 2–4 (LLM mend) currently live in `spectoship2/src/pipeline/` and will move to a sister package `@shipispec/tsmend` per the roadmap.
+
+Read first:
+- `STATUS.md` — what's working, what's planned, current gaps
+- `ARCHITECTURE.md` — why the package is shaped the way it is
+- `tsc-defense-roadmap.md` — phased plan with open decisions
+- `CLAUDE.md` — working principles (small allowlist, fixture-pinned trust model)
+
+---
+
+## Source-of-truth map
+
+This package owns its TypeScript-error handling code outright. The shims in `spectoship2/` re-export from here, not the reverse.
+
+| Path | Role |
+|---|---|
+| `src/index.ts` | Public API (`runValidationLoop`, `runInProcessTsc`, `runLSPFixerPass`, `discoverTsFiles`) |
+| `src/validatorInProcess.ts` | In-process tsc with lib-path workaround (Layer 0) |
+| `src/tsLanguageServiceFixer.ts` | LSP auto-fixer using `getCodeFixesAtPosition` (Layer 1) |
+| `cli/run-stack.ts` | CLI: `tsx cli/run-stack.ts --workspace <path>` |
+| `benchmark/run-benchmark.ts` | Fixture harness (auto-discovers `fixtures/*/`) |
+| `fixtures/` | 14 hand-authored synthetic fixtures across 3 tiers |
+| `spectoship2/src/pipeline/validatorInProcess.ts` | **Re-export shim** → `@shipispec/tsfix` |
+| `spectoship2/src/pipeline/tsLanguageServiceFixer.ts` | **Re-export shim** → `@shipispec/tsfix` |
+
+---
+
+## How the layers fit together
+
+Per `ARCHITECTURE.md`, a TSC error has up to four chances to die before reaching a user. Layers -1 (prevention) and 2-4 (mend) live outside this package.
+
+```
+                    ┌─────────────────────────────────────────────────┐
+                    │ Layer -1: PREVENTION (in spectoship2/, not here)│
+                    │   packageGotchas, installedExports, priorExports│
+                    │   codeGenPrompts (rules injected into prompt)    │
+                    └────────────────────┬────────────────────────────┘
+                                         │ files written to disk
+                                         ▼
+  ┌────── @shipispec/tsfix ───────┴──────────────────────────┐
+  │                                                                  │
+  │   ┌─────────────────────────────────────────────┐               │
+  │   │ Layer 0: src/validatorInProcess.ts           │               │
+  │   │   in-process tsc → structured diagnostics    │               │
+  │   │   workspace lib-path override                │               │
+  │   └─────────────────────┬───────────────────────┘               │
+  │                         │ if errors                              │
+  │                         ▼                                        │
+  │   ┌─────────────────────────────────────────────┐               │
+  │   │ Layer 1: src/tsLanguageServiceFixer.ts       │               │
+  │   │   getCodeFixesAtPosition (5 SAFE codes)      │               │
+  │   │   signature-set progress check, max 5 iters  │               │
+  │   └─────────────────────┬───────────────────────┘               │
+  │                         │ re-validate; if errors remain          │
+  └─────────────────────────┼─────────────────────────────────────────┘
+                            ▼
+                 ┌─────────────────────────────────┐
+                 │ Layers 2-4: LLM MEND            │
+                 │   mendAgent / mendArchitect /   │
+                 │   multiFileMend / repairAgent   │
+                 │   (in spectoship2/, not here;   │
+                 │    moves to @shipispec/tsmend│
+                 │    in v0.2 per roadmap)         │
+                 └─────────────────────────────────┘
+```
+
+---
+
+## What to read first
+
+1. **`STATUS.md`** — current state, fixture catalog, recent fixes
+2. **`ARCHITECTURE.md`** — why the package is shaped the way it is (12 sections)
+3. **`tsc-defense-roadmap.md`** — phased plan with open decisions
+4. **`src/index.ts`** — public API entry point (`runValidationLoop`)
+5. **`src/tsLanguageServiceFixer.ts`** — Layer 1 fixer; understand `SAFE_FIXABLE_CODES`, the signature-set progress check, and the iteration loop
+6. **`src/validatorInProcess.ts`** — in-process tsc with the lib-path workaround that makes the package work inside the VS Code Extension Host
+
+---
+
+## Standalone harness
+
+```
+cli/run-stack.ts             # CLI: run stack on any workspace
+benchmark/run-benchmark.ts   # benchmark across all fixtures
+fixtures/                    # 14 hand-authored synthetic workspaces
+  _shared/                   # shared node_modules symlink target
+  clean-baseline/            # regression check (must stay green)
+  synthetic-*/               # 9 LSP-behavior fixtures (positive + negative)
+  api-drift-*/               # 4 version-drift fixtures (Zod 3 vs 4, React 18 vs 19, etc.)
+```
+
+### Run the CLI
+
+```
+cd /Users/ogg/Documents/microservices/Meta/spectoship2
+./node_modules/.bin/tsx ../tsc-defense-stack/cli/run-stack.ts --workspace <path>
+```
+
+Flags: `--json`, `--no-lsp`, `--verbose`, `--files <comma-list>`. Exit 0 = clean, 1 = errors remain, 2 = bad args.
+
+> Note: per Phase 0c of `tsc-defense-roadmap.md`, this package will gain its own local `node_modules` so commands run from inside the package directory. Today it shares `spectoship2/node_modules`.
+
+### Run the benchmark
+
+```
+cd /Users/ogg/Documents/microservices/Meta/spectoship2
+./node_modules/.bin/tsx ../tsc-defense-stack/benchmark/run-benchmark.ts
+```
+
+`--fixture <name>` to run a single fixture in isolation.
+
+### Current baseline
+
+**14/14 synthetic fixtures pass. LSP fixer auto-resolves 14/25 errors (56%).** The remaining errors are intentional non-fixes — TS7006 implicit-any, TS2741 missing prop, API-drift errors that need the mend layer. See `STATUS.md` § Fixture catalog for the full list.
+
+### Capturing real-failure fixtures
+
+Phase 3b in the roadmap. When a real spec-pipeline run produces a TSC error Layer 0-1 doesn't fix, snapshot the broken `.ts(x)` files into `fixtures/real-<timestamp>-<hash>/` with an `expected.json`. The fixture set then grows from production failures, not just synthetic ones.

package/bin/tsfix.mjs

@@ -0,0 +1,49 @@
+#!/usr/bin/env node
+/**
+ * Bin wrapper for `tsfix`. Resolves `tsx` from this package's own
+ * dependencies and spawns it against `cli/run-stack.ts`, forwarding all
+ * args. Inherits stdio so output/colors look identical to running tsx
+ * directly. Propagates the child exit code.
+ *
+ * Why a wrapper instead of pointing `bin` directly at `cli/run-stack.ts`:
+ * the CLI is a `.ts` file. `npm link` symlinks it into PATH, but execution
+ * fails because shells parse it as a shell script. A `.mjs` wrapper that
+ * Node can run directly fixes the local-dev story.
+ *
+ * NOT a substitute for the Phase 1a esbuild bundle: this wrapper requires
+ * `tsx` to be resolvable from the package's `node_modules`. For a true
+ * cold-start `npx @shipispec/tsfix ./project`, we need a bundled
+ * .js CLI. See tsc-defense-roadmap.md § Phase 1a.
+ */
+
+import { spawn } from "node:child_process";
+import { dirname, resolve } from "node:path";
+import { createRequire } from "node:module";
+import { fileURLToPath } from "node:url";
+
+const here = dirname(fileURLToPath(import.meta.url));
+const cliEntry = resolve(here, "..", "cli", "run-stack.ts");
+
+let tsxCli;
+try {
+	tsxCli = createRequire(import.meta.url).resolve("tsx/cli");
+} catch (err) {
+	process.stderr.write(
+		"error: tsc-defense requires `tsx` in this package's node_modules.\n" +
+		"       run: npm install\n" +
+		"       (or wait for the Phase 1a esbuild bundle that drops this dep.)\n",
+	);
+	process.exit(2);
+}
+
+const child = spawn(process.execPath, [tsxCli, cliEntry, ...process.argv.slice(2)], {
+	stdio: "inherit",
+});
+
+child.on("exit", (code, signal) => {
+	if (signal) {
+		process.kill(process.pid, signal);
+	} else {
+		process.exit(code ?? 0);
+	}
+});

package/cli/run-stack.ts

@@ -0,0 +1,195 @@
+/**
+ * Standalone TSC Defense Stack runner.
+ *
+ * Runs the deterministic layers (in-process tsc + LSP fixer) against an
+ * arbitrary workspace and reports per-layer outcomes. No LLM calls.
+ *
+ * Usage:
+ *   npx tsx tsc-defense-stack/cli/run-stack.ts --workspace <path>
+ *   npx tsx tsc-defense-stack/cli/run-stack.ts --workspace <path> --json
+ *   npx tsx tsc-defense-stack/cli/run-stack.ts --workspace <path> --no-lsp
+ *
+ * Why standalone: iterate on TSC reliability without running the full
+ * SpecToShip pipeline (~$1 per run). See tsc-defense-stack/CLAUDE.md.
+ */
+
+import * as path from "node:path";
+import * as fs from "node:fs";
+import {
+	runValidationLoop,
+	discoverTsFiles,
+	type ValidationLoopResult,
+} from "../src/index.js";
+
+interface CliArgs {
+	workspace: string;
+	json: boolean;
+	noLsp: boolean;
+	files: string[] | undefined;
+	verbose: boolean;
+}
+
+interface StackReport {
+	workspace: string;
+	errorsBefore: number;
+	lspFixer: {
+		ran: boolean;
+		fixesApplied: number;
+		filesEdited: string[];
+		iterations: number;
+	} | null;
+	errorsAfter: number;
+	remainingByCode: Record<string, number>;
+	remainingByFile: Record<string, number>;
+	passed: boolean;
+	elapsedMs: number;
+	logs?: string[];
+}
+
+function parseArgs(argv: string[]): CliArgs {
+	const args: CliArgs = {
+		workspace: "",
+		json: false,
+		noLsp: false,
+		files: undefined,
+		verbose: false,
+	};
+	for (let i = 0; i < argv.length; i++) {
+		const a = argv[i];
+		if (a === "--workspace" || a === "-w") {
+			args.workspace = argv[++i] ?? "";
+		} else if (a === "--json") {
+			args.json = true;
+		} else if (a === "--no-lsp") {
+			args.noLsp = true;
+		} else if (a === "--files") {
+			args.files = (argv[++i] ?? "").split(",").map((s) => s.trim()).filter(Boolean);
+		} else if (a === "--verbose" || a === "-v") {
+			args.verbose = true;
+		} else if (a === "--help" || a === "-h") {
+			printHelp();
+			process.exit(0);
+		}
+	}
+	if (!args.workspace) {
+		console.error("error: --workspace <path> is required");
+		printHelp();
+		process.exit(2);
+	}
+	return args;
+}
+
+function printHelp(): void {
+	console.error(`
+Usage: run-stack --workspace <path> [options]
+
+Options:
+  --workspace, -w <path>   Workspace root (required)
+  --files <list>           Comma-separated file paths to scope tsc/lsp to (default: all .ts/.tsx)
+  --no-lsp                 Skip Layer 0 LSP auto-fixer
+  --json                   Emit JSON report on stdout
+  --verbose, -v            Stream layer logs to stderr
+  --help, -h               Show this help
+
+Exit codes:
+  0  no errors after stack
+  1  errors remain after stack
+  2  bad arguments / harness error
+`.trim());
+}
+
+function makeLogger(captureLines: string[], verbose: boolean) {
+	const log = (level: string, msg: string) => {
+		const line = `[${level}] ${msg}`;
+		captureLines.push(line);
+		if (verbose) process.stderr.write(line + "\n");
+	};
+	return {
+		info: (m: string) => log("info", m),
+		warn: (m: string) => log("warn", m),
+		error: (m: string) => log("error", m),
+	};
+}
+
+function printHumanReport(r: StackReport): void {
+	const w = process.stderr;
+	w.write(`\nTSC Defense Stack — ${r.workspace}\n`);
+	w.write(`  errors before: ${r.errorsBefore}\n`);
+	if (r.lspFixer?.ran) {
+		w.write(
+			`  LSP fixer:     applied ${r.lspFixer.fixesApplied} fix(es) in ${r.lspFixer.iterations} iter(s); edited ${r.lspFixer.filesEdited.length} file(s)\n`,
+		);
+	} else {
+		w.write(`  LSP fixer:     skipped\n`);
+	}
+	w.write(`  errors after:  ${r.errorsAfter}\n`);
+	if (r.errorsAfter > 0) {
+		const top = Object.entries(r.remainingByCode)
+			.sort((a, b) => b[1] - a[1])
+			.slice(0, 8);
+		w.write(`  top remaining codes:\n`);
+		for (const [code, n] of top) {
+			w.write(`    ${code.padEnd(8)} ${n}\n`);
+		}
+	}
+	w.write(`  elapsed:       ${r.elapsedMs}ms\n`);
+	w.write(`  ${r.passed ? "✓ PASS" : "✗ FAIL"}\n\n`);
+}
+
+async function main(): Promise<number> {
+	const args = parseArgs(process.argv.slice(2));
+	const workspaceRoot = path.resolve(args.workspace);
+	if (!fs.existsSync(workspaceRoot)) {
+		console.error(`error: workspace not found: ${workspaceRoot}`);
+		return 2;
+	}
+	if (!fs.existsSync(path.join(workspaceRoot, "tsconfig.json"))) {
+		console.error(`error: no tsconfig.json in ${workspaceRoot}`);
+		return 2;
+	}
+
+	const logs: string[] = [];
+	const logger = makeLogger(logs, args.verbose);
+
+	const targetFiles = args.files ?? discoverTsFiles(workspaceRoot);
+	if (targetFiles.length === 0) {
+		console.error("error: no .ts/.tsx files found in workspace");
+		return 2;
+	}
+
+	const loop: ValidationLoopResult = runValidationLoop({
+		workspaceRoot,
+		targetFiles,
+		skipLSPFixer: args.noLsp,
+		logger,
+	});
+
+	const report: StackReport = {
+		workspace: path.relative(process.cwd(), workspaceRoot) || workspaceRoot,
+		errorsBefore: loop.errorsBefore,
+		lspFixer: args.noLsp
+			? { ran: false, fixesApplied: 0, filesEdited: [], iterations: 0 }
+			: loop.lspFixer,
+		errorsAfter: loop.errorsAfter,
+		remainingByCode: loop.remainingByCode,
+		remainingByFile: loop.remainingByFile,
+		passed: loop.passed,
+		elapsedMs: loop.elapsedMs,
+	};
+
+	if (args.json) {
+		process.stdout.write(JSON.stringify(report, null, 2) + "\n");
+	} else {
+		printHumanReport(report);
+	}
+
+	return report.passed ? 0 : 1;
+}
+
+main().then(
+	(code) => process.exit(code),
+	(err) => {
+		console.error("harness error:", err instanceof Error ? err.stack : err);
+		process.exit(2);
+	},
+);

package/package.json

@@ -0,0 +1,68 @@
+{
+	"name": "@shipispec/tsfix",
+	"version": "0.1.0",
+	"description": "Reusable TypeScript error-recovery agent. Validates LLM-generated TS code, auto-fixes deterministic error classes via the TS Language Service, and exposes hooks for LLM-driven repair.",
+	"keywords": [
+		"typescript",
+		"tsc",
+		"error-recovery",
+		"language-service",
+		"code-fix",
+		"auto-fix",
+		"llm",
+		"ai-codegen",
+		"validator",
+		"linter"
+	],
+	"license": "MIT",
+	"author": "owgreen-dev <ogreenowow@gmail.com>",
+	"homepage": "https://github.com/owgreen-dev/spectoship-meta/tree/main/tsc-defense-stack#readme",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/owgreen-dev/spectoship-meta.git",
+		"directory": "tsc-defense-stack"
+	},
+	"bugs": {
+		"url": "https://github.com/owgreen-dev/spectoship-meta/issues"
+	},
+	"engines": {
+		"node": ">=20.9.0"
+	},
+	"type": "module",
+	"main": "src/index.ts",
+	"types": "src/index.ts",
+	"exports": {
+		".": "./src/index.ts",
+		"./validation": "./src/validatorInProcess.ts",
+		"./lsp-fixer": "./src/tsLanguageServiceFixer.ts"
+	},
+	"bin": {
+		"tsfix": "./bin/tsfix.mjs"
+	},
+	"files": [
+		"src",
+		"!src/**/*.test.ts",
+		"cli",
+		"bin",
+		"README.md",
+		"LICENSE"
+	],
+	"scripts": {
+		"setup-fixtures": "node -e \"require('fs').existsSync('fixtures/_shared/node_modules')||require('child_process').execSync('npm install --prefix fixtures/_shared',{stdio:'inherit'})\"",
+		"prebenchmark": "npm run setup-fixtures",
+		"pretest": "npm run setup-fixtures",
+		"benchmark": "tsx benchmark/run-benchmark.ts",
+		"run-stack": "tsx cli/run-stack.ts",
+		"test": "vitest run",
+		"check-types": "tsc --noEmit"
+	},
+	"devDependencies": {
+		"@types/node": "^20.0.0",
+		"tsx": "^4.20.6",
+		"typescript": "^5.9.3",
+		"vitest": "^3.2.4"
+	},
+	"peerDependencies": {
+		"typescript": ">=5.0.0"
+	}
+}

package/src/index.ts

@@ -0,0 +1,202 @@
+/**
+ * @shipispec/tsfix — public API.
+ *
+ * A reusable TypeScript error-recovery agent. Validates LLM-generated (or any)
+ * TypeScript code via in-process tsc, auto-fixes deterministic error classes
+ * (TS2304/2305/2552/2724) via TypeScript's built-in code-fix engine, and
+ * exposes hooks for LLM-driven repair (planned, not yet shipped).
+ *
+ * ## Quick start (library)
+ *
+ * ```ts
+ * import { runValidationLoop } from "@shipispec/tsfix";
+ *
+ * const result = await runValidationLoop({
+ *   workspaceRoot: "/path/to/your/project",
+ *   targetFiles: ["src/index.ts", "src/utils.ts"],
+ * });
+ *
+ * console.log(result.passed, result.errorsAfter, result.lspFixer.fixesApplied);
+ * ```
+ *
+ * ## Quick start (CLI)
+ *
+ * ```
+ * npx @shipispec/tsfix --workspace ./my-project
+ * ```
+ *
+ * ## Layered API
+ *
+ * - `runValidationLoop` — full deterministic loop (recommended entry point)
+ * - `runInProcessTsc` — just type-check, returns structured diagnostics
+ * - `runLSPFixerPass` — just the auto-fix pass, edits files in place
+ *
+ * ## What it doesn't do (yet)
+ *
+ * LLM-driven repair (the mend-agent layers from the spectoship pipeline) is
+ * not exported here yet. They depend on internal types (ParsedTask) that need
+ * to be redesigned as opaque interfaces before they can be moved into this
+ * package. v0.2 target.
+ */
+
+export { runInProcessTsc, isInProcessTscEnabled, resetInProcessTscCache } from "./validatorInProcess.js";
+export type { InProcessTscOptions, InProcessTscResult } from "./validatorInProcess.js";
+
+export { runLSPFixerPass, isLSPFixerEnabled, resetLSPFixerCache } from "./tsLanguageServiceFixer.js";
+export type { LSPFixerOptions, LSPFixerResult, LSPFixerLogger } from "./tsLanguageServiceFixer.js";
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import {
+	runInProcessTsc,
+	resetInProcessTscCache,
+	type InProcessTscResult,
+} from "./validatorInProcess.js";
+import { runLSPFixerPass } from "./tsLanguageServiceFixer.js";
+
+/** Logger shape required by the validation/fix loop. Plain object with three methods. */
+export interface Logger {
+	info(msg: string): void;
+	warn(msg: string): void;
+	error(msg: string): void;
+}
+
+export interface ValidationLoopOptions {
+	/** Absolute path to the workspace (must contain `tsconfig.json`). */
+	workspaceRoot: string;
+	/**
+	 * Files to scope the type-check + fix to. If omitted, all .ts/.tsx files
+	 * under `workspaceRoot` (excluding node_modules, .next, dist, build, .git)
+	 * are discovered.
+	 */
+	targetFiles?: string[];
+	/** Skip Layer 0 LSP auto-fixer. Default false. */
+	skipLSPFixer?: boolean;
+	/** Default: a no-op logger. Pass your own to capture layer events. */
+	logger?: Logger;
+}
+
+export interface ValidationLoopResult {
+	passed: boolean;
+	errorsBefore: number;
+	errorsAfter: number;
+	lspFixer: {
+		ran: boolean;
+		fixesApplied: number;
+		filesEdited: string[];
+		iterations: number;
+	};
+	remainingByCode: Record<string, number>;
+	remainingByFile: Record<string, number>;
+	diagnostics: InProcessTscResult["diagnostics"];
+	elapsedMs: number;
+}
+
+const noopLogger: Logger = {
+	info: () => {},
+	warn: () => {},
+	error: () => {},
+};
+
+/**
+ * Discover all `.ts` / `.tsx` files under a workspace, excluding common
+ * non-source dirs. Skips `.d.ts` declaration files.
+ */
+export function discoverTsFiles(workspaceRoot: string): string[] {
+	const out: string[] = [];
+	const skip = new Set(["node_modules", ".next", "dist", "build", ".git", "out", "coverage"]);
+	const walk = (dir: string): void => {
+		let entries: fs.Dirent[];
+		try {
+			entries = fs.readdirSync(dir, { withFileTypes: true });
+		} catch {
+			return;
+		}
+		for (const e of entries) {
+			if (e.isDirectory()) {
+				if (skip.has(e.name)) {
+					continue;
+				}
+				walk(path.join(dir, e.name));
+			} else if (e.isFile() && !e.name.endsWith(".d.ts")) {
+				if (e.name.endsWith(".ts") || e.name.endsWith(".tsx")) {
+					out.push(path.relative(workspaceRoot, path.join(dir, e.name)));
+				}
+			}
+		}
+	};
+	walk(workspaceRoot);
+	return out;
+}
+
+/**
+ * Run the full deterministic validation + fix loop:
+ *
+ *   1. In-process tsc → capture baseline diagnostics
+ *   2. If errors AND not `skipLSPFixer`, run Layer 0 LSP auto-fix
+ *   3. If fixes were applied, re-run in-process tsc to capture post-fix state
+ *   4. Return aggregated result
+ *
+ * Throws on missing `tsconfig.json` or workspace path.
+ */
+export function runValidationLoop(opts: ValidationLoopOptions): ValidationLoopResult {
+	const { workspaceRoot, skipLSPFixer = false } = opts;
+	const logger = opts.logger ?? noopLogger;
+
+	if (!fs.existsSync(workspaceRoot)) {
+		throw new Error(`workspace not found: ${workspaceRoot}`);
+	}
+	if (!fs.existsSync(path.join(workspaceRoot, "tsconfig.json"))) {
+		throw new Error(`no tsconfig.json in ${workspaceRoot}`);
+	}
+
+	const targetFiles = opts.targetFiles ?? discoverTsFiles(workspaceRoot);
+	const startMs = Date.now();
+
+	resetInProcessTscCache();
+	const before = runInProcessTsc({ workspaceRoot, generatedFiles: targetFiles, logger });
+	const errorsBefore = before.diagnostics.filter((d) => d.category === "error").length;
+
+	let after = before;
+	let lspFixer = {
+		ran: false,
+		fixesApplied: 0,
+		filesEdited: [] as string[],
+		iterations: 0,
+	};
+
+	if (errorsBefore > 0 && !skipLSPFixer) {
+		const lsp = runLSPFixerPass({ workspaceRoot, targetFiles, logger });
+		lspFixer = {
+			ran: true,
+			fixesApplied: lsp.fixesApplied,
+			filesEdited: lsp.filesEdited,
+			iterations: lsp.iterations,
+		};
+		if (lsp.fixesApplied > 0) {
+			resetInProcessTscCache();
+			after = runInProcessTsc({ workspaceRoot, generatedFiles: targetFiles, logger });
+		}
+	}
+
+	const errorDiags = after.diagnostics.filter((d) => d.category === "error");
+	const errorsAfter = errorDiags.length;
+
+	const remainingByCode: Record<string, number> = {};
+	const remainingByFile: Record<string, number> = {};
+	for (const d of errorDiags) {
+		remainingByCode[d.code] = (remainingByCode[d.code] ?? 0) + 1;
+		remainingByFile[d.file] = (remainingByFile[d.file] ?? 0) + 1;
+	}
+
+	return {
+		passed: errorsAfter === 0,
+		errorsBefore,
+		errorsAfter,
+		lspFixer,
+		remainingByCode,
+		remainingByFile,
+		diagnostics: after.diagnostics,
+		elapsedMs: Date.now() - startMs,
+	};
+}