@shipispec/tsfix 0.4.0 → 0.5.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";
@@ -186,3 +192,5 @@ 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";

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.5.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",