@schlenkr/ragents 0.1.0

package/packages/agent/src/core/tools/edit-diff.ts

@@ -0,0 +1,704 @@
+/**
+ * Shared diff computation utilities for the edit and similar tools.
+ */
+
+import * as Diff from "diff";
+import { constants } from "fs";
+import { access, readFile } from "fs/promises";
+import { resolveToCwd } from "./path-utils.ts";
+
+export function detectLineEnding(content: string): "\r\n" | "\n" {
+	const crlfIdx = content.indexOf("\r\n");
+	const lfIdx = content.indexOf("\n");
+	if (lfIdx === -1) return "\n";
+	if (crlfIdx === -1) return "\n";
+	return crlfIdx < lfIdx ? "\r\n" : "\n";
+}
+
+export function normalizeToLF(text: string): string {
+	return text.replace(/\r\n/g, "\n").replace(/\r/g, "\n");
+}
+
+export function restoreLineEndings(text: string, ending: "\r\n" | "\n"): string {
+	return ending === "\r\n" ? text.replace(/\n/g, "\r\n") : text;
+}
+
+/**
+ * Normalize text for fuzzy matching. Applies progressive transformations:
+ * - Strip trailing whitespace from each line
+ * - Normalize smart quotes to ASCII equivalents
+ * - Normalize Unicode dashes/hyphens to ASCII hyphen
+ * - Normalize special Unicode spaces to regular space
+ */
+export function normalizeForFuzzyMatch(text: string): string {
+	return (
+		text
+			.normalize("NFKC")
+			// Strip trailing whitespace per line
+			.split("\n")
+			.map((line) => line.trimEnd())
+			.join("\n")
+			// Smart single quotes → '
+			.replace(/[\u2018\u2019\u201A\u201B]/g, "'")
+			// Smart double quotes → "
+			.replace(/[\u201C\u201D\u201E\u201F]/g, '"')
+			// Various dashes/hyphens → -
+			// U+2010 hyphen, U+2011 non-breaking hyphen, U+2012 figure dash,
+			// U+2013 en-dash, U+2014 em-dash, U+2015 horizontal bar, U+2212 minus
+			.replace(/[\u2010\u2011\u2012\u2013\u2014\u2015\u2212]/g, "-")
+			// Special spaces → regular space
+			// U+00A0 NBSP, U+2002-U+200A various spaces, U+202F narrow NBSP,
+			// U+205F medium math space, U+3000 ideographic space
+			.replace(/[\u00A0\u2002-\u200A\u202F\u205F\u3000]/g, " ")
+	);
+}
+
+function splitLinesWithEndings(content: string): string[] {
+	return content.match(/[^\n]*\n|[^\n]+/g) ?? [];
+}
+
+interface LineSpan {
+	start: number;
+	end: number;
+}
+
+interface MatchedEdit {
+	editIndex: number;
+	matchIndex: number;
+	matchLength: number;
+	newText: string;
+}
+
+type TextReplacement = Pick<MatchedEdit, "matchIndex" | "matchLength" | "newText">;
+
+function getLineSpans(content: string): LineSpan[] {
+	let offset = 0;
+	return splitLinesWithEndings(content).map((line) => {
+		const span = { start: offset, end: offset + line.length };
+		offset = span.end;
+		return span;
+	});
+}
+
+function getReplacementLineRange(lines: LineSpan[], replacement: TextReplacement) {
+	const replacementStart = replacement.matchIndex;
+	const replacementEnd = replacement.matchIndex + replacement.matchLength;
+
+	let startLine = -1;
+	for (let i = 0; i < lines.length; i++) {
+		const line = lines[i];
+		if (replacementStart >= line.start && replacementStart < line.end) {
+			startLine = i;
+			break;
+		}
+	}
+	if (startLine === -1) {
+		throw new Error("Replacement range is outside the base content.");
+	}
+
+	let endLine = startLine;
+	while (endLine < lines.length && lines[endLine].end < replacementEnd) {
+		endLine++;
+	}
+	if (endLine >= lines.length) {
+		throw new Error("Replacement range is outside the base content.");
+	}
+
+	return { startLine, endLine: endLine + 1 };
+}
+
+function applyReplacements(content: string, replacements: TextReplacement[], offset = 0): string {
+	let result = content;
+	for (let i = replacements.length - 1; i >= 0; i--) {
+		const replacement = replacements[i];
+		const matchIndex = replacement.matchIndex - offset;
+		result =
+			result.substring(0, matchIndex) + replacement.newText + result.substring(matchIndex + replacement.matchLength);
+	}
+	return result;
+}
+
+/**
+ * Apply replacements matched against `baseContent` to `originalContent` while
+ * preserving unchanged line blocks from the original.
+ *
+ * This is useful when `baseContent` is a normalized view of the original. Each
+ * replacement is widened to the lines it actually touches, those touched lines
+ * are rewritten from the normalized base, and all other lines are copied back
+ * from `originalContent`. The actual replacement ranges drive preservation so
+ * duplicate normalized lines cannot be aligned to the wrong occurrence.
+ */
+export function applyReplacementsPreservingUnchangedLines(
+	originalContent: string,
+	baseContent: string,
+	replacements: TextReplacement[],
+): string {
+	const originalLines = splitLinesWithEndings(originalContent);
+	const baseLines = getLineSpans(baseContent);
+	if (originalLines.length !== baseLines.length) {
+		throw new Error("Cannot preserve unchanged lines because the base content has a different line count.");
+	}
+
+	const groups: Array<{ startLine: number; endLine: number; replacements: TextReplacement[] }> = [];
+	const sortedReplacements = [...replacements].sort((a, b) => a.matchIndex - b.matchIndex);
+	for (const replacement of sortedReplacements) {
+		const range = getReplacementLineRange(baseLines, replacement);
+		const current = groups[groups.length - 1];
+		if (current && range.startLine < current.endLine) {
+			current.endLine = Math.max(current.endLine, range.endLine);
+			current.replacements.push(replacement);
+			continue;
+		}
+		groups.push({ ...range, replacements: [replacement] });
+	}
+
+	let originalLineIndex = 0;
+	let result = "";
+	for (const group of groups) {
+		result += originalLines.slice(originalLineIndex, group.startLine).join("");
+
+		const groupStartOffset = baseLines[group.startLine].start;
+		const groupEndOffset = baseLines[group.endLine - 1].end;
+		result += applyReplacements(
+			baseContent.slice(groupStartOffset, groupEndOffset),
+			group.replacements,
+			groupStartOffset,
+		);
+		originalLineIndex = group.endLine;
+	}
+	result += originalLines.slice(originalLineIndex).join("");
+
+	return result;
+}
+
+export interface FuzzyMatchResult {
+	/** Whether a match was found */
+	found: boolean;
+	/** The index where the match starts (in the content that should be used for replacement) */
+	index: number;
+	/** Length of the matched text */
+	matchLength: number;
+	/** Whether fuzzy matching was used (false = exact match) */
+	usedFuzzyMatch: boolean;
+	/**
+	 * The content to use for replacement operations.
+	 * When exact match: original content. When fuzzy match: normalized content.
+	 */
+	contentForReplacement: string;
+}
+
+export interface Edit {
+	oldText: string;
+	newText: string;
+	/** 1-based index of the occurrence to replace when oldText is not unique */
+	occurrence?: number;
+	/** Line number close to the intended occurrence; the closest occurrence wins */
+	nearLine?: number;
+	/** Replace every occurrence instead of requiring a unique match */
+	replaceAll?: boolean;
+}
+
+export interface AppliedEditsResult {
+	baseContent: string;
+	newContent: string;
+	/** Number of replaced regions, which is larger than edits.length when replaceAll is used */
+	replacementCount: number;
+}
+
+/**
+ * Find oldText in content, trying exact match first, then fuzzy match.
+ * When fuzzy matching is used, the returned contentForReplacement is the
+ * fuzzy-normalized version of the content (trailing whitespace stripped,
+ * Unicode quotes/dashes normalized to ASCII).
+ */
+export function fuzzyFindText(content: string, oldText: string): FuzzyMatchResult {
+	// Try exact match first
+	const exactIndex = content.indexOf(oldText);
+	if (exactIndex !== -1) {
+		return {
+			found: true,
+			index: exactIndex,
+			matchLength: oldText.length,
+			usedFuzzyMatch: false,
+			contentForReplacement: content,
+		};
+	}
+
+	// Try fuzzy match - work entirely in normalized space
+	const fuzzyContent = normalizeForFuzzyMatch(content);
+	const fuzzyOldText = normalizeForFuzzyMatch(oldText);
+	const fuzzyIndex = fuzzyContent.indexOf(fuzzyOldText);
+
+	if (fuzzyIndex === -1) {
+		return {
+			found: false,
+			index: -1,
+			matchLength: 0,
+			usedFuzzyMatch: false,
+			contentForReplacement: content,
+		};
+	}
+
+	// When fuzzy matching, return offsets in normalized space. Callers can use
+	// the normalized content to compute replacements, then decide how much of
+	// that normalized output should be written back.
+	return {
+		found: true,
+		index: fuzzyIndex,
+		matchLength: fuzzyOldText.length,
+		usedFuzzyMatch: true,
+		contentForReplacement: fuzzyContent,
+	};
+}
+
+/** Strip UTF-8 BOM if present, return both the BOM (if any) and the text without it */
+export function stripBom(content: string): { bom: string; text: string } {
+	return content.startsWith("\uFEFF") ? { bom: "\uFEFF", text: content.slice(1) } : { bom: "", text: content };
+}
+
+const MAX_LISTED_OCCURRENCES = 20;
+const MAX_CONTEXT_LINE_LENGTH = 120;
+
+function collectMatchIndices(content: string, needle: string): number[] {
+	if (needle.length === 0) {
+		return [];
+	}
+	const indices: number[] = [];
+	for (let index = content.indexOf(needle); index !== -1; index = content.indexOf(needle, index + needle.length)) {
+		indices.push(index);
+	}
+	return indices;
+}
+
+interface OccurrenceMatches {
+	indices: number[];
+	matchLength: number;
+}
+
+/** Exact occurrences when there are any, otherwise the fuzzy-normalized ones. */
+function findOccurrences(content: string, oldText: string): OccurrenceMatches {
+	const exactIndices = collectMatchIndices(content, oldText);
+	if (exactIndices.length > 0) {
+		return { indices: exactIndices, matchLength: oldText.length };
+	}
+	const fuzzyOldText = normalizeForFuzzyMatch(oldText);
+	return {
+		indices: collectMatchIndices(normalizeForFuzzyMatch(content), fuzzyOldText),
+		matchLength: fuzzyOldText.length,
+	};
+}
+
+/** Line numbers (1-based) for ascending indices into content. */
+function getLineNumbers(content: string, indices: number[]): number[] {
+	const lineNumbers: number[] = [];
+	let line = 1;
+	let cursor = 0;
+	for (const index of indices) {
+		while (cursor < index) {
+			if (content[cursor] === "\n") line++;
+			cursor++;
+		}
+		lineNumbers.push(line);
+	}
+	return lineNumbers;
+}
+
+function formatOccurrences(content: string, indices: number[]): string {
+	const lines = content.split("\n");
+	const shown = indices.slice(0, MAX_LISTED_OCCURRENCES);
+	const entries = getLineNumbers(content, shown).map((line) => {
+		const text = lines[line - 1].trim();
+		const context = text.length > MAX_CONTEXT_LINE_LENGTH ? `${text.slice(0, MAX_CONTEXT_LINE_LENGTH)}...` : text;
+		return `  line ${line}: ${context}`;
+	});
+	const remaining = indices.length - shown.length;
+	return (remaining > 0 ? [...entries, `  ... and ${remaining} more`] : entries).join("\n");
+}
+
+function getNotFoundError(path: string, editIndex: number, totalEdits: number): Error {
+	if (totalEdits === 1) {
+		return new Error(
+			`Could not find the exact text in ${path}. The old text must match exactly including all whitespace and newlines.`,
+		);
+	}
+	return new Error(
+		`Could not find edits[${editIndex}] in ${path}. The oldText must match exactly including all whitespace and newlines.`,
+	);
+}
+
+function getDuplicateError(
+	path: string,
+	editIndex: number,
+	totalEdits: number,
+	fuzzyContent: string,
+	indices: number[],
+): Error {
+	const header =
+		totalEdits === 1
+			? `Found ${indices.length} occurrences of the text in ${path}. The text must be unique.`
+			: `Found ${indices.length} occurrences of edits[${editIndex}] in ${path}. Each oldText must be unique.`;
+	return new Error(
+		`${header} Occurrences:\n${formatOccurrences(fuzzyContent, indices)}\n` +
+			`Either extend oldText with surrounding context, or set edits[${editIndex}].occurrence (1-based), edits[${editIndex}].nearLine or edits[${editIndex}].replaceAll.`,
+	);
+}
+
+function validateEditAnchors(path: string, editIndex: number, edit: Edit): void {
+	if (edit.replaceAll && (edit.occurrence !== undefined || edit.nearLine !== undefined)) {
+		throw new Error(
+			`edits[${editIndex}].replaceAll cannot be combined with occurrence or nearLine in ${path}. Use either replaceAll or one anchor.`,
+		);
+	}
+	if (edit.occurrence !== undefined && (!Number.isInteger(edit.occurrence) || edit.occurrence < 1)) {
+		throw new Error(`edits[${editIndex}].occurrence must be an integer >= 1 in ${path}.`);
+	}
+	if (edit.nearLine !== undefined && (!Number.isInteger(edit.nearLine) || edit.nearLine < 1)) {
+		throw new Error(`edits[${editIndex}].nearLine must be an integer >= 1 in ${path}.`);
+	}
+}
+
+function pickByOccurrence(
+	path: string,
+	editIndex: number,
+	occurrence: number,
+	content: string,
+	indices: number[],
+): number {
+	if (occurrence > indices.length) {
+		throw new Error(
+			`edits[${editIndex}].occurrence is ${occurrence}, but ${path} contains ${indices.length} occurrence(s). Occurrences:\n${formatOccurrences(content, indices)}`,
+		);
+	}
+	return indices[occurrence - 1];
+}
+
+function pickByNearLine(path: string, editIndex: number, nearLine: number, content: string, indices: number[]): number {
+	const distances = getLineNumbers(content, indices).map((line) => Math.abs(line - nearLine));
+	const shortest = distances.reduce((best, distance) => Math.min(best, distance));
+	const closest = indices.filter((_, i) => distances[i] === shortest);
+	if (closest.length > 1) {
+		throw new Error(
+			`edits[${editIndex}].nearLine ${nearLine} is ambiguous in ${path}: ${closest.length} occurrences are equally close. Occurrences:\n${formatOccurrences(content, indices)}`,
+		);
+	}
+	return closest[0];
+}
+
+/** Occurrence indices this edit replaces: all, the anchored one, or the single unique one. */
+function selectOccurrences(
+	path: string,
+	editIndex: number,
+	totalEdits: number,
+	edit: Edit,
+	content: string,
+	indices: number[],
+): number[] {
+	if (edit.replaceAll) {
+		return indices;
+	}
+
+	const byOccurrence =
+		edit.occurrence === undefined ? undefined : pickByOccurrence(path, editIndex, edit.occurrence, content, indices);
+	const byNearLine =
+		edit.nearLine === undefined ? undefined : pickByNearLine(path, editIndex, edit.nearLine, content, indices);
+	if (byOccurrence !== undefined && byNearLine !== undefined && byOccurrence !== byNearLine) {
+		throw new Error(
+			`edits[${editIndex}].occurrence and edits[${editIndex}].nearLine select different occurrences in ${path}. Use only one of them.`,
+		);
+	}
+	const anchored = byOccurrence ?? byNearLine;
+	if (anchored !== undefined) {
+		return [anchored];
+	}
+
+	const fuzzyContent = normalizeForFuzzyMatch(content);
+	const fuzzyIndices = collectMatchIndices(fuzzyContent, normalizeForFuzzyMatch(edit.oldText));
+	if (fuzzyIndices.length > 1) {
+		throw getDuplicateError(path, editIndex, totalEdits, fuzzyContent, fuzzyIndices);
+	}
+	return [indices[0]];
+}
+
+function getEmptyOldTextError(path: string, editIndex: number, totalEdits: number): Error {
+	if (totalEdits === 1) {
+		return new Error(`oldText must not be empty in ${path}.`);
+	}
+	return new Error(`edits[${editIndex}].oldText must not be empty in ${path}.`);
+}
+
+function getNoChangeError(path: string, totalEdits: number): Error {
+	if (totalEdits === 1) {
+		return new Error(
+			`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.`,
+		);
+	}
+	return new Error(`No changes made to ${path}. The replacements produced identical content.`);
+}
+
+/**
+ * Apply one or more exact-text replacements to LF-normalized content.
+ *
+ * All edits are matched against the same original content. An edit replaces its
+ * unique match, the match picked by occurrence or nearLine, or every match when
+ * replaceAll is set. Replacements are applied in reverse order so offsets remain
+ * stable. If any edit needs fuzzy matching, the operation runs in fuzzy-normalized
+ * content space and then overlays those line-level changes onto the original
+ * content so unchanged line blocks keep their original bytes.
+ */
+export function applyEditsToNormalizedContent(
+	normalizedContent: string,
+	edits: Edit[],
+	path: string,
+): AppliedEditsResult {
+	const normalizedEdits = edits.map((edit) => ({
+		...edit,
+		oldText: normalizeToLF(edit.oldText),
+		newText: normalizeToLF(edit.newText),
+	}));
+
+	for (let i = 0; i < normalizedEdits.length; i++) {
+		if (normalizedEdits[i].oldText.length === 0) {
+			throw getEmptyOldTextError(path, i, normalizedEdits.length);
+		}
+		validateEditAnchors(path, i, normalizedEdits[i]);
+	}
+
+	const initialMatches = normalizedEdits.map((edit) => fuzzyFindText(normalizedContent, edit.oldText));
+	const usedFuzzyMatch = initialMatches.some((match) => match.usedFuzzyMatch);
+	const replacementBaseContent = usedFuzzyMatch ? normalizeForFuzzyMatch(normalizedContent) : normalizedContent;
+
+	const matchedEdits: MatchedEdit[] = [];
+	for (let i = 0; i < normalizedEdits.length; i++) {
+		const edit = normalizedEdits[i];
+		const { indices, matchLength } = findOccurrences(replacementBaseContent, edit.oldText);
+		if (indices.length === 0) {
+			throw getNotFoundError(path, i, normalizedEdits.length);
+		}
+
+		const selected = selectOccurrences(path, i, normalizedEdits.length, edit, replacementBaseContent, indices);
+		for (const matchIndex of selected) {
+			matchedEdits.push({
+				editIndex: i,
+				matchIndex,
+				matchLength,
+				newText: edit.newText,
+			});
+		}
+	}
+
+	matchedEdits.sort((a, b) => a.matchIndex - b.matchIndex);
+	for (let i = 1; i < matchedEdits.length; i++) {
+		const previous = matchedEdits[i - 1];
+		const current = matchedEdits[i];
+		if (previous.matchIndex + previous.matchLength > current.matchIndex) {
+			throw new Error(
+				`edits[${previous.editIndex}] and edits[${current.editIndex}] overlap in ${path}. Merge them into one edit or target disjoint regions.`,
+			);
+		}
+	}
+
+	const baseContent = normalizedContent;
+	const newContent = usedFuzzyMatch
+		? applyReplacementsPreservingUnchangedLines(normalizedContent, replacementBaseContent, matchedEdits)
+		: applyReplacements(replacementBaseContent, matchedEdits);
+
+	if (baseContent === newContent) {
+		throw getNoChangeError(path, normalizedEdits.length);
+	}
+
+	return { baseContent, newContent, replacementCount: matchedEdits.length };
+}
+
+/** Generate a standard unified patch. */
+export function generateUnifiedPatch(path: string, oldContent: string, newContent: string, contextLines = 4): string {
+	return Diff.createTwoFilesPatch(path, path, oldContent, newContent, undefined, undefined, {
+		context: contextLines,
+		headerOptions: Diff.FILE_HEADERS_ONLY,
+	});
+}
+
+/**
+ * Generate a display-oriented diff string with line numbers and context.
+ * Returns both the diff string and the first changed line number (in the new file).
+ */
+export function generateDiffString(
+	oldContent: string,
+	newContent: string,
+	contextLines = 4,
+): { diff: string; firstChangedLine: number | undefined } {
+	const parts = Diff.diffLines(oldContent, newContent);
+	const output: string[] = [];
+
+	const oldLines = oldContent.split("\n");
+	const newLines = newContent.split("\n");
+	const maxLineNum = Math.max(oldLines.length, newLines.length);
+	const lineNumWidth = String(maxLineNum).length;
+
+	let oldLineNum = 1;
+	let newLineNum = 1;
+	let lastWasChange = false;
+	let firstChangedLine: number | undefined;
+
+	for (let i = 0; i < parts.length; i++) {
+		const part = parts[i];
+		const raw = part.value.split("\n");
+		if (raw[raw.length - 1] === "") {
+			raw.pop();
+		}
+
+		if (part.added || part.removed) {
+			// Capture the first changed line (in the new file)
+			if (firstChangedLine === undefined) {
+				firstChangedLine = newLineNum;
+			}
+
+			// Show the change
+			for (const line of raw) {
+				if (part.added) {
+					const lineNum = String(newLineNum).padStart(lineNumWidth, " ");
+					output.push(`+${lineNum} ${line}`);
+					newLineNum++;
+				} else {
+					// removed
+					const lineNum = String(oldLineNum).padStart(lineNumWidth, " ");
+					output.push(`-${lineNum} ${line}`);
+					oldLineNum++;
+				}
+			}
+			lastWasChange = true;
+		} else {
+			// Context lines - only show a few before/after changes
+			const nextPartIsChange = i < parts.length - 1 && (parts[i + 1].added || parts[i + 1].removed);
+			const hasLeadingChange = lastWasChange;
+			const hasTrailingChange = nextPartIsChange;
+
+			if (hasLeadingChange && hasTrailingChange) {
+				if (raw.length <= contextLines * 2) {
+					for (const line of raw) {
+						const lineNum = String(oldLineNum).padStart(lineNumWidth, " ");
+						output.push(` ${lineNum} ${line}`);
+						oldLineNum++;
+						newLineNum++;
+					}
+				} else {
+					const leadingLines = raw.slice(0, contextLines);
+					const trailingLines = raw.slice(raw.length - contextLines);
+					const skippedLines = raw.length - leadingLines.length - trailingLines.length;
+
+					for (const line of leadingLines) {
+						const lineNum = String(oldLineNum).padStart(lineNumWidth, " ");
+						output.push(` ${lineNum} ${line}`);
+						oldLineNum++;
+						newLineNum++;
+					}
+
+					output.push(` ${"".padStart(lineNumWidth, " ")} ...`);
+					oldLineNum += skippedLines;
+					newLineNum += skippedLines;
+
+					for (const line of trailingLines) {
+						const lineNum = String(oldLineNum).padStart(lineNumWidth, " ");
+						output.push(` ${lineNum} ${line}`);
+						oldLineNum++;
+						newLineNum++;
+					}
+				}
+			} else if (hasLeadingChange) {
+				const shownLines = raw.slice(0, contextLines);
+				const skippedLines = raw.length - shownLines.length;
+
+				for (const line of shownLines) {
+					const lineNum = String(oldLineNum).padStart(lineNumWidth, " ");
+					output.push(` ${lineNum} ${line}`);
+					oldLineNum++;
+					newLineNum++;
+				}
+
+				if (skippedLines > 0) {
+					output.push(` ${"".padStart(lineNumWidth, " ")} ...`);
+					oldLineNum += skippedLines;
+					newLineNum += skippedLines;
+				}
+			} else if (hasTrailingChange) {
+				const skippedLines = Math.max(0, raw.length - contextLines);
+				if (skippedLines > 0) {
+					output.push(` ${"".padStart(lineNumWidth, " ")} ...`);
+					oldLineNum += skippedLines;
+					newLineNum += skippedLines;
+				}
+
+				for (const line of raw.slice(skippedLines)) {
+					const lineNum = String(oldLineNum).padStart(lineNumWidth, " ");
+					output.push(` ${lineNum} ${line}`);
+					oldLineNum++;
+					newLineNum++;
+				}
+			} else {
+				// Skip these context lines entirely
+				oldLineNum += raw.length;
+				newLineNum += raw.length;
+			}
+
+			lastWasChange = false;
+		}
+	}
+
+	return { diff: output.join("\n"), firstChangedLine };
+}
+
+export interface EditDiffResult {
+	diff: string;
+	firstChangedLine: number | undefined;
+}
+
+export interface EditDiffError {
+	error: string;
+}
+
+/**
+ * Compute the diff for one or more edit operations without applying them.
+ * Used for preview rendering in the TUI before the tool executes.
+ */
+export async function computeEditsDiff(
+	path: string,
+	edits: Edit[],
+	cwd: string,
+): Promise<EditDiffResult | EditDiffError> {
+	const absolutePath = resolveToCwd(path, cwd);
+
+	try {
+		// Check if file exists and is readable
+		try {
+			await access(absolutePath, constants.R_OK);
+		} catch (error: unknown) {
+			const errorMessage = error instanceof Error && "code" in error ? `Error code: ${error.code}` : String(error);
+			return { error: `Could not edit file: ${path}. ${errorMessage}.` };
+		}
+
+		// Read the file
+		const rawContent = await readFile(absolutePath, "utf-8");
+
+		// Strip BOM before matching (LLM won't include invisible BOM in oldText)
+		const { text: content } = stripBom(rawContent);
+		const normalizedContent = normalizeToLF(content);
+		const { baseContent, newContent } = applyEditsToNormalizedContent(normalizedContent, edits, path);
+
+		// Generate the diff
+		return generateDiffString(baseContent, newContent);
+	} catch (err) {
+		return { error: err instanceof Error ? err.message : String(err) };
+	}
+}
+
+/**
+ * Compute the diff for a single edit operation without applying it.
+ * Kept as a convenience wrapper for single-edit callers.
+ */
+export async function computeEditDiff(
+	path: string,
+	oldText: string,
+	newText: string,
+	cwd: string,
+): Promise<EditDiffResult | EditDiffError> {
+	return computeEditsDiff(path, [{ oldText, newText }], cwd);
+}