@shipispec/tsfix 0.4.0 → 0.6.0

package/dist/types/index.d.ts

@@ -44,6 +44,12 @@
  * - `mendSingleFile` — single-LLM-call repair via Vercel AI SDK
  * - `runMendLoop` — bounded retry with no-progress / regression detection
  * - `parseEditBlocks` / `applyEditBlocks` — Aider-style SEARCH/REPLACE applier
+ *
+ * ## Layer 4 escape hatch (v0.5.0+)
+ *
+ * - `stubAndContinue` — insert `// @ts-expect-error - tsfix: ...` above
+ *   unresolved error sites so the workspace compiles. Opt-in: set
+ *   `stubOnFailure: true` on `runMendLoop`, or call directly.
  */
 export { runInProcessTsc, isInProcessTscEnabled, resetInProcessTscCache } from "./validatorInProcess.js";
 export type { InProcessTscOptions, InProcessTscResult } from "./validatorInProcess.js";
@@ -150,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
@@ -186,3 +206,7 @@ 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";
+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/dist/types/runMendLoop.d.ts

@@ -24,6 +24,7 @@
  */
 import type { Diagnostic, MendContext } from "./index.js";
 import { type LLMCall } from "./mendAgent.js";
+import { type AppliedStub } from "./stubAndContinue.js";
 export interface RunMendLoopOptions {
     context: MendContext;
     llm: {
@@ -35,6 +36,13 @@ export interface RunMendLoopOptions {
     maxIterations?: number;
     /** Single dry-run pass — call LLM, parse, but don't write to disk. Default false. */
     dryRun?: boolean;
+    /**
+     * When the loop exits with leftover errors (stopReason !== "fixed"),
+     * apply Layer 4 stub-and-continue: insert `// @ts-expect-error - tsfix: ...`
+     * comments above each unresolved error site so tsc exits 0. Opt-in.
+     * Default false. Ignored when `dryRun: true`.
+     */
+    stubOnFailure?: boolean;
     /** @internal — LLM call override for tests. */
     _callLLM?: LLMCall;
 }
@@ -50,7 +58,7 @@ export interface MendLoopIteration {
     /** Raw LLM response for this iteration — useful for debugging failed patches. */
     rawResponse: string;
 }
-export type StopReason = "noErrors" | "fixed" | "noProgress" | "regressed" | "maxIterations";
+export type StopReason = "noErrors" | "fixed" | "noProgress" | "regressed" | "maxIterations" | "stubbed";
 export interface RunMendLoopResult {
     iterations: MendLoopIteration[];
     diagnosticsBefore: Diagnostic[];
@@ -60,5 +68,12 @@ export interface RunMendLoopResult {
     totalInputTokens: number;
     totalOutputTokens: number;
     totalLatencyMs: number;
+    /**
+     * Layer 4 stubs applied after the LLM loop terminated with leftover
+     * errors. Present only when `stubOnFailure: true` was set. Empty array
+     * means stubOnFailure ran but nothing was eligible (e.g. all errors
+     * were in .d.ts files).
+     */
+    stubs?: AppliedStub[];
 }
 export declare function runMendLoop(opts: RunMendLoopOptions): Promise<RunMendLoopResult>;

package/dist/types/stubAndContinue.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Layer 4 — stub-and-continue escape hatch.
+ *
+ * When Layer 0/1 abstains and Layer 2's `runMendLoop` returns with leftover
+ * diagnostics (stopReason `noProgress`, `regressed`, or `maxIterations`),
+ * Layer 4 inserts a `// @ts-expect-error` directive immediately above each
+ * unresolved error site so `tsc --noEmit` exits 0. Caller's pipeline
+ * unblocks; the developer reviews the directive at leisure.
+ *
+ * Why `@ts-expect-error` and not `@ts-ignore`:
+ *   `@ts-expect-error` errors out if the next line has NO error — meaning
+ *   stale directives self-destruct as soon as the underlying issue is
+ *   fixed by other means. `@ts-ignore` is permissive and rots silently.
+ *
+ * Trust posture: Layer 4 is opt-in. The CLI default never reaches it.
+ * `runMendLoop` only invokes it when `stubOnFailure: true` is set.
+ *
+ * Idempotency: re-running on a workspace that already has stubs above the
+ * same error lines is a no-op. We detect the existing directive on the
+ * line above and skip.
+ */
+import type { Diagnostic } from "./index.js";
+export interface StubAndContinueOptions {
+    /** Absolute path to the workspace (used for resolving / skipping node_modules). */
+    workspaceRoot: string;
+    /** Unresolved diagnostics (errors only — warnings/suggestions ignored). */
+    diagnostics: Diagnostic[];
+    /** Report what would be stubbed without writing. Default false. */
+    dryRun?: boolean;
+    logger?: {
+        info(msg: string): void;
+        warn(msg: string): void;
+        error(msg: string): void;
+    };
+    /** Override the comment marker (default: "tsfix"). */
+    stubMarker?: string;
+    /** Cap on message length included in the comment. Default 120. */
+    maxMessageLength?: number;
+}
+export interface AppliedStub {
+    /** Absolute path of the file edited. */
+    file: string;
+    /**
+     * 1-based line number tsc originally reported the error on (pre-stub).
+     * In the file *after* stubbing, the error code lives at `errorLine + 1`
+     * and the `@ts-expect-error` comment lives at `errorLine`.
+     */
+    errorLine: number;
+    /** All TS codes on the error line, deduplicated and sorted. */
+    codes: string[];
+    /** The comment text actually written (without leading whitespace). */
+    commentText: string;
+}
+export interface SkippedStub {
+    file: string;
+    line: number;
+    codes: string[];
+    reason: "node_modules" | "declaration_file" | "file_not_found" | "already_stubbed" | "file_too_short";
+}
+export interface StubAndContinueResult {
+    stubsApplied: AppliedStub[];
+    skipped: SkippedStub[];
+    filesEdited: string[];
+    diagnosticsBefore: number;
+    /** Diagnostics still on disk after stubs were applied (excludes the stubbed sites). */
+    diagnosticsAfter: number;
+}
+export declare function stubAndContinue(opts: StubAndContinueOptions): StubAndContinueResult;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@shipispec/tsfix",
-	"version": "0.4.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",
@@ -52,8 +52,7 @@
 		"build": "node scripts/build.mjs",
 		"matrix": "node scripts/run-matrix.mjs",
 		"capture": "node scripts/capture-fixture.mjs",
-		"pregenerate-fixtures": "npm run build",
-		"generate-fixtures": "node scripts/generate-fixtures.mjs",
+		"generate-fixtures": "tsx scripts/generate-fixtures.mjs",
 		"prepack": "npm run build",
 		"setup-fixtures": "node -e \"require('fs').existsSync('fixtures/_shared/node_modules')||require('child_process').execSync('npm install --prefix fixtures/_shared',{stdio:'inherit'})\"",
 		"prebenchmark": "npm run setup-fixtures",