@shipispec/tsfix 0.3.0 → 0.5.0

package/dist/types/applyEditBlock.d.ts

@@ -0,0 +1,68 @@
+/**
+ * SEARCH/REPLACE block parser + fuzzy applier (Aider's `editblock` format).
+ *
+ * The format an LLM emits when asked to repair a file:
+ *
+ *     path/to/file.ts
+ *     <<<<<<< SEARCH
+ *     // exact text to find
+ *     =======
+ *     // replacement text
+ *     >>>>>>> REPLACE
+ *
+ * Fenced code blocks (```ts ... ```) around the markers are tolerated.
+ * Multiple blocks per file and multiple files per LLM output are allowed.
+ *
+ * Match algorithm (3 tiers, abstain on ambiguity):
+ *   1. Exact substring match.
+ *   2. Right-strip per line (trailing-whitespace tolerance), retry.
+ *   3. Full strip per line (leading + trailing), retry.
+ *
+ * If a tier finds multiple matches, we surface "ambiguous: N matches" rather
+ * than guess. Better to drop the patch and let the LLM emit a more specific
+ * SEARCH block on the next iteration than to silently corrupt the file.
+ */
+export interface EditBlock {
+    file: string;
+    search: string;
+    replace: string;
+}
+export interface ApplyEditBlocksOptions {
+    workspaceRoot: string;
+    blocks: EditBlock[];
+    /** Compute new content, return successes/failures, but skip writing to disk. */
+    dryRun?: boolean;
+}
+export interface ApplyResult {
+    blocks: EditBlock[];
+    applied: number;
+    filesEdited: string[];
+    failures: Array<{
+        block: EditBlock;
+        reason: string;
+    }>;
+}
+/**
+ * Extract every well-formed SEARCH/REPLACE block from raw LLM output.
+ * Malformed / truncated blocks at the tail are skipped silently.
+ */
+export declare function parseEditBlocks(llmOutput: string): EditBlock[];
+export type SingleBlockResult = {
+    newContent: string;
+    matchedTier: "exact" | "rstrip" | "strip";
+} | {
+    error: string;
+};
+/**
+ * Apply one search/replace to a single file's content. Pure — doesn't
+ * touch disk.
+ */
+export declare function applySingleBlock(fileContent: string, search: string, replace: string): SingleBlockResult;
+/**
+ * Top-level: apply a list of edit blocks. Stacks multiple blocks against
+ * the same file in memory before writing, so block N+1 sees block N's edit.
+ *
+ * Failures are collected, not thrown — the mend loop wants to know what
+ * succeeded so it can re-run tsc on the partial fix.
+ */
+export declare function applyEditBlocks(opts: ApplyEditBlocksOptions): ApplyResult;

package/dist/types/index.d.ts

@@ -4,7 +4,8 @@
  * A reusable TypeScript error-recovery agent. Validates LLM-generated (or any)
  * TypeScript code via in-process tsc, auto-fixes deterministic error classes
  * (TS2304/2305/2552/2724) via TypeScript's built-in code-fix engine, and
- * exposes hooks for LLM-driven repair (planned, not yet shipped).
+ * runs Layer 2 LLM mend (single-file repair via Vercel AI SDK + Anthropic)
+ * on what survives.
  *
  * ## Quick start (library)
  *
@@ -31,15 +32,24 @@
  * - `runInProcessTsc` — just type-check, returns structured diagnostics
  * - `runLSPFixerPass` — just the auto-fix pass, edits files in place
  *
- * ## Public types for downstream LLM-mend integrations
+ * ## Public types for the LLM-mend layer
  *
  * - `Diagnostic` — single tsc error (re-exported from `runInProcessTsc`)
- * - `MendContext` — input contract for a Layer 2–4 LLM-mend agent
+ * - `MendContext` — input contract for the Layer 2–4 LLM-mend agent
  * - `LayerEvent` — per-layer event shape for streaming telemetry
  *
- * The mend agents themselves (`@shipispec/tsmend`, planned) consume these
- * types but are not shipped from this package — `tsfix` stays Layer 0–1
- * deterministic.
+ * ## Layer 2 mend API (v0.4.0+)
+ *
+ * - `getTypeContext` — TS Language Service type-declaration injection
+ * - `mendSingleFile` — single-LLM-call repair via Vercel AI SDK
+ * - `runMendLoop` — bounded retry with no-progress / regression detection
+ * - `parseEditBlocks` / `applyEditBlocks` — Aider-style SEARCH/REPLACE applier
+ *
+ * ## 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";
@@ -174,3 +184,13 @@ export interface LayerEvent {
     /** `Date.now()` at emission. */
     ts: number;
 }
+export { getTypeContext, resetTypeContextCache } from "./typeContext.js";
+export type { TypeContextOptions, TypeContext } from "./typeContext.js";
+export { parseEditBlocks, applySingleBlock, applyEditBlocks } from "./applyEditBlock.js";
+export type { EditBlock, ApplyEditBlocksOptions, ApplyResult, SingleBlockResult, } from "./applyEditBlock.js";
+export { mendSingleFile } from "./mendAgent.js";
+export type { MendSingleFileOptions, MendSingleFileResult, LLMCall } from "./mendAgent.js";
+export { runMendLoop } from "./runMendLoop.js";
+export type { RunMendLoopOptions, RunMendLoopResult, MendLoopIteration, StopReason, } from "./runMendLoop.js";
+export { stubAndContinue } from "./stubAndContinue.js";
+export type { StubAndContinueOptions, StubAndContinueResult, AppliedStub, SkippedStub, } from "./stubAndContinue.js";

package/dist/types/mendAgent.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Single-file LLM mend (Layer 2).
+ *
+ * Builds a prompt of:
+ *   - System block: instructions + the erroring file's full content + type
+ *     context resolved through the TS Language Service for each diagnostic.
+ *   - User block: the diagnostics themselves (changes per iteration; cheap).
+ *
+ * Sends to Anthropic via Vercel AI SDK, parses the SEARCH/REPLACE response,
+ * applies via `applyEditBlocks`. Multi-file scope is Layer 3 (deferred to
+ * tsmend v0.2).
+ *
+ * Prompt-cache breakpoint placement is intentionally simple in v0.1.0 — we
+ * pass the whole system block as one cached unit. Future tuning belongs in
+ * `runMendLoop` once we have benchmark data on hit rates.
+ */
+import type { MendContext } from "./index.js";
+import { type ApplyResult, type EditBlock } from "./applyEditBlock.js";
+export interface MendSingleFileOptions {
+    context: MendContext;
+    llm: {
+        provider: "anthropic";
+        model: string;
+        apiKey: string;
+    };
+    /** Compute and parse patches but skip writing to disk. Default false. */
+    dryRun?: boolean;
+    /** @internal — LLM call override. Tests inject a fake; real callers leave it. */
+    _callLLM?: LLMCall;
+}
+export interface MendSingleFileResult {
+    rawResponse: string;
+    blocks: EditBlock[];
+    apply: ApplyResult;
+    inputTokens: number;
+    outputTokens: number;
+    latencyMs: number;
+}
+export type LLMCall = (params: {
+    systemBlock: string;
+    userBlock: string;
+    model: string;
+    apiKey: string;
+}) => Promise<{
+    text: string;
+    inputTokens: number;
+    outputTokens: number;
+}>;
+/** @internal — exported for unit tests. */
+export declare function buildSystemBlock(context: MendContext, erroredFile: string): string;
+/** @internal — exported for unit tests. */
+export declare function buildUserBlock(context: MendContext, erroredFile: string): string;
+export declare function mendSingleFile(opts: MendSingleFileOptions): Promise<MendSingleFileResult>;

package/dist/types/runMendLoop.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Bounded mend loop with no-progress detection.
+ *
+ *   1. Run tsc (`runInProcessTsc` from tsfix) to capture baseline diagnostics.
+ *   2. If clean → return immediately with `stopReason: "noErrors"`.
+ *   3. For up to `maxIterations`:
+ *        a. Build a per-iteration MendContext scoped to the current errors.
+ *        b. Call `mendSingleFile` (LLM → SEARCH/REPLACE → apply).
+ *        c. Re-run tsc.
+ *        d. Compare error-signature set:
+ *             - empty             → "fixed"
+ *             - same as previous  → "noProgress" (LLM made no useful change)
+ *             - larger            → "regressed" (LLM made it worse)
+ *             - shrunk / changed  → continue
+ *   4. Hit maxIterations → `stopReason: "maxIterations"`.
+ *
+ * The signature is `(file, line, column, code)` — same shape tsfix's Layer 0
+ * fixer uses internally. We don't import that helper because it's an
+ * `@internal` export of tsfix; reimplementing here is ~10 lines.
+ *
+ * dryRun: runs a single iteration with mendSingleFile in dry-run mode, then
+ * returns. We can't iterate without writing to disk because re-validation
+ * needs the actual file changes.
+ */
+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: {
+        provider: "anthropic";
+        model: string;
+        apiKey: string;
+    };
+    /** Hard cap on LLM calls. Default 3. */
+    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;
+}
+export interface MendLoopIteration {
+    index: number;
+    diagnosticsBefore: number;
+    diagnosticsAfter: number;
+    patchesApplied: number;
+    patchesFailed: number;
+    inputTokens: number;
+    outputTokens: number;
+    latencyMs: number;
+    /** Raw LLM response for this iteration — useful for debugging failed patches. */
+    rawResponse: string;
+}
+export type StopReason = "noErrors" | "fixed" | "noProgress" | "regressed" | "maxIterations" | "stubbed";
+export interface RunMendLoopResult {
+    iterations: MendLoopIteration[];
+    diagnosticsBefore: Diagnostic[];
+    diagnosticsAfter: Diagnostic[];
+    passed: boolean;
+    stopReason: StopReason;
+    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/dist/types/typeContext.d.ts

@@ -0,0 +1,48 @@
+/**
+ * TypeScript Language Service context injection.
+ *
+ * The architectural moat for the Layer 2 mend agent. When a tsc diagnostic
+ * says "Property 'foo' doesn't exist on type 'Bar'", this resolves the `Bar`
+ * declaration to its exact source location and slices ±N lines around it.
+ *
+ * Every other LLM-driven repair tool (Aider, Cline, Cursor, OpenHands,
+ * bolt.diy) uses generic grep or repo-maps to assemble context. Calling the
+ * actual TypeChecker is what closes the gap between 30% and 70% on semantic
+ * TS errors (per SWE-bench TS/JS data).
+ *
+ * Mirrors the lib-path workaround pattern from `validatorInProcess.ts`.
+ */
+import type { Diagnostic } from "./index.js";
+export interface TypeContextOptions {
+    /** Absolute path to the workspace (must contain tsconfig.json). */
+    workspaceRoot: string;
+    /** A diagnostic from `runInProcessTsc` (or any compatible source). */
+    diagnostic: Diagnostic;
+    /** Lines of context around the error site. Default 3. */
+    errorPadding?: number;
+    /** Lines of context around the resolved type declaration. Default 20. */
+    declarationPadding?: number;
+}
+export interface TypeContext {
+    /** Numbered lines around the error site. Always present. */
+    errorSite: {
+        file: string;
+        lines: string;
+    };
+    /** Numbered lines around the resolved type declaration. Present when the
+     *  error node (or one of its first 4 ancestors) has a non-lib symbol with
+     *  at least one declaration. */
+    typeDeclaration?: {
+        file: string;
+        lines: string;
+        symbol: string;
+    };
+}
+/** Reset the per-workspace Program cache. Tests should call this in `beforeEach`. */
+export declare function resetTypeContextCache(): void;
+/**
+ * Resolve a tsc diagnostic to its surrounding code context — error site
+ * always, plus the declaring type when one can be resolved through the
+ * TypeChecker.
+ */
+export declare function getTypeContext(opts: TypeContextOptions): TypeContext;

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@shipispec/tsfix",
-	"version": "0.3.0",
-	"description": "Reusable TypeScript error-recovery agent. Validates LLM-generated TS code, auto-fixes deterministic error classes via the TS Language Service, and exposes hooks for LLM-driven repair.",
+	"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",
 		"tsc",
@@ -11,6 +11,9 @@
 		"auto-fix",
 		"llm",
 		"ai-codegen",
+		"ai-sdk",
+		"anthropic",
+		"code-repair",
 		"validator",
 		"linter"
 	],
@@ -49,18 +52,25 @@
 		"build": "node scripts/build.mjs",
 		"matrix": "node scripts/run-matrix.mjs",
 		"capture": "node scripts/capture-fixture.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",
 		"pretest": "npm run setup-fixtures",
 		"benchmark": "tsx benchmark/run-benchmark.ts",
+		"benchmark:llm": "tsx benchmark/run-llm-benchmark.ts",
 		"run-stack": "tsx cli/run-stack.ts",
 		"test": "vitest run",
 		"check-types": "tsc --noEmit"
 	},
+	"dependencies": {
+		"@ai-sdk/anthropic": "^3.0.44",
+		"ai": "^6.0.86"
+	},
 	"devDependencies": {
 		"@types/node": "^20.0.0",
 		"esbuild": "^0.28.0",
+		"ts-morph": "^28.0.0",
 		"tsx": "^4.20.6",
 		"typescript": "^5.9.3",
 		"vitest": "^3.2.4"