decorated-pi 0.3.0 → 0.4.1

package/extensions/patch.ts

@@ -11,7 +11,7 @@
 
 import * as fs from "node:fs";
 import * as path from "node:path";
-import * as os from "node:os";
+import * as fsPromises from "node:fs/promises";
 
 // ═══════════════════════════════════════════════════════════════════════════
 // Types
@@ -45,6 +45,8 @@ export interface PatchResult {
   replacements: Map<string, ReplacementInfo[]>;
   /** Original file lines per file, for diff context generation */
   originalLines: Map<string, string[]>;
+  /** Pre-generated diff string (set by applyEdits to avoid re-reading files) */
+  diff: string;
 }
 
 /** Records a single old_str→new_str replacement within a file */
@@ -63,6 +65,8 @@ export interface ReplacementInfo {
   newLines: string[];
   /** Optional anchor text (first line only, for hunk display) */
   anchor?: string;
+  /** Anchor was provided but not found, and patch fell back to global old_str search */
+  anchorMissing?: boolean;
 }
 
 // ═══════════════════════════════════════════════════════════════════════════
@@ -90,6 +94,7 @@ export async function applyPatch(patch: FilePatch, cwd: string): Promise<PatchRe
     warnings: [],
     replacements: new Map(),
     originalLines: new Map(),
+    diff: "",
   };
 
   const absPath = resolveAbsPath(cwd, patch.path);
@@ -119,6 +124,7 @@ export async function applyPatches(patches: FilePatch[], cwd: string): Promise<P
     warnings: [],
     replacements: new Map(),
     originalLines: new Map(),
+    diff: "",
   };
 
   for (const p of patches) {
@@ -185,82 +191,106 @@ async function applyEdits(
   }
 
   const rawContent = fs.readFileSync(absPath, "utf8");
-  // Store original lines for diff context generation later
-  const origLines = rawContent.split("\n");
-  // Remove trailing empty line from split (trailing newline), but keep lines for content-less files
-  if (origLines.length > 1 && origLines[origLines.length - 1] === "") origLines.pop();
-  result.originalLines.set(displayPath, origLines);
-
   const lineEnding = detectLineEnding(rawContent);
   let content = normalizeLineEndings(rawContent);
 
   // Precompute line offsets for O(log n) line number lookups
-  const rawLineOffsets = buildLineOffsets(rawContent);
+  const lineOffsets = buildLineOffsets(rawContent);
+  const totalLines = lineOffsets.length - 1;
 
   // Track cumulative offset for mapping current positions back to original
   let cumulativeOffset = 0;
   const replacements: ReplacementInfo[] = [];
+  const neededRanges: LineRange[] = [];
 
   for (const edit of edits) {
     if (!edit.old_str) {
       throw new ApplyError(`old_str must not be empty in ${displayPath}.`);
     }
 
-    const oldNorm = normalizeLineEndings(edit.old_str);
-    const newNorm = normalizeLineEndings(edit.new_str);
+    let oldNorm = normalizeLineEndings(edit.old_str);
+    let newNorm = normalizeLineEndings(edit.new_str);
 
     // Determine search range
     let searchFrom = 0;
+    let displayAnchor: string | undefined;
+    let anchorMissing = false;
+    let anchorNotFoundMessage: string | undefined;
 
     if (edit.anchor) {
       const anchorNorm = normalizeLineEndings(edit.anchor);
 
-      // Find anchor — must be unique
+      // Find anchor — must be unique when present
       const anchorIdx = content.indexOf(anchorNorm);
       if (anchorIdx === -1) {
-        throw new ApplyError(
-          `Anchor not found in ${displayPath}: "${truncate(edit.anchor)}".`
-        );
-      }
-      // Check uniqueness
-      const secondAnchor = content.indexOf(anchorNorm, anchorIdx + 1);
-      if (secondAnchor !== -1) {
-        throw new ApplyError(
-          `Anchor is not unique in ${displayPath}: "${truncate(edit.anchor)}" ` +
-          `found at multiple locations. Choose a more specific anchor.`
-        );
+        anchorNotFoundMessage = `Anchor not found in ${displayPath}: "${truncate(edit.anchor)}".`;
+      } else {
+        const secondAnchor = content.indexOf(anchorNorm, anchorIdx + 1);
+        if (secondAnchor !== -1) {
+          anchorNotFoundMessage = `Anchor is not unique in ${displayPath}: "${truncate(edit.anchor)}".`;
+        } else {
+          searchFrom = Math.max(0, anchorIdx - (oldNorm.length - 1));
+          displayAnchor = edit.anchor;
+          anchorMissing = false;
+        }
       }
-
-      // Search from anchor start position onward (anchor narrows search range)
-      // old_str may start at anchor position (anchor is a prefix of old_str)
-      searchFrom = anchorIdx;
     }
 
     // Find old_str in range — must be unique
-    const matchIdx = content.indexOf(oldNorm, searchFrom);
+    let matchIdx = anchorNotFoundMessage ? -1 : content.indexOf(oldNorm, searchFrom);
+    if (matchIdx === -1 && anchorNotFoundMessage) {
+      // Anchor was missing/unusable — try global exact match first
+      displayAnchor = edit.anchor;
+      anchorMissing = true;
+      matchIdx = content.indexOf(oldNorm, 0);
+      if (matchIdx !== -1) {
+        const secondGlobalMatch = content.indexOf(oldNorm, matchIdx + 1);
+        if (secondGlobalMatch !== -1) {
+          const dupDiag = diagnoseOldStrNotUnique(oldNorm, content);
+          throw new ApplyError(`${anchorNotFoundMessage}\n${dupDiag}`);
+        }
+      }
+    }
+
     if (matchIdx === -1) {
-      throw new ApplyError(
-        `old_str not found in ${displayPath}` +
-        (edit.anchor ? ` after anchor "${truncate(edit.anchor)}"` : "") +
-        `: "${truncate(edit.old_str)}". ` +
-        `The file may have changed — re-read it and try again.`
-      );
+      // Fuzzy match fallback: normalize tab↔space + trailing whitespace
+      const searchLine = searchFrom === 0 ? 0 : content.substring(0, searchFrom).split("\n").length - 1;
+      const fuzzy = tryFuzzyLineMatch(oldNorm, content, searchLine);
+      if (fuzzy) {
+        oldNorm = fuzzy.matched;
+        matchIdx = fuzzy.idx;
+        newNorm = normalizeIndentForFuzzy(fuzzy.matched.split("\n")[0] ?? "", newNorm);
+      } else if (anchorNotFoundMessage) {
+        const diag = diagnoseOldStrMismatch(oldNorm, content);
+        throw new ApplyError(
+          `${anchorNotFoundMessage}\nold_str not found in ${displayPath}: "${truncate(edit.old_str)}".\n${diag}`
+        );
+      } else {
+        const diag = diagnoseOldStrMismatch(oldNorm, content);
+        throw new ApplyError(
+          `old_str not found in ${displayPath}` +
+          (edit.anchor ? ` after anchor "${truncate(edit.anchor)}"` : "") +
+          `: "${truncate(edit.old_str)}".\n${diag}`
+        );
+      }
     }
 
-    // Check uniqueness
-    const secondMatch = content.indexOf(oldNorm, matchIdx + 1);
-    if (secondMatch !== -1) {
-      throw new ApplyError(
-        `old_str is not unique in ${displayPath}: "${truncate(edit.old_str)}". ` +
-        `Add more context to old_str or use an anchor to narrow the search.`
-      );
+    // Check uniqueness in anchor-narrowed / plain search path only when anchor was used normally
+    if (!anchorNotFoundMessage) {
+      const secondMatch = content.indexOf(oldNorm, matchIdx + 1);
+      if (secondMatch !== -1) {
+        const dupDiag = diagnoseOldStrNotUnique(oldNorm, content);
+        throw new ApplyError(
+          `${dupDiag}`
+        );
+      }
     }
 
     // Compute line numbers in the original file for diff generation (O(log n) via binary search)
     // matchIdx is in the modified content; subtract cumulative offset to map back to original
     const origMatchIdx = matchIdx - cumulativeOffset;
-    const oldStartLine = lineAtOffset(rawLineOffsets, origMatchIdx);
-    const oldEndLine = lineAtOffset(rawLineOffsets, origMatchIdx + oldNorm.length - 1);
+    const oldStartLine = lineAtOffset(lineOffsets, origMatchIdx);
+    const oldEndLine = lineAtOffset(lineOffsets, origMatchIdx + oldNorm.length - 1);
 
     // Apply replacement
     content =
@@ -283,10 +313,36 @@ async function applyEdits(
       newEndLine,
       oldLines: oldNorm.split("\n").filter((l, i, arr) => !(i === arr.length - 1 && l === "")),
       newLines: newNorm.split("\n").filter((l, i, arr) => !(i === arr.length - 1 && l === "")),
-      anchor: edit.anchor ? edit.anchor.split("\n")[0] : undefined,
+      anchor: displayAnchor ? displayAnchor.split("\n")[0] : undefined,
+      anchorMissing,
+    });
+
+    // Collect context range for this edit
+    neededRanges.push({
+      startLine: Math.max(1, oldStartLine - CONTEXT_LINES),
+      endLine: Math.min(totalLines, oldEndLine + CONTEXT_LINES),
     });
   }
 
+  // Generate diff using only needed context lines (no full-file split)
+  const mergedRanges = mergeRanges(neededRanges);
+  const currentLineOffsets = buildLineOffsets(content);
+  const neededLines: Map<number, string> = new Map();
+  for (const range of mergedRanges) {
+    const lines = extractLineRange(content, currentLineOffsets, range.startLine, range.endLine);
+    for (let i = 0; i < lines.length; i++) {
+      neededLines.set(range.startLine + i, lines[i]);
+    }
+  }
+
+  // Build diff for this file and append to result
+  const fileDiff = generateLocalDiff(displayPath, replacements, neededLines, totalLines);
+  if (result.diff) {
+    result.diff += "\n" + fileDiff;
+  } else {
+    result.diff = fileDiff;
+  }
+
   // Restore line endings
   const finalContent = restoreLineEndings(content, lineEnding);
 
@@ -334,47 +390,99 @@ export async function computePatchPreview(
         return { error: "File not found" };
       }
 
-      const rawContent = fs.readFileSync(absPath, "utf8");
-      const origLines = rawContent.split("\n");
-      if (origLines.length > 1 && origLines[origLines.length - 1] === "") origLines.pop();
-      let content = normalizeLineEndings(rawContent);
-      const rawLineOffsets = buildLineOffsets(rawContent);
-      const allReplacements: ReplacementInfo[] = [];
-      let cumulativeOffset = 0;
+      const rawContent = await fsPromises.readFile(absPath, "utf8");
+    const lineOffsets = buildLineOffsets(rawContent);
+    const totalLines = lineOffsets.length - 1;
+    let content = normalizeLineEndings(rawContent);
+    const allReplacements: ReplacementInfo[] = [];
+    const neededRanges: LineRange[] = [];
+    let cumulativeOffset = 0;
 
       for (const edit of patch.edits) {
         if (!edit.old_str) continue;
-        const oldNorm = normalizeLineEndings(edit.old_str);
-        const newNorm = normalizeLineEndings(edit.new_str);
+        let oldNorm = normalizeLineEndings(edit.old_str);
+        let newNorm = normalizeLineEndings(edit.new_str);
 
         let searchFrom = 0;
+        let displayAnchor: string | undefined;
+        let anchorMissing = false;
+        let anchorNotFoundMessage: string | undefined;
         if (edit.anchor) {
           const anchorNorm = normalizeLineEndings(edit.anchor);
           const idx = content.indexOf(anchorNorm);
           if (idx === -1) {
-            return { error: `Anchor not found: "${truncate(edit.anchor)}"` };
+            anchorNotFoundMessage = `Anchor not found: "${truncate(edit.anchor)}"`;
+          } else {
+            const secondAnchor = content.indexOf(anchorNorm, idx + 1);
+            if (secondAnchor !== -1) {
+              anchorNotFoundMessage = `Anchor is not unique: "${truncate(edit.anchor)}"`;
+            } else {
+              searchFrom = Math.max(0, idx - (oldNorm.length - 1));
+              displayAnchor = edit.anchor;
+              anchorMissing = false;
+            }
+          }
+        }
+
+        let matchIdx = anchorNotFoundMessage ? -1 : content.indexOf(oldNorm, searchFrom);
+        if (matchIdx === -1 && anchorNotFoundMessage) {
+          displayAnchor = edit.anchor;
+          anchorMissing = true;
+          matchIdx = content.indexOf(oldNorm, 0);
+          if (matchIdx !== -1) {
+            const secondGlobalMatch = content.indexOf(oldNorm, matchIdx + 1);
+            if (secondGlobalMatch !== -1) {
+              const dupDiag = diagnoseOldStrNotUnique(oldNorm, content);
+              return { error: `${anchorNotFoundMessage}\n${dupDiag}` };
+            }
           }
-          searchFrom = idx;
         }
 
-        const matchIdx = content.indexOf(oldNorm, searchFrom);
         if (matchIdx === -1) {
-          return { error: `old_str not found: "${truncate(edit.old_str)}"` };
+          const searchLine = 0;
+          const fuzzy = tryFuzzyLineMatch(oldNorm, content, searchLine);
+          if (fuzzy) {
+            oldNorm = fuzzy.matched;
+            matchIdx = fuzzy.idx;
+            newNorm = normalizeIndentForFuzzy(fuzzy.matched.split("\n")[0] ?? "", newNorm);
+          } else if (anchorNotFoundMessage) {
+            const diag = diagnoseOldStrMismatch(oldNorm, content);
+            return { error: `${anchorNotFoundMessage}\nold_str not found: "${truncate(edit.old_str)}"\n${diag}` };
+          } else {
+            const diag = diagnoseOldStrMismatch(oldNorm, content);
+            return { error: `old_str not found: "${truncate(edit.old_str)}".\n${diag}` };
+          }
         }
 
         const origMatchIdx = matchIdx - cumulativeOffset;
-        const oldStartLine = lineAtOffset(rawLineOffsets, origMatchIdx);
-        const oldEndLine = lineAtOffset(rawLineOffsets, origMatchIdx + oldNorm.length - 1);
+        const oldStartLine = lineAtOffset(lineOffsets, origMatchIdx);
+        const oldEndLine = lineAtOffset(lineOffsets, origMatchIdx + oldNorm.length - 1);
         const oldLines = oldNorm.split("\n").filter((l, i, arr) => !(i === arr.length - 1 && l === ""));
         const newLines = newNorm.split("\n").filter((l, i, arr) => !(i === arr.length - 1 && l === ""));
         content = content.substring(0, matchIdx) + newNorm + content.substring(matchIdx + oldNorm.length);
         const newStartLine = charOffsetToLine(content, matchIdx);
         const newEndLine = charOffsetToLine(content, matchIdx + newNorm.length - 1);
-        allReplacements.push({ oldStartLine, oldEndLine, newStartLine, newEndLine, oldLines, newLines, anchor: edit.anchor ? edit.anchor.split("\n")[0] : undefined });
+        // Record needed context range around this edit
+        neededRanges.push({
+          startLine: Math.max(1, oldStartLine - CONTEXT_LINES),
+          endLine: Math.min(totalLines, oldEndLine + CONTEXT_LINES),
+        });
+        allReplacements.push({ oldStartLine, oldEndLine, newStartLine, newEndLine, oldLines, newLines, anchor: displayAnchor ? displayAnchor.split("\n")[0] : undefined, anchorMissing });
         cumulativeOffset += newNorm.length - oldNorm.length;
       }
 
-      const diff = generateReplacementDiff(patch.path, allReplacements, origLines);
+      // Merge needed ranges and extract only those lines
+      const mergedRanges = mergeRanges(neededRanges);
+      const currentLineOffsets = buildLineOffsets(content);
+      const neededLines: Map<number, string> = new Map();
+      for (const range of mergedRanges) {
+        const lines = extractLineRange(content, currentLineOffsets, range.startLine, range.endLine);
+        for (let i = 0; i < lines.length; i++) {
+          neededLines.set(range.startLine + i, lines[i]);
+        }
+      }
+
+      const diff = generateLocalDiff(patch.path, allReplacements, neededLines, totalLines);
       return { diff };
     } else {
       return { error: "Must provide edits[] or overwrite:true" };
@@ -400,6 +508,12 @@ export async function computePatchPreviewMulti(
 
 
 export function generatePatchDiff(result: PatchResult): string {
+  // If applyEdits pre-generated the diff, use it directly (avoids re-reading files)
+  if (result.diff) {
+    return result.diff;
+  }
+
+  // Fallback: reconstruct diff from stored originalLines (legacy path)
   const parts: string[] = [];
   for (const [filePath, reps] of result.replacements) {
     const origLines = result.originalLines.get(filePath) ?? [];
@@ -438,14 +552,29 @@ function buildReplacementChunks(
   return chunks;
 }
 
-function getChunkAnchors(chunk: ReplacementChunk): string[] {
-  return [
-    ...new Set(
-      chunk.reps
-        .map((rep) => rep.anchor?.trim())
-        .filter((anchor): anchor is string => Boolean(anchor)),
-    ),
-  ];
+interface ChunkAnchor {
+  text: string;
+  missing: boolean;
+}
+
+function getChunkAnchors(chunk: ReplacementChunk): ChunkAnchor[] {
+  const byText = new Map<string, ChunkAnchor>();
+  for (const rep of chunk.reps) {
+    const text = rep.anchor?.trim();
+    if (!text) continue;
+    const existing = byText.get(text);
+    if (!existing) {
+      byText.set(text, { text, missing: Boolean(rep.anchorMissing) });
+    } else if (!rep.anchorMissing) {
+      // If any replacement successfully used this anchor, do not mark it missing.
+      existing.missing = false;
+    }
+  }
+  return [...byText.values()];
+}
+
+function formatAnchorLabel(anchor: ChunkAnchor): string {
+  return anchor.text + (anchor.missing ? " (missing)" : "");
 }
 
 function formatChunkHeader(chunk: ReplacementChunk): string {
@@ -459,7 +588,7 @@ function formatChunkHeader(chunk: ReplacementChunk): string {
   }
 
   if (anchors.length === 1) {
-    return `@@ lines ${range} @@ anchor: ${anchors[0]}`;
+    return `@@ lines ${range} @@ anchor: ${formatAnchorLabel(anchors[0]!)}`;
   }
 
   return `@@ lines ${range} @@`;
@@ -471,7 +600,7 @@ function formatChunkMetadataLines(chunk: ReplacementChunk): string[] {
 
   const shown = anchors.slice(0, 2);
   const remaining = anchors.length - shown.length;
-  const lines = ["anchors:", ...shown.map((anchor) => `  - ${anchor}`)];
+  const lines = ["anchors:", ...shown.map((anchor) => `  - ${formatAnchorLabel(anchor)}`)];
   if (remaining > 0) {
     lines.push(`  - +${remaining} more`);
   }
@@ -581,7 +710,18 @@ function restoreLineEndings(text: string, ending: string): string {
   return ending === "\r\n" ? text.replace(/\n/g, "\r\n") : text;
 }
 
-/** Precompute character offsets for each line start. offsets[i] = char offset of line i+1 (1-based). */
+// ═══════════════════════════════════════════════════════════════════════════
+// Line range utilities (for partial file reading)
+// ═══════════════════════════════════════════════════════════════════════════
+
+const CONTEXT_LINES = 3;
+
+interface LineRange {
+  startLine: number;
+  endLine: number;
+}
+
+/** Build line offset table: offsets[i] = character offset of line i+1 (1-based) */
 function buildLineOffsets(content: string): number[] {
   const offsets = [0];
   for (let i = 0; i < content.length; i++) {
@@ -590,8 +730,8 @@ function buildLineOffsets(content: string): number[] {
   return offsets;
 }
 
-/** Binary search: find 1-based line number containing the given char offset.
- *  Uses precomputed line offsets instead of scanning from the beginning. */
+
+/** Binary search: find 1-based line number containing charOffset */
 function lineAtOffset(lineOffsets: number[], charOffset: number): number {
   let lo = 0, hi = lineOffsets.length - 1;
   while (lo < hi) {
@@ -599,10 +739,51 @@ function lineAtOffset(lineOffsets: number[], charOffset: number): number {
     if (lineOffsets[mid] <= charOffset) lo = mid;
     else hi = mid - 1;
   }
-  return lo + 1; // 1-based
+  return lo + 1;
+}
+
+/** Binary search: find line start offset given 1-based line number */
+function offsetAtLine(lineOffsets: number[], lineNum: number): number {
+  if (lineNum <= 1) return 0;
+  if (lineNum > lineOffsets.length) return lineOffsets[lineOffsets.length - 1];
+  return lineOffsets[lineNum - 1];
+}
+
+/** Extract a range of lines from content (1-based, inclusive) */
+function extractLineRange(content: string, lineOffsets: number[], startLine: number, endLine: number): string[] {
+  const lines: string[] = [];
+  for (let i = startLine; i <= endLine; i++) {
+    const start = offsetAtLine(lineOffsets, i);
+    const end = offsetAtLine(lineOffsets, i + 1);
+    // Remove trailing \n from last line if present
+    const lineText = content.slice(start, end).replace(/\n$/, "");
+    lines.push(lineText);
+  }
+  return lines;
+}
+
+
+/** Merge overlapping/adjacent line ranges */
+function mergeRanges(ranges: LineRange[]): LineRange[] {
+  if (ranges.length === 0) return [];
+  const sorted = [...ranges].sort((a, b) => a.startLine - b.startLine);
+  const merged: LineRange[] = [];
+  for (const r of sorted) {
+    const last = merged[merged.length - 1];
+    if (last && r.startLine <= last.endLine + 1) {
+      last.endLine = Math.max(last.endLine, r.endLine);
+    } else {
+      merged.push({ ...r });
+    }
+  }
+  return merged;
 }
 
-/** Convert a character offset to a 1-based line number. O(n) — prefer lineAtOffset for repeated calls on same content. */
+function randomId(): string {
+  return Math.random().toString(36).slice(2, 10);
+}
+
+/** Convert a character offset to a 1-based line number. */
 function charOffsetToLine(content: string, offset: number): number {
   let line = 1;
   for (let i = 0; i < offset && i < content.length; i++) {
@@ -611,8 +792,225 @@ function charOffsetToLine(content: string, offset: number): number {
   return line;
 }
 
-function randomId(): string {
-  return Math.random().toString(36).slice(2, 10);
+/**
+ * Generate diff using only the needed lines (partial file context).
+ */
+function generateLocalDiff(
+  filePath: string,
+  reps: ReplacementInfo[],
+  neededLines: Map<number, string>,
+  totalLines: number,
+): string {
+  if (reps.length === 0) return "";
+
+  const parts: string[] = [];
+  parts.push(`--- ${filePath}`);
+  parts.push(`+++ ${filePath}`);
+
+  // Calculate dynamic width based on max line number
+  const maxLineNum = Math.max(totalLines, ...reps.map(r => r.oldEndLine));
+  const numWidth = String(maxLineNum).length;
+
+  // Merge replacement chunks
+  const chunks = buildReplacementChunks(reps, totalLines, CONTEXT_LINES);
+  for (let c = 0; c < chunks.length; c++) {
+    if (c > 0) parts.push("");
+    const chunk = chunks[c]!;
+    parts.push(formatChunkHeader(chunk));
+    parts.push(...formatChunkMetadataLines(chunk));
+
+    // Output context + removed + added
+    let cursor = chunk.startLine;
+    for (const rep of chunk.reps) {
+      // Context before this replacement
+      for (let i = cursor; i < rep.oldStartLine; i++) {
+        const lineText = neededLines.get(i);
+        if (lineText !== undefined) {
+          parts.push(` ${String(i).padStart(numWidth, " ")} ${lineText}`);
+        }
+      }
+      // Removed lines
+      for (let i = 0; i < rep.oldLines.length; i++) {
+        parts.push(`-${String(rep.oldStartLine + i).padStart(numWidth, " ")} ${rep.oldLines[i]}`);
+      }
+      // Added lines
+      for (let i = 0; i < rep.newLines.length; i++) {
+        parts.push(`+${String(rep.oldStartLine + i).padStart(numWidth, " ")} ${rep.newLines[i]}`);
+      }
+      cursor = rep.oldEndLine + 1;
+    }
+    // Trailing context
+    for (let i = cursor; i <= chunk.endLine; i++) {
+      const lineText = neededLines.get(i);
+      if (lineText !== undefined) {
+        parts.push(` ${String(i).padStart(numWidth, " ")} ${lineText}`);
+      }
+    }
+  }
+
+  return parts.join("\n");
+}
+
+// ─── old_str mismatch diagnostics ─────────────────────────────────────────
+
+/** Detect tab width from the file by analyzing indentation columns of tab-only lines. */
+function detectTabWidth(content: string): number {
+  const lines = content.split("\n");
+  const cols: number[] = [];
+  for (const line of lines) {
+    const nonTabIdx = line.search(/[^\t]/);
+    if (nonTabIdx === -1 || nonTabIdx === 0) continue;
+    cols.push(nonTabIdx);
+  }
+  if (cols.length < 2) return 0;
+  const diffs: number[] = [];
+  for (let i = 1; i < cols.length; i++) {
+    if (cols[i] === cols[i - 1] || cols[i]! > cols[i - 1]! + 8) continue;
+    diffs.push(cols[i]! - cols[i - 1]!);
+  }
+  if (diffs.length === 0) return 0;
+  const sorted = [...diffs].sort((a, b) => a - b);
+  const median = sorted[Math.floor(sorted.length / 2)]!;
+  return [2, 4, 8].reduce((best, w) => Math.abs(w - median) < Math.abs(best - median) ? w : best, 4);
+}
+
+export function diagnoseOldStrNotUnique(oldNorm: string, content: string): string {
+  const fileLines = content.split("\n");
+  const firstOldLine = (oldNorm.split("\n")[0] ?? "").trim();
+  const occurrences: number[] = [];
+  let idx = 0;
+  while ((idx = content.indexOf(oldNorm, idx)) !== -1) {
+    const lineNum = content.substring(0, idx).split("\n").length;
+    occurrences.push(lineNum);
+    idx++;
+  }
+  if (occurrences.length === 0) return "";
+  const shown = occurrences.slice(0, 5);
+  const extra = occurrences.length - shown.length;
+  const lines = shown.map((n) => `  line ${n}: "${(fileLines[n - 1] ?? "").replace(/\t/g, "\\t").slice(0, 60)}"`);
+  if (extra > 0) lines.push(`  and ${extra} more occurrence(s)`);
+  return `old_str appears ${occurrences.length} times:\n${lines.join("\n")}\nAdd more surrounding context to make it unique.`;
+}
+
+/** Try fuzzy match: normalize tab↔space and trailing whitespace, then search line-by-line. */
+function tryFuzzyLineMatch(
+  oldNorm: string,
+  content: string,
+  searchLineStart: number,
+): { idx: number; matched: string } | undefined {
+  const oldLines = oldNorm.split("\n");
+  const fileLines = content.split("\n");
+
+  const fuzzyEq = (fileLine: string, oldLine: string): boolean => {
+    if (fileLine === oldLine) return true;
+    for (const tw of [8, 4, 2]) {
+      if (fileLine.replace(/\t/g, " ".repeat(tw)) === oldLine.replace(/\t/g, " ".repeat(tw))) return true;
+    }
+    if (fileLine.replace(/[\t ]+$/, "") === oldLine.replace(/[\t ]+$/, "")) return true;
+    return false;
+  };
+
+  for (let i = searchLineStart; i <= fileLines.length - oldLines.length; i++) {
+    let ok = true;
+    for (let j = 0; j < oldLines.length; j++) {
+      if (!fuzzyEq(fileLines[i + j] ?? "", oldLines[j] ?? "")) { ok = false; break; }
+    }
+    if (ok) {
+      let idx = 0;
+      for (let k = 0; k < i; k++) idx += (fileLines[k] ?? "").length + 1;
+      const matched = oldLines.map((_, j) => fileLines[i + j]).join("\n");
+      // Check uniqueness in the fuzzy-matched range
+      const secondIdx = content.indexOf(matched, idx + 1);
+      if (secondIdx === -1) return { idx, matched };
+    }
+  }
+  return undefined;
+}
+
+/** Replace new_str's leading whitespace with the actual file line's leading whitespace style. */
+function normalizeIndentForFuzzy(actualLine: string, newLine: string): string {
+  const actualLeading = actualLine.match(/^[\t ]*/)?.[0] ?? "";
+  const newLeading = newLine.match(/^[\t ]*/)?.[0] ?? "";
+  if (actualLeading === newLeading) return newLine;
+  return actualLeading + newLine.slice(newLeading.length);
+}
+
+export function diagnoseOldStrMismatch(oldNorm: string, content: string, isConfigFile?: boolean): string {
+  const oldLines = oldNorm.split("\n");
+  const fileLines = content.split("\n");
+  const firstOldLine = oldLines[0] ?? "";
+  const parts: string[] = [];
+
+  // Find the closest matching line in the file
+  let bestMatchIdx = -1;
+  let bestMatchType = "";
+
+  for (let i = 0; i < fileLines.length; i++) {
+    const fileLine = fileLines[i] ?? "";
+
+    if (fileLine === firstOldLine) {
+      bestMatchIdx = i;
+      bestMatchType = "";
+      break;
+    }
+
+    if (fileLine.replace(/\t/g, "        ") === firstOldLine ||
+        fileLine.replace(/\t/g, "    ") === firstOldLine ||
+        fileLine.replace(/\t/g, "  ") === firstOldLine) {
+      bestMatchIdx = i;
+      bestMatchType = "tab vs space (file has tabs, old_str has spaces)";
+      break;
+    }
+
+    if (fileLine.replace(/[\t ]+$/, "") === firstOldLine.replace(/[\t ]+$/, "")) {
+      bestMatchIdx = i;
+      bestMatchType = "trailing whitespace mismatch";
+      break;
+    }
+
+    if (fileLine.toLowerCase() === firstOldLine.toLowerCase()) {
+      bestMatchIdx = i;
+      bestMatchType = "case mismatch";
+      break;
+    }
+
+    const trimmedOld = firstOldLine.trim();
+    if (trimmedOld.length > 3 && fileLine.includes(trimmedOld)) {
+      if (bestMatchIdx === -1) {
+        bestMatchIdx = i;
+        bestMatchType = "indent mismatch (content matches, whitespace differs)";
+      }
+    }
+  }
+
+  if (bestMatchIdx >= 0 && bestMatchType) {
+    parts.push(`Hint: ${bestMatchType} at line ${bestMatchIdx + 1}.`);
+    parts.push(`  actual: ${JSON.stringify(fileLines[bestMatchIdx])}`);
+    parts.push(`  expected: ${JSON.stringify(firstOldLine)}`);
+  } else if (bestMatchIdx >= 0) {
+    // First line matched, but full old_str block does not — find the first mismatching line
+    const oldArr = oldNorm.split("\n");
+    let mismatchLine = 0;
+    for (let j = 1; j < oldArr.length; j++) {
+      const fileLine = fileLines[bestMatchIdx + j] ?? "<EOF>";
+      const oldLine = oldArr[j] ?? "";
+      if (fileLine !== oldLine) {
+        mismatchLine = bestMatchIdx + j + 1;
+        parts.push(`Line ${bestMatchIdx + 1} matches, but diff at line ${mismatchLine}:`);
+        parts.push(`  actual: ${JSON.stringify(fileLine)}`);
+        parts.push(`  expected: ${JSON.stringify(oldLine)}`);
+        break;
+      }
+    }
+    if (mismatchLine === 0) {
+      parts.push(`First line matches at line ${bestMatchIdx + 1}, but full ${oldArr.length}-line block does not.`);
+    }
+  } else if (firstOldLine.trim().length > 3) {
+    parts.push(`Content "${firstOldLine.trim().slice(0, 60)}" not found anywhere in the file.`);
+    parts.push(`File may have changed — re-read it and try again.`);
+  }
+
+  return parts.join("\n");
 }
 
 function truncate(s: string, maxLen = 60): string {