@prometheus-ai/hashline 0.5.0

package/src/recovery.ts

@@ -0,0 +1,186 @@
+/**
+ * Recover from a stale section snapshot tag 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 a section tag resolves to a snapshot that no
+ * longer matches the live file content. The recovery class is stateless apart
+ * from the {@link SnapshotStore} it queries; the snapshot store is the seam
+ * lets you plug in your own caching strategy.
+ */
+import * as Diff from "diff";
+import { applyEdits } from "./apply";
+import { RECOVERY_EXTERNAL_WARNING, RECOVERY_SESSION_CHAIN_WARNING, RECOVERY_SESSION_REPLAY_WARNING } from "./messages";
+import type { Snapshot, SnapshotStore } from "./snapshots";
+import type { Anchor, ApplyResult, Edit } from "./types";
+
+// Section tags 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[];
+}
+
+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[],
+	recoveryWarning: string,
+): RecoveryResult | null {
+	let applied: ApplyResult;
+	try {
+		applied = applyEdits(previousText, [...edits]);
+	} 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 collectAnchorLines(edits: readonly Edit[]): number[] {
+	const lines: number[] = [];
+	for (const edit of edits) {
+		for (const anchor of getEditAnchors(edit)) lines.push(anchor.line);
+	}
+	return lines;
+}
+
+function getEditAnchors(edit: Edit): Anchor[] {
+	if (edit.kind === "delete") return [edit.anchor];
+	// Recovery only ever receives already-resolved edits (no `block`); this arm
+	// exists for type-exhaustiveness over the full `Edit` union.
+	if (edit.kind === "block") return [edit.anchor];
+	return edit.cursor.kind === "before_anchor" || edit.cursor.kind === "after_anchor" ? [edit.cursor.anchor] : [];
+}
+
+/**
+ * Returns true when every anchor line in `edits` has identical content in
+ * `previousText` and `currentText`. The session-chain replay fast-path
+ * requires this: if the prior in-session edit rewrote the line the model is
+ * now re-targeting with a stale hash, replaying onto current would silently
+ * overwrite the new content with whatever the model authored against the
+ * old content — a corruption window, not a recovery.
+ */
+function verifyAnchorContent(previousText: string, currentText: string, edits: readonly Edit[]): boolean {
+	const lines = collectAnchorLines(edits);
+	if (lines.length === 0) return true;
+	const prev = previousText.split("\n");
+	const curr = currentText.split("\n");
+	for (const line of lines) {
+		const idx = line - 1;
+		if (idx < 0 || idx >= prev.length || idx >= curr.length) return false;
+		if (prev[idx] !== curr[idx]) return false;
+	}
+	return true;
+}
+
+function replaySessionChainOnCurrent(
+	previousText: string,
+	currentText: string,
+	edits: readonly Edit[],
+): RecoveryResult | null {
+	// Two guards narrow the corruption window. Neither alone is sufficient,
+	// and even together they don't fully prove correctness — replay is the
+	// less-certain recovery mode and emits RECOVERY_SESSION_REPLAY_WARNING
+	// so the caller can verify the diff.
+	//   - Equal line counts: every line number in `edits` still resolves to
+	//     SOME logical row (no net shift across the prior chain). A
+	//     coincidental insert+delete pair can still leave indices pointing
+	//     at different logical rows than the model anchored against.
+	//   - Anchor-content alignment: the row at each anchor's line index has
+	//     identical content in previous and current. Catches the common
+	//     case of a prior edit rewriting the targeted line; can still be
+	//     coincidentally satisfied by a duplicated row at the shifted
+	//     index.
+	if (previousText.split("\n").length !== currentText.split("\n").length) return null;
+	if (!verifyAnchorContent(previousText, currentText, edits)) return null;
+	let applied: ApplyResult;
+	try {
+		applied = applyEdits(currentText, [...edits]);
+	} catch {
+		return null;
+	}
+	if (applied.text === currentText) return null;
+	return {
+		text: applied.text,
+		firstChangedLine: applied.firstChangedLine,
+		warnings: [RECOVERY_SESSION_REPLAY_WARNING, ...(applied.warnings ?? [])],
+	};
+}
+
+/** 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-tag incident. The default
+ * implementation tries two strategies in order:
+ *
+ * 1. Apply the edits on the full-file version the tag names, then 3-way-merge
+ *    the resulting patch onto the live content (handles external writes).
+ * 2. (Session chain) If that version wasn't the head, replay the edits onto
+ *    the live content directly when line counts match AND every edit's anchor
+ *    line content is unchanged between version and current — a prior in-session
+ *    edit advanced the tag and the model's anchors still name the same logical
+ *    rows. Emits a dedicated {@link RECOVERY_SESSION_REPLAY_WARNING} because
+ *    even with both guards a coincidental insert+delete pair on duplicate rows
+ *    can still land the edit on the wrong row; see {@link replaySessionChainOnCurrent}.
+ */
+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 } = args;
+		const snapshot = this.store.byHash(path, fileHash);
+		if (!snapshot) return null;
+		const isHead = isHeadSnapshot(this.store.head(path), snapshot);
+		const recoveryWarning = isHead ? RECOVERY_EXTERNAL_WARNING : RECOVERY_SESSION_CHAIN_WARNING;
+		const merged = applyEditsToSnapshot(snapshot.text, currentText, edits, recoveryWarning);
+		if (merged !== null) return merged;
+		// Session-chain fallback: the 3-way merge on the version refused.
+		// Replay onto current is gated by line-count equality AND
+		// anchor-content alignment — see `replaySessionChainOnCurrent`
+		// for why both guards together still don't fully prove correctness.
+		if (!isHead) return replaySessionChainOnCurrent(snapshot.text, currentText, edits);
+		return null;
+	}
+}

package/src/snapshots.ts

@@ -0,0 +1,128 @@
+/**
+ * Per-session snapshot store used by {@link Recovery} and {@link Patcher} to
+ * bind hashline section tags to the exact file content that minted them.
+ *
+ * A section tag is a content-derived hash of the *whole file* (see
+ * {@link computeFileHash}). Any read of byte-identical content mints the same
+ * tag, so reads of one file state fuse onto one anchor and a follow-up edit
+ * anchored at any line validates whenever the live file still hashes to it.
+ *
+ * Producers (typically `read` / `search` / `write` tools) call
+ * {@link SnapshotStore.record} with the full normalized text they observed.
+ * The store hashes it, dedups against the per-path history, and returns the
+ * tag. Consumers (the patcher) resolve a stale tag back to the recorded full
+ * text via {@link SnapshotStore.byHash} and 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`: a bounded set of paths, each with a
+ * short history of full-file versions so in-session edit chains can still
+ * recover against the version a stale tag names.
+ */
+import { LRUCache } from "lru-cache/raw";
+import { computeFileHash } from "./format";
+
+/**
+ * One full-file version observed at a point in time. The tag the model sees is
+ * {@link Snapshot.hash}; recovery replays edits against {@link Snapshot.text}.
+ */
+export interface Snapshot {
+	/** Canonical path this version belongs to. */
+	readonly path: string;
+	/** Full normalized (LF, no BOM) file text as observed. */
+	readonly text: string;
+	/** Content-derived tag for {@link Snapshot.text} (see {@link computeFileHash}). */
+	readonly hash: string;
+	/** Timestamp (ms since epoch) the version was recorded. */
+	recordedAt: number;
+}
+
+/**
+ * Storage seam for full-file version snapshots. The patcher calls {@link head}
+ * for the latest version of a path and {@link byHash} when it needs the
+ * specific historical version a section's stale tag names.
+ */
+export abstract class SnapshotStore {
+	/** Most-recently recorded version for `path`, or `null` if none. */
+	abstract head(path: string): Snapshot | null;
+
+	/** Recorded version for `path` whose tag equals `hash`, or `null`. */
+	abstract byHash(path: string, hash: string): Snapshot | null;
+
+	/** Record the full normalized text of `path` and return its content tag. */
+	abstract record(path: string, fullText: string): string;
+
+	/** Drop the version history for a single path. */
+	abstract invalidate(path: string): void;
+
+	/** Drop every version history. */
+	abstract clear(): void;
+}
+
+const DEFAULT_MAX_PATHS = 30;
+const DEFAULT_MAX_VERSIONS_PER_PATH = 4;
+
+export interface InMemorySnapshotStoreOptions {
+	/** Maximum number of distinct paths tracked at once (default 30). LRU eviction. */
+	maxPaths?: number;
+	/** Maximum full-file versions retained per path (default 4). Oldest dropped first. */
+	maxVersionsPerPath?: number;
+}
+
+/**
+ * In-memory {@link SnapshotStore} backed by `lru-cache`. Per-path history is a
+ * short ring of full-file versions (oldest dropped first); per-session path
+ * tracking is LRU-bounded so cold paths age out automatically.
+ *
+ * Recording byte-identical content again refreshes recency and reuses the
+ * existing tag (read fusion); recording new content unshifts a fresh version
+ * onto the front of the path history.
+ */
+export class InMemorySnapshotStore extends SnapshotStore {
+	readonly #versions: LRUCache<string, Snapshot[]>;
+	readonly #maxVersionsPerPath: number;
+
+	constructor(options: InMemorySnapshotStoreOptions = {}) {
+		super();
+		this.#versions = new LRUCache<string, Snapshot[]>({ max: options.maxPaths ?? DEFAULT_MAX_PATHS });
+		this.#maxVersionsPerPath = options.maxVersionsPerPath ?? DEFAULT_MAX_VERSIONS_PER_PATH;
+	}
+
+	head(path: string): Snapshot | null {
+		return this.#versions.get(path)?.[0] ?? null;
+	}
+
+	byHash(path: string, hash: string): Snapshot | null {
+		const history = this.#versions.get(path);
+		return history?.find(version => version.hash === hash) ?? null;
+	}
+
+	record(path: string, fullText: string): string {
+		const hash = computeFileHash(fullText);
+		// `get` refreshes LRU recency for `path`.
+		const history = this.#versions.get(path) ?? [];
+		const existing = history.find(version => version.hash === hash);
+		if (existing) {
+			// Same content state observed again: refresh recency and promote to
+			// head (it is the current file content), then reuse the tag.
+			existing.recordedAt = Date.now();
+			if (history[0] !== existing) {
+				this.#versions.set(path, [existing, ...history.filter(version => version !== existing)]);
+			}
+			return hash;
+		}
+
+		const snapshot: Snapshot = { path, text: fullText, hash, recordedAt: Date.now() };
+		this.#versions.set(path, [snapshot, ...history].slice(0, this.#maxVersionsPerPath));
+		return hash;
+	}
+
+	invalidate(path: string): void {
+		this.#versions.delete(path);
+	}
+
+	clear(): void {
+		this.#versions.clear();
+	}
+}

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;
+}