@oh-my-pi/hashline 15.5.4

package/src/messages.ts

@@ -0,0 +1,76 @@
+/**
+ * Centralized error and warning text emitted by the hashline parser, applier,
+ * and patcher. Consolidating these as named constants makes them easy to
+ * audit and keeps wording stable across the rendering paths that surface
+ * them.
+ */
+
+/** Lines of context shown either side of a hash mismatch. */
+export const MISMATCH_CONTEXT = 2;
+
+/** Optional patch envelope start marker; silently consumed when present. */
+export const BEGIN_PATCH_MARKER = "*** Begin Patch";
+
+/** Optional patch envelope end marker; terminates parsing when encountered. */
+export const END_PATCH_MARKER = "*** End Patch";
+
+/**
+ * Recovery sentinel emitted by an agent loop when a contaminated tool-call
+ * stream is truncated mid-call. Behaves like {@link END_PATCH_MARKER} for
+ * parsing — terminates the line loop — and additionally surfaces a warning
+ * so the caller knows to re-issue any remaining edits.
+ */
+export const ABORT_MARKER = "*** Abort";
+
+/** Warning text appended to the tool result when {@link ABORT_MARKER} terminates parsing. */
+export const ABORT_WARNING =
+	"Tool stream truncated mid-call due to detected output corruption. Applied ops above are valid. Re-issue any remaining edits.";
+
+/**
+ * Warning text appended when two consecutive `A-B:` ops on the exact same
+ * range get coalesced (model painted a before/after pair). The second op wins;
+ * the first op's payload is silently discarded.
+ */
+export const REPLACE_PAIR_COALESCED_WARNING =
+	"Detected an identical-range before/after replace pair; kept only the second block's payload. Issue ONE op per range — the payload is the final desired content, never both old and new.";
+
+/**
+ * Warning text appended when un-prefixed continuation lines are accepted as
+ * implicit payload (lenient legacy behavior). The author wrote a multi-line
+ * replace without `+` prefixes; the parser accepted it because the lines did
+ * not classify as ops/headers/payloads, but the canonical syntax requires `+`
+ * on every continuation line after the op.
+ */
+export const IMPLICIT_CONTINUATION_WARNING =
+	"Accepted continuation line(s) without the `+` prefix as implicit payload. Canonical syntax is `A-B:` followed by `+` on every continuation row; without `+`, lines that look like ops will be parsed as new ops instead of payload. Prefer the explicit form.";
+
+/**
+ * Warning text appended when an inner `LINE:TEXT` (or sub-range `A-B:TEXT`)
+ * op arrives while an outer `A-B:` replace is still pending and the inner
+ * anchor falls inside the outer range. The author used the read-output
+ * `LINE:TEXT` format as if it were a payload-continuation line; we strip the
+ * `LINE:` prefix and append the body to the pending payload, but warn so the
+ * canonical `+`-continuation form remains preferred.
+ */
+export const PAYLOAD_LINE_PREFIX_DEMOTED_WARNING =
+	"Detected one or more `LINE:TEXT` lines whose anchors fell inside a pending replace range; treated them as payload-continuation lines and stripped the `LINE:` prefix. Inside an `A-B:` block, every payload line must be on its own row prefixed with `+` — never reuse the read-output gutter format.";
+
+/**
+ * Warning text appended when an op carries an inline payload (`LINE:TEXT`,
+ * `LINE↑CONTENT`, `LINE↓CONTENT`). Canonical syntax is the bare op followed
+ * by `+`-prefixed payload rows on the next line(s).
+ */
+export const INLINE_PAYLOAD_ACCEPTED_WARNING =
+	"Accepted inline payload on the op line (e.g. `LINE:CONTENT`, `LINE↑CONTENT`). Canonical syntax is the bare op followed by `+`-prefixed payload rows on the next line(s). Prefer the explicit form.";
+
+/** Warning text emitted by `Recovery` when an external write fits a cached snapshot. */
+export const RECOVERY_EXTERNAL_WARNING =
+	"Recovered from a stale file hash using a previous read snapshot (file changed externally between read and edit).";
+
+/** Warning text emitted by `Recovery` when a prior in-session edit advanced the hash. */
+export const RECOVERY_SESSION_CHAIN_WARNING =
+	"Recovered from a stale file hash using an earlier in-session snapshot (the file hash advanced after a prior edit in this session).";
+
+/** Warning text emitted by `Recovery` when the session-chain fast-path was taken. */
+export const RECOVERY_SESSION_REPLAY_WARNING =
+	"Recovered by replaying your edits onto the current file content — your previous edit in this session changed line(s) you re-targeted with a stale hash. Verify the diff matches your intent before continuing.";

package/src/mismatch.ts

@@ -0,0 +1,121 @@
+/**
+ * Error type raised when a section's file-hash does not match the live file
+ * content and recovery is unavailable / has failed.
+ *
+ * Carries enough context to render a useful diagnostic: the anchored lines
+ * plus a couple of lines of surrounding context. The {@link MismatchError}
+ * formats this into a message at construction time.
+ */
+import { formatNumberedLine, HL_FILE_HASH_SEP, HL_FILE_PREFIX } from "./format";
+import { MISMATCH_CONTEXT } from "./messages";
+
+const LINE_REF_RE = /^\s*[>+\-*]*\s*(\d+)(?::.*)?\s*$/;
+
+/** Format the required-shape diagnostic shown when a line reference is malformed. */
+export function formatFullAnchorRequirement(raw?: string): string {
+	const received = raw === undefined ? "" : ` Received ${JSON.stringify(raw)}.`;
+	return (
+		`a bare line number from read/search output plus the section header file hash ` +
+		`(for example ${HL_FILE_PREFIX}src/foo.ts${HL_FILE_HASH_SEP}1a2b and line "160")${received}`
+	);
+}
+
+/** Parse a decorated bare line-number anchor like `42`, `*42:foo`, ` > 7`. */
+export function parseTag(ref: string): { line: number } {
+	const match = ref.match(LINE_REF_RE);
+	if (!match) {
+		throw new Error(`Invalid line reference. Expected ${formatFullAnchorRequirement(ref)}.`);
+	}
+	const line = Number.parseInt(match[1], 10);
+	if (line < 1) throw new Error(`Line number must be >= 1, got ${line} in "${ref}".`);
+	return { line };
+}
+
+export interface MismatchDetails {
+	path?: string;
+	expectedFileHash: string;
+	actualFileHash: string;
+	fileLines: string[];
+	anchorLines?: readonly number[];
+}
+
+function getMismatchDisplayLines(anchorLines: readonly number[], fileLines: string[]): number[] {
+	const displayLines = new Set<number>();
+	for (const line of anchorLines) {
+		if (line < 1 || line > fileLines.length) continue;
+		const lo = Math.max(1, line - MISMATCH_CONTEXT);
+		const hi = Math.min(fileLines.length, line + MISMATCH_CONTEXT);
+		for (let lineNum = lo; lineNum <= hi; lineNum++) displayLines.add(lineNum);
+	}
+	return [...displayLines].sort((a, b) => a - b);
+}
+
+/**
+ * Raised when a hashline section's file hash doesn't match the live file's
+ * content (and recovery, if configured, declined the merge). Carries the
+ * file lines plus anchored lines so renderers can produce a richer
+ * diagnostic via {@link MismatchError.displayMessage}.
+ */
+export class MismatchError extends Error {
+	readonly path: string | undefined;
+	readonly expectedFileHash: string;
+	readonly actualFileHash: string;
+	readonly fileLines: string[];
+	readonly anchorLines: readonly number[];
+
+	constructor(details: MismatchDetails) {
+		super(MismatchError.formatMessage(details));
+		this.name = "MismatchError";
+		this.path = details.path;
+		this.expectedFileHash = details.expectedFileHash;
+		this.actualFileHash = details.actualFileHash;
+		this.fileLines = details.fileLines;
+		this.anchorLines = details.anchorLines ?? [];
+	}
+
+	get displayMessage(): string {
+		return MismatchError.formatDisplayMessage({
+			path: this.path,
+			expectedFileHash: this.expectedFileHash,
+			actualFileHash: this.actualFileHash,
+			fileLines: this.fileLines,
+			anchorLines: this.anchorLines,
+		});
+	}
+
+	static rejectionHeader(details: MismatchDetails): string[] {
+		const pathText = details.path ? ` for ${details.path}` : "";
+		return [
+			`Edit rejected${pathText}: file changed between read and edit.`,
+			`Section is bound to ${HL_FILE_HASH_SEP}${details.expectedFileHash}, but the current file hashes to ${HL_FILE_HASH_SEP}${details.actualFileHash}. If your previous edit in this session modified this file, copy the ${HL_FILE_PREFIX}path${HL_FILE_HASH_SEP}newhash from that edit's response. Otherwise re-read the file before retrying.`,
+		];
+	}
+
+	static formatDisplayMessage(details: MismatchDetails): string {
+		return MismatchError.formatMessage(details);
+	}
+
+	static formatMessage(details: MismatchDetails): string {
+		const anchorSet = new Set(details.anchorLines ?? []);
+		const lines = MismatchError.rejectionHeader(details);
+		const displayLines = getMismatchDisplayLines(details.anchorLines ?? [], details.fileLines);
+		if (displayLines.length === 0) return lines.join("\n");
+		lines.push("");
+		let previous = -1;
+		for (const lineNum of displayLines) {
+			if (previous !== -1 && lineNum > previous + 1) lines.push("...");
+			previous = lineNum;
+			const text = details.fileLines[lineNum - 1] ?? "";
+			const marker = anchorSet.has(lineNum) ? "*" : " ";
+			lines.push(`${marker}${formatNumberedLine(lineNum, text)}`);
+		}
+		return lines.join("\n");
+	}
+}
+
+/** Throws when the line reference is out of bounds for the given file. */
+export function validateLineRef(ref: { line: number }, fileLines: string[]): void {
+	if (ref.line < 1 || ref.line > fileLines.length) {
+		throw new Error(`Line ${ref.line} does not exist (file has ${fileLines.length} lines)`);
+	}
+}

package/src/normalize.ts

@@ -0,0 +1,38 @@
+/**
+ * Minimal text-shape normalization: line-ending detection / round-trip and
+ * BOM stripping. The patcher uses these to canonicalize text to LF before
+ * applying edits and to restore the original shape on write-back.
+ */
+
+export type LineEnding = "\r\n" | "\n";
+
+/** Detect the first line ending style in `content`. Defaults to LF when neither is present. */
+export function detectLineEnding(content: string): LineEnding {
+	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";
+}
+
+/** Normalize every line ending to LF. */
+export function normalizeToLF(text: string): string {
+	return text.replace(/\r\n?/g, "\n");
+}
+
+/** Re-encode LF text with the requested line ending. */
+export function restoreLineEndings(text: string, ending: LineEnding): string {
+	return ending === "\r\n" ? text.replace(/\n/g, "\r\n") : text;
+}
+
+export interface BomResult {
+	/** Either the empty string or the BOM sequence (currently UTF-8 BOM). */
+	bom: string;
+	/** Text with any leading BOM removed. */
+	text: string;
+}
+
+/** Strip a UTF-8 BOM if present and return both the BOM and the trailing text. */
+export function stripBom(content: string): BomResult {
+	return content.startsWith("\uFEFF") ? { bom: "\uFEFF", text: content.slice(1) } : { bom: "", text: content };
+}

package/src/parser.ts

@@ -0,0 +1,350 @@
+/**
+ * Token-driven state machine that turns a stream of {@link Token}s into a
+ * flat list of {@link Edit}s. Sits between the {@link Tokenizer} and the
+ * applier.
+ *
+ * Lifecycle:
+ *
+ * 1. Construct one {@link Executor} per hunk (or share one with `reset()`).
+ * 2. Feed it tokens via {@link Executor.feed}. Multi-line payloads are
+ *    accumulated across tokens until the next op flushes them.
+ * 3. Call {@link Executor.end} to flush the trailing pending op and validate
+ *    cross-op invariants (no overlapping deletes, etc.).
+ *
+ * Convenience entry point: {@link parsePatch}.
+ */
+import {
+	HL_OP_CHARS,
+	HL_OP_DELETE,
+	HL_OP_INSERT_AFTER,
+	HL_OP_INSERT_BEFORE,
+	HL_OP_REPLACE,
+	HL_PAYLOAD_PREFIX,
+} from "./format";
+import {
+	ABORT_WARNING,
+	IMPLICIT_CONTINUATION_WARNING,
+	INLINE_PAYLOAD_ACCEPTED_WARNING,
+	PAYLOAD_LINE_PREFIX_DEMOTED_WARNING,
+	REPLACE_PAIR_COALESCED_WARNING,
+} from "./messages";
+import { cloneCursor, isDeleteOpWithPayload, type ParsedRange, type Token, Tokenizer } from "./tokenizer";
+import type { Anchor, Cursor, Edit } from "./types";
+
+function validateRangeOrder(range: ParsedRange, lineNum: number): void {
+	if (range.end.line < range.start.line) {
+		throw new Error(`line ${lineNum}: range ${range.start.line}-${range.end.line} ends before it starts.`);
+	}
+}
+
+function rangesEqual(a: ParsedRange, b: ParsedRange): boolean {
+	return a.start.line === b.start.line && a.end.line === b.end.line;
+}
+
+function rangeContains(outer: ParsedRange, inner: ParsedRange): boolean {
+	return outer.start.line <= inner.start.line && inner.end.line <= outer.end.line;
+}
+
+function expandRange(range: ParsedRange): Anchor[] {
+	const anchors: Anchor[] = [];
+	for (let line = range.start.line; line <= range.end.line; line++) {
+		anchors.push({ line });
+	}
+	return anchors;
+}
+
+type PendingOp =
+	| { kind: "insert"; cursor: Cursor; lineNum: number }
+	| { kind: "replace"; range: ParsedRange; lineNum: number };
+
+interface Pending {
+	op: PendingOp;
+	payload: string[];
+}
+
+/**
+ * Token-driven state machine that turns a stream of {@link Token}s into a
+ * flat list of {@link Edit}s.
+ *
+ * `feed()` accepts tokens one at a time; multi-line payloads accumulate
+ * until the next op or {@link end} flushes them. After `terminated` flips
+ * true (on `envelope-end` or `abort`) subsequent feeds are silently ignored
+ * so callers can keep draining their tokenizer.
+ */
+export class Executor {
+	#edits: Edit[] = [];
+	#warnings: string[] = [];
+	#editIndex = 0;
+	#pending: Pending | undefined;
+	#terminated = false;
+
+	/** True once an `envelope-end` or `abort` token has been observed. */
+	get terminated(): boolean {
+		return this.#terminated;
+	}
+
+	/**
+	 * Consume one token. After `terminated` flips true subsequent feeds are
+	 * silently ignored so callers can keep draining their tokenizer without
+	 * explicit early-exit guards.
+	 */
+	feed(token: Token): void {
+		if (this.#terminated) return;
+
+		switch (token.kind) {
+			case "envelope-begin":
+				return;
+			case "envelope-end":
+				this.#terminated = true;
+				return;
+			case "abort":
+				this.#warnings.push(ABORT_WARNING);
+				this.#terminated = true;
+				return;
+			case "header":
+				this.#flushPending();
+				return;
+			case "blank":
+				return;
+			case "payload":
+				this.#handlePayload(token.text, token.lineNum);
+				return;
+			case "raw":
+				this.#handleRaw(token.text, token.lineNum);
+				return;
+			case "op-delete":
+				this.#flushPending();
+				if (token.trailingPayload) {
+					throw new Error(
+						`line ${token.lineNum}: ${HL_OP_DELETE} deletes only. Payload is forbidden after ${HL_OP_DELETE}; use ${HL_OP_REPLACE} to replace.`,
+					);
+				}
+				validateRangeOrder(token.range, token.lineNum);
+				for (const anchor of expandRange(token.range)) {
+					this.#edits.push({ kind: "delete", anchor, lineNum: token.lineNum, index: this.#editIndex++ });
+				}
+				return;
+			case "op-insert":
+				this.#flushPending();
+				this.#pending = {
+					op: { kind: "insert", cursor: token.cursor, lineNum: token.lineNum },
+					payload: [],
+				};
+				if (token.inlineBody !== undefined) {
+					this.#pending.payload.push(token.inlineBody);
+					if (!this.#warnings.includes(INLINE_PAYLOAD_ACCEPTED_WARNING)) {
+						this.#warnings.push(INLINE_PAYLOAD_ACCEPTED_WARNING);
+					}
+				}
+				return;
+			case "op-replace":
+				validateRangeOrder(token.range, token.lineNum);
+				if (this.#pending !== undefined && this.#pending.op.kind === "replace") {
+					const outer = this.#pending.op.range;
+					const inner = token.range;
+					if (rangesEqual(outer, inner)) {
+						// Identical-range before/after pair. Drop the "before" payload
+						// silently; the second op proceeds as the lone winner. Other
+						// overlap shapes (different ranges, replace+delete, delete+delete)
+						// still hit the post-hoc validator.
+						this.#pending = undefined;
+						if (!this.#warnings.includes(REPLACE_PAIR_COALESCED_WARNING)) {
+							this.#warnings.push(REPLACE_PAIR_COALESCED_WARNING);
+						}
+					} else if (rangeContains(outer, inner)) {
+						// Model wrote a payload line in read-output `LINE:TEXT` format
+						// (or `A-B:TEXT` for a sub-range) inside an outer `A-B:` block.
+						// The tokenizer can't tell payload from op when the anchor and
+						// sigil shape are identical, so demote: append the op's inline
+						// body to the pending payload, strip the `LINE:` prefix, and
+						// keep accumulating. Without this the inner anchors would each
+						// register as their own delete and clash with the outer range.
+						this.#pending.payload.push(token.inlineBody ?? "");
+						if (!this.#warnings.includes(PAYLOAD_LINE_PREFIX_DEMOTED_WARNING)) {
+							this.#warnings.push(PAYLOAD_LINE_PREFIX_DEMOTED_WARNING);
+						}
+						return;
+					}
+				}
+				this.#flushPending();
+				this.#pending = {
+					op: { kind: "replace", range: token.range, lineNum: token.lineNum },
+					payload: [],
+				};
+				if (token.inlineBody !== undefined) {
+					this.#pending.payload.push(token.inlineBody);
+					if (!this.#warnings.includes(INLINE_PAYLOAD_ACCEPTED_WARNING)) {
+						this.#warnings.push(INLINE_PAYLOAD_ACCEPTED_WARNING);
+					}
+				}
+				return;
+		}
+	}
+
+	/**
+	 * Flush any open pending op (with its full accumulated payload, including
+	 * explicit `+` blank lines) and return the accumulated edits and
+	 * warnings. The executor is single-use; {@link reset} is required for
+	 * reuse.
+	 *
+	 * Throws if two replace/delete ops target the same line with non-identical
+	 * shapes (different ranges, replace+delete, delete+delete). Identical-range
+	 * `A-B:` pairs in the same hunk are coalesced last-wins by `feed()` with a
+	 * warning, so they never reach the validator.
+	 */
+	end(): { edits: Edit[]; warnings: string[] } {
+		this.#flushPending();
+		this.#validateNoOverlappingDeletes();
+		return { edits: this.#edits, warnings: this.#warnings };
+	}
+
+	/** Reset to a fresh state so the same instance can drive another parse. */
+	reset(): void {
+		this.#edits = [];
+		this.#warnings = [];
+		this.#editIndex = 0;
+		this.#pending = undefined;
+		this.#terminated = false;
+	}
+
+	/**
+	 * Each `:` / `!` op contributes a delete edit per line in its range; if
+	 * any line ends up targeted by deletes originating from two different
+	 * source ops (distinguished by their `lineNum`), the patch is internally
+	 * inconsistent. Identical-range `A-B:` pairs are already collapsed by
+	 * `feed()`; remaining shapes here are an `A-B:` that overlaps a later
+	 * `N!`/`N:` with a different range, or two `!` deletes on the same line.
+	 * The applier would run both literally and the file would end up with two
+	 * copies of the line, not a chosen winner.
+	 */
+	#validateNoOverlappingDeletes(): void {
+		const sourceLinesByAnchor = new Map<number, number[]>();
+		for (const edit of this.#edits) {
+			if (edit.kind !== "delete") continue;
+			let sourceLines = sourceLinesByAnchor.get(edit.anchor.line);
+			if (sourceLines === undefined) {
+				sourceLines = [];
+				sourceLinesByAnchor.set(edit.anchor.line, sourceLines);
+			}
+			if (!sourceLines.includes(edit.lineNum)) sourceLines.push(edit.lineNum);
+		}
+		for (const [anchorLine, sourceLines] of sourceLinesByAnchor) {
+			if (sourceLines.length < 2) continue;
+			const [firstOp, secondOp] = [...sourceLines].sort((a, b) => a - b);
+			throw new Error(
+				`line ${secondOp}: anchor line ${anchorLine} is already targeted by the ${HL_OP_REPLACE}/${HL_OP_DELETE} op on line ${firstOp}. ` +
+					`Issue ONE op per range; payload is only the final desired content, never a before/after pair.`,
+			);
+		}
+	}
+
+	#handlePayload(text: string, lineNum: number): void {
+		if (this.#pending) {
+			this.#pending.payload.push(text);
+			return;
+		}
+
+		throw new Error(
+			`line ${lineNum}: payload line has no preceding ${HL_OP_INSERT_BEFORE}, ${HL_OP_INSERT_AFTER}, ${HL_OP_REPLACE}, or ${HL_OP_DELETE} operation. ` +
+				`Got ${JSON.stringify(`${HL_PAYLOAD_PREFIX}${text}`)}.`,
+		);
+	}
+
+	#handleRaw(text: string, lineNum: number): void {
+		if (this.#pending) {
+			if (text.trim().length === 0) return;
+			// Lenient legacy fallback: the tokenizer routes a line to `raw` only
+			// when it does not parse as an op, header, payload, or envelope
+			// marker. A `raw` token while a pending op exists is therefore an
+			// unambiguous continuation row that the author wrote without the
+			// `+` prefix. Accept it as payload and warn so the canonical
+			// `+`-prefixed form remains preferred.
+			this.#pending.payload.push(text);
+			if (!this.#warnings.includes(IMPLICIT_CONTINUATION_WARNING)) {
+				this.#warnings.push(IMPLICIT_CONTINUATION_WARNING);
+			}
+			return;
+		}
+
+		// Whitespace-only raw lines outside any pending op are silently dropped;
+		// fully empty lines arrive as `blank` tokens.
+		if (text.trim().length === 0) return;
+		// Orphan raw text outside any pending op: pick the most specific
+		// diagnostic so the user sees the actionable hint.
+		if (isDeleteOpWithPayload(text)) {
+			throw new Error(
+				`line ${lineNum}: ${HL_OP_DELETE} deletes only. Payload is forbidden after ${HL_OP_DELETE}; use ${HL_OP_REPLACE} to replace.`,
+			);
+		}
+
+		const firstChar = text[0];
+		const startsWithOp = firstChar !== undefined && HL_OP_CHARS.includes(firstChar);
+		if (startsWithOp || firstChar === "-" || firstChar === "@" || firstChar === "«" || firstChar === "»") {
+			throw new Error(
+				`line ${lineNum}: unrecognized op. Use LINE${HL_OP_INSERT_BEFORE} (insert before), LINE${HL_OP_INSERT_AFTER} (insert after), LINE${HL_OP_REPLACE} / A-B${HL_OP_REPLACE} (replace), or LINE${HL_OP_DELETE} / A-B${HL_OP_DELETE} (delete). ` +
+					`Got ${JSON.stringify(text)}.`,
+			);
+		}
+
+		throw new Error(
+			`line ${lineNum}: payload line has no preceding ${HL_OP_INSERT_BEFORE}, ${HL_OP_INSERT_AFTER}, ${HL_OP_REPLACE}, or ${HL_OP_DELETE} operation. ` +
+				`Got ${JSON.stringify(text)}.`,
+		);
+	}
+
+	#flushPending(): void {
+		const pending = this.#pending;
+		if (!pending) return;
+
+		const { op, payload } = pending;
+		const linesToInsert = payload.length === 0 ? [""] : payload;
+
+		if (op.kind === "insert") {
+			for (const text of linesToInsert) {
+				this.#edits.push({
+					kind: "insert",
+					cursor: cloneCursor(op.cursor),
+					text,
+					lineNum: op.lineNum,
+					index: this.#editIndex++,
+				});
+			}
+		} else {
+			for (const text of linesToInsert) {
+				this.#edits.push({
+					kind: "insert",
+					cursor: { kind: "before_anchor", anchor: { ...op.range.start } },
+					text,
+					lineNum: op.lineNum,
+					index: this.#editIndex++,
+				});
+			}
+			for (const anchor of expandRange(op.range)) {
+				this.#edits.push({ kind: "delete", anchor, lineNum: op.lineNum, index: this.#editIndex++ });
+			}
+		}
+
+		this.#pending = undefined;
+	}
+}
+
+/**
+ * Drive a full hashline diff through the tokenizer + executor pipeline and
+ * return the resulting edits plus any parse-time warnings. This is the
+ * convenience entry point most callers want; reach for {@link Tokenizer} /
+ * {@link Executor} directly only when you need streaming feeds, cross-section
+ * state, or custom token handling.
+ */
+export function parsePatch(diff: string): { edits: Edit[]; warnings: string[] } {
+	const tokenizer = new Tokenizer();
+	const executor = new Executor();
+	const drain = (tokens: Token[]): void => {
+		for (const token of tokens) {
+			if (executor.terminated) return;
+			executor.feed(token);
+		}
+	};
+	drain(tokenizer.feed(diff));
+	drain(tokenizer.end());
+	return executor.end();
+}