@prometheus-ai/hashline 0.5.4 → 0.5.8

package/src/prefixes.ts

@@ -31,6 +31,16 @@ function stripLeadingHashlinePrefixes(line: string): string {
 	} while (result !== previous);
 	return result;
 }
+/**
+ * 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 function stripOneLeadingHashlinePrefix(line: string): string {
+	return line.replace(HL_PREFIX_RE, "");
+}
 
 interface LinePrefixStats {
 	nonEmpty: number;

package/src/prompt.md

@@ -5,14 +5,15 @@ Every file section starts with `[PATH#TAG]`. `TAG` is the 4-hex snapshot tag fro
 </headers>
 
 <ops>
-replace N..M:      replace original lines N..M with the body rows below.
-replace block N:   replace the whole syntactic block that BEGINS on line N — its header line through its closing line — resolved with tree-sitter. Body rows below. Point N at the line that OPENS the construct (the `if`/`function`/`def`/`{`-bearing line), not a closing `}` or a blank line.
-delete N..M        delete original lines N..M. No body.
-delete block N     delete the whole syntactic block that BEGINS on line N.
-insert before N:   insert the body rows immediately before line N.
-insert after N:    insert the body rows immediately after line N.
-insert head:       insert the body rows at the very start of the file.
-insert tail:       insert the body rows at the very end of the file.
+`replace N..M:` — replace original lines N..M with the body rows below. INCLUSIVE — line M is consumed too.
+`replace block N:` — replace the whole syntactic block that BEGINS on line N; tree-sitter resolves the closing line. Body rows below.
+`delete N..M` — delete original lines N..M. No body.
+`delete block N` — delete the whole syntactic block that BEGINS on line N.
+`insert before N:` — insert the body rows immediately before line N.
+`insert after N:` — insert the body rows immediately after line N.
+`insert after block N:` — insert the body rows after the END of the block that BEGINS on line N — outside it, at sibling depth. To append inside a block, use `insert after`.
+`insert head:` — insert the body rows at the very start of the file.
+`insert tail:` — insert the body rows at the very end of the file.
 Single line: `replace N..N:` / `delete N`. The range is the ORIGINAL lines you touch; body length is irrelevant (replacing 1 line with 10 is still `replace N..N:`).
 </ops>
 
@@ -23,15 +24,22 @@ There is NO other body row kind. NEVER write `-old` or a bare/context line. To k
 </body-rows>
 
 <rules>
-- Line numbers come from `read`/`search` (`LINE:TEXT`). Copy the `[PATH#TAG]` header; use the bare LINE numbers.
-- Numbers refer to the ORIGINAL file and stay valid for the whole patch — they do not shift as hunks apply.
-- Across calls they do NOT survive: each applied edit mints a fresh `#TAG` and renumbers the file, so the tag and line numbers you just used are dead. Anchor the next edit on the `[PATH#TAG]` and lines from the edit response (or re-`read`), never on pre-edit numbers.
-- A line number is an offset, not a structural boundary: never `insert after N` into a construct you have not read, and never start or end a `replace`/`delete` range mid-expression or mid-block. If unsure what is on those lines, `read` them first.
-- On a stale-tag rejection — or any result you cannot fully account for — STOP and re-`read`. Never stack more line-numbered edits onto output you have not re-grounded; that compounds corruption.
+- Line numbers and the `[PATH#TAG]` header come from your latest `read`/`search` (`LINE:TEXT` rows).
+- Numbers refer to the ORIGINAL file; they do not shift as hunks apply.
+- They die with the call: every applied edit mints a fresh `#TAG` and renumbers — anchor the next edit on the edit response or a fresh `read`.
+- Touch only lines you literally saw as `LINE:TEXT`; the tag certifies the snapshot, not your knowledge of it.
+- Elided regions (`…`) are UNSEEN — never place or span a hunk across one; `read` it first.
+- Never start or end a range mid-expression or mid-block.
+- Indent body rows exactly for the depth they should live at.
+- On a stale-tag rejection or any surprising result: STOP and re-`read` before further edits.
 - One hunk per range; the body is the final content, never an old/new pair.
-- Keep every range as tight as the change: a range must cover ONLY lines whose content actually changes. Never widen it to swallow an unchanged signature, brace, or neighboring statement just to rewrite a few lines inside — change one line with `replace N..N`, not the whole block around it. (A range where every line genuinely changes is correctly long; tightness is about excluding unchanged lines, not about being short.) This bounds the blast radius if a number is off: a stale single-line replace corrupts one line, while a stale block replace shreds the whole block and its structure.
-- To change lines 2 and 5 while keeping 3–4, issue two hunks (`replace 2..2:` and `replace 5..5:`). Untouched lines are simply absent from every range.
-- NEVER use this tool to format code — reordering imports, re-indenting, aligning columns, or any mechanical restyling. That is the project formatter's job; run it instead of hand-editing layout here.
+- Ranges cover ONLY lines whose content changes. Never widen over unchanged lines — a stale wide range shreds everything it spans.
+- Whole construct → `replace block N` (tree-sitter resolves the end); lines inside it → `replace N..M`.
+- `replace block N` resolves EXACTLY the node at N. Leading decorators/attributes/doc-comments are separate nodes: point N at the FIRST decorator to sweep both; standalone line-comments are never swept — use `replace N..M`.
+- `insert after block N`: N is the opener, never the closer or last visible line; saw the closer? Use plain `insert after M:`.
+- Non-adjacent changes = separate hunks; untouched lines stay out of every range.
+- Pure additions use `insert`, never a widened `replace` — retyped keepers are exactly what gets dropped.
+- NEVER format/restyle code with this tool; run the project formatter instead.
 </rules>
 
 <example>
@@ -81,6 +89,15 @@ replace block 1:
 +def greet(name):
 +    print(f"Hello, {name}")
 ```
+
+A decorator or doc-comment is a SEPARATE block — `replace block` on the `def`/`fn` line keeps it. Point N at the decorator to take both; here line 1 is `@cache`, so anchoring on the `def` (line 2) would resolve only the function and orphan `@cache`:
+```
+[svc.py#C3D4]
+replace block 1:
++@cache
++def load(key):
++    return store[key]
+```
 </example>
 
 <anti-patterns>
@@ -99,11 +116,28 @@ replace 3..3:
 # RIGHT
 replace 3..3:
 +   return msg
+
+# WRONG — a pure insertion done as a widened `replace`: you only want to add one line after 2,
+# but you replace 2..4, retype the keepers in the body, and drop one (here line 4, `greet("world")`).
+replace 2..4:
++    msg = "Hello, " + name
++    extra = compute(name)
++    print(msg)
+# RIGHT — touch nothing you keep; the new line is the whole body.
+insert after 2:
++    extra = compute(name)
+
+# WRONG — `insert after block N:` anchored on a closing delimiter / last visible line. RIGHT: plain `insert after M:`
+insert after block 3:
++after()
+# RIGHT
+insert after 3:
++after()
 </anti-patterns>
 
 <critical>
 If you remember nothing else:
-1. RE-GROUND AFTER EVERY EDIT. Each applied edit mints a fresh `#TAG` and renumbers the file — the tag and line numbers you just used are now dead. Take the next edit's numbers from the edit response or a fresh `read`, never from pre-edit memory. On a stale-tag rejection or any unexpected result, STOP and re-`read`.
-2. RANGES ARE TIGHT AND IN-BOUNDS. Cover only lines whose content actually changes; never widen a range to swallow an unchanged signature, brace, or statement, and never start or end a range mid-expression or mid-block. A stale single-line replace corrupts one line; a stale block replace shreds the whole block.
-3. THE BODY IS THE FINAL CONTENT. Only `+TEXT` rows under a `:` header — never `-old`/bare context lines, never an old/new pair. The range does the deleting.
+1. RE-GROUND AFTER EVERY EDIT. Every apply mints a fresh `#TAG` and renumbers — take the next edit's numbers from the edit response or a fresh `read`. Stale tag or surprise? STOP, re-`read`.
+2. RANGES ARE TIGHT. Cover only lines that change; a stale wide range shreds everything it spans. Whole construct → `replace block N`.
+3. THE BODY IS THE FINAL CONTENT. Only `+TEXT` rows; never `-old`/context lines. The range does the deleting.
 </critical>

package/src/snapshots.ts

@@ -62,12 +62,20 @@ export abstract class SnapshotStore {
 
 const DEFAULT_MAX_PATHS = 30;
 const DEFAULT_MAX_VERSIONS_PER_PATH = 4;
+/** Global ceiling on retained snapshot text across all paths (UTF-16 code units). */
+const DEFAULT_MAX_TOTAL_BYTES = 64 * 1024 * 1024;
 
 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;
 }
 
 /**
@@ -85,7 +93,15 @@ export class InMemorySnapshotStore extends SnapshotStore {
 
 	constructor(options: InMemorySnapshotStoreOptions = {}) {
 		super();
-		this.#versions = new LRUCache<string, Snapshot[]>({ max: options.maxPaths ?? DEFAULT_MAX_PATHS });
+		this.#versions = new LRUCache<string, Snapshot[]>({
+			max: options.maxPaths ?? DEFAULT_MAX_PATHS,
+			maxSize: options.maxTotalBytes ?? DEFAULT_MAX_TOTAL_BYTES,
+			sizeCalculation: history => {
+				let total = 1;
+				for (const version of history) total += version.text.length;
+				return total;
+			},
+		});
 		this.#maxVersionsPerPath = options.maxVersionsPerPath ?? DEFAULT_MAX_VERSIONS_PER_PATH;
 	}
 

package/src/tokenizer.ts

@@ -204,6 +204,7 @@ export type BlockTarget =
 	| { kind: "delete_block"; anchor: Anchor }
 	| { kind: "insert_before"; anchor: Anchor }
 	| { kind: "insert_after"; anchor: Anchor }
+	| { kind: "insert_after_block"; anchor: Anchor }
 	| { kind: "bof" }
 	| { kind: "eof" };
 
@@ -238,6 +239,16 @@ function scanInsertTarget(line: string, index: number, end: number): TargetScan
 	}
 	const afterEnd = scanKeyword(line, cursor, end, HL_INSERT_AFTER);
 	if (afterEnd !== null) {
+		// `insert after block N:` — resolve N to a tree-sitter block range at
+		// apply time and insert after its last line. Try the `block` sub-keyword
+		// before falling back to a literal `insert after N:` anchor.
+		const blockEnd = scanKeyword(line, skipWhitespace(line, afterEnd, end), end, HL_BLOCK_KEYWORD);
+		if (blockEnd !== null) {
+			const anchor = scanLineNumber(line, skipWhitespace(line, blockEnd, end), end);
+			if (anchor === null) return null;
+			const nextIndex = consumeOptionalColon(line, anchor.nextIndex, end);
+			return { target: { kind: "insert_after_block", anchor: { line: anchor.line } }, nextIndex };
+		}
 		const anchor = scanLineNumber(line, skipWhitespace(line, afterEnd, end), end);
 		if (anchor === null) return null;
 		const nextIndex = consumeOptionalColon(line, anchor.nextIndex, end);

package/src/types.ts

@@ -31,22 +31,32 @@ 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; lineNum: number; index: number; 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;
 	  };
@@ -59,6 +69,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. */
@@ -96,9 +113,11 @@ export interface CompactDiffPreview {
 	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;
 }
 
@@ -112,6 +131,24 @@ export interface BlockSpan {
 	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). */