@shipispec/tsfix 0.1.0 → 0.3.0

package/dist/types/index.d.ts

@@ -0,0 +1,176 @@
+/**
+ * @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
+ *
+ * ## Public types for downstream LLM-mend integrations
+ *
+ * - `Diagnostic` — single tsc error (re-exported from `runInProcessTsc`)
+ * - `MendContext` — input contract for a Layer 2–4 LLM-mend agent
+ * - `LayerEvent` — per-layer event shape for streaming telemetry
+ *
+ * The mend agents themselves (`@shipispec/tsmend`, planned) consume these
+ * types but are not shipped from this package — `tsfix` stays Layer 0–1
+ * deterministic.
+ */
+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 { type InProcessTscResult } from "./validatorInProcess.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;
+    /**
+     * Run the LSP fixer in memory but do NOT persist edits to disk. The
+     * returned `lspFixer.filesEdited` lists files that *would* have been
+     * written. Useful for previewing changes before letting tsfix mutate a
+     * workspace. Default false.
+     */
+    dryRun?: 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;
+}
+/**
+ * Discover all `.ts` / `.tsx` files under a workspace, excluding common
+ * non-source dirs. Skips `.d.ts` declaration files.
+ */
+export declare function discoverTsFiles(workspaceRoot: string): string[];
+/**
+ * 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 declare function runValidationLoop(opts: ValidationLoopOptions): ValidationLoopResult;
+/**
+ * Single tsc diagnostic. Re-exported from `runInProcessTsc`'s result type
+ * so consumers building a `MendContext` don't have to dig the shape out of
+ * `InProcessTscResult["diagnostics"][number]`.
+ */
+export type Diagnostic = InProcessTscResult["diagnostics"][number];
+/**
+ * Input contract for a Layer 2–4 LLM-mend agent.
+ *
+ * Pattern:
+ *   1. Run `runValidationLoop` (Layer 0/1).
+ *   2. If `result.errorsAfter > 0`, build a `MendContext` from the
+ *      surviving diagnostics + whatever task/spec context your pipeline has.
+ *   3. Hand off to a mend agent (e.g. `@shipispec/tsmend`).
+ *
+ * Required fields: `workspaceRoot`, `diagnostics`, `erroredFiles`.
+ * Everything else is optional — leave fields out if your pipeline doesn't
+ * carry them.
+ */
+export interface MendContext {
+    /** Absolute path to the workspace (must contain `tsconfig.json`). */
+    workspaceRoot: string;
+    /** Diagnostics that survived Layer 0/1 and need higher-layer repair. */
+    diagnostics: Diagnostic[];
+    /** Absolute paths of files containing the surviving diagnostics. */
+    erroredFiles: string[];
+    /** Optional one-line summary of what the failing code was supposed to do. */
+    taskDescription?: string;
+    /** Optional Markdown spec the code is implementing. Helps the LLM understand intent. */
+    featureSpecText?: string;
+    /** Optional testable acceptance criteria from the spec. */
+    acceptanceCriteria?: string;
+    /** Other tasks in the same feature, with their files and current status. */
+    siblingTasks?: Array<{
+        description: string;
+        files: string[];
+        status: "pending" | "completed" | "failed";
+    }>;
+    /** Public API surface from earlier completed tasks (helps prevent re-defining symbols). */
+    priorTaskExports?: string;
+    /** Compact type signatures of installed npm dependencies (helps prevent API hallucination). */
+    installedTypes?: string;
+}
+/**
+ * Per-layer event for streaming telemetry across the validate → fix → mend
+ * chain. Designed for an `onLayerEvent` callback (added in a future minor
+ * release) rather than accumulating in a result array — a workspace with
+ * 200 errors emits ~1000 events.
+ *
+ * Layer assignments:
+ *   0 = prevention (prompt rules, exported-API injection — caller's problem)
+ *   1 = tsfix LSP fixer (this package)
+ *   2 = single-file LLM mend
+ *   3 = multi-file LLM mend (blast-radius search/replace)
+ *   4 = stub-and-continue (escape hatch)
+ */
+export interface LayerEvent {
+    /** Which layer ran. */
+    layer: 0 | 1 | 2 | 3 | 4;
+    /** TypeScript error code being acted on (e.g. 2304, 2339, 7006). */
+    errorCode: number;
+    /** True if the error was resolved by this layer. */
+    fixed: boolean;
+    /** Wall-clock time spent on this attempt. */
+    latencyMs: number;
+    /** USD cost (LLM tokens). Undefined for deterministic layers. */
+    costUsd?: number;
+    /** `Date.now()` at emission. */
+    ts: number;
+}

package/dist/types/tsLanguageServiceFixer.d.ts

@@ -0,0 +1,124 @@
+/**
+ * TS Language Service Fixer — Sprint G / Sprint J (2026-05-03).
+ *
+ * Layer 0 of the mend stack. Uses TypeScript's built-in `LanguageService.getCodeFixesAtPosition`
+ * (the same engine VS Code's Quick Fix uses) to resolve common errors *deterministically*,
+ * before we spend a single LLM call on them.
+ *
+ * Why this exists: ~80% of generated-code TS errors fall into a small set of
+ * boring categories that the compiler already knows how to fix:
+ *
+ *   - TS2304 "Cannot find name X"           → auto-import
+ *   - TS2305 "no exported member named X"   → did-you-mean rename
+ *   - TS2551 "Property X does not exist on Y. Did you mean Z?" → spelling fix
+ *   - TS2552 "Cannot find name X. Did you mean Y?" → spelling fix
+ *   - TS2724 "no exported member, did you mean Y?" → import rename
+ *
+ * For these, the fixer is free (no LLM), fast (~ms), and deterministic.
+ * The LLM mend stack only gets called for *interesting* errors that require
+ * semantic reasoning (signature drift, missing logic, package gotchas).
+ *
+ * Conservative coverage: we only apply fixes for codes whose auto-fixes are
+ * unambiguous. Codes like TS7006 (implicit any) and TS2741 (missing property)
+ * are skipped — those need human intent to choose the right type or default
+ * value, and a wrong auto-fix introduces silent bugs.
+ *
+ * Iteration cap: 5 passes. After each pass we re-validate; cascades like
+ * "rename import → rename type annotation → rename method call" can need 3-4
+ * hops to converge. The signature-set progress check stops sooner if no new
+ * errors appear. If errors remain after pass 5, escalate to LLM mend.
+ *
+ * Feature flag: `SPECTOSHIP_TS_LSP_FIXER=false` opts out (default: ON).
+ */
+import * as ts from "typescript";
+export interface LSPFixerLogger {
+    info(msg: string): void;
+    warn(msg: string): void;
+    error(msg: string): void;
+}
+export interface LSPFixerOptions {
+    workspaceRoot: string;
+    /** Files where errors were detected. Limits the fix scope. */
+    targetFiles: string[];
+    logger: LSPFixerLogger;
+    /** Max iterations (default 5). Signature-set progress check stops sooner. */
+    maxIterations?: number;
+    /**
+     * When true, run the full fix loop in memory but do NOT persist edits to
+     * disk. Returned `LSPFixerResult` is identical otherwise — `filesEdited`
+     * lists the files that *would* have been written, `fixesApplied` is the
+     * count of fixes the loop computed. Use to preview what tsfix would do
+     * before letting it modify a workspace.
+     */
+    dryRun?: boolean;
+}
+export interface LSPFixerResult {
+    /** Number of fixes successfully applied across all iterations. */
+    fixesApplied: number;
+    /** Files whose contents were modified on disk. */
+    filesEdited: string[];
+    /** Iteration count when fixer stopped (1 if it converged on first pass). */
+    iterations: number;
+    /** When true, every diagnostic was auto-fixable and resolved. Caller can skip LLM mend. */
+    allResolved: boolean;
+    /** Errors remaining after the last iteration (caller passes these to LLM mend). */
+    remainingErrors: Array<{
+        file: string;
+        line: number;
+        column: number;
+        code: string;
+        message: string;
+    }>;
+}
+/**
+ * Apply LSP code-fixes to all diagnostics in the workspace whose error code
+ * is in SAFE_FIXABLE_CODES. Writes edits back to disk. Re-runs ts diagnostics
+ * after each pass; stops when no further fixable errors remain or
+ * maxIterations is reached.
+ *
+ * Throws on host setup failure (missing tsconfig, etc.) — callers should
+ * catch and fall through to LLM mend.
+ */
+export declare function runLSPFixerPass(opts: LSPFixerOptions): LSPFixerResult;
+/**
+ * When the LanguageService returns multiple code-fix candidates, only apply
+ * if they're textually equivalent (same edits on the same files). This
+ * conservatively skips ambiguous cases (e.g., import from `lib/foo` vs
+ * `lib/bar` where both export `Foo`) where guessing wrong is worse than
+ * deferring to the LLM.
+ */
+/**
+ * @internal Compute a stable `(file, start, code)` signature for each fixable
+ * error. Used by the iteration loop's stuck-loop detector.
+ */
+export declare function computeErrorSignatures(errors: readonly {
+    file: string;
+    start: number;
+    code: number;
+}[]): Set<string>;
+/**
+ * @internal True if `a` and `b` contain the same members. Used to decide
+ * whether the iteration loop is stuck (same error set across passes) vs.
+ * making genuine progress (set membership changed even if size didn't).
+ */
+export declare function signatureSetsEqual(a: Set<string>, b: Set<string>): boolean;
+/**
+ * @internal True if every fix in `fixes` produces identical text edits.
+ * Used to decide whether multiple candidate fixes for one error are safe to
+ * pick automatically (identical = unambiguous; different = abstain).
+ */
+export declare function fixesAreEquivalent(fixes: readonly ts.CodeFixAction[]): boolean;
+/**
+ * @internal Apply a CodeFixAction's text changes to in-memory snapshots.
+ * Returns the number of changes successfully applied. Bumps script versions
+ * so the LanguageService re-parses on next call. Skips edits to files not
+ * already in `snapshots` (defensive — won't create new files unbeknownst).
+ */
+export declare function applyFixToSnapshots(fix: ts.CodeFixAction, snapshots: Map<string, {
+    content: string;
+    version: number;
+}>): number;
+/** Whether the LSP fixer is enabled (env-flag opt-out). Default ON. */
+export declare function isLSPFixerEnabled(): boolean;
+/** Reset internal caches (for tests). No-op currently — service is created per-call. */
+export declare function resetLSPFixerCache(): void;

package/dist/types/validatorInProcess.d.ts

@@ -0,0 +1,64 @@
+/**
+ * In-process TypeScript validator (Phase 5 — TSC iron-clad).
+ *
+ * Replaces the `tsc --noEmit` shell exec with `ts.createProgram` +
+ * `getPreEmitDiagnostics()`. Three wins over shelling:
+ *
+ *   1. **Structured diagnostics** — `{file, start, length, code, messageText,
+ *      category, relatedInformation}` natively, no regex parsing of tsc text
+ *      output. Feeds Layer 2's symbol tracer directly.
+ *
+ *   2. **Speed** — long-lived Program per workspace caches lib files,
+ *      transitive deps, and tsconfig parse. Cold start is comparable; warm
+ *      validation is ~5-10× faster than spawning a fresh tsc process.
+ *
+ *   3. **Diagnostic enrichment** — we have the AST in hand, so each error
+ *      can carry the offending node's source span and aliased symbol info,
+ *      which the shell tsc doesn't provide.
+ *
+ * Backwards compatibility: feature-flagged via `SPECTOSHIP_TSC_INPROCESS`
+ * env var. Shell tsc remains the default until we measure parity on real
+ * projects.
+ */
+export interface InProcessTscResult {
+    passed: boolean;
+    /** Diagnostic messages formatted in the same shape as `tsc` output. */
+    output: string;
+    /** Structured per-error data — drives Layer 2 cross-file tracer. */
+    diagnostics: Array<{
+        file: string;
+        line: number;
+        column: number;
+        code: string;
+        message: string;
+        category: "error" | "warning" | "message" | "suggestion";
+    }>;
+    /** Number of lines of output for log truncation. */
+    lineCount: number;
+}
+export interface InProcessTscOptions {
+    workspaceRoot: string;
+    /** Optional list of files to filter diagnostics to (matches shell tsc filter). */
+    generatedFiles?: string[];
+    logger: {
+        info(msg: string): void;
+        warn(msg: string): void;
+        error(msg: string): void;
+    };
+}
+/**
+ * Run tsc in-process. Compatible with the shell-based ToolResult shape
+ * so the caller can swap implementations transparently.
+ */
+export declare function runInProcessTsc(opts: InProcessTscOptions): InProcessTscResult;
+/** Reset cache (for tests + when workspace switches). */
+export declare function resetInProcessTscCache(): void;
+/**
+ * Whether the in-process path is enabled. Defaults to ON as of Sprint J
+ * (2026-05-03) — shell tsc consistently times out at 60s on Node 23 due to
+ * the documented tsc startup-pause bug, blocking every code-gen task.
+ * In-process is also 5-10× faster on warm runs because the Program is reused.
+ *
+ * Set `SPECTOSHIP_TSC_INPROCESS=false` to opt out.
+ */
+export declare function isInProcessTscEnabled(): boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@shipispec/tsfix",
-	"version": "0.1.0",
+	"version": "0.3.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",
@@ -16,38 +16,40 @@
 	],
 	"license": "MIT",
 	"author": "owgreen-dev <ogreenowow@gmail.com>",
-	"homepage": "https://github.com/owgreen-dev/spectoship-meta/tree/main/tsc-defense-stack#readme",
+	"homepage": "https://github.com/owgreen-dev/tsfix#readme",
 	"repository": {
 		"type": "git",
-		"url": "git+https://github.com/owgreen-dev/spectoship-meta.git",
-		"directory": "tsc-defense-stack"
+		"url": "git+https://github.com/owgreen-dev/tsfix.git"
 	},
 	"bugs": {
-		"url": "https://github.com/owgreen-dev/spectoship-meta/issues"
+		"url": "https://github.com/owgreen-dev/tsfix/issues"
 	},
 	"engines": {
 		"node": ">=20.9.0"
 	},
 	"type": "module",
-	"main": "src/index.ts",
-	"types": "src/index.ts",
+	"main": "./dist/index.js",
+	"types": "./dist/index.d.ts",
 	"exports": {
-		".": "./src/index.ts",
-		"./validation": "./src/validatorInProcess.ts",
-		"./lsp-fixer": "./src/tsLanguageServiceFixer.ts"
+		".": {
+			"types": "./dist/index.d.ts",
+			"import": "./dist/index.js"
+		}
 	},
 	"bin": {
-		"tsfix": "./bin/tsfix.mjs"
+		"tsfix": "./dist/cli.js"
 	},
 	"files": [
-		"src",
-		"!src/**/*.test.ts",
-		"cli",
-		"bin",
+		"dist",
 		"README.md",
-		"LICENSE"
+		"LICENSE",
+		"CHANGELOG.md"
 	],
 	"scripts": {
+		"build": "node scripts/build.mjs",
+		"matrix": "node scripts/run-matrix.mjs",
+		"capture": "node scripts/capture-fixture.mjs",
+		"prepack": "npm run build",
 		"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",
@@ -58,6 +60,7 @@
 	},
 	"devDependencies": {
 		"@types/node": "^20.0.0",
+		"esbuild": "^0.28.0",
 		"tsx": "^4.20.6",
 		"typescript": "^5.9.3",
 		"vitest": "^3.2.4"

package/bin/tsfix.mjs

@@ -1,49 +0,0 @@
-#!/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

@@ -1,195 +0,0 @@
-/**
- * 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);
-	},
-);