jeopi-hashline 16.2.13

package/dist/types/snapshots.d.ts

@@ -0,0 +1,127 @@
+/**
+ * One full-file version observed at a point in time. The tag the model sees is
+ * {@link Snapshot.hash}; recovery replays edits against {@link Snapshot.text}.
+ */
+export interface Snapshot {
+    /** Canonical path this version belongs to. */
+    readonly path: string;
+    /** Full normalized (LF, no BOM) file text as observed. */
+    readonly text: string;
+    /** Content-derived tag for {@link Snapshot.text} (see {@link computeFileHash}). */
+    readonly hash: string;
+    /** Timestamp (ms since epoch) the version was recorded. */
+    recordedAt: number;
+    /**
+     * 1-indexed file lines a producer (read/search) actually *displayed* under
+     * this tag. A partial read (range, or a structural summary that collapsed
+     * bodies) leaves this sparse; a whole-file read fills every line. Multiple
+     * reads of the same content union into one set. `undefined` means "no
+     * provenance recorded" — the patcher then skips the seen-line check and
+     * applies as before. Mutated in place as more of the same content is read.
+     */
+    seenLines?: Set<number>;
+}
+/**
+ * Storage seam for full-file version snapshots. The patcher calls {@link head}
+ * for the latest version of a path and {@link byHashExact} when it needs the
+ * specific historical version a section's stale tag names.
+ */
+export declare abstract class SnapshotStore {
+    /** Most-recently recorded version for `path`, or `null` if none. */
+    abstract head(path: string): Snapshot | null;
+    /**
+     * Recorded version for `path` whose tag equals `hash`, or `null`. When two
+     * distinct texts collide on the 16-bit tag, returns the most-recently
+     * recorded one; callers that treat the tag as content identity must use
+     * {@link byHashExact} (or verify {@link Snapshot.text} via {@link byContent}).
+     */
+    abstract byHash(path: string, hash: string): Snapshot | null;
+    /**
+     * Collision-safe {@link byHash}: the single retained version for `path`
+     * whose tag equals `hash`, or `null` when none is retained OR when two or
+     * more distinct texts collide on the tag. In the collision case there is
+     * no way to know which retained text the model's line anchors were minted
+     * against, so consumers that replay anchors (recovery, previews) must
+     * refuse rather than pick one.
+     */
+    abstract byHashExact(path: string, hash: string): Snapshot | null;
+    /**
+     * Recorded version for `path` whose {@link Snapshot.text} equals `fullText`,
+     * or `null`. Disambiguates hash collisions where two distinct file states
+     * share the same 4-hex tag: the patcher consults this before taking the
+     * no-drift path so a colliding live text is never accepted as the exact
+     * snapshot the model's line anchors were minted against.
+     */
+    abstract byContent(path: string, fullText: string): Snapshot | null;
+    /**
+     * Every retained version whose tag equals `hash`, across all tracked
+     * paths. The patcher uses this to recover the intended file when a section
+     * names a path that does not exist on disk but carries a tag the store
+     * minted — the model mistyped the path of a file it read this session.
+     *
+     * The base returns no matches (recovery disabled); stores that can
+     * enumerate their contents override it to enable tag-based path recovery.
+     */
+    findByHash(_hash: string): Snapshot[];
+    /**
+     * Record the full normalized text of `path` and return its content tag.
+     * `seenLines` (optional) are the 1-indexed lines the producer displayed;
+     * they merge into {@link Snapshot.seenLines} across reads of identical text.
+     */
+    abstract record(path: string, fullText: string, seenLines?: Iterable<number>): string;
+    /**
+     * Merge `lines` into the {@link Snapshot.seenLines} of the version whose tag
+     * equals `hash`. No-op when no such version is retained (the content aged
+     * out or was overwritten). Lets producers attach displayed lines after the
+     * tag was already minted (the body is formatted after the hash is computed).
+     */
+    abstract recordSeenLines(path: string, hash: string, lines: Iterable<number>): void;
+    /** Drop the version history for a single path. */
+    abstract invalidate(path: string): void;
+    /**
+     * Move retained version history (and read provenance) from `from` to `to`.
+     * No-op when `from` has no history. Used by file moves so tags minted from
+     * reads of the source path stay valid at the destination.
+     */
+    abstract relocate(from: string, to: string): void;
+    /** Drop every version history. */
+    abstract clear(): void;
+}
+export interface InMemorySnapshotStoreOptions {
+    /** Maximum number of distinct paths tracked at once (default 30). LRU eviction. */
+    maxPaths?: number;
+    /** Maximum full-file versions retained per path (default 4). Oldest dropped first. */
+    maxVersionsPerPath?: number;
+    /**
+     * Global ceiling on retained snapshot text summed across every path's
+     * version history, measured in UTF-16 code units (default 64 MiB).
+     * Least-recently-used path histories are evicted to stay under it.
+     */
+    maxTotalBytes?: number;
+}
+/**
+ * In-memory {@link SnapshotStore} backed by `lru-cache`. Per-path history is a
+ * short ring of full-file versions (oldest dropped first); per-session path
+ * tracking is LRU-bounded so cold paths age out automatically.
+ *
+ * Recording byte-identical content again refreshes recency and reuses the
+ * existing tag (read fusion); recording new content unshifts a fresh version
+ * onto the front of the path history. Two distinct texts that collide on the
+ * short 4-hex tag are retained as separate versions so callers can still tell
+ * them apart via {@link Snapshot.text} — the tag is only a fast index, never
+ * the identity.
+ */
+export declare class InMemorySnapshotStore extends SnapshotStore {
+    #private;
+    constructor(options?: InMemorySnapshotStoreOptions);
+    head(path: string): Snapshot | null;
+    byHash(path: string, hash: string): Snapshot | null;
+    byHashExact(path: string, hash: string): Snapshot | null;
+    byContent(path: string, fullText: string): Snapshot | null;
+    findByHash(hash: string): Snapshot[];
+    record(path: string, fullText: string, seenLines?: Iterable<number>): string;
+    recordSeenLines(path: string, hash: string, lines: Iterable<number>): void;
+    invalidate(path: string): void;
+    relocate(from: string, to: string): void;
+    clear(): void;
+}

package/dist/types/stream.d.ts

@@ -0,0 +1,2 @@
+import type { StreamOptions } from "./types";
+export declare function streamHashLines(source: ReadableStream<Uint8Array> | AsyncIterable<Uint8Array>, options?: StreamOptions): AsyncGenerator<string>;

package/dist/types/tokenizer.d.ts

@@ -0,0 +1,73 @@
+import type { Anchor, Cursor, ParsedRange } from "./types";
+export declare function splitHashlineLines(text: string): string[];
+export declare function cloneCursor(cursor: Cursor): Cursor;
+/** Parse a bare line-number anchor. Throws on malformed input. */
+export declare function parseLid(raw: string, lineNum: number): Anchor;
+export type BlockTarget = {
+    kind: "replace";
+    range: ParsedRange;
+} | {
+    kind: "block";
+    anchor: Anchor;
+} | {
+    kind: "delete";
+    range: ParsedRange;
+} | {
+    kind: "delete_block";
+    anchor: Anchor;
+} | {
+    kind: "insert_before";
+    anchor: Anchor;
+} | {
+    kind: "insert_after";
+    anchor: Anchor;
+} | {
+    kind: "insert_after_block";
+    anchor: Anchor;
+} | {
+    kind: "rem";
+} | {
+    kind: "move";
+    dest: string;
+} | {
+    kind: "bof";
+} | {
+    kind: "eof";
+};
+interface TokenBase {
+    lineNum: number;
+}
+export type Token = (TokenBase & {
+    kind: "blank";
+}) | (TokenBase & {
+    kind: "envelope-begin";
+}) | (TokenBase & {
+    kind: "envelope-end";
+}) | (TokenBase & {
+    kind: "abort";
+}) | (TokenBase & {
+    kind: "header";
+    path: string;
+    fileHash?: string;
+}) | (TokenBase & {
+    kind: "op-block";
+    target: BlockTarget;
+}) | (TokenBase & {
+    kind: "payload-literal";
+    text: string;
+}) | (TokenBase & {
+    kind: "raw";
+    text: string;
+});
+export declare class Tokenizer {
+    #private;
+    feed(chunk: string): Token[];
+    end(): Token[];
+    reset(): void;
+    tokenizeAll(text: string): Token[];
+    tokenize(line: string, lineNum?: number): Token;
+    isOp(line: string): boolean;
+    isHeader(line: string): boolean;
+    isEnvelopeMarker(line: string): boolean;
+}
+export type { ParsedRange } from "./types";

package/dist/types/types.d.ts

@@ -0,0 +1,172 @@
+/**
+ * Pure data types shared across the hashline parser, applier, and patcher.
+ * Nothing in this file references a filesystem, agent runtime, or schema
+ * library — keep it that way.
+ */
+/** A line-number anchor (1-indexed). */
+export interface Anchor {
+    line: number;
+}
+/** Where an `insert` edit should land relative to existing content. */
+export type Cursor = {
+    kind: "bof";
+} | {
+    kind: "eof";
+} | {
+    kind: "before_anchor";
+    anchor: Anchor;
+} | {
+    kind: "after_anchor";
+    anchor: Anchor;
+};
+/**
+ * A single low-level edit produced by the parser and consumed by the applier.
+ * Multi-line replacements decompose to one `insert` per replacement line plus
+ * one `delete` per consumed line. Replacement payloads are tagged so the
+ * applier can distinguish literal insertion from new content for a deleted
+ * line.
+ */
+export type Edit = {
+    kind: "insert";
+    cursor: Cursor;
+    text: string;
+    lineNum: number;
+    index: number;
+    mode?: "replacement";
+    /**
+     * Present on inserts lowered from `insert_after_block N:`: the
+     * resolved block's first line. Lets the applier slide a body that
+     * claims a depth inside the block back across the block's trailing
+     * closer lines (never above this line).
+     */
+    blockStart?: number;
+} | {
+    kind: "delete";
+    anchor: Anchor;
+    lineNum: number;
+    index: number;
+    oldAssertion?: string;
+} | {
+    /**
+     * Deferred block edit (`replace_block N:` / `delete_block N` /
+     * `insert_after_block N:`). The exact line span is unknown at parse
+     * time — it is computed by {@link resolveBlockEdits} once file text +
+     * path (→ language) are available, then expanded into concrete edits:
+     * a non-empty `payloads` without `mode` (from `replace_block`) becomes
+     * the same `replacement` inserts + deletes that `replace start.=end:`
+     * produces; an empty `payloads` (from `delete_block`) becomes a pure
+     * range deletion; `mode: "insert_after"` becomes plain `after_anchor`
+     * inserts at the block's last line. `applyEdits` never sees this
+     * variant.
+     */
+    kind: "block";
+    anchor: Anchor;
+    payloads: string[];
+    mode?: "insert_after";
+    lineNum: number;
+    index: number;
+};
+/** File-level operation parsed from a section body (`REM` / `MV`). */
+export type FileOp = {
+    kind: "rem";
+} | {
+    kind: "move";
+    dest: string;
+};
+/** Result of applying a parsed set of edits to a text body. */
+export interface ApplyResult {
+    /** Post-edit text body. */
+    text: string;
+    /** First line number (1-indexed) that changed, or `undefined` for a no-op apply. */
+    firstChangedLine?: number;
+    /** Diagnostic warnings collected by the parser, patcher, or recovery. */
+    warnings?: string[];
+    /**
+     * Resolved spans for each `replace_block`/`delete_block` op in this apply,
+     * in patch order. Present only when the apply matched the tagged content
+     * (the common no-drift path), so the line numbers line up with what the
+     * caller read. Absent when there were no block ops.
+     */
+    blockResolutions?: BlockResolution[];
+}
+/** A parsed `[A.=B]` line range. */
+export interface ParsedRange {
+    start: Anchor;
+    end: Anchor;
+}
+/** Optional hints for {@link splitPatchInput}. */
+export interface SplitOptions {
+    /** Resolves absolute paths inside hashline headers to cwd-relative form. */
+    cwd?: string;
+    /**
+     * Fallback path used when the input lacks a `[PATH]` header but contains
+     * recognizable hashline operations. Lets streaming previews work before
+     * the model has written the header.
+     */
+    path?: string;
+}
+/** Streaming-formatter knobs for {@link streamHashLines}. */
+export interface StreamOptions {
+    /** First line number to use when formatting (1-indexed, default 1). */
+    startLine?: number;
+    /** Maximum formatted lines per yielded chunk (default 200). */
+    maxChunkLines?: number;
+    /** Maximum UTF-8 bytes per yielded chunk (default 64 KiB). */
+    maxChunkBytes?: number;
+}
+/** Result of {@link buildCompactDiffPreview}. */
+export interface CompactDiffPreview {
+    preview: string;
+    addedLines: number;
+    removedLines: number;
+}
+/** Optional knobs for {@link buildCompactDiffPreview}. */
+export interface CompactDiffOptions {
+    /** Added lines kept on each side of a long added-run elision (default 2). */
+    maxAddedRunContext?: number;
+    /** Back-compat alias for {@link maxAddedRunContext}. */
+    maxUnchangedRun?: number;
+}
+/**
+ * Resolved 1-indexed inclusive line span of a `replace_block N:` target.
+ */
+export interface BlockSpan {
+    /** First line of the block (1-indexed, inclusive). */
+    start: number;
+    /** Last line of the block (1-indexed, inclusive). */
+    end: number;
+}
+/**
+ * One `replace_block N:` / `delete_block N` / `insert_after_block N:` anchor
+ * resolved to its concrete line span. Surfaced on {@link ApplyResult} so the
+ * host can echo "block N → lines start.=end" and let the model catch a wrong
+ * opener — e.g. a decorator or doc-comment that sits in a separate node
+ * outside the resolved block.
+ */
+export interface BlockResolution {
+    /** The 1-indexed line the block op was anchored on (the `N`). */
+    anchorLine: number;
+    /** First line of the resolved span (1-indexed, inclusive). */
+    start: number;
+    /** Last line of the resolved span (1-indexed, inclusive). */
+    end: number;
+    /** Which block op produced this resolution. */
+    op: "replace" | "delete" | "insert_after";
+}
+/** Request handed to a {@link BlockResolver} to resolve one `replace_block N:` anchor. */
+export interface BlockResolverRequest {
+    /** Target file path (used to infer language by extension). */
+    path: string;
+    /** Full text the block must be resolved against (the snapshot the tag names). */
+    text: string;
+    /** 1-indexed line the block must begin on. */
+    line: number;
+}
+/**
+ * Resolves a `replace_block N:` anchor to the line span of the syntactic block
+ * that begins on line N. Returns `null` when no block can be resolved
+ * (unrecognized language, blank/out-of-range line, no node begins there, or the
+ * resolved subtree has a syntax error). Pure seam: the hashline core declares
+ * the contract; the host injects a tree-sitter-backed implementation.
+ */
+export type BlockResolver = (request: BlockResolverRequest) => BlockSpan | null;

package/package.json

@@ -0,0 +1,64 @@
+{
+	"type": "module",
+	"name": "jeopi-hashline",
+	"version": "16.2.13",
+	"description": "Hashline: a compact, line-anchored patch language and applier. Pluggable FS/IO so it works over disk, in-memory, or any custom backend.",
+	"homepage": "https://github.com/akillness/jeopi",
+	"author": "Can Boluk",
+	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/akillness/jeopi.git",
+		"directory": "packages/hashline"
+	},
+	"bugs": {
+		"url": "https://github.com/akillness/jeopi/issues"
+	},
+	"keywords": [
+		"patch",
+		"diff",
+		"edit",
+		"hashline",
+		"agent",
+		"llm"
+	],
+	"main": "./src/index.ts",
+	"types": "./dist/types/index.d.ts",
+	"scripts": {
+		"check": "biome check . && bun run check:types",
+		"check:types": "tsgo -p tsconfig.json --noEmit",
+		"lint": "biome lint .",
+		"test": "bun test --parallel",
+		"fix": "biome check --write --unsafe .",
+		"fmt": "biome format --write ."
+	},
+	"dependencies": {
+		"diff": "^9.0.0",
+		"lru-cache": "11.5.1"
+	},
+	"devDependencies": {
+		"@types/bun": "^1.3.14"
+	},
+	"engines": {
+		"bun": ">=1.3.14"
+	},
+	"files": [
+		"src",
+		"README.md",
+		"CHANGELOG.md",
+		"dist/types"
+	],
+	"exports": {
+		".": {
+			"types": "./dist/types/index.d.ts",
+			"import": "./src/index.ts"
+		},
+		"./grammar.lark": "./src/grammar.lark",
+		"./prompt.md": "./src/prompt.md",
+		"./*": {
+			"types": "./dist/types/*.d.ts",
+			"import": "./src/*.ts"
+		},
+		"./*.js": "./src/*.ts"
+	}
+}