@khanhicetea/pi-better-tool 0.1.0

package/src/diagnostics.ts

@@ -0,0 +1,350 @@
+/**
+ * Failure diagnostics for the better edit tool.
+ *
+ * Turns structured matching failures into recovery context the model can act
+ * on immediately, without re-reading the file:
+ *
+ * - ambiguous oldText → every occurrence's line number plus the *minimal*
+ *   prefix/suffix context expansion that makes that occurrence unique,
+ *   rendered as a ready-to-use oldText snippet
+ * - not-found oldText  → the closest matching region (fuzzy line similarity),
+ *   a per-line comparison, and the exact file bytes to retry with
+ */
+
+import type { EditFailure, EditOp, LineRange } from "./apply.ts";
+import { normalizeEdits } from "./apply.ts";
+import { findClosestRegion, lineSimilarity, probeMatchCauses } from "./similarity.ts";
+import {
+	countFuzzyOccurrences,
+	getLineSpans,
+	lineAt,
+	normalizeForFuzzyMatch,
+	type LineSpan,
+} from "./text.ts";
+
+/** Skip expensive diagnostics for huge files; the plain error still works. */
+const MAX_CONTENT_FOR_DIAGNOSTICS = 2_000_000;
+/** Max total context lines tried when growing an occurrence to uniqueness. */
+const MAX_TOTAL_CONTEXT_LINES = 12;
+/** Occurrences listed with line numbers. */
+const MAX_LISTED_OCCURRENCES = 8;
+/** Occurrences that get a ready-to-use disambiguation snippet. */
+const MAX_SNIPPET_OCCURRENCES = 3;
+/** Max lines shown inside a snippet. */
+const MAX_SNIPPET_LINES = 60;
+/** Max non-equal alignment ops rendered. */
+const MAX_DIFF_OPS_SHOWN = 12;
+
+export interface Expansion {
+	/** Whole lines of prefix context included. */
+	prefixLines: number;
+	/** Whole lines of suffix context included. */
+	suffixLines: number;
+	/** Exact file bytes to use as the new oldText. */
+	text: string;
+	startLine: number;
+	endLine: number;
+}
+
+export interface FormatFailureOptions {
+	path: string;
+	/** LF-normalized, BOM-stripped file content. */
+	normalizedContent: string;
+	/** Raw edits as provided by the model. */
+	edits: EditOp[];
+	failure: EditFailure;
+}
+
+export function formatEditFailure(opts: FormatFailureOptions): string {
+	const { path, normalizedContent, edits, failure } = opts;
+	const total = edits.length;
+
+	switch (failure.kind) {
+		case "empty-old-text": {
+			return total === 1
+				? `oldText must not be empty in ${path}.`
+				: `edits[${failure.editIndex}].oldText must not be empty in ${path}.`;
+		}
+
+		case "not-found": {
+			const head =
+				total === 1
+					? `Could not find the exact text in ${path}. The old text must match exactly including all whitespace and newlines.`
+					: `Could not find edits[${failure.editIndex}] in ${path}. The oldText must match exactly including all whitespace and newlines.`;
+			const normalized = normalizeEdits(edits)[failure.editIndex];
+			const body =
+				normalizedContent.length <= MAX_CONTENT_FOR_DIAGNOSTICS
+					? formatNotFound(opts, normalized.oldText)
+					: "File is too large for closest-match diagnostics; read the relevant region and retry.";
+			return `${head}\n\n${body}\n\nNo changes were written — the file was not modified.`;
+		}
+
+		case "ambiguous": {
+			const head =
+				total === 1
+					? `Found ${failure.occurrenceOffsets.length} occurrences of the text in ${path}. The text must be unique. Please provide more context to make it unique.`
+					: `Found ${failure.occurrenceOffsets.length} occurrences of edits[${failure.editIndex}] in ${path}. Each oldText must be unique. Please provide more context to make it unique.`;
+			const body =
+				normalizedContent.length <= MAX_CONTENT_FOR_DIAGNOSTICS
+					? formatAmbiguous(opts, failure)
+					: "File is too large for disambiguation diagnostics; read the relevant region and retry with more context.";
+			return `${head}\n\n${body}\n\nNo changes were written — the file was not modified.`;
+		}
+
+		case "overlap": {
+			const { firstEditIndex, secondEditIndex, firstRange, secondRange } = failure;
+			return `edits[${firstEditIndex}] and edits[${secondEditIndex}] overlap in ${path} (edits[${firstEditIndex}] covers lines ${firstRange.start}-${firstRange.end}, edits[${secondEditIndex}] covers lines ${secondRange.start}-${secondRange.end}). Merge them into one edit or target disjoint regions.`;
+		}
+
+		case "no-change": {
+			return total === 1
+				? `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.`
+				: `No changes made to ${path}. The replacements produced identical content.`;
+		}
+	}
+}
+
+// ---------------------------------------------------------------------------
+// Ambiguous: per-occurrence minimal prefix/suffix expansion
+// ---------------------------------------------------------------------------
+
+function formatAmbiguous(opts: FormatFailureOptions, failure: Extract<EditFailure, { kind: "ambiguous" }>): string {
+	const { normalizedContent } = opts;
+	const oldText = normalizeEdits(opts.edits)[failure.editIndex].oldText;
+	const fuzzyContent = normalizeForFuzzyMatch(normalizedContent);
+	const fuzzyOld = normalizeForFuzzyMatch(oldText);
+	const fuzzySpans = getLineSpans(fuzzyContent);
+	const spans = getLineSpans(normalizedContent);
+
+	const lines: string[] = [];
+	const listed = failure.occurrenceOffsets.slice(0, MAX_LISTED_OCCURRENCES);
+	lines.push("Occurrences:");
+	listed.forEach((offset, i) => {
+		const range = rangeFromOffset(fuzzySpans, offset, fuzzyOld.length);
+		lines.push(`  ${i + 1}. ${describeLines(range.start, range.end)}`);
+	});
+	if (failure.occurrenceOffsets.length > listed.length) {
+		lines.push(`  … and ${failure.occurrenceOffsets.length - listed.length} more`);
+	}
+	lines.push("");
+
+	lines.push(
+		"Retry with a disambiguated oldText: pick ONE occurrence below and reuse its snippet exactly. Each snippet already includes the minimum surrounding context that makes it unique:",
+	);
+
+	let shown = 0;
+	let missingExpansionNote = false;
+	for (let i = 0; i < listed.length && shown < MAX_SNIPPET_OCCURRENCES; i++) {
+		const offset = listed[i];
+		const range = rangeFromOffset(fuzzySpans, offset, fuzzyOld.length);
+		const expansion = findMinimalUniqueExpansion(normalizedContent, fuzzyContent, spans, range);
+		if (!expansion) {
+			missingExpansionNote = true;
+			continue;
+		}
+		shown++;
+		const where = `minimum context: ${plural(expansion.prefixLines, "line")} before, ${plural(expansion.suffixLines, "line")} after`;
+		lines.push("");
+		lines.push(`Occurrence ${i + 1} (${describeLines(range.start, range.end)}) — ${where}:`);
+		lines.push(...renderSnippet(expansion.text, `lines ${expansion.startLine}-${expansion.endLine}`));
+	}
+
+	if (missingExpansionNote) {
+		lines.push("");
+		lines.push(
+			`Some occurrences could not be auto-disambiguated within ${MAX_TOTAL_CONTEXT_LINES} context lines (likely near-identical repeated blocks). Extend oldText manually with distinguishing lines from the occurrences listed above.`,
+		);
+	}
+	if (shown === 0 && !missingExpansionNote) {
+		lines.push("", "Extend oldText with more surrounding lines until it matches exactly one location.");
+	}
+	lines.push("");
+	lines.push(
+		"Tip: use the snippet byte-for-byte as the new oldText, and make newText the snippet with your change applied (the snippet may span whole lines).",
+	);
+	return lines.join("\n");
+}
+
+function rangeFromOffset(spans: LineSpan[], offset: number, length: number): LineRange {
+	return { start: lineAt(spans, offset) + 1, end: lineAt(spans, offset + Math.max(1, length) - 1) + 1 };
+}
+
+function describeLines(start: number, end: number): string {
+	return start === end ? `line ${start}` : `lines ${start}-${end}`;
+}
+
+function plural(n: number, noun: string): string {
+	return `${n} ${noun}${n === 1 ? "" : "s"}`;
+}
+
+/**
+ * Find the smallest whole-line context expansion of the occurrence at `range`
+ * whose text occurs exactly once in the file (checked in fuzzy space, exactly
+ * like the matching engine's uniqueness rule).
+ *
+ * The search starts from the occurrence's own full lines (zero extra context),
+ * which also covers duplicates that share a line: whenever any anchored
+ * substring of those lines could be unique, the full lines are unique too.
+ */
+export function findMinimalUniqueExpansion(
+	content: string,
+	fuzzyContent: string,
+	spans: LineSpan[],
+	range: LineRange,
+): Expansion | null {
+	const totalLines = spans.length;
+	const maxPrefix = range.start - 1;
+	const maxSuffix = totalLines - range.end;
+
+	for (let total = 0; total <= MAX_TOTAL_CONTEXT_LINES; total++) {
+		for (let prefix = 0; prefix <= total; prefix++) {
+			const suffix = total - prefix;
+			if (prefix > maxPrefix || suffix > maxSuffix) continue;
+			const startLine = range.start - prefix;
+			const endLine = range.end + suffix;
+			const candidate = sliceLines(content, spans, startLine, endLine);
+			const verified = verifyUniqueSnippet(fuzzyContent, candidate);
+			if (verified) {
+				return {
+					prefixLines: prefix,
+					suffixLines: suffix,
+					text: verified,
+					startLine,
+					endLine,
+				};
+			}
+		}
+	}
+	return null;
+}
+
+function sliceLines(content: string, spans: LineSpan[], startLine: number, endLine: number): string {
+	return content.slice(spans[startLine - 1].start, spans[endLine - 1].end);
+}
+
+/**
+ * A snippet is handed to the model inside a fenced block; strip one trailing
+ * newline so copying is unambiguous, but only if the stripped version is still
+ * unique (a trailing newline can participate in uniqueness).
+ */
+function verifyUniqueSnippet(fuzzyContent: string, candidate: string): string | null {
+	const stripped = candidate.endsWith("\n") ? candidate.slice(0, -1) : candidate;
+	if (countFuzzyOccurrences(fuzzyContent, stripped) === 1) return stripped;
+	if (stripped !== candidate && countFuzzyOccurrences(fuzzyContent, candidate) === 1) return candidate;
+	return null;
+}
+
+// ---------------------------------------------------------------------------
+// Not-found: closest region + per-line comparison + exact bytes
+// ---------------------------------------------------------------------------
+
+function formatNotFound(opts: FormatFailureOptions, oldText: string): string {
+	const { normalizedContent } = opts;
+	const closest = findClosestRegion(normalizedContent, oldText);
+	const causes = probeMatchCauses(normalizedContent, oldText);
+
+	const lines: string[] = [];
+	if (closest) {
+		lines.push(
+			`Closest match in the file: ${describeLines(closest.startLine, closest.endLine)} (~${Math.round(closest.score * 100)}% line similarity${closest.truncated ? `, compared against the first ${closest.totalOldLines} lines of your oldText` : ""}).`,
+		);
+		const diffOps = closest.ops.filter((op) => op.type !== "equal");
+		if (diffOps.length === 0) {
+			// All compared lines passed the similarity threshold; surface the
+			// least-similar pair so small content drift (punctuation, extra
+			// characters) is not misreported as a pure whitespace issue.
+			let worst: { fileLine?: number; fileText?: string; oldLine?: number; oldText?: string; sim: number } | null = null;
+			for (const op of closest.ops) {
+				if (op.type !== "equal" || op.fileText === undefined || op.oldText === undefined) continue;
+				const sim = lineSimilarity(op.fileText, op.oldText);
+				if (!worst || sim < worst.sim) worst = { ...op, sim };
+			}
+			if (worst && worst.sim < 0.999) {
+				lines.push(
+					`No structural differences, but file line ${worst.fileLine} and your oldText line ${worst.oldLine} are only ~${Math.round(worst.sim * 100)}% similar:`,
+				);
+				lines.push(`    file:     ${truncateLine(worst.fileText ?? "")}`);
+				lines.push(`    oldText:  ${truncateLine(worst.oldText ?? "")}`);
+			} else {
+				lines.push(
+					"Every compared line matches individually — the mismatch is probably in line boundaries or trailing whitespace.",
+				);
+			}
+		} else {
+			lines.push(`Differences vs your oldText (${closest.equalCount} of ${closest.totalOldLines} compared lines match):`);
+			for (const op of diffOps.slice(0, MAX_DIFF_OPS_SHOWN)) {
+				if (op.type === "changed") {
+					lines.push(`  file line ${op.fileLine} differs from your oldText line ${op.oldLine}:`);
+					lines.push(`    file:     ${truncateLine(op.fileText ?? "")}`);
+					lines.push(`    oldText:  ${truncateLine(op.oldText ?? "")}`);
+				} else if (op.type === "file-only") {
+					lines.push(
+						`  file line ${op.fileLine} is missing from your oldText: ${truncateLine(op.fileText ?? "")}`,
+					);
+				} else {
+					lines.push(`  your oldText line ${op.oldLine} is not present in the file: ${truncateLine(op.oldText ?? "")}`);
+				}
+			}
+			if (diffOps.length > MAX_DIFF_OPS_SHOWN) {
+				lines.push(`  … ${diffOps.length - MAX_DIFF_OPS_SHOWN} more differing lines`);
+			}
+		}
+		lines.push("");
+		lines.push(
+			`Exact file content at ${describeLines(closest.startLine, closest.endLine)} — retry using this text as oldText (then apply your change to newText):`,
+		);
+		lines.push(...snippetFromLines(normalizedContent, closest.startLine, closest.endLine));
+	} else {
+		lines.push("No similar region was found in the file (best similarity below threshold).");
+		lines.push("If you expected this text to exist, read the file around the expected location and retry.");
+	}
+
+	if (causes.length > 0) {
+		lines.push("");
+		lines.push("Possible cause:");
+		for (const cause of causes) lines.push(`- ${cause}`);
+	}
+	return lines.join("\n");
+}
+
+function truncateLine(line: string): string {
+	const collapsed = line.replace(/\t/g, "→tab→");
+	return collapsed.length > 120 ? `${collapsed.slice(0, 117)}…` : collapsed;
+}
+
+// ---------------------------------------------------------------------------
+// Snippet rendering
+// ---------------------------------------------------------------------------
+
+function snippetFromLines(content: string, startLine: number, endLine: number): string[] {
+	const spans = getLineSpans(content);
+	const raw = content.slice(spans[startLine - 1].start, spans[endLine - 1].end);
+	const text = raw.endsWith("\n") ? raw.slice(0, -1) : raw;
+	return renderSnippet(text, `lines ${startLine}-${endLine}`);
+}
+
+function renderSnippet(text: string, where: string): string[] {
+	const fence = fenceFor(text);
+	const allLines = text.split("\n");
+	if (allLines.length <= MAX_SNIPPET_LINES) {
+		return [fence, text, fence];
+	}
+	const head = allLines.slice(0, MAX_SNIPPET_LINES - 10);
+	const tail = allLines.slice(-10);
+	const skipped = allLines.length - head.length - tail.length;
+	return [
+		fence,
+		...head,
+		`… (${skipped} middle lines snipped — see ${where}; re-read that range if you need the full text)`,
+		...tail,
+		fence,
+	];
+}
+
+/** Choose a fence longer than any backtick run inside the snippet. */
+export function fenceFor(text: string): string {
+	let max = 2;
+	const runs = text.match(/`{3,}/g) ?? [];
+	for (const run of runs) max = Math.max(max, run.length);
+	return "`".repeat(Math.max(3, max + 1));
+}

package/src/index.ts

@@ -0,0 +1,22 @@
+/**
+ * pi-better-tool — better built-in tools for the pi coding agent.
+ *
+ * Currently ships one override:
+ * - `edit` — identical matching semantics to the built-in edit tool, but
+ *   failures return recovery context (closest matching region, per-occurrence
+ *   minimal disambiguation snippets) so the agent can retry immediately
+ *   without re-reading the file.
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { registerBetterEditTool } from "./tool.ts";
+
+export { registerBetterEditTool, executeBetterEdit, prepareEditArguments, betterEditSchema } from "./tool.ts";
+export type { BetterEditInput } from "./tool.ts";
+export { formatEditFailure, findMinimalUniqueExpansion, fenceFor } from "./diagnostics.ts";
+export { analyzeEdits, applyAnalysis } from "./apply.ts";
+export type { EditFailure, EditOp, EditAnalysis } from "./apply.ts";
+
+export default function (pi: ExtensionAPI) {
+	registerBetterEditTool(pi);
+}

package/src/similarity.ts

@@ -0,0 +1,249 @@
+/**
+ * Fuzzy line similarity used to locate the region of the file that a failed
+ * oldText *almost* matched, so the tool can show the model the actual bytes
+ * instead of forcing a full re-read.
+ */
+
+import { toFuzzyLines } from "./text.ts";
+
+export interface AlignOp {
+	type: "equal" | "changed" | "file-only" | "old-only";
+	/** 1-based line number in the file (for equal/changed/file-only). */
+	fileLine?: number;
+	fileText?: string;
+	/** 1-based line number in the model-provided oldText. */
+	oldLine?: number;
+	oldText?: string;
+}
+
+export interface ClosestRegion {
+	startLine: number;
+	endLine: number;
+	/** 0..1 mean line similarity. */
+	score: number;
+	ops: AlignOp[];
+	equalCount: number;
+	totalOldLines: number;
+	/** oldText was truncated for comparison (very large oldText). */
+	truncated: boolean;
+}
+
+/** Dice coefficient over character bigrams; 1.0 for identical strings. */
+export function lineSimilarity(a: string, b: string): number {
+	if (a === b) return 1;
+	if (a.length < 2 || b.length < 2) return 0;
+	const gramsA = bigramCounts(a);
+	const gramsB = bigramCounts(b);
+	let overlap = 0;
+	let total = 0;
+	for (const count of gramsA.values()) total += count;
+	for (const count of gramsB.values()) total += count;
+	for (const [gram, countA] of gramsA) {
+		const countB = gramsB.get(gram);
+		if (countB) overlap += Math.min(countA, countB);
+	}
+	return (2 * overlap) / total;
+}
+
+function bigramCounts(s: string): Map<string, number> {
+	const counts = new Map<string, number>();
+	for (let i = 0; i + 1 < s.length; i++) {
+		const gram = s.slice(i, i + 2);
+		counts.set(gram, (counts.get(gram) ?? 0) + 1);
+	}
+	return counts;
+}
+
+const MAX_COMPARE_LINES = 300;
+const PREFILTER_FILE_LINES = 2000;
+const MIN_SCORE = 0.3;
+const MATCH_THRESHOLD = 0.75;
+
+/**
+ * Find the window of file lines most similar to oldText.
+ * Compares window sizes of len-1, len, len+1 so a single extra/missing line
+ * still lands the search on the right region.
+ */
+export function findClosestRegion(content: string, oldText: string): ClosestRegion | null {
+	const allQLines = toFuzzyLines(oldText);
+	const cLines = toFuzzyLines(content);
+	if (allQLines.length === 0 || cLines.length === 0) return null;
+
+	const truncated = allQLines.length > MAX_COMPARE_LINES;
+	const q = truncated ? allQLines.slice(0, MAX_COMPARE_LINES) : allQLines;
+	const L = q.length;
+
+	const sizes = [...new Set([L - 1, L, L + 1].filter((s) => s >= 1 && s <= cLines.length))];
+	const bigFile = cLines.length > PREFILTER_FILE_LINES;
+
+	let bestScore = -1;
+	let bestStart = -1;
+	let bestSize = L;
+
+	for (const w of sizes) {
+		for (let s = 0; s + w <= cLines.length; s++) {
+			if (bigFile && !prefilter(cLines, q, s, w, L)) continue;
+			const score = scoreWindow(cLines, q, s, w, L);
+			if (score > bestScore) {
+				bestScore = score;
+				bestStart = s;
+				bestSize = w;
+			}
+		}
+	}
+
+	if (bestStart < 0 || bestScore < MIN_SCORE) return null;
+
+	const windowLines = cLines.slice(bestStart, bestStart + bestSize);
+	const ops = alignLines(q, windowLines, bestStart);
+	const equalCount = ops.filter((op) => op.type === "equal").length;
+	return {
+		startLine: bestStart + 1,
+		endLine: bestStart + bestSize,
+		score: bestScore,
+		ops,
+		equalCount,
+		totalOldLines: L,
+		truncated,
+	};
+}
+
+function scoreWindow(cLines: string[], q: string[], start: number, w: number, L: number): number {
+	// Positional score: strict index-by-index pairing (handles indentation /
+	// trailing-whitespace drift).
+	const pairs = Math.min(L, w);
+	let positionalSum = 0;
+	for (let i = 0; i < pairs; i++) {
+		positionalSum += lineSimilarity(q[i], cLines[start + i]);
+	}
+	const positional = positionalSum / Math.max(L, w);
+
+	// Bag score: best match per oldText line anywhere in the window (handles a
+	// single inserted/removed line in the middle that breaks positional pairing).
+	let bagSum = 0;
+	for (let i = 0; i < L; i++) {
+		let best = 0;
+		for (let j = start; j < start + w; j++) {
+			const sim = lineSimilarity(q[i], cLines[j]);
+			if (sim > best) best = sim;
+			if (best === 1) break;
+		}
+		bagSum += best;
+	}
+	return Math.max(positional, (bagSum / L) * 0.95);
+}
+
+function prefilter(cLines: string[], q: string[], s: number, w: number, L: number): boolean {
+	const mid = Math.floor(L / 2);
+	const probes: Array<[number, number]> = [
+		[s, 0],
+		[s, L - 1],
+		[s, mid],
+		[s + w - 1, L - 1],
+		[s + w - 1, 0],
+		[s + w - 1, mid],
+		[s + Math.floor(w / 2), mid],
+	];
+	for (const [ci, qi] of probes) {
+		if (ci >= 0 && ci < cLines.length && qi >= 0 && qi < L) {
+			if (lineSimilarity(cLines[ci], q[qi]) >= 0.45) return true;
+		}
+	}
+	return false;
+}
+
+/**
+ * LCS-style alignment between oldText lines and the best window.
+ * Lines with similarity >= MATCH_THRESHOLD count as equal; adjacent
+ * old-only/file-only runs are merged into "changed" pairs.
+ */
+function alignLines(q: string[], w: string[], wOffset: number): AlignOp[] {
+	const n = q.length;
+	const m = w.length;
+	const dp: number[][] = Array.from({ length: n + 1 }, () => new Array<number>(m + 1).fill(0));
+	for (let i = n - 1; i >= 0; i--) {
+		for (let j = m - 1; j >= 0; j--) {
+			if (lineSimilarity(q[i], w[j]) >= MATCH_THRESHOLD) {
+				dp[i][j] = dp[i + 1][j + 1] + 1;
+			} else {
+				dp[i][j] = Math.max(dp[i + 1][j], dp[i][j + 1]);
+			}
+		}
+	}
+
+	const raw: AlignOp[] = [];
+	let i = 0;
+	let j = 0;
+	while (i < n && j < m) {
+		if (lineSimilarity(q[i], w[j]) >= MATCH_THRESHOLD) {
+			raw.push({ type: "equal", fileLine: wOffset + j + 1, fileText: w[j], oldLine: i + 1, oldText: q[i] });
+			i++;
+			j++;
+		} else if (dp[i + 1][j] > dp[i][j + 1]) {
+			// Strictly better to skip the oldText line; on ties prefer skipping
+			// the file line so inserted file lines surface as file-only ops.
+			raw.push({ type: "old-only", oldLine: i + 1, oldText: q[i] });
+			i++;
+		} else {
+			raw.push({ type: "file-only", fileLine: wOffset + j + 1, fileText: w[j] });
+			j++;
+		}
+	}
+	while (i < n) {
+		raw.push({ type: "old-only", oldLine: i + 1, oldText: q[i] });
+		i++;
+	}
+	while (j < m) {
+		raw.push({ type: "file-only", fileLine: wOffset + j + 1, fileText: w[j] });
+		j++;
+	}
+
+	// Merge adjacent old-only/file-only runs into pairwise "changed" ops.
+	const merged: AlignOp[] = [];
+	for (let k = 0; k < raw.length; k++) {
+		const op = raw[k];
+		if (op.type === "old-only") {
+			const next = raw[k + 1];
+			if (next && next.type === "file-only") {
+				merged.push({ type: "changed", fileLine: next.fileLine, fileText: next.fileText, oldLine: op.oldLine, oldText: op.oldText });
+				k++;
+				continue;
+			}
+			merged.push(op);
+			continue;
+		}
+		if (op.type === "file-only") {
+			const next = raw[k + 1];
+			if (next && next.type === "old-only") {
+				merged.push({ type: "changed", fileLine: op.fileLine, fileText: op.fileText, oldLine: next.oldLine, oldText: next.oldText });
+				k++;
+				continue;
+			}
+			merged.push(op);
+			continue;
+		}
+		merged.push(op);
+	}
+	return merged;
+}
+
+/** Cheap probes for common causes of a failed match. */
+export function probeMatchCauses(content: string, oldText: string): string[] {
+	const causes: string[] = [];
+	const stripWS = (s: string) => s.replace(/\s+/g, "");
+	if (stripWS(content).includes(stripWS(oldText))) {
+		causes.push(
+			"whitespace mismatch: the text matches when ALL whitespace is removed — check tabs vs spaces and indentation width",
+		);
+	} else if (content.toLowerCase().includes(oldText.toLowerCase())) {
+		causes.push("letter-case mismatch: the text matches case-insensitively");
+	}
+	const fileHasTabs = content.includes("\t");
+	const oldHasTabs = oldText.includes("\t");
+	if (fileHasTabs && !oldHasTabs) {
+		causes.push("the file contains tab characters but your oldText uses spaces");
+	} else if (!fileHasTabs && oldHasTabs) {
+		causes.push("your oldText contains tab characters but the file uses spaces");
+	}
+	return causes;
+}