@oh-my-pi/hashline 15.10.12 → 15.11.1

package/dist/types/messages.d.ts

@@ -6,6 +6,13 @@
  */
 /** Lines of context shown either side of a hash mismatch. */
 export declare const MISMATCH_CONTEXT = 2;
+/**
+ * Render numbered `LINE:TEXT` context rows around `anchorLines`
+ * (±{@link MISMATCH_CONTEXT} lines each), `*`-marking the anchored lines and
+ * separating non-adjacent runs with `...`. Out-of-range anchors contribute no
+ * rows; returns an empty array when every anchor is out of range.
+ */
+export declare function formatAnchoredContext(anchorLines: readonly number[], fileLines: readonly string[]): string[];
 /** 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. */
@@ -32,10 +39,11 @@ export declare const EMPTY_BLOCK = "`replace block N:` needs at least one `+TEXT
  * Error text emitted when a block-anchored op 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
- * concrete-line form.
+ * a syntax error). Names the offending line, steers back to an explicit
+ * concrete-line form, and — when `fileLines` is provided — appends a
+ * {@link formatAnchoredContext} preview of the file around the anchor line.
  */
-export declare function blockUnresolvedMessage(line: number, op?: "replace" | "delete" | "insert_after"): string;
+export declare function blockUnresolvedMessage(line: number, op?: "replace" | "delete" | "insert_after", fileLines?: readonly string[]): string;
 /**
  * Error text emitted when a block-anchored edit reaches a code path that
  * has no {@link BlockResolver} wired in. Indicates a host-configuration bug

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/hashline",
-	"version": "15.10.12",
+	"version": "15.11.1",
 	"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

@@ -69,7 +69,9 @@ export function resolveBlockEdits(
 		if (span === null) {
 			if (onUnresolved === "drop") continue;
 			throw new Error(
-				`line ${edit.lineNum}: ${resolver ? blockUnresolvedMessage(edit.anchor.line, op) : BLOCK_RESOLVER_UNAVAILABLE}`,
+				`line ${edit.lineNum}: ${
+					resolver ? blockUnresolvedMessage(edit.anchor.line, op, text.split("\n")) : BLOCK_RESOLVER_UNAVAILABLE
+				}`,
 			);
 		}
 		options.onResolved?.({

package/src/messages.ts

@@ -5,11 +5,37 @@
  * them.
  */
 
-import { HL_FILE_HASH_SEP, HL_FILE_PREFIX, HL_FILE_SUFFIX } from "./format";
+import { formatNumberedLine, HL_FILE_HASH_SEP, HL_FILE_PREFIX, HL_FILE_SUFFIX } from "./format";
 
 /** Lines of context shown either side of a hash mismatch. */
 export const MISMATCH_CONTEXT = 2;
 
+/**
+ * Render numbered `LINE:TEXT` context rows around `anchorLines`
+ * (±{@link MISMATCH_CONTEXT} lines each), `*`-marking the anchored lines and
+ * separating non-adjacent runs with `...`. Out-of-range anchors contribute no
+ * rows; returns an empty array when every anchor is out of range.
+ */
+export function formatAnchoredContext(anchorLines: readonly number[], fileLines: readonly string[]): string[] {
+	const displayLines = new Set<number>();
+	for (const line of anchorLines) {
+		if (line < 1 || line > fileLines.length) continue;
+		const lo = Math.max(1, line - MISMATCH_CONTEXT);
+		const hi = Math.min(fileLines.length, line + MISMATCH_CONTEXT);
+		for (let lineNum = lo; lineNum <= hi; lineNum++) displayLines.add(lineNum);
+	}
+	const anchorSet = new Set(anchorLines);
+	const rows: string[] = [];
+	let previous = -1;
+	for (const lineNum of [...displayLines].sort((a, b) => a - b)) {
+		if (previous !== -1 && lineNum > previous + 1) rows.push("...");
+		previous = lineNum;
+		const marker = anchorSet.has(lineNum) ? "*" : " ";
+		rows.push(`${marker}${formatNumberedLine(lineNum, fileLines[lineNum - 1] ?? "")}`);
+	}
+	return rows;
+}
+
 /** Optional patch envelope start marker; silently consumed when present. */
 export const BEGIN_PATCH_MARKER = "*** Begin Patch";
 
@@ -50,10 +76,15 @@ export const EMPTY_BLOCK =
  * Error text emitted when a block-anchored op 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
- * concrete-line form.
+ * a syntax error). Names the offending line, steers back to an explicit
+ * concrete-line form, and — when `fileLines` is provided — appends a
+ * {@link formatAnchoredContext} preview of the file around the anchor line.
  */
-export function blockUnresolvedMessage(line: number, op: "replace" | "delete" | "insert_after" = "replace"): string {
+export function blockUnresolvedMessage(
+	line: number,
+	op: "replace" | "delete" | "insert_after" = "replace",
+	fileLines?: readonly string[],
+): string {
 	const phrase =
 		op === "delete"
 			? `delete block ${line}`
@@ -66,11 +97,15 @@ export function blockUnresolvedMessage(line: number, op: "replace" | "delete" |
 			: op === "insert_after"
 				? `\`insert after M:\` with the block's explicit last line`
 				: `\`replace ${line}..M:\` with the block's explicit end line`;
-	return (
+	let message =
 		`\`${phrase}\` could not resolve a syntactic block beginning on line ${line}. ` +
 		`The language may be unsupported, the line may be blank or a closing delimiter, or the block may not parse. ` +
-		`Use ${fallback} instead.`
-	);
+		`Use ${fallback} instead.`;
+	if (fileLines) {
+		const context = formatAnchoredContext([line], fileLines);
+		if (context.length > 0) message += `\n\n${context.join("\n")}`;
+	}
+	return message;
 }
 
 /**

package/src/mismatch.ts

@@ -6,8 +6,8 @@
  * plus a couple of lines of surrounding context. The {@link MismatchError}
  * formats this into a message at construction time.
  */
-import { formatNumberedLine, HL_FILE_HASH_EXAMPLES, HL_FILE_HASH_SEP, HL_FILE_PREFIX, HL_FILE_SUFFIX } from "./format";
-import { MISMATCH_CONTEXT } from "./messages";
+import { HL_FILE_HASH_EXAMPLES, HL_FILE_HASH_SEP, HL_FILE_PREFIX, HL_FILE_SUFFIX } from "./format";
+import { formatAnchoredContext } from "./messages";
 
 const LINE_REF_RE = /^\s*[>+\-*]*\s*(\d+)(?::.*)?\s*$/;
 /** Format the required-shape diagnostic shown when a line reference is malformed. */
@@ -46,17 +46,6 @@ export interface MismatchDetails {
 	hashRecognized?: boolean;
 }
 
-function getMismatchDisplayLines(anchorLines: readonly number[], fileLines: string[]): number[] {
-	const displayLines = new Set<number>();
-	for (const line of anchorLines) {
-		if (line < 1 || line > fileLines.length) continue;
-		const lo = Math.max(1, line - MISMATCH_CONTEXT);
-		const hi = Math.min(fileLines.length, line + MISMATCH_CONTEXT);
-		for (let lineNum = lo; lineNum <= hi; lineNum++) displayLines.add(lineNum);
-	}
-	return [...displayLines].sort((a, b) => a - b);
-}
-
 /**
  * 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
@@ -113,19 +102,10 @@ export class MismatchError extends Error {
 	}
 
 	static formatMessage(details: MismatchDetails): string {
-		const anchorSet = new Set(details.anchorLines ?? []);
 		const lines = MismatchError.rejectionHeader(details);
-		const displayLines = getMismatchDisplayLines(details.anchorLines ?? [], details.fileLines);
-		if (displayLines.length === 0) return lines.join("\n");
-		lines.push("");
-		let previous = -1;
-		for (const lineNum of displayLines) {
-			if (previous !== -1 && lineNum > previous + 1) lines.push("...");
-			previous = lineNum;
-			const text = details.fileLines[lineNum - 1] ?? "";
-			const marker = anchorSet.has(lineNum) ? "*" : " ";
-			lines.push(`${marker}${formatNumberedLine(lineNum, text)}`);
-		}
+		const context = formatAnchoredContext(details.anchorLines ?? [], details.fileLines);
+		if (context.length === 0) return lines.join("\n");
+		lines.push("", ...context);
 		return lines.join("\n");
 	}
 }

package/src/prompt.md

@@ -11,7 +11,7 @@ Every file section starts with `[PATH#TAG]`. `TAG` is the 4-hex snapshot tag fro
 `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 syntactic block that BEGINS on line N (resolved like `replace block`).
+`insert after block N:` — insert the body rows after the END of the syntactic block that BEGINS on line N. Point N at the line that OPENS the construct (the `if`/`function`/`def`/`{`-bearing line), not the closing delimiter / last visible line; if you have the last line, use plain `insert after M:` instead.
 `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:`).
@@ -36,6 +36,7 @@ There is NO other body row kind. NEVER write `-old` or a bare/context line. To k
 - Keep every range as tight as the change: a range covers 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. Tightness means excluding unchanged lines, not being short: a range where every line genuinely changes is correctly long. Tight ranges bound the blast radius of a stale number: a stale one-line range corrupts one line; a stale wide range shreds every line it spans. This applies to hand-counted `replace N..M` ranges; `replace block N` is exempt — tree-sitter fixes the end.
 - `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`); glance at it to confirm you got what you meant. Use `replace N..M` to change specific lines inside a construct.
 - The resolved span of `replace block N` is EXACTLY the node beginning on line N. A leading decorator, attribute, or doc-comment is a separate node and is NOT included; to take a decorated 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.
+- `insert after block N` follows the same opener-only anchor rule as `replace block N`: N is the first line of the syntactic block, never a line inside it, its closing delimiter, or its last visible line. To append after a closing delimiter you can see, use plain `insert after M:`.
 - 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.
@@ -125,6 +126,13 @@ replace 2..4:
 # 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>