@shipispec/tsfix 0.1.0 → 0.3.0

package/dist/index.d.ts

@@ -0,0 +1,176 @@
+/**
+ * @shipispec/tsfix — public API.
+ *
+ * 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).
+ *
+ * ## Quick start (library)
+ *
+ * ```ts
+ * import { runValidationLoop } from "@shipispec/tsfix";
+ *
+ * const result = await runValidationLoop({
+ *   workspaceRoot: "/path/to/your/project",
+ *   targetFiles: ["src/index.ts", "src/utils.ts"],
+ * });
+ *
+ * console.log(result.passed, result.errorsAfter, result.lspFixer.fixesApplied);
+ * ```
+ *
+ * ## Quick start (CLI)
+ *
+ * ```
+ * npx @shipispec/tsfix --workspace ./my-project
+ * ```
+ *
+ * ## Layered API
+ *
+ * - `runValidationLoop` — full deterministic loop (recommended entry point)
+ * - `runInProcessTsc` — just type-check, returns structured diagnostics
+ * - `runLSPFixerPass` — just the auto-fix pass, edits files in place
+ *
+ * ## Public types for downstream LLM-mend integrations
+ *
+ * - `Diagnostic` — single tsc error (re-exported from `runInProcessTsc`)
+ * - `MendContext` — input contract for a 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.
+ */
+export { runInProcessTsc, isInProcessTscEnabled, resetInProcessTscCache } from "./validatorInProcess.js";
+export type { InProcessTscOptions, InProcessTscResult } from "./validatorInProcess.js";
+export { runLSPFixerPass, isLSPFixerEnabled, resetLSPFixerCache } from "./tsLanguageServiceFixer.js";
+export type { LSPFixerOptions, LSPFixerResult, LSPFixerLogger } from "./tsLanguageServiceFixer.js";
+import { type InProcessTscResult } from "./validatorInProcess.js";
+/** Logger shape required by the validation/fix loop. Plain object with three methods. */
+export interface Logger {
+    info(msg: string): void;
+    warn(msg: string): void;
+    error(msg: string): void;
+}
+export interface ValidationLoopOptions {
+    /** Absolute path to the workspace (must contain `tsconfig.json`). */
+    workspaceRoot: string;
+    /**
+     * Files to scope the type-check + fix to. If omitted, all .ts/.tsx files
+     * under `workspaceRoot` (excluding node_modules, .next, dist, build, .git)
+     * are discovered.
+     */
+    targetFiles?: string[];
+    /** Skip Layer 0 LSP auto-fixer. Default false. */
+    skipLSPFixer?: boolean;
+    /**
+     * Run the LSP fixer in memory but do NOT persist edits to disk. The
+     * returned `lspFixer.filesEdited` lists files that *would* have been
+     * written. Useful for previewing changes before letting tsfix mutate a
+     * workspace. Default false.
+     */
+    dryRun?: boolean;
+    /** Default: a no-op logger. Pass your own to capture layer events. */
+    logger?: Logger;
+}
+export interface ValidationLoopResult {
+    passed: boolean;
+    errorsBefore: number;
+    errorsAfter: number;
+    lspFixer: {
+        ran: boolean;
+        fixesApplied: number;
+        filesEdited: string[];
+        iterations: number;
+    };
+    remainingByCode: Record<string, number>;
+    remainingByFile: Record<string, number>;
+    diagnostics: InProcessTscResult["diagnostics"];
+    elapsedMs: number;
+}
+/**
+ * Discover all `.ts` / `.tsx` files under a workspace, excluding common
+ * non-source dirs. Skips `.d.ts` declaration files.
+ */
+export declare function discoverTsFiles(workspaceRoot: string): string[];
+/**
+ * Run the full deterministic validation + fix loop:
+ *
+ *   1. In-process tsc → capture baseline diagnostics
+ *   2. If errors AND not `skipLSPFixer`, run Layer 0 LSP auto-fix
+ *   3. If fixes were applied, re-run in-process tsc to capture post-fix state
+ *   4. Return aggregated result
+ *
+ * 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;
+}