apex-code 0.0.1-alpha.9 → 0.0.4

package/dist/core/tools/edit-diff.d.ts

@@ -60,6 +60,46 @@ export interface AppliedEditsResult {
  * Unicode quotes/dashes normalized to ASCII).
  */
 export declare function fuzzyFindText(content: string, oldText: string): FuzzyMatchResult;
+/**
+ * Explicit budgets for the advisory edit-failure diagnostics below. Diagnostics
+ * are a best-effort hint, never an apply path, so every dimension of the scan
+ * is bounded and the ordinary failure is returned untouched when a bound is
+ * exceeded (spec 2026-09-01-tool-reliability-and-execution-budgets.md § 2).
+ */
+export declare const EDIT_DIAGNOSTIC_MAX_FILE_BYTES = 1048576;
+export declare const EDIT_DIAGNOSTIC_MAX_TARGET_BYTES = 65536;
+export declare const EDIT_DIAGNOSTIC_MAX_CANDIDATES = 3;
+export declare const EDIT_DIAGNOSTIC_MAX_SCAN_WINDOWS = 20000;
+export declare const EDIT_DIAGNOSTIC_MAX_OCCURRENCES = 5;
+export declare const EDIT_DIAGNOSTIC_SNIPPET_LINE_CHARS = 160;
+export interface EditCandidateLocation {
+    /** 1-based, inclusive. */
+    startLine: number;
+    /** 1-based, inclusive. */
+    endLine: number;
+    /** Bigram Dice similarity against the failed target, rounded to two decimals. */
+    similarity: number;
+    /** Bounded snippet of the candidate source lines, each line-numbered. */
+    snippet: string;
+}
+/**
+ * Advisory diagnostics attached to a failed edit match. These describe where a
+ * target almost matched or where duplicates live; they are never a replacement
+ * location and must never be applied.
+ */
+export interface EditFailureDiagnostics {
+    kind: "missing-match" | "duplicate-match";
+    candidates: EditCandidateLocation[];
+    /** 1-based source lines of up to EDIT_DIAGNOSTIC_MAX_OCCURRENCES duplicates. */
+    occurrenceLines: number[];
+    omittedOccurrences: number;
+    /** True when the scan stopped at a work or time bound before finishing. */
+    scanTruncated: boolean;
+    /** Set when scanning was unsafe or oversized; no candidates are reported. */
+    unavailableReason?: string;
+}
+/** Render advisory diagnostics as an error-message appendix. Empty when there is nothing to say. */
+export declare function formatEditFailureDiagnostics(diagnostics: EditFailureDiagnostics | undefined): string;
 /**
  * Apply one or more exact-text replacements to LF-normalized content.
  *
@@ -92,6 +132,14 @@ export interface EditDiffError {
  * Used for preview rendering in the TUI before the tool executes.
  */
 export declare function computeEditsDiff(path: string, edits: Edit[], cwd: string): Promise<EditDiffResult | EditDiffError>;
+/**
+ * The half of `computeEditsDiff` that does not choose which bytes to read.
+ *
+ * The permission preview must describe the operation the gate authorized rather
+ * than whatever the pathname resolves to a second time, so it supplies content
+ * read through the prepared operation and calls this (ADR 0029).
+ */
+export declare function computeEditsDiffFromContent(path: string, rawContent: string, edits: Edit[]): EditDiffResult | EditDiffError;
 /**
  * Compute the diff for a single edit operation without applying it.
  * Kept as a convenience wrapper for single-edit callers.

package/dist/core/tools/edit-diff.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"edit-diff.d.ts","sourceRoot":"","sources":["../../../src/core/tools/edit-diff.ts"],"names":[],"mappings":"AAAA;;GAEG;AAQH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAM/D;AAED,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAElD;AAED,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,CAE9E;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAqB3D;AAWD,UAAU,WAAW;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;CAChB;AAED,KAAK,eAAe,GAAG,IAAI,CAAC,WAAW,EAAE,YAAY,GAAG,aAAa,GAAG,SAAS,CAAC,CAAC;AAiDnF;;;;;;;;;GASG;AACH,wBAAgB,yCAAyC,CACxD,eAAe,EAAE,MAAM,EACvB,WAAW,EAAE,MAAM,EACnB,YAAY,EAAE,eAAe,EAAE,GAC7B,MAAM,CAqCR;AAED,MAAM,WAAW,gBAAgB;IAChC,gCAAgC;IAChC,KAAK,EAAE,OAAO,CAAC;IACf,4FAA4F;IAC5F,KAAK,EAAE,MAAM,CAAC;IACd,iCAAiC;IACjC,WAAW,EAAE,MAAM,CAAC;IACpB,4DAA4D;IAC5D,cAAc,EAAE,OAAO,CAAC;IACxB;;;OAGG;IACH,qBAAqB,EAAE,MAAM,CAAC;CAC9B;AAED,MAAM,WAAW,IAAI;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,kBAAkB;IAClC,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;CACnB;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,gBAAgB,CAsChF;AA8CD;;;;;;;;GAQG;AACH,wBAAgB,6BAA6B,CAC5C,iBAAiB,EAAE,MAAM,EACzB,KAAK,EAAE,IAAI,EAAE,EACb,IAAI,EAAE,MAAM,GACV,kBAAkB,CA0DpB;AAED,yCAAyC;AACzC,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,YAAY,SAAI,GAAG,MAAM,CAKnH;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CACjC,UAAU,EAAE,MAAM,EAClB,UAAU,EAAE,MAAM,EAClB,YAAY,SAAI,GACd;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,gBAAgB,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,CAuHxD;AAED,MAAM,WAAW,cAAc;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,gBAAgB,EAAE,MAAM,GAAG,SAAS,CAAC;CACrC;AAED,MAAM,WAAW,aAAa;IAC7B,KAAK,EAAE,MAAM,CAAC;CACd;AAED;;;GAGG;AACH,wBAAsB,gBAAgB,CACrC,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,IAAI,EAAE,EACb,GAAG,EAAE,MAAM,GACT,OAAO,CAAC,cAAc,GAAG,aAAa,CAAC,CAyBzC;AAED;;;GAGG;AACH,wBAAsB,eAAe,CACpC,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,EACf,GAAG,EAAE,MAAM,GACT,OAAO,CAAC,cAAc,GAAG,aAAa,CAAC,CAEzC","sourcesContent":["/**\n * Shared diff computation utilities for the edit and similar tools.\n */\n\nimport * as Diff from \"diff\";\nimport { constants } from \"fs\";\nimport { access, readFile } from \"fs/promises\";\nimport { splitBom } from \"../../utils/text.ts\";\nimport { resolveToCwd } from \"./path-utils.ts\";\n\nexport function detectLineEnding(content: string): \"\\r\\n\" | \"\\n\" {\n\tconst crlfIdx = content.indexOf(\"\\r\\n\");\n\tconst lfIdx = content.indexOf(\"\\n\");\n\tif (lfIdx === -1) return \"\\n\";\n\tif (crlfIdx === -1) return \"\\n\";\n\treturn crlfIdx < lfIdx ? \"\\r\\n\" : \"\\n\";\n}\n\nexport function normalizeToLF(text: string): string {\n\treturn text.replace(/\\r\\n/g, \"\\n\").replace(/\\r/g, \"\\n\");\n}\n\nexport function restoreLineEndings(text: string, ending: \"\\r\\n\" | \"\\n\"): string {\n\treturn ending === \"\\r\\n\" ? text.replace(/\\n/g, \"\\r\\n\") : text;\n}\n\n/**\n * Normalize text for fuzzy matching. Applies progressive transformations:\n * - Strip trailing whitespace from each line\n * - Normalize smart quotes to ASCII equivalents\n * - Normalize Unicode dashes/hyphens to ASCII hyphen\n * - Normalize special Unicode spaces to regular space\n */\nexport function normalizeForFuzzyMatch(text: string): string {\n\treturn (\n\t\ttext\n\t\t\t.normalize(\"NFKC\")\n\t\t\t// Strip trailing whitespace per line\n\t\t\t.split(\"\\n\")\n\t\t\t.map((line) => line.trimEnd())\n\t\t\t.join(\"\\n\")\n\t\t\t// Smart single quotes → '\n\t\t\t.replace(/[\\u2018\\u2019\\u201A\\u201B]/g, \"'\")\n\t\t\t// Smart double quotes → \"\n\t\t\t.replace(/[\\u201C\\u201D\\u201E\\u201F]/g, '\"')\n\t\t\t// Various dashes/hyphens → -\n\t\t\t// U+2010 hyphen, U+2011 non-breaking hyphen, U+2012 figure dash,\n\t\t\t// U+2013 en-dash, U+2014 em-dash, U+2015 horizontal bar, U+2212 minus\n\t\t\t.replace(/[\\u2010\\u2011\\u2012\\u2013\\u2014\\u2015\\u2212]/g, \"-\")\n\t\t\t// Special spaces → regular space\n\t\t\t// U+00A0 NBSP, U+2002-U+200A various spaces, U+202F narrow NBSP,\n\t\t\t// U+205F medium math space, U+3000 ideographic space\n\t\t\t.replace(/[\\u00A0\\u2002-\\u200A\\u202F\\u205F\\u3000]/g, \" \")\n\t);\n}\n\nfunction splitLinesWithEndings(content: string): string[] {\n\treturn content.match(/[^\\n]*\\n|[^\\n]+/g) ?? [];\n}\n\ninterface LineSpan {\n\tstart: number;\n\tend: number;\n}\n\ninterface MatchedEdit {\n\teditIndex: number;\n\tmatchIndex: number;\n\tmatchLength: number;\n\tnewText: string;\n}\n\ntype TextReplacement = Pick<MatchedEdit, \"matchIndex\" | \"matchLength\" | \"newText\">;\n\nfunction getLineSpans(content: string): LineSpan[] {\n\tlet offset = 0;\n\treturn splitLinesWithEndings(content).map((line) => {\n\t\tconst span = { start: offset, end: offset + line.length };\n\t\toffset = span.end;\n\t\treturn span;\n\t});\n}\n\nfunction getReplacementLineRange(lines: LineSpan[], replacement: TextReplacement) {\n\tconst replacementStart = replacement.matchIndex;\n\tconst replacementEnd = replacement.matchIndex + replacement.matchLength;\n\n\tlet startLine = -1;\n\tfor (let i = 0; i < lines.length; i++) {\n\t\tconst line = lines[i];\n\t\tif (replacementStart >= line.start && replacementStart < line.end) {\n\t\t\tstartLine = i;\n\t\t\tbreak;\n\t\t}\n\t}\n\tif (startLine === -1) {\n\t\tthrow new Error(\"Replacement range is outside the base content.\");\n\t}\n\n\tlet endLine = startLine;\n\twhile (endLine < lines.length && lines[endLine].end < replacementEnd) {\n\t\tendLine++;\n\t}\n\tif (endLine >= lines.length) {\n\t\tthrow new Error(\"Replacement range is outside the base content.\");\n\t}\n\n\treturn { startLine, endLine: endLine + 1 };\n}\n\nfunction applyReplacements(content: string, replacements: TextReplacement[], offset = 0): string {\n\tlet result = content;\n\tfor (let i = replacements.length - 1; i >= 0; i--) {\n\t\tconst replacement = replacements[i];\n\t\tconst matchIndex = replacement.matchIndex - offset;\n\t\tresult =\n\t\t\tresult.substring(0, matchIndex) + replacement.newText + result.substring(matchIndex + replacement.matchLength);\n\t}\n\treturn result;\n}\n\n/**\n * Apply replacements matched against `baseContent` to `originalContent` while\n * preserving unchanged line blocks from the original.\n *\n * This is useful when `baseContent` is a normalized view of the original. Each\n * replacement is widened to the lines it actually touches, those touched lines\n * are rewritten from the normalized base, and all other lines are copied back\n * from `originalContent`. The actual replacement ranges drive preservation so\n * duplicate normalized lines cannot be aligned to the wrong occurrence.\n */\nexport function applyReplacementsPreservingUnchangedLines(\n\toriginalContent: string,\n\tbaseContent: string,\n\treplacements: TextReplacement[],\n): string {\n\tconst originalLines = splitLinesWithEndings(originalContent);\n\tconst baseLines = getLineSpans(baseContent);\n\tif (originalLines.length !== baseLines.length) {\n\t\tthrow new Error(\"Cannot preserve unchanged lines because the base content has a different line count.\");\n\t}\n\n\tconst groups: Array<{ startLine: number; endLine: number; replacements: TextReplacement[] }> = [];\n\tconst sortedReplacements = [...replacements].sort((a, b) => a.matchIndex - b.matchIndex);\n\tfor (const replacement of sortedReplacements) {\n\t\tconst range = getReplacementLineRange(baseLines, replacement);\n\t\tconst current = groups[groups.length - 1];\n\t\tif (current && range.startLine < current.endLine) {\n\t\t\tcurrent.endLine = Math.max(current.endLine, range.endLine);\n\t\t\tcurrent.replacements.push(replacement);\n\t\t\tcontinue;\n\t\t}\n\t\tgroups.push({ ...range, replacements: [replacement] });\n\t}\n\n\tlet originalLineIndex = 0;\n\tlet result = \"\";\n\tfor (const group of groups) {\n\t\tresult += originalLines.slice(originalLineIndex, group.startLine).join(\"\");\n\n\t\tconst groupStartOffset = baseLines[group.startLine].start;\n\t\tconst groupEndOffset = baseLines[group.endLine - 1].end;\n\t\tresult += applyReplacements(\n\t\t\tbaseContent.slice(groupStartOffset, groupEndOffset),\n\t\t\tgroup.replacements,\n\t\t\tgroupStartOffset,\n\t\t);\n\t\toriginalLineIndex = group.endLine;\n\t}\n\tresult += originalLines.slice(originalLineIndex).join(\"\");\n\n\treturn result;\n}\n\nexport interface FuzzyMatchResult {\n\t/** Whether a match was found */\n\tfound: boolean;\n\t/** The index where the match starts (in the content that should be used for replacement) */\n\tindex: number;\n\t/** Length of the matched text */\n\tmatchLength: number;\n\t/** Whether fuzzy matching was used (false = exact match) */\n\tusedFuzzyMatch: boolean;\n\t/**\n\t * The content to use for replacement operations.\n\t * When exact match: original content. When fuzzy match: normalized content.\n\t */\n\tcontentForReplacement: string;\n}\n\nexport interface Edit {\n\toldText: string;\n\tnewText: string;\n}\n\nexport interface AppliedEditsResult {\n\tbaseContent: string;\n\tnewContent: string;\n}\n\n/**\n * Find oldText in content, trying exact match first, then fuzzy match.\n * When fuzzy matching is used, the returned contentForReplacement is the\n * fuzzy-normalized version of the content (trailing whitespace stripped,\n * Unicode quotes/dashes normalized to ASCII).\n */\nexport function fuzzyFindText(content: string, oldText: string): FuzzyMatchResult {\n\t// Try exact match first\n\tconst exactIndex = content.indexOf(oldText);\n\tif (exactIndex !== -1) {\n\t\treturn {\n\t\t\tfound: true,\n\t\t\tindex: exactIndex,\n\t\t\tmatchLength: oldText.length,\n\t\t\tusedFuzzyMatch: false,\n\t\t\tcontentForReplacement: content,\n\t\t};\n\t}\n\n\t// Try fuzzy match - work entirely in normalized space\n\tconst fuzzyContent = normalizeForFuzzyMatch(content);\n\tconst fuzzyOldText = normalizeForFuzzyMatch(oldText);\n\tconst fuzzyIndex = fuzzyContent.indexOf(fuzzyOldText);\n\n\tif (fuzzyIndex === -1) {\n\t\treturn {\n\t\t\tfound: false,\n\t\t\tindex: -1,\n\t\t\tmatchLength: 0,\n\t\t\tusedFuzzyMatch: false,\n\t\t\tcontentForReplacement: content,\n\t\t};\n\t}\n\n\t// When fuzzy matching, return offsets in normalized space. Callers can use\n\t// the normalized content to compute replacements, then decide how much of\n\t// that normalized output should be written back.\n\treturn {\n\t\tfound: true,\n\t\tindex: fuzzyIndex,\n\t\tmatchLength: fuzzyOldText.length,\n\t\tusedFuzzyMatch: true,\n\t\tcontentForReplacement: fuzzyContent,\n\t};\n}\n\nfunction countOccurrences(content: string, oldText: string): number {\n\tconst fuzzyContent = normalizeForFuzzyMatch(content);\n\tconst fuzzyOldText = normalizeForFuzzyMatch(oldText);\n\treturn fuzzyContent.split(fuzzyOldText).length - 1;\n}\n\nfunction getNotFoundError(path: string, editIndex: number, totalEdits: number): Error {\n\tif (totalEdits === 1) {\n\t\treturn new Error(\n\t\t\t`Could not find the exact text in ${path}. The old text must match exactly including all whitespace and newlines.`,\n\t\t);\n\t}\n\treturn new Error(\n\t\t`Could not find edits[${editIndex}] in ${path}. The oldText must match exactly including all whitespace and newlines.`,\n\t);\n}\n\nfunction getDuplicateError(path: string, editIndex: number, totalEdits: number, occurrences: number): Error {\n\tif (totalEdits === 1) {\n\t\treturn new Error(\n\t\t\t`Found ${occurrences} occurrences of the text in ${path}. The text must be unique. Please provide more context to make it unique.`,\n\t\t);\n\t}\n\treturn new Error(\n\t\t`Found ${occurrences} occurrences of edits[${editIndex}] in ${path}. Each oldText must be unique. Please provide more context to make it unique.`,\n\t);\n}\n\nfunction getEmptyOldTextError(path: string, editIndex: number, totalEdits: number): Error {\n\tif (totalEdits === 1) {\n\t\treturn new Error(`oldText must not be empty in ${path}.`);\n\t}\n\treturn new Error(`edits[${editIndex}].oldText must not be empty in ${path}.`);\n}\n\nfunction getNoChangeError(path: string, totalEdits: number): Error {\n\tif (totalEdits === 1) {\n\t\treturn new Error(\n\t\t\t`No changes made to ${path}. The replacement produced identical content. This might indicate an issue with special characters or the text not existing as expected.`,\n\t\t);\n\t}\n\treturn new Error(`No changes made to ${path}. The replacements produced identical content.`);\n}\n\n/**\n * Apply one or more exact-text replacements to LF-normalized content.\n *\n * All edits are matched against the same original content. Replacements are\n * then applied in reverse order so offsets remain stable. If any edit needs\n * fuzzy matching, the operation runs in fuzzy-normalized content space and then\n * overlays those line-level changes onto the original content so unchanged line\n * blocks keep their original bytes.\n */\nexport function applyEditsToNormalizedContent(\n\tnormalizedContent: string,\n\tedits: Edit[],\n\tpath: string,\n): AppliedEditsResult {\n\tconst normalizedEdits = edits.map((edit) => ({\n\t\toldText: normalizeToLF(edit.oldText),\n\t\tnewText: normalizeToLF(edit.newText),\n\t}));\n\n\tfor (let i = 0; i < normalizedEdits.length; i++) {\n\t\tif (normalizedEdits[i].oldText.length === 0) {\n\t\t\tthrow getEmptyOldTextError(path, i, normalizedEdits.length);\n\t\t}\n\t}\n\n\tconst initialMatches = normalizedEdits.map((edit) => fuzzyFindText(normalizedContent, edit.oldText));\n\tconst usedFuzzyMatch = initialMatches.some((match) => match.usedFuzzyMatch);\n\tconst replacementBaseContent = usedFuzzyMatch ? normalizeForFuzzyMatch(normalizedContent) : normalizedContent;\n\n\tconst matchedEdits: MatchedEdit[] = [];\n\tfor (let i = 0; i < normalizedEdits.length; i++) {\n\t\tconst edit = normalizedEdits[i];\n\t\tconst matchResult = fuzzyFindText(replacementBaseContent, edit.oldText);\n\t\tif (!matchResult.found) {\n\t\t\tthrow getNotFoundError(path, i, normalizedEdits.length);\n\t\t}\n\n\t\tconst occurrences = countOccurrences(replacementBaseContent, edit.oldText);\n\t\tif (occurrences > 1) {\n\t\t\tthrow getDuplicateError(path, i, normalizedEdits.length, occurrences);\n\t\t}\n\n\t\tmatchedEdits.push({\n\t\t\teditIndex: i,\n\t\t\tmatchIndex: matchResult.index,\n\t\t\tmatchLength: matchResult.matchLength,\n\t\t\tnewText: edit.newText,\n\t\t});\n\t}\n\n\tmatchedEdits.sort((a, b) => a.matchIndex - b.matchIndex);\n\tfor (let i = 1; i < matchedEdits.length; i++) {\n\t\tconst previous = matchedEdits[i - 1];\n\t\tconst current = matchedEdits[i];\n\t\tif (previous.matchIndex + previous.matchLength > current.matchIndex) {\n\t\t\tthrow new Error(\n\t\t\t\t`edits[${previous.editIndex}] and edits[${current.editIndex}] overlap in ${path}. Merge them into one edit or target disjoint regions.`,\n\t\t\t);\n\t\t}\n\t}\n\n\tconst baseContent = normalizedContent;\n\tconst newContent = usedFuzzyMatch\n\t\t? applyReplacementsPreservingUnchangedLines(normalizedContent, replacementBaseContent, matchedEdits)\n\t\t: applyReplacements(replacementBaseContent, matchedEdits);\n\n\tif (baseContent === newContent) {\n\t\tthrow getNoChangeError(path, normalizedEdits.length);\n\t}\n\n\treturn { baseContent, newContent };\n}\n\n/** Generate a standard unified patch. */\nexport function generateUnifiedPatch(path: string, oldContent: string, newContent: string, contextLines = 4): string {\n\treturn Diff.createTwoFilesPatch(path, path, oldContent, newContent, undefined, undefined, {\n\t\tcontext: contextLines,\n\t\theaderOptions: Diff.FILE_HEADERS_ONLY,\n\t});\n}\n\n/**\n * Generate a display-oriented diff string with line numbers and context.\n * Returns both the diff string and the first changed line number (in the new file).\n */\nexport function generateDiffString(\n\toldContent: string,\n\tnewContent: string,\n\tcontextLines = 4,\n): { diff: string; firstChangedLine: number | undefined } {\n\tconst parts = Diff.diffLines(oldContent, newContent);\n\tconst output: string[] = [];\n\n\tconst oldLines = oldContent.split(\"\\n\");\n\tconst newLines = newContent.split(\"\\n\");\n\tconst maxLineNum = Math.max(oldLines.length, newLines.length);\n\tconst lineNumWidth = String(maxLineNum).length;\n\n\tlet oldLineNum = 1;\n\tlet newLineNum = 1;\n\tlet lastWasChange = false;\n\tlet firstChangedLine: number | undefined;\n\n\tfor (let i = 0; i < parts.length; i++) {\n\t\tconst part = parts[i];\n\t\tconst raw = part.value.split(\"\\n\");\n\t\tif (raw[raw.length - 1] === \"\") {\n\t\t\traw.pop();\n\t\t}\n\n\t\tif (part.added || part.removed) {\n\t\t\t// Capture the first changed line (in the new file)\n\t\t\tif (firstChangedLine === undefined) {\n\t\t\t\tfirstChangedLine = newLineNum;\n\t\t\t}\n\n\t\t\t// Show the change\n\t\t\tfor (const line of raw) {\n\t\t\t\tif (part.added) {\n\t\t\t\t\tconst lineNum = String(newLineNum).padStart(lineNumWidth, \" \");\n\t\t\t\t\toutput.push(`+${lineNum} ${line}`);\n\t\t\t\t\tnewLineNum++;\n\t\t\t\t} else {\n\t\t\t\t\t// removed\n\t\t\t\t\tconst lineNum = String(oldLineNum).padStart(lineNumWidth, \" \");\n\t\t\t\t\toutput.push(`-${lineNum} ${line}`);\n\t\t\t\t\toldLineNum++;\n\t\t\t\t}\n\t\t\t}\n\t\t\tlastWasChange = true;\n\t\t} else {\n\t\t\t// Context lines - only show a few before/after changes\n\t\t\tconst nextPartIsChange = i < parts.length - 1 && (parts[i + 1].added || parts[i + 1].removed);\n\t\t\tconst hasLeadingChange = lastWasChange;\n\t\t\tconst hasTrailingChange = nextPartIsChange;\n\n\t\t\tif (hasLeadingChange && hasTrailingChange) {\n\t\t\t\tif (raw.length <= contextLines * 2) {\n\t\t\t\t\tfor (const line of raw) {\n\t\t\t\t\t\tconst lineNum = String(oldLineNum).padStart(lineNumWidth, \" \");\n\t\t\t\t\t\toutput.push(` ${lineNum} ${line}`);\n\t\t\t\t\t\toldLineNum++;\n\t\t\t\t\t\tnewLineNum++;\n\t\t\t\t\t}\n\t\t\t\t} else {\n\t\t\t\t\tconst leadingLines = raw.slice(0, contextLines);\n\t\t\t\t\tconst trailingLines = raw.slice(raw.length - contextLines);\n\t\t\t\t\tconst skippedLines = raw.length - leadingLines.length - trailingLines.length;\n\n\t\t\t\t\tfor (const line of leadingLines) {\n\t\t\t\t\t\tconst lineNum = String(oldLineNum).padStart(lineNumWidth, \" \");\n\t\t\t\t\t\toutput.push(` ${lineNum} ${line}`);\n\t\t\t\t\t\toldLineNum++;\n\t\t\t\t\t\tnewLineNum++;\n\t\t\t\t\t}\n\n\t\t\t\t\toutput.push(` ${\"\".padStart(lineNumWidth, \" \")} ...`);\n\t\t\t\t\toldLineNum += skippedLines;\n\t\t\t\t\tnewLineNum += skippedLines;\n\n\t\t\t\t\tfor (const line of trailingLines) {\n\t\t\t\t\t\tconst lineNum = String(oldLineNum).padStart(lineNumWidth, \" \");\n\t\t\t\t\t\toutput.push(` ${lineNum} ${line}`);\n\t\t\t\t\t\toldLineNum++;\n\t\t\t\t\t\tnewLineNum++;\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t} else if (hasLeadingChange) {\n\t\t\t\tconst shownLines = raw.slice(0, contextLines);\n\t\t\t\tconst skippedLines = raw.length - shownLines.length;\n\n\t\t\t\tfor (const line of shownLines) {\n\t\t\t\t\tconst lineNum = String(oldLineNum).padStart(lineNumWidth, \" \");\n\t\t\t\t\toutput.push(` ${lineNum} ${line}`);\n\t\t\t\t\toldLineNum++;\n\t\t\t\t\tnewLineNum++;\n\t\t\t\t}\n\n\t\t\t\tif (skippedLines > 0) {\n\t\t\t\t\toutput.push(` ${\"\".padStart(lineNumWidth, \" \")} ...`);\n\t\t\t\t\toldLineNum += skippedLines;\n\t\t\t\t\tnewLineNum += skippedLines;\n\t\t\t\t}\n\t\t\t} else if (hasTrailingChange) {\n\t\t\t\tconst skippedLines = Math.max(0, raw.length - contextLines);\n\t\t\t\tif (skippedLines > 0) {\n\t\t\t\t\toutput.push(` ${\"\".padStart(lineNumWidth, \" \")} ...`);\n\t\t\t\t\toldLineNum += skippedLines;\n\t\t\t\t\tnewLineNum += skippedLines;\n\t\t\t\t}\n\n\t\t\t\tfor (const line of raw.slice(skippedLines)) {\n\t\t\t\t\tconst lineNum = String(oldLineNum).padStart(lineNumWidth, \" \");\n\t\t\t\t\toutput.push(` ${lineNum} ${line}`);\n\t\t\t\t\toldLineNum++;\n\t\t\t\t\tnewLineNum++;\n\t\t\t\t}\n\t\t\t} else {\n\t\t\t\t// Skip these context lines entirely\n\t\t\t\toldLineNum += raw.length;\n\t\t\t\tnewLineNum += raw.length;\n\t\t\t}\n\n\t\t\tlastWasChange = false;\n\t\t}\n\t}\n\n\treturn { diff: output.join(\"\\n\"), firstChangedLine };\n}\n\nexport interface EditDiffResult {\n\tdiff: string;\n\tfirstChangedLine: number | undefined;\n}\n\nexport interface EditDiffError {\n\terror: string;\n}\n\n/**\n * Compute the diff for one or more edit operations without applying them.\n * Used for preview rendering in the TUI before the tool executes.\n */\nexport async function computeEditsDiff(\n\tpath: string,\n\tedits: Edit[],\n\tcwd: string,\n): Promise<EditDiffResult | EditDiffError> {\n\tconst absolutePath = resolveToCwd(path, cwd);\n\n\ttry {\n\t\t// Check if file exists and is readable\n\t\ttry {\n\t\t\tawait access(absolutePath, constants.R_OK);\n\t\t} catch (error: unknown) {\n\t\t\tconst errorMessage = error instanceof Error && \"code\" in error ? `Error code: ${error.code}` : String(error);\n\t\t\treturn { error: `Could not edit file: ${path}. ${errorMessage}.` };\n\t\t}\n\n\t\t// Read the file\n\t\tconst rawContent = await readFile(absolutePath, \"utf-8\");\n\n\t\t// Strip BOM before matching (LLM won't include invisible BOM in oldText)\n\t\tconst { text: content } = splitBom(rawContent);\n\t\tconst normalizedContent = normalizeToLF(content);\n\t\tconst { baseContent, newContent } = applyEditsToNormalizedContent(normalizedContent, edits, path);\n\n\t\t// Generate the diff\n\t\treturn generateDiffString(baseContent, newContent);\n\t} catch (err) {\n\t\treturn { error: err instanceof Error ? err.message : String(err) };\n\t}\n}\n\n/**\n * Compute the diff for a single edit operation without applying it.\n * Kept as a convenience wrapper for single-edit callers.\n */\nexport async function computeEditDiff(\n\tpath: string,\n\toldText: string,\n\tnewText: string,\n\tcwd: string,\n): Promise<EditDiffResult | EditDiffError> {\n\treturn computeEditsDiff(path, [{ oldText, newText }], cwd);\n}\n"]}
+{"version":3,"file":"edit-diff.d.ts","sourceRoot":"","sources":["../../../src/core/tools/edit-diff.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Shared diff computation utilities for the edit and similar tools.\n */\n\nimport * as Diff from \"diff\";\nimport { constants } from \"fs\";\nimport { access, readFile } from \"fs/promises\";\nimport { splitBom } from \"../../utils/text.ts\";\nimport { resolveToCwd } from \"./path-utils.ts\";\n\nexport function detectLineEnding(content: string): \"\\r\\n\" | \"\\n\" {\n\tconst crlfIdx = content.indexOf(\"\\r\\n\");\n\tconst lfIdx = content.indexOf(\"\\n\");\n\tif (lfIdx === -1) return \"\\n\";\n\tif (crlfIdx === -1) return \"\\n\";\n\treturn crlfIdx < lfIdx ? \"\\r\\n\" : \"\\n\";\n}\n\nexport function normalizeToLF(text: string): string {\n\treturn text.replace(/\\r\\n/g, \"\\n\").replace(/\\r/g, \"\\n\");\n}\n\nexport function restoreLineEndings(text: string, ending: \"\\r\\n\" | \"\\n\"): string {\n\treturn ending === \"\\r\\n\" ? text.replace(/\\n/g, \"\\r\\n\") : text;\n}\n\n/**\n * Normalize text for fuzzy matching. Applies progressive transformations:\n * - Strip trailing whitespace from each line\n * - Normalize smart quotes to ASCII equivalents\n * - Normalize Unicode dashes/hyphens to ASCII hyphen\n * - Normalize special Unicode spaces to regular space\n */\nexport function normalizeForFuzzyMatch(text: string): string {\n\treturn (\n\t\ttext\n\t\t\t.normalize(\"NFKC\")\n\t\t\t// Strip trailing whitespace per line\n\t\t\t.split(\"\\n\")\n\t\t\t.map((line) => line.trimEnd())\n\t\t\t.join(\"\\n\")\n\t\t\t// Smart single quotes → '\n\t\t\t.replace(/[\\u2018\\u2019\\u201A\\u201B]/g, \"'\")\n\t\t\t// Smart double quotes → \"\n\t\t\t.replace(/[\\u201C\\u201D\\u201E\\u201F]/g, '\"')\n\t\t\t// Various dashes/hyphens → -\n\t\t\t// U+2010 hyphen, U+2011 non-breaking hyphen, U+2012 figure dash,\n\t\t\t// U+2013 en-dash, U+2014 em-dash, U+2015 horizontal bar, U+2212 minus\n\t\t\t.replace(/[\\u2010\\u2011\\u2012\\u2013\\u2014\\u2015\\u2212]/g, \"-\")\n\t\t\t// Special spaces → regular space\n\t\t\t// U+00A0 NBSP, U+2002-U+200A various spaces, U+202F narrow NBSP,\n\t\t\t// U+205F medium math space, U+3000 ideographic space\n\t\t\t.replace(/[\\u00A0\\u2002-\\u200A\\u202F\\u205F\\u3000]/g, \" \")\n\t);\n}\n\nfunction splitLinesWithEndings(content: string): string[] {\n\treturn content.match(/[^\\n]*\\n|[^\\n]+/g) ?? [];\n}\n\ninterface LineSpan {\n\tstart: number;\n\tend: number;\n}\n\ninterface MatchedEdit {\n\teditIndex: number;\n\tmatchIndex: number;\n\tmatchLength: number;\n\tnewText: string;\n}\n\ntype TextReplacement = Pick<MatchedEdit, \"matchIndex\" | \"matchLength\" | \"newText\">;\n\nfunction getLineSpans(content: string): LineSpan[] {\n\tlet offset = 0;\n\treturn splitLinesWithEndings(content).map((line) => {\n\t\tconst span = { start: offset, end: offset + line.length };\n\t\toffset = span.end;\n\t\treturn span;\n\t});\n}\n\nfunction getReplacementLineRange(lines: LineSpan[], replacement: TextReplacement) {\n\tconst replacementStart = replacement.matchIndex;\n\tconst replacementEnd = replacement.matchIndex + replacement.matchLength;\n\n\tlet startLine = -1;\n\tfor (let i = 0; i < lines.length; i++) {\n\t\tconst line = lines[i];\n\t\tif (replacementStart >= line.start && replacementStart < line.end) {\n\t\t\tstartLine = i;\n\t\t\tbreak;\n\t\t}\n\t}\n\tif (startLine === -1) {\n\t\tthrow new Error(\"Replacement range is outside the base content.\");\n\t}\n\n\tlet endLine = startLine;\n\twhile (endLine < lines.length && lines[endLine].end < replacementEnd) {\n\t\tendLine++;\n\t}\n\tif (endLine >= lines.length) {\n\t\tthrow new Error(\"Replacement range is outside the base content.\");\n\t}\n\n\treturn { startLine, endLine: endLine + 1 };\n}\n\nfunction applyReplacements(content: string, replacements: TextReplacement[], offset = 0): string {\n\tlet result = content;\n\tfor (let i = replacements.length - 1; i >= 0; i--) {\n\t\tconst replacement = replacements[i];\n\t\tconst matchIndex = replacement.matchIndex - offset;\n\t\tresult =\n\t\t\tresult.substring(0, matchIndex) + replacement.newText + result.substring(matchIndex + replacement.matchLength);\n\t}\n\treturn result;\n}\n\n/**\n * Apply replacements matched against `baseContent` to `originalContent` while\n * preserving unchanged line blocks from the original.\n *\n * This is useful when `baseContent` is a normalized view of the original. Each\n * replacement is widened to the lines it actually touches, those touched lines\n * are rewritten from the normalized base, and all other lines are copied back\n * from `originalContent`. The actual replacement ranges drive preservation so\n * duplicate normalized lines cannot be aligned to the wrong occurrence.\n */\nexport function applyReplacementsPreservingUnchangedLines(\n\toriginalContent: string,\n\tbaseContent: string,\n\treplacements: TextReplacement[],\n): string {\n\tconst originalLines = splitLinesWithEndings(originalContent);\n\tconst baseLines = getLineSpans(baseContent);\n\tif (originalLines.length !== baseLines.length) {\n\t\tthrow new Error(\"Cannot preserve unchanged lines because the base content has a different line count.\");\n\t}\n\n\tconst groups: Array<{ startLine: number; endLine: number; replacements: TextReplacement[] }> = [];\n\tconst sortedReplacements = [...replacements].sort((a, b) => a.matchIndex - b.matchIndex);\n\tfor (const replacement of sortedReplacements) {\n\t\tconst range = getReplacementLineRange(baseLines, replacement);\n\t\tconst current = groups[groups.length - 1];\n\t\tif (current && range.startLine < current.endLine) {\n\t\t\tcurrent.endLine = Math.max(current.endLine, range.endLine);\n\t\t\tcurrent.replacements.push(replacement);\n\t\t\tcontinue;\n\t\t}\n\t\tgroups.push({ ...range, replacements: [replacement] });\n\t}\n\n\tlet originalLineIndex = 0;\n\tlet result = \"\";\n\tfor (const group of groups) {\n\t\tresult += originalLines.slice(originalLineIndex, group.startLine).join(\"\");\n\n\t\tconst groupStartOffset = baseLines[group.startLine].start;\n\t\tconst groupEndOffset = baseLines[group.endLine - 1].end;\n\t\tresult += applyReplacements(\n\t\t\tbaseContent.slice(groupStartOffset, groupEndOffset),\n\t\t\tgroup.replacements,\n\t\t\tgroupStartOffset,\n\t\t);\n\t\toriginalLineIndex = group.endLine;\n\t}\n\tresult += originalLines.slice(originalLineIndex).join(\"\");\n\n\treturn result;\n}\n\nexport interface FuzzyMatchResult {\n\t/** Whether a match was found */\n\tfound: boolean;\n\t/** The index where the match starts (in the content that should be used for replacement) */\n\tindex: number;\n\t/** Length of the matched text */\n\tmatchLength: number;\n\t/** Whether fuzzy matching was used (false = exact match) */\n\tusedFuzzyMatch: boolean;\n\t/**\n\t * The content to use for replacement operations.\n\t * When exact match: original content. When fuzzy match: normalized content.\n\t */\n\tcontentForReplacement: string;\n}\n\nexport interface Edit {\n\toldText: string;\n\tnewText: string;\n}\n\nexport interface AppliedEditsResult {\n\tbaseContent: string;\n\tnewContent: string;\n}\n\n/**\n * Find oldText in content, trying exact match first, then fuzzy match.\n * When fuzzy matching is used, the returned contentForReplacement is the\n * fuzzy-normalized version of the content (trailing whitespace stripped,\n * Unicode quotes/dashes normalized to ASCII).\n */\nexport function fuzzyFindText(content: string, oldText: string): FuzzyMatchResult {\n\t// Try exact match first\n\tconst exactIndex = content.indexOf(oldText);\n\tif (exactIndex !== -1) {\n\t\treturn {\n\t\t\tfound: true,\n\t\t\tindex: exactIndex,\n\t\t\tmatchLength: oldText.length,\n\t\t\tusedFuzzyMatch: false,\n\t\t\tcontentForReplacement: content,\n\t\t};\n\t}\n\n\t// Try fuzzy match - work entirely in normalized space\n\tconst fuzzyContent = normalizeForFuzzyMatch(content);\n\tconst fuzzyOldText = normalizeForFuzzyMatch(oldText);\n\tconst fuzzyIndex = fuzzyContent.indexOf(fuzzyOldText);\n\n\tif (fuzzyIndex === -1) {\n\t\treturn {\n\t\t\tfound: false,\n\t\t\tindex: -1,\n\t\t\tmatchLength: 0,\n\t\t\tusedFuzzyMatch: false,\n\t\t\tcontentForReplacement: content,\n\t\t};\n\t}\n\n\t// When fuzzy matching, return offsets in normalized space. Callers can use\n\t// the normalized content to compute replacements, then decide how much of\n\t// that normalized output should be written back.\n\treturn {\n\t\tfound: true,\n\t\tindex: fuzzyIndex,\n\t\tmatchLength: fuzzyOldText.length,\n\t\tusedFuzzyMatch: true,\n\t\tcontentForReplacement: fuzzyContent,\n\t};\n}\n\nfunction countOccurrences(content: string, oldText: string): number {\n\tconst fuzzyContent = normalizeForFuzzyMatch(content);\n\tconst fuzzyOldText = normalizeForFuzzyMatch(oldText);\n\treturn fuzzyContent.split(fuzzyOldText).length - 1;\n}\n\n/**\n * Explicit budgets for the advisory edit-failure diagnostics below. Diagnostics\n * are a best-effort hint, never an apply path, so every dimension of the scan\n * is bounded and the ordinary failure is returned untouched when a bound is\n * exceeded (spec 2026-09-01-tool-reliability-and-execution-budgets.md § 2).\n */\nexport const EDIT_DIAGNOSTIC_MAX_FILE_BYTES = 1_048_576;\nexport const EDIT_DIAGNOSTIC_MAX_TARGET_BYTES = 65_536;\nexport const EDIT_DIAGNOSTIC_MAX_CANDIDATES = 3;\nexport const EDIT_DIAGNOSTIC_MAX_SCAN_WINDOWS = 20_000;\nexport const EDIT_DIAGNOSTIC_MAX_OCCURRENCES = 5;\nexport const EDIT_DIAGNOSTIC_SNIPPET_LINE_CHARS = 160;\n\nconst EDIT_DIAGNOSTIC_MIN_SIMILARITY = 0.2;\nconst EDIT_DIAGNOSTIC_SCAN_BUDGET_MS = 50;\nconst EDIT_DIAGNOSTIC_MAX_OCCURRENCE_STEPS = 10_000;\n\nexport interface EditCandidateLocation {\n\t/** 1-based, inclusive. */\n\tstartLine: number;\n\t/** 1-based, inclusive. */\n\tendLine: number;\n\t/** Bigram Dice similarity against the failed target, rounded to two decimals. */\n\tsimilarity: number;\n\t/** Bounded snippet of the candidate source lines, each line-numbered. */\n\tsnippet: string;\n}\n\n/**\n * Advisory diagnostics attached to a failed edit match. These describe where a\n * target almost matched or where duplicates live; they are never a replacement\n * location and must never be applied.\n */\nexport interface EditFailureDiagnostics {\n\tkind: \"missing-match\" | \"duplicate-match\";\n\tcandidates: EditCandidateLocation[];\n\t/** 1-based source lines of up to EDIT_DIAGNOSTIC_MAX_OCCURRENCES duplicates. */\n\toccurrenceLines: number[];\n\tomittedOccurrences: number;\n\t/** True when the scan stopped at a work or time bound before finishing. */\n\tscanTruncated: boolean;\n\t/** Set when scanning was unsafe or oversized; no candidates are reported. */\n\tunavailableReason?: string;\n}\n\nfunction unavailableDiagnostics(kind: EditFailureDiagnostics[\"kind\"], reason: string): EditFailureDiagnostics {\n\treturn {\n\t\tkind,\n\t\tcandidates: [],\n\t\toccurrenceLines: [],\n\t\tomittedOccurrences: 0,\n\t\tscanTruncated: false,\n\t\tunavailableReason: reason,\n\t};\n}\n\nfunction isDiagnosticScannable(\n\tkind: EditFailureDiagnostics[\"kind\"],\n\tcontent: string,\n\ttarget: string,\n): EditFailureDiagnostics | undefined {\n\tif (Buffer.byteLength(content, \"utf-8\") > EDIT_DIAGNOSTIC_MAX_FILE_BYTES) {\n\t\treturn unavailableDiagnostics(\n\t\t\tkind,\n\t\t\t`advisory diagnostic scan skipped: file exceeds the ${EDIT_DIAGNOSTIC_MAX_FILE_BYTES}-byte diagnostic budget`,\n\t\t);\n\t}\n\tif (Buffer.byteLength(target, \"utf-8\") > EDIT_DIAGNOSTIC_MAX_TARGET_BYTES) {\n\t\treturn unavailableDiagnostics(\n\t\t\tkind,\n\t\t\t`advisory diagnostic scan skipped: oldText exceeds the ${EDIT_DIAGNOSTIC_MAX_TARGET_BYTES}-byte diagnostic budget`,\n\t\t);\n\t}\n\treturn undefined;\n}\n\nfunction bigrams(text: string): Set<string> {\n\tconst result = new Set<string>();\n\tfor (let i = 0; i < text.length - 1; i++) {\n\t\tresult.add(text.slice(i, i + 2));\n\t}\n\treturn result;\n}\n\nfunction diceSimilarity(a: Set<string>, b: Set<string>): number {\n\tif (a.size === 0 && b.size === 0) return 1;\n\tif (a.size === 0 || b.size === 0) return 0;\n\tlet intersection = 0;\n\tfor (const gram of a) {\n\t\tif (b.has(gram)) intersection++;\n\t}\n\treturn (2 * intersection) / (a.size + b.size);\n}\n\nfunction truncateSnippetLine(line: string): string {\n\tif (line.length <= EDIT_DIAGNOSTIC_SNIPPET_LINE_CHARS) return line;\n\treturn `${line.slice(0, EDIT_DIAGNOSTIC_SNIPPET_LINE_CHARS)}…`;\n}\n\nfunction buildSnippet(lines: string[], startLine: number, lineCount: number): string {\n\tconst shown = Math.min(lineCount, 5);\n\tconst parts: string[] = [];\n\tfor (let i = 0; i < shown; i++) {\n\t\tparts.push(`${startLine + i + 1} | ${truncateSnippetLine(lines[startLine + i] ?? \"\")}`);\n\t}\n\treturn parts.join(\"\\n\");\n}\n\n/**\n * Find the closest line windows to a failed target. Purely advisory: the result\n * names locations so the caller can retry with better context, and is never a\n * replacement specification.\n */\nfunction scanMissingMatchCandidates(content: string, target: string): EditFailureDiagnostics {\n\tconst blocked = isDiagnosticScannable(\"missing-match\", content, target);\n\tif (blocked) return blocked;\n\n\tconst lines = content.split(\"\\n\");\n\tconst windowSize = Math.max(1, target.split(\"\\n\").length);\n\tconst windowCount = lines.length - windowSize + 1;\n\tconst deadline = Date.now() + EDIT_DIAGNOSTIC_SCAN_BUDGET_MS;\n\tconst targetGrams = bigrams(target);\n\n\tconst best: Array<{ startLine: number; similarity: number }> = [];\n\tlet windowsScanned = 0;\n\tlet scanTruncated = false;\n\tfor (let start = 0; start < windowCount; start++) {\n\t\tif (windowsScanned >= EDIT_DIAGNOSTIC_MAX_SCAN_WINDOWS || (start % 512 === 0 && Date.now() > deadline)) {\n\t\t\tscanTruncated = true;\n\t\t\tbreak;\n\t\t}\n\t\twindowsScanned++;\n\t\tconst windowGrams = bigrams(lines.slice(start, start + windowSize).join(\"\\n\"));\n\t\tconst similarity = diceSimilarity(targetGrams, windowGrams);\n\t\tif (similarity < EDIT_DIAGNOSTIC_MIN_SIMILARITY) continue;\n\t\tif (best.length < EDIT_DIAGNOSTIC_MAX_CANDIDATES || similarity > best[best.length - 1].similarity) {\n\t\t\tbest.push({ startLine: start, similarity });\n\t\t\tbest.sort((a, b) => b.similarity - a.similarity);\n\t\t\tif (best.length > EDIT_DIAGNOSTIC_MAX_CANDIDATES) best.pop();\n\t\t}\n\t}\n\n\treturn {\n\t\tkind: \"missing-match\",\n\t\tcandidates: best.map((entry) => ({\n\t\t\tstartLine: entry.startLine + 1,\n\t\t\tendLine: entry.startLine + windowSize,\n\t\t\tsimilarity: Math.round(entry.similarity * 100) / 100,\n\t\t\tsnippet: buildSnippet(lines, entry.startLine, windowSize),\n\t\t})),\n\t\toccurrenceLines: [],\n\t\tomittedOccurrences: 0,\n\t\tscanTruncated,\n\t};\n}\n\nfunction lineNumberForOffset(lineStarts: number[], offset: number): number {\n\tlet low = 0;\n\tlet high = lineStarts.length - 1;\n\twhile (low < high) {\n\t\tconst mid = Math.ceil((low + high) / 2);\n\t\tif (lineStarts[mid] <= offset) low = mid;\n\t\telse high = mid - 1;\n\t}\n\treturn low + 1;\n}\n\n/** List bounded 1-based source lines for duplicate occurrences. Advisory only. */\nfunction scanDuplicateOccurrences(content: string, target: string): EditFailureDiagnostics {\n\tconst blocked = isDiagnosticScannable(\"duplicate-match\", content, target);\n\tif (blocked) return blocked;\n\n\tconst lines = content.split(\"\\n\");\n\tconst lineStarts: number[] = [];\n\tlet offset = 0;\n\tfor (const line of lines) {\n\t\tlineStarts.push(offset);\n\t\toffset += line.length + 1;\n\t}\n\n\tconst occurrenceLines: number[] = [];\n\tlet total = 0;\n\tlet truncated = false;\n\tlet searchFrom = 0;\n\twhile (target.length > 0) {\n\t\tconst index = content.indexOf(target, searchFrom);\n\t\tif (index === -1) break;\n\t\ttotal++;\n\t\tif (occurrenceLines.length < EDIT_DIAGNOSTIC_MAX_OCCURRENCES) {\n\t\t\toccurrenceLines.push(lineNumberForOffset(lineStarts, index));\n\t\t}\n\t\tsearchFrom = index + target.length;\n\t\tif (total >= EDIT_DIAGNOSTIC_MAX_OCCURRENCE_STEPS) {\n\t\t\ttruncated = true;\n\t\t\tbreak;\n\t\t}\n\t}\n\n\treturn {\n\t\tkind: \"duplicate-match\",\n\t\tcandidates: [],\n\t\toccurrenceLines,\n\t\tomittedOccurrences: Math.max(0, total - occurrenceLines.length),\n\t\tscanTruncated: truncated,\n\t};\n}\n\n/** Render advisory diagnostics as an error-message appendix. Empty when there is nothing to say. */\nexport function formatEditFailureDiagnostics(diagnostics: EditFailureDiagnostics | undefined): string {\n\tif (!diagnostics) return \"\";\n\tif (diagnostics.unavailableReason) {\n\t\treturn `\\n\\n(${diagnostics.unavailableReason}.)`;\n\t}\n\tconst sections: string[] = [];\n\tif (diagnostics.kind === \"duplicate-match\" && diagnostics.occurrenceLines.length > 0) {\n\t\tconst more = diagnostics.omittedOccurrences > 0 ? ` (+${diagnostics.omittedOccurrences} more)` : \"\";\n\t\tsections.push(`Advisory occurrence lines (not applied): ${diagnostics.occurrenceLines.join(\", \")}${more}`);\n\t}\n\tif (diagnostics.kind === \"missing-match\" && diagnostics.candidates.length > 0) {\n\t\tconst parts = [\"Advisory closest matches (not applied):\"];\n\t\tfor (const candidate of diagnostics.candidates) {\n\t\t\tparts.push(\n\t\t\t\t`  lines ${candidate.startLine}-${candidate.endLine} (${Math.round(candidate.similarity * 100)}% similar)`,\n\t\t\t);\n\t\t\tfor (const line of candidate.snippet.split(\"\\n\")) {\n\t\t\t\tparts.push(`    ${line}`);\n\t\t\t}\n\t\t}\n\t\tsections.push(parts.join(\"\\n\"));\n\t}\n\tif (diagnostics.scanTruncated) {\n\t\tsections.push(\n\t\t\t`(Advisory location scan truncated after ${EDIT_DIAGNOSTIC_MAX_SCAN_WINDOWS} windows; remaining locations were not examined.)`,\n\t\t);\n\t}\n\treturn sections.length > 0 ? `\\n\\n${sections.join(\"\\n\")}` : \"\";\n}\n\nfunction appendEditDiagnostics(error: Error, diagnostics: EditFailureDiagnostics): Error {\n\terror.message += formatEditFailureDiagnostics(diagnostics);\n\treturn error;\n}\n\nfunction getNotFoundError(path: string, editIndex: number, totalEdits: number): Error {\n\tif (totalEdits === 1) {\n\t\treturn new Error(\n\t\t\t`Could not find the exact text in ${path}. The old text must match exactly including all whitespace and newlines.`,\n\t\t);\n\t}\n\treturn new Error(\n\t\t`Could not find edits[${editIndex}] in ${path}. The oldText must match exactly including all whitespace and newlines.`,\n\t);\n}\n\nfunction getDuplicateError(path: string, editIndex: number, totalEdits: number, occurrences: number): Error {\n\tif (totalEdits === 1) {\n\t\treturn new Error(\n\t\t\t`Found ${occurrences} occurrences of the text in ${path}. The text must be unique. Please provide more context to make it unique.`,\n\t\t);\n\t}\n\treturn new Error(\n\t\t`Found ${occurrences} occurrences of edits[${editIndex}] in ${path}. Each oldText must be unique. Please provide more context to make it unique.`,\n\t);\n}\n\nfunction getEmptyOldTextError(path: string, editIndex: number, totalEdits: number): Error {\n\tif (totalEdits === 1) {\n\t\treturn new Error(`oldText must not be empty in ${path}.`);\n\t}\n\treturn new Error(`edits[${editIndex}].oldText must not be empty in ${path}.`);\n}\n\nfunction getNoChangeError(path: string, totalEdits: number): Error {\n\tif (totalEdits === 1) {\n\t\treturn new Error(\n\t\t\t`No changes made to ${path}. The replacement produced identical content. This might indicate an issue with special characters or the text not existing as expected.`,\n\t\t);\n\t}\n\treturn new Error(`No changes made to ${path}. The replacements produced identical content.`);\n}\n\n/**\n * Apply one or more exact-text replacements to LF-normalized content.\n *\n * All edits are matched against the same original content. Replacements are\n * then applied in reverse order so offsets remain stable. If any edit needs\n * fuzzy matching, the operation runs in fuzzy-normalized content space and then\n * overlays those line-level changes onto the original content so unchanged line\n * blocks keep their original bytes.\n */\nexport function applyEditsToNormalizedContent(\n\tnormalizedContent: string,\n\tedits: Edit[],\n\tpath: string,\n): AppliedEditsResult {\n\tconst normalizedEdits = edits.map((edit) => ({\n\t\toldText: normalizeToLF(edit.oldText),\n\t\tnewText: normalizeToLF(edit.newText),\n\t}));\n\n\tfor (let i = 0; i < normalizedEdits.length; i++) {\n\t\tif (normalizedEdits[i].oldText.length === 0) {\n\t\t\tthrow getEmptyOldTextError(path, i, normalizedEdits.length);\n\t\t}\n\t}\n\n\tconst initialMatches = normalizedEdits.map((edit) => fuzzyFindText(normalizedContent, edit.oldText));\n\tconst usedFuzzyMatch = initialMatches.some((match) => match.usedFuzzyMatch);\n\tconst replacementBaseContent = usedFuzzyMatch ? normalizeForFuzzyMatch(normalizedContent) : normalizedContent;\n\n\tconst matchedEdits: MatchedEdit[] = [];\n\tfor (let i = 0; i < normalizedEdits.length; i++) {\n\t\tconst edit = normalizedEdits[i];\n\t\tconst matchResult = fuzzyFindText(replacementBaseContent, edit.oldText);\n\t\tif (!matchResult.found) {\n\t\t\t// Advisory only: candidates name near-miss locations but never supply a\n\t\t\t// replacement. Matching above remains the only apply path.\n\t\t\tconst diagnosticTarget = usedFuzzyMatch ? normalizeForFuzzyMatch(edit.oldText) : edit.oldText;\n\t\t\tthrow appendEditDiagnostics(\n\t\t\t\tgetNotFoundError(path, i, normalizedEdits.length),\n\t\t\t\tscanMissingMatchCandidates(replacementBaseContent, diagnosticTarget),\n\t\t\t);\n\t\t}\n\n\t\tconst occurrences = countOccurrences(replacementBaseContent, edit.oldText);\n\t\tif (occurrences > 1) {\n\t\t\tconst diagnosticTarget = usedFuzzyMatch ? normalizeForFuzzyMatch(edit.oldText) : edit.oldText;\n\t\t\tthrow appendEditDiagnostics(\n\t\t\t\tgetDuplicateError(path, i, normalizedEdits.length, occurrences),\n\t\t\t\tscanDuplicateOccurrences(replacementBaseContent, diagnosticTarget),\n\t\t\t);\n\t\t}\n\n\t\tmatchedEdits.push({\n\t\t\teditIndex: i,\n\t\t\tmatchIndex: matchResult.index,\n\t\t\tmatchLength: matchResult.matchLength,\n\t\t\tnewText: edit.newText,\n\t\t});\n\t}\n\n\tmatchedEdits.sort((a, b) => a.matchIndex - b.matchIndex);\n\tfor (let i = 1; i < matchedEdits.length; i++) {\n\t\tconst previous = matchedEdits[i - 1];\n\t\tconst current = matchedEdits[i];\n\t\tif (previous.matchIndex + previous.matchLength > current.matchIndex) {\n\t\t\tthrow new Error(\n\t\t\t\t`edits[${previous.editIndex}] and edits[${current.editIndex}] overlap in ${path}. Merge them into one edit or target disjoint regions.`,\n\t\t\t);\n\t\t}\n\t}\n\n\tconst baseContent = normalizedContent;\n\tconst newContent = usedFuzzyMatch\n\t\t? applyReplacementsPreservingUnchangedLines(normalizedContent, replacementBaseContent, matchedEdits)\n\t\t: applyReplacements(replacementBaseContent, matchedEdits);\n\n\tif (baseContent === newContent) {\n\t\tthrow getNoChangeError(path, normalizedEdits.length);\n\t}\n\n\treturn { baseContent, newContent };\n}\n\n/** Generate a standard unified patch. */\nexport function generateUnifiedPatch(path: string, oldContent: string, newContent: string, contextLines = 4): string {\n\treturn Diff.createTwoFilesPatch(path, path, oldContent, newContent, undefined, undefined, {\n\t\tcontext: contextLines,\n\t\theaderOptions: Diff.FILE_HEADERS_ONLY,\n\t});\n}\n\n/**\n * Generate a display-oriented diff string with line numbers and context.\n * Returns both the diff string and the first changed line number (in the new file).\n */\nexport function generateDiffString(\n\toldContent: string,\n\tnewContent: string,\n\tcontextLines = 4,\n): { diff: string; firstChangedLine: number | undefined } {\n\tconst parts = Diff.diffLines(oldContent, newContent);\n\tconst output: string[] = [];\n\n\tconst oldLines = oldContent.split(\"\\n\");\n\tconst newLines = newContent.split(\"\\n\");\n\tconst maxLineNum = Math.max(oldLines.length, newLines.length);\n\tconst lineNumWidth = String(maxLineNum).length;\n\n\tlet oldLineNum = 1;\n\tlet newLineNum = 1;\n\tlet lastWasChange = false;\n\tlet firstChangedLine: number | undefined;\n\n\tfor (let i = 0; i < parts.length; i++) {\n\t\tconst part = parts[i];\n\t\tconst raw = part.value.split(\"\\n\");\n\t\tif (raw[raw.length - 1] === \"\") {\n\t\t\traw.pop();\n\t\t}\n\n\t\tif (part.added || part.removed) {\n\t\t\t// Capture the first changed line (in the new file)\n\t\t\tif (firstChangedLine === undefined) {\n\t\t\t\tfirstChangedLine = newLineNum;\n\t\t\t}\n\n\t\t\t// Show the change\n\t\t\tfor (const line of raw) {\n\t\t\t\tif (part.added) {\n\t\t\t\t\tconst lineNum = String(newLineNum).padStart(lineNumWidth, \" \");\n\t\t\t\t\toutput.push(`+${lineNum} ${line}`);\n\t\t\t\t\tnewLineNum++;\n\t\t\t\t} else {\n\t\t\t\t\t// removed\n\t\t\t\t\tconst lineNum = String(oldLineNum).padStart(lineNumWidth, \" \");\n\t\t\t\t\toutput.push(`-${lineNum} ${line}`);\n\t\t\t\t\toldLineNum++;\n\t\t\t\t}\n\t\t\t}\n\t\t\tlastWasChange = true;\n\t\t} else {\n\t\t\t// Context lines - only show a few before/after changes\n\t\t\tconst nextPartIsChange = i < parts.length - 1 && (parts[i + 1].added || parts[i + 1].removed);\n\t\t\tconst hasLeadingChange = lastWasChange;\n\t\t\tconst hasTrailingChange = nextPartIsChange;\n\n\t\t\tif (hasLeadingChange && hasTrailingChange) {\n\t\t\t\tif (raw.length <= contextLines * 2) {\n\t\t\t\t\tfor (const line of raw) {\n\t\t\t\t\t\tconst lineNum = String(oldLineNum).padStart(lineNumWidth, \" \");\n\t\t\t\t\t\toutput.push(` ${lineNum} ${line}`);\n\t\t\t\t\t\toldLineNum++;\n\t\t\t\t\t\tnewLineNum++;\n\t\t\t\t\t}\n\t\t\t\t} else {\n\t\t\t\t\tconst leadingLines = raw.slice(0, contextLines);\n\t\t\t\t\tconst trailingLines = raw.slice(raw.length - contextLines);\n\t\t\t\t\tconst skippedLines = raw.length - leadingLines.length - trailingLines.length;\n\n\t\t\t\t\tfor (const line of leadingLines) {\n\t\t\t\t\t\tconst lineNum = String(oldLineNum).padStart(lineNumWidth, \" \");\n\t\t\t\t\t\toutput.push(` ${lineNum} ${line}`);\n\t\t\t\t\t\toldLineNum++;\n\t\t\t\t\t\tnewLineNum++;\n\t\t\t\t\t}\n\n\t\t\t\t\toutput.push(` ${\"\".padStart(lineNumWidth, \" \")} ...`);\n\t\t\t\t\toldLineNum += skippedLines;\n\t\t\t\t\tnewLineNum += skippedLines;\n\n\t\t\t\t\tfor (const line of trailingLines) {\n\t\t\t\t\t\tconst lineNum = String(oldLineNum).padStart(lineNumWidth, \" \");\n\t\t\t\t\t\toutput.push(` ${lineNum} ${line}`);\n\t\t\t\t\t\toldLineNum++;\n\t\t\t\t\t\tnewLineNum++;\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t} else if (hasLeadingChange) {\n\t\t\t\tconst shownLines = raw.slice(0, contextLines);\n\t\t\t\tconst skippedLines = raw.length - shownLines.length;\n\n\t\t\t\tfor (const line of shownLines) {\n\t\t\t\t\tconst lineNum = String(oldLineNum).padStart(lineNumWidth, \" \");\n\t\t\t\t\toutput.push(` ${lineNum} ${line}`);\n\t\t\t\t\toldLineNum++;\n\t\t\t\t\tnewLineNum++;\n\t\t\t\t}\n\n\t\t\t\tif (skippedLines > 0) {\n\t\t\t\t\toutput.push(` ${\"\".padStart(lineNumWidth, \" \")} ...`);\n\t\t\t\t\toldLineNum += skippedLines;\n\t\t\t\t\tnewLineNum += skippedLines;\n\t\t\t\t}\n\t\t\t} else if (hasTrailingChange) {\n\t\t\t\tconst skippedLines = Math.max(0, raw.length - contextLines);\n\t\t\t\tif (skippedLines > 0) {\n\t\t\t\t\toutput.push(` ${\"\".padStart(lineNumWidth, \" \")} ...`);\n\t\t\t\t\toldLineNum += skippedLines;\n\t\t\t\t\tnewLineNum += skippedLines;\n\t\t\t\t}\n\n\t\t\t\tfor (const line of raw.slice(skippedLines)) {\n\t\t\t\t\tconst lineNum = String(oldLineNum).padStart(lineNumWidth, \" \");\n\t\t\t\t\toutput.push(` ${lineNum} ${line}`);\n\t\t\t\t\toldLineNum++;\n\t\t\t\t\tnewLineNum++;\n\t\t\t\t}\n\t\t\t} else {\n\t\t\t\t// Skip these context lines entirely\n\t\t\t\toldLineNum += raw.length;\n\t\t\t\tnewLineNum += raw.length;\n\t\t\t}\n\n\t\t\tlastWasChange = false;\n\t\t}\n\t}\n\n\treturn { diff: output.join(\"\\n\"), firstChangedLine };\n}\n\nexport interface EditDiffResult {\n\tdiff: string;\n\tfirstChangedLine: number | undefined;\n}\n\nexport interface EditDiffError {\n\terror: string;\n}\n\n/**\n * Compute the diff for one or more edit operations without applying them.\n * Used for preview rendering in the TUI before the tool executes.\n */\nexport async function computeEditsDiff(\n\tpath: string,\n\tedits: Edit[],\n\tcwd: string,\n): Promise<EditDiffResult | EditDiffError> {\n\tconst absolutePath = resolveToCwd(path, cwd);\n\n\ttry {\n\t\t// Check if file exists and is readable\n\t\ttry {\n\t\t\tawait access(absolutePath, constants.R_OK);\n\t\t} catch (error: unknown) {\n\t\t\tconst errorMessage = error instanceof Error && \"code\" in error ? `Error code: ${error.code}` : String(error);\n\t\t\treturn { error: `Could not edit file: ${path}. ${errorMessage}.` };\n\t\t}\n\n\t\t// Read the file\n\t\tconst rawContent = await readFile(absolutePath, \"utf-8\");\n\t\treturn computeEditsDiffFromContent(path, rawContent, edits);\n\t} catch (err) {\n\t\treturn { error: err instanceof Error ? err.message : String(err) };\n\t}\n}\n\n/**\n * The half of `computeEditsDiff` that does not choose which bytes to read.\n *\n * The permission preview must describe the operation the gate authorized rather\n * than whatever the pathname resolves to a second time, so it supplies content\n * read through the prepared operation and calls this (ADR 0029).\n */\nexport function computeEditsDiffFromContent(\n\tpath: string,\n\trawContent: string,\n\tedits: Edit[],\n): EditDiffResult | EditDiffError {\n\ttry {\n\t\t// Strip BOM before matching (LLM won't include invisible BOM in oldText)\n\t\tconst { text: content } = splitBom(rawContent);\n\t\tconst normalizedContent = normalizeToLF(content);\n\t\tconst { baseContent, newContent } = applyEditsToNormalizedContent(normalizedContent, edits, path);\n\t\treturn generateDiffString(baseContent, newContent);\n\t} catch (err) {\n\t\treturn { error: err instanceof Error ? err.message : String(err) };\n\t}\n}\n\n/**\n * Compute the diff for a single edit operation without applying it.\n * Kept as a convenience wrapper for single-edit callers.\n */\nexport async function computeEditDiff(\n\tpath: string,\n\toldText: string,\n\tnewText: string,\n\tcwd: string,\n): Promise<EditDiffResult | EditDiffError> {\n\treturn computeEditsDiff(path, [{ oldText, newText }], cwd);\n}\n"]}

package/dist/core/tools/edit-diff.js

@@ -179,6 +179,200 @@ function countOccurrences(content, oldText) {
     const fuzzyOldText = normalizeForFuzzyMatch(oldText);
     return fuzzyContent.split(fuzzyOldText).length - 1;
 }
+/**
+ * Explicit budgets for the advisory edit-failure diagnostics below. Diagnostics
+ * are a best-effort hint, never an apply path, so every dimension of the scan
+ * is bounded and the ordinary failure is returned untouched when a bound is
+ * exceeded (spec 2026-09-01-tool-reliability-and-execution-budgets.md § 2).
+ */
+export const EDIT_DIAGNOSTIC_MAX_FILE_BYTES = 1_048_576;
+export const EDIT_DIAGNOSTIC_MAX_TARGET_BYTES = 65_536;
+export const EDIT_DIAGNOSTIC_MAX_CANDIDATES = 3;
+export const EDIT_DIAGNOSTIC_MAX_SCAN_WINDOWS = 20_000;
+export const EDIT_DIAGNOSTIC_MAX_OCCURRENCES = 5;
+export const EDIT_DIAGNOSTIC_SNIPPET_LINE_CHARS = 160;
+const EDIT_DIAGNOSTIC_MIN_SIMILARITY = 0.2;
+const EDIT_DIAGNOSTIC_SCAN_BUDGET_MS = 50;
+const EDIT_DIAGNOSTIC_MAX_OCCURRENCE_STEPS = 10_000;
+function unavailableDiagnostics(kind, reason) {
+    return {
+        kind,
+        candidates: [],
+        occurrenceLines: [],
+        omittedOccurrences: 0,
+        scanTruncated: false,
+        unavailableReason: reason,
+    };
+}
+function isDiagnosticScannable(kind, content, target) {
+    if (Buffer.byteLength(content, "utf-8") > EDIT_DIAGNOSTIC_MAX_FILE_BYTES) {
+        return unavailableDiagnostics(kind, `advisory diagnostic scan skipped: file exceeds the ${EDIT_DIAGNOSTIC_MAX_FILE_BYTES}-byte diagnostic budget`);
+    }
+    if (Buffer.byteLength(target, "utf-8") > EDIT_DIAGNOSTIC_MAX_TARGET_BYTES) {
+        return unavailableDiagnostics(kind, `advisory diagnostic scan skipped: oldText exceeds the ${EDIT_DIAGNOSTIC_MAX_TARGET_BYTES}-byte diagnostic budget`);
+    }
+    return undefined;
+}
+function bigrams(text) {
+    const result = new Set();
+    for (let i = 0; i < text.length - 1; i++) {
+        result.add(text.slice(i, i + 2));
+    }
+    return result;
+}
+function diceSimilarity(a, b) {
+    if (a.size === 0 && b.size === 0)
+        return 1;
+    if (a.size === 0 || b.size === 0)
+        return 0;
+    let intersection = 0;
+    for (const gram of a) {
+        if (b.has(gram))
+            intersection++;
+    }
+    return (2 * intersection) / (a.size + b.size);
+}
+function truncateSnippetLine(line) {
+    if (line.length <= EDIT_DIAGNOSTIC_SNIPPET_LINE_CHARS)
+        return line;
+    return `${line.slice(0, EDIT_DIAGNOSTIC_SNIPPET_LINE_CHARS)}…`;
+}
+function buildSnippet(lines, startLine, lineCount) {
+    const shown = Math.min(lineCount, 5);
+    const parts = [];
+    for (let i = 0; i < shown; i++) {
+        parts.push(`${startLine + i + 1} | ${truncateSnippetLine(lines[startLine + i] ?? "")}`);
+    }
+    return parts.join("\n");
+}
+/**
+ * Find the closest line windows to a failed target. Purely advisory: the result
+ * names locations so the caller can retry with better context, and is never a
+ * replacement specification.
+ */
+function scanMissingMatchCandidates(content, target) {
+    const blocked = isDiagnosticScannable("missing-match", content, target);
+    if (blocked)
+        return blocked;
+    const lines = content.split("\n");
+    const windowSize = Math.max(1, target.split("\n").length);
+    const windowCount = lines.length - windowSize + 1;
+    const deadline = Date.now() + EDIT_DIAGNOSTIC_SCAN_BUDGET_MS;
+    const targetGrams = bigrams(target);
+    const best = [];
+    let windowsScanned = 0;
+    let scanTruncated = false;
+    for (let start = 0; start < windowCount; start++) {
+        if (windowsScanned >= EDIT_DIAGNOSTIC_MAX_SCAN_WINDOWS || (start % 512 === 0 && Date.now() > deadline)) {
+            scanTruncated = true;
+            break;
+        }
+        windowsScanned++;
+        const windowGrams = bigrams(lines.slice(start, start + windowSize).join("\n"));
+        const similarity = diceSimilarity(targetGrams, windowGrams);
+        if (similarity < EDIT_DIAGNOSTIC_MIN_SIMILARITY)
+            continue;
+        if (best.length < EDIT_DIAGNOSTIC_MAX_CANDIDATES || similarity > best[best.length - 1].similarity) {
+            best.push({ startLine: start, similarity });
+            best.sort((a, b) => b.similarity - a.similarity);
+            if (best.length > EDIT_DIAGNOSTIC_MAX_CANDIDATES)
+                best.pop();
+        }
+    }
+    return {
+        kind: "missing-match",
+        candidates: best.map((entry) => ({
+            startLine: entry.startLine + 1,
+            endLine: entry.startLine + windowSize,
+            similarity: Math.round(entry.similarity * 100) / 100,
+            snippet: buildSnippet(lines, entry.startLine, windowSize),
+        })),
+        occurrenceLines: [],
+        omittedOccurrences: 0,
+        scanTruncated,
+    };
+}
+function lineNumberForOffset(lineStarts, offset) {
+    let low = 0;
+    let high = lineStarts.length - 1;
+    while (low < high) {
+        const mid = Math.ceil((low + high) / 2);
+        if (lineStarts[mid] <= offset)
+            low = mid;
+        else
+            high = mid - 1;
+    }
+    return low + 1;
+}
+/** List bounded 1-based source lines for duplicate occurrences. Advisory only. */
+function scanDuplicateOccurrences(content, target) {
+    const blocked = isDiagnosticScannable("duplicate-match", content, target);
+    if (blocked)
+        return blocked;
+    const lines = content.split("\n");
+    const lineStarts = [];
+    let offset = 0;
+    for (const line of lines) {
+        lineStarts.push(offset);
+        offset += line.length + 1;
+    }
+    const occurrenceLines = [];
+    let total = 0;
+    let truncated = false;
+    let searchFrom = 0;
+    while (target.length > 0) {
+        const index = content.indexOf(target, searchFrom);
+        if (index === -1)
+            break;
+        total++;
+        if (occurrenceLines.length < EDIT_DIAGNOSTIC_MAX_OCCURRENCES) {
+            occurrenceLines.push(lineNumberForOffset(lineStarts, index));
+        }
+        searchFrom = index + target.length;
+        if (total >= EDIT_DIAGNOSTIC_MAX_OCCURRENCE_STEPS) {
+            truncated = true;
+            break;
+        }
+    }
+    return {
+        kind: "duplicate-match",
+        candidates: [],
+        occurrenceLines,
+        omittedOccurrences: Math.max(0, total - occurrenceLines.length),
+        scanTruncated: truncated,
+    };
+}
+/** Render advisory diagnostics as an error-message appendix. Empty when there is nothing to say. */
+export function formatEditFailureDiagnostics(diagnostics) {
+    if (!diagnostics)
+        return "";
+    if (diagnostics.unavailableReason) {
+        return `\n\n(${diagnostics.unavailableReason}.)`;
+    }
+    const sections = [];
+    if (diagnostics.kind === "duplicate-match" && diagnostics.occurrenceLines.length > 0) {
+        const more = diagnostics.omittedOccurrences > 0 ? ` (+${diagnostics.omittedOccurrences} more)` : "";
+        sections.push(`Advisory occurrence lines (not applied): ${diagnostics.occurrenceLines.join(", ")}${more}`);
+    }
+    if (diagnostics.kind === "missing-match" && diagnostics.candidates.length > 0) {
+        const parts = ["Advisory closest matches (not applied):"];
+        for (const candidate of diagnostics.candidates) {
+            parts.push(`  lines ${candidate.startLine}-${candidate.endLine} (${Math.round(candidate.similarity * 100)}% similar)`);
+            for (const line of candidate.snippet.split("\n")) {
+                parts.push(`    ${line}`);
+            }
+        }
+        sections.push(parts.join("\n"));
+    }
+    if (diagnostics.scanTruncated) {
+        sections.push(`(Advisory location scan truncated after ${EDIT_DIAGNOSTIC_MAX_SCAN_WINDOWS} windows; remaining locations were not examined.)`);
+    }
+    return sections.length > 0 ? `\n\n${sections.join("\n")}` : "";
+}
+function appendEditDiagnostics(error, diagnostics) {
+    error.message += formatEditFailureDiagnostics(diagnostics);
+    return error;
+}
 function getNotFoundError(path, editIndex, totalEdits) {
     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.`);
@@ -230,11 +424,15 @@ export function applyEditsToNormalizedContent(normalizedContent, edits, path) {
         const edit = normalizedEdits[i];
         const matchResult = fuzzyFindText(replacementBaseContent, edit.oldText);
         if (!matchResult.found) {
-            throw getNotFoundError(path, i, normalizedEdits.length);
+            // Advisory only: candidates name near-miss locations but never supply a
+            // replacement. Matching above remains the only apply path.
+            const diagnosticTarget = usedFuzzyMatch ? normalizeForFuzzyMatch(edit.oldText) : edit.oldText;
+            throw appendEditDiagnostics(getNotFoundError(path, i, normalizedEdits.length), scanMissingMatchCandidates(replacementBaseContent, diagnosticTarget));
         }
         const occurrences = countOccurrences(replacementBaseContent, edit.oldText);
         if (occurrences > 1) {
-            throw getDuplicateError(path, i, normalizedEdits.length, occurrences);
+            const diagnosticTarget = usedFuzzyMatch ? normalizeForFuzzyMatch(edit.oldText) : edit.oldText;
+            throw appendEditDiagnostics(getDuplicateError(path, i, normalizedEdits.length, occurrences), scanDuplicateOccurrences(replacementBaseContent, diagnosticTarget));
         }
         matchedEdits.push({
             editIndex: i,
@@ -400,11 +598,25 @@ export async function computeEditsDiff(path, edits, cwd) {
         }
         // Read the file
         const rawContent = await readFile(absolutePath, "utf-8");
+        return computeEditsDiffFromContent(path, rawContent, edits);
+    }
+    catch (err) {
+        return { error: err instanceof Error ? err.message : String(err) };
+    }
+}
+/**
+ * The half of `computeEditsDiff` that does not choose which bytes to read.
+ *
+ * The permission preview must describe the operation the gate authorized rather
+ * than whatever the pathname resolves to a second time, so it supplies content
+ * read through the prepared operation and calls this (ADR 0029).
+ */
+export function computeEditsDiffFromContent(path, rawContent, edits) {
+    try {
         // Strip BOM before matching (LLM won't include invisible BOM in oldText)
         const { text: content } = splitBom(rawContent);
         const normalizedContent = normalizeToLF(content);
         const { baseContent, newContent } = applyEditsToNormalizedContent(normalizedContent, edits, path);
-        // Generate the diff
         return generateDiffString(baseContent, newContent);
     }
     catch (err) {