@oh-my-pi/hashline 15.5.4

package/src/patcher.ts

@@ -0,0 +1,360 @@
+/**
+ * High-level patch orchestrator. Reads each section's target file via the
+ * configured {@link Filesystem}, strips BOM and normalizes line endings,
+ * validates the section file hash (with optional {@link Recovery}), applies
+ * the edits, and writes the result back through the same {@link Filesystem}.
+ *
+ * Two layers:
+ *
+ * - {@link Patcher.apply} — high-level, all-or-nothing. Preflights every
+ *   section in memory before any write hits disk, then commits in order.
+ * - {@link Patcher.prepare} / {@link Patcher.commit} — granular primitives
+ *   for callers that need per-section control (e.g. batched LSP flush,
+ *   custom interleaving). `prepare` performs all the read-side work,
+ *   validates the section file hash (with recovery), and applies the
+ *   edits in memory. `commit` writes the prepared result and records a
+ *   fresh snapshot.
+ *
+ * Because `prepare` already runs the full apply, a multi-section batch is
+ * naturally all-or-nothing: by the time any `commit` runs, every section
+ * has been validated.
+ *
+ * The patcher itself is stateless across calls; reuse one instance per
+ * filesystem configuration.
+ */
+import { applyEdits } from "./apply";
+import { computeFileHash, formatHashlineHeader, HL_FILE_HASH_SEP, HL_FILE_PREFIX } from "./format";
+import type { Filesystem, WriteResult } from "./fs";
+import { isNotFound } from "./fs";
+import type { Patch, PatchSection } from "./input";
+import { MismatchError } from "./mismatch";
+import { detectLineEnding, type LineEnding, normalizeToLF, restoreLineEndings, stripBom } from "./normalize";
+import { Recovery, type RecoveryResult } from "./recovery";
+import type { SnapshotStore } from "./snapshots";
+import type { ApplyOptions, ApplyResult, Edit } from "./types";
+
+export interface PatcherOptions {
+	/** Storage backend used for all reads and writes. */
+	fs: Filesystem;
+	/**
+	 * Optional snapshot store that enables stale-hash recovery. When set, a
+	 * section with a stale hash tries a 3-way merge against a cached
+	 * snapshot before the apply fails with {@link MismatchError}.
+	 */
+	snapshots?: SnapshotStore;
+	/**
+	 * Optional default {@link ApplyOptions} forwarded to every section.
+	 * Per-call overrides win on a key-by-key basis.
+	 */
+	applyOptions?: ApplyOptions;
+}
+
+/** Per-section result returned by {@link Patcher.apply} / {@link Patcher.commit}. */
+export interface PatchSectionResult {
+	/** Section path (as authored, after cwd-resolution at parse time). */
+	path: string;
+	/** Filesystem-canonical key for this section (e.g. absolute path). */
+	canonicalPath: string;
+	/** `"noop"` when the apply produced no change; otherwise `"create"` / `"update"`. */
+	op: "create" | "update" | "noop";
+	/** Pre-edit text (LF-normalized, BOM-stripped). */
+	before: string;
+	/** Post-edit text (LF-normalized, BOM-stripped). For `"noop"` equals `before`. */
+	after: string;
+	/** Same text as `after` but with the original BOM and line ending restored. */
+	persisted: string;
+	/** Final text that the {@link Filesystem} actually wrote (may differ if the FS transformed it). */
+	written: string;
+	/** 4-hex hash of `after`. Use to anchor follow-up edits. */
+	fileHash: string;
+	/** Hashline section header (`¶path#hash`) of the post-edit content. */
+	header: string;
+	/** 1-indexed first changed line in `after`, or `undefined` for noops. */
+	firstChangedLine?: number;
+	/** Warnings collected by the parser, applier, and (optionally) recovery. */
+	warnings: string[];
+}
+
+export interface PatcherApplyResult {
+	sections: PatchSectionResult[];
+}
+
+/**
+ * Opaque token returned by {@link Patcher.prepare}. Carries the section, the
+ * raw file content read off disk, and the in-memory apply result.
+ * {@link Patcher.commit} just writes the {@link PreparedSection.applyResult}.
+ */
+export class PreparedSection {
+	/** @internal */
+	constructor(
+		readonly section: PatchSection,
+		readonly canonicalPath: string,
+		readonly exists: boolean,
+		readonly rawContent: string,
+		readonly bom: string,
+		readonly lineEnding: LineEnding,
+		readonly normalized: string,
+		readonly applyResult: ApplyResult,
+		readonly parseWarnings: readonly string[],
+	) {}
+
+	/** Convenience: returns true when the apply produced no change. */
+	get isNoop(): boolean {
+		return this.applyResult.text === this.normalized;
+	}
+}
+
+function hasAnchorScopedEdit(edits: readonly Edit[]): boolean {
+	return edits.some(edit => {
+		if (edit.kind === "delete") return true;
+		return edit.cursor.kind === "before_anchor" || edit.cursor.kind === "after_anchor";
+	});
+}
+
+function assertSectionHashAllowed(sectionPath: string, fileHash: string | undefined, edits: readonly Edit[]): void {
+	if (fileHash !== undefined || !hasAnchorScopedEdit(edits)) return;
+	throw new Error(
+		`Missing hashline file hash for anchored edit to ${sectionPath}; use \`${HL_FILE_PREFIX}${sectionPath}${HL_FILE_HASH_SEP}hash\` from your latest read.`,
+	);
+}
+
+function recoveryToApplyResult(result: RecoveryResult): ApplyResult {
+	return {
+		text: result.text,
+		firstChangedLine: result.firstChangedLine,
+		warnings: result.warnings,
+	};
+}
+
+function mergeWarnings(...sources: ReadonlyArray<readonly string[] | undefined>): string[] {
+	const out: string[] = [];
+	for (const source of sources) {
+		if (!source) continue;
+		for (const warning of source) out.push(warning);
+	}
+	return out;
+}
+
+function assertUniqueCanonicalPaths(prepared: readonly PreparedSection[]): void {
+	const seen = new Map<string, string>();
+	for (const entry of prepared) {
+		const previous = seen.get(entry.canonicalPath);
+		if (previous !== undefined) {
+			throw new Error(
+				`Multiple hashline sections resolve to the same file (${previous} and ${entry.section.path}). Merge their ops under one header before applying.`,
+			);
+		}
+		seen.set(entry.canonicalPath, entry.section.path);
+	}
+}
+
+/**
+ * High-level patcher. Wires a {@link Filesystem} and an optional
+ * {@link SnapshotStore} together with the parsing + applying core.
+ *
+ * Construct once per FS configuration; reuse across patches.
+ */
+export class Patcher {
+	readonly fs: Filesystem;
+	readonly snapshots: SnapshotStore | undefined;
+	readonly recovery: Recovery | undefined;
+	readonly applyOptions: ApplyOptions;
+
+	constructor(options: PatcherOptions) {
+		this.fs = options.fs;
+		this.snapshots = options.snapshots;
+		this.recovery = options.snapshots ? new Recovery(options.snapshots) : undefined;
+		this.applyOptions = options.applyOptions ?? {};
+	}
+
+	/**
+	 * Apply every section in `patch`. `prepare` runs the full apply for each
+	 * section in memory before any write hits the filesystem, so a
+	 * multi-section batch is naturally all-or-nothing. Returns one
+	 * {@link PatchSectionResult} per section in the original patch order.
+	 */
+	async apply(patch: Patch, options: ApplyOptions = {}): Promise<PatcherApplyResult> {
+		const merged: ApplyOptions = { ...this.applyOptions, ...options };
+
+		// Single-section fast path.
+		if (patch.sections.length === 1) {
+			const prepared = await this.prepare(patch.sections[0], merged);
+			return { sections: [await this.commit(prepared)] };
+		}
+
+		// Prepare every section first so any failure (stale hash, missing
+		// file, parse error, in-memory no-op) surfaces before any write.
+		const prepared: PreparedSection[] = [];
+		for (const section of patch.sections) prepared.push(await this.prepare(section, merged));
+		assertUniqueCanonicalPaths(prepared);
+		for (const entry of prepared) {
+			if (entry.isNoop) {
+				throw new Error(`Edits to ${entry.section.path} resulted in no changes being made.`);
+			}
+		}
+
+		const results: PatchSectionResult[] = [];
+		for (const entry of prepared) results.push(await this.commit(entry));
+		return { sections: results };
+	}
+
+	/**
+	 * Run the preflight pass only: read, parse, validate, apply-in-memory.
+	 * No writes hit the filesystem. Use for CI checks and dry runs.
+	 */
+	async preflight(patch: Patch, options: ApplyOptions = {}): Promise<void> {
+		const merged: ApplyOptions = { ...this.applyOptions, ...options };
+		const prepared: PreparedSection[] = [];
+		for (const section of patch.sections) prepared.push(await this.prepare(section, merged));
+		assertUniqueCanonicalPaths(prepared);
+		for (const entry of prepared) {
+			if (entry.isNoop) {
+				throw new Error(`Edits to ${entry.section.path} resulted in no changes being made.`);
+			}
+		}
+	}
+
+	/**
+	 * Read a section's target file, parse the section, validate the file
+	 * hash (with recovery), and apply the edits in memory. Returns a
+	 * {@link PreparedSection} which can be fed to {@link commit} to land
+	 * the result on the filesystem.
+	 *
+	 * Throws on parse error, missing-file-for-anchored-edit, or unrecovered
+	 * hash mismatch ({@link MismatchError}).
+	 */
+	async prepare(section: PatchSection, options: ApplyOptions = {}): Promise<PreparedSection> {
+		const applyOptions: ApplyOptions = { ...this.applyOptions, ...options };
+		const { edits, warnings: parseWarnings } = section.parse();
+		assertSectionHashAllowed(section.path, section.fileHash, edits);
+
+		const canonicalPath = this.fs.canonicalPath(section.path);
+		await this.fs.preflightWrite(section.path);
+		const { exists, rawContent } = await this.#tryRead(section.path);
+		if (!exists && hasAnchorScopedEdit(edits)) {
+			throw new Error(`File not found: ${section.path}`);
+		}
+
+		const { bom, text } = stripBom(rawContent);
+		const lineEnding = detectLineEnding(text);
+		const normalized = normalizeToLF(text);
+
+		const applyResult = this.#applyWithRecovery({
+			section,
+			canonicalPath,
+			exists,
+			normalized,
+			edits,
+			applyOptions,
+		});
+
+		return new PreparedSection(
+			section,
+			canonicalPath,
+			exists,
+			rawContent,
+			bom,
+			lineEnding,
+			normalized,
+			applyResult,
+			parseWarnings,
+		);
+	}
+
+	/**
+	 * Commit a previously {@link prepare}d section to the filesystem.
+	 * Restores line endings and BOM, writes via the {@link Filesystem}, and
+	 * records a fresh snapshot in the {@link SnapshotStore} (when
+	 * configured) keyed by the filesystem-canonical path.
+	 */
+	async commit(prepared: PreparedSection): Promise<PatchSectionResult> {
+		const { section, normalized, bom, lineEnding, parseWarnings, exists, applyResult, canonicalPath } = prepared;
+		const after = applyResult.text;
+		const warnings = mergeWarnings(parseWarnings, applyResult.warnings);
+
+		if (after === normalized) {
+			const hash = computeFileHash(normalized);
+			return {
+				path: section.path,
+				canonicalPath,
+				op: "noop",
+				before: normalized,
+				after: normalized,
+				persisted: prepared.rawContent,
+				written: prepared.rawContent,
+				fileHash: hash,
+				header: formatHashlineHeader(section.path, hash),
+				warnings,
+			};
+		}
+
+		const persisted = bom + restoreLineEndings(after, lineEnding);
+		const write: WriteResult = await this.fs.writeText(section.path, persisted);
+		const fileHash = computeFileHash(after);
+		const op = exists ? "update" : "create";
+
+		if (this.snapshots) {
+			this.snapshots.recordContiguous(canonicalPath, 1, after.split("\n"), {
+				fullText: after,
+				fileHash,
+			});
+		}
+
+		return {
+			path: section.path,
+			canonicalPath,
+			op,
+			before: normalized,
+			after,
+			persisted,
+			written: write.text,
+			fileHash,
+			header: formatHashlineHeader(section.path, fileHash),
+			firstChangedLine: applyResult.firstChangedLine,
+			warnings,
+		};
+	}
+
+	async #tryRead(path: string): Promise<{ exists: boolean; rawContent: string }> {
+		try {
+			const content = await this.fs.readText(path);
+			return { exists: true, rawContent: content };
+		} catch (error) {
+			if (isNotFound(error)) return { exists: false, rawContent: "" };
+			throw error;
+		}
+	}
+
+	#applyWithRecovery(args: {
+		section: PatchSection;
+		canonicalPath: string;
+		exists: boolean;
+		normalized: string;
+		edits: readonly Edit[];
+		applyOptions: ApplyOptions;
+	}): ApplyResult {
+		const { section, canonicalPath, exists, normalized, edits, applyOptions } = args;
+		const expected = exists ? section.fileHash : undefined;
+		if (expected === undefined) return applyEdits(normalized, [...edits], applyOptions);
+
+		const currentHash = computeFileHash(normalized);
+		if (currentHash === expected) return applyEdits(normalized, [...edits], applyOptions);
+
+		const recovered = this.recovery?.tryRecover({
+			path: canonicalPath,
+			currentText: normalized,
+			fileHash: expected,
+			edits,
+			options: applyOptions,
+		});
+		if (recovered) return recoveryToApplyResult(recovered);
+
+		throw new MismatchError({
+			path: section.path,
+			expectedFileHash: expected,
+			actualFileHash: currentHash,
+			fileLines: normalized.split("\n"),
+			anchorLines: section.collectAnchorLines(),
+		});
+	}
+}

package/src/prefixes.ts

@@ -0,0 +1,130 @@
+/**
+ * When a hashline payload is authored against `read`/`search` output, each
+ * line is prefixed with either a hashline-mode line number (`123:`) or, for
+ * diff-style echoes, a leading `+`. These helpers detect that and recover
+ * the raw text. Two strip modes are exposed:
+ *
+ * - {@link stripNewLinePrefixes} — opportunistic: strips when the input
+ *   clearly carries hashline or diff prefixes, leaves it alone otherwise.
+ * - {@link stripHashlinePrefixes} — strict: only strips when every non-empty
+ *   content line is hashline-prefixed.
+ *
+ * These run *before* the tokenizer; they exist because hashline mode is the
+ * common case for echoed file content, and erroneously echoed prefixes will
+ * otherwise turn every content line into a (malformed) op.
+ */
+
+const HL_PREFIX_RE = /^\s*(?:>>>|>>)?\s*(?:[+*-]\s*)?\d+:/;
+const HL_PREFIX_PLUS_RE = /^\s*(?:>>>|>>)?\s*\+\s*\d+:/;
+const HL_HEADER_RE = /^\s*¶\S+#[0-9a-f]{4}\s*$/;
+const DIFF_PLUS_RE = /^[+](?![+])/;
+const READ_TRUNCATION_NOTICE_RE = /^\[(?:Showing lines \d+-\d+ of \d+|\d+ more lines? in (?:file|\S+))\b.*\bUse :L?\d+/;
+
+function stripLeadingHashlinePrefixes(line: string): string {
+	let result = line;
+	let previous: string;
+	do {
+		previous = result;
+		result = result.replace(HL_PREFIX_RE, "");
+	} while (result !== previous);
+	return result;
+}
+
+interface LinePrefixStats {
+	nonEmpty: number;
+	headerCount: number;
+	hashPrefixCount: number;
+	diffPlusHashPrefixCount: number;
+	diffPlusCount: number;
+	truncationNoticeCount: number;
+}
+
+function collectLinePrefixStats(lines: string[]): LinePrefixStats {
+	const stats: LinePrefixStats = {
+		nonEmpty: 0,
+		headerCount: 0,
+		hashPrefixCount: 0,
+		diffPlusHashPrefixCount: 0,
+		diffPlusCount: 0,
+		truncationNoticeCount: 0,
+	};
+
+	for (const line of lines) {
+		if (line.length === 0) continue;
+		if (READ_TRUNCATION_NOTICE_RE.test(line)) {
+			stats.truncationNoticeCount++;
+			continue;
+		}
+		if (HL_HEADER_RE.test(line)) {
+			stats.nonEmpty++;
+			stats.headerCount++;
+			continue;
+		}
+		stats.nonEmpty++;
+		if (HL_PREFIX_RE.test(line)) stats.hashPrefixCount++;
+		if (HL_PREFIX_PLUS_RE.test(line)) stats.diffPlusHashPrefixCount++;
+		if (DIFF_PLUS_RE.test(line)) stats.diffPlusCount++;
+	}
+	return stats;
+}
+
+/**
+ * Strip whichever prefix scheme the lines appear to be carrying:
+ * - hashline line-number prefixes (`123:`) when every content line has one
+ * - leading `+` (diff style) when at least half the lines have one
+ * - mixed `+<n>:` form when present
+ *
+ * Returns the lines untouched if no scheme is recognized.
+ */
+export function stripNewLinePrefixes(lines: string[]): string[] {
+	const stats = collectLinePrefixStats(lines);
+	if (stats.nonEmpty === 0) return lines;
+
+	const contentLineCount = stats.nonEmpty - stats.headerCount;
+	const stripHash = contentLineCount > 0 && stats.hashPrefixCount === contentLineCount;
+	const stripPlus =
+		!stripHash &&
+		stats.diffPlusHashPrefixCount === 0 &&
+		stats.diffPlusCount > 0 &&
+		stats.diffPlusCount >= stats.nonEmpty * 0.5;
+
+	if (!stripHash && !stripPlus && stats.diffPlusHashPrefixCount === 0) return lines;
+
+	return lines
+		.filter(line => !READ_TRUNCATION_NOTICE_RE.test(line) && !(stripHash && HL_HEADER_RE.test(line)))
+		.map(line => {
+			if (stripHash) return stripLeadingHashlinePrefixes(line);
+			if (stripPlus) return line.replace(DIFF_PLUS_RE, "");
+			if (stats.diffPlusHashPrefixCount > 0 && HL_PREFIX_PLUS_RE.test(line)) {
+				return line.replace(HL_PREFIX_RE, "");
+			}
+			return line;
+		});
+}
+
+/**
+ * Strict variant: strip hashline prefixes only when every content line is
+ * hashline-prefixed. Returns the lines unchanged otherwise.
+ */
+export function stripHashlinePrefixes(lines: string[]): string[] {
+	const stats = collectLinePrefixStats(lines);
+	if (stats.nonEmpty === 0) return lines;
+	const contentLineCount = stats.nonEmpty - stats.headerCount;
+	if (contentLineCount === 0 || stats.hashPrefixCount !== contentLineCount) return lines;
+	return lines
+		.filter(line => !READ_TRUNCATION_NOTICE_RE.test(line) && !HL_HEADER_RE.test(line))
+		.map(line => stripLeadingHashlinePrefixes(line));
+}
+
+/**
+ * Normalize line payloads by stripping read/search line prefixes. `null` /
+ * `undefined` yield `[]`; a single multiline string is split on `\n`.
+ */
+export function hashlineParseText(edit: string[] | string | null | undefined): string[] {
+	if (edit == null) return [];
+	if (typeof edit === "string") {
+		const trimmed = edit.endsWith("\n") ? edit.slice(0, -1) : edit;
+		edit = trimmed.replaceAll("\r", "").split("\n");
+	}
+	return stripNewLinePrefixes(edit);
+}

package/src/prompt.md

@@ -0,0 +1,83 @@
+Your patch language is a compact, line-anchored edit format.
+
+<payload>
+Patch payload is a series of hunks: `¶PATH#HASH` header followed by any number of operations. `HASH` should be copied as is from read/search. Missing? Re-`read`.
+- No context rows, no gutters.
+- NEVER restate unchanged lines "for context".
+- Op lines carry NO payload. Every payload line lives on its own row and MUST start with `+`; that delimiter is stripped.
+- Payload indentation is literal.
+</payload>
+
+<ops>
+LINE↑    insert before (or BOF↑)
+LINE↓    insert after  (or EOF↓)
+A-B:     replace A..B  (or A: == A..A)
+A-B!     delete A..B   (or A! == A..A)
++PAYLOAD payload line for the preceding op
+</ops>
+
+<rules>
+- **Payload is only what's NEW.** `:` replaces inside; `↑`/`↓` add at anchor. NEVER repeat anchor lines or neighbors.
+- **Use `+` for a blank payload line; use `++text` to write a line starting with `+text`.**
+- **Inserts add ONLY the rows you list.** The file's existing newlines around the anchor stay. NEVER tack a trailing `+` blank "for spacing" — it writes a literal blank line into the file, doubling whatever is already there.
+- **A bare `LINE↑`/`LINE↓` with no payload still inserts ONE blank line.** Not a no-op. Omit the op if you want nothing there.
+- **Go small.** Add → `↑`/`↓`; replace → `:`; delete → `!`.
+- **Line numbers are frozen references to what you have seen.** Later ops in the same hunk still use original line numbers; they do NOT shift as earlier ops apply.
+</rules>
+
+<common-failures>
+- **NEVER replay past your range.** Stop before B+1; extend B if needed.
+- **Read lines look like replace ops.** `84:content` = "make line 84 content" — and inline content is rejected. Don't echo read-style rows.
+- **NEVER fabricate file hashes.** Missing? Re-`read`.
+</common-failures>
+
+<example>
+```a.ts#1a2b
+1:const X = "a";
+2:
+3:export function f() { return X; }
+4:f();
+```
+
+# replace one line, insert after, delete
+```
+¶a.ts#1a2b
+1:
++const X = "b";
++export const Y = X;
+1↓
++const Z = Y;
+4!
+```
+</example>
+
+<anti-pattern>
+# WRONG — inline payload after the sigil is rejected
+1:const X = "b";
+1↓const Z = Y;
+1-2:const X = "b";
++export const Y = X;
+# WRONG — INSERT used to change a line (old line survives)
+1↓
++const X = "b";
+# WRONG — echoing read-style lines as context before the real op
+1:const X = "a";
+1-2:
++const X = "b";
++export const Y = X;
+# WRONG — trailing `+` blank writes a literal empty line; the new blank lands right next to the orig blank at line 2, doubling it
+1↓
++const Y = X;
++
+# WRONG — `2↓` still anchors at PRE-EDIT line 2 (frozen), NOT at the line just inserted by `1↓`. Both inserts land at their own anchors, giving three consecutive blanks (new from `1↓`, orig blank line 2, new from `2↓`).
+1↓
+2↓
+</anti-pattern>
+
+<critical>
+- One op per range, ever.
+- Pick op precisely. Update: `:`, add: `↑`/`↓`, remove: `!`.
+- Payload always lives on its own `+`-prefixed line — never inline with the op.
+- Payload is only what's NEW; never repeat anchor lines or neighbors.
+- Anchor exactly; don't anchor neighbors.
+</critical>