@oh-my-pi/hashline 15.5.4

package/src/recovery.ts

@@ -0,0 +1,163 @@
+/**
+ * Recover from a stale section file-hash by replaying the would-be edit
+ * against a cached pre-edit snapshot of the file and 3-way-merging the
+ * result onto the current on-disk content.
+ *
+ * The patcher consults this when it sees a section hash that doesn't match
+ * the live file content. The recovery class is stateless apart from the
+ * {@link SnapshotStore} it queries; the snapshot store is the seam that
+ * lets you plug in your own caching strategy.
+ */
+import * as Diff from "diff";
+import { applyEdits } from "./apply";
+import { computeFileHash } from "./format";
+import { RECOVERY_EXTERNAL_WARNING, RECOVERY_SESSION_CHAIN_WARNING, RECOVERY_SESSION_REPLAY_WARNING } from "./messages";
+import type { Snapshot, SnapshotStore } from "./snapshots";
+import type { ApplyOptions, ApplyResult, Edit } from "./types";
+
+// Section hashes are line-precise; never let Diff.applyPatch slide a hunk
+// onto a duplicate closer 100+ lines away. If snapshot replay does not
+// align exactly, refuse and let the caller re-read.
+const RECOVERY_FUZZ_FACTOR = 0;
+
+export interface RecoveryArgs {
+	path: string;
+	currentText: string;
+	fileHash: string;
+	edits: readonly Edit[];
+	options?: ApplyOptions;
+}
+
+export interface RecoveryResult {
+	/** Post-recovery text. */
+	text: string;
+	/** First changed line (1-indexed) relative to the live `currentText`, or `undefined`. */
+	firstChangedLine: number | undefined;
+	/** Warnings collected during recovery, including the user-facing recovery banner. */
+	warnings: string[];
+}
+
+function applyEditsToSnapshot(
+	previousText: string,
+	currentText: string,
+	edits: readonly Edit[],
+	options: ApplyOptions,
+	recoveryWarning: string,
+): RecoveryResult | null {
+	let applied: ApplyResult;
+	try {
+		applied = applyEdits(previousText, [...edits], options);
+	} catch {
+		return null;
+	}
+	if (applied.text === previousText) return null;
+
+	const patch = Diff.structuredPatch("file", "file", previousText, applied.text, "", "", { context: 3 });
+	const merged = Diff.applyPatch(currentText, patch, { fuzzFactor: RECOVERY_FUZZ_FACTOR });
+	if (typeof merged !== "string" || merged === currentText) return null;
+
+	const firstChangedLine = findFirstChangedLine(currentText, merged) ?? applied.firstChangedLine;
+	const hasNetChange = firstChangedLine !== undefined;
+	const warnings = hasNetChange ? [recoveryWarning, ...(applied.warnings ?? [])] : [...(applied.warnings ?? [])];
+
+	return { text: merged, firstChangedLine, warnings };
+}
+
+function replaySessionChainOnCurrent(
+	previousText: string,
+	currentText: string,
+	edits: readonly Edit[],
+	options: ApplyOptions,
+): RecoveryResult | null {
+	// Only safe when no insert/delete shifted line counts in the prior edit
+	// chain: if total line counts match, every line number in `edits` still
+	// resolves to the same logical row.
+	if (previousText.split("\n").length !== currentText.split("\n").length) return null;
+	let applied: ApplyResult;
+	try {
+		applied = applyEdits(currentText, [...edits], options);
+	} catch {
+		return null;
+	}
+	if (applied.text === currentText) return null;
+	return {
+		text: applied.text,
+		firstChangedLine: applied.firstChangedLine,
+		warnings: [RECOVERY_SESSION_REPLAY_WARNING, ...(applied.warnings ?? [])],
+	};
+}
+
+function buildSparseOverlayText(currentText: string, snapshotLines: ReadonlyMap<number, string>): string {
+	const overlaid = currentText.split("\n");
+	let maxCachedLine = 0;
+	for (const lineNum of snapshotLines.keys()) {
+		if (lineNum > maxCachedLine) maxCachedLine = lineNum;
+	}
+	while (overlaid.length < maxCachedLine) overlaid.push("");
+	for (const [lineNum, content] of snapshotLines) {
+		overlaid[lineNum - 1] = content;
+	}
+	return overlaid.join("\n");
+}
+
+/** First 1-indexed line at which `a` and `b` diverge, or `undefined` if equal. */
+function findFirstChangedLine(a: string, b: string): number | undefined {
+	if (a === b) return undefined;
+	const aLines = a.split("\n");
+	const bLines = b.split("\n");
+	const max = Math.max(aLines.length, bLines.length);
+	for (let i = 0; i < max; i++) {
+		if (aLines[i] !== bLines[i]) return i + 1;
+	}
+	return undefined;
+}
+
+function isHeadSnapshot(head: Snapshot | null, snapshot: Snapshot): boolean {
+	return head === snapshot;
+}
+
+/**
+ * Stateless recovery driver over a {@link SnapshotStore}. Construct once and
+ * call {@link Recovery.tryRecover} per stale-hash incident. The default
+ * implementation tries three strategies in order:
+ *
+ * 1. Apply on the cached `fullText` snapshot, then 3-way-merge onto current.
+ * 2. (Session chain) If the snapshot wasn't the head, retry on current text
+ *    when line counts match — the user's previous edit advanced the hash but
+ *    didn't shift line numbers.
+ * 3. Reconstruct from a sparse snapshot (lines map only), verify the rebuilt
+ *    text hashes to the expected value, then 3-way-merge.
+ */
+export class Recovery {
+	constructor(readonly store: SnapshotStore) {}
+
+	/**
+	 * Attempt recovery. Returns `null` when no path forward is found — the
+	 * caller should then surface a {@link MismatchError}.
+	 */
+	tryRecover(args: RecoveryArgs): RecoveryResult | null {
+		const { path, currentText, fileHash, edits, options = {} } = args;
+		const head = this.store.head(path);
+		const snapshot = this.store.byHash(path, fileHash);
+		if (!snapshot || snapshot.lines.size === 0) return null;
+
+		const isHead = isHeadSnapshot(head, snapshot);
+		const recoveryWarning = isHead ? RECOVERY_EXTERNAL_WARNING : RECOVERY_SESSION_CHAIN_WARNING;
+		const isSessionChain = !isHead;
+
+		if (snapshot.fullText !== undefined) {
+			const merged = applyEditsToSnapshot(snapshot.fullText, currentText, edits, options, recoveryWarning);
+			if (merged !== null) return merged;
+			// Session-chain fast-path: prior in-session edit changed the same
+			// line(s) the user is now re-targeting with the stale hash. When
+			// line counts match, the edits' line numbers still resolve to the
+			// right rows — replay onto the current text directly.
+			if (isSessionChain) return replaySessionChainOnCurrent(snapshot.fullText, currentText, edits, options);
+			return null;
+		}
+
+		const overlayText = buildSparseOverlayText(currentText, snapshot.lines);
+		if (computeFileHash(overlayText) !== fileHash) return null;
+		return applyEditsToSnapshot(overlayText, currentText, edits, options, recoveryWarning);
+	}
+}

package/src/snapshots.ts

@@ -0,0 +1,171 @@
+/**
+ * Per-session snapshot store used by {@link Recovery} to rescue patches when
+ * a section's file hash has drifted (file changed externally or a prior
+ * in-session edit advanced the hash).
+ *
+ * Producers (typically a `read` tool) record snapshots as they observe file
+ * content. Consumers (the patcher) query for the snapshot whose hash matches
+ * a stale section, then 3-way-merge the would-be edit onto the live content.
+ *
+ * The abstract base class lets callers plug in whatever storage they like
+ * (LRU, persistent SQLite, etc.). {@link InMemorySnapshotStore} ships as a
+ * sensible default backed by `lru-cache` so paths age out automatically.
+ */
+import { LRUCache } from "lru-cache/raw";
+
+/**
+ * One snapshot of a file as it was observed at a point in time. Either the
+ * full text is recorded (`fullText` set) for full-file reads, or a sparse
+ * map of `(lineNumber, content)` pairs for partial views (search matches,
+ * range reads).
+ */
+export interface Snapshot {
+	/** 1-indexed line number → exact content as observed. */
+	readonly lines: Map<number, string>;
+	/** Full normalized text when the read observed the whole file. */
+	fullText?: string;
+	/** 4-hex hash carried alongside the read, when known. */
+	fileHash?: string;
+	/** Timestamp (ms since epoch) the snapshot was recorded. */
+	recordedAt: number;
+}
+
+/** Optional metadata supplied at snapshot record time. */
+export interface SnapshotMetadata {
+	/** Full normalized text, when the producer observed the whole file. */
+	fullText?: string;
+	/** 4-hex hash carried by the read, when known. */
+	fileHash?: string;
+}
+
+/**
+ * Storage seam for file-content snapshots. The patcher calls {@link head}
+ * for the latest snapshot of a path and {@link byHash} when it needs the
+ * specific historical snapshot that matches a section's stale hash.
+ */
+export abstract class SnapshotStore {
+	/** Most-recent snapshot for `path`, or `null` if none. */
+	abstract head(path: string): Snapshot | null;
+
+	/** Most-recent snapshot for `path` whose `fileHash` equals `fileHash`. */
+	abstract byHash(path: string, fileHash: string): Snapshot | null;
+
+	/** Record a contiguous run of lines (e.g. from a `read` tool). `startLine` is 1-indexed. */
+	abstract recordContiguous(
+		path: string,
+		startLine: number,
+		lines: readonly string[],
+		metadata?: SnapshotMetadata,
+	): void;
+
+	/** Record sparse `(lineNumber, content)` pairs (e.g. a `search` match plus context). */
+	abstract recordSparse(path: string, entries: Iterable<readonly [number, string]>, metadata?: SnapshotMetadata): void;
+
+	/** Drop the snapshot history for a single path. */
+	abstract invalidate(path: string): void;
+
+	/** Drop every snapshot history. */
+	abstract clear(): void;
+}
+
+const DEFAULT_MAX_PATHS = 30;
+const DEFAULT_MAX_SNAPSHOTS_PER_PATH = 4;
+
+function hasConflict(
+	existing: ReadonlyMap<number, string>,
+	incoming: ReadonlyArray<readonly [number, string]>,
+): boolean {
+	for (const [lineNum, content] of incoming) {
+		const prior = existing.get(lineNum);
+		if (prior !== undefined && prior !== content) return true;
+	}
+	return false;
+}
+
+function hasHashConflict(existing: Snapshot, metadata: SnapshotMetadata): boolean {
+	return metadata.fileHash !== undefined && existing.fileHash !== undefined && metadata.fileHash !== existing.fileHash;
+}
+
+function isSameSnapshotIdentity(left: Snapshot, right: Snapshot): boolean {
+	if (left.fileHash !== undefined && right.fileHash !== undefined) return left.fileHash === right.fileHash;
+	if (left.fullText !== undefined && right.fullText !== undefined) return left.fullText === right.fullText;
+	return false;
+}
+
+export interface InMemorySnapshotStoreOptions {
+	/** Maximum number of distinct paths tracked at once (default 30). LRU eviction. */
+	maxPaths?: number;
+	/** Maximum snapshots retained per path (default 4). Oldest dropped first. */
+	maxSnapshotsPerPath?: number;
+}
+
+/**
+ * In-memory {@link SnapshotStore} backed by `lru-cache`. Per-path snapshot
+ * history is a short ring (oldest dropped first); per-session path tracking
+ * is LRU-bounded so cold paths age out automatically.
+ *
+ * Newer snapshots merge into the head when their entries don't conflict and
+ * the recorded `fileHash` (if any) still agrees; otherwise a fresh snapshot
+ * is pushed onto the front of the history list.
+ */
+export class InMemorySnapshotStore extends SnapshotStore {
+	readonly #snapshots: LRUCache<string, Snapshot[]>;
+	readonly #maxSnapshotsPerPath: number;
+
+	constructor(options: InMemorySnapshotStoreOptions = {}) {
+		super();
+		this.#snapshots = new LRUCache<string, Snapshot[]>({ max: options.maxPaths ?? DEFAULT_MAX_PATHS });
+		this.#maxSnapshotsPerPath = options.maxSnapshotsPerPath ?? DEFAULT_MAX_SNAPSHOTS_PER_PATH;
+	}
+
+	head(path: string): Snapshot | null {
+		return this.#snapshots.get(path)?.[0] ?? null;
+	}
+
+	byHash(path: string, fileHash: string): Snapshot | null {
+		const history = this.#snapshots.get(path);
+		return history?.find(entry => entry.fileHash === fileHash) ?? null;
+	}
+
+	recordContiguous(path: string, startLine: number, lines: readonly string[], metadata: SnapshotMetadata = {}): void {
+		if (lines.length === 0 && metadata.fullText === undefined) return;
+		const entries: Array<readonly [number, string]> = lines.map((line, idx) => [startLine + idx, line] as const);
+		this.#record(path, entries, metadata);
+	}
+
+	recordSparse(path: string, entries: Iterable<readonly [number, string]>, metadata: SnapshotMetadata = {}): void {
+		const arr = Array.from(entries);
+		if (arr.length === 0 && metadata.fullText === undefined) return;
+		this.#record(path, arr, metadata);
+	}
+
+	invalidate(path: string): void {
+		this.#snapshots.delete(path);
+	}
+
+	clear(): void {
+		this.#snapshots.clear();
+	}
+
+	#record(path: string, entries: ReadonlyArray<readonly [number, string]>, metadata: SnapshotMetadata): void {
+		const history = this.#snapshots.get(path) ?? [];
+		const head = history[0];
+		const now = Date.now();
+		if (head && !hasConflict(head.lines, entries) && !hasHashConflict(head, metadata)) {
+			for (const [lineNum, content] of entries) head.lines.set(lineNum, content);
+			if (metadata.fullText !== undefined) head.fullText = metadata.fullText;
+			if (metadata.fileHash !== undefined) head.fileHash = metadata.fileHash;
+			head.recordedAt = now;
+			// `get` above already touched LRU recency for this key.
+			return;
+		}
+
+		const nextSnapshot: Snapshot = {
+			lines: new Map(entries),
+			...metadata,
+			recordedAt: now,
+		};
+		const deduped = history.filter(entry => !isSameSnapshotIdentity(entry, nextSnapshot));
+		this.#snapshots.set(path, [nextSnapshot, ...deduped].slice(0, this.#maxSnapshotsPerPath));
+	}
+}

package/src/stream.ts

@@ -0,0 +1,132 @@
+/**
+ * Lazily format a stream of UTF-8 bytes into hashline-numbered lines, yielded
+ * as bounded text chunks. Used to send `read`-style file content to consumers
+ * without materializing the full file at once.
+ *
+ * Each yielded chunk is at most {@link StreamOptions.maxChunkLines} lines and
+ * at most {@link StreamOptions.maxChunkBytes} UTF-8 bytes (whichever fires
+ * first).
+ */
+import { formatNumberedLine } from "./format";
+import type { StreamOptions } from "./types";
+
+interface ResolvedStreamOptions {
+	startLine: number;
+	maxChunkLines: number;
+	maxChunkBytes: number;
+}
+
+function resolveStreamOptions(options: StreamOptions): ResolvedStreamOptions {
+	return {
+		startLine: options.startLine ?? 1,
+		maxChunkLines: options.maxChunkLines ?? 200,
+		maxChunkBytes: options.maxChunkBytes ?? 64 * 1024,
+	};
+}
+
+interface ChunkEmitter {
+	pushLine: (line: string) => string[];
+	flush: () => string | undefined;
+}
+
+function createChunkEmitter(options: ResolvedStreamOptions): ChunkEmitter {
+	let lineNumber = options.startLine;
+	let outLines: string[] = [];
+	let outBytes = 0;
+
+	const flush = (): string | undefined => {
+		if (outLines.length === 0) return undefined;
+		const chunk = outLines.join("\n");
+		outLines = [];
+		outBytes = 0;
+		return chunk;
+	};
+
+	const pushLine = (line: string): string[] => {
+		const formatted = formatNumberedLine(lineNumber, line);
+		lineNumber++;
+
+		const chunks: string[] = [];
+		const sepBytes = outLines.length === 0 ? 0 : 1;
+		const lineBytes = Buffer.byteLength(formatted, "utf-8");
+		const wouldOverflow =
+			outLines.length >= options.maxChunkLines || outBytes + sepBytes + lineBytes > options.maxChunkBytes;
+
+		if (outLines.length > 0 && wouldOverflow) {
+			const flushed = flush();
+			if (flushed) chunks.push(flushed);
+		}
+
+		outLines.push(formatted);
+		outBytes += (outLines.length === 1 ? 0 : 1) + lineBytes;
+
+		if (outLines.length >= options.maxChunkLines || outBytes >= options.maxChunkBytes) {
+			const flushed = flush();
+			if (flushed) chunks.push(flushed);
+		}
+		return chunks;
+	};
+
+	return { pushLine, flush };
+}
+
+function isReadableStream(value: unknown): value is ReadableStream<Uint8Array> {
+	return (
+		typeof value === "object" &&
+		value !== null &&
+		"getReader" in value &&
+		typeof (value as { getReader?: unknown }).getReader === "function"
+	);
+}
+
+async function* bytesFromReadableStream(stream: ReadableStream<Uint8Array>): AsyncGenerator<Uint8Array> {
+	const reader = stream.getReader();
+	try {
+		while (true) {
+			const { done, value } = await reader.read();
+			if (done) return;
+			if (value) yield value;
+		}
+	} finally {
+		reader.releaseLock();
+	}
+}
+
+export async function* streamHashLines(
+	source: ReadableStream<Uint8Array> | AsyncIterable<Uint8Array>,
+	options: StreamOptions = {},
+): AsyncGenerator<string> {
+	const resolved = resolveStreamOptions(options);
+	const decoder = new TextDecoder("utf-8");
+	const chunks = isReadableStream(source) ? bytesFromReadableStream(source) : source;
+	const emitter = createChunkEmitter(resolved);
+
+	let pending = "";
+	let sawAnyLine = false;
+
+	for await (const chunk of chunks) {
+		pending += decoder.decode(chunk, { stream: true });
+		let nl = pending.indexOf("\n");
+		while (nl !== -1) {
+			const raw = pending.slice(0, nl);
+			const line = raw.endsWith("\r") ? raw.slice(0, -1) : raw;
+			sawAnyLine = true;
+			for (const out of emitter.pushLine(line)) yield out;
+			pending = pending.slice(nl + 1);
+			nl = pending.indexOf("\n");
+		}
+	}
+
+	pending += decoder.decode();
+	if (pending.length > 0) {
+		sawAnyLine = true;
+		const tail = pending.endsWith("\r") ? pending.slice(0, -1) : pending;
+		for (const out of emitter.pushLine(tail)) yield out;
+	}
+	if (!sawAnyLine) {
+		for (const out of emitter.pushLine("")) yield out;
+	}
+
+	const last = emitter.flush();
+	if (last) yield last;
+}