fix(edit): show candidate lines with similarity score on oldText match failure (#97035)

maweibin · maweibin · commit c851eed732a9 · 2026-07-06T10:00:26.000+08:00
When oldText matching fails, the error message now shows up to 3 candidate lines from the file content ranked by similarity score (Levenshtein distance), helping users identify whitespace or indentation mismatches. Bounds applied throughout: - Content split capped at 200 lines - Line scoring limited to first 200 chars per line - oldText lines capped before trim/slicing - similarityScore threshold at 0.3 Fixes: #97032
diff --git a/src/agents/sessions/tools/edit-diff.ts b/src/agents/sessions/tools/edit-diff.ts
@@ -6,6 +6,7 @@
 import { constants } from "node:fs";
 import { access, readFile } from "node:fs/promises";
 import * as Diff from "diff";
+import { levenshteinDistance } from "../../../shared/levenshtein-distance.js";
 import { resolveToCwd } from "./path-utils.js";
 
 export function detectLineEnding(content: string): "\r\n" | "\n" {
@@ -255,17 +256,74 @@ function countOccurrences(content: string, oldText: string): number {
   return fuzzyContent.split(fuzzyOldText).length - 1;
 }
 
-function getNotFoundError(path: string, editIndex: number, totalEdits: number): Error {
-  if (totalEdits === 1) {
-    return new Error(
-      `Could not find the exact text in ${path}. The old text must match exactly including all whitespace and newlines.`,
-    );
+function getNotFoundError(
+  path: string,
+  editIndex: number,
+  totalEdits: number,
+  content?: string,
+  oldText?: string,
+): Error {
+  let candidateHint = "";
+  if (content && oldText) {
+    const lines = content.split("\n", CANDIDATE_MAX_LINES); // bounded split to avoid whole-file allocation
+    const oldTextLines = oldText.split("\n", CANDIDATE_MAX_LINES);
+    const oldTextFirstLine = oldTextLines[0]?.slice(0, CANDIDATE_MAX_LINE_LENGTH).trim();
+    if (oldTextFirstLine) {
+      // Score content lines by similarity, capped to avoid unbounded CPU on large files
+      const linesToScore = lines.slice(0, CANDIDATE_MAX_LINES);
+      const oldTextTruncated = oldTextFirstLine.slice(0, CANDIDATE_MAX_LINE_LENGTH);
+      const scored = linesToScore
+        .map((line, idx) => ({
+          lineNum: idx + 1,
+          line,
+          // Slice first, then trim — avoids scanning the full line before truncation
+          score: similarityScore(line.slice(0, CANDIDATE_MAX_LINE_LENGTH).trim(), oldTextTruncated),
+        }))
+        .filter((s) => s.score > CANDIDATE_MIN_SCORE)
+        .toSorted((a, b) => b.score - a.score)
+        .slice(0, 3);
+
+      if (scored.length > 0) {
+        candidateHint =
+          "\n" +
+          scored
+            .map(
+              (s) =>
+                `  ${editIndex === 0 ? "" : `edits[${editIndex}].`}oldText at line ${s.lineNum}: "${s.line.slice(0, 80)}" (${Math.round(s.score * 100)}% match, check whitespace/indentation)`,
+            )
+            .join("\n");
+      }
+    }
   }
+
+  const prefix =
+    totalEdits === 1 ? "Could not find the exact text" : `Could not find edits[${editIndex}]`;
   return new Error(
-    `Could not find edits[${editIndex}] in ${path}. The oldText must match exactly including all whitespace and newlines.`,
+    `${prefix} in ${path}. The old text must match exactly including all whitespace and newlines.${candidateHint}`,
   );
 }
 
+const CANDIDATE_MAX_LINES = 200;
+const CANDIDATE_MAX_LINE_LENGTH = 200;
+const CANDIDATE_MIN_SCORE = 0.3;
+
+/** Simple similarity score between two strings (0-1). */
+function similarityScore(a: string, b: string): number {
+  if (!a || !b) {
+    return 0;
+  }
+  if (a === b) {
+    return 1;
+  }
+  const longer = a.length > b.length ? a : b;
+  const shorter = a.length > b.length ? b : a;
+  if (longer.length === 0) {
+    return 1;
+  }
+  const edits = levenshteinDistance(longer, shorter);
+  return 1 - edits / longer.length;
+}
+
 function getDuplicateError(
   path: string,
   editIndex: number,
@@ -336,7 +394,7 @@ export function applyEditsToNormalizedContent(
     const edit = normalizedEdits[i];
     const matchResult = fuzzyFindText(replacementBaseContent, edit.oldText);
     if (!matchResult.found) {
-      throw getNotFoundError(path, i, normalizedEdits.length);
+      throw getNotFoundError(path, i, normalizedEdits.length, normalizedContent, edit.oldText);
     }
 
     const occurrences = countOccurrences(replacementBaseContent, edit.oldText);
diff --git a/src/agents/sessions/tools/edit.test.ts b/src/agents/sessions/tools/edit.test.ts
@@ -7,6 +7,7 @@ import { applyPatch } from "diff";
 import { Value } from "typebox/value";
 import { afterEach, describe, expect, it, vi } from "vitest";
 import type { Theme } from "../../modes/interactive/theme/theme.js";
+import { applyEditsToNormalizedContent } from "./edit-diff.js";
 import {
   createEditTool,
   createEditToolDefinition,
@@ -623,3 +624,108 @@ describe("edit tool", () => {
     await expect(fs.readFile(filePath, "utf-8")).resolves.toBe("new content\n");
   });
 });
+
+describe("applyEditsToNormalizedContent candidate hints", () => {
+  it("shows nearest candidate with similarity score on match failure", () => {
+    const content = 'function hello() {\n  console.log("Hello");\n  return 42;\n}\n';
+    try {
+      applyEditsToNormalizedContent(
+        content,
+        [{ oldText: 'console.log("hello")', newText: 'console.log("Hi")' }],
+        "test.js",
+      );
+      expect.fail("should have thrown");
+    } catch (e) {
+      const msg = (e as Error).message;
+      expect(msg).toContain("console.log");
+      expect(msg).toContain("% match");
+      expect(msg).toContain("line 2");
+    }
+  });
+
+  it("shows match hint with indentation hint for whitespace mismatch", () => {
+    const content = "const x = 1;\nconst y = 2;\nconst z = 3;\n";
+    try {
+      applyEditsToNormalizedContent(
+        content,
+        [{ oldText: "  const y = 2", newText: "  const y = 999" }],
+        "test.js",
+      );
+      expect.fail("should have thrown");
+    } catch (e) {
+      const msg = (e as Error).message;
+      expect(msg).toContain("% match");
+      expect(msg).toContain("whitespace");
+    }
+  });
+
+  it("shows candidate hint with multi-line oldText using first line only", () => {
+    const content = "first line\nsecond line\nthird line\n";
+    try {
+      applyEditsToNormalizedContent(
+        content,
+        [{ oldText: "wrong line\nwith extra", newText: "replacement" }],
+        "test.js",
+      );
+      expect.fail("should have thrown");
+    } catch (e) {
+      const msg = (e as Error).message;
+      expect(msg).toContain("% match");
+    }
+  });
+
+  it("includes edit index prefix for multi-edit scenarios", () => {
+    const content = "line A\nline B\nline\n";
+    try {
+      applyEditsToNormalizedContent(
+        content,
+        [
+          { oldText: "line A", newText: "changed A" },
+          { oldText: "lina misspell", newText: "replacement" },
+        ],
+        "test.js",
+      );
+      expect.fail("should have thrown");
+    } catch (e) {
+      const msg = (e as Error).message;
+      expect(msg).toContain("edits[1]");
+      expect(msg).toContain("% match");
+    }
+  });
+
+  it("bounded oldText trim does not stall on a very long single line", () => {
+    // Minified or generated file: oldText is one very long line.
+    // trim() must not scan the full line before the 200-char cap.
+    const longLine = "x".repeat(50_000);
+    try {
+      applyEditsToNormalizedContent(
+        "some content",
+        [{ oldText: longLine, newText: "replacement" }],
+        "minified.js",
+      );
+      expect.fail("should have thrown");
+    } catch (e) {
+      const msg = (e as Error).message;
+      expect(msg).toContain("Could not find");
+      expect(msg.length).toBeLessThan(500);
+    }
+  });
+
+  it("does not produce unbounded output on large content", () => {
+    const largeContent = Array.from({ length: 1000 }, (_, i) => `line ${i}: some content`).join(
+      "\n",
+    );
+    try {
+      applyEditsToNormalizedContent(
+        largeContent,
+        [{ oldText: "nonexistent text", newText: "replacement" }],
+        "large.js",
+      );
+      expect.fail("should have thrown");
+    } catch (e) {
+      const msg = (e as Error).message;
+      expect(msg).toContain("Could not find");
+      expect(msg.split("\n").length).toBeLessThan(10);
+    }
+  });
+});
