@prometheus-ai/hashline 0.5.0

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,134 @@
+/**
+ * Hashline format primitives: sigils, separators, regex fragments, and
+ * display helpers. These are the single source of truth for the parser, the
+ * tokenizer, the prompt, and the formal grammar.
+ */
+
+import type { Cursor } from "./types";
+
+/** File-section header delimiters: `[path#hash]`. */
+export const HL_FILE_PREFIX = "[";
+export const HL_FILE_SUFFIX = "]";
+
+/** Payload sigil for literal body rows. */
+export const HL_PAYLOAD_REPLACE = "+";
+
+/** Hunk-header keyword for concrete line replacement. */
+export const HL_REPLACE_KEYWORD = "replace";
+/** Hunk-header sub-keyword: `replace block N:` resolves N to a tree-sitter block range. */
+export const HL_BLOCK_KEYWORD = "block";
+/** Hunk-header keyword for concrete line deletion. */
+export const HL_DELETE_KEYWORD = "delete";
+/** Hunk-header keyword for insertion operations. */
+export const HL_INSERT_KEYWORD = "insert";
+/** Insert position keyword for inserting before a concrete line. */
+export const HL_INSERT_BEFORE = "before";
+/** Insert position keyword for inserting after a concrete line. */
+export const HL_INSERT_AFTER = "after";
+/** Insert position keyword for inserting at the start of the file. */
+export const HL_INSERT_HEAD = "head";
+/** Insert position keyword for inserting at the end of the file. */
+export const HL_INSERT_TAIL = "tail";
+/** Hunk-header terminator for body-bearing operations. */
+export const HL_HEADER_COLON = ":";
+
+/** Separator between a hashline file path and its opaque snapshot tag. */
+export const HL_FILE_HASH_SEP = "#";
+
+/** Separator between two line numbers in a range, e.g. `5..10`. */
+export const HL_RANGE_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, "\\$&");
+}
+
+/** 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 = `(${HL_LINE_RE_RAW})`;
+
+/** Format a concrete replacement hunk header. */
+export function formatReplaceHeader(start: number, end: number): string {
+	return `${HL_REPLACE_KEYWORD} ${start}${HL_RANGE_SEP}${end}${HL_HEADER_COLON}`;
+}
+
+/** Format a concrete deletion hunk header. */
+export function formatDeleteHeader(start: number, end = start): string {
+	return start === end ? `${HL_DELETE_KEYWORD} ${start}` : `${HL_DELETE_KEYWORD} ${start}${HL_RANGE_SEP}${end}`;
+}
+
+/** Format an insertion hunk header for a cursor position. */
+export function formatInsertHeader(cursor: Cursor): string {
+	switch (cursor.kind) {
+		case "before_anchor":
+			return `${HL_INSERT_KEYWORD} ${HL_INSERT_BEFORE} ${cursor.anchor.line}${HL_HEADER_COLON}`;
+		case "after_anchor":
+			return `${HL_INSERT_KEYWORD} ${HL_INSERT_AFTER} ${cursor.anchor.line}${HL_HEADER_COLON}`;
+		case "bof":
+			return `${HL_INSERT_KEYWORD} ${HL_INSERT_HEAD}${HL_HEADER_COLON}`;
+		case "eof":
+			return `${HL_INSERT_KEYWORD} ${HL_INSERT_TAIL}${HL_HEADER_COLON}`;
+	}
+}
+
+/** Number of hex characters in a content-derived file-hash tag. */
+export const HL_FILE_HASH_LENGTH = 4;
+/** Canonical uppercase hexadecimal content-hash tag carried by a hashline section header. */
+export const HL_FILE_HASH_RE_RAW = `[0-9A-F]{${HL_FILE_HASH_LENGTH}}`;
+/** 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-hash tags for use in user-facing error messages and
+ * prompt examples.
+ */
+export const HL_FILE_HASH_EXAMPLES = ["1A2B", "3C4D", "9F3E"] as const;
+/**
+ * Normalize text before hashing: trim trailing `[ \t\r]` from every line (and
+ * the final line) in a single pass so CRLF endings and display-trimmed lines
+ * do not invalidate a tag.
+ */
+function normalizeFileHashText(text: string): string {
+	return text.replace(/[ \t\r]+(?=\n|$)/g, "");
+}
+/**
+ * Compute the content-derived hash tag carried by a hashline section header.
+ * The tag is a 4-hex fingerprint of the whole file's normalized text: any read
+ * of byte-identical content mints the same tag, and a follow-up edit anchored
+ * at any line validates whenever the live file still hashes to it.
+ */
+export function computeFileHash(text: string): string {
+	const normalized = normalizeFileHashText(text);
+	const low16 = Bun.hash.xxHash32(normalized, 0) & 0xffff;
+	return low16.toString(16).padStart(HL_FILE_HASH_LENGTH, "0").toUpperCase();
+}
+
+/**
+ * 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(", ");
+}
+
+/** Format a hashline section header for a file path and snapshot tag. */
+export function formatHashlineHeader(filePath: string, fileHash: string): string {
+	return `${HL_FILE_PREFIX}${filePath}${HL_FILE_HASH_SEP}${fileHash}${HL_FILE_SUFFIX}`;
+}
+
+/** 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,25 @@
+start: begin_patch file_patch+ end_patch
+begin_patch: "*** Begin Patch" LF
+end_patch:   "*** End Patch" LF?
+
+file_patch: file_header hunk+
+file_header: "[" filename "#" file_hash "]" LF
+file_hash: /[0-9A-F]{4}/
+filename: /[^#\r\n]+/
+
+hunk: replace_hunk | replace_block_hunk | insert_hunk | delete_hunk | delete_block_hunk
+replace_hunk: replace_anchor LF emit_op*
+replace_block_hunk: replace_block_anchor LF emit_op+
+insert_hunk: insert_anchor LF emit_op+
+delete_hunk: "delete " header_range LF
+delete_block_hunk: "delete block " LID LF
+replace_anchor: "replace " header_range ":"
+replace_block_anchor: "replace block " LID ":"
+insert_anchor:  "insert " insert_pos ":"
+insert_pos: "before " LID | "after " LID | "head" | "tail"
+emit_op: "+" /(.*)/ LF
+
+header_range: LID ".." LID
+LID: /[1-9]\d*/
+
+%import common.LF

package/src/index.ts

@@ -0,0 +1,17 @@
+export * from "./apply";
+export * from "./block";
+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";