editcodewithai 2.5.0 → 2.6.0

package/README.md

@@ -171,6 +171,45 @@ The library handles several file operations automatically:
 - **Creating new files**: When the AI includes a file name that doesn't exist in the original set.
 - **Deleting files**: When the AI returns empty/whitespace-only content for a file (works with `whole` format; for `diff`/`udiff`, deletions happen naturally when all content is replaced).
 
+### Best-effort application and warnings
+
+`performAiEdit` applies edits independently and **never throws because the model
+returned an edit that could not be matched**. If one edit references a missing
+file, an anchor that cannot be found, or an ambiguous location, that edit is
+skipped and reported — every other valid edit is still applied.
+
+Skipped edits are returned in `result.warnings`:
+
+```typescript
+const result = await performAiEdit({
+  prompt,
+  files,
+  llmFunction,
+  editFormat: "diff",
+});
+
+for (const warning of result.warnings ?? []) {
+  console.warn(warning.code, warning.fileName, warning.message);
+}
+```
+
+| Warning code       | Meaning                                                             |
+| ------------------ | ------------------------------------------------------------------- |
+| `FILE_NOT_FOUND`   | The edit targets a filename that isn't in the file set.             |
+| `SEARCH_NOT_FOUND` | The `SEARCH` text could not be located in the file.                 |
+| `HUNK_NOT_FOUND`   | A udiff hunk's original lines could not be located.                 |
+| `AMBIGUOUS_SEARCH` | The anchor matched more than one location, so the edit was skipped. |
+| `AMBIGUOUS_FILE`   | More than one file shares the target name, so the edit was skipped. |
+| `EMPTY_SEARCH`     | The search block was empty, so the edit could not be applied.       |
+| `NO_EDITS_PARSED`  | The model response contained no recognizable edits.                 |
+
+Matching is deterministic: only harmless formatting drift is absorbed (CRLF vs
+LF, a missing/extra trailing newline, trailing whitespace). Anything ambiguous or
+unmatched is skipped rather than guessed. Successful normalized matches produce
+no warnings.
+
+`warnings` is optional, so existing consumers continue to work unchanged.
+
 ## API Reference
 
 ### `performAiEdit(params)`
@@ -198,16 +237,17 @@ type LlmFunction = (prompt: string) => Promise<{
 
 #### Output: `PerformAiEditResult`
 
-| Property                 | Type       | Description                                                    |
-| ------------------------ | ---------- | -------------------------------------------------------------- |
-| `changedFiles`           | `VizFiles` | The updated file collection with all edits applied.            |
-| `openRouterGenerationId` | `string`   | The generation ID from the LLM function response.              |
-| `upstreamCostCents`      | `number`   | Cost in cents (only populated if `apiKey` was provided).       |
-| `provider`               | `string`   | The OpenRouter provider name used.                             |
-| `inputTokens`            | `number`   | Number of input (prompt) tokens billed.                        |
-| `outputTokens`           | `number`   | Number of output (completion) tokens billed.                   |
-| `promptTemplateVersion`  | `number`   | Version of the prompt template used (for tracking migrations). |
-| `rawResponse`            | `string`   | The raw string response from the LLM, unmodified.              |
+| Property                 | Type             | Description                                                       |
+| ------------------------ | ---------------- | ----------------------------------------------------------------- |
+| `changedFiles`           | `VizFiles`       | The updated file collection with all edits applied.               |
+| `openRouterGenerationId` | `string`         | The generation ID from the LLM function response.                 |
+| `upstreamCostCents`      | `number`         | Cost in cents (only populated if `apiKey` was provided).          |
+| `provider`               | `string`         | The OpenRouter provider name used.                                |
+| `inputTokens`            | `number`         | Number of input (prompt) tokens billed.                           |
+| `outputTokens`           | `number`         | Number of output (completion) tokens billed.                      |
+| `promptTemplateVersion`  | `number`         | Version of the prompt template used (for tracking migrations).    |
+| `rawResponse`            | `string`         | The raw string response from the LLM, unmodified.                 |
+| `warnings`               | `ApplyWarning[]` | Edits that were skipped because they could not be applied safely. |
 
 ### Exported Utilities
 
@@ -225,11 +265,14 @@ import {
 
   // --- Diff parsing (manual use) ---
   parseDiffs, // Parse search/replace blocks (diff format)
-  applyDiffs, // Apply parsed diffs to a file set
+  applyDiffs, // Apply parsed diffs to a file set (throws on unmatched edits)
+  applyDiffsSafe, // Best-effort apply: returns { files, warnings } instead of throwing
   parseDiffFenced, // Parse search/replace blocks (diff-fenced format)
   parseUdiffs, // Parse unified diff hunks
-  applyUdiffs, // Apply parsed unified diff hunks to a file set
+  applyUdiffs, // Apply parsed unified diff hunks (throws on unmatched edits)
+  applyUdiffsSafe, // Best-effort apply: returns { files, warnings } instead of throwing
   applyHybridEdits, // Apply mixed whole-file + diff edits from a single response
+  applyHybridEditsSafe, // Best-effort hybrid apply: returns { files, warnings }
 
   // --- Cost metadata ---
   getGenerationMetadata, // Fetch OpenRouter cost data for a generation ID

package/dist/applyEngine.d.ts

@@ -0,0 +1,13 @@
+import { VizFiles } from "@vizhub/viz-types";
+import type { ApplyResult, ParsedEdit } from "./types";
+/**
+ * Applies parsed edits on a best-effort basis.
+ *
+ * Each edit is applied independently: an edit that cannot be applied safely is
+ * skipped and reported in `warnings`, and never prevents other edits from being
+ * applied. The input `files` is never mutated.
+ *
+ * This function only throws for programmer error; anticipated model-output
+ * failures are reported as warnings.
+ */
+export declare function applyEditsSafe(files: VizFiles, edits: ParsedEdit[]): ApplyResult;

package/dist/applyEngine.js

@@ -0,0 +1,102 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.applyEditsSafe = applyEditsSafe;
+const matching_1 = require("./matching");
+/**
+ * Normalizes a filename for comparison: trims, converts Windows separators to
+ * "/", collapses duplicate separators, and strips leading "./" and "/".
+ *
+ * Case is intentionally preserved — case-insensitive matching is not part of
+ * the deterministic behavior and is deferred.
+ */
+function normalizeFileName(name) {
+    return name
+        .trim()
+        .replace(/\\/g, "/")
+        .replace(/\/+/g, "/")
+        .replace(/^\.\//, "")
+        .replace(/^\/+/, "");
+}
+function resolveFileId(files, rawName) {
+    const target = normalizeFileName(rawName);
+    const matches = Object.keys(files).filter((id) => normalizeFileName(files[id].name) === target);
+    if (matches.length === 1)
+        return { kind: "found", id: matches[0] };
+    if (matches.length > 1)
+        return { kind: "ambiguous" };
+    return { kind: "none" };
+}
+function anchorOf(edit) {
+    return edit.kind === "diff" ? edit.search : edit.original;
+}
+function replacementOf(edit) {
+    return edit.kind === "diff" ? edit.replace : edit.updated;
+}
+/**
+ * Applies parsed edits on a best-effort basis.
+ *
+ * Each edit is applied independently: an edit that cannot be applied safely is
+ * skipped and reported in `warnings`, and never prevents other edits from being
+ * applied. The input `files` is never mutated.
+ *
+ * This function only throws for programmer error; anticipated model-output
+ * failures are reported as warnings.
+ */
+function applyEditsSafe(files, edits) {
+    const work = JSON.parse(JSON.stringify(files));
+    const warnings = [];
+    for (const edit of edits) {
+        const resolution = resolveFileId(work, edit.fileName);
+        if (resolution.kind === "ambiguous") {
+            warnings.push({
+                code: "AMBIGUOUS_FILE",
+                fileName: edit.fileName,
+                message: `Skipped ${edit.fileName}: multiple files share that name.`,
+            });
+            continue;
+        }
+        if (resolution.kind === "none") {
+            warnings.push({
+                code: "FILE_NOT_FOUND",
+                fileName: edit.fileName,
+                message: `Skipped changes to ${edit.fileName}: file not found.`,
+            });
+            continue;
+        }
+        const anchor = anchorOf(edit);
+        if (anchor.trim() === "") {
+            warnings.push({
+                code: "EMPTY_SEARCH",
+                fileName: edit.fileName,
+                message: `Skipped a change to ${edit.fileName}: the search block was empty.`,
+            });
+            continue;
+        }
+        const file = work[resolution.id];
+        const match = (0, matching_1.findAnchor)(file.text, anchor);
+        if (match === null) {
+            warnings.push({
+                code: edit.kind === "udiff" ? "HUNK_NOT_FOUND" : "SEARCH_NOT_FOUND",
+                fileName: edit.fileName,
+                message: edit.kind === "udiff"
+                    ? `Skipped part of a change to ${edit.fileName}: referenced lines were not found.`
+                    : `Skipped a change to ${edit.fileName}: the referenced code was not found.`,
+            });
+            continue;
+        }
+        // Ambiguous anchors are never guessed: skip rather than replace the first.
+        if (match.matchCount > 1) {
+            warnings.push({
+                code: "AMBIGUOUS_SEARCH",
+                fileName: edit.fileName,
+                message: `Skipped a change to ${edit.fileName}: the referenced code matched ${match.matchCount} locations.`,
+            });
+            continue;
+        }
+        file.text =
+            file.text.slice(0, match.start) +
+                replacementOf(edit) +
+                file.text.slice(match.end);
+    }
+    return { files: work, warnings };
+}

package/dist/fileUtils.d.ts

@@ -1,4 +1,5 @@
 import { VizFiles, VizFile, FileCollection } from "@vizhub/viz-types";
+import type { ApplyResult } from "./types";
 /**
  * If the LLM outputs empty text for a file, we interpret this
  * as a request to delete the file.
@@ -43,4 +44,21 @@ export declare function parseUdiffs(responseText: string): UdiffHunk[];
  *    (If the same file appears in both forms, the whole-file content wins.)
  */
 export declare function applyHybridEdits(responseText: string, originalFiles: VizFiles, parseWholeFiles: (text: string) => FileCollection): VizFiles;
+/**
+ * Best-effort variant of `applyDiffs`. Never throws for unmatched files or
+ * anchors; skipped edits are reported in `warnings`.
+ */
+export declare function applyDiffsSafe(originalFiles: VizFiles, diffs: Diff[]): ApplyResult;
+/**
+ * Best-effort variant of `applyUdiffs`. Never throws for unmatched files or
+ * hunks; skipped edits are reported in `warnings`.
+ */
+export declare function applyUdiffsSafe(originalFiles: VizFiles, hunks: UdiffHunk[]): ApplyResult;
+/**
+ * Best-effort variant of `applyHybridEdits`. Applies search/replace diffs first,
+ * then whole-file replacements. Warnings for diffs that target a file which is
+ * also replaced wholesale are suppressed, since the whole-file content
+ * supersedes the failed diff.
+ */
+export declare function applyHybridEditsSafe(responseText: string, originalFiles: VizFiles, parseWholeFiles: (text: string) => FileCollection): ApplyResult;
 export declare function applyUdiffs(originalFiles: VizFiles, hunks: UdiffHunk[]): VizFiles;

package/dist/fileUtils.js

@@ -9,8 +9,12 @@ exports.applyDiffs = applyDiffs;
 exports.parseDiffFenced = parseDiffFenced;
 exports.parseUdiffs = parseUdiffs;
 exports.applyHybridEdits = applyHybridEdits;
+exports.applyDiffsSafe = applyDiffsSafe;
+exports.applyUdiffsSafe = applyUdiffsSafe;
+exports.applyHybridEditsSafe = applyHybridEditsSafe;
 exports.applyUdiffs = applyUdiffs;
 const viz_utils_1 = require("@vizhub/viz-utils");
+const applyEngine_1 = require("./applyEngine");
 /**
  * If the LLM outputs empty text for a file, we interpret this
  * as a request to delete the file.
@@ -184,6 +188,45 @@ function applyHybridEdits(responseText, originalFiles, parseWholeFiles) {
     changedFiles = mergeFileChanges(changedFiles, parsed);
     return changedFiles;
 }
+/**
+ * Best-effort variant of `applyDiffs`. Never throws for unmatched files or
+ * anchors; skipped edits are reported in `warnings`.
+ */
+function applyDiffsSafe(originalFiles, diffs) {
+    return (0, applyEngine_1.applyEditsSafe)(originalFiles, diffs.map((diff) => ({
+        kind: "diff",
+        fileName: diff.fileName,
+        search: diff.search,
+        replace: diff.replace,
+    })));
+}
+/**
+ * Best-effort variant of `applyUdiffs`. Never throws for unmatched files or
+ * hunks; skipped edits are reported in `warnings`.
+ */
+function applyUdiffsSafe(originalFiles, hunks) {
+    return (0, applyEngine_1.applyEditsSafe)(originalFiles, hunks.map((hunk) => ({
+        kind: "udiff",
+        fileName: hunk.fileName,
+        original: hunk.original,
+        updated: hunk.updated,
+    })));
+}
+/**
+ * Best-effort variant of `applyHybridEdits`. Applies search/replace diffs first,
+ * then whole-file replacements. Warnings for diffs that target a file which is
+ * also replaced wholesale are suppressed, since the whole-file content
+ * supersedes the failed diff.
+ */
+function applyHybridEditsSafe(responseText, originalFiles, parseWholeFiles) {
+    const diffResult = applyDiffsSafe(originalFiles, parseDiffs(responseText));
+    const parsedWholeFiles = parseWholeFiles(responseText);
+    const changedFiles = mergeFileChanges(diffResult.files, parsedWholeFiles);
+    const wholeFileNames = new Set(Object.keys(parsedWholeFiles).map((name) => name.trim()));
+    const warnings = diffResult.warnings.filter((warning) => warning.fileName === undefined ||
+        !wholeFileNames.has(warning.fileName.trim()));
+    return { files: changedFiles, warnings };
+}
 function applyUdiffs(originalFiles, hunks) {
     const changedFiles = JSON.parse(JSON.stringify(originalFiles));
     for (const hunk of hunks) {

package/dist/index.d.ts

@@ -1,9 +1,9 @@
 import type { PerformAiEditParams, PerformAiEditResult } from "./types";
 import { PROMPT_TEMPLATE_VERSION, assembleFullPrompt, FORMAT_INSTRUCTIONS } from "./prompt";
 import { getGenerationMetadata } from "./metadata";
-import { prepareFilesForPrompt, mergeFileChanges, parseDiffs, applyDiffs, parseDiffFenced, parseUdiffs, applyUdiffs, applyHybridEdits, isImageFile } from "./fileUtils";
-export type { LlmFunction, PerformAiEditParams, PerformAiEditResult, EditFormat, } from "./types";
-export { FORMAT_INSTRUCTIONS, mergeFileChanges, prepareFilesForPrompt, isImageFile, parseDiffs, applyDiffs, parseDiffFenced, parseUdiffs, applyUdiffs, applyHybridEdits, assembleFullPrompt, getGenerationMetadata, PROMPT_TEMPLATE_VERSION, };
+import { prepareFilesForPrompt, mergeFileChanges, parseDiffs, applyDiffs, applyDiffsSafe, parseDiffFenced, parseUdiffs, applyUdiffs, applyUdiffsSafe, applyHybridEdits, applyHybridEditsSafe, isImageFile } from "./fileUtils";
+export type { LlmFunction, PerformAiEditParams, PerformAiEditResult, EditFormat, ApplyWarning, ApplyWarningCode, ApplyResult, ParsedEdit, } from "./types";
+export { FORMAT_INSTRUCTIONS, mergeFileChanges, prepareFilesForPrompt, isImageFile, parseDiffs, applyDiffs, applyDiffsSafe, parseDiffFenced, parseUdiffs, applyUdiffs, applyUdiffsSafe, applyHybridEdits, applyHybridEditsSafe, assembleFullPrompt, getGenerationMetadata, PROMPT_TEMPLATE_VERSION, };
 /**
  * Core AI logic for:
  * - Building the prompt (including context)

package/dist/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.PROMPT_TEMPLATE_VERSION = exports.getGenerationMetadata = exports.assembleFullPrompt = exports.applyHybridEdits = exports.applyUdiffs = exports.parseUdiffs = exports.parseDiffFenced = exports.applyDiffs = exports.parseDiffs = exports.isImageFile = exports.prepareFilesForPrompt = exports.mergeFileChanges = exports.FORMAT_INSTRUCTIONS = void 0;
+exports.PROMPT_TEMPLATE_VERSION = exports.getGenerationMetadata = exports.assembleFullPrompt = exports.applyHybridEditsSafe = exports.applyHybridEdits = exports.applyUdiffsSafe = exports.applyUdiffs = exports.parseUdiffs = exports.parseDiffFenced = exports.applyDiffsSafe = exports.applyDiffs = exports.parseDiffs = exports.isImageFile = exports.prepareFilesForPrompt = exports.mergeFileChanges = exports.FORMAT_INSTRUCTIONS = void 0;
 exports.performAiEdit = performAiEdit;
 const llm_code_format_1 = require("llm-code-format");
 const prompt_1 = require("./prompt");
@@ -14,10 +14,13 @@ Object.defineProperty(exports, "prepareFilesForPrompt", { enumerable: true, get:
 Object.defineProperty(exports, "mergeFileChanges", { enumerable: true, get: function () { return fileUtils_1.mergeFileChanges; } });
 Object.defineProperty(exports, "parseDiffs", { enumerable: true, get: function () { return fileUtils_1.parseDiffs; } });
 Object.defineProperty(exports, "applyDiffs", { enumerable: true, get: function () { return fileUtils_1.applyDiffs; } });
+Object.defineProperty(exports, "applyDiffsSafe", { enumerable: true, get: function () { return fileUtils_1.applyDiffsSafe; } });
 Object.defineProperty(exports, "parseDiffFenced", { enumerable: true, get: function () { return fileUtils_1.parseDiffFenced; } });
 Object.defineProperty(exports, "parseUdiffs", { enumerable: true, get: function () { return fileUtils_1.parseUdiffs; } });
 Object.defineProperty(exports, "applyUdiffs", { enumerable: true, get: function () { return fileUtils_1.applyUdiffs; } });
+Object.defineProperty(exports, "applyUdiffsSafe", { enumerable: true, get: function () { return fileUtils_1.applyUdiffsSafe; } });
 Object.defineProperty(exports, "applyHybridEdits", { enumerable: true, get: function () { return fileUtils_1.applyHybridEdits; } });
+Object.defineProperty(exports, "applyHybridEditsSafe", { enumerable: true, get: function () { return fileUtils_1.applyHybridEditsSafe; } });
 Object.defineProperty(exports, "isImageFile", { enumerable: true, get: function () { return fileUtils_1.isImageFile; } });
 const debug = false;
 /**
@@ -44,35 +47,60 @@ async function performAiEdit({ prompt, files, llmFunction, apiKey, editFormat =
     // 4. We parse the output to figure out which files changed
     const resultString = result.content;
     let changedFiles;
+    const warnings = [];
+    let editsParsed = 0;
     switch (editFormat) {
         case "whole": {
             const parsed = (0, llm_code_format_1.parseMarkdownFiles)(resultString, "bold");
+            editsParsed = Object.keys(parsed.files).length;
             changedFiles = (0, fileUtils_1.mergeFileChanges)(files, parsed.files);
             break;
         }
         case "diff": {
             const diffs = (0, fileUtils_1.parseDiffs)(resultString);
-            changedFiles = (0, fileUtils_1.applyDiffs)(files, diffs);
+            editsParsed = diffs.length;
+            const applied = (0, fileUtils_1.applyDiffsSafe)(files, diffs);
+            changedFiles = applied.files;
+            warnings.push(...applied.warnings);
             break;
         }
         case "diff-fenced": {
             const diffs = (0, fileUtils_1.parseDiffFenced)(resultString);
-            changedFiles = (0, fileUtils_1.applyDiffs)(files, diffs);
+            editsParsed = diffs.length;
+            const applied = (0, fileUtils_1.applyDiffsSafe)(files, diffs);
+            changedFiles = applied.files;
+            warnings.push(...applied.warnings);
             break;
         }
         case "udiff": {
             const hunks = (0, fileUtils_1.parseUdiffs)(resultString);
-            changedFiles = (0, fileUtils_1.applyUdiffs)(files, hunks);
+            editsParsed = hunks.length;
+            const applied = (0, fileUtils_1.applyUdiffsSafe)(files, hunks);
+            changedFiles = applied.files;
+            warnings.push(...applied.warnings);
             break;
         }
         case "hybrid": {
-            changedFiles = (0, fileUtils_1.applyHybridEdits)(resultString, files, (text) => (0, llm_code_format_1.parseMarkdownFiles)(text, "bold").files);
+            const diffs = (0, fileUtils_1.parseDiffs)(resultString);
+            const wholeFiles = (0, llm_code_format_1.parseMarkdownFiles)(resultString, "bold").files;
+            editsParsed = diffs.length + Object.keys(wholeFiles).length;
+            const applied = (0, fileUtils_1.applyHybridEditsSafe)(resultString, files, (text) => (0, llm_code_format_1.parseMarkdownFiles)(text, "bold").files);
+            changedFiles = applied.files;
+            warnings.push(...applied.warnings);
             break;
         }
         default:
             // This will catch any unhandled or unknown edit formats.
             throw new Error(`Unknown edit format: ${editFormat}`);
     }
+    // Zero parsed edits is worth surfacing, but only when nothing else was
+    // reported — otherwise it just adds noise on top of real failures.
+    if (editsParsed === 0 && warnings.length === 0) {
+        warnings.push({
+            code: "NO_EDITS_PARSED",
+            message: "The model returned no applicable edits.",
+        });
+    }
     // 6. Retrieve cost metadata for charging the user
     const openRouterGenerationId = result.generationId || "";
     let upstreamCostCents = 0;
@@ -98,5 +126,6 @@ async function performAiEdit({ prompt, files, llmFunction, apiKey, editFormat =
         outputTokens,
         promptTemplateVersion: prompt_1.PROMPT_TEMPLATE_VERSION,
         rawResponse: resultString, // Include the raw response
+        warnings,
     };
 }

package/dist/matching.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Deterministic anchor matching for edit application.
+ *
+ * This module intentionally implements only deterministic strategies. It never
+ * guesses a location via similarity scoring; if a deterministic match cannot be
+ * found, callers skip the edit and report a warning.
+ *
+ * Strategies, in order:
+ *   1. `exact`           — the anchor is a literal substring.
+ *   2. `line-normalized` — both sides split into lines and compared with
+ *                          trailing whitespace removed. This absorbs CRLF vs LF
+ *                          drift, a missing/extra trailing newline, and
+ *                          trailing-whitespace drift.
+ *
+ * Leading indentation drift is deliberately NOT handled (deferred).
+ */
+export type MatchStrategy = "exact" | "line-normalized";
+export interface AnchorMatch {
+    start: number;
+    end: number;
+    strategy: MatchStrategy;
+    /** Number of equally-valid locations found. `> 1` means ambiguous. */
+    matchCount: number;
+}
+/**
+ * Finds `anchor` within `source` using deterministic strategies only.
+ *
+ * Returns `null` when no deterministic match exists. When a match exists,
+ * `matchCount` reports how many equivalent locations were found so callers can
+ * skip ambiguous edits.
+ */
+export declare function findAnchor(source: string, anchor: string): AnchorMatch | null;

package/dist/matching.js

@@ -0,0 +1,126 @@
+"use strict";
+/**
+ * Deterministic anchor matching for edit application.
+ *
+ * This module intentionally implements only deterministic strategies. It never
+ * guesses a location via similarity scoring; if a deterministic match cannot be
+ * found, callers skip the edit and report a warning.
+ *
+ * Strategies, in order:
+ *   1. `exact`           — the anchor is a literal substring.
+ *   2. `line-normalized` — both sides split into lines and compared with
+ *                          trailing whitespace removed. This absorbs CRLF vs LF
+ *                          drift, a missing/extra trailing newline, and
+ *                          trailing-whitespace drift.
+ *
+ * Leading indentation drift is deliberately NOT handled (deferred).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.findAnchor = findAnchor;
+/**
+ * Splits text into lines while retaining each line's character offsets.
+ * A trailing newline produces a final empty line, matching `String.split("\n")`.
+ */
+function splitLinesWithOffsets(text) {
+    const lines = [];
+    if (text.length === 0)
+        return lines;
+    let start = 0;
+    // Loop is bounded: `start` always advances past the newline.
+    for (;;) {
+        const newlineIndex = text.indexOf("\n", start);
+        if (newlineIndex === -1) {
+            lines.push({ text: text.slice(start), start, end: text.length });
+            break;
+        }
+        lines.push({
+            text: text.slice(start, newlineIndex),
+            start,
+            end: newlineIndex,
+        });
+        start = newlineIndex + 1;
+        if (start === text.length) {
+            lines.push({ text: "", start, end: start });
+            break;
+        }
+    }
+    return lines;
+}
+function countOccurrences(haystack, needle) {
+    if (needle.length === 0)
+        return 0;
+    let count = 0;
+    let index = haystack.indexOf(needle);
+    while (index !== -1) {
+        count++;
+        index = haystack.indexOf(needle, index + needle.length);
+    }
+    return count;
+}
+function findLineNormalized(source, anchor) {
+    const sourceLines = splitLinesWithOffsets(source);
+    const anchorLines = splitLinesWithOffsets(anchor);
+    // Trailing/leading blank lines carry no anchoring information.
+    while (anchorLines.length > 0 &&
+        anchorLines[anchorLines.length - 1].text.trim() === "") {
+        anchorLines.pop();
+    }
+    while (anchorLines.length > 0 && anchorLines[0].text.trim() === "") {
+        anchorLines.shift();
+    }
+    if (anchorLines.length === 0)
+        return null;
+    if (anchorLines.length > sourceLines.length)
+        return null;
+    const normalizedAnchor = anchorLines.map((line) => line.text.trimEnd());
+    const normalizedSource = sourceLines.map((line) => line.text.trimEnd());
+    let matchCount = 0;
+    let first = null;
+    for (let i = 0; i + normalizedAnchor.length <= sourceLines.length; i++) {
+        let isMatch = true;
+        for (let j = 0; j < normalizedAnchor.length; j++) {
+            if (normalizedSource[i + j] !== normalizedAnchor[j]) {
+                isMatch = false;
+                break;
+            }
+        }
+        if (isMatch) {
+            matchCount++;
+            if (first === null) {
+                first = {
+                    start: sourceLines[i].start,
+                    end: sourceLines[i + normalizedAnchor.length - 1].end,
+                };
+            }
+        }
+    }
+    if (first === null)
+        return null;
+    return {
+        start: first.start,
+        end: first.end,
+        strategy: "line-normalized",
+        matchCount,
+    };
+}
+/**
+ * Finds `anchor` within `source` using deterministic strategies only.
+ *
+ * Returns `null` when no deterministic match exists. When a match exists,
+ * `matchCount` reports how many equivalent locations were found so callers can
+ * skip ambiguous edits.
+ */
+function findAnchor(source, anchor) {
+    if (anchor.length === 0 || source.length === 0)
+        return null;
+    const exactIndex = source.indexOf(anchor);
+    if (exactIndex !== -1) {
+        return {
+            start: exactIndex,
+            end: exactIndex + anchor.length,
+            strategy: "exact",
+            matchCount: countOccurrences(source, anchor),
+        };
+    }
+    return findLineNormalized(source, anchor);
+}

package/dist/prompt.d.ts

@@ -1,5 +1,5 @@
 import type { EditFormat } from "./types";
-export declare const PROMPT_TEMPLATE_VERSION = 1;
+export declare const PROMPT_TEMPLATE_VERSION = 2;
 export declare const FORMAT_INSTRUCTIONS: Record<EditFormat, string>;
 /**
  * Assembles the full prompt by combining task, files context, and formatting instructions

package/dist/prompt.js

@@ -3,7 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.FORMAT_INSTRUCTIONS = exports.PROMPT_TEMPLATE_VERSION = void 0;
 exports.assembleFullPrompt = assembleFullPrompt;
 // Versions of the prompt template.
-exports.PROMPT_TEMPLATE_VERSION = 1;
+exports.PROMPT_TEMPLATE_VERSION = 2;
 // Template pieces
 const TASK = (prompt) => `## Your Task\n\n${prompt}`;
 const FILES = (filesContext) => `## Original Files\n\n${filesContext}`;
@@ -32,6 +32,7 @@ exports.FORMAT_INSTRUCTIONS = {
         "// new code\n",
         ">>>>>>> REPLACE\n",
         "```\n",
+        "Use the exact filename listed in the Original Files section. Copy the SEARCH text verbatim, including whitespace and indentation. Do not invent filenames.",
     ].join(""),
     "diff-fenced": [
         "## Formatting Instructions\n\n",
@@ -44,6 +45,7 @@ exports.FORMAT_INSTRUCTIONS = {
         "// new code\n",
         ">>>>>>> REPLACE\n",
         "```\n",
+        "Use the exact filename listed in the Original Files section. Copy the SEARCH text verbatim, including whitespace and indentation. Do not invent filenames.",
     ].join(""),
     udiff: [
         "## Formatting Instructions\n\n",
@@ -55,6 +57,7 @@ exports.FORMAT_INSTRUCTIONS = {
         "-// line to be removed\n",
         "+// line to be added\n",
         "```\n",
+        "Use the exact filename listed in the Original Files section. Copy all context lines verbatim, including whitespace. Do not invent filenames; use the whole-file format when creating a new file.",
     ].join(""),
     hybrid: [
         "## Formatting Instructions\n\n",

package/dist/types.d.ts

@@ -1,5 +1,42 @@
 import { VizFiles } from "@vizhub/viz-types";
 export type EditFormat = "whole" | "diff" | "diff-fenced" | "udiff" | "hybrid";
+/**
+ * A parsed edit that can be applied independently to a file.
+ * `diff`/`diff-fenced` edits are search/replace pairs; `udiff` edits are
+ * original/updated blocks.
+ */
+export interface DiffEdit {
+    kind: "diff";
+    fileName: string;
+    search: string;
+    replace: string;
+}
+export interface UdiffEdit {
+    kind: "udiff";
+    fileName: string;
+    original: string;
+    updated: string;
+}
+export type ParsedEdit = DiffEdit | UdiffEdit;
+/**
+ * Reason an edit was skipped. Warnings strictly mean "something went wrong"
+ * or "this edit could not be applied" — successful normalized matches are not
+ * reported here.
+ */
+export type ApplyWarningCode = "FILE_NOT_FOUND" | "SEARCH_NOT_FOUND" | "HUNK_NOT_FOUND" | "AMBIGUOUS_SEARCH" | "AMBIGUOUS_FILE" | "EMPTY_SEARCH" | "NO_EDITS_PARSED";
+export interface ApplyWarning {
+    code: ApplyWarningCode;
+    fileName?: string;
+    message: string;
+}
+/**
+ * Result of best-effort edit application. `files` always contains the changes
+ * that could be applied safely; `warnings` describes everything skipped.
+ */
+export interface ApplyResult {
+    files: VizFiles;
+    warnings: ApplyWarning[];
+}
 export type LlmFunction = (prompt: string) => Promise<{
     content: string;
     generationId?: string;
@@ -20,4 +57,6 @@ export interface PerformAiEditResult {
     outputTokens?: number;
     promptTemplateVersion?: number;
     rawResponse?: string;
+    /** Edits that were skipped because they could not be applied safely. */
+    warnings?: ApplyWarning[];
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "editcodewithai",
-  "version": "2.5.0",
+  "version": "2.6.0",
   "description": "Edit Code With AI",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",