@oh-my-pi/hashline 15.10.1 → 15.10.3

package/dist/types/block.d.ts

@@ -1,4 +1,4 @@
-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
@@ -8,6 +8,13 @@ export interface ResolveBlockEditsOptions {
      * or transient parse error must not throw.
      */
     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;
 }
 /** True when at least one edit is an unresolved `replace block N:` edit. */
 export declare function hasBlockEdit(edits: readonly Edit[]): boolean;

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/types.d.ts

@@ -64,6 +64,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 {
@@ -110,6 +117,23 @@ export interface BlockSpan {
     /** Last line of the block (1-indexed, inclusive). */
     end: number;
 }
+/**
+ * One `replace block N:` / `delete 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;
+    /** True for `delete block N`; false for `replace block N:`. */
+    isDelete: boolean;
+}
 /** 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": "@oh-my-pi/hashline",
-	"version": "15.10.1",
+	"version": "15.10.3",
 	"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://omp.sh",
 	"author": "Can Boluk",

package/src/block.ts

@@ -10,7 +10,7 @@
  * remain, so {@link applyEdits} (and recovery) only ever see resolved edits.
  */
 import { BLOCK_RESOLVER_UNAVAILABLE, blockUnresolvedMessage } from "./messages";
-import type { BlockResolver, Cursor, Edit } from "./types";
+import type { BlockResolution, BlockResolver, Cursor, Edit } from "./types";
 
 export interface ResolveBlockEditsOptions {
 	/**
@@ -21,6 +21,13 @@ export interface ResolveBlockEditsOptions {
 	 * or transient parse error must not throw.
 	 */
 	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;
 }
 
 /** True when at least one edit is an unresolved `replace block N:` edit. */
@@ -61,6 +68,12 @@ export function resolveBlockEdits(
 				`line ${edit.lineNum}: ${resolver ? blockUnresolvedMessage(edit.anchor.line) : BLOCK_RESOLVER_UNAVAILABLE}`,
 			);
 		}
+		options.onResolved?.({
+			anchorLine: edit.anchor.line,
+			start: span.start,
+			end: span.end,
+			isDelete: edit.payloads.length === 0,
+		});
 		// Mirror the parser's `replace start..end:` expansion exactly: one
 		// `before_anchor` replacement insert per payload row at `span.start`,
 		// then one delete per line across `[span.start, span.end]`. An empty

package/src/parser.ts

@@ -12,6 +12,7 @@ import {
 	EMPTY_INSERT,
 	MINUS_ROW_REJECTED,
 } from "./messages";
+import { stripOneLeadingHashlinePrefix } from "./prefixes";
 import { type BlockTarget, cloneCursor, type ParsedRange, type Token, Tokenizer } from "./tokenizer";
 import type { Anchor, Cursor, Edit } from "./types";
 
@@ -81,7 +82,7 @@ interface PendingComment {
 	text: string;
 }
 
-type PayloadRow = { kind: "literal"; text: string; lineNum: number };
+type PayloadRow = { kind: "literal"; text: string; lineNum: number; bare?: boolean };
 
 interface Pending {
 	target: BlockTarget;
@@ -220,7 +221,14 @@ export class Executor {
 				throw new Error(`line ${lineNum}: ${DELETE_BLOCK_TAKES_NO_BODY}`);
 			if (text.trimStart().charCodeAt(0) === 45 /* - */) throw new Error(`line ${lineNum}: ${MINUS_ROW_REJECTED}`);
 			if (!this.#warnings.includes(BARE_BODY_AUTO_PIPED_WARNING)) this.#warnings.push(BARE_BODY_AUTO_PIPED_WARNING);
-			this.#pending.payloads.push({ kind: "literal", text, lineNum });
+			// Defer read-output line-number stripping to #flushPending: a bare
+			// "N:text" row is only a copy-paste artifact from snapshot output
+			// when *every* bare row in the hunk carries that prefix. Stripping a
+			// row in isolation would corrupt a genuine body that merely starts
+			// with "digits:" (YAML ports "42:hello", timestamps "12:30") when it
+			// sits next to an unprefixed sibling. Rows with an explicit "+" go
+			// through #handleLiteralPayload and are never bare, never stripped.
+			this.#pending.payloads.push({ kind: "literal", text, lineNum, bare: true });
 			return;
 		}
 		if (text.trim().length === 0) return;
@@ -230,6 +238,26 @@ export class Executor {
 		);
 	}
 
+	/**
+	 * Strip a single read-output line-number prefix (`N:`) from every bare body
+	 * row, but only when *all* bare rows carry one. A uniform set of prefixes is
+	 * the signature of content pasted straight from `read`/`search` output; a
+	 * mixed set means the `N:` is genuine payload content and must stay. Rows
+	 * authored with an explicit `+` are not bare and are never touched.
+	 */
+	#stripBarePrefixesIfUniform(payloads: PayloadRow[]): void {
+		let sawBare = false;
+		for (const row of payloads) {
+			if (!row.bare) continue;
+			sawBare = true;
+			if (stripOneLeadingHashlinePrefix(row.text) === row.text) return;
+		}
+		if (!sawBare) return;
+		for (const row of payloads) {
+			if (row.bare) row.text = stripOneLeadingHashlinePrefix(row.text);
+		}
+	}
+
 	#pushInsert(cursor: Cursor, text: string, lineNum: number, mode?: "replacement"): void {
 		this.#edits.push({
 			kind: "insert",
@@ -263,6 +291,7 @@ export class Executor {
 		const pending = this.#pending;
 		if (!pending) return;
 		const { target, lineNum, payloads } = pending;
+		this.#stripBarePrefixesIfUniform(payloads);
 		this.#pending = undefined;
 		if (target.kind === "delete") {
 			for (const anchor of expandRange(target.range)) this.#pushDelete(anchor, lineNum);

package/src/patcher.ts

@@ -33,7 +33,7 @@ import { MismatchError } from "./mismatch";
 import { detectLineEnding, type LineEnding, normalizeToLF, restoreLineEndings, stripBom } from "./normalize";
 import { Recovery, type RecoveryResult } from "./recovery";
 import type { SnapshotStore } from "./snapshots";
-import type { ApplyResult, BlockResolver, Edit } from "./types";
+import type { ApplyResult, BlockResolution, BlockResolver, Edit } from "./types";
 
 export interface PatcherOptions {
 	/** Storage backend used for all reads and writes. */
@@ -72,6 +72,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 {
@@ -300,6 +306,7 @@ export class Patcher {
 			fileHash,
 			header: formatHashlineHeader(section.path, fileHash),
 			firstChangedLine: applyResult.firstChangedLine,
+			blockResolutions: applyResult.blockResolutions,
 			warnings,
 		};
 	}
@@ -355,6 +362,7 @@ export class Patcher {
 		//     resulting ranges flow through the 3-way-merge recovery below.
 		// When a block edit needs the tagged snapshot but it is unavailable, the
 		// range cannot be placed safely — reject with a MismatchError (re-read).
+		const blockResolutions: BlockResolution[] = [];
 		let resolved: readonly Edit[] = edits;
 		if (hasBlockEdit(edits)) {
 			const baseText =
@@ -362,13 +370,20 @@ export class Patcher {
 			if (baseText === undefined) {
 				throw this.#mismatchError(section, canonicalPath, normalized, expected ?? "", false);
 			}
-			resolved = resolveBlockEdits(edits, baseText, section.path, this.blockResolver, { onUnresolved: "throw" });
+			resolved = resolveBlockEdits(edits, baseText, section.path, this.blockResolver, {
+				onUnresolved: "throw",
+				onResolved: resolution => blockResolutions.push(resolution),
+			});
 		}
 
-		if (expected === undefined) return applyEdits(normalized, resolved);
-		// Whole-file unchanged → the tag still names the live content, so an
-		// edit anchored at ANY line (displayed or not) is safe to apply.
-		if (liveMatches) return applyEdits(normalized, resolved);
+		// No tag, or the tag still names the live content: an edit anchored at any
+		// line is safe to apply, and the resolved block spans line up with what
+		// the caller read, so echo them back. (A drifted file falls through to
+		// recovery below, where line numbers shift, so resolutions are dropped.)
+		if (expected === undefined || liveMatches) {
+			const result = applyEdits(normalized, resolved);
+			return blockResolutions.length > 0 ? { ...result, blockResolutions } : result;
+		}
 		// Head/tail-only inserts are position-stable: "start"/"end" cannot move
 		// with content drift, so a stale tag is non-fatal. Apply onto the live
 		// content and warn instead of hard-failing — unlike an anchored

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

@@ -6,7 +6,7 @@ Every file section starts with `[PATH#TAG]`. `TAG` is the 4-hex snapshot tag fro
 
 <ops>
 replace N..M:      replace original lines N..M with the body rows below. CAUTION, IT IS INCLUSIVE! MAKE SURE YOU INTEND TO DELETE BOTH ENDS!
-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.
+replace block N:   replace the whole syntactic block that BEGINS on line N — header line through closing line — resolved with tree-sitter, so you never count the end. Body rows below. Reach for this to rewrite a whole construct (function/`if`/loop/class body): the end can't be mis-counted or clipped mid-block. Point N at the line that OPENS the construct (the `if`/`function`/`def`/`{`-bearing line), not a closing `}` or a blank line. The span is EXACTLY that node — a leading decorator/attribute/doc-comment is a separate node and is NOT swept in (see rules).
 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.
@@ -31,7 +31,8 @@ There is NO other body row kind. NEVER write `-old` or a bare/context line. To k
 - An elided or partial read is NOT a read of the gap. A `…` (or any collapsed/truncated region) between two excerpts means those lines are UNSEEN — treat them exactly like lines you never opened. Never place a hunk on, or span a range across, an elided region; `read` that range explicitly first. Reconstructing it from memory of "what the code probably looks like" is how ranges drift off-by-N and shred neighboring blocks.
 - 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.
 - 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.
+- 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 one-line range corrupts one line, while a stale wide range shreds every line it spans. (This is about hand-counted `replace N..M` ranges; the `replace block N` operator is the opposite — tree-sitter fixes the end, so it can't be mis-counted or clipped.)
+- `replace block N` vs `replace N..M`: use `replace block N` to rewrite a WHOLE construct (function / `if` / loop / class body) — tree-sitter resolves its closing line, so a long body can't be mis-counted and a stale end can't clip it mid-block; the edit result echoes the span it matched (`replace block N → resolved lines A-B`), so glance at it to confirm you got what you meant. Use `replace N..M` to change specific lines inside a construct. The resolved span is EXACTLY the node beginning on line N: a leading decorator, attribute, or doc-comment is a separate node and is NOT included. To replace a decorated/annotated definition together with its decorator, point N at the FIRST decorator line (Python parses `@dec` + `def` as one block). A leading line-comment that parses as its own node (e.g. Rust `///`) is not captured by any single opener — use `replace N..M` spanning the comment and the construct.
 - 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.
 - Pure additions use `insert`, never a widened `replace`. If the change only adds lines, `insert before/after` the spot and keep every existing line out of all ranges. Do NOT `replace` a span of keepers and retype them around the new line "to preserve" them — those retyped keepers are exactly what gets silently dropped when one is forgotten. A keeper that never enters your body cannot be lost. `replace` is only for lines whose own text changes.
 - 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.
@@ -84,6 +85,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>
@@ -117,6 +127,6 @@ insert after 2:
 <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.
+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 one-line range corrupts one line; a stale wide range shreds everything it spans — to rewrite a whole construct, prefer `replace block N` so tree-sitter fixes the end.
 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.
 </critical>

package/src/types.ts

@@ -59,6 +59,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. */
@@ -112,6 +119,24 @@ export interface BlockSpan {
 	end: number;
 }
 
+/**
+ * One `replace block N:` / `delete 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;
+	/** True for `delete block N`; false for `replace block N:`. */
+	isDelete: boolean;
+}
+
 /** 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). */