@prometheus-ai/hashline 0.5.3 → 0.5.8

package/CHANGELOG.md

@@ -0,0 +1,7 @@
+# Changelog
+
+## [Unreleased]
+
+## [0.5.0] - 2026-06-11
+
+- Establish Prometheus public baseline for the package.

package/dist/types/apply.d.ts

@@ -1,4 +1,6 @@
 import type { ApplyResult, Edit } from "./types";
+/** A line that is nothing but closing delimiters: `}`, `)`, `];`, `})`, `},`. */
+export declare const STRUCTURAL_CLOSER_RE: RegExp;
 /**
  * Apply a parsed list of edits to a text body. Pure function — no I/O.
  *

package/dist/types/block.d.ts

@@ -1,19 +1,34 @@
-import type { BlockResolver, Edit } from "./types";
+import type { BlockResolution, 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.
+     * How to handle a replace/delete 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. Unresolvable `insert after block N:` edits never reach this: they
+     * are lowered to plain `insert after N:` with a warning.
      */
     onUnresolved?: "throw" | "drop";
+    /**
+     * Invoked once per successfully resolved block edit, in patch order, with
+     * the anchor line and the concrete span it resolved to. Lets the host echo
+     * the resolution back to the caller. Never fired for dropped/unresolvable
+     * edits.
+     */
+    onResolved?: (resolution: BlockResolution) => void;
+    /**
+     * Invoked once per diagnostic produced while resolving — currently the
+     * `insert after block N:` lowerings (closer anchor or unresolvable block).
+     * Hosts should surface these on the apply result's `warnings`.
+     */
+    onWarning?: (message: string) => void;
 }
-/** True when at least one edit is an unresolved `replace block N:` edit. */
+/** True when at least one edit is an unresolved deferred block 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.
+ * Resolve every deferred block 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.
  *

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

@@ -1,12 +1,14 @@
 /**
  * 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.
+ * current-file preview. Removed lines are counted for stats and post-edit
+ * offset tracking, but omitted from the preview. Added and context lines are
+ * anchored to their post-edit positions so a follow-up edit can reuse visible
+ * concrete lines directly. Long contiguous added runs are summarized with a
+ * `…` marker instead of echoing every inserted line.
  *
  * 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;
+export declare function buildCompactDiffPreview(diff: string, options?: CompactDiffOptions): CompactDiffPreview;

package/dist/types/messages.d.ts

@@ -1,85 +1,98 @@
-/**
- * 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.
- */
+/** Centralized error/warning text for the hashline parser, applier, and patcher. */
 /** 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. */
+/**
+ * Numbered `LINE:TEXT` rows around `anchorLines` (±{@link MISMATCH_CONTEXT}),
+ * `*`-marking anchors, `...` between non-adjacent runs. Out-of-range anchors
+ * contribute no rows.
+ */
+export declare function formatAnchoredContext(anchorLines: readonly number[], fileLines: readonly string[]): string[];
+/** Optional patch envelope start marker; silently consumed. */
 export declare const BEGIN_PATCH_MARKER = "*** Begin Patch";
-/** Optional patch envelope end marker; terminates parsing when encountered. */
+/** Optional patch envelope end marker; terminates parsing. */
 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.
+ * Truncation sentinel emitted by an agent loop mid-call. Ends parsing like
+ * {@link END_PATCH_MARKER}, without 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. */
+/** Two consecutive hunks targeted the exact same concrete range. */
+export declare const REPLACE_PAIR_COALESCED_WARNING = "Two hunks targeted the same range; kept only the second. One `replace N..M:` hunk per range \u2014 the body is the final content, never old+new.";
+/** Bare bodyless hunk followed by an overlapping concrete hunk. */
+export declare const REPLACE_PAIR_COALESCED_OVERLAP_WARNING = "Dropped a bare hunk overlapped by the concrete hunk after it. One `replace N..M:` hunk per range \u2014 the body is the final content, never old+new.";
+/** Bare body rows 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.";
+/** Unified-diff-style `-` row in a hunk body. */
+export declare const MINUS_ROW_REJECTED = "`-` rows are not valid; the range already names the lines being changed. For a literal `-` line, write `+-\u2026`.";
+/** Replace hunk with 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.";
+/** `replace block N:` hunk with no body. */
+export declare const EMPTY_BLOCK = "`replace block N:` needs at least one `+TEXT` body row. To delete a block, use `delete block N`.";
+/**
+ * Block-anchored replace/delete could not resolve to a syntactic block
+ * (unsupported language, blank/out-of-range line, no node beginning on N, or
+ * parse error). Appends a {@link formatAnchoredContext} preview when
+ * `fileLines` is given. `insert after block N:` never reaches this — it is
+ * lowered to plain `insert after N:` instead (see
+ * {@link insertAfterBlockUnresolvedLoweredWarning}).
+ */
+export declare function blockUnresolvedMessage(line: number, op?: "replace" | "delete", fileLines?: readonly string[]): string;
+/** Block-anchored edit reached a path with no {@link BlockResolver} wired in — a host-configuration bug. */
+export declare const BLOCK_RESOLVER_UNAVAILABLE = "`replace block`/`delete block`/`insert after block` are not available here (no block resolver configured). Use a concrete 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.
+ * `insert after block N:` anchored on a closing-delimiter line, lowered to
+ * plain `insert after N:` — the closer ends a block, and inserting after it
+ * is exactly what the plain form does.
  */
-export declare function blockUnresolvedMessage(line: number): string;
+export declare function insertAfterBlockCloserLoweredWarning(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.
+ * `insert after block N:` anchor unresolvable (unsupported language, blank
+ * line, parse error, or no resolver), lowered to plain `insert after N:` —
+ * applying with a warning beats failing the patch.
  */
-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.";
+export declare function insertAfterBlockUnresolvedLoweredWarning(line: number): string;
 /**
- * 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.
+ * Internal invariant: `applyEdits` received an unresolved `replace block N:`
+ * edit; `resolveBlockEdits` must run first. Wiring bug, not authored input.
  */
 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. */
+/** Delete hunk received 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. */
+/** `delete block N` hunk received 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:`.";
+/** Insert hunk with 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. */
+/**
+ * `insert after` body indented shallower than the anchor: the landing slid
+ * forward past trailing closer lines — the common "anchored on the last line
+ * I read instead of after the block" mistake.
+ */
+export declare function afterInsertLandingShiftWarning(anchorLine: number, landingLine: number, crossed: number): string;
+/**
+ * `insert after block N:` body indented deeper than the block's closer: the
+ * landing was pulled inside the block — a deeper body almost always means
+ * "append inside the block's body".
+ */
+export declare function blockInsertLandingShiftWarning(blockStart: number, closerLine: number, landingLine: number): string;
+/** `Recovery`: an external write matched 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).";
+/** `Recovery`: 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 (a prior edit in this session advanced the hash).";
 /**
- * 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.
+ * `Recovery`: session-chain replay fast-path. Less certain than
+ * {@link RECOVERY_SESSION_CHAIN_WARNING} — the 3-way merge refused, the
+ * anchor-content gate passed, but a coincidental insert+delete earlier in
+ * the chain could still misplace an anchor — hence the verify hedge.
  */
-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.";
+export declare const RECOVERY_SESSION_REPLAY_WARNING = "Recovered by replaying your edits onto the current file content (a prior in-session edit changed the lines you re-targeted with a stale hash). Verify the diff matches your intent.";
 /**
- * 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).
+ * `insert head:`/`insert tail:` applied despite a stale snapshot tag.
+ * Head/tail position is content-independent, so drift is non-fatal: apply
+ * onto live content and warn instead of hard-failing.
  */
-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.";
+export declare const HEADTAIL_DRIFT_WARNING = "Applied the `insert head:`/`insert tail:` edit despite a stale snapshot tag (file changed since your read) \u2014 head/tail position is content-independent. 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.
+ * Section omitted the mandatory snapshot tag. Shared by the apply
+ * ({@link Patcher.prepare}) and preview/diff paths so both stay in lockstep.
  */
 export declare function missingSnapshotTagMessage(sectionPath: string): string;

package/dist/types/patcher.d.ts

@@ -3,7 +3,7 @@ import type { Patch, PatchSection } from "./input";
 import { type LineEnding } from "./normalize";
 import { Recovery } from "./recovery";
 import type { SnapshotStore } from "./snapshots";
-import type { ApplyResult, BlockResolver } from "./types";
+import type { ApplyResult, BlockResolution, BlockResolver } from "./types";
 export interface PatcherOptions {
     /** Storage backend used for all reads and writes. */
     fs: Filesystem;
@@ -40,6 +40,12 @@ export interface PatchSectionResult {
     firstChangedLine?: number;
     /** Warnings collected by the parser, applier, and (optionally) recovery. */
     warnings: string[];
+    /**
+     * Resolved spans for any `replace block`/`delete block` ops, present when the
+     * apply matched the tagged content. Undefined for patches with no block ops
+     * (and for resolutions routed through drift recovery, where numbers shift).
+     */
+    blockResolutions?: BlockResolution[];
 }
 export interface PatcherApplyResult {
     sections: PatchSectionResult[];

package/dist/types/prefixes.d.ts

@@ -13,6 +13,14 @@
  * common case for echoed file content, and erroneously echoed prefixes will
  * otherwise turn every content line into a (malformed) op.
  */
+/**
+ * Single-pass variant of {@link stripLeadingHashlinePrefixes} that strips at
+ * most one leading hashline prefix (`N:`, `>>>N:`, `+N:` etc.) and does NOT
+ * loop. Use this when the input carries at most one snapshot prefix (e.g. a
+ * bare body row paste from `read` output) — recursive stripping would corrupt
+ * content whose own text starts with `digits:`.
+ */
+export declare function stripOneLeadingHashlinePrefix(line: string): string;
 /**
  * Strip whichever prefix scheme the lines appear to be carrying:
  * - hashline line-number prefixes (`123:`) when every content line has one

package/dist/types/snapshots.d.ts

@@ -34,6 +34,12 @@ export interface InMemorySnapshotStoreOptions {
     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

package/dist/types/tokenizer.d.ts

@@ -21,6 +21,9 @@ export type BlockTarget = {
 } | {
     kind: "insert_after";
     anchor: Anchor;
+} | {
+    kind: "insert_after_block";
+    anchor: Anchor;
 } | {
     kind: "bof";
 } | {

package/dist/types/types.d.ts

@@ -33,6 +33,13 @@ export type Edit = {
     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;
@@ -41,18 +48,21 @@ export type Edit = {
     oldAssertion?: string;
 } | {
     /**
-     * Deferred block edit (`replace block N:` / `delete 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`
-     * (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. `applyEdits` never sees this
+     * 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;
 };
@@ -64,6 +74,13 @@ export interface ApplyResult {
     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 {
@@ -96,9 +113,11 @@ export interface CompactDiffPreview {
     addedLines: number;
     removedLines: number;
 }
-/** Optional knobs for {@link buildCompactDiffPreview}. Reserved for future use. */
+/** Optional knobs for {@link buildCompactDiffPreview}. */
 export interface CompactDiffOptions {
-    /** Maximum entries kept on each side of an unchanged-context truncation (default 2). */
+    /** Added lines kept on each side of a long added-run elision (default 2). */
+    maxAddedRunContext?: number;
+    /** Back-compat alias for {@link maxAddedRunContext}. */
     maxUnchangedRun?: number;
 }
 /**
@@ -110,6 +129,23 @@ export interface BlockSpan {
     /** 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). */

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@prometheus-ai/hashline",
-	"version": "0.5.3",
+	"version": "0.5.8",
 	"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://prometheus.trivlab.com",
 	"author": "Uttam Trivedi",
@@ -44,6 +44,8 @@
 	},
 	"files": [
 		"src",
+		"README.md",
+		"CHANGELOG.md",
 		"dist/types"
 	],
 	"exports": {