@shipispec/tsfix 0.5.0 → 0.6.0

package/CHANGELOG.md

@@ -4,6 +4,70 @@ All notable changes to `@shipispec/tsfix` are documented here. Format follows [K
 
 ## [Unreleased]
 
+## [0.6.0] - 2026-05-19
+
+**Library-aware error recovery.** Layer 2 now auto-detects breaking-change hints for known libraries from your `package.json` and steers the LLM away from tsc's misleading quick-fixes when a library migration is the real cause. Plus a hardened type-context walk (no more crashes on rename cascades or branded types) and a meaningful set of security anti-patterns in the system prompt.
+
+### Added (library-migration hints)
+- **`detectLibraryMigrations(workspaceRoot, registry?)`** — reads `package.json`, matches installed deps against a built-in registry of known breaking changes, returns matching hints. Auto-invoked by `runMendLoop` when `context.libraryMigrations` is left `undefined`. Pass `[]` explicitly to opt out.
+- **`BUILT_IN_LIBRARY_MIGRATIONS` registry** — initial entries cover `vite-plugin-svgr` (v4 — `?react` query suffix), `next` (15 — `params`/`searchParams` are Promises), `ai` (v3 / v6), `drizzle-orm` (parameterized template literals).
+- **`formatLibraryMigrationsBlock(hints)`** + **`formatLibraryMigrationsTaskDescription(hints)`** — public formatters. The latter produces the `taskDescription` headline (`Library migration: <names>`) that overrides any caller-supplied description when migrations apply — empirically, models follow tsc's quick-fix when the migration is mentioned only in a buried section.
+- **CLI `--no-library-hints`** — opt-out flag. Default behavior auto-detects and injects hints. When a migration matches AND `--llm` is set, the CLI also skips Layer 0/1 (tsc's quick-fix is the misleading path for these cases).
+- **`MendContext.libraryMigrations?: Array<{ name: string; hint: string }>`** — new optional field. `undefined` = auto-detect; `[]` = opt out; populated array = override (skip detection).
+
+### Added (system-prompt security anti-patterns)
+- **Type-assertion escape-hatches** — explicitly forbids `as keyof T` for runtime-string TS7053 silencing, `x as any` / `x as unknown as T` to dodge a real mismatch, `!` non-null assertions to dodge TS18047/TS2532. The prompt directs the model to narrow at the function signature, widen with an index signature, or guard with `if (key in obj)` instead.
+- **Dependency removal/substitution** — restoring a missing import is preferred to substituting a different library (e.g. `bcrypt` → `crypto.subtle.digest` is flagged as a security regression even when tsc accepts it).
+- **SQL / NoSQL / shell injection** — forbids string concatenation of user-controlled values into raw query strings; directs the model to Drizzle's tagged template, Prisma / mysql2 placeholders, etc.
+- **React XSS** — forbids `dangerouslySetInnerHTML` as a way to dodge a children-type error; recommends auto-escaping JSX or DOMPurify.
+
+### Added (union-cleanup positive guidance)
+- When a type variant or interface property has been removed/renamed, the prompt now directs the model to do a FULL sweep in the same patch instead of partial cleanup. Specific TS2322 / TS2353 / TS2367 guidance: drop the excess property, drop now-orphaned function parameters with their use sites, replace the no-longer-valid comparison or delete it with its branch. Aimed at the "I changed one reference and left three more" failure mode that produces fresh errors on iteration 2.
+
+### Added (tests)
+- 14 unit tests in `libraryMigrations.test.ts` covering empty / matching / minMajor / maxMajor / multi-dep / malformed-package.json / custom-registry / formatter shapes / headline generation.
+- 4 tests in `mendAgent.test.ts` for `buildSystemBlock`'s library-migration integration (block present, taskDescription override, empty array, custom description preserved without migrations).
+- 2 tests in `runMendLoop.test.ts` for auto-detect (populates from package.json when omitted; opts out on explicit `[]`).
+- 1 regression test in `typeContext.test.ts` — "does not throw on multi-file rename-cascade (TS2305: unresolvable named import)" with 4 importers.
+- Total: **130/130 tests pass.**
+
+### Fixed
+- **`getTypeContext` no longer crashes on multi-file rename cascades or branded types.** `typeContext.ts:tryResolve` now wraps `checker.getTypeAtLocation(n)` and the subsequent `getSymbol()` / `aliasSymbol` / `getDeclarations()` chain in try/catch — TypeScript's internals throw `Cannot read properties of undefined (reading 'kind' / 'flags')` from `isDeclarationNameOrImportPropertyName` on these shapes; tsfix treats those as "no resolvable type" and continues. Belt-and-suspenders try/catch added in `mendAgent.ts` around the per-diagnostic context build — if one diagnostic's context fails for any reason, that diagnostic is skipped instead of killing the whole mend (one bad diag should not lose the LLM's chance to fix the other errors in the file).
+
+### Bench results
+Re-measured against the 34-fixture corpus (24 single-file + 10 multi-file) at n=3 per cell:
+
+| Surface | v0.5.0 | v0.6.0 | Δ |
+|---|---|---|---|
+| Single-file pass rate | 95.8% | **98.6%** | +2.8pp |
+| Multi-file pass rate | 23.3% | **40.0%** | +16.7pp |
+| Aggregate (102 cells) | 74.5% | **81.4%** | +6.9pp |
+| Hard crashes | 6 cells | **0** | -6 |
+| Cost per full bench | — | **$0.21** | — |
+| Cost per case (haiku-4-5) | — | **<$0.005** | — |
+
+Per-fixture flips notable enough to call out:
+
+- **`case-ts2614-vite-svgr` (0/3 → 3/3)** — vite-plugin-svgr v4's `?react` query suffix migration. Before: model followed tsc's quick-fix and emitted `import Logo from "./logo.svg"` (type-checks under the `*.svg` ambient, breaks at runtime under vite). After: with the registry hint, the model emits `import Logo from "./logo.svg?react"` and the resulting code works in both tsc and the dev server.
+- **`case-m7-index-signature-removed` (0/3 → 3/3)** — anti-pattern prompts ended the `as keyof T` escape-hatch loop.
+- **`case-m3-union-variant-removed` (2/3 → 3/3)** + **`case-m6-hook-tuple-arity` (2/3 → 3/3)** — union-cleanup guidance fixed the partial-sweep failure mode.
+- **`case-m1` + `case-m10`** — previously errored with the `typeContext` crash; now produce measurable results.
+
+Caveats: n=3 per cell is noisy at the per-case level (a single-cell flip from 2→3 may revert); aggregate column totals at 24+ cases are the trustworthy signal. Multi-file scenarios remain the gap — Layer 3 (multi-file mend) is the deferred answer.
+
+### Changed
+- **`runMendLoop`** auto-populates `context.libraryMigrations` from `rawContext.workspaceRoot`'s `package.json` when the caller leaves it `undefined`. Existing callers that omit the field get the new behavior automatically; existing callers that pass a non-empty array see no change.
+- **`buildSystemBlock`** leads the prompt body with the library-migrations section when any apply, and uses the migration headline as the `taskDescription` (overrides any caller-supplied description). The library section lives between `SYSTEM_INSTRUCTIONS` and the errored-file content — earliest position where the model still sees it before reaching the file.
+- **CLI** — when a library migration matches AND `--llm` is set, Layer 0/1 is skipped (tsc's quick-fix is the misleading path for these cases). Existing zero-LLM CLI behavior unchanged.
+
+### Engines
+- Node `>=20.9.0` (unchanged)
+- TypeScript `>=5.0.0` peer (unchanged)
+
+## [0.5.0] - 2026-05-16
+
+**Layer 4 (stub-and-continue), Day 2/3 fixture mutators, parallel + cached Layer-2 benchmark, and CLI exposure of Layer 2.** This closes the "tsfix never leaves the workspace worse than it found it" property: when Layer 2 can't resolve the last few errors, the workspace can opt-in to `@ts-expect-error` directives that self-destruct once the underlying issue is fixed elsewhere. The CLI now exposes `--llm` end-to-end (was library-API only).
+
 ### Added (Layer 4 — stub-and-continue escape hatch)
 - **`stubAndContinue(opts)`** — new public API. Inserts `// @ts-expect-error - tsfix: <codes> — <message>` immediately above each unresolved error site so `tsc --noEmit` exits 0. Closes the "tsfix never leaves the workspace worse than it found it" property. Uses `@ts-expect-error` (not `@ts-ignore`) so directives self-destruct once the underlying issue is fixed by other means.
 - **`runMendLoop` opt-in flag** — new `stubOnFailure?: boolean` option (default `false`). When the LLM loop terminates with leftover errors and the flag is set, Layer 4 runs automatically. New `"stubbed"` stop reason; new `stubs?: AppliedStub[]` result field with what was applied.
@@ -201,7 +265,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.4.0...HEAD
+[Unreleased]: https://github.com/owgreen-dev/tsfix/compare/v0.6.0...HEAD
+[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
 [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

package/README.md

@@ -1,13 +1,14 @@
 # tsfix
 
-> 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.
+> 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.
 
-`@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:
+`@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:
 
 - **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.
+- **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. 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.
 
-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**.
+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**.
 
 ## Before / after (Layer 0)
 
@@ -97,20 +98,73 @@ 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.
+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.
+
+## 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.
+
+tsfix v0.6.0 reads your `package.json` on every Layer 2 invocation, matches installed deps against a built-in registry of known breaking changes, and injects library-migration hints into the system prompt's headline (not buried — headline framing matters more than buried context). With `vite-plugin-svgr@^4` installed:
+
+```
+### library-migrations
+- vite-plugin-svgr: v4 requires the `?react` query suffix to import an SVG
+  as a React component. `import Logo from "./logo.svg"` returns the asset URL.
+  `import Logo from "./logo.svg?react"` returns the component.
+
+### task
+Library migration: vite-plugin-svgr
+```
+
+Bench result on this exact case before/after: **0/3 → 3/3**.
+
+The built-in registry currently covers four libraries chosen for high LLM-repair confusion ratio:
+
+| Library | Hint |
+|---|---|
+| `vite-plugin-svgr` v4+ | `?react` query suffix to import as React component |
+| `next` v15+ | `params` / `searchParams` are now Promises (must `await`) |
+| `ai` v3 / v6 | `generateText` API shape changes |
+| `drizzle-orm` | parameterized `sql` template literals, not string concat |
+
+`detectLibraryMigrations(workspaceRoot, registry?)` is also exported as a public API; pass your own registry to extend it. `runMendLoop` auto-invokes detection when you leave `context.libraryMigrations` `undefined`; pass `[]` to opt out, or `--no-library-hints` on the CLI.
+
+### Security-aware system prompt
+
+The same release hardened the system prompt against the LLM-repair failure modes that silence tsc at the cost of runtime semantics:
+
+- **`as keyof T` to silence TS7053** — fix the function signature or guard with `if (key in obj)` instead. Casting away an index-signature error keeps the call type-passing while losing all the runtime safety.
+- **Substituting one library for another to dodge a missing import** — e.g. `bcrypt` → `crypto.subtle.digest`. The fix is to restore the missing import, not swap to a different cryptographic primitive that tsc accepts.
+- **String concatenation of user input into raw SQL** — use Drizzle's tagged template / Prisma placeholders.
+- **`dangerouslySetInnerHTML` to dodge a children-type error** — JSX `{value}` auto-escapes; if you need HTML, sanitize via DOMPurify.
+
+### Realistic bench (34 fixtures, single + multi-file)
+
+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 | Δ |
+|---|---|---|---|
+| Single-file pass rate | 95.8% | **98.6%** | +2.8pp |
+| Multi-file pass rate | 23.3% | **40.0%** | +16.7pp |
+| Aggregate (102 cells) | 74.5% | **81.4%** | +6.9pp |
+| Hard crashes | 6 cells | **0** | -6 |
+| 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 four-layer model
 
 ```
-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 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 --llm or runMendLoop)
+Layer 4 — Stub-and-continue (this package: opt-in escape hatch, @ts-expect-error)
 ─────────────────────────────────────────────────────────────────
-Layer 3 — Multi-file LLM  (planned: blast-radius search/replace via findReferences)
-Layer 4 — Stub-and-continue (planned: escape hatch)
+Layer 3 — Multi-file LLM    (planned: blast-radius search/replace via findReferences)
 ```
 
-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.
+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. Layer 4 makes sure the workspace is never left worse than it started.
 
 ## Library API
 

package/dist/cli.js

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
 
 // cli/run-stack.ts
-import * as path8 from "node:path";
-import * as fs8 from "node:fs";
+import * as path9 from "node:path";
+import * as fs9 from "node:fs";
 
 // src/validatorInProcess.ts
 import * as fs from "node:fs";
@@ -473,8 +473,8 @@ function applyFixToSnapshots(fix, snapshots) {
 }
 
 // src/index.ts
-import * as fs7 from "node:fs";
-import * as path7 from "node:path";
+import * as fs8 from "node:fs";
+import * as path8 from "node:path";
 
 // src/typeContext.ts
 import * as fs3 from "node:fs";
@@ -549,9 +549,20 @@ function isLibFile(fileName) {
 }
 function findTypeDeclaration(checker, startNode, maxWalkUp = 4) {
   const tryResolve = (n) => {
-    const type = checker.getTypeAtLocation(n);
-    const symbol = type.getSymbol() ?? type.aliasSymbol;
-    const declarations = symbol?.getDeclarations();
+    let type;
+    try {
+      type = checker.getTypeAtLocation(n);
+    } catch {
+      return void 0;
+    }
+    let symbol;
+    let declarations;
+    try {
+      symbol = type.getSymbol() ?? type.aliasSymbol;
+      declarations = symbol?.getDeclarations();
+    } catch {
+      return void 0;
+    }
     if (!declarations || declarations.length === 0) return void 0;
     const nonLib = declarations.find((d) => !isLibFile(d.getSourceFile().fileName));
     if (!nonLib) return void 0;
@@ -784,10 +795,77 @@ function applyEditBlocks(opts) {
 }
 
 // src/mendAgent.ts
-import * as fs5 from "node:fs";
-import * as path5 from "node:path";
+import * as fs6 from "node:fs";
+import * as path6 from "node:path";
 import { generateText } from "ai";
 import { createAnthropic } from "@ai-sdk/anthropic";
+
+// src/libraryMigrations.ts
+import * as fs5 from "node:fs";
+import * as path5 from "node:path";
+var BUILT_IN_LIBRARY_MIGRATIONS = [
+  {
+    match: { name: "vite-plugin-svgr", minMajor: 4 },
+    hint: "vite-plugin-svgr v4+ (released 2023-09-20) changed how SVG imports work. The PREVIOUS form `import { ReactComponent as X } from './x.svg'` no longer works \u2014 the ambient module declaration now only matches `*.svg?react`. Correct fix: `import X from './x.svg?react'` (default import + ?react query suffix). DO NOT use tsc's quick-fix `import X from './x.svg'` (no query) \u2014 that type-checks but resolves to the asset URL string at runtime, not a component."
+  },
+  {
+    match: { name: "next", minMajor: 15 },
+    hint: "Next.js 15 changed dynamic-route page props: `params` and `searchParams` are now `Promise<...>` instead of plain objects. The fix shape is: change the page's `params` type to `Promise<{...}>`, mark the page component `async`, and `await params` inside. See https://nextjs.org/docs/app/api-reference/file-conventions/page."
+  },
+  {
+    match: { name: "ai", minMajor: 3, maxMajor: 4 },
+    hint: "Vercel AI SDK v3.x has overload-narrowing issues with `generateObject`. If passing a schema through an object widened with `satisfies Record<K, z.ZodTypeAny>`, the typed overload silently falls back to `output: 'no-schema'` (which forbids the `schema` property). Fix: drop the `satisfies Record<...>` widener, or cast the schema at the call site."
+  },
+  {
+    match: { name: "drizzle-orm" },
+    hint: "Drizzle ORM table access has two distinct surfaces. `db.<table>` is for `select/insert/update/delete` builders. `db.query.<table>` is the Relational Queries API for `findFirst`/`findMany` with relation loading. If you see `Property '<table>' does not exist on type 'PostgresJsDatabase<...>'` when trying to call `.findFirst`/`.findMany`, use `db.query.<table>` instead."
+  }
+];
+function parseMajor(spec) {
+  const m = spec.match(/(\d+)(?:\.\d+)*/);
+  return m ? parseInt(m[1], 10) : null;
+}
+function detectLibraryMigrations(workspaceRoot, registry = BUILT_IN_LIBRARY_MIGRATIONS) {
+  let pkg;
+  try {
+    const pkgPath = path5.join(workspaceRoot, "package.json");
+    if (!fs5.existsSync(pkgPath)) return [];
+    pkg = JSON.parse(fs5.readFileSync(pkgPath, "utf-8"));
+  } catch {
+    return [];
+  }
+  const allDeps = { ...pkg.dependencies ?? {}, ...pkg.devDependencies ?? {} };
+  const hints = [];
+  for (const entry of registry) {
+    const { match, hint } = entry;
+    const versionSpec = allDeps[match.name];
+    if (!versionSpec) continue;
+    const major = parseMajor(versionSpec);
+    if (match.minMajor != null && (major == null || major < match.minMajor)) continue;
+    if (match.maxMajor != null && (major == null || major > match.maxMajor)) continue;
+    hints.push({ name: `${match.name}@${versionSpec}`, hint });
+  }
+  return hints;
+}
+function formatLibraryMigrationsBlock(hints) {
+  if (hints.length === 0) return "";
+  const lines = ["### library-migrations", ""];
+  lines.push(
+    "These migrations apply to your workspace's installed deps. When tsc's quick-fix conflicts with the migration target below, PREFER the migration target. tsc only checks types, not runtime semantics \u2014 these hints encode runtime constraints tsc cannot see."
+  );
+  lines.push("");
+  for (const h of hints) {
+    lines.push(`- [${h.name}] ${h.hint}`);
+  }
+  return lines.join("\n");
+}
+function formatLibraryMigrationsTaskDescription(hints) {
+  if (hints.length === 0) return void 0;
+  const names = hints.map((h) => h.name).join(", ");
+  return `Library migration: ${names}`;
+}
+
+// src/mendAgent.ts
 var SYSTEM_INSTRUCTIONS = `You are a TypeScript code-repair tool. You receive a TypeScript file with one or more compiler errors and resolve them.
 
 Output ONLY SEARCH/REPLACE blocks. No prose, no explanations, no XML wrappers.
@@ -808,16 +886,43 @@ Rules:
 - REPLACE must be valid TypeScript that resolves the diagnostic.
 - Do not invent imports, types, properties, or values. Use only what the type-context section shows.
 - One SEARCH/REPLACE block per logical change.
-- If you cannot resolve a diagnostic with the information given, omit a block for it.`;
+- If you cannot resolve a diagnostic with the information given, omit a block for it.
+
+Anti-patterns \u2014 these silence the type error but break runtime semantics, lose type safety, or introduce security regressions. Do NOT emit a patch that does any of the following:
+
+1. Type-assertion escape-hatches that hide the error rather than fix it:
+   - \`x as any\` / \`x as unknown as T\` to dodge a real mismatch.
+   - \`key as keyof T\` to silence a TS7053 index-signature error when \`key\` is a runtime \`string\` (not a statically-known literal). Narrow the parameter type to \`keyof T\` at the function signature instead, OR widen the object type to include an index signature, OR perform a runtime \`if (key in obj)\` guard. \`as keyof T\` keeps the call site type-passing while losing all the runtime safety the index signature gave.
+   - \`!\` non-null assertions to dodge TS18047/TS2532 \u2014 narrow with a truthiness check or optional-chaining + nullish-coalesce that actually preserves the narrow on the true branch.
+
+2. Removing or substituting a declared dependency to dodge a missing-import error. If \`package.json\` lists the package and the source uses it, RESTORE the import. Do not substitute a different library (e.g. \`bcrypt\` \u2192 \`crypto.subtle.digest\`) \u2014 that is a security regression even when tsc accepts it.
+
+3. SQL / NoSQL / shell injection patterns:
+   - String concatenation of user-controlled values into raw query strings (\`db.execute("WHERE id = " + userId)\`). Use the library's tagged-template / parameterized form (\`db.execute(sql\\\`WHERE id = \\\${userId}\\\`)\` for Drizzle; placeholders for Prisma / mysql2; etc).
+   - Never use template literals to interpolate user input into a raw SQL string unless the literal is itself a parameterizing tagged template.
+
+4. React XSS escape-hatches:
+   - \`dangerouslySetInnerHTML\` to dodge a children-type error. If a component expects \`children: string\` and you have arbitrary HTML, render it as text (JSX \`{value}\` auto-escapes) or sanitize via a library (DOMPurify) and document the assumption.
+   - Setting \`innerHTML\` directly on a DOM element from user input.
+
+These anti-patterns apply only to the listed shapes. For other diagnostics, follow the regular Rules above and pick the smallest valid fix \u2014 including legitimate uses of \`as unknown as T\`, \`keyof typeof T\` (as a type annotation, not a cast), or restructuring a type union. Do not omit a block just because the fix involves an \`as\` cast or a structural change \u2014 only omit when the fix would match one of the four anti-patterns above.
+
+When a type, union variant, or interface property has been removed or renamed, consumer code that referenced the old shape needs FULL cleanup, not partial cleanup:
+
+- TS2322 / TS2353 (excess property in object literal): REMOVE the excess property from the literal. Do not retain it. Example: if a \`{ type: 'archived', userId, reason, at }\` object now needs \`type: 'created'\` and the \`created\` variant has no \`reason\` field, the fix is to drop \`reason\` from the object \u2014 keeping it produces a fresh TS2353. This is field deletion, not "silencing an error" \u2014 there is no error to silence; the property genuinely no longer belongs.
+- Function parameters and return types that exist solely to support the removed variant (e.g. a \`reason: string\` parameter on a function that no longer needs reasons) should be dropped along with their use sites in the same SEARCH/REPLACE block.
+- TS2367 (comparison with no overlap): if comparing against a removed literal, EITHER pick a still-valid literal that preserves the function's spirit, OR delete the comparison and its branch if neither makes sense. Don't leave a comparison against a now-invalid literal.
+
+The goal is internal consistency: if you change one reference to a removed variant/property, sweep ALL references in this file in the same patch. A half-cleanup leaves new tsc errors and is worse than the original state.`;
 function workspaceRelative(workspaceRoot, p) {
-  return path5.isAbsolute(p) ? path5.relative(workspaceRoot, p) : p;
+  return path6.isAbsolute(p) ? path6.relative(workspaceRoot, p) : p;
 }
 function buildSystemBlock(context, erroredFile) {
   const wsRel = workspaceRelative(context.workspaceRoot, erroredFile);
-  const absPath = path5.isAbsolute(erroredFile) ? erroredFile : path5.join(context.workspaceRoot, erroredFile);
+  const absPath = path6.isAbsolute(erroredFile) ? erroredFile : path6.join(context.workspaceRoot, erroredFile);
   let fileContent;
   try {
-    fileContent = fs5.readFileSync(absPath, "utf-8");
+    fileContent = fs6.readFileSync(absPath, "utf-8");
   } catch {
     fileContent = "(file unreadable)";
   }
@@ -827,10 +932,15 @@ function buildSystemBlock(context, erroredFile) {
   const typeContexts = [];
   const seen = /* @__PURE__ */ new Set();
   for (const diag of fileDiags) {
-    const ctx = getTypeContext({
-      workspaceRoot: context.workspaceRoot,
-      diagnostic: diag
-    });
+    let ctx;
+    try {
+      ctx = getTypeContext({
+        workspaceRoot: context.workspaceRoot,
+        diagnostic: diag
+      });
+    } catch {
+      continue;
+    }
     if (!ctx.typeDeclaration) continue;
     const key = `${ctx.typeDeclaration.file}:${ctx.typeDeclaration.symbol}`;
     if (seen.has(key)) continue;
@@ -841,22 +951,21 @@ function buildSystemBlock(context, erroredFile) {
 ` + ctx.typeDeclaration.lines
     );
   }
-  const parts = [
-    SYSTEM_INSTRUCTIONS,
-    "",
-    `### file: ${wsRel}`,
-    "```ts",
-    fileContent.replace(/\n$/, ""),
-    "```"
-  ];
+  const parts = [SYSTEM_INSTRUCTIONS, ""];
+  const libMigrations = context.libraryMigrations ?? [];
+  if (libMigrations.length > 0) {
+    parts.push(formatLibraryMigrationsBlock(libMigrations), "");
+  }
+  parts.push(`### file: ${wsRel}`, "```ts", fileContent.replace(/\n$/, ""), "```");
   if (typeContexts.length > 0) {
     parts.push("", "### type-context");
     for (const tc of typeContexts) {
       parts.push("```ts", tc, "```");
     }
   }
-  if (context.taskDescription) {
-    parts.push("", `### task`, context.taskDescription);
+  const taskHeadline = formatLibraryMigrationsTaskDescription(libMigrations) ?? context.taskDescription;
+  if (taskHeadline) {
+    parts.push("", `### task`, taskHeadline);
   }
   return parts.join("\n");
 }
@@ -920,8 +1029,8 @@ async function mendSingleFile(opts) {
 }
 
 // src/stubAndContinue.ts
-import * as fs6 from "node:fs";
-import * as path6 from "node:path";
+import * as fs7 from "node:fs";
+import * as path7 from "node:path";
 var noopLogger = { info: () => {
 }, warn: () => {
 }, error: () => {
@@ -938,17 +1047,17 @@ function groupByLine(diagnostics) {
   return groups;
 }
 function resolveFile(diagnosticFile, workspaceRoot) {
-  return path6.isAbsolute(diagnosticFile) ? diagnosticFile : path6.resolve(workspaceRoot, diagnosticFile);
+  return path7.isAbsolute(diagnosticFile) ? diagnosticFile : path7.resolve(workspaceRoot, diagnosticFile);
 }
 function shouldSkipFile(file, workspaceRoot) {
-  const rel = path6.relative(workspaceRoot, file);
-  if (rel.startsWith("node_modules") || rel.includes(`${path6.sep}node_modules${path6.sep}`)) {
+  const rel = path7.relative(workspaceRoot, file);
+  if (rel.startsWith("node_modules") || rel.includes(`${path7.sep}node_modules${path7.sep}`)) {
     return "node_modules";
   }
   if (file.endsWith(".d.ts")) {
     return "declaration_file";
   }
-  if (!fs6.existsSync(file)) {
+  if (!fs7.existsSync(file)) {
     return "file_not_found";
   }
   return null;
@@ -1007,7 +1116,7 @@ function stubAndContinue(opts) {
       }
       continue;
     }
-    const source = fs6.readFileSync(file, "utf-8");
+    const source = fs7.readFileSync(file, "utf-8");
     const eol = source.includes("\r\n") ? "\r\n" : "\n";
     const lines = source.split(/\r?\n/);
     entries.sort((a, b) => b.line - a.line);
@@ -1049,10 +1158,10 @@ function stubAndContinue(opts) {
     if (edited) {
       filesEditedSet.add(file);
       if (!dryRun) {
-        fs6.writeFileSync(file, lines.join(eol), "utf-8");
-        logger.info(`[stub-and-continue] stubbed ${entries.length} site(s) in ${path6.relative(workspaceRoot, file)}`);
+        fs7.writeFileSync(file, lines.join(eol), "utf-8");
+        logger.info(`[stub-and-continue] stubbed ${entries.length} site(s) in ${path7.relative(workspaceRoot, file)}`);
       } else {
-        logger.info(`[stub-and-continue] (dry-run) would stub ${entries.length} site(s) in ${path6.relative(workspaceRoot, file)}`);
+        logger.info(`[stub-and-continue] (dry-run) would stub ${entries.length} site(s) in ${path7.relative(workspaceRoot, file)}`);
       }
     }
   }
@@ -1103,8 +1212,9 @@ function refreshDiagnostics(workspaceRoot, files) {
   return result.diagnostics.filter((d) => d.category === "error");
 }
 async function runMendLoop(opts) {
-  const { context, llm, maxIterations = 3, dryRun = false, stubOnFailure = false, _callLLM } = opts;
+  const { context: rawContext, llm, maxIterations = 3, dryRun = false, stubOnFailure = false, _callLLM } = opts;
   const startMs = Date.now();
+  const context = rawContext.libraryMigrations === void 0 ? { ...rawContext, libraryMigrations: detectLibraryMigrations(rawContext.workspaceRoot) } : rawContext;
   const diagnosticsBefore = context.diagnostics.filter((d) => d.category === "error");
   if (diagnosticsBefore.length === 0) {
     return {
@@ -1217,7 +1327,7 @@ function discoverTsFiles(workspaceRoot) {
   const walk = (dir) => {
     let entries;
     try {
-      entries = fs7.readdirSync(dir, { withFileTypes: true });
+      entries = fs8.readdirSync(dir, { withFileTypes: true });
     } catch {
       return;
     }
@@ -1226,10 +1336,10 @@ function discoverTsFiles(workspaceRoot) {
         if (skip.has(e.name)) {
           continue;
         }
-        walk(path7.join(dir, e.name));
+        walk(path8.join(dir, e.name));
       } else if (e.isFile() && !e.name.endsWith(".d.ts")) {
         if (e.name.endsWith(".ts") || e.name.endsWith(".tsx")) {
-          out.push(path7.relative(workspaceRoot, path7.join(dir, e.name)));
+          out.push(path8.relative(workspaceRoot, path8.join(dir, e.name)));
         }
       }
     }
@@ -1240,10 +1350,10 @@ function discoverTsFiles(workspaceRoot) {
 function runValidationLoop(opts) {
   const { workspaceRoot, skipLSPFixer = false, dryRun = false } = opts;
   const logger = opts.logger ?? noopLogger3;
-  if (!fs7.existsSync(workspaceRoot)) {
+  if (!fs8.existsSync(workspaceRoot)) {
     throw new Error(`workspace not found: ${workspaceRoot}`);
   }
-  if (!fs7.existsSync(path7.join(workspaceRoot, "tsconfig.json"))) {
+  if (!fs8.existsSync(path8.join(workspaceRoot, "tsconfig.json"))) {
     throw new Error(`no tsconfig.json in ${workspaceRoot}`);
   }
   const targetFiles = opts.targetFiles ?? discoverTsFiles(workspaceRoot);
@@ -1313,7 +1423,8 @@ function parseArgs(argv) {
     llm: false,
     llmModel: "claude-haiku-4-5",
     llmMaxIterations: 3,
-    llmBudgetUsd: void 0
+    llmBudgetUsd: void 0,
+    noLibraryHints: false
   };
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
@@ -1347,6 +1458,8 @@ function parseArgs(argv) {
         process.exit(2);
       }
       args.llmBudgetUsd = v;
+    } else if (a === "--no-library-hints") {
+      args.noLibraryHints = true;
     } else if (a === "--help" || a === "-h") {
       printHelp();
       process.exit(0);
@@ -1380,6 +1493,12 @@ Layer 2 (opt-in \u2014 single-file LLM mend via Anthropic):
                               Cost estimate is 0 for unknown models.
   --llm-max-iterations <N>    Cap on LLM retries (default: 3)
   --llm-budget-usd <amount>   Soft cost cap. Exits with code 3 if exceeded.
+  --no-library-hints          Disable auto-detection of library breaking-change
+                              hints (vite-plugin-svgr v4 ?react migration,
+                              Next.js 15 async params, etc.). When workspace
+                              package.json contains a known migration target,
+                              tsfix injects hints into Layer 2's prompt + skips
+                              Layer 0/1 (whose quick-fix would conflict).
 
 Layer 2 requires ANTHROPIC_API_KEY in the environment.
 
@@ -1454,12 +1573,12 @@ TSC Defense Stack \u2014 ${r.workspace}${r.dryRun ? " (dry-run)" : ""}
 }
 async function main() {
   const args = parseArgs(process.argv.slice(2));
-  const workspaceRoot = path8.resolve(args.workspace);
-  if (!fs8.existsSync(workspaceRoot)) {
+  const workspaceRoot = path9.resolve(args.workspace);
+  if (!fs9.existsSync(workspaceRoot)) {
     console.error(`error: workspace not found: ${workspaceRoot}`);
     return 2;
   }
-  if (!fs8.existsSync(path8.join(workspaceRoot, "tsconfig.json"))) {
+  if (!fs9.existsSync(path9.join(workspaceRoot, "tsconfig.json"))) {
     console.error(`error: no tsconfig.json in ${workspaceRoot}`);
     return 2;
   }
@@ -1470,15 +1589,23 @@ async function main() {
     console.error("error: no .ts/.tsx files found in workspace");
     return 2;
   }
+  const libraryMigrations = args.noLibraryHints ? [] : detectLibraryMigrations(workspaceRoot);
+  const migrationApplies = args.llm && libraryMigrations.length > 0;
+  if (migrationApplies && !args.noLsp) {
+    logger.info(
+      `Library migrations detected (${libraryMigrations.map((h) => h.name).join(", ")}) \u2014 skipping Layer 0/1 to let Layer 2 apply the migration target. Use --no-library-hints to disable.`
+    );
+  }
+  const effectiveNoLsp = args.noLsp || migrationApplies;
   const loop = runValidationLoop({
     workspaceRoot,
     targetFiles,
-    skipLSPFixer: args.noLsp,
+    skipLSPFixer: effectiveNoLsp,
     dryRun: args.dryRun,
     logger
   });
   const report = {
-    workspace: path8.relative(process.cwd(), workspaceRoot) || workspaceRoot,
+    workspace: path9.relative(process.cwd(), workspaceRoot) || workspaceRoot,
     errorsBefore: loop.errorsBefore,
     lspFixer: args.noLsp ? { ran: false, fixesApplied: 0, filesEdited: [], iterations: 0 } : loop.lspFixer,
     layer2: null,
@@ -1509,7 +1636,11 @@ async function main() {
     const context = {
       workspaceRoot,
       diagnostics: errorDiags,
-      erroredFiles: Array.from(new Set(errorDiags.map((d) => d.file)))
+      erroredFiles: Array.from(new Set(errorDiags.map((d) => d.file))),
+      // Explicitly pass migrations so `runMendLoop` doesn't re-detect.
+      // `[]` is meaningful — it means "we know there are none" — vs
+      // `undefined` which would trigger auto-detect.
+      libraryMigrations
     };
     const layer2Start = Date.now();
     const mend = await runMendLoop({

package/dist/index.d.ts

@@ -156,6 +156,20 @@ export interface MendContext {
     priorTaskExports?: string;
     /** Compact type signatures of installed npm dependencies (helps prevent API hallucination). */
     installedTypes?: string;
+    /**
+     * Library-migration hints for installed deps whose breaking changes are
+     * known to mislead tsc's quick-fix. When non-empty, the Layer 2 prompt
+     * leads with these and the `taskDescription` is overridden to name them.
+     *
+     * Auto-populated by `runMendLoop` from `<workspaceRoot>/package.json` if
+     * the caller doesn't set it. Pass `[]` explicitly to opt out.
+     *
+     * See `libraryMigrations.ts` for the built-in registry.
+     */
+    libraryMigrations?: Array<{
+        name: string;
+        hint: string;
+    }>;
 }
 /**
  * Per-layer event for streaming telemetry across the validate → fix → mend
@@ -194,3 +208,5 @@ export { runMendLoop } from "./runMendLoop.js";
 export type { RunMendLoopOptions, RunMendLoopResult, MendLoopIteration, StopReason, } from "./runMendLoop.js";
 export { stubAndContinue } from "./stubAndContinue.js";
 export type { StubAndContinueOptions, StubAndContinueResult, AppliedStub, SkippedStub, } from "./stubAndContinue.js";
+export { BUILT_IN_LIBRARY_MIGRATIONS, detectLibraryMigrations, formatLibraryMigrationsBlock, formatLibraryMigrationsTaskDescription, } from "./libraryMigrations.js";
+export type { LibraryMigrationHint } from "./libraryMigrations.js";

package/dist/index.js

@@ -475,8 +475,8 @@ function resetLSPFixerCache() {
 }
 
 // src/index.ts
-import * as fs7 from "node:fs";
-import * as path7 from "node:path";
+import * as fs8 from "node:fs";
+import * as path8 from "node:path";
 
 // src/typeContext.ts
 import * as fs3 from "node:fs";
@@ -554,9 +554,20 @@ function isLibFile(fileName) {
 }
 function findTypeDeclaration(checker, startNode, maxWalkUp = 4) {
   const tryResolve = (n) => {
-    const type = checker.getTypeAtLocation(n);
-    const symbol = type.getSymbol() ?? type.aliasSymbol;
-    const declarations = symbol?.getDeclarations();
+    let type;
+    try {
+      type = checker.getTypeAtLocation(n);
+    } catch {
+      return void 0;
+    }
+    let symbol;
+    let declarations;
+    try {
+      symbol = type.getSymbol() ?? type.aliasSymbol;
+      declarations = symbol?.getDeclarations();
+    } catch {
+      return void 0;
+    }
     if (!declarations || declarations.length === 0) return void 0;
     const nonLib = declarations.find((d) => !isLibFile(d.getSourceFile().fileName));
     if (!nonLib) return void 0;
@@ -789,10 +800,77 @@ function applyEditBlocks(opts) {
 }
 
 // src/mendAgent.ts
-import * as fs5 from "node:fs";
-import * as path5 from "node:path";
+import * as fs6 from "node:fs";
+import * as path6 from "node:path";
 import { generateText } from "ai";
 import { createAnthropic } from "@ai-sdk/anthropic";
+
+// src/libraryMigrations.ts
+import * as fs5 from "node:fs";
+import * as path5 from "node:path";
+var BUILT_IN_LIBRARY_MIGRATIONS = [
+  {
+    match: { name: "vite-plugin-svgr", minMajor: 4 },
+    hint: "vite-plugin-svgr v4+ (released 2023-09-20) changed how SVG imports work. The PREVIOUS form `import { ReactComponent as X } from './x.svg'` no longer works \u2014 the ambient module declaration now only matches `*.svg?react`. Correct fix: `import X from './x.svg?react'` (default import + ?react query suffix). DO NOT use tsc's quick-fix `import X from './x.svg'` (no query) \u2014 that type-checks but resolves to the asset URL string at runtime, not a component."
+  },
+  {
+    match: { name: "next", minMajor: 15 },
+    hint: "Next.js 15 changed dynamic-route page props: `params` and `searchParams` are now `Promise<...>` instead of plain objects. The fix shape is: change the page's `params` type to `Promise<{...}>`, mark the page component `async`, and `await params` inside. See https://nextjs.org/docs/app/api-reference/file-conventions/page."
+  },
+  {
+    match: { name: "ai", minMajor: 3, maxMajor: 4 },
+    hint: "Vercel AI SDK v3.x has overload-narrowing issues with `generateObject`. If passing a schema through an object widened with `satisfies Record<K, z.ZodTypeAny>`, the typed overload silently falls back to `output: 'no-schema'` (which forbids the `schema` property). Fix: drop the `satisfies Record<...>` widener, or cast the schema at the call site."
+  },
+  {
+    match: { name: "drizzle-orm" },
+    hint: "Drizzle ORM table access has two distinct surfaces. `db.<table>` is for `select/insert/update/delete` builders. `db.query.<table>` is the Relational Queries API for `findFirst`/`findMany` with relation loading. If you see `Property '<table>' does not exist on type 'PostgresJsDatabase<...>'` when trying to call `.findFirst`/`.findMany`, use `db.query.<table>` instead."
+  }
+];
+function parseMajor(spec) {
+  const m = spec.match(/(\d+)(?:\.\d+)*/);
+  return m ? parseInt(m[1], 10) : null;
+}
+function detectLibraryMigrations(workspaceRoot, registry = BUILT_IN_LIBRARY_MIGRATIONS) {
+  let pkg;
+  try {
+    const pkgPath = path5.join(workspaceRoot, "package.json");
+    if (!fs5.existsSync(pkgPath)) return [];
+    pkg = JSON.parse(fs5.readFileSync(pkgPath, "utf-8"));
+  } catch {
+    return [];
+  }
+  const allDeps = { ...pkg.dependencies ?? {}, ...pkg.devDependencies ?? {} };
+  const hints = [];
+  for (const entry of registry) {
+    const { match, hint } = entry;
+    const versionSpec = allDeps[match.name];
+    if (!versionSpec) continue;
+    const major = parseMajor(versionSpec);
+    if (match.minMajor != null && (major == null || major < match.minMajor)) continue;
+    if (match.maxMajor != null && (major == null || major > match.maxMajor)) continue;
+    hints.push({ name: `${match.name}@${versionSpec}`, hint });
+  }
+  return hints;
+}
+function formatLibraryMigrationsBlock(hints) {
+  if (hints.length === 0) return "";
+  const lines = ["### library-migrations", ""];
+  lines.push(
+    "These migrations apply to your workspace's installed deps. When tsc's quick-fix conflicts with the migration target below, PREFER the migration target. tsc only checks types, not runtime semantics \u2014 these hints encode runtime constraints tsc cannot see."
+  );
+  lines.push("");
+  for (const h of hints) {
+    lines.push(`- [${h.name}] ${h.hint}`);
+  }
+  return lines.join("\n");
+}
+function formatLibraryMigrationsTaskDescription(hints) {
+  if (hints.length === 0) return void 0;
+  const names = hints.map((h) => h.name).join(", ");
+  return `Library migration: ${names}`;
+}
+
+// src/mendAgent.ts
 var SYSTEM_INSTRUCTIONS = `You are a TypeScript code-repair tool. You receive a TypeScript file with one or more compiler errors and resolve them.
 
 Output ONLY SEARCH/REPLACE blocks. No prose, no explanations, no XML wrappers.
@@ -813,16 +891,43 @@ Rules:
 - REPLACE must be valid TypeScript that resolves the diagnostic.
 - Do not invent imports, types, properties, or values. Use only what the type-context section shows.
 - One SEARCH/REPLACE block per logical change.
-- If you cannot resolve a diagnostic with the information given, omit a block for it.`;
+- If you cannot resolve a diagnostic with the information given, omit a block for it.
+
+Anti-patterns \u2014 these silence the type error but break runtime semantics, lose type safety, or introduce security regressions. Do NOT emit a patch that does any of the following:
+
+1. Type-assertion escape-hatches that hide the error rather than fix it:
+   - \`x as any\` / \`x as unknown as T\` to dodge a real mismatch.
+   - \`key as keyof T\` to silence a TS7053 index-signature error when \`key\` is a runtime \`string\` (not a statically-known literal). Narrow the parameter type to \`keyof T\` at the function signature instead, OR widen the object type to include an index signature, OR perform a runtime \`if (key in obj)\` guard. \`as keyof T\` keeps the call site type-passing while losing all the runtime safety the index signature gave.
+   - \`!\` non-null assertions to dodge TS18047/TS2532 \u2014 narrow with a truthiness check or optional-chaining + nullish-coalesce that actually preserves the narrow on the true branch.
+
+2. Removing or substituting a declared dependency to dodge a missing-import error. If \`package.json\` lists the package and the source uses it, RESTORE the import. Do not substitute a different library (e.g. \`bcrypt\` \u2192 \`crypto.subtle.digest\`) \u2014 that is a security regression even when tsc accepts it.
+
+3. SQL / NoSQL / shell injection patterns:
+   - String concatenation of user-controlled values into raw query strings (\`db.execute("WHERE id = " + userId)\`). Use the library's tagged-template / parameterized form (\`db.execute(sql\\\`WHERE id = \\\${userId}\\\`)\` for Drizzle; placeholders for Prisma / mysql2; etc).
+   - Never use template literals to interpolate user input into a raw SQL string unless the literal is itself a parameterizing tagged template.
+
+4. React XSS escape-hatches:
+   - \`dangerouslySetInnerHTML\` to dodge a children-type error. If a component expects \`children: string\` and you have arbitrary HTML, render it as text (JSX \`{value}\` auto-escapes) or sanitize via a library (DOMPurify) and document the assumption.
+   - Setting \`innerHTML\` directly on a DOM element from user input.
+
+These anti-patterns apply only to the listed shapes. For other diagnostics, follow the regular Rules above and pick the smallest valid fix \u2014 including legitimate uses of \`as unknown as T\`, \`keyof typeof T\` (as a type annotation, not a cast), or restructuring a type union. Do not omit a block just because the fix involves an \`as\` cast or a structural change \u2014 only omit when the fix would match one of the four anti-patterns above.
+
+When a type, union variant, or interface property has been removed or renamed, consumer code that referenced the old shape needs FULL cleanup, not partial cleanup:
+
+- TS2322 / TS2353 (excess property in object literal): REMOVE the excess property from the literal. Do not retain it. Example: if a \`{ type: 'archived', userId, reason, at }\` object now needs \`type: 'created'\` and the \`created\` variant has no \`reason\` field, the fix is to drop \`reason\` from the object \u2014 keeping it produces a fresh TS2353. This is field deletion, not "silencing an error" \u2014 there is no error to silence; the property genuinely no longer belongs.
+- Function parameters and return types that exist solely to support the removed variant (e.g. a \`reason: string\` parameter on a function that no longer needs reasons) should be dropped along with their use sites in the same SEARCH/REPLACE block.
+- TS2367 (comparison with no overlap): if comparing against a removed literal, EITHER pick a still-valid literal that preserves the function's spirit, OR delete the comparison and its branch if neither makes sense. Don't leave a comparison against a now-invalid literal.
+
+The goal is internal consistency: if you change one reference to a removed variant/property, sweep ALL references in this file in the same patch. A half-cleanup leaves new tsc errors and is worse than the original state.`;
 function workspaceRelative(workspaceRoot, p) {
-  return path5.isAbsolute(p) ? path5.relative(workspaceRoot, p) : p;
+  return path6.isAbsolute(p) ? path6.relative(workspaceRoot, p) : p;
 }
 function buildSystemBlock(context, erroredFile) {
   const wsRel = workspaceRelative(context.workspaceRoot, erroredFile);
-  const absPath = path5.isAbsolute(erroredFile) ? erroredFile : path5.join(context.workspaceRoot, erroredFile);
+  const absPath = path6.isAbsolute(erroredFile) ? erroredFile : path6.join(context.workspaceRoot, erroredFile);
   let fileContent;
   try {
-    fileContent = fs5.readFileSync(absPath, "utf-8");
+    fileContent = fs6.readFileSync(absPath, "utf-8");
   } catch {
     fileContent = "(file unreadable)";
   }
@@ -832,10 +937,15 @@ function buildSystemBlock(context, erroredFile) {
   const typeContexts = [];
   const seen = /* @__PURE__ */ new Set();
   for (const diag of fileDiags) {
-    const ctx = getTypeContext({
-      workspaceRoot: context.workspaceRoot,
-      diagnostic: diag
-    });
+    let ctx;
+    try {
+      ctx = getTypeContext({
+        workspaceRoot: context.workspaceRoot,
+        diagnostic: diag
+      });
+    } catch {
+      continue;
+    }
     if (!ctx.typeDeclaration) continue;
     const key = `${ctx.typeDeclaration.file}:${ctx.typeDeclaration.symbol}`;
     if (seen.has(key)) continue;
@@ -846,22 +956,21 @@ function buildSystemBlock(context, erroredFile) {
 ` + ctx.typeDeclaration.lines
     );
   }
-  const parts = [
-    SYSTEM_INSTRUCTIONS,
-    "",
-    `### file: ${wsRel}`,
-    "```ts",
-    fileContent.replace(/\n$/, ""),
-    "```"
-  ];
+  const parts = [SYSTEM_INSTRUCTIONS, ""];
+  const libMigrations = context.libraryMigrations ?? [];
+  if (libMigrations.length > 0) {
+    parts.push(formatLibraryMigrationsBlock(libMigrations), "");
+  }
+  parts.push(`### file: ${wsRel}`, "```ts", fileContent.replace(/\n$/, ""), "```");
   if (typeContexts.length > 0) {
     parts.push("", "### type-context");
     for (const tc of typeContexts) {
       parts.push("```ts", tc, "```");
     }
   }
-  if (context.taskDescription) {
-    parts.push("", `### task`, context.taskDescription);
+  const taskHeadline = formatLibraryMigrationsTaskDescription(libMigrations) ?? context.taskDescription;
+  if (taskHeadline) {
+    parts.push("", `### task`, taskHeadline);
   }
   return parts.join("\n");
 }
@@ -925,8 +1034,8 @@ async function mendSingleFile(opts) {
 }
 
 // src/stubAndContinue.ts
-import * as fs6 from "node:fs";
-import * as path6 from "node:path";
+import * as fs7 from "node:fs";
+import * as path7 from "node:path";
 var noopLogger = { info: () => {
 }, warn: () => {
 }, error: () => {
@@ -943,17 +1052,17 @@ function groupByLine(diagnostics) {
   return groups;
 }
 function resolveFile(diagnosticFile, workspaceRoot) {
-  return path6.isAbsolute(diagnosticFile) ? diagnosticFile : path6.resolve(workspaceRoot, diagnosticFile);
+  return path7.isAbsolute(diagnosticFile) ? diagnosticFile : path7.resolve(workspaceRoot, diagnosticFile);
 }
 function shouldSkipFile(file, workspaceRoot) {
-  const rel = path6.relative(workspaceRoot, file);
-  if (rel.startsWith("node_modules") || rel.includes(`${path6.sep}node_modules${path6.sep}`)) {
+  const rel = path7.relative(workspaceRoot, file);
+  if (rel.startsWith("node_modules") || rel.includes(`${path7.sep}node_modules${path7.sep}`)) {
     return "node_modules";
   }
   if (file.endsWith(".d.ts")) {
     return "declaration_file";
   }
-  if (!fs6.existsSync(file)) {
+  if (!fs7.existsSync(file)) {
     return "file_not_found";
   }
   return null;
@@ -1012,7 +1121,7 @@ function stubAndContinue(opts) {
       }
       continue;
     }
-    const source = fs6.readFileSync(file, "utf-8");
+    const source = fs7.readFileSync(file, "utf-8");
     const eol = source.includes("\r\n") ? "\r\n" : "\n";
     const lines = source.split(/\r?\n/);
     entries.sort((a, b) => b.line - a.line);
@@ -1054,10 +1163,10 @@ function stubAndContinue(opts) {
     if (edited) {
       filesEditedSet.add(file);
       if (!dryRun) {
-        fs6.writeFileSync(file, lines.join(eol), "utf-8");
-        logger.info(`[stub-and-continue] stubbed ${entries.length} site(s) in ${path6.relative(workspaceRoot, file)}`);
+        fs7.writeFileSync(file, lines.join(eol), "utf-8");
+        logger.info(`[stub-and-continue] stubbed ${entries.length} site(s) in ${path7.relative(workspaceRoot, file)}`);
       } else {
-        logger.info(`[stub-and-continue] (dry-run) would stub ${entries.length} site(s) in ${path6.relative(workspaceRoot, file)}`);
+        logger.info(`[stub-and-continue] (dry-run) would stub ${entries.length} site(s) in ${path7.relative(workspaceRoot, file)}`);
       }
     }
   }
@@ -1108,8 +1217,9 @@ function refreshDiagnostics(workspaceRoot, files) {
   return result.diagnostics.filter((d) => d.category === "error");
 }
 async function runMendLoop(opts) {
-  const { context, llm, maxIterations = 3, dryRun = false, stubOnFailure = false, _callLLM } = opts;
+  const { context: rawContext, llm, maxIterations = 3, dryRun = false, stubOnFailure = false, _callLLM } = opts;
   const startMs = Date.now();
+  const context = rawContext.libraryMigrations === void 0 ? { ...rawContext, libraryMigrations: detectLibraryMigrations(rawContext.workspaceRoot) } : rawContext;
   const diagnosticsBefore = context.diagnostics.filter((d) => d.category === "error");
   if (diagnosticsBefore.length === 0) {
     return {
@@ -1222,7 +1332,7 @@ function discoverTsFiles(workspaceRoot) {
   const walk = (dir) => {
     let entries;
     try {
-      entries = fs7.readdirSync(dir, { withFileTypes: true });
+      entries = fs8.readdirSync(dir, { withFileTypes: true });
     } catch {
       return;
     }
@@ -1231,10 +1341,10 @@ function discoverTsFiles(workspaceRoot) {
         if (skip.has(e.name)) {
           continue;
         }
-        walk(path7.join(dir, e.name));
+        walk(path8.join(dir, e.name));
       } else if (e.isFile() && !e.name.endsWith(".d.ts")) {
         if (e.name.endsWith(".ts") || e.name.endsWith(".tsx")) {
-          out.push(path7.relative(workspaceRoot, path7.join(dir, e.name)));
+          out.push(path8.relative(workspaceRoot, path8.join(dir, e.name)));
         }
       }
     }
@@ -1245,10 +1355,10 @@ function discoverTsFiles(workspaceRoot) {
 function runValidationLoop(opts) {
   const { workspaceRoot, skipLSPFixer = false, dryRun = false } = opts;
   const logger = opts.logger ?? noopLogger3;
-  if (!fs7.existsSync(workspaceRoot)) {
+  if (!fs8.existsSync(workspaceRoot)) {
     throw new Error(`workspace not found: ${workspaceRoot}`);
   }
-  if (!fs7.existsSync(path7.join(workspaceRoot, "tsconfig.json"))) {
+  if (!fs8.existsSync(path8.join(workspaceRoot, "tsconfig.json"))) {
     throw new Error(`no tsconfig.json in ${workspaceRoot}`);
   }
   const targetFiles = opts.targetFiles ?? discoverTsFiles(workspaceRoot);
@@ -1296,9 +1406,13 @@ function runValidationLoop(opts) {
   };
 }
 export {
+  BUILT_IN_LIBRARY_MIGRATIONS,
   applyEditBlocks,
   applySingleBlock,
+  detectLibraryMigrations,
   discoverTsFiles,
+  formatLibraryMigrationsBlock,
+  formatLibraryMigrationsTaskDescription,
   getTypeContext,
   isInProcessTscEnabled,
   isLSPFixerEnabled,

package/dist/types/index.d.ts

@@ -156,6 +156,20 @@ export interface MendContext {
     priorTaskExports?: string;
     /** Compact type signatures of installed npm dependencies (helps prevent API hallucination). */
     installedTypes?: string;
+    /**
+     * Library-migration hints for installed deps whose breaking changes are
+     * known to mislead tsc's quick-fix. When non-empty, the Layer 2 prompt
+     * leads with these and the `taskDescription` is overridden to name them.
+     *
+     * Auto-populated by `runMendLoop` from `<workspaceRoot>/package.json` if
+     * the caller doesn't set it. Pass `[]` explicitly to opt out.
+     *
+     * See `libraryMigrations.ts` for the built-in registry.
+     */
+    libraryMigrations?: Array<{
+        name: string;
+        hint: string;
+    }>;
 }
 /**
  * Per-layer event for streaming telemetry across the validate → fix → mend
@@ -194,3 +208,5 @@ export { runMendLoop } from "./runMendLoop.js";
 export type { RunMendLoopOptions, RunMendLoopResult, MendLoopIteration, StopReason, } from "./runMendLoop.js";
 export { stubAndContinue } from "./stubAndContinue.js";
 export type { StubAndContinueOptions, StubAndContinueResult, AppliedStub, SkippedStub, } from "./stubAndContinue.js";
+export { BUILT_IN_LIBRARY_MIGRATIONS, detectLibraryMigrations, formatLibraryMigrationsBlock, formatLibraryMigrationsTaskDescription, } from "./libraryMigrations.js";
+export type { LibraryMigrationHint } from "./libraryMigrations.js";

package/dist/types/libraryMigrations.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Library breaking-change registry for Layer 2.
+ *
+ * When an installed dependency has a known migration whose correct fix
+ * differs from tsc's own quick-fix suggestion, this module injects a hint
+ * into the mend prompt so the LLM doesn't blindly follow tsc.
+ *
+ * Empirically grounded — each entry corresponds to a concrete bench case
+ * where, without the hint, both haiku-4-5 and sonnet-4-5 score 0/3
+ * functional+secure and follow tsc's misleading quick-fix; with the hint,
+ * both score 3/3 functional+secure on the same fixture.
+ *
+ * Scope: library MIGRATIONS where tsc's quick-fix is misleading or where
+ * the correct fix requires syntax not present in the source. NOT for
+ * general TS errors — those are tsfix's deterministic Layer 0/1 surface.
+ */
+export interface LibraryMigrationHint {
+    /** Display name, e.g., `"vite-plugin-svgr@^4.0.0"`. Populated by detect. */
+    name: string;
+    /** Instructional text injected into the Layer 2 system prompt. */
+    hint: string;
+}
+interface RegistryEntry {
+    match: {
+        name: string;
+        minMajor?: number;
+        maxMajor?: number;
+    };
+    hint: string;
+}
+/**
+ * Built-in registry. Keep entries SMALL — only patterns where we have
+ * empirical evidence that the model picks the wrong fix without the hint.
+ * Don't lard this up with general advice; that belongs in the system prompt.
+ */
+export declare const BUILT_IN_LIBRARY_MIGRATIONS: RegistryEntry[];
+/**
+ * Read the workspace's package.json, walk dependencies + devDependencies,
+ * return the registry entries whose match rule fires.
+ *
+ * Best-effort: returns `[]` on any failure (missing package.json, parse
+ * error, etc.). Never throws.
+ */
+export declare function detectLibraryMigrations(workspaceRoot: string, registry?: RegistryEntry[]): LibraryMigrationHint[];
+/**
+ * Format an array of hints into a prompt block. Empty input → empty string,
+ * caller can short-circuit.
+ */
+export declare function formatLibraryMigrationsBlock(hints: LibraryMigrationHint[]): string;
+/**
+ * Build the one-line task description from a list of hints. Empty input
+ * → undefined. We've found that putting library names in the
+ * `taskDescription` (the prompt's headline framing) is dramatically more
+ * effective than burying the same content in the body.
+ */
+export declare function formatLibraryMigrationsTaskDescription(hints: LibraryMigrationHint[]): string | undefined;
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@shipispec/tsfix",
-	"version": "0.5.0",
+	"version": "0.6.0",
 	"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",