@shipispec/tsfix 0.2.0 → 0.4.0

package/CHANGELOG.md

@@ -4,8 +4,70 @@ All notable changes to `@shipispec/tsfix` are documented here. Format follows [K
 
 ## [Unreleased]
 
+## [0.4.0] - 2026-05-14
+
+**Layer 2 LLM mend is now in-package.** The previously-planned sister package `@shipispec/tsmend` has been folded into `tsfix` so the deterministic Layer 0/1 stack and the LLM-driven Layer 2 stack ship as one. This reverses the v0.3.0 sister-package decision (D3) — see roadmap update.
+
+### Added (Layer 2 — single-file LLM mend)
+- **`getTypeContext(opts)`** — TS Language Service helper. Resolves an error site to its declaring type via `getTypeAtLocation()` + `getDeclarations()`, slices ±3 lines around the error site and ±20 lines around the declaration. Bounded walk-up (4 hops) plus a special case for `PropertyAccessExpression` so TS2339 errors resolve to the *receiver's* type, not the non-existent property's. The architectural moat — no other OSS tool does this for TypeScript specifically.
+- **`mendSingleFile(opts)`** — single-LLM repair via Vercel AI SDK + `@ai-sdk/anthropic`. Uses top-level `system:` parameter (v6 pattern), markdown-headered file delimiters in the prompt (XML wrappers caused Claude to mirror them in output and break the parser). Returns `rawResponse`, parsed `blocks`, `apply` result, token counts, latency.
+- **`applySingleBlock(content, search, replace)`** + **`applyEditBlocks(opts)`** + **`parseEditBlocks(text)`** — Aider-style `editblock` parser and 3-tier fuzzy applier (exact → rstrip → strip). Defensive parser handles `<file path="…">` wrappers Claude emits when the system prompt uses XML markers. Abstains on ambiguous matches (multiple hits) rather than guess.
+- **`runMendLoop(opts)`** — bounded retry (default 3 iterations) with no-progress / regression detection via error-signature-set comparison. Streams per-iteration data: `patchesApplied`, `patchesFailed`, `inputTokens`, `outputTokens`, `latencyMs`, `rawResponse`. Stop reasons: `noErrors`, `fixed`, `noProgress`, `regressed`, `maxIterations`.
+
+### Added (fixtures + harness)
+- **3 hand-authored minimal Layer-2 fixtures** — `mend-ts2339-property-typo`, `mend-ts7006-implicit-any`, `mend-ts2741-missing-prop`.
+- **2 realistic Layer-2 fixtures** — `realistic-multi-error-user-helpers` (3 errors, 1 file, `taskDescription` populated), `realistic-rename-ripple` (2 errors, 2 files).
+- **30 auto-generated fixtures** via `scripts/generate-fixtures.mjs` (ts-morph AST mutators × 3 codes × 3 seeds × 10 each). Total Layer-2 fixture corpus: **35**.
+- **`benchmark/run-llm-benchmark.ts`** (`npm run benchmark:llm`) — Layer 2 live LLM benchmark against Anthropic. Skips silently with exit 0 when `ANTHROPIC_API_KEY` is unset.
+- **`scripts/generate-fixtures.mjs`** (`npm run generate-fixtures`) — ts-morph AST mutators that introduce one targeted error per fixture into a valid seed file. Validation gate: every mutation runs through `runInProcessTsc` to confirm the expected error code, then through `runValidationLoop` to confirm Layer 0 abstains. Memory-bounded shared `Project` + tempDir + cache resets to prevent OOMs.
+
+### Added (tests)
+- **33 unit tests** across `typeContext`, `applyEditBlock`, `mendAgent`, `runMendLoop`. Mocked LLM call via injectable `_callLLM` — tests never hit the real API.
+
+### Added (CI)
+- Workflow gains a Layer-2 benchmark step gated on `ANTHROPIC_API_KEY` (skips cleanly when unset). Existing Layer-0 benchmark + matrix steps unchanged.
+- Bumped `actions/checkout` + `actions/setup-node` v4 → v5.
+
+### Changed
+- **Dependencies added (runtime):** `@ai-sdk/anthropic@^3.0.44`, `ai@^6.0.86`. Previous "near-zero deps" north star (Layer 0/1 only) is superseded — package now spans Layer 0/1/2.
+- **Dependencies added (dev):** `ts-morph@^28.0.0` (fixture generation).
+- **Public-API surface** at `src/index.ts` extended with the Layer-2 exports listed above. Layer 0/1 surface unchanged — `runValidationLoop`, `runInProcessTsc`, `runLSPFixerPass`, `discoverTsFiles`, and the contract types stay byte-identical.
+- **Roadmap decision D3 reversed** — previous decision was "mend in sister package"; current decision is "mend in-package." Updated in `tsc-defense-roadmap.md`.
+
+### Engines
+- Node `>=20.9.0` (unchanged)
+- TypeScript `>=5.0.0` peer (unchanged)
+
+### Performance signals (Layer 2, 35-fixture run, claude-haiku-4-5)
+
+| Metric | Target | Observed |
+|---|---|---|
+| Pass rate | ≥70% (Haiku floor) | **100%** (35/35) |
+| Iter-1 success | ≥40% | **97%** (34/35) |
+| Cost / fixture | ≤$0.005 | **$0.001 avg** |
+| Latency / fixture | P95 ≤25s | ~1.5s |
+
+Caveat: 30 of 35 fixtures are single-error mutations of 3 seeds. Real-world diversity will dent these numbers.
+
+## [0.3.0] - 2026-05-07
+
+Phase 2 contract release. **Establishes the public types `MendContext`, `LayerEvent`, and `Diagnostic` so a downstream LLM-mend package (e.g. `@shipispec/tsmend`) can consume tsfix's output without redefining the shape.** No behavior changes; purely additive types. Also collapses several dev-only improvements that landed since v0.2.0 into a single release.
+
 ### Added
-- **Project-shape matrix** (`scripts/run-matrix.mjs`, `npm run matrix`) — pre-publish gate that builds the local tarball and exercises it cold against 6 distinct project shapes: `monorepo-refs` (project references — pinned as a documented limitation), `next-app` (App Router, `paths` alias, `jsx: preserve`), `plain-ts-bundler` (esnext + bundler), `plain-ts-commonjs` (legacy CJS + ES2015 + node10), `plain-ts-nodenext` (nodenext resolution), `react-vite` (TSX + `jsx: react-jsx`). Each sample has an `expected.json` asserting `errorsBefore`, `errorsAfterMax`, `lspFixesAppliedMin/Max`, `mustPass`, and `expectFileContains` post-fix. 6/6 pass on 2026-05-05. Dev-only — not shipped in the tarball.
+- **`MendContext` interface** — public type defining the input contract for a Layer 2–4 LLM-mend agent. Required fields: `workspaceRoot`, `diagnostics`, `erroredFiles`. Optional fields: `taskDescription`, `featureSpecText`, `acceptanceCriteria`, `siblingTasks`, `priorTaskExports`, `installedTypes`.
+- **`LayerEvent` interface** — per-layer event shape for streaming telemetry. Designed for an `onLayerEvent` callback in a future minor release; the type is published now so downstream callers can construct events themselves.
+- **`Diagnostic` type alias** — public re-export of `InProcessTscResult["diagnostics"][number]`. Convenience for consumers building `MendContext`.
+- **Project-shape matrix** (`scripts/run-matrix.mjs`, `npm run matrix`) — pre-publish gate that builds the local tarball and exercises it cold against 6 distinct project shapes: `monorepo-refs` (project references — pinned as a documented limitation), `next-app` (App Router, `paths` alias, `jsx: preserve`), `plain-ts-bundler` (esnext + bundler), `plain-ts-commonjs` (legacy CJS + ES2015 + node10), `plain-ts-nodenext` (nodenext resolution), `react-vite` (TSX + `jsx: react-jsx`). 6/6 pass. Dev-only — not shipped in the tarball.
+- **Capture script** (`scripts/capture-fixture.mjs`, `npm run capture`) — Phase 3b tooling for snapshotting real broken workspaces into `fixtures/real-<name>/`. Awaits first real failure to produce fixtures.
+- **GitHub Actions CI** (`.github/workflows/test.yml`) — runs check-types, vitest, benchmark, and the matrix on every PR + main push.
+
+### Changed
+- **Repository moved.** `tsc-defense-stack/` was extracted from the `spectoship-meta` monorepo into its own repository at <https://github.com/owgreen-dev/tsfix>. All `repository.url`, `homepage`, `bugs.url` fields point at the new repo. Internal git history pre-2026-05-06 lives in the original monorepo; the CHANGELOG narrates v0.1.0–v0.2.0 in detail.
+- **Public README rewritten** for an OSS audience — tagline, before/after, 30-second cold start, four-layer model, library API, trust model, contributing protocol. Previous internal-orientation README preserved at `docs/internal-orientation.md`.
+
+### Engines
+- Node `>=20.9.0` (unchanged)
+- TypeScript `>=5.0.0` peer (unchanged)
 
 ## [0.2.0] - 2026-05-04
 
@@ -80,7 +142,9 @@ Initial public release. **Layers 0–1 only** (deterministic detection + auto-fi
 - Node `>=20.9.0` (matches VS Code Extension Host runtime)
 - TypeScript `>=5.0.0` (peer dep, must be installed in the consuming workspace)
 
-[Unreleased]: https://github.com/owgreen-dev/tsfix/compare/v0.2.0...HEAD
+[Unreleased]: https://github.com/owgreen-dev/tsfix/compare/v0.4.0...HEAD
+[0.4.0]: https://github.com/owgreen-dev/tsfix/compare/v0.3.0...v0.4.0
+[0.3.0]: https://github.com/owgreen-dev/tsfix/compare/v0.2.0...v0.3.0
 [0.2.0]: https://github.com/owgreen-dev/tsfix/compare/v0.1.1...v0.2.0
 [0.1.1]: https://github.com/owgreen-dev/tsfix/compare/v0.1.0...v0.1.1
 [0.1.0]: https://github.com/owgreen-dev/tsfix/releases/tag/v0.1.0

package/README.md

@@ -1,170 +1,240 @@
-# TSC Defense Stack — `@shipispec/tsfix`
+# 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.
+> Two-layer TypeScript error recovery for LLM-generated code — fix `TS2304`, `TS2305`, `TS2551`, `TS2552`, `TS2724` deterministically with the same engine that powers VS Code's Quick Fix, and escalate the rest to a single-file LLM mend.
 
-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)
+`@shipispec/tsfix` is what you reach for when you've just generated a few hundred files of TypeScript with an LLM and `tsc --noEmit` is screaming at you. It runs in two layers:
 
----
+- **Layer 0/1** — Deterministic. Borrows the same TypeScript Language Service that powers VS Code's "Quick Fix" lightbulb and runs it as a CLI. Fixes typos, missing imports, and did-you-mean errors with no LLM, no network, no config.
+- **Layer 2** — Opt-in. A single-file LLM mend agent (Vercel AI SDK + Anthropic) that picks up what Layer 0 abstains on: TS2339 (property doesn't exist), TS7006 (implicit `any`), TS2741 (missing required prop), and other cases where the LSP can't statically derive the fix. Driven by **type-context injection** — when tsc says "Property 'foo' doesn't exist on type 'Bar'", tsfix resolves the `Bar` declaration via the TypeChecker and feeds its source to the model.
 
-## Source-of-truth map
+Layer 2 only runs if you explicitly call its API or set `ANTHROPIC_API_KEY` and use the `runMendLoop` entry point. The default `tsfix --workspace ...` CLI is still **Layer 0/1 only**.
 
-This package owns its TypeScript-error handling code outright. The shims in `spectoship2/` re-export from here, not the reverse.
+## Before / after (Layer 0)
 
-| 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` |
+```
+$ tsc --noEmit
+src/api.ts:5:2  - error TS2552: Cannot find name 'consol'. Did you mean 'console'?
+src/api.ts:8:5  - error TS2305: Module '"react"' has no exported member 'ueState'.
+src/api.ts:12:14 - error TS2551: Property 'lenght' does not exist on type 'string[]'. Did you mean 'length'?
 
----
+Found 3 errors in 1 file.
 
-## How the layers fit together
+$ npx @shipispec/tsfix --workspace .
+[ts-lsp-fixer] applied 3 fixes across 1 file
+
+$ tsc --noEmit
+$ # 0 errors
+```
 
-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.
+## 30-second cold start
 
+```bash
+cd your-broken-project
+npx @shipispec/tsfix --workspace .
 ```
-                    ┌─────────────────────────────────────────────────┐
-                    │ 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)         │
-                 └─────────────────────────────────┘
+
+No config file. Exit code conventions:
+
+| Code | Meaning |
+|---|---|
+| 0 | Workspace is clean |
+| 1 | Errors remain (printed to stderr) |
+| 2 | Bad arguments / harness error |
+
+Preview what *would* change without writing to disk:
+
+```bash
+npx @shipispec/tsfix --workspace . --dry-run
+```
+
+Machine-readable output for piping into other tools:
+
+```bash
+npx @shipispec/tsfix --workspace . --json
 ```
 
----
+### All flags
+
+| Flag | Meaning |
+|---|---|
+| `--workspace <path>` | Required. Directory containing your `tsconfig.json`. |
+| `--dry-run` | Run the fixer in memory, report counts, write nothing. |
+| `--no-lsp` | Validate only — skip auto-fix. |
+| `--files <a.ts,b.ts>` | Restrict fixing to a comma-separated list. |
+| `--json` | Machine-readable output. |
+| `--verbose` | Per-fix logging. |
+| `--help` | Print usage. |
+
+The CLI does not run Layer 2 — call the library API for that (below).
 
-## What to read first
+## What Layer 0 fixes
 
-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
+| TS code | Meaning | What tsfix does |
+|---|---|---|
+| `TS2304` | Cannot find name | Auto-imports |
+| `TS2305` | Module has no exported member | Did-you-mean rename |
+| `TS2551` | Property does not exist on T, did you mean Y | Spelling fix |
+| `TS2552` | Cannot find name, did you mean Y | Spelling fix |
+| `TS2724` | Module member did-you-mean | Import rename |
 
----
+Against a 14-fixture benchmark spanning typos, did-you-mean cases, multi-file ripples, and 4 API-drift scenarios: **14/14 fixtures pass and 14/25 errors are auto-fixed (56%).** The remaining errors are intentionally outside Layer 0's scope and escape to Layer 2.
 
-## Standalone harness
+## What Layer 0 does *not* fix (Layer 2 picks these up)
+
+By design, Layer 0 only applies fixes that are **deterministic** and **non-structural**. It refuses to:
+
+- Add or remove function declarations
+- Insert type annotations or change types
+- Modify control flow (`await` insertions, async propagation)
+- Rewrite JSX trees
+- Add object-literal stub properties
+
+The internal allowlist is two-layered: error codes (`SAFE_FIXABLE_CODES`) and Quick Fix names (`SAFE_FIX_NAMES = ['import', 'fixImport', 'spelling', 'fixSpelling']`). When the language service offers anything outside that allowlist, Layer 0 abstains and surfaces the error so Layer 2 (or a human) can pick it up.
+
+Layer 2 is built for the cases the LSP can't statically resolve:
+
+- `TS2339` — Property doesn't exist on type. The LLM needs to see *the type's declaration* to decide whether the receiver should grow a field, the call site has a typo with no near-match, or the receiver is the wrong type entirely.
+- `TS7006` — Implicit `any`. The LLM picks the right annotation from surrounding context.
+- `TS2741` — Missing required property. The LLM sees the contextual type and supplies a real value, not a placeholder.
+
+Against a 35-fixture Layer-2 benchmark (3 hand-authored minimal + 2 realistic + 30 ts-morph-generated mutations across TS2339/TS7006/TS2741), **35/35 pass at $0.001/fixture avg, P95 latency ~1.5s on `claude-haiku-4-5`.** Caveat: the 30 generated fixtures are mutations of 3 seeds — real-world diversity will move these numbers.
+
+## The four-layer model
 
 ```
-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.)
+Layer 0 — Prevention      (prompt rules, exported-API injection — your problem)
+Layer 1 — Deterministic   (this package: LSP auto-fix, CLI default)
+Layer 2 — Single-file LLM (this package: opt-in via library API)
+─────────────────────────────────────────────────────────────────
+Layer 3 — Multi-file LLM  (planned: blast-radius search/replace via findReferences)
+Layer 4 — Stub-and-continue (planned: escape hatch)
 ```
 
-### Use as a library (today's recommended path)
+The bet: roughly half of TypeScript errors in LLM output are deterministically fixable. By catching them in Layer 1 you dodge the LLM tax (latency, cost, nondeterminism) on the easy half. Layer 2 takes the other half — but only when you explicitly invoke it.
 
-`@shipispec/tsfix` ships its source as `.ts`. Plain Node 22+ refuses to type-strip files in `node_modules`, so consumers need a TypeScript-aware loader (`tsx`, `ts-node`, or `jiti`) until v0.2 ships an esbuild bundle. Most LLM-tooling projects already use one of these.
+## Library API
 
-```sh
-npm install @shipispec/tsfix typescript
-```
+### Layer 0/1 — deterministic loop
 
-```js
-// run-fix.mjs
-import { runValidationLoop } from "@shipispec/tsfix";
+```typescript
+import { runValidationLoop } from '@shipispec/tsfix';
 
-const result = runValidationLoop({ workspaceRoot: "./my-project" });
-console.log(result.errorsBefore, "→", result.errorsAfter);
-console.log("LSP fixes:", result.lspFixer.fixesApplied);
+const result = runValidationLoop({
+  workspaceRoot: '/path/to/your/project',
+  // Optional:
+  // targetFiles: ['src/api.ts'],
+  // dryRun: true,
+  // logger: { info: console.log, warn: console.warn, error: console.error },
+});
+
+result.errorsBefore;          // number
+result.errorsAfter;           // number
+result.lspFixer.fixesApplied; // number
+result.lspFixer.filesEdited;  // string[]
+result.passed;                // boolean — true if errorsAfter === 0
 ```
 
-```sh
-npx tsx run-fix.mjs    # tsx loads the package's .ts source
+Other Layer 0/1 exports:
+
+- `runInProcessTsc(opts)` — validation only, no fixer. Returns structured diagnostics.
+- `runLSPFixerPass(opts)` — Layer 0 fixer alone, no validation loop wrapper.
+- `discoverTsFiles(workspaceRoot)` — file-walking helper. Skips `node_modules`, `.next`, `dist`, `build`, `out`, `coverage`, `.git`.
+
+### Layer 2 — LLM mend (opt-in)
+
+```typescript
+import { runValidationLoop, runMendLoop } from '@shipispec/tsfix';
+
+// Layer 0/1 first.
+const layer1 = runValidationLoop({ workspaceRoot });
+
+if (!layer1.passed) {
+  // Layer 2 escalation.
+  const layer2 = await runMendLoop({
+    context: {
+      workspaceRoot,
+      diagnostics: layer1.remainingDiagnostics,
+      erroredFiles: layer1.lspFixer.filesWithErrors,
+      // Optional fields that improve mend quality:
+      // taskDescription: 'Build a user CRUD module',
+      // featureSpecText: '...the markdown spec...',
+      // acceptanceCriteria: '...',
+      // installedTypes: '...',  // compact API surface from npm deps
+    },
+    llm: {
+      provider: 'anthropic',
+      model: 'claude-haiku-4-5',
+      apiKey: process.env.ANTHROPIC_API_KEY,
+    },
+    maxIterations: 3,
+  });
+
+  console.log(layer2.stopReason);  // 'fixed' | 'noProgress' | 'regressed' | 'maxIterations'
+  console.log(layer2.totalCostUsd);
+}
 ```
 
-### Use as a CLI (after `npm link` from a clone)
+Other Layer 2 exports:
 
-The bin's `npx` cold-start is blocked on the v0.2 esbuild bundle (see roadmap § 1a). For now, clone-and-link works:
+- `mendSingleFile(opts)` — one LLM call for one file. The building block under `runMendLoop`.
+- `getTypeContext(opts)` — resolve a `Diagnostic` to its declaring type via the TS Language Service and return ±N lines around the declaration. The architectural moat — every other LLM-driven repair tool uses generic grep or repo-maps.
+- `parseEditBlocks(text)` / `applyEditBlocks(opts)` — Aider-style SEARCH/REPLACE patch parser + 3-tier fuzzy applier.
+- Types: `MendContext`, `LayerEvent`, `Diagnostic`, plus the per-function option/result types.
 
-```sh
-git clone https://github.com/owgreen-dev/spectoship-meta
-cd spectoship-meta/tsc-defense-stack
-npm install
-npm link
+## Trust model
 
-tsfix --workspace ./your-project
-```
+Layer 0/1 loads `typescript` from your workspace's `node_modules` — it does **not** bundle its own. This ensures the fixer behaves identically to the `tsc` your project actually compiles with.
 
-Flags: `--json`, `--no-lsp`, `--verbose`, `--files <comma-list>`. Exit codes: `0` = clean, `1` = errors remain, `2` = bad args / harness error.
+> **Run tsfix only on workspaces you trust.** Loading `typescript` from an attacker-controlled `node_modules` is equivalent to running `node_modules/.bin/tsc` against it.
 
-### Run the benchmark (contributor-only)
+**Network surface (Layer 0/1):** none. No telemetry, no calls home, no background processes, no config files written outside `--workspace`.
 
-From inside the package directory after `npm install`:
-```sh
-npm run benchmark              # all 14 fixtures
-npm run benchmark -- --fixture synthetic-typo-ts2552    # one fixture
-```
+**Network surface (Layer 2):** every `mendSingleFile` call hits Anthropic's API via the Vercel AI SDK. The source files in `MendContext.erroredFiles` and the resolved type-context slices are sent in the prompt. If your code is sensitive, do not call Layer 2 — the CLI never does, and the library exports are explicit.
 
-### Current baseline
+## Engines
 
-**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.
+- Node `>=20.9.0`
+- TypeScript `>=5.0.0` (peer dep — must be installed in your workspace)
 
-### Capturing real-failure fixtures
+If your workspace has no `node_modules/typescript`, tsfix will fail with a clear error:
 
-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.
+```
+error: this workspace has no TypeScript installed.
+run: npm install --save-dev typescript
+```
 
----
+## Contributing
 
-## Troubleshooting
+### Adding a Layer-0 fix
 
-**`ERR_MODULE_NOT_FOUND: Cannot find package 'typescript'`** — your package manager didn't install the peer dependency. Run `npm install typescript` (or yarn/pnpm equivalent). Modern npm (v7+) auto-installs peers, so you'll usually only see this with older npm or with `auto-install-peers=false`.
+1. **Probe** — write a tiny test workspace with the exact error you want fixable. Drop it under `fixtures/<descriptive-name>/` with an `expected.json` declaring `errorsBefore`, `errorsAfterMax`, `lspFixesAppliedMin/Max`, and `mustPass`.
+2. **Verify** — run `npm run benchmark -- --fixture <name>` and inspect what the language service offers (the `fix.fixName` field).
+3. **Allowlist change** — if `fixName` is unsafe (`fixMissingFunctionDeclaration`, `addMissingPropertyAndOptional`, etc.), document why we don't trust it. Otherwise, add the error code to `SAFE_FIXABLE_CODES` and the fix name to `SAFE_FIX_NAMES` in `src/tsLanguageServiceFixer.ts`.
+4. **Lock it in** — confirm all existing fixtures still pass (`npm run benchmark`). Open a PR.
 
-**`Cannot find module '<workspace>/tsconfig.json'`** — you pointed `--workspace` at a directory with no `tsconfig.json`. Pass a directory whose root has the project's tsconfig (typically the project root, not a sub-package).
+Each new code/fix-name pair gets its own fixture. We don't trust the language service blindly — we trust it under specific, pinned conditions.
 
----
+### Adding a Layer-2 fixture
 
-## Trust model
+Layer-2 fixtures live under `fixtures/` alongside Layer-0 ones, identified by `expectedErrorCode` (singular) or `costUsdMax` in their `expected.json`. The Layer-0 benchmark skips them; `npm run benchmark:llm` runs them against Anthropic.
 
-`@shipispec/tsfix` loads `typescript` from your workspace's `node_modules` (this is required for the lib-path workaround that makes the package work inside esbuild bundles). That means a malicious workspace's `typescript` install can execute arbitrary code at validate time.
+- Hand-author one under `fixtures/mend-<descriptive-name>/` for new error classes.
+- Or generate one via `npm run generate-fixtures -- --code=TS2339 --seed=apiRouter.ts --count=10 --rng-seed=42`. The generator validates every mutation through Layer 0 first to confirm Layer 0 abstains (otherwise it's not Layer 2 territory).
 
-**Only run `tsfix` on workspaces you trust.** This is the same trust boundary as ESLint, Prettier, Vitest, and other tools that load the workspace's TypeScript.
+### Pre-publish gates
 
-There is no telemetry, no outbound HTTP, and no exec calls outside the local `node` ↔ `tsx` invocation in the bin wrapper. The only filesystem writes are LSP edits to files you pass in via `targetFiles` (or files discovered under `workspaceRoot`).
+- `npm run benchmark` — Layer 0, 14 fixtures, no network.
+- `npm run benchmark:llm` — Layer 2, 35 fixtures, requires `ANTHROPIC_API_KEY`. Total cost ~$0.04 per run.
+- `npm run matrix` — runs the local tarball against 6 distinct project shapes (Next.js, Vite + React, plain `nodenext`, plain `bundler`, plain CommonJS, monorepo with project references). Adds ~3 min; run manually before tagging.
 
----
+## License
 
-## What's in the package vs what's only for contributors
+MIT.
 
-The published tarball ships `src/`, `cli/`, `bin/`, plus `README.md` / `LICENSE` / `CHANGELOG.md`. Everything else (`benchmark/`, `fixtures/`, `tsconfig.json`, the dev-only npm scripts in `package.json`, the design docs in `docs/`) is contributor-side and either excluded from the tarball via `package.json#files` or just not part of the consumer-facing surface.
+## See also
 
-**Heads-up for consumers:** the published `package.json` includes `scripts.benchmark`, `scripts.test`, and `scripts.setup-fixtures`. Those reference `tsx`, `vitest`, and `fixtures/_shared/` — none of which ship to consumers. Don't run them from your `node_modules/@shipispec/tsfix/` directory; clone the repo if you want to contribute.
+- `CHANGELOG.md` — release notes per version.
+- `ARCHITECTURE.md` — internal design rationale (the four-layer model, the workspace lib-path workaround).
+- `STATUS.md` — current snapshot, gaps, and roadmap state.
+- `tsc-defense-roadmap.md` — phased plan.
+- `docs/internal-orientation.md` — the original SpecToShip-context README, kept for contributors who want the design history.

package/dist/cli.js

@@ -475,6 +475,11 @@ function applyFixToSnapshots(fix, snapshots) {
 // src/index.ts
 import * as fs3 from "node:fs";
 import * as path3 from "node:path";
+
+// src/typeContext.ts
+import * as ts3 from "typescript";
+
+// src/index.ts
 var noopLogger = {
   info: () => {
   },

package/dist/index.d.ts

@@ -4,7 +4,8 @@
  * 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).
+ * runs Layer 2 LLM mend (single-file repair via Vercel AI SDK + Anthropic)
+ * on what survives.
  *
  * ## Quick start (library)
  *
@@ -31,12 +32,18 @@
  * - `runInProcessTsc` — just type-check, returns structured diagnostics
  * - `runLSPFixerPass` — just the auto-fix pass, edits files in place
  *
- * ## What it doesn't do (yet)
+ * ## Public types for the LLM-mend layer
  *
- * 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.
+ * - `Diagnostic` — single tsc error (re-exported from `runInProcessTsc`)
+ * - `MendContext` — input contract for the Layer 2–4 LLM-mend agent
+ * - `LayerEvent` — per-layer event shape for streaming telemetry
+ *
+ * ## Layer 2 mend API (v0.4.0+)
+ *
+ * - `getTypeContext` — TS Language Service type-declaration injection
+ * - `mendSingleFile` — single-LLM-call repair via Vercel AI SDK
+ * - `runMendLoop` — bounded retry with no-progress / regression detection
+ * - `parseEditBlocks` / `applyEditBlocks` — Aider-style SEARCH/REPLACE applier
  */
 export { runInProcessTsc, isInProcessTscEnabled, resetInProcessTscCache } from "./validatorInProcess.js";
 export type { InProcessTscOptions, InProcessTscResult } from "./validatorInProcess.js";
@@ -101,3 +108,81 @@ export declare function discoverTsFiles(workspaceRoot: string): string[];
  * 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;
+}
+export { getTypeContext, resetTypeContextCache } from "./typeContext.js";
+export type { TypeContextOptions, TypeContext } from "./typeContext.js";
+export { parseEditBlocks, applySingleBlock, applyEditBlocks } from "./applyEditBlock.js";
+export type { EditBlock, ApplyEditBlocksOptions, ApplyResult, SingleBlockResult, } from "./applyEditBlock.js";
+export { mendSingleFile } from "./mendAgent.js";
+export type { MendSingleFileOptions, MendSingleFileResult, LLMCall } from "./mendAgent.js";
+export { runMendLoop } from "./runMendLoop.js";
+export type { RunMendLoopOptions, RunMendLoopResult, MendLoopIteration, StopReason, } from "./runMendLoop.js";