@shipispec/tsfix 0.6.1 → 0.6.2

package/CHANGELOG.md

@@ -4,6 +4,14 @@ All notable changes to `@shipispec/tsfix` are documented here. Format follows [K
 
 ## [Unreleased]
 
+## [0.6.2] - 2026-05-23
+
+**Cosmetic patch.** No behavior change; no API surface change. Drops the stale prototype-era "TSC Defense Stack" string from CLI output (was the human-report banner header), replaced with "tsfix" to match the published package name. Surfaced while debugging a vhs demo recording — the recording would otherwise have shown stale branding above the fold. 147/147 tests still pass.
+
+### Changed
+- **CLI human-report header** now prints `tsfix — <workspace>` instead of `TSC Defense Stack — <workspace>` (`cli/run-stack.ts:287`).
+- **Benchmark runner header** now prints `tsfix benchmark — N fixture(s)` instead of `TSC Defense Stack Benchmark — N fixture(s)` (`benchmark/run-benchmark.ts:187`; contributor-facing, not shipped in the npm tarball).
+
 ## [0.6.1] - 2026-05-19
 
 **Integration release.** Combines v0.6.0's library-aware error recovery with the multi-provider + telemetry work that landed on `main` between v0.5.0 and v0.6.0. The npm-published v0.6.0 was built from a stale local checkout and shipped without the Tier 2 (multi-provider) and Tier 3 (onLayerEvent + runFullStack) features that were already on `main`. v0.6.1 is the canonical "everything-since-0.5.0" release; users upgrading from v0.5.0 should jump straight to v0.6.1.
@@ -306,7 +314,8 @@ 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.6.1...HEAD
+[Unreleased]: https://github.com/owgreen-dev/tsfix/compare/v0.6.2...HEAD
+[0.6.2]: https://github.com/owgreen-dev/tsfix/compare/v0.6.1...v0.6.2
 [0.6.1]: https://github.com/owgreen-dev/tsfix/compare/v0.6.0...v0.6.1
 [0.6.0]: https://github.com/owgreen-dev/tsfix/compare/v0.5.0...v0.6.0
 [0.5.0]: https://github.com/owgreen-dev/tsfix/compare/v0.4.0...v0.5.0

package/README.md

@@ -1,14 +1,26 @@
 # tsfix
 
-> Library-aware 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. Escalate the rest to a single-file LLM mend that knows what tsc's quick-fix gets wrong about your installed libraries.
+> **TypeScript error recovery for LLM-generated code.** When Cursor / Claude Code / Copilot / your spec-to-code agent leaves you with a wall of `tsc --noEmit` errors, tsfix repairs them — **library-aware** mend on the hard ones, deterministic VS Code Quick Fix on the trivial ones. **98.6% pass on a real-world single-file bench at <$0.005 per fix.** MIT, BYOK.
 
-`@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 layers:
+<!-- demo.gif goes here — broken project → `npx @shipispec/tsfix --workspace . --llm` → green tsc. See docs/demo/demo.tape -->
 
-- **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) 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. **Multi-provider** (Anthropic / OpenAI / Google) via `--llm-provider`. As of v0.6.0, also **library-aware**: tsfix reads your `package.json` and injects breaking-change hints for known libraries (`vite-plugin-svgr`, `next`, `ai`, `drizzle-orm`) so the model picks the runtime-correct fix instead of tsc's misleading quick-fix.
-- **Layer 4** — Escape hatch. When Layer 2 can't resolve the last few errors, opt in to `// @ts-expect-error - tsfix: ...` directives that self-destruct once the underlying issue is fixed elsewhere. tsfix never leaves the workspace worse than it found it.
+## Why tsfix exists
 
-Layer 2 only runs if you explicitly call its API or set `ANTHROPIC_API_KEY` and pass `--llm` to the CLI. The default `tsfix --workspace ...` CLI is still **Layer 0/1 only**.
+tsfix is built for the *output of code generators*, not human-written TypeScript. The thing it does that nothing else does: **it knows what tsc's own quick-fix gets wrong about your installed libraries.**
+
+When `vite-plugin-svgr@4` is in your `package.json` and tsc says *"Module '"./logo.svg"' has no exported member 'ReactComponent'. Did you mean `import Logo from "./logo.svg"`?"*, tsc is right about types and wrong about runtime. The default import resolves to the asset URL string under vite, not a component. **tsc is now green. The dev server is now broken.** An LLM dutifully following tsc's quick-fix produces code that type-checks and crashes the page.
+
+tsfix reads your `package.json` on every Layer 2 invocation, matches installed deps against a built-in registry of known breaking changes (vite-plugin-svgr, Next.js 15 async params, Vercel AI SDK v3, Drizzle ORM), and injects the correct migration hint into the LLM prompt's headline. The model then emits `import Logo from "./logo.svg?react"` — tsc green AND the dev server works.
+
+That's the one-sentence pitch. The rest of the package is a careful, layered, cost-aware way to deliver it across every TS error class.
+
+## The layers, opt-in by layer
+
+- **Layer 1 (default, deterministic)** — Auto-fix typos, missing imports, and did-you-mean errors via the same TypeScript Language Service that powers VS Code's "Quick Fix" lightbulb. Zero network, zero LLM cost, zero config. Catches roughly half of LLM-generated TS errors before you ever pay for an LLM call.
+- **Layer 2 (opt-in via `--llm`)** — Single-file LLM mend via the Vercel AI SDK. Multi-provider: **Anthropic / OpenAI / Google** (`--llm-provider`). Library-aware (above). Driven by **type-context injection** — when tsc says *"Property 'foo' doesn't exist on type 'Bar'"*, tsfix resolves `Bar`'s declaration via the TypeChecker and feeds its source to the model. That's the architectural moat: every other LLM-driven repair tool uses generic grep or repo-maps.
+- **Layer 4 (library-only, opt-in via `runMendLoop({stubOnFailure: true})`)** — Escape hatch. When Layer 2 can't resolve the last few errors, inserts `// @ts-expect-error - tsfix: ...` directives that self-destruct once the underlying issue is fixed elsewhere. tsfix never leaves the workspace worse than it found it.
+
+The default CLI is **Layer 0/1 only** — no network calls, no surprises. Layer 2 only runs when you opt in with `--llm` and have a provider key in your environment.
 
 ## Before / after (Layer 0)
 
@@ -56,6 +68,8 @@ npx @shipispec/tsfix --workspace . --json
 
 ### All flags
 
+**Core (Layer 0/1):**
+
 | Flag | Meaning |
 |---|---|
 | `--workspace <path>` | Required. Directory containing your `tsconfig.json`. |
@@ -66,7 +80,40 @@ npx @shipispec/tsfix --workspace . --json
 | `--verbose` | Per-fix logging. |
 | `--help` | Print usage. |
 
-The CLI does not run Layer 2 — call the library API for that (below).
+**Layer 2 (LLM mend — opt-in, sends source to your chosen provider):**
+
+| Flag | Meaning |
+|---|---|
+| `--llm` | Escalate errors that survive Layer 0/1 to Layer 2. Requires the provider's API key in the environment. |
+| `--llm-provider <name>` | `anthropic` (default) \| `openai` \| `google`. Each provider reads its own env var: `ANTHROPIC_API_KEY` / `OPENAI_API_KEY` / `GOOGLE_GENERATIVE_AI_API_KEY`. |
+| `--llm-model <name>` | Model name. Defaults per provider: `claude-haiku-4-5` / `gpt-5-mini` / `gemini-2.5-flash`. |
+| `--llm-max-iterations <N>` | Cap on LLM retries (default: `3`). Each iteration sends the still-erroring files plus updated diagnostics. |
+| `--llm-budget-usd <amount>` | Soft cost cap; exits with code `3` if exceeded. Cost estimates use a per-provider pricing table (snapshot 2026-05-16) — unknown models log a warning and don't trigger the cap. |
+| `--no-library-hints` | Disable auto-detection of library breaking-change hints from `package.json`. |
+
+### Exit codes
+
+| Code | Meaning |
+|---|---|
+| `0` | Workspace is clean (or Layer 2 cleared all errors). |
+| `1` | Errors remain. |
+| `2` | Bad arguments / missing API key / `--llm` + `--dry-run` rejected. |
+| `3` | Layer 2 budget cap (`--llm-budget-usd`) exceeded. Partial work is persisted to disk. |
+
+### Using in CI
+
+`npx @shipispec/tsfix` prints `npm warn exec The following package was not found and will be installed: @shipispec/tsfix@<version>` on every cold runner. To avoid the warning and skip the install prompt, either install once at workflow start:
+
+```bash
+npm install -g @shipispec/tsfix@latest
+tsfix --workspace .
+```
+
+…or pass `--yes` to npx:
+
+```bash
+npx --yes @shipispec/tsfix --workspace .
+```
 
 ## What Layer 0 fixes
 
@@ -98,9 +145,14 @@ Layer 2 is built for the cases the LSP can't statically resolve:
 - `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; see the realistic 34-fixture bench below.
+tsfix ships two benchmark suites, and it's worth being precise about what each measures:
 
-## Library-aware error recovery (v0.6.0)
+- **Synthetic suite** (in-package, `npm run benchmark:llm`) — hand-authored minimal cases plus ts-morph-generated single-error mutations of a few seed files. These are *easy* by construction (one isolated error, no cross-file ripple) and Layer 2 passes effectively all of them. Useful as a regression gate, **not** as a real-world accuracy claim.
+- **Realistic suite** (34 fixtures drawn from real LLM-repair failures — see the table below) — this is the number to trust. It's where the headline 98.6% / 81.4% figures come from.
+
+If you only read one number, read the realistic suite.
+
+## Library-aware error recovery (v0.6.0+)
 
 A typical TypeScript LLM-repair failure mode: tsc reports `TS2614: Module '"./logo.svg"' has no exported member 'ReactComponent'. Did you mean to use 'import Logo from "./logo.svg"' instead?` The model dutifully follows tsc's quick-fix and emits `import Logo from "./logo.svg"`. **tsc is now green. The dev server is now broken.** Under `vite-plugin-svgr@4`, importing an SVG as a React component requires the `?react` query suffix — `import Logo from "./logo.svg?react"`. The default export is the asset URL, not a component. Quick-fix accuracy ≠ runtime correctness.
 
@@ -142,7 +194,7 @@ The same release hardened the system prompt against the LLM-repair failure modes
 
 Measured against a 34-fixture corpus drawn from real LLM-repair failures in adjacent projects (24 single-file + 10 multi-file), n=3 per cell:
 
-| Surface | v0.5.0 | v0.6.0 | Δ |
+| Surface | v0.5.0 | v0.6.1 | Δ |
 |---|---|---|---|
 | Single-file pass rate | 95.8% | **98.6%** | +2.8pp |
 | Multi-file pass rate | 23.3% | **40.0%** | +16.7pp |
@@ -151,7 +203,7 @@ Measured against a 34-fixture corpus drawn from real LLM-repair failures in adja
 | Cost per full bench | — | **$0.21** | — |
 | Cost per case (`claude-haiku-4-5`) | — | **<$0.005** | — |
 
-Multi-file scenarios remain the gap — Layer 3 (multi-file mend with `findReferences`-driven blast-radius search) is the deferred answer.
+The mend-quality gains landed in v0.6.0 (library-migrations, crash hardening, anti-patterns); v0.6.1 adds multi-provider + telemetry without changing these numbers. Multi-file scenarios remain the gap — Layer 3 (multi-file mend with `findReferences`-driven blast-radius search) is the deferred answer.
 
 ## The four-layer model
 
@@ -257,29 +309,39 @@ error: this workspace has no TypeScript installed.
 run: npm install --save-dev typescript
 ```
 
-## Contributing
+## Build from source
 
-### Adding a Layer-0 fix
+tsfix is plain TypeScript bundled with esbuild — no special toolchain.
 
-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.
+```bash
+git clone https://github.com/owgreen-dev/tsfix
+cd tsfix
+npm install
 
-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.
+npm run check-types   # tsc --noEmit — must pass
+npm test              # vitest unit suite
+npm run build         # bundle to dist/ (index.js, cli.js, *.d.ts)
+```
+
+Run a single test file or pattern:
+
+```bash
+npx vitest run src/libraryMigrations.test.ts
+npx vitest run -t "auto-populates libraryMigrations"
+```
 
-### Adding a Layer-2 fixture
+Try your local build against a real project without publishing:
 
-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.
+```bash
+npm run build
+node dist/cli.js --workspace /path/to/some/broken-project
+```
 
-- 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).
+Requires Node `>=20.9.0`. The package has no `dev` watch script — the loop is edit → `npm run check-types` → `npm test`.
 
-### Pre-publish gates
+## Contributing
 
-- `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.
+See **[CONTRIBUTING.md](CONTRIBUTING.md)** for the full guide: dev setup, how to add a Layer-0 fix or a Layer-2 fixture, how to extend the library-migration registry, and the pre-publish gates. PRs that add a library to the migration registry are especially welcome — that's the highest-leverage contribution.
 
 ## License
 
@@ -287,8 +349,8 @@ MIT.
 
 ## See also
 
-- `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.
+- `CHANGELOG.md` — release notes per version (authoritative for current state).
+- `CONTRIBUTING.md` — dev setup, how to add a fix/fixture, how to extend the migration registry.
+- `ARCHITECTURE.md` — design rationale (the four-layer model, the workspace lib-path workaround).
+- `ROADMAP.md` — phased plan and resolved/deferred decisions.
+- `docs/blog-tsc-correctness-is-not-runtime-correctness.md` — the "tsc-correctness ≠ runtime-correctness" writeup (the svgr `?react` case).

package/dist/cli.js

@@ -1703,7 +1703,7 @@ function makeLogger(captureLines, verbose) {
 function printHumanReport(r) {
   const w = process.stderr;
   w.write(`
-TSC Defense Stack \u2014 ${r.workspace}${r.dryRun ? " (dry-run)" : ""}
+tsfix \u2014 ${r.workspace}${r.dryRun ? " (dry-run)" : ""}
 `);
   w.write(`  errors before: ${r.errorsBefore}
 `);

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@shipispec/tsfix",
-	"version": "0.6.1",
+	"version": "0.6.2",
 	"description": "TypeScript error-recovery for LLM-generated code. Layer 0/1 deterministic auto-fix via the TS Language Service + Layer 2 LLM mend (Vercel AI SDK + Anthropic) in one package.",
 	"keywords": [
 		"typescript",