@shipispec/tsfix 0.2.0 → 0.4.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,12 +32,18 @@
  * - `runInProcessTsc` — just type-check, returns structured diagnostics
  * - `runLSPFixerPass` — just the auto-fix pass, edits files in place
  *
- * ## What it doesn't do (yet)
+ * ## Public types for the LLM-mend layer
  *
- * LLM-driven repair (the mend-agent layers from the spectoship pipeline) is
- * not exported here yet. They depend on internal types (ParsedTask) that need
- * to be redesigned as opaque interfaces before they can be moved into this
- * package. v0.2 target.
+ * - `Diagnostic` — single tsc error (re-exported from `runInProcessTsc`)
+ * - `MendContext` — input contract for the Layer 2–4 LLM-mend agent
+ * - `LayerEvent` — per-layer event shape for streaming telemetry
+ *
+ * ## 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
  */
 export { runInProcessTsc, isInProcessTscEnabled, resetInProcessTscCache } from "./validatorInProcess.js";
 export type { InProcessTscOptions, InProcessTscResult } from "./validatorInProcess.js";
@@ -101,3 +108,81 @@ export declare function discoverTsFiles(workspaceRoot: string): string[];
  * Throws on missing `tsconfig.json` or workspace path.
  */
 export declare function runValidationLoop(opts: ValidationLoopOptions): ValidationLoopResult;
+/**
+ * Single tsc diagnostic. Re-exported from `runInProcessTsc`'s result type
+ * so consumers building a `MendContext` don't have to dig the shape out of
+ * `InProcessTscResult["diagnostics"][number]`.
+ */
+export type Diagnostic = InProcessTscResult["diagnostics"][number];
+/**
+ * Input contract for a Layer 2–4 LLM-mend agent.
+ *
+ * Pattern:
+ *   1. Run `runValidationLoop` (Layer 0/1).
+ *   2. If `result.errorsAfter > 0`, build a `MendContext` from the
+ *      surviving diagnostics + whatever task/spec context your pipeline has.
+ *   3. Hand off to a mend agent (e.g. `@shipispec/tsmend`).
+ *
+ * Required fields: `workspaceRoot`, `diagnostics`, `erroredFiles`.
+ * Everything else is optional — leave fields out if your pipeline doesn't
+ * carry them.
+ */
+export interface MendContext {
+    /** Absolute path to the workspace (must contain `tsconfig.json`). */
+    workspaceRoot: string;
+    /** Diagnostics that survived Layer 0/1 and need higher-layer repair. */
+    diagnostics: Diagnostic[];
+    /** Absolute paths of files containing the surviving diagnostics. */
+    erroredFiles: string[];
+    /** Optional one-line summary of what the failing code was supposed to do. */
+    taskDescription?: string;
+    /** Optional Markdown spec the code is implementing. Helps the LLM understand intent. */
+    featureSpecText?: string;
+    /** Optional testable acceptance criteria from the spec. */
+    acceptanceCriteria?: string;
+    /** Other tasks in the same feature, with their files and current status. */
+    siblingTasks?: Array<{
+        description: string;
+        files: string[];
+        status: "pending" | "completed" | "failed";
+    }>;
+    /** Public API surface from earlier completed tasks (helps prevent re-defining symbols). */
+    priorTaskExports?: string;
+    /** Compact type signatures of installed npm dependencies (helps prevent API hallucination). */
+    installedTypes?: string;
+}
+/**
+ * Per-layer event for streaming telemetry across the validate → fix → mend
+ * chain. Designed for an `onLayerEvent` callback (added in a future minor
+ * release) rather than accumulating in a result array — a workspace with
+ * 200 errors emits ~1000 events.
+ *
+ * Layer assignments:
+ *   0 = prevention (prompt rules, exported-API injection — caller's problem)
+ *   1 = tsfix LSP fixer (this package)
+ *   2 = single-file LLM mend
+ *   3 = multi-file LLM mend (blast-radius search/replace)
+ *   4 = stub-and-continue (escape hatch)
+ */
+export interface LayerEvent {
+    /** Which layer ran. */
+    layer: 0 | 1 | 2 | 3 | 4;
+    /** TypeScript error code being acted on (e.g. 2304, 2339, 7006). */
+    errorCode: number;
+    /** True if the error was resolved by this layer. */
+    fixed: boolean;
+    /** Wall-clock time spent on this attempt. */
+    latencyMs: number;
+    /** USD cost (LLM tokens). Undefined for deterministic layers. */
+    costUsd?: number;
+    /** `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";

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,64 @@
+/**
+ * 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";
+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;
+    /** @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";
+export interface RunMendLoopResult {
+    iterations: MendLoopIteration[];
+    diagnosticsBefore: Diagnostic[];
+    diagnosticsAfter: Diagnostic[];
+    passed: boolean;
+    stopReason: StopReason;
+    totalInputTokens: number;
+    totalOutputTokens: number;
+    totalLatencyMs: number;
+}
+export declare function runMendLoop(opts: RunMendLoopOptions): Promise<RunMendLoopResult>;

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.2.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.4.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"
 	],
@@ -48,18 +51,27 @@
 	"scripts": {
 		"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",
 		"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"