@nghyane/arcane 0.1.0

package/src/patch/shared.ts

@@ -0,0 +1,400 @@
+/**
+ * Shared utilities for edit tool TUI rendering.
+ */
+import type { ToolCallContext } from "@nghyane/arcane-agent";
+import type { Component } from "@nghyane/arcane-tui";
+import { Text } from "@nghyane/arcane-tui";
+import type { RenderResultOptions } from "../extensibility/custom-tools/types";
+import type { FileDiagnosticsResult } from "../lsp";
+import { renderDiff as renderDiffColored } from "../modes/components/diff";
+import { getLanguageFromPath, type Theme } from "../modes/theme/theme";
+import type { OutputMeta } from "../tools/output-meta";
+import {
+	formatExpandHint,
+	formatStatusIcon,
+	getDiffStats,
+	PREVIEW_LIMITS,
+	replaceTabs,
+	shortenPath,
+	ToolUIKit,
+	truncateDiffByHunk,
+} from "../tools/render-utils";
+import { Ellipsis, Hasher, type RenderCache, renderStatusLine, truncateToWidth } from "../tui";
+import type { DiffError, DiffResult, Operation } from "./types";
+
+// ═══════════════════════════════════════════════════════════════════════════
+// LSP Batching
+// ═══════════════════════════════════════════════════════════════════════════
+
+const LSP_BATCH_TOOLS = new Set(["edit", "write"]);
+
+export function getLspBatchRequest(toolCall: ToolCallContext | undefined): { id: string; flush: boolean } | undefined {
+	if (!toolCall) {
+		return undefined;
+	}
+	const hasOtherWrites = toolCall.toolCalls.some(
+		(call, index) => index !== toolCall.index && LSP_BATCH_TOOLS.has(call.name),
+	);
+	if (!hasOtherWrites) {
+		return undefined;
+	}
+	const hasLaterWrites = toolCall.toolCalls.slice(toolCall.index + 1).some(call => LSP_BATCH_TOOLS.has(call.name));
+	return { id: toolCall.batchId, flush: !hasLaterWrites };
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Tool Details Types
+// ═══════════════════════════════════════════════════════════════════════════
+
+export interface EditToolDetails {
+	/** Unified diff of the changes made */
+	diff: string;
+	/** Line number of the first change in the new file (for editor navigation) */
+	firstChangedLine?: number;
+	/** Diagnostic result (if available) */
+	diagnostics?: FileDiagnosticsResult;
+	/** Operation type (patch mode only) */
+	op?: Operation;
+	/** New path after move/rename (patch mode only) */
+	rename?: string;
+	/** Structured output metadata */
+	meta?: OutputMeta;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// TUI Renderer
+// ═══════════════════════════════════════════════════════════════════════════
+
+interface EditRenderArgs {
+	path?: string;
+	file_path?: string;
+	oldText?: string;
+	newText?: string;
+	patch?: string;
+	all?: boolean;
+	// Patch mode fields
+	op?: Operation;
+	rename?: string;
+	diff?: string;
+	/**
+	 * Computed preview diff (used when tool args don't include a diff, e.g. hashline mode).
+	 */
+	previewDiff?: string;
+	// Hashline mode fields
+	edits?: HashlineEditPreview[];
+}
+
+type HashlineEditPreview =
+	| { target: string; new_content: string[] }
+	| { first: string; last: string; new_content: string[] }
+	| { before?: string; after?: string; inserted_lines: string[] }
+	| { old_text: string; new_text: string; all?: boolean };
+
+/** Extended context for edit tool rendering */
+export interface EditRenderContext {
+	/** Pre-computed diff preview (computed before tool executes) */
+	editDiffPreview?: DiffResult | DiffError;
+	/** Function to render diff text with syntax highlighting */
+	renderDiff?: (diffText: string, options?: { filePath?: string }) => string;
+}
+
+const EDIT_STREAMING_PREVIEW_LINES = 12;
+
+function countLines(text: string): number {
+	if (!text) return 0;
+	return text.split("\n").length;
+}
+
+function formatStreamingDiff(diff: string, rawPath: string, uiTheme: Theme, label = "streaming"): string {
+	if (!diff) return "";
+	const lines = diff.split("\n");
+	const total = lines.length;
+	const displayLines = lines.slice(-EDIT_STREAMING_PREVIEW_LINES);
+	const hidden = total - displayLines.length;
+	let text = "\n\n";
+	if (hidden > 0) {
+		text += uiTheme.fg("dim", `… (${hidden} earlier lines)\n`);
+	}
+	text += renderDiffColored(displayLines.join("\n"), { filePath: rawPath });
+	text += uiTheme.fg("dim", `\n… (${label})`);
+	return text;
+}
+
+function formatStreamingHashlineEdits(edits: unknown[], uiTheme: Theme, ui: ToolUIKit): string {
+	const MAX_EDITS = 4;
+	const MAX_DST_LINES = 8;
+	let text = "\n\n";
+	text += uiTheme.fg("dim", `[${edits.length} hashline edit${edits.length === 1 ? "" : "s"}]`);
+	text += "\n";
+	let shownEdits = 0;
+	let shownDstLines = 0;
+	for (const edit of edits) {
+		shownEdits++;
+		if (shownEdits > MAX_EDITS) break;
+		const formatted = formatHashlineEdit(edit);
+		text += uiTheme.fg("toolOutput", ui.truncate(replaceTabs(formatted.srcLabel), 120));
+		text += "\n";
+		if (formatted.dst === "") {
+			text += uiTheme.fg("dim", ui.truncate("  (delete)", 120));
+			text += "\n";
+			continue;
+		}
+		for (const dstLine of formatted.dst.split("\n")) {
+			shownDstLines++;
+			if (shownDstLines > MAX_DST_LINES) break;
+			text += uiTheme.fg("toolOutput", ui.truncate(replaceTabs(`+ ${dstLine}`), 120));
+			text += "\n";
+		}
+		if (shownDstLines > MAX_DST_LINES) break;
+	}
+	if (edits.length > MAX_EDITS) {
+		text += uiTheme.fg("dim", `… (${edits.length - MAX_EDITS} more edits)`);
+	}
+	if (shownDstLines > MAX_DST_LINES) {
+		text += uiTheme.fg("dim", `\n… (${shownDstLines - MAX_DST_LINES} more dst lines)`);
+	}
+
+	return text.trimEnd();
+	function formatHashlineEdit(edit: unknown): { srcLabel: string; dst: string } {
+		const asRecord = (value: unknown): Record<string, unknown> | undefined => {
+			if (typeof value === "object" && value !== null) return value as Record<string, unknown>;
+			return undefined;
+		};
+		const editRecord = asRecord(edit);
+		if (!editRecord) {
+			return {
+				srcLabel: "• (incomplete edit)",
+				dst: "",
+			};
+		}
+		if ("target" in editRecord) {
+			const target = typeof editRecord.target === "string" ? editRecord.target : "…";
+			const newContent = editRecord.new_content;
+			return {
+				srcLabel: `• line ${target}`,
+				dst: Array.isArray(newContent) ? (newContent as string[]).join("\n") : "",
+			};
+		}
+		if ("first" in editRecord || "last" in editRecord) {
+			const first = typeof editRecord.first === "string" ? editRecord.first : "…";
+			const last = typeof editRecord.last === "string" ? editRecord.last : "…";
+			const newContent = editRecord.new_content;
+			return {
+				srcLabel: `• range ${first}..${last}`,
+				dst: Array.isArray(newContent) ? (newContent as string[]).join("\n") : "",
+			};
+		}
+		if ("old_text" in editRecord || "new_text" in editRecord) {
+			const all = typeof editRecord.all === "boolean" ? editRecord.all : false;
+			return {
+				srcLabel: `• replace old_text→new_text${all ? " (all)" : ""}`,
+				dst: typeof editRecord.new_text === "string" ? editRecord.new_text : "",
+			};
+		}
+		if ("inserted_lines" in editRecord || "before" in editRecord || "after" in editRecord) {
+			const after = typeof editRecord.after === "string" ? editRecord.after : undefined;
+			const before = typeof editRecord.before === "string" ? editRecord.before : undefined;
+			const insertedLines = editRecord.inserted_lines;
+			const text = Array.isArray(insertedLines) ? (insertedLines as string[]).join("\n") : "";
+			const refs = [after, before].filter(Boolean).join("..") || "…";
+			return {
+				srcLabel: `• insert ${refs}`,
+				dst: text,
+			};
+		}
+		return {
+			srcLabel: "• (incomplete edit)",
+			dst: "",
+		};
+	}
+}
+function formatMetadataLine(lineCount: number | null, language: string | undefined, uiTheme: Theme): string {
+	const icon = uiTheme.getLangIcon(language);
+	if (lineCount !== null) {
+		return uiTheme.fg("dim", `${icon} ${lineCount} lines`);
+	}
+	return uiTheme.fg("dim", `${icon}`);
+}
+
+function renderDiffSection(
+	diff: string,
+	rawPath: string,
+	expanded: boolean,
+	uiTheme: Theme,
+	ui: ToolUIKit,
+	renderDiffFn: (t: string, o?: { filePath?: string }) => string,
+): string {
+	let text = "";
+	const diffStats = getDiffStats(diff);
+	text += `\n${uiTheme.fg("dim", uiTheme.format.bracketLeft)}${ui.formatDiffStats(
+		diffStats.added,
+		diffStats.removed,
+		diffStats.hunks,
+	)}${uiTheme.fg("dim", uiTheme.format.bracketRight)}`;
+
+	const {
+		text: truncatedDiff,
+		hiddenHunks,
+		hiddenLines,
+	} = expanded
+		? { text: diff, hiddenHunks: 0, hiddenLines: 0 }
+		: truncateDiffByHunk(diff, PREVIEW_LIMITS.DIFF_COLLAPSED_HUNKS, PREVIEW_LIMITS.DIFF_COLLAPSED_LINES);
+
+	text += `\n\n${renderDiffFn(truncatedDiff, { filePath: rawPath })}`;
+	if (!expanded && (hiddenHunks > 0 || hiddenLines > 0)) {
+		const remainder: string[] = [];
+		if (hiddenHunks > 0) remainder.push(`${hiddenHunks} more hunks`);
+		if (hiddenLines > 0) remainder.push(`${hiddenLines} more lines`);
+		text += uiTheme.fg("toolOutput", `\n… (${remainder.join(", ")}) ${formatExpandHint(uiTheme)}`);
+	}
+	return text;
+}
+
+export const editToolRenderer = {
+	mergeCallAndResult: true,
+
+	renderCall(args: EditRenderArgs, options: RenderResultOptions, uiTheme: Theme): Component {
+		const ui = new ToolUIKit(uiTheme);
+		const rawPath = args.file_path || args.path || "";
+		const filePath = shortenPath(rawPath);
+		const editLanguage = getLanguageFromPath(rawPath) ?? "text";
+		const editIcon = uiTheme.fg("muted", uiTheme.getLangIcon(editLanguage));
+		let pathDisplay = filePath ? uiTheme.fg("accent", filePath) : uiTheme.fg("toolOutput", "…");
+
+		// Add arrow for move/rename operations
+		if (args.rename) {
+			pathDisplay += ` ${uiTheme.fg("dim", "→")} ${uiTheme.fg("accent", shortenPath(args.rename))}`;
+		}
+
+		// Show operation type for patch mode
+		const opTitle = args.op === "create" ? "Create" : args.op === "delete" ? "Delete" : "Edit";
+		const spinner =
+			options?.spinnerFrame !== undefined ? formatStatusIcon("running", uiTheme, options.spinnerFrame) : "";
+		let text = `${ui.title(opTitle)} ${spinner ? `${spinner} ` : ""}${editIcon} ${pathDisplay}`;
+
+		// Show streaming preview of diff/content
+		if (args.previewDiff) {
+			text += formatStreamingDiff(args.previewDiff, rawPath, uiTheme, "preview");
+		} else if (args.diff && args.op) {
+			text += formatStreamingDiff(args.diff, rawPath, uiTheme);
+		} else if (args.edits && args.edits.length > 0) {
+			text += formatStreamingHashlineEdits(args.edits, uiTheme, ui);
+		} else if (args.diff) {
+			const previewLines = args.diff.split("\n");
+			const maxLines = 6;
+			text += "\n\n";
+			for (const line of previewLines.slice(0, maxLines)) {
+				text += `${uiTheme.fg("toolOutput", ui.truncate(replaceTabs(line), 80))}\n`;
+			}
+			if (previewLines.length > maxLines) {
+				text += uiTheme.fg("dim", `… ${previewLines.length - maxLines} more lines`);
+			}
+		} else if (args.newText || args.patch) {
+			const previewLines = (args.newText ?? args.patch ?? "").split("\n");
+			const maxLines = 6;
+			text += "\n\n";
+			for (const line of previewLines.slice(0, maxLines)) {
+				text += `${uiTheme.fg("toolOutput", ui.truncate(replaceTabs(line), 80))}\n`;
+			}
+			if (previewLines.length > maxLines) {
+				text += uiTheme.fg("dim", `… ${previewLines.length - maxLines} more lines`);
+			}
+		}
+
+		return new Text(text, 0, 0);
+	},
+
+	renderResult(
+		result: { content: Array<{ type: string; text?: string }>; details?: EditToolDetails; isError?: boolean },
+		options: RenderResultOptions & { renderContext?: EditRenderContext },
+		uiTheme: Theme,
+		args?: EditRenderArgs,
+	): Component {
+		const ui = new ToolUIKit(uiTheme);
+		const rawPath = args?.file_path || args?.path || "";
+		const filePath = shortenPath(rawPath);
+		const editLanguage = getLanguageFromPath(rawPath) ?? "text";
+		const editIcon = uiTheme.fg("muted", uiTheme.getLangIcon(editLanguage));
+
+		const op = args?.op || result.details?.op;
+		const rename = args?.rename || result.details?.rename;
+		const opTitle = op === "create" ? "Create" : op === "delete" ? "Delete" : "Edit";
+
+		// Pre-compute metadata line (static across renders)
+		const lineCountSource = args?.newText ?? args?.oldText ?? args?.diff ?? args?.patch ?? null;
+		const metadataLine =
+			op !== "delete"
+				? `\n${formatMetadataLine(lineCountSource ? countLines(lineCountSource) : null, editLanguage, uiTheme)}`
+				: "";
+
+		// Pre-compute error text (static)
+		const errorText = result.isError ? (result.content?.find(c => c.type === "text")?.text ?? "") : "";
+
+		let cached: RenderCache | undefined;
+
+		return {
+			render(width) {
+				const { expanded, renderContext } = options;
+				const editDiffPreview = renderContext?.editDiffPreview;
+				const renderDiffFn = renderContext?.renderDiff ?? ((t: string) => t);
+				const key = new Hasher().bool(expanded).u32(width).digest();
+				if (cached?.key === key) return cached.lines;
+
+				// Build path display with line number
+				let pathDisplay = filePath ? uiTheme.fg("accent", filePath) : uiTheme.fg("toolOutput", "…");
+				const firstChangedLine =
+					(editDiffPreview && "firstChangedLine" in editDiffPreview
+						? editDiffPreview.firstChangedLine
+						: undefined) || (result.details && !result.isError ? result.details.firstChangedLine : undefined);
+				if (firstChangedLine) {
+					pathDisplay += uiTheme.fg("warning", `:${firstChangedLine}`);
+				}
+
+				// Add arrow for rename operations
+				if (rename) {
+					pathDisplay += ` ${uiTheme.fg("dim", "→")} ${uiTheme.fg("accent", shortenPath(rename))}`;
+				}
+
+				const header = renderStatusLine(
+					{
+						icon: result.isError ? "error" : "success",
+						title: opTitle,
+						description: `${editIcon} ${pathDisplay}`,
+					},
+					uiTheme,
+				);
+				let text = header;
+				text += metadataLine;
+
+				if (result.isError) {
+					if (errorText) {
+						text += `\n\n${uiTheme.fg("error", replaceTabs(errorText))}`;
+					}
+				} else if (result.details?.diff) {
+					text += renderDiffSection(result.details.diff, rawPath, expanded, uiTheme, ui, renderDiffFn);
+				} else if (editDiffPreview) {
+					if ("error" in editDiffPreview) {
+						text += `\n\n${uiTheme.fg("error", replaceTabs(editDiffPreview.error))}`;
+					} else if (editDiffPreview.diff) {
+						text += renderDiffSection(editDiffPreview.diff, rawPath, expanded, uiTheme, ui, renderDiffFn);
+					}
+				}
+
+				// Show LSP diagnostics if available
+				if (result.details?.diagnostics) {
+					text += ui.formatDiagnostics(result.details.diagnostics, expanded, (fp: string) =>
+						uiTheme.getLangIcon(getLanguageFromPath(fp)),
+					);
+				}
+
+				const lines =
+					width > 0 ? text.split("\n").map(line => truncateToWidth(line, width, Ellipsis.Omit)) : text.split("\n");
+				cached = { key, lines };
+				return lines;
+			},
+			invalidate() {
+				cached = undefined;
+			},
+		};
+	},
+};

package/src/patch/types.ts

@@ -0,0 +1,292 @@
+/**
+ * Shared types for the edit tool module.
+ */
+
+// ═══════════════════════════════════════════════════════════════════════════
+// File System Abstraction
+// ═══════════════════════════════════════════════════════════════════════════
+
+/** Abstraction for file system operations to support LSP writethrough */
+export interface FileSystem {
+	exists(path: string): Promise<boolean>;
+	read(path: string): Promise<string>;
+	readBinary?: (path: string) => Promise<Uint8Array>;
+	write(path: string, content: string): Promise<void>;
+	delete(path: string): Promise<void>;
+	mkdir(path: string): Promise<void>;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Fuzzy Matching Types
+// ═══════════════════════════════════════════════════════════════════════════
+
+/** Result of a fuzzy match operation */
+export interface FuzzyMatch {
+	/** The actual text that was matched */
+	actualText: string;
+	/** Character index where the match starts */
+	startIndex: number;
+	/** Line number where the match starts (1-indexed) */
+	startLine: number;
+	/** Confidence score (0-1, where 1 is exact match) */
+	confidence: number;
+}
+
+/** Outcome of attempting to find a match */
+export interface MatchOutcome {
+	/** The match if found with sufficient confidence */
+	match?: FuzzyMatch;
+	/** The closest match found (may be below threshold) */
+	closest?: FuzzyMatch;
+	/** Number of occurrences if multiple exact matches found */
+	occurrences?: number;
+	/** Line numbers where occurrences were found (1-indexed) */
+	occurrenceLines?: number[];
+	/** Preview snippets for each occurrence (up to 5) */
+	occurrencePreviews?: string[];
+	/** Number of fuzzy matches above threshold */
+	fuzzyMatches?: number;
+	/** True when a dominant fuzzy match was accepted despite multiple candidates */
+	dominantFuzzy?: boolean;
+}
+
+/** Result of a sequence search */
+export type SequenceMatchStrategy =
+	| "exact"
+	| "trim-trailing"
+	| "trim"
+	| "comment-prefix"
+	| "unicode"
+	| "prefix"
+	| "substring"
+	| "fuzzy"
+	| "fuzzy-dominant"
+	| "character";
+
+export interface SequenceSearchResult {
+	/** Starting line index of the match (0-indexed) */
+	index: number | undefined;
+	/** Confidence score (1.0 for exact match, lower for fuzzy) */
+	confidence: number;
+	/** Number of matches at the same confidence level (for ambiguity detection) */
+	matchCount?: number;
+	/** Sample of matching indices (0-indexed, up to a small limit) */
+	matchIndices?: number[];
+	/** Matching strategy used */
+	strategy?: SequenceMatchStrategy;
+}
+
+/** Result of a context line search */
+export type ContextMatchStrategy = "exact" | "trim" | "unicode" | "prefix" | "substring" | "fuzzy";
+
+export interface ContextLineResult {
+	/** Index of the matching line (0-indexed) */
+	index: number | undefined;
+	/** Confidence score (1.0 for exact match, lower for fuzzy) */
+	confidence: number;
+	/** Number of matches at the same confidence level (for ambiguity detection) */
+	matchCount?: number;
+	/** Sample of matching indices (0-indexed, up to a small limit) */
+	matchIndices?: number[];
+	/** Matching strategy used */
+	strategy?: ContextMatchStrategy;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Patch Types
+// ═══════════════════════════════════════════════════════════════════════════
+
+export type Operation = "create" | "delete" | "update";
+
+/** Input for a patch operation */
+export interface PatchInput {
+	/** File path (relative or absolute) */
+	path: string;
+	/** Operation type */
+	op: Operation;
+	/** New path for rename (update only) */
+	rename?: string;
+	/** File content (create) or diff hunks (update) */
+	diff?: string;
+}
+
+/** Normalized patch input used internally by the applicator. */
+export interface NormalizedPatchInput {
+	path: string;
+	op: Operation;
+	rename?: string;
+	diff?: string;
+}
+
+export function normalizePatchInput(input: PatchInput): NormalizedPatchInput {
+	return {
+		path: input.path,
+		op: input.op ?? "update",
+		rename: input.rename,
+		diff: input.diff,
+	};
+}
+
+/** A single hunk/chunk in a diff */
+export interface DiffHunk {
+	/** Context line to narrow down position (e.g., class/method definition) */
+	changeContext?: string;
+	/** 1-based line hint from unified diff headers (old file) */
+	oldStartLine?: number;
+	/** 1-based line hint from unified diff headers (new file) */
+	newStartLine?: number;
+	/** True if the hunk contains context lines (space-prefixed) */
+	hasContextLines: boolean;
+	/** Lines to be replaced (old content) */
+	oldLines: string[];
+	/** Lines to replace with (new content) */
+	newLines: string[];
+	/** If true, oldLines must occur at end of file */
+	isEndOfFile: boolean;
+}
+
+/** Describes a change made to a file */
+export interface FileChange {
+	type: Operation;
+	path: string;
+	newPath?: string;
+	oldContent?: string;
+	newContent?: string;
+}
+
+/** Result of applying a patch */
+export interface ApplyPatchResult {
+	change: FileChange;
+	warnings?: string[];
+}
+
+/** Options for applying a patch */
+export interface ApplyPatchOptions {
+	/** Working directory for resolving relative paths */
+	cwd: string;
+	/** Dry run - compute changes without writing */
+	dryRun?: boolean;
+	/** Similarity threshold for fuzzy matching */
+	fuzzyThreshold?: number;
+	/** Allow fuzzy/partial matching when applying hunks */
+	allowFuzzy?: boolean;
+	/** File system abstraction (defaults to Bun-based implementation) */
+	fs?: FileSystem;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Diff Generation Types
+// ═══════════════════════════════════════════════════════════════════════════
+
+/** Result of generating a diff */
+export interface DiffResult {
+	/** The unified diff string */
+	diff: string;
+	/** Line number of the first change in the new file */
+	firstChangedLine: number | undefined;
+}
+
+/** Error from diff computation */
+export interface DiffError {
+	error: string;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Hashline Types
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Hashline edit operation/input types are schema-derived in `patch/index.ts`
+ * via `Static<typeof hashlineEditItemSchema>` and `Static<typeof hashlineEditSchema>`.
+ */
+
+/** A single hash mismatch found during validation */
+export interface HashMismatch {
+	/** 1-indexed line number */
+	line: number;
+	/** Hash the caller provided */
+	expected: string;
+	/** Hash computed from the current file content */
+	actual: string;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Error Classes
+// ═══════════════════════════════════════════════════════════════════════════
+
+export class ParseError extends Error {
+	constructor(
+		message: string,
+		public readonly lineNumber?: number,
+	) {
+		super(lineNumber !== undefined ? `Line ${lineNumber}: ${message}` : message);
+		this.name = "ParseError";
+	}
+}
+
+export class ApplyPatchError extends Error {
+	constructor(message: string) {
+		super(message);
+		this.name = "ApplyPatchError";
+	}
+}
+
+export class EditMatchError extends Error {
+	constructor(
+		public readonly path: string,
+		public readonly searchText: string,
+		public readonly closest: FuzzyMatch | undefined,
+		public readonly options: { allowFuzzy: boolean; threshold: number; fuzzyMatches?: number },
+	) {
+		super(EditMatchError.formatMessage(path, searchText, closest, options));
+		this.name = "EditMatchError";
+	}
+
+	static formatMessage(
+		path: string,
+		searchText: string,
+		closest: FuzzyMatch | undefined,
+		options: { allowFuzzy: boolean; threshold: number; fuzzyMatches?: number },
+	): string {
+		if (!closest) {
+			return options.allowFuzzy
+				? `Could not find a close enough match in ${path}.`
+				: `Could not find the exact text in ${path}. The old text must match exactly including all whitespace and newlines.`;
+		}
+
+		const similarity = Math.round(closest.confidence * 100);
+		const searchLines = searchText.split("\n");
+		const actualLines = closest.actualText.split("\n");
+		const { oldLine, newLine } = findFirstDifferentLine(searchLines, actualLines);
+		const thresholdPercent = Math.round(options.threshold * 100);
+
+		const hint = options.allowFuzzy
+			? options.fuzzyMatches && options.fuzzyMatches > 1
+				? `Found ${options.fuzzyMatches} high-confidence matches. Provide more context to make it unique.`
+				: `Closest match was below the ${thresholdPercent}% similarity threshold.`
+			: "Fuzzy matching is disabled. Enable 'Edit fuzzy match' in settings to accept high-confidence matches.";
+
+		return [
+			options.allowFuzzy
+				? `Could not find a close enough match in ${path}.`
+				: `Could not find the exact text in ${path}.`,
+			``,
+			`Closest match (${similarity}% similar) at line ${closest.startLine}:`,
+			`  - ${oldLine}`,
+			`  + ${newLine}`,
+			hint,
+		].join("\n");
+	}
+}
+
+function findFirstDifferentLine(oldLines: string[], newLines: string[]): { oldLine: string; newLine: string } {
+	const max = Math.max(oldLines.length, newLines.length);
+	for (let i = 0; i < max; i++) {
+		const oldLine = oldLines[i] ?? "";
+		const newLine = newLines[i] ?? "";
+		if (oldLine !== newLine) {
+			return { oldLine, newLine };
+		}
+	}
+	return { oldLine: oldLines[0] ?? "", newLine: newLines[0] ?? "" };
+}