pi-hashline-edit-pro 0.3.1 → 0.3.3

package/src/hashline/apply.ts

@@ -1,11 +1,3 @@
-/**
- * Application — edit span resolution, conflict detection, and assembly.
- *
- * This module owns the pipeline that turns resolved edits into character-level
- * spans, detects conflicts, and applies the spans back-to-front to produce
- * the final file content. It also owns the changed-line-range computation
- * and the hashline region formatting used by read and edit responses.
- */
 
 import { throwIfAborted } from "../runtime";
 import { computeLineHashes } from "./hash";
@@ -19,7 +11,6 @@ import {
 	type HashlineEdit,
 } from "./resolve";
 
-// ─── Line index ─────────────────────────────────────────────────────────
 
 type LineIndex = {
 	fileLines: string[];
@@ -47,7 +38,6 @@ export function buildLineIndex(content: string): LineIndex {
 	};
 }
 
-// ─── Edit span resolution ───────────────────────────────────────────────
 
 type ResolvedEditSpan = {
 	kind: "replace" | "insert";
@@ -319,13 +309,6 @@ function assertNoConflictingSpans(spans: ResolvedEditSpan[]): void {
 	}
 }
 
-/**
- * Resolve validated edits into ordered, conflict-free character-level spans.
- *
- * Each edit is mapped through resolveEditToSpan (which may produce a noop),
- * duplicate spans are deduplicated, conflicts are rejected, and the remaining
- * spans are sorted back-to-front for safe in-place assembly.
- */
 function resolveEditSpans(
 	edits: ResolvedHashlineEdit[],
 	content: string,
@@ -378,10 +361,6 @@ function resolveEditSpans(
 	});
 }
 
-/**
- * Apply ordered spans to content in reverse (back-to-front) order so earlier
- * spans' offsets stay valid.
- */
 function assembleEditResult(
 	content: string,
 	spans: ResolvedEditSpan[],
@@ -406,25 +385,7 @@ function assembleEditResult(
 	return result;
 }
 
-// ─── Main edit engine ───────────────────────────────────────────────────
-
-/**
- * Apply hashline-anchored edits to file content.
- *
- * Three-phase pipeline:
- *   1. validateAnchorEdits — resolve each hash to a line; mismatches are
- *      rejected with `[E_STALE_ANCHOR]` and collisions with
- *      `[E_AMBIGUOUS_ANCHOR]`
- *   2. resolveEditSpans   — map edits to character spans, dedup, conflict-detect, sort
- *   3. assembleEditResult — apply spans back-to-front, compute changed range
- *
- * `precomputedHashes` is an optional per-line hash array from
- * `computeLineHashes(content)`. When provided, the same array is used for
- * validation AND for the stale-anchor retry block in mismatch errors, so
- * the hashes the model sees on a stale-anchor failure match the hashes the
- * runtime actually validated against. When omitted, hashes are computed
- * once at the top of this function and threaded through all phases.
- */
+
 export function applyHashlineEdits(
 	content: string,
 	edits: import("./resolve").HashlineEdit[],
@@ -446,13 +407,7 @@ export function applyHashlineEdits(
 			lastChangedLine: undefined,
 		};
 
-	// Normalize `replace` edits: a single-element `lines: [""]` is equivalent
-	// to `lines: []` (deletion). The "non-empty lines" span branch preserves
-	// the trailing newline of the last replaced line, which would leave an
-	// extra blank line behind when the user meant to delete. Models commonly
-	// emit `[""]` to mean "delete this", and the deletion branch handles the
-	// trailing newline correctly. (`append`/`prepend` are unaffected — there
-	// `[""]` legitimately means "insert a blank line".)
+	// Normalize lines: [""] to lines: [] for deletion.
 	edits = edits.map((edit) =>
 		edit.op === "replace" &&
 		edit.lines.length === 1 &&
@@ -466,7 +421,6 @@ export function applyHashlineEdits(
 	const noopEdits: NoopEdit[] = [];
 	const warnings: string[] = [];
 
-	// Phase 1: validate anchors (and resolve to line numbers)
 	const { resolved, mismatches } = validateAnchorEdits(
 		edits,
 		lineIndex.fileLines,
@@ -484,7 +438,6 @@ export function applyHashlineEdits(
 	warnings.push(...barePrefixWarnings);
 	maybeWarnSuspiciousUnicodeEscapePlaceholder(edits, warnings);
 
-	// Phase 2: resolve edits to ordered spans
 	const orderedSpans = resolveEditSpans(
 		resolved,
 		content,
@@ -493,7 +446,6 @@ export function applyHashlineEdits(
 		signal,
 	);
 
-	// Phase 3: assemble result
 	const result = assembleEditResult(content, orderedSpans, signal);
 	assertDoesNotEmptyFile(content, result);
 	const changedRange = computeChangedLineRange(content, result);
@@ -507,17 +459,10 @@ export function applyHashlineEdits(
 	};
 }
 
-// ─── Affected-line computation (for returning anchors after edit) ───────
 
 const ANCHOR_CONTEXT_LINES = 2;
 const ANCHOR_MAX_OUTPUT_LINES = 12;
 
-/**
- * Compute the post-edit line range covering changed lines plus context.
- * Uses `firstChangedLine` and `lastChangedLine` from the edit result for
- * precise bounds. Returns null if the range (with context) exceeds the
- * output budget, signalling that the LLM should re-read instead.
- */
 export function computeAffectedLineRange(params: {
 	firstChangedLine: number | undefined;
 	lastChangedLine: number | undefined;
@@ -537,7 +482,6 @@ export function computeAffectedLineRange(params: {
 		return null;
 	}
 
-	// Empty file after edit: no meaningful anchor block.
 	if (resultLineCount === 0) {
 		return null;
 	}
@@ -545,7 +489,6 @@ export function computeAffectedLineRange(params: {
 	const start = Math.max(1, firstChangedLine - contextLines);
 	const end = Math.min(resultLineCount, lastChangedLine + contextLines);
 
-	// Guard against inverted range (can happen when context pushes end below start).
 	if (end < start) {
 		return null;
 	}
@@ -557,15 +500,6 @@ export function computeAffectedLineRange(params: {
 	return { start, end };
 }
 
-/**
- * Format a list of lines as `#HASH:content` rows.
- *
- * Used by the read tool's preview and the changed-mode anchor block. The
- * hashes must be the precomputed per-line hashes for the file — see
- * `computeLineHashes`. The line number is no longer part of the wire
- * format; callers that need line numbers for pagination or context can
- * compute them separately.
- */
 export function formatHashlineRegion(
 	hashes: string[],
 	lines: string[],
@@ -576,17 +510,11 @@ export function formatHashlineRegion(
 		);
 	}
 	return lines
-		.map((line, index) => `${hashes[index]}:${line}`)
+		.map((line, index) => `${hashes[index]}│${line}`)
 		.join("\n");
 }
 
-// ─── Changed line range computation ─────────────────────────────────
 
-/**
- * Compute first/last changed line numbers between two document versions.
- * Uses character-level diff to locate the changed span, then maps to line
- * numbers in the result document so downstream anchor chaining works.
- */
 export function computeChangedLineRange(
 	original: string,
 	result: string,

package/src/hashline/hash.ts

@@ -1,130 +1,51 @@
-/**
- * Hash computation — xxHash32-based line hashing with occurrence-aware
- * discriminators.
- *
- * This module owns the hash constants, the xxHash32 wrapper, and the
- * per-line hash computation functions. Every other module that needs
- * line hashes goes through `computeLineHashes` (full-file) or
- * `computeLineHash` (single-line helper).
- */
 
 import * as XXH from "xxhashjs";
 
-// ─── Constants ──────────────────────────────────────────────────────────
-
-/**
- * Hash length in characters. The original `pi-hashline-edit` uses 2 chars of
- * a 16-char alphabet (8 bits / 256 buckets); this fork uses 4 chars of a
- * 64-char alphabet (24 bits / 16 777 216 buckets). With HASH_LENGTH=4, the
- * birthday paradox stays out of practical concern for any realistic file
- * size. Bumping to 5 is a one-line change here if you want to push the
- * threshold further; the cost is one more char per anchor in the `read`
- * output.
- */
+
 export const HASH_LENGTH = 4;
 
-/** Prefix marker for hash anchors. Every anchor starts with `#` so the hash */
-/** format is `#` + HASH_LENGTH base64 chars (e.g. `#aB3x`, `#4yN-`). */
-export const HASH_PREFIX = "#";
-
-/** Total wire-format length of an anchor: prefix + hash body. */
-export const ANCHOR_LENGTH = HASH_PREFIX.length + HASH_LENGTH;
-
-/**
- * URL-safe base64 alphabet: A–Z, a–z, 0–9, `-`, `_`. 64 distinct chars
- * giving 6 bits per hash character. No exclusions, no human-readability
- * heuristics — the consumer is an LLM that tokenizes, not a human that
- * squints at pixel glyphs. The `-` and `_` are at the end of the string
- * so any character class built from this alphabet (e.g. `[${HASH_ALPHABET}]`)
- * treats them as literal rather than as range operators.
- */
+export const HASH_PREFIX = "";
+
+export const ANCHOR_LENGTH = HASH_LENGTH;
+
 const HASH_ALPHABET =
 	"ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_";
 const HASH_ALPHABET_BITS = 6;
 const HASH_ALPHABET_MASK = (1 << HASH_ALPHABET_BITS) - 1;
-// `-` must be escaped when used inside a regex character class — otherwise it
-// forms a range with the preceding char (`9-_` spans ASCII 57–95, which
-// silently swallows the literal `-`). The `_` is always literal.
 const HASH_ALPHABET_REGEX_SAFE = HASH_ALPHABET.replace(/-/g, "\\-");
 const HASH_ALPHABET_RE = new RegExp(`^[${HASH_ALPHABET_REGEX_SAFE}]+$`);
 export const HASH_CHARS_CLASS = `${HASH_PREFIX}[${HASH_ALPHABET_REGEX_SAFE}]{${HASH_LENGTH}}`;
-
-/**
- * Encode the top `HASH_LENGTH * 6` bits of a 32-bit hash value as a
- * `HASH_LENGTH`-char string in the URL-safe base64 alphabet.
- *
- * The 0.2.0/0.3.0 releases pre-computed this mapping as a `DICT` lookup
- * table. At 3 chars that was 262 144 entries × 3 chars = ~1 MB of static
- * memory; at 4 chars it would be 16 777 216 entries × 4 chars = ~450 MB
- * and a multi-second module load. So we now compute the string inline.
- * The per-line cost is one xxHash32 call plus `HASH_LENGTH` small string
- * concatenations, which is still nanoseconds — this is called once per
- * line in `computeLineHashes`, not on a hot path.
- */
 function hashToString(h: number): string {
 	const totalBits = HASH_LENGTH * HASH_ALPHABET_BITS;
 	const shift = 32 - totalBits;
 	let n = h >>> shift;
 	let out = "";
 	for (let j = 0; j < HASH_LENGTH; j++) {
-		// Build left-to-right: the first iteration writes the high-order
-		// 6 bits, the last writes the low-order 6 bits.
 		out +=
 			HASH_ALPHABET[
 				(n >>> ((HASH_LENGTH - 1 - j) * HASH_ALPHABET_BITS)) &
 					HASH_ALPHABET_MASK
 			]!;
 	}
-	return HASH_PREFIX + out;
+	return out;
 }
 
-/**
- * Patterns used to detect (and reject) hashline display prefixes inside edit
- * payloads. The runtime no longer strips them — the model must send literal
- * file content. Matching any of these triggers `[E_INVALID_PATCH]`.
- */
 export const HASHLINE_PREFIX_RE = new RegExp(
-	`^\\s*(?:>>>|>>)?\\s*${HASH_CHARS_CLASS}:`,
+	`^\\s*(?:>>>|>>)?\\s*${HASH_CHARS_CLASS}│`,
 );
 export const HASHLINE_PREFIX_PLUS_RE = new RegExp(
-	`^\\+\\s*${HASH_CHARS_CLASS}:`,
+	`^\\+\\s*${HASH_CHARS_CLASS}│`,
 );
 export const DIFF_MINUS_RE = /^-\s*\d+\s{4}/;
 
-/**
- * Bare hashline prefix: a `#` + HASH_LENGTH-char hash followed by ":" with
- * no "LINE#" part (e.g. "#KKZ:### heading", "#TPN:text", "#TJZ:"). Capture
- * group 1 is the full anchor (including `#` prefix).
- *
- * This is the partial-hash failure mode from issue #24: the model copies a
- * hash it saw in `read` output into the line content but drops the rest
- * of the rendered `#HASH:content` form. The anchor (prefix + HASH_LENGTH chars
- * + ":") is matched by this regex, then `assertNoBareHashPrefixLines` rejects
- * the edit with `[E_BARE_HASH_PREFIX]` so the model gets actionable feedback
- * instead of a silent correctness bug.
- */
-export const HASHLINE_BARE_PREFIX_RE = new RegExp(`^\\s*(${HASH_CHARS_CLASS}):`);
-
-/** Lines containing no alphanumeric characters (only punctuation/symbols/whitespace). */
+export const HASHLINE_BARE_PREFIX_RE = new RegExp(`^\\s*(${HASH_CHARS_CLASS})│`);
+
 const RE_SIGNIFICANT = /[\p{L}\p{N}]/u;
 
 function xxh32(input: string, seed = 0): number {
 	return XXH.h32(seed).update(input).digest().toNumber() >>> 0;
 }
 
-/**
- * Discriminator prefixes for the occurrence-aware hash space.
- *
- * `S${lineNumber}` puts symbol-only lines (lone `}`, etc.) into a namespace
- * keyed by line number, so the same `}` on different lines never collides.
- *
- * `C${occurrence}` puts content lines into a namespace keyed by the running
- * occurrence count of that canonical content, so the same `import {...}` on
- * different lines never collides either. This is the key behavioural change
- * from the upstream 2-char hash: identical content now hashes to different
- * values at different positions, so the model can target a specific
- * occurrence without resorting to `offset` + a small `limit` window.
- */
 const SYMBOL_DISCRIMINATOR = (lineNumber: number): string => `S${lineNumber}`;
 const CONTENT_DISCRIMINATOR = (occurrence: number): string => `C${occurrence}`;
 
@@ -136,19 +57,6 @@ function isSymbolOnly(canonical: string): boolean {
 	return !RE_SIGNIFICANT.test(canonical);
 }
 
-/**
- * Compute hashes for every line of the file.
- *
- * Returns an array of length `lines.length`, where index `i` is the hash of
- * line `i + 1` (1-indexed). Two lines with the same canonical content get
- * different hashes based on which occurrence they are.
- *
- * The runtime always works from a precomputed array so that all validation,
- * formatting, and error-message code paths see the same hash for a given line.
- * The standalone `computeLineHash(idx, line)` helper below is kept for
- * single-line use (e.g. diff-preview formatting) where occurrence context
- * is not available; it treats the input as a 1st-occurrence content line.
- */
 export function computeLineHashes(content: string): string[] {
 	const lines = content.split("\n");
 	const hashes = new Array<string>(lines.length);
@@ -169,16 +77,6 @@ export function computeLineHashes(content: string): string[] {
 	return hashes;
 }
 
-/**
- * Single-line hash for callers that don't have the full file context.
- *
- * This treats the input as a 1st-occurrence content line (or, for symbol-only
- * lines, as the line at index `idx`). It is the right answer for diff-preview
- * formatting and for tests that build anchors one line at a time, but it is
- * NOT the same as the hash that `computeLineHashes` would produce for the
- * same line in a file with duplicate content. Production validation always
- * uses `computeLineHashes` + per-line lookup.
- */
 export function computeLineHash(idx: number, line: string): string {
 	const canonical = canonicalizeLine(line);
 	const discriminator = isSymbolOnly(canonical)
@@ -187,7 +85,6 @@ export function computeLineHash(idx: number, line: string): string {
 	return hashToString(xxh32(`${discriminator}:${canonical}`));
 }
 
-/** Exported for tests and for downstream tools that want to mirror the format. */
 export const HASH_FORMAT = {
 	prefix: HASH_PREFIX,
 	length: HASH_LENGTH,
@@ -197,5 +94,4 @@ export const HASH_FORMAT = {
 };
 
 
-/** Re-export HASH_ALPHABET_RE for parse module */
 export { HASH_ALPHABET_RE };

package/src/hashline/index.ts

@@ -1,35 +1,6 @@
-/**
- * Hashline engine — hash-anchored line editing.
- *
- * Forked from pi-hashline-edit (MIT, github.com/RimuruW/pi-hashline-edit),
- * which was vendored & adapted from oh-my-pi (MIT, github.com/can1357/oh-my-pi).
- *
- * This fork preserves the strict semantics of the original (no silent
- * relocation, no autocorrection heuristics, no fuzzy fallback) and uses a
- * `#`-prefixed hash over a 64-character URL-safe base64 alphabet, giving
- * 24 bits of entropy (16 777 216 buckets) per anchor. Birthday-paradox
- * collisions become effectively zero for any realistic file size. The
- * alphabet is sized for an LLM consumer, not a human reader — the model
- * tokenizes, it does not squint at pixel glyphs.
- *
- * Anchor format: `#` prefix + 4 base64 chars (e.g. `#aB3x`). The line number
- * is no longer part of the wire format, and no content may follow the anchor
- * either. The model never has to type a line number; the runtime resolves each
- * anchor to a line via the file's precomputed hash array.
- * a line via the file's precomputed hash array.
- *
- * On a hash collision (two different lines happen to have the same hash
- * — extremely rare at 24 bits) the anchor is rejected with
- * `[E_AMBIGUOUS_ANCHOR]`. The model is expected to disambiguate by calling
- * `read` again to get fresh hashes.
- */
 
-// Re-export everything from sub-modules to preserve the public API surface.
-// Consumers should import from "./hashline" (this index) and get the same
-// symbols as before the split.
 
 export {
-	// Hash computation
 	HASH_LENGTH,
 	HASH_PREFIX,
 	ANCHOR_LENGTH,
@@ -44,14 +15,12 @@ export {
 } from "./hash";
 
 export {
-	// Parsing
 	parseHashRef,
 	hashlineParseText,
 	type Anchor,
 } from "./parse";
 
 export {
-	// Resolution and validation
 	type ResolvedAnchor,
 	type HashlineEdit,
 	type ResolvedHashlineEdit,
@@ -64,7 +33,6 @@ export {
 } from "./resolve";
 
 export {
-	// Application
 	buildLineIndex,
 	applyHashlineEdits,
 	computeAffectedLineRange,

package/src/hashline/parse.ts

@@ -1,60 +1,36 @@
-/**
- * Parsing — anchor parsing and edit content preprocessing.
- *
- * This module owns the wire-format parsing for hash anchors and the
- * content preprocessing that rejects display prefixes in edit payloads.
- */
 
 import {
 	ANCHOR_LENGTH,
-	HASH_PREFIX,
 	HASH_ALPHABET_RE,
 	HASH_CHARS_CLASS,
 	HASHLINE_PREFIX_PLUS_RE,
 	DIFF_MINUS_RE,
 } from "./hash";
 
-// ─── Types ──────────────────────────────────────────────────────────────
 
-/**
- * An anchor is just a hash. The hash is the entire wire format for `pos`
- * and `end` — the runtime looks it up in the file's precomputed hash array
- * to find the line. No content may follow the hash.
- */
 export type Anchor = { hash: string };
 
-// ─── Parsing ────────────────────────────────────────────────────────────
 
 function diagnoseHashRef(ref: string): string {
 	const trimmed = ref.trim();
 
 	if (!trimmed.length) {
-		return `[E_BAD_REF] Invalid anchor. Expected a hash anchor like "#aB3x" (prefix "#" + 4 base64 chars).`;
+		return `[E_BAD_REF] Invalid anchor. Expected a 4-character base64 anchor (e.g. \"aB3x\").`;
 	}
 
-	// Detect the legacy "LINE#HASH" form (5#aB3x, 12#MQ, etc.) so we can
-	// give a clear error pointing at the new format.
-	if (/^\d+\s*#/.test(trimmed)) {
-		return `[E_BAD_REF] Invalid anchor. Use the hash alone (e.g. "#aB3x") — no line numbers or trailing content.`;
+	if (/^\d+/.test(trimmed)) {
+		return `[E_BAD_REF] Invalid anchor. Use the hash alone (e.g. \"aB3x\") — no line numbers or trailing content.`;
 	}
 
-	return `[E_BAD_REF] Invalid anchor "${trimmed}". Expected a hash anchor like "#aB3x".`;
+	return `[E_BAD_REF] Invalid anchor \"${trimmed}\". Expected a 4-character base64 anchor (e.g. \"aB3x\").`;
 }
 
 function parseAnchorRef(ref: string): Anchor {
 	const trimmed = ref.trim();
 
-	// Strict: the wire format is `#` + 4-character hash from the URL-safe base64
-	// alphabet (A-Za-z0-9-_), copied verbatim from `read` output. The first
-	// character of the hash body can be `-` (a valid alphabet char), so an anchor
-	// like `#-qkl` is taken literally. No other form is tolerated: `+`/`-`/`>>>`
-	// markers from diff contexts or stale-anchor retry blocks are rejected. The
-	// model must copy just the anchor (prefix + 4 chars) with no surrounding
-	// characters.
 	if (
 		trimmed.length === ANCHOR_LENGTH &&
-		trimmed.startsWith(HASH_PREFIX) &&
-		HASH_ALPHABET_RE.test(trimmed.slice(HASH_PREFIX.length))
+		HASH_ALPHABET_RE.test(trimmed)
 	) {
 		return { hash: trimmed };
 	}
@@ -62,28 +38,9 @@ function parseAnchorRef(ref: string): Anchor {
 	throw new Error(diagnoseHashRef(ref));
 }
 
-/**
- * Parse a hash anchor. Accepts `#HASH` (e.g. `"#aB3x"`) only. The
- * `#HASH:content` disambiguator from earlier versions is gone — the anchor
- * is the entire wire format for `pos` and `end`, and no content may
- * follow it.
- *
- * Throws `[E_BAD_REF]` for malformed input.
- */
 export const parseHashRef = parseAnchorRef;
 
-// ─── Content preprocessing ──────────────────────────────────────────────
 
-/**
- * Reject hashline display prefixes in edit payloads. Strict semantics: the
- * model must send literal file content for `lines`, not the rendered read /
- * diff form. Silent stripping is no longer performed — see AGENTS.md.
- *
- * This covers the unambiguous `+HASH:` / diff `+/-` forms, rejectable on
- * shape alone. The bare `HHHH:` variant (issue #24) is context-dependent and
- * lives in `assertNoBareHashPrefixLines`.
- *
- */
 function assertNoDisplayPrefixes(lines: string[]): void {
 	for (const line of lines) {
 		if (!line.length) continue;
@@ -92,20 +49,12 @@ function assertNoDisplayPrefixes(lines: string[]): void {
 			DIFF_MINUS_RE.test(line)
 		) {
 			throw new Error(
-			`[E_INVALID_PATCH] "lines" must contain literal file content, not HASH: or diff prefixes. Offending line: ${JSON.stringify(line)}`
+			`[E_INVALID_PATCH] \"lines\" must contain literal file content, not HASH| or diff prefixes. Offending line: ${JSON.stringify(line)}`
 			);
 		}
 	}
 }
 
-/**
- * Parse replacement text into lines.
- *
- * String input is normalized to LF and drops exactly one trailing newline,
- * matching read-preview style content. Array input is preserved verbatim so
- * explicitly provided blank lines remain intact. Display prefixes are
- * rejected by `assertNoDisplayPrefixes`, never silently stripped.
- */
 export function hashlineParseText(edit: string[] | string | null): string[] {
 	if (edit === null) return [];
 	const lines =