@oh-my-pi/hashline 15.10.11 → 15.11.0

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.11",
+	"version": "15.11.0",
 	"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");
 	}
 }