@oh-my-pi/hashline 15.5.4

package/src/diff-preview.ts

@@ -0,0 +1,49 @@
+/**
+ * Re-number a unified diff that uses the `+<lineNum>|content` /
+ * `-<lineNum>|content` / ` <lineNum>|content` line format into a compact
+ * preview that anchors every line to its post-edit position. Added lines,
+ * removed lines, and context lines all end up with a hashline-style anchor
+ * so a follow-up edit can reuse them directly.
+ *
+ * This is intentionally decoupled from the diff producer: anything that
+ * emits the `<sign><lineNum>|<content>` shape works.
+ */
+import type { CompactDiffOptions, CompactDiffPreview } from "./types";
+
+export function buildCompactDiffPreview(diff: string, _options: CompactDiffOptions = {}): CompactDiffPreview {
+	const lines = diff.length === 0 ? [] : diff.split("\n");
+	let addedLines = 0;
+	let removedLines = 0;
+
+	// External diff producers number `+` lines with the post-edit line number,
+	// `-` lines with the pre-edit line number, and context lines with the
+	// pre-edit line number. To emit fresh line numbers usable for follow-up
+	// edits, convert context-line numbers to post-edit positions by tracking
+	// the running offset (added so far - removed so far) as we walk the diff.
+	const formatted = lines.map(line => {
+		const kind = line[0];
+		if (kind !== "+" && kind !== "-" && kind !== " ") return line;
+
+		const body = line.slice(1);
+		const sep = body.indexOf("|");
+		if (sep === -1) return line;
+
+		const lineNumber = Number.parseInt(body.slice(0, sep), 10);
+		const content = body.slice(sep + 1);
+
+		switch (kind) {
+			case "+":
+				addedLines++;
+				return `+${lineNumber}:${content}`;
+			case "-":
+				removedLines++;
+				return `-${lineNumber}:${content}`;
+			default: {
+				const newLineNumber = lineNumber + addedLines - removedLines;
+				return ` ${newLineNumber}:${content}`;
+			}
+		}
+	});
+
+	return { preview: formatted.join("\n"), addedLines, removedLines };
+}

package/src/format.ts

@@ -0,0 +1,110 @@
+/**
+ * Hashline format primitives: sigils, separators, regex fragments, and the
+ * file-hash computation. These are the single source of truth for the
+ * parser, the tokenizer, the prompt, and the formal grammar.
+ */
+
+/** Op sigil used immediately after a line-number anchor to insert before it. */
+export const HL_OP_INSERT_BEFORE = "↑";
+/** Op sigil used immediately after a line-number anchor to insert after it. */
+export const HL_OP_INSERT_AFTER = "↓";
+/** Op sigil used after a range (or single anchor) to replace its lines. */
+export const HL_OP_REPLACE = ":";
+/** Op sigil used after a range (or single anchor) to delete its lines. */
+export const HL_OP_DELETE = "!";
+
+/** All hashline edit op sigils, concatenated for fast membership tests. */
+export const HL_OP_CHARS = `${HL_OP_INSERT_BEFORE}${HL_OP_INSERT_AFTER}${HL_OP_REPLACE}${HL_OP_DELETE}`;
+
+/** Prefix for payload continuation lines. The prefix itself is not written. */
+export const HL_PAYLOAD_PREFIX = "+";
+
+/** Hashline edit file-section header marker. */
+export const HL_FILE_PREFIX = "¶";
+
+/** Separator between a hashline file path and its file hash. */
+export const HL_FILE_HASH_SEP = "#";
+
+/** Separator between a line number and displayed line content in hashline mode. */
+export const HL_LINE_BODY_SEP = ":";
+
+function regexEscape(str: string): string {
+	return str.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+/**
+ * Decoration prefix that may precede a line number in tool output:
+ * `>` (context line in grep), `-` (removed line), `*` (match line).
+ * Any combination, in any order, surrounded by optional whitespace. Output
+ * formatters emit at most one decoration per line; the parser stays liberal
+ * because it accepts whatever the model echoes back.
+ */
+export const HL_ANCHOR_DECORATION_RE_RAW = `\\s*[>\\-*]*\\s*`;
+
+/** Capture-group regex source for a decorated bare line-number anchor. */
+export const HL_ANCHOR_RE_RAW = `${HL_ANCHOR_DECORATION_RE_RAW}(\\d+)`;
+
+/** Bare positive line-number Lid (no decorations, no captures, no anchors). */
+export const HL_LINE_RE_RAW = `[1-9]\\d*`;
+
+/** Capture-group form of {@link HL_LINE_RE_RAW}. */
+export const HL_LINE_CAPTURE_RE_RAW = `([1-9]\\d*)`;
+
+/** Four-hex-character file hash carried by a hashline section header. */
+export const HL_FILE_HASH_RE_RAW = `[0-9a-f]{4}`;
+
+/** Capture-group form of {@link HL_FILE_HASH_RE_RAW}. */
+export const HL_FILE_HASH_CAPTURE_RE_RAW = `(${HL_FILE_HASH_RE_RAW})`;
+
+/** Regex-escaped form of {@link HL_LINE_BODY_SEP}, safe for embedding inside a regex. */
+export const HL_LINE_BODY_SEP_RE_RAW = regexEscape(HL_LINE_BODY_SEP);
+
+/**
+ * Representative file hashes for use in user-facing error messages and prompt
+ * examples.
+ */
+export const HL_FILE_HASH_EXAMPLES = ["1a2b", "3c4d", "9f3e"] as const;
+
+/**
+ * Format a comma-separated list of example anchors with an optional line-number
+ * prefix, quoted for inclusion in error messages: `"160", "42", "7"`.
+ */
+export function describeAnchorExamples(linePrefix = ""): string {
+	const examples = linePrefix ? [linePrefix, `${linePrefix.slice(0, -1) || "4"}2`, "7"] : ["160", "42", "7"];
+	return examples.map(e => `"${e}"`).join(", ");
+}
+
+function normalizeFileHashText(text: string): string {
+	return text
+		.replace(/\r/g, "")
+		.split("\n")
+		.map(line => line.trimEnd())
+		.join("\n");
+}
+
+/**
+ * Compute the 4-hex-character hash carried by a hashline section header. The
+ * hash normalizes CR characters and trailing whitespace before hashing so
+ * platform line endings and display-trimmed lines do not invalidate anchors.
+ */
+export function computeFileHash(text: string): string {
+	const normalized = normalizeFileHashText(text);
+	const low16 = Bun.hash.xxHash32(normalized, 0) & 0xffff;
+	return low16.toString(16).padStart(4, "0");
+}
+
+/** Format a hashline section header for a file path and file hash. */
+export function formatHashlineHeader(filePath: string, fileHash: string): string {
+	return `${HL_FILE_PREFIX}${filePath}${HL_FILE_HASH_SEP}${fileHash}`;
+}
+
+/** Formats a single numbered line as `LINE:TEXT`. */
+export function formatNumberedLine(lineNumber: number, line: string): string {
+	return `${lineNumber}${HL_LINE_BODY_SEP}${line}`;
+}
+
+/** Format file text with hashline-mode line-number prefixes for display. */
+export function formatNumberedLines(text: string, startLine = 1): string {
+	const lines = text.split("\n");
+	return lines.map((line, i) => formatNumberedLine(startLine + i, line)).join("\n");
+}

package/src/fs.ts

@@ -0,0 +1,167 @@
+/**
+ * Storage seam for the hashline patcher. {@link Filesystem} is intentionally
+ * minimal — `readText`, `writeText`, `exists` — so any backing store can be
+ * adapted: disk, memory, S3, an LSP text-document protocol, a Git tree, a
+ * VFS, etc.
+ *
+ * The patcher does its own BOM stripping and LF normalization between
+ * {@link Filesystem.readText} and {@link Filesystem.writeText}; the FS deals
+ * only in raw text strings.
+ */
+import * as pathModule from "node:path";
+
+/**
+ * Result returned by {@link Filesystem.writeText}. The patcher echoes back
+ * `text` so adapters that transform on serialization (e.g. notebooks) can
+ * report what actually landed on disk.
+ */
+export interface WriteResult {
+	/** Final text that was persisted. May differ from the input if the FS transformed it. */
+	text: string;
+}
+
+/**
+ * ENOENT-like error thrown by {@link Filesystem.readText} when a path is
+ * missing. Carrying a `code` property keeps the contract compatible with
+ * `node:fs` callers that already check `err.code === "ENOENT"`.
+ */
+export class NotFoundError extends Error {
+	readonly code = "ENOENT";
+
+	constructor(path: string, cause?: unknown) {
+		super(`File not found: ${path}`);
+		this.name = "NotFoundError";
+		if (cause !== undefined) (this as Error & { cause?: unknown }).cause = cause;
+	}
+}
+
+/** Type guard for {@link NotFoundError} and structurally-compatible errors. */
+export function isNotFound(error: unknown): boolean {
+	if (error instanceof NotFoundError) return true;
+	if (error instanceof Error && (error as Error & { code?: string }).code === "ENOENT") return true;
+	return false;
+}
+
+/**
+ * Abstract storage backend the {@link Patcher} reads from and writes to.
+ * Subclass for new backends; the package ships {@link InMemoryFilesystem} and
+ * {@link NodeFilesystem} for the most common cases.
+ *
+ * Implementations work with raw text — the patcher handles BOM stripping and
+ * line-ending normalization itself. `readText` MUST throw {@link
+ * NotFoundError} (or any error for which {@link isNotFound} returns true)
+ * when the path doesn't exist; that's how the patcher detects a create-vs-
+ * update.
+ */
+export abstract class Filesystem {
+	/** Read the file's full text content. Throw on missing file. */
+	abstract readText(path: string): Promise<string>;
+
+	/** Validate that `path` is writable before a prepared batch starts committing. */
+	async preflightWrite(_path: string): Promise<void> {}
+
+	/** Persist `content` at `path`. Returns the actual final text that was written. */
+	abstract writeText(path: string, content: string): Promise<WriteResult>;
+
+	/** Return true when the path exists and can be read. Default: probe via {@link readText}. */
+	async exists(path: string): Promise<boolean> {
+		try {
+			await this.readText(path);
+			return true;
+		} catch (error) {
+			if (isNotFound(error)) return false;
+			throw error;
+		}
+	}
+
+	/**
+	 * Canonical path used as a key by external caches (e.g. snapshot
+	 * stores). The default is identity; override to return an absolute or
+	 * otherwise canonicalised path so producers and consumers of cached
+	 * snapshots agree on the key without each having to redo the resolution.
+	 */
+	canonicalPath(path: string): string {
+		return path;
+	}
+}
+
+/**
+ * In-memory {@link Filesystem}. Useful for tests, sandboxes, dry-runs, and as
+ * a building block for stacked adapters (e.g. an LRU layer on top).
+ */
+export class InMemoryFilesystem extends Filesystem {
+	#files = new Map<string, string>();
+
+	constructor(initial?: Iterable<readonly [string, string]>) {
+		super();
+		if (initial) {
+			for (const [path, content] of initial) this.#files.set(path, content);
+		}
+	}
+
+	async readText(path: string): Promise<string> {
+		const text = this.#files.get(path);
+		if (text === undefined) throw new NotFoundError(path);
+		return text;
+	}
+
+	async writeText(path: string, content: string): Promise<WriteResult> {
+		this.#files.set(path, content);
+		return { text: content };
+	}
+
+	async exists(path: string): Promise<boolean> {
+		return this.#files.has(path);
+	}
+
+	/** Synchronous helper for setting up fixtures without awaiting. */
+	set(path: string, content: string): void {
+		this.#files.set(path, content);
+	}
+
+	/** Synchronous helper for inspecting state without awaiting. */
+	get(path: string): string | undefined {
+		return this.#files.get(path);
+	}
+
+	/** Remove a single entry. Returns true when something was removed. */
+	delete(path: string): boolean {
+		return this.#files.delete(path);
+	}
+
+	/** Wipe all entries. */
+	clear(): void {
+		this.#files.clear();
+	}
+
+	/** Iterate `[path, content]` pairs. */
+	entries(): IterableIterator<[string, string]> {
+		return this.#files.entries();
+	}
+}
+
+/**
+ * Disk-backed {@link Filesystem} using Bun's file APIs. The default for CLI
+ * use. Paths are accepted as-is; callers responsible for any cwd or
+ * jail/sandbox resolution should wrap this with their own subclass.
+ */
+export class NodeFilesystem extends Filesystem {
+	async readText(path: string): Promise<string> {
+		const file = Bun.file(path);
+		if (!(await file.exists())) throw new NotFoundError(path);
+		return file.text();
+	}
+
+	async writeText(path: string, content: string): Promise<WriteResult> {
+		await Bun.write(path, content);
+		return { text: content };
+	}
+
+	canonicalPath(path: string): string {
+		return pathModule.resolve(path);
+	}
+
+	async exists(path: string): Promise<boolean> {
+		return Bun.file(path).exists();
+	}
+}

package/src/grammar.lark

@@ -0,0 +1,22 @@
+start: begin_patch hunk+ end_patch
+begin_patch: "*** Begin Patch" LF
+end_patch: "*** End Patch" LF?
+
+hunk: update_hunk
+update_hunk: "¶" filename ("#" file_hash)? LF line_op*
+
+filename: /([^\s#]+)/
+file_hash: /[0-9a-f]{4}/
+
+line_op: insert_before | insert_after | replace | delete
+insert_before: anchor "↑" LF payload*
+insert_after: anchor "↓" LF payload*
+replace: range ":" LF payload*
+delete: range "!" LF
+payload: "+" /[^\n]*/ LF
+
+anchor: LID | "EOF" | "BOF"
+range: LID ("-" LID)?
+LID: /[1-9]\d*/
+
+%import common.LF

package/src/index.ts

@@ -0,0 +1,16 @@
+export * from "./apply";
+export * from "./diff-preview";
+export * from "./format";
+export * from "./fs";
+export * from "./input";
+export * from "./messages";
+export * from "./mismatch";
+export * from "./normalize";
+export * from "./parser";
+export * from "./patcher";
+export * from "./prefixes";
+export * from "./recovery";
+export * from "./snapshots";
+export * from "./stream";
+export * from "./tokenizer";
+export * from "./types";

package/src/input.ts

@@ -0,0 +1,319 @@
+/**
+ * Top-level patch parser. Splits an authored hashline input into a list of
+ * {@link PatchSection}s, each rooted at a `¶PATH#HASH` header, then exposes
+ * a {@link Patch} class that gives lazy access to the parsed edits per
+ * section.
+ *
+ * The splitter is purely lexical — it doesn't know whether a section's path
+ * actually exists. That's the patcher's job.
+ */
+import * as path from "node:path";
+import { applyEdits } from "./apply";
+import { HL_FILE_HASH_SEP, HL_FILE_PREFIX } from "./format";
+import { parsePatch } from "./parser";
+import { Tokenizer } from "./tokenizer";
+import type { ApplyOptions, ApplyResult, Edit, SplitOptions } from "./types";
+
+// Pure classification — single shared tokenizer is safe.
+const TOKENIZER = new Tokenizer();
+
+function unquoteHashlinePath(pathText: string): string {
+	if (pathText.length < 2) return pathText;
+	const first = pathText[0];
+	const last = pathText[pathText.length - 1];
+	if ((first === '"' || first === "'") && first === last) return pathText.slice(1, -1);
+	return pathText;
+}
+
+function normalizeHashlinePath(rawPath: string, cwd?: string): string {
+	const unquoted = unquoteHashlinePath(rawPath.trim());
+	if (!cwd || !path.isAbsolute(unquoted)) return unquoted;
+	const relative = path.relative(path.resolve(cwd), path.resolve(unquoted));
+	const isWithinCwd = relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
+	return isWithinCwd ? relative || "." : unquoted;
+}
+
+interface RawSection {
+	path: string;
+	fileHash?: string;
+	diff: string;
+}
+
+/**
+ * Parse a `¶PATH[#hash]` header line. Returns `null` for lines that do not
+ * begin with the `¶` prefix; throws the existing "Input header must be …"
+ * error when a `¶`-prefixed line fails the strict shape (so malformed paths
+ * surface immediately instead of being silently re-classified as payload).
+ */
+function parseHashlineHeaderLine(line: string, cwd?: string): RawSection | null {
+	const trimmed = line.trimEnd();
+	if (!trimmed.startsWith(HL_FILE_PREFIX)) return null;
+
+	const token = TOKENIZER.tokenize(trimmed);
+	if (token.kind !== "header") {
+		throw new Error(
+			`Input header must be ${HL_FILE_PREFIX}PATH or ${HL_FILE_PREFIX}PATH${HL_FILE_HASH_SEP}HASH with a 4-hex file hash; got ${JSON.stringify(trimmed)}.`,
+		);
+	}
+
+	const parsedPath = normalizeHashlinePath(token.path, cwd);
+	if (parsedPath.length === 0) {
+		throw new Error(`Input header "${HL_FILE_PREFIX}" is empty; provide a file path.`);
+	}
+	return token.fileHash !== undefined
+		? { path: parsedPath, fileHash: token.fileHash, diff: "" }
+		: { path: parsedPath, diff: "" };
+}
+
+function stripLeadingBlankLines(input: string): string {
+	const stripped = input.startsWith("\uFEFF") ? input.slice(1) : input;
+	const lines = stripped.split("\n");
+	while (lines.length > 0) {
+		const head = lines[0].replace(/\r$/, "");
+		if (head.trim().length === 0 || TOKENIZER.tokenize(head).kind === "envelope-begin") {
+			lines.shift();
+			continue;
+		}
+		break;
+	}
+	return lines.join("\n");
+}
+
+/**
+ * Returns true when the input contains at least one line that the tokenizer
+ * recognizes as a hashline op. Used by streaming previews to decide whether
+ * the partial input is worth treating as a hashline patch yet.
+ */
+export function containsRecognizableHashlineOperations(input: string): boolean {
+	for (const line of input.split(/\r?\n/)) {
+		if (TOKENIZER.isOp(line)) return true;
+	}
+	return false;
+}
+
+function normalizeFallbackInput(input: string, options: SplitOptions): string {
+	const stripped = input.startsWith("\uFEFF") ? input.slice(1) : input;
+	const hasExplicitHeader = stripped
+		.split(/\r?\n/)
+		.some(rawLine => parseHashlineHeaderLine(rawLine, options.cwd) !== null);
+	if (hasExplicitHeader) return input;
+
+	if (!options.path || !containsRecognizableHashlineOperations(input)) return input;
+	const fallbackPath = normalizeHashlinePath(options.path, options.cwd);
+	if (fallbackPath.length === 0) return input;
+	return `${HL_FILE_PREFIX}${fallbackPath}\n${input}`;
+}
+
+function splitRawSections(input: string, options: SplitOptions = {}): RawSection[] {
+	const stripped = stripLeadingBlankLines(normalizeFallbackInput(input, options));
+	const lines = stripped.split(/\r?\n/);
+	const firstLine = lines[0] ?? "";
+
+	if (parseHashlineHeaderLine(firstLine, options.cwd) === null) {
+		const preview = JSON.stringify(firstLine.slice(0, 120));
+		throw new Error(
+			`input must begin with "${HL_FILE_PREFIX}PATH${HL_FILE_HASH_SEP}HASH" on the first non-blank line for anchored edits; got: ${preview}. ` +
+				`Example: "${HL_FILE_PREFIX}src/foo.ts${HL_FILE_HASH_SEP}1a2b" then edit ops.`,
+		);
+	}
+
+	const sections: RawSection[] = [];
+	let current: RawSection | undefined;
+	let currentLines: string[] = [];
+
+	const flush = () => {
+		if (!current) return;
+		const hasOps = currentLines.some(line => line.trim().length > 0);
+		if (hasOps) sections.push({ ...current, diff: currentLines.join("\n") });
+		currentLines = [];
+	};
+
+	for (const line of lines) {
+		const trimmed = line.trimEnd();
+		const token = TOKENIZER.tokenize(line);
+		if (token.kind === "envelope-end" || token.kind === "abort") break;
+		if (token.kind === "envelope-begin") continue;
+
+		// Route every `¶`-prefixed line through parseHashlineHeaderLine so
+		// malformed headers still raise the strict "Input header must be …"
+		// diagnostic (the tokenizer alone would silently classify them as
+		// payload).
+		if (trimmed.startsWith(HL_FILE_PREFIX)) {
+			const header = parseHashlineHeaderLine(line, options.cwd);
+			if (header !== null) {
+				flush();
+				current = header;
+				currentLines = [];
+				continue;
+			}
+		}
+		currentLines.push(line);
+	}
+	flush();
+	return sections;
+}
+
+/**
+ * Snapshot of one section in a parsed {@link Patch}: a target file plus the
+ * lazily-parsed list of edits that should land on it. Constructed by
+ * {@link Patch.parse}; consumers usually iterate `patch.sections` rather
+ * than build these directly.
+ */
+export class PatchSection {
+	readonly path: string;
+	readonly fileHash: string | undefined;
+	readonly diff: string;
+	#parsed: { edits: Edit[]; warnings: string[] } | undefined;
+
+	constructor(raw: RawSection) {
+		this.path = raw.path;
+		this.fileHash = raw.fileHash;
+		this.diff = raw.diff;
+	}
+
+	/**
+	 * Parse this section's diff body. Cached: subsequent calls return the
+	 * same `{ edits, warnings }` object so callers can safely call this from
+	 * multiple paths (preflight, apply, diff-preview).
+	 */
+	parse(): { edits: Edit[]; warnings: readonly string[] } {
+		this.#parsed ??= parsePatch(this.diff);
+		return this.#parsed;
+	}
+
+	/** Parsed edits for this section. */
+	get edits(): readonly Edit[] {
+		return this.parse().edits;
+	}
+
+	/** Warnings emitted during parsing of this section. */
+	get warnings(): readonly string[] {
+		return this.parse().warnings;
+	}
+
+	/**
+	 * True when at least one edit anchors to a concrete file line (range or
+	 * before/after_anchor insert). Pure BOF/EOF inserts do not count: those
+	 * are safe to apply to files that don't yet exist.
+	 */
+	get hasAnchorScopedEdit(): boolean {
+		return this.edits.some(edit => {
+			if (edit.kind === "delete") return true;
+			return edit.cursor.kind === "before_anchor" || edit.cursor.kind === "after_anchor";
+		});
+	}
+
+	/** Anchor lines touched by this section, sorted ascending and deduplicated. */
+	collectAnchorLines(): readonly number[] {
+		const lines = new Set<number>();
+		for (const edit of this.edits) {
+			if (edit.kind === "delete") {
+				lines.add(edit.anchor.line);
+				continue;
+			}
+			if (edit.cursor.kind === "before_anchor" || edit.cursor.kind === "after_anchor") {
+				lines.add(edit.cursor.anchor.line);
+			}
+		}
+		return [...lines].sort((a, b) => a - b);
+	}
+
+	/**
+	 * Apply this section's edits to `text` and return the post-edit result.
+	 * Pure: does no I/O, does not validate the section file hash. The
+	 * {@link Patcher} owns hash validation and recovery; reach for this
+	 * method directly when you've already validated the file content and
+	 * just want the result.
+	 */
+	applyTo(text: string, options: ApplyOptions = {}): ApplyResult {
+		const { edits, warnings } = this.parse();
+		const result = applyEdits(text, [...edits], options);
+		// Preserve parse warnings alongside applier warnings so consumers
+		// don't need to call `parse()` separately.
+		const merged = warnings.length === 0 ? result.warnings : [...warnings, ...(result.warnings ?? [])];
+		return merged && merged.length > 0
+			? { ...result, warnings: merged }
+			: { text: result.text, firstChangedLine: result.firstChangedLine };
+	}
+}
+
+/**
+ * A parsed hashline patch — zero or more {@link PatchSection}s, each rooted
+ * at a `¶PATH#HASH` header. Construct via {@link Patch.parse}.
+ *
+ * `Patch` is pure data: parsing is line-anchored and does not look at the
+ * filesystem. To apply a patch, hand it to {@link Patcher.apply}.
+ */
+export class Patch {
+	readonly sections: readonly PatchSection[];
+
+	private constructor(sections: PatchSection[]) {
+		this.sections = sections;
+	}
+
+	/**
+	 * Parse `input` into a {@link Patch}. `options.cwd` resolves absolute
+	 * paths inside headers to cwd-relative form; `options.path` provides a
+	 * fallback when the input lacks a header but contains hashline ops
+	 * (useful for streaming previews).
+	 *
+	 * Consecutive sections targeting the same path are merged into a single
+	 * section with concatenated diff bodies. Anchors authored against the
+	 * same file snapshot must be applied as one batch; otherwise the first
+	 * sub-edit shifts line numbers out from under the second's anchors and
+	 * validation fails.
+	 */
+	static parse(input: string, options: SplitOptions = {}): Patch {
+		const raw = mergeSamePathSections(splitRawSections(input, options));
+		return new Patch(raw.map(section => new PatchSection(section)));
+	}
+
+	/**
+	 * Parse `input` and return only the first section. Throws if the input
+	 * has zero sections. Convenience for the single-section case where the
+	 * caller already knows the patch is one hunk.
+	 */
+	static parseSingle(input: string, options: SplitOptions = {}): PatchSection {
+		const patch = Patch.parse(input, options);
+		const first = patch.sections[0];
+		if (!first) throw new Error("Patch input did not produce any sections.");
+		return first;
+	}
+}
+
+/**
+ * Collapse consecutive or interleaved sections targeting the same path into a
+ * single section with concatenated diffs. Anchors authored against the same
+ * file snapshot must be applied as one batch; otherwise the first sub-edit
+ * shifts line numbers out from under the second's anchors and validation
+ * fails. Path order is preserved by first occurrence.
+ */
+function mergeSamePathSections(sections: RawSection[]): RawSection[] {
+	const byPath = new Map<string, { fileHash?: string; diffs: string[] }>();
+	for (const section of sections) {
+		const existing = byPath.get(section.path);
+		if (existing) {
+			if (
+				existing.fileHash !== undefined &&
+				section.fileHash !== undefined &&
+				existing.fileHash !== section.fileHash
+			) {
+				throw new Error(
+					`Conflicting hashline file hashes for ${section.path}: #${existing.fileHash} and #${section.fileHash}. Re-read the file and retry with one current header.`,
+				);
+			}
+			if (existing.fileHash === undefined && section.fileHash !== undefined) existing.fileHash = section.fileHash;
+			existing.diffs.push(section.diff);
+			continue;
+		}
+		byPath.set(section.path, {
+			...(section.fileHash !== undefined ? { fileHash: section.fileHash } : {}),
+			diffs: [section.diff],
+		});
+	}
+	return Array.from(byPath, ([sectionPath, entry]) => ({
+		path: sectionPath,
+		...(entry.fileHash !== undefined ? { fileHash: entry.fileHash } : {}),
+		diff: entry.diffs.join("\n"),
+	}));
+}