@prometheus-ai/hashline 0.5.0

package/README.md

@@ -0,0 +1,79 @@
+# @prometheus-ai/hashline
+
+A compact, line-anchored patch language and applier.
+
+Hashline is a diff format designed for LLM-driven file edits. It binds every
+hunk to a file-content hash so stale anchors are rejected before they corrupt
+code, and it abstracts over the filesystem so the same patcher works on disk,
+in memory, over the network, or against any custom backend.
+
+## Quick start
+
+```ts
+import {
+	Filesystem,
+	InMemoryFilesystem,
+	InMemorySnapshotStore,
+	Patcher,
+	Patch,
+} from "@prometheus-ai/hashline";
+
+const fs = new InMemoryFilesystem();
+const snapshots = new InMemorySnapshotStore();
+const before = `const greeting = "hi";\nexport { greeting };\n`;
+await fs.writeText("hello.ts", before);
+
+const tag = snapshots.record("hello.ts", before);
+const patcher = new Patcher({ fs, snapshots });
+const patch = Patch.parse(String.raw`[hello.ts#${tag}]
+replace 1..1:
++const greeting = "hello";`);
+const result = await patcher.apply(patch);
+
+console.log(result.sections[0].op); // "update"
+console.log(await fs.readText("hello.ts"));
+```
+
+## Format
+
+See [`src/prompt.md`](./src/prompt.md) for the user-facing description and
+[`src/grammar.lark`](./src/grammar.lark) for the formal grammar.
+
+Each file section starts with `[PATH#TAG]`. The tag is a 4-hex
+content hash of the full normalized file text recorded by the
+`SnapshotStore`, and it is not meaningful outside that store. The patcher
+protects against stale anchors by resolving the tag, verifying the live file
+still matches the recorded content hash, and refusing or attempting
+session-aware recovery on mismatch.
+
+Inside a section:
+- `replace A..B:` — replace lines A..B with following `+TEXT` body rows.
+- `replace block A:` — replace the syntactic block beginning on line A.
+- `delete A..B` / `delete block A` — delete concrete lines or a resolved block.
+- `insert before A:` / `insert after A:` / `insert head:` / `insert tail:` — insert following body rows.
+- `+TEXT` — literal body row (use `+` alone for a blank line).
+
+## Abstractions
+
+### `Filesystem`
+
+Read and write text by path. The default implementations:
+
+- `InMemoryFilesystem` — backed by a `Map`. Tests, sandboxes.
+- `NodeFilesystem` — disk-backed via `Bun.file`/`Bun.write`. Default for CLIs.
+
+Subclass `Filesystem` to wire hashline into any storage: VFS, S3, an LSP
+text-document protocol, a Git tree, anything.
+
+### `SnapshotStore`
+
+Required. Hashline tags are full-file content hashes recorded per path, so
+`Patcher` must receive the store that observed them. Recovery replays edits
+against the cached pre-edit snapshot and 3-way-merges onto current content
+when the live file diverged.
+
+### `Patcher`
+
+The orchestration class. Reads, normalizes line endings + BOM, applies edits,
+restores line endings, and writes via the configured `Filesystem`. Multi-section
+patches are preflighted up front so a partial batch never lands.

package/dist/types/apply.d.ts

@@ -0,0 +1,8 @@
+import type { ApplyResult, Edit } from "./types";
+/**
+ * Apply a parsed list of edits to a text body. Pure function — no I/O.
+ *
+ * Returns the post-edit text and the first changed line number (1-indexed).
+ * Throws if an anchor is out of bounds.
+ */
+export declare function applyEdits(text: string, edits: readonly Edit[]): ApplyResult;

package/dist/types/block.d.ts

@@ -0,0 +1,24 @@
+import type { BlockResolver, Edit } from "./types";
+export interface ResolveBlockEditsOptions {
+    /**
+     * How to handle a block edit that cannot be resolved (missing resolver or a
+     * `null` span). `"throw"` (default) raises a `blockUnresolvedMessage` error —
+     * used by the authoritative apply + final preview paths. `"drop"` silently
+     * skips the edit — used by the streaming preview, where a half-written file
+     * or transient parse error must not throw.
+     */
+    onUnresolved?: "throw" | "drop";
+}
+/** True when at least one edit is an unresolved `replace block N:` edit. */
+export declare function hasBlockEdit(edits: readonly Edit[]): boolean;
+/**
+ * Resolve every `replace block N:` edit in `edits` against `text` (parsed as
+ * the language inferred from `path`). Non-block edits pass through untouched.
+ * Returns a fresh edit list with no `block` variants. The fast path returns the
+ * input unchanged when there is nothing to resolve.
+ *
+ * Synthesized inserts/deletes carry sequential `index` values for readability
+ * only — {@link applyEdits} re-derives every edit's index from array order, so
+ * the passthrough edits keeping their original indices is harmless.
+ */
+export declare function resolveBlockEdits(edits: readonly Edit[], text: string, path: string, resolver: BlockResolver | undefined, options?: ResolveBlockEditsOptions): readonly Edit[];

package/dist/types/diff-preview.d.ts

@@ -0,0 +1,12 @@
+/**
+ * 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 declare function buildCompactDiffPreview(diff: string, _options?: CompactDiffOptions): CompactDiffPreview;

package/dist/types/format.d.ts

@@ -0,0 +1,76 @@
+/**
+ * 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 declare const HL_FILE_PREFIX = "[";
+export declare const HL_FILE_SUFFIX = "]";
+/** Payload sigil for literal body rows. */
+export declare const HL_PAYLOAD_REPLACE = "+";
+/** Hunk-header keyword for concrete line replacement. */
+export declare const HL_REPLACE_KEYWORD = "replace";
+/** Hunk-header sub-keyword: `replace block N:` resolves N to a tree-sitter block range. */
+export declare const HL_BLOCK_KEYWORD = "block";
+/** Hunk-header keyword for concrete line deletion. */
+export declare const HL_DELETE_KEYWORD = "delete";
+/** Hunk-header keyword for insertion operations. */
+export declare const HL_INSERT_KEYWORD = "insert";
+/** Insert position keyword for inserting before a concrete line. */
+export declare const HL_INSERT_BEFORE = "before";
+/** Insert position keyword for inserting after a concrete line. */
+export declare const HL_INSERT_AFTER = "after";
+/** Insert position keyword for inserting at the start of the file. */
+export declare const HL_INSERT_HEAD = "head";
+/** Insert position keyword for inserting at the end of the file. */
+export declare const HL_INSERT_TAIL = "tail";
+/** Hunk-header terminator for body-bearing operations. */
+export declare const HL_HEADER_COLON = ":";
+/** Separator between a hashline file path and its opaque snapshot tag. */
+export declare const HL_FILE_HASH_SEP = "#";
+/** Separator between two line numbers in a range, e.g. `5..10`. */
+export declare const HL_RANGE_SEP = "..";
+/** Separator between a line number and displayed line content in hashline mode. */
+export declare const HL_LINE_BODY_SEP = ":";
+/** Bare positive line-number Lid (no decorations, no captures, no anchors). */
+export declare const HL_LINE_RE_RAW = "[1-9]\\d*";
+/** Capture-group form of {@link HL_LINE_RE_RAW}. */
+export declare const HL_LINE_CAPTURE_RE_RAW = "([1-9]\\d*)";
+/** Format a concrete replacement hunk header. */
+export declare function formatReplaceHeader(start: number, end: number): string;
+/** Format a concrete deletion hunk header. */
+export declare function formatDeleteHeader(start: number, end?: number): string;
+/** Format an insertion hunk header for a cursor position. */
+export declare function formatInsertHeader(cursor: Cursor): string;
+/** Number of hex characters in a content-derived file-hash tag. */
+export declare const HL_FILE_HASH_LENGTH = 4;
+/** Canonical uppercase hexadecimal content-hash tag carried by a hashline section header. */
+export declare const HL_FILE_HASH_RE_RAW = "[0-9A-F]{4}";
+/** Capture-group form of {@link HL_FILE_HASH_RE_RAW}. */
+export declare const HL_FILE_HASH_CAPTURE_RE_RAW = "([0-9A-F]{4})";
+/** Regex-escaped form of {@link HL_LINE_BODY_SEP}, safe for embedding inside a regex. */
+export declare const HL_LINE_BODY_SEP_RE_RAW: string;
+/**
+ * Representative file-hash tags for use in user-facing error messages and
+ * prompt examples.
+ */
+export declare const HL_FILE_HASH_EXAMPLES: readonly ["1A2B", "3C4D", "9F3E"];
+/**
+ * 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 declare function computeFileHash(text: string): string;
+/**
+ * Format a comma-separated list of example anchors with an optional line-number
+ * prefix, quoted for inclusion in error messages: `"160", "42", "7"`.
+ */
+export declare function describeAnchorExamples(linePrefix?: string): string;
+/** Format a hashline section header for a file path and snapshot tag. */
+export declare function formatHashlineHeader(filePath: string, fileHash: string): string;
+/** Formats a single numbered line as `LINE:TEXT`. */
+export declare function formatNumberedLine(lineNumber: number, line: string): string;
+/** Format file text with hashline-mode line-number prefixes for display. */
+export declare function formatNumberedLines(text: string, startLine?: number): string;

package/dist/types/fs.d.ts

@@ -0,0 +1,80 @@
+/**
+ * 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 declare class NotFoundError extends Error {
+    readonly code = "ENOENT";
+    constructor(path: string, cause?: unknown);
+}
+/** Type guard for {@link NotFoundError} and structurally-compatible errors. */
+export declare function isNotFound(error: unknown): boolean;
+/**
+ * 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 declare 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. */
+    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}. */
+    exists(path: string): Promise<boolean>;
+    /**
+     * 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;
+}
+/**
+ * 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 declare class InMemoryFilesystem extends Filesystem {
+    #private;
+    constructor(initial?: Iterable<readonly [string, string]>);
+    readText(path: string): Promise<string>;
+    writeText(path: string, content: string): Promise<WriteResult>;
+    exists(path: string): Promise<boolean>;
+    /** Synchronous helper for setting up fixtures without awaiting. */
+    set(path: string, content: string): void;
+    /** Synchronous helper for inspecting state without awaiting. */
+    get(path: string): string | undefined;
+    /** Remove a single entry. Returns true when something was removed. */
+    delete(path: string): boolean;
+    /** Wipe all entries. */
+    clear(): void;
+    /** Iterate `[path, content]` pairs. */
+    entries(): IterableIterator<[string, string]>;
+}
+/**
+ * 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 declare class NodeFilesystem extends Filesystem {
+    readText(path: string): Promise<string>;
+    writeText(path: string, content: string): Promise<WriteResult>;
+    canonicalPath(path: string): string;
+    exists(path: string): Promise<boolean>;
+}

package/dist/types/index.d.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";

package/dist/types/input.d.ts

@@ -0,0 +1,100 @@
+import type { ApplyResult, BlockResolver, Edit, SplitOptions } from "./types";
+interface RawSection {
+    path: string;
+    fileHash?: string;
+    diff: string;
+}
+/**
+ * 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 declare function containsRecognizableHashlineOperations(input: string): boolean;
+/**
+ * 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 declare class PatchSection {
+    #private;
+    readonly path: string;
+    readonly fileHash: string | undefined;
+    readonly diff: string;
+    constructor(raw: RawSection);
+    /**
+     * 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[];
+    };
+    /** Parsed edits for this section. */
+    get edits(): readonly Edit[];
+    /** Warnings emitted during parsing of this section. */
+    get warnings(): readonly string[];
+    /**
+     * True when at least one edit anchors to concrete file content. Pure
+     * `insert head:` / `insert tail:` literal inserts do not count: those are
+     * safe to apply to files that don't yet exist.
+     */
+    get hasAnchorScopedEdit(): boolean;
+    /** Anchor lines touched by this section, sorted ascending and deduplicated. */
+    collectAnchorLines(): readonly number[];
+    /**
+     * Apply this section's edits to `text` and return the post-edit result.
+     * Pure: does no I/O, does not validate the section snapshot tag. The
+     * {@link Patcher} owns tag validation and recovery; reach for this
+     * method directly when you've already validated the file content and
+     * just want the result.
+     *
+     * `blockResolver` resolves any `replace block N:` edits against `text`; an
+     * unresolvable block throws (this is the final, authoritative preview path).
+     */
+    applyTo(text: string, blockResolver?: BlockResolver): ApplyResult;
+    /**
+     * Streaming-tolerant counterpart to {@link applyTo}. Uses
+     * {@link parsePatchStreaming} so a trailing in-flight op (no payload yet,
+     * or a per-token parse error mid-stream) does not throw or emit a phantom
+     * empty-payload edit. Intended for incremental diff previews; the writer
+     * path should always use {@link applyTo}.
+     *
+     * `blockResolver` resolves any `replace block N:` edits against `text`; an
+     * unresolvable block is silently dropped so a half-written file does not
+     * throw mid-stream.
+     */
+    applyPartialTo(text: string, blockResolver?: BlockResolver): ApplyResult;
+}
+/**
+ * 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 declare class Patch {
+    readonly sections: readonly PatchSection[];
+    private constructor();
+    /**
+     * 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;
+    /**
+     * 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;
+}
+export {};

package/dist/types/messages.d.ts

@@ -0,0 +1,85 @@
+/**
+ * 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 declare const MISMATCH_CONTEXT = 2;
+/** Optional patch envelope start marker; silently consumed when present. */
+export declare const BEGIN_PATCH_MARKER = "*** Begin Patch";
+/** Optional patch envelope end marker; terminates parsing when encountered. */
+export declare 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 does not surface a warning.
+ */
+export declare const ABORT_MARKER = "*** Abort";
+/** Warning text appended when two consecutive hunks target the exact same concrete range. */
+export declare const REPLACE_PAIR_COALESCED_WARNING = "Detected two identical-range hashline hunks; kept only the second hunk. Issue ONE `replace N..M:` hunk per range \u2014 payload is the final desired content, never both old and new.";
+/** Warning text appended when an empty bodyless hunk is followed by an overlapping concrete hunk. */
+export declare const REPLACE_PAIR_COALESCED_OVERLAP_WARNING = "Detected an overlapping bare hashline hunk immediately followed by a concrete hunk; dropped the earlier bare hunk. Issue ONE `replace N..M:` hunk per range \u2014 payload is the final desired content, never both old and new.";
+/** Warning text appended when bare body rows are auto-converted to literal rows. */
+export declare const BARE_BODY_AUTO_PIPED_WARNING = "Auto-prefixed bare body row(s) with `+`. Body rows must be `+TEXT` literal lines; pasting raw code as payload is not a portable shape.";
+/** Error text emitted when a hunk body contains a unified-diff-style `-` row. */
+export declare const MINUS_ROW_REJECTED = "`-` rows are not valid; hashline ranges already name the lines being changed. To insert a literal line starting with `-`, write `+-\u2026`.";
+/** Error text emitted when a replace hunk has no body. */
+export declare const EMPTY_REPLACE = "`replace N..M:` needs at least one `+TEXT` body row. To delete lines, use `delete N..M`.";
+/** Error text emitted when a `replace block N:` hunk has no body. */
+export declare const EMPTY_BLOCK = "`replace block N:` needs at least one `+TEXT` body row. To delete a block, use `delete N..M` with the block's line range.";
+/**
+ * Error text emitted when a `replace block N:` anchor cannot be resolved to a
+ * syntactic block (unrecognized language, blank/out-of-range line, no node
+ * begins on line N such as a lone closing delimiter, or the resolved block has
+ * a syntax error). Names the offending line and steers back to an explicit
+ * `replace N..M:` range.
+ */
+export declare function blockUnresolvedMessage(line: number): string;
+/**
+ * Error text emitted when a `replace block N:` edit reaches a code path that
+ * has no {@link BlockResolver} wired in. Indicates a host-configuration bug
+ * rather than authored-input error.
+ */
+export declare const BLOCK_RESOLVER_UNAVAILABLE = "`replace block N:` is not available here (no tree-sitter block resolver is configured). Use `replace N..M:` with an explicit range.";
+/**
+ * Internal invariant error: `applyEdits` received an unresolved `replace block
+ * N:` edit. Block edits must be expanded by `resolveBlockEdits` before reaching
+ * the applier; hitting this is a wiring bug, not authored-input error.
+ */
+export declare const UNRESOLVED_BLOCK_INTERNAL = "internal error: unresolved `replace block` edit reached the applier (resolveBlockEdits was not run).";
+/** Error text emitted when a delete hunk receives a body row. */
+export declare const DELETE_TAKES_NO_BODY = "`delete N..M` does not take body rows. Remove the body, or use `replace N..M:`.";
+/** Error text emitted when a `delete block N` hunk receives a body row. */
+export declare const DELETE_BLOCK_TAKES_NO_BODY = "`delete block N` does not take body rows. Remove the body, or use `replace block N:` to replace the block.";
+/** Error text emitted when an insert hunk has no body. */
+export declare const EMPTY_INSERT = "`insert` needs at least one `+TEXT` body row.";
+/** Warning text emitted by `Recovery` when an external write fits a cached snapshot. */
+export declare 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 declare 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 replay
+ * fast-path was taken. Distinct from {@link RECOVERY_SESSION_CHAIN_WARNING}
+ * because replay is the less-certain mode: the structured-patch 3-way
+ * merge refused, the anchor-content gate passed, but a coincidental
+ * insert+delete pair earlier in the chain could still leave an anchor's
+ * line number pointing at a duplicated row. Surface the hedge so the
+ * model verifies before continuing.
+ */
+export declare const RECOVERY_SESSION_REPLAY_WARNING = "Recovered by replaying your edits onto the current file content \u2014 your previous edit in this session changed line(s) you re-targeted with a stale hash. Verify the diff matches your intent before continuing.";
+/**
+ * Warning emitted when an `insert head:` / `insert tail:` edit is applied to an
+ * existing file whose snapshot tag is stale (the file drifted since the read).
+ * Head/tail insert position is content-independent — "start"/"end" cannot move
+ * with drift — so this is non-fatal: the edit applies onto the live content and
+ * we surface the drift instead of hard-failing (unlike an anchored mismatch).
+ */
+export declare const HEADTAIL_DRIFT_WARNING = "Applied an `insert head:`/`insert tail:` edit onto the current file content even though the snapshot tag was stale (the file changed since your read). Head/tail position is content-independent, so the insert was not rejected \u2014 but re-read if the drift was unexpected.";
+/**
+ * Error text emitted when a hashline section omits the mandatory snapshot tag.
+ * The tag is REQUIRED on every section, enforced identically by the apply path
+ * ({@link Patcher.prepare}) and the preview/diff path, so both surfaces reuse
+ * this single builder to stay in lockstep.
+ */
+export declare function missingSnapshotTagMessage(sectionPath: string): string;

package/dist/types/mismatch.d.ts

@@ -0,0 +1,44 @@
+/** Format the required-shape diagnostic shown when a line reference is malformed. */
+export declare function formatFullAnchorRequirement(raw?: string): string;
+/** Parse a decorated bare line-number anchor like `42`, `*42:foo`, ` > 7`. */
+export declare function parseTag(ref: string): {
+    line: number;
+};
+export interface MismatchDetails {
+    path?: string;
+    expectedFileHash: string;
+    actualFileHash: string;
+    fileLines: string[];
+    anchorLines?: readonly number[];
+    /**
+     * `true` when the section's expected hash resolved to a recorded snapshot
+     * (file content drifted since that snapshot), `false` when no snapshot
+     * was ever recorded for the hash (likely fabricated or carried over from
+     * a prior session). Drives a more actionable rejection message; defaults
+     * to `true` for backward compatibility with direct callers.
+     */
+    hashRecognized?: boolean;
+}
+/**
+ * Raised when a hashline section's snapshot tag 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 declare class MismatchError extends Error {
+    readonly path: string | undefined;
+    readonly expectedFileHash: string;
+    readonly actualFileHash: string;
+    readonly fileLines: string[];
+    readonly anchorLines: readonly number[];
+    readonly hashRecognized: boolean;
+    constructor(details: MismatchDetails);
+    get displayMessage(): string;
+    static rejectionHeader(details: MismatchDetails): string[];
+    static formatDisplayMessage(details: MismatchDetails): string;
+    static formatMessage(details: MismatchDetails): string;
+}
+/** Throws when the line reference is out of bounds for the given file. */
+export declare function validateLineRef(ref: {
+    line: number;
+}, fileLines: string[]): void;

package/dist/types/normalize.d.ts

@@ -0,0 +1,20 @@
+/**
+ * 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 declare function detectLineEnding(content: string): LineEnding;
+/** Normalize every line ending to LF. */
+export declare function normalizeToLF(text: string): string;
+/** Re-encode LF text with the requested line ending. */
+export declare function restoreLineEndings(text: string, ending: LineEnding): string;
+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 declare function stripBom(content: string): BomResult;

package/dist/types/parser.d.ts

@@ -0,0 +1,23 @@
+import { type Token } from "./tokenizer";
+import type { Edit } from "./types";
+export declare class Executor {
+    #private;
+    feed(token: Token): void;
+    end(): {
+        edits: Edit[];
+        warnings: string[];
+    };
+    endStreaming(): {
+        edits: Edit[];
+        warnings: string[];
+    };
+    reset(): void;
+}
+export declare function parsePatch(diff: string): {
+    edits: Edit[];
+    warnings: string[];
+};
+export declare function parsePatchStreaming(diff: string): {
+    edits: Edit[];
+    warnings: string[];
+};