pi-hashline-edit-pro 0.3.1 → 0.3.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-hashline-edit-pro",
-  "version": "0.3.1",
+  "version": "0.3.2",
   "description": "Strict hashline read/edit tool override for pi-coding-agent with hash-anchored edits (4-char, 24-bit)",
   "repository": {
     "type": "git",

package/src/edit-diff.ts

@@ -4,7 +4,6 @@ import {
   ANCHOR_LENGTH,
 } from "./hashline";
 
-// ─── Line ending normalization ──────────────────────────────────────────
 
 export function detectLineEnding(content: string): "\r\n" | "\n" {
   const crlfIdx = content.indexOf("\r\n");
@@ -30,7 +29,6 @@ export function stripBom(content: string): { bom: string; text: string } {
     : { bom: "", text: content };
 }
 
-// ─── Diff generation ────────────────────────────────────────────────────
 
 function formatDiffPreviewLine(
   prefix: " " | "+" | "-",
@@ -38,9 +36,6 @@ function formatDiffPreviewLine(
   hash: string | undefined,
 ): string {
   if (hash === undefined) {
-    // Removed lines have no hash, but they still need column alignment with
-    // the hash-prefixed lines (` HASH:`, `+HASH:`). Pad with `HASH_LENGTH`
-    // spaces so the `:` lines up in the same column.
     return `${prefix}${" ".repeat(ANCHOR_LENGTH)}:${line}`;
   }
   return `${prefix}${hash}:${line}`;

package/src/edit-normalize.ts

@@ -1,29 +1,6 @@
-/**
- * Single normalization layer that maps the dialects a model may emit onto the
- * canonical hashline edit request before validation runs.
- *
- * The only dialect we still absorb is the `file_path` → `path` alias and the
- * JSON-stringified `edits` array. Pi's native legacy `oldText`/`newText`
- * shape (whether top-level or as `op: "replace_text"`) is no longer
- * supported: the hashline protocol requires hash-anchored edits, and the
- * legacy text-matching path is what produces the
- * `[E_NO_MATCH] replace_text found no exact unique match` failure mode the
- * model hits on whitespace/Unicode drift. Any model that still emits the
- * legacy shape is rejected with a clear error in `assertEditItem` /
- * `assertEditRequest` so it learns the correct shape on the next turn.
- *
- * This runs as the tool's `prepareArguments` hook, which Pi executes before AJV
- * schema validation and before `execute()`. The output is plain enumerable data
- * (an `edits` array), so Pi's `structuredClone` of prepareArguments output keeps
- * every field.
- */
 
 import { isRecord, hasOwn } from "./utils";
 
-/**
- * Parse `edits` when a model serializes it as a JSON string instead of an array
- * (observed with some models, mirrors Pi's built-in edit handling).
- */
 function coerceEditsArray(edits: unknown): unknown {
 	if (typeof edits !== "string") {
 		return edits;
@@ -37,12 +14,6 @@ function coerceEditsArray(edits: unknown): unknown {
 }
 
 
-/**
- * Normalize a raw edit-tool request into the canonical hashline shape.
- *
- * Returns the input unchanged when it is not an object, so malformed payloads
- * still reach validation and surface a precise error there.
- */
 export function normalizeEditRequest(input: unknown): unknown {
 	if (!isRecord(input)) {
 		return input;

package/src/edit-response.ts

@@ -1,14 +1,3 @@
-/**
- * Edit response builders.
- *
- * Pulled out of `src/edit.ts` execute() so each returnMode branch
- * (noop / full / ranges / changed) is independently testable and the
- * top-level execute path stays narrative.
- *
- * No behaviour change: outputs are byte-identical to the previous inline
- * implementation. The only additive surface is `details.metrics` (Phase 2 C
- * — observability for hosts; the LLM-visible text is unchanged).
- */
 
 import { generateDiffString } from "./edit-diff";
 import {
@@ -18,10 +7,6 @@ import {
 } from "./hashline";
 import { formatHashlineReadPreview } from "./read";
 
-// Local shape — pi-coding-agent does not export a public `ToolResult`. The
-// builders return `details` as `any` so callers can keep their own per-tool
-// details type without re-asserting it here. This file intentionally does
-// not import the agent's tool-result type to stay decoupled from internals.
 type ToolResult = {
 	content: Array<{ type: "text"; text: string }>;
 	isError?: boolean;
@@ -30,7 +15,6 @@ type ToolResult = {
 
 const CHANGED_ANCHOR_TEXT_BUDGET_BYTES = 50 * 1024;
 
-// ─── Public types ───────────────────────────────────────────────────────
 
 export type ReturnMode = "changed" | "full" | "ranges";
 
@@ -52,14 +36,6 @@ export type FullContentPreview = {
 	nextOffset?: number;
 };
 
-/**
- * Host-visible, opt-in observability surface (Phase 2 C). The LLM never sees
- * this — it lives in `details` only. Hosts can use it for dashboards,
- * adoption metrics, or regression alarms (e.g. "noop rate spiking").
- *
- * snake_case is intentional: most observability backends prefer it and
- * avoiding camelCase saves a transform on the host side.
- */
 export type EditMetrics = {
 	edits_attempted: number;
 	edits_noop: number;

package/src/edit.ts

@@ -127,11 +127,6 @@ export const hashlineEditToolSchema = Type.Object(
 		edits: Type.Optional(
 			Type.Array(hashlineEditItemSchema, { description: "edits over $path" }),
 		),
-		// File-path alias and JSON-stringified edits are still absorbed by
-		// normalizeEditRequest in the prepareArguments hook, which runs before
-		// this schema is validated. The legacy native top-level oldText/newText
-		// dialect is NOT folded — it is rejected outright with [E_LEGACY_SHAPE]
-		// in assertEditRequest, so it never reaches the schema validator.
 	},
 	{ additionalProperties: false },
 );
@@ -205,15 +200,6 @@ const EDIT_PROMPT_SNIPPET = readFileSync(
 
 const ROOT_KEYS = new Set(["path", "returnMode", "returnRanges", "edits"]);
 
-// Validates the canonical edit request envelope after normalizeEditRequest has
-// converged any model dialects. Per-edit structural validation is delegated to
-// resolveEditAnchors (src/hashline.ts), which is the single source of truth for
-// edit-item shape + op constraints. This function validates only the root-level
-// request fields: path, returnMode, returnRanges, and that edits is an array.
-//
-// Intentional overlap with the published TypeBox schema: pi normally runs AJV
-// validation before execute(), but that can be disabled in environments without
-// runtime code generation support, so the semantic checks here are the backstop.
 export function assertEditRequest(
 	request: unknown,
 ): asserts request is EditRequestParams {
@@ -221,12 +207,6 @@ export function assertEditRequest(
 		throw new Error("[E_BAD_SHAPE] Edit request must be an object.");
 	}
 
-	// The legacy native top-level oldText/newText dialect (with or without the
-	// snake_case aliases) is no longer supported. Hash-anchored edits are the
-	// only path — the legacy shape is what produces
-	// `[E_NO_MATCH] replace_text found no exact unique match` on real-world
-	// whitespace/Unicode drift. Reject early with a clear error so the model
-	// learns the right shape on the next turn.
 	for (const legacyKey of ["oldText", "newText", "old_text", "new_text"]) {
 		if (hasOwn(request, legacyKey)) {
 			throw new Error(
@@ -310,16 +290,8 @@ export function assertEditRequest(
 		);
 	}
 
-	// Per-edit validation lives in resolveEditAnchors — the single source of
-	// truth for edit-item shape, op constraints, and anchor parsing.
 }
 
-/**
- * Shared edit pipeline: normalize, validate, read file, resolve anchors,
- * and apply edits. Both `computeEditPreview` (dry-run) and `execute()`
- * (real) call this; the access mode parameter controls whether the file
- * must be writable.
- */
 async function executeEditPipeline(
 	request: unknown,
 	cwd: string,
@@ -392,10 +364,6 @@ async function executeEditPipeline(
 	const originalEnding = detectLineEnding(rawContent);
 	const originalNormalized = normalizeToLF(rawContent);
 
-	// Pre-compute hashes for the original file once. The same array is passed
-	// into applyHashlineEdits so validation and the stale-anchor retry block
-	// agree on what each line's hash is, and so we can return updated
-	// occurrence-aware anchors in the response without recomputing.
 	const originalHashes = computeLineHashes(originalNormalized);
 
 	const resolved = resolveEditAnchors(toolEdits);
@@ -458,16 +426,8 @@ const editToolDefinition: EditToolDefinition = {
 	description: EDIT_DESC,
 	parameters: hashlineEditToolSchema,
 	promptSnippet: EDIT_PROMPT_SNIPPET,
-	// Converge model dialects (JSON-string edits, file_path alias) onto the
-	// canonical hashline shape before Pi validates and before execute(). The
-	// legacy top-level oldText/newText dialect is NOT folded — it is rejected
-	// outright with [E_LEGACY_SHAPE] in assertEditRequest. See
-	// src/edit-normalize.ts.
 	prepareArguments: (args: unknown) =>
 		normalizeEditRequest(args) as EditRequestParams,
-	// Force the default tool shell (Box with pending/success/error background) so
-	// we don't inherit renderShell: "self" from the built-in edit tool of the
-	// same name, which would drop the shared background color block.
 	renderShell: "default",
 	renderCall(args, theme, context) {
 		const previewInput = getRenderablePreviewInput(args);
@@ -588,8 +548,6 @@ const editToolDefinition: EditToolDefinition = {
 	},
 
 	async execute(_toolCallId, params, signal, _onUpdate, ctx) {
-		// normalizeEditRequest is re-applied here so execute does not depend on
-		// prepareArguments having run. Idempotent on canonical input.
 		const normalized = normalizeEditRequest(params);
 		assertEditRequest(normalized);
 		const normalizedParams = normalized;
@@ -667,10 +625,6 @@ const editToolDefinition: EditToolDefinition = {
 				requestedReturnRanges,
 				originalNormalized,
 				result,
-				// Hash the post-edit file once. The result builders will use
-				// these for the per-line anchors in the full / ranges / changed
-				// response blocks; computing once here is cheaper than letting
-				// each builder recompute.
 				resultHashes: computeLineHashes(result),
 				warnings,
 				snapshotId: updatedSnapshotId,

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[],
@@ -580,13 +514,7 @@ export function formatHashlineRegion(
 		.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,74 +1,27 @@
-/**
- * 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.
- */
 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)) &
@@ -78,11 +31,6 @@ function hashToString(h: number): string {
 	return HASH_PREFIX + 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}:`,
 );
@@ -91,40 +39,14 @@ export const HASHLINE_PREFIX_PLUS_RE = new RegExp(
 );
 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). */
 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 +58,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 +78,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 +86,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 +95,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,9 +1,3 @@
-/**
- * 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,
@@ -14,16 +8,9 @@ import {
 	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();
@@ -32,8 +19,6 @@ function diagnoseHashRef(ref: string): string {
 		return `[E_BAD_REF] Invalid anchor. Expected a hash anchor like "#aB3x" (prefix "#" + 4 base64 chars).`;
 	}
 
-	// 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.`;
 	}
@@ -44,13 +29,6 @@ function diagnoseHashRef(ref: string): string {
 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) &&
@@ -62,28 +40,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;
@@ -98,14 +57,6 @@ function assertNoDisplayPrefixes(lines: string[]): void {
 	}
 }
 
-/**
- * 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 =

package/src/hashline/resolve.ts

@@ -1,23 +1,9 @@
-/**
- * Resolution — anchor resolution, edit validation, and mismatch formatting.
- *
- * This module owns the logic that resolves hash anchors to line numbers,
- * validates edit structure, and formats mismatch errors. It is the bridge
- * between the parsed edit requests and the apply pipeline.
- */
 
 import { throwIfAborted } from "../runtime";
 import { HASHLINE_BARE_PREFIX_RE } from "./hash";
 import { parseHashRef, hashlineParseText, type Anchor } from "./parse";
 
-// ─── Types ──────────────────────────────────────────────────────────────
 
-/**
- * The internal, post-resolution representation of an anchor. After
- * `validateAnchorEdits` has resolved the hash to a line, the resulting
- * `ResolvedAnchor` carries the line number plus whether the hash matched
- * exactly (vs. falling back to no-anchor-found / not-found).
- */
 export type ResolvedAnchor = {
 	line: number;
 	hash: string;
@@ -29,11 +15,6 @@ export type HashlineEdit =
 	| { op: "append"; pos?: Anchor; lines: string[] }
 	| { op: "prepend"; pos?: Anchor; lines: string[] };
 
-/**
- * A `HashlineEdit` with all anchors resolved to line numbers. This is
- * the shape consumed by `resolveEditToSpan` and the rest of the apply
- * pipeline.
- */
 export type ResolvedHashlineEdit =
 	| {
 			op: "replace";
@@ -56,17 +37,6 @@ export interface NoopEdit {
 	currentContent: string;
 }
 
-/**
- * Schema-level edit as received from the tool layer.
- *
- * `pos` is the anchor for `append`/`prepend`; `start` and `end` are the
- * inclusive range anchors for `replace`. `lines` is canonicalized to an array.
- *
- * The `oldText` and `newText` fields are legacy — they exist on this type
- * only because `normalizeEditRequest` may pass them through before
- * `assertEditRequest` rejects them with `[E_LEGACY_SHAPE]`. They are
- * never accepted by the edit pipeline. Do not use them in new code.
- */
 export type HashlineToolEdit = {
 	op: string;
 	pos?: string;
@@ -79,17 +49,7 @@ export type HashlineToolEdit = {
 	newText?: string;
 };
 
-// ─── Anchor resolution ──────────────────────────────────────────────────
-
-/**
- * Resolve an `Anchor` to a specific line in the file.
- *
- * Returns a `ResolvedAnchor` on success. Returns an error object on:
- *   - `not_found`: no line in the file has this hash
- *   - `ambiguous`: the hash matches multiple lines (the model must
- *     re-read to disambiguate; the runtime does not accept a
-	 *     `#HASH:content` disambiguator on the wire)
- */
+
 function resolveAnchor(
 	ref: Anchor,
 	fileLines: string[],
@@ -112,7 +72,6 @@ function resolveAnchor(
 	return { ref, kind: "ambiguous", candidates: hashMatches };
 }
 
-// ─── Mismatch formatting ────────────────────────────────────────────────
 
 export function formatMismatchError(
 	mismatches: HashMismatch[],
@@ -170,26 +129,7 @@ export function formatMismatchError(
 	return out.join("\n");
 }
 
-// ─── Edit structure validation ──────────────────────────────────────────
-
-/**
- * Validate + parse flat tool-schema edits into typed internal representations.
- *
- * This is the single source of truth for per-edit structural validation (shape,
- * op constraints, field types) and anchor parsing. `assertEditRequest` validates
- * only the request envelope (path, returnMode, etc.) and delegates here for
- * edit payload validation.
- *
- * Strict: provided anchors must parse successfully. Missing anchors are
- * fine for append (→ EOF) and prepend (→ BOF), but a malformed anchor
- * that was explicitly supplied is always an error.
- *
- * - replace + start + end → range replace (both anchors required; for a
- *   single-line replace, set start = end = the line's hash)
- * - append + pos → append after that anchor
- * - prepend + pos → prepend before that anchor
- * - no anchors → file-level append/prepend (only for those ops)
- */
+
 const ITEM_KEYS = new Set(["op", "pos", "start", "end", "lines"]);
 function isStringArray(value: unknown): value is string[] {
 	return (
@@ -269,15 +209,7 @@ export function resolveEditAnchors(edits: HashlineToolEdit[]): HashlineEdit[] {
 		const op = edit.op;
 		switch (op) {
 			case "replace": {
-				// Normalize `lines: [""]` (a single empty string) to `lines: []`
-				// (deletion). The "lines.length > 0" branch in resolveEditToSpan
-				// preserves the trailing newline of the last replaced line, so a
-				// single-element empty array would leave that newline behind and
-				// produce an extra blank line. Models commonly emit `[""]` to
-				// mean "delete this", and the deletion branch handles the
-				// trailing newline correctly. Note: this is `replace`-only;
-				// `append`/`prepend` legitimately use `[""]` to insert a blank
-				// line.
+				// Normalize lines: [""] to lines: [] for deletion.
 				const replaceLines = hashlineParseText(edit.lines ?? null);
 				const normalizedLines =
 					replaceLines.length === 1 && replaceLines[0] === ""
@@ -312,7 +244,6 @@ export function resolveEditAnchors(edits: HashlineToolEdit[]): HashlineEdit[] {
 	return result;
 }
 
-// ─── Anchor validation ──────────────────────────────────────────────────
 
 function maybeWarnSuspiciousUnicodeEscapePlaceholder(
 	edits: HashlineEdit[],
@@ -327,28 +258,6 @@ function maybeWarnSuspiciousUnicodeEscapePlaceholder(
 	}
 }
 
-/**
- * Reject edit content that starts with a bare hash prefix. Companion to
- * `assertNoDisplayPrefixes`, which rejects the unambiguous `+HASH:` form at
- * the parse stage; this catches the bare `HASH:` form (after optional leading
- * whitespace) at the apply stage. The first 5 characters of every `lines`
- * entry are checked: `#` prefix + 4 alphabet characters (A–Z, a–z, 0–9, `-`, `_`)
- * followed by `:`.
- *
- * Bare `#HASH:` prefixes in `lines` are almost always a model mistake — the
- * model copied the hash prefix from a `read` output but dropped the rest of
- * the rendered `#HASH:content` form. We reject with `[E_BARE_HASH_PREFIX]`
- * rather than warn, because a stray hash in the file content is a silent
- * correctness bug (the line is written verbatim, no autocorrection) and
- * because the cost of a false positive is small: the model can rephrase the
- * line (e.g. quote it, escape the colon, or use a different identifier
- * shape) and retry.
- *
- * The error message lists the offending lines, the suspect hash prefix for
- * each, and whether any of them collide with a real file-line hash. A
- * collision is a strong signal that the model was reading a `#HASH:content`
- * line and copied only the prefix.
- */
 export function assertNoBareHashPrefixLines(
 	edits: HashlineEdit[],
 	fileLines: string[],
@@ -360,8 +269,6 @@ export function assertNoBareHashPrefixLines(
 			`assertNoBareHashPrefixLines: fileHashes.length (${fileHashes.length}) must match fileLines.length (${fileLines.length}).`,
 		);
 	}
-	// Collect bare-prefix suspects up front: regex only. Almost every edit has
-	// none, so this lets the common path bail before paying for file hashes.
 	const suspects: { line: string; hash: string; editIndex: number; lineIndex: number }[] = [];
 	for (let editIndex = 0; editIndex < edits.length; editIndex++) {
 		const edit = edits[editIndex]!;
@@ -379,8 +286,6 @@ export function assertNoBareHashPrefixLines(
 	const matchedCount = matched.length;
 	const exampleLine = `${suspects[0]!.hash}:${suspects[0]!.line}`;
 
-	// For Python files, return a warning instead of throwing — Python uses
-	// `else:`, `except:`, `elif:` etc. which trigger the bare-prefix detector.
 	if (isPython) {
 		const hint = matchedCount > 0
 			? `${matchedCount} prefix(es) match file line hashes.`
@@ -398,18 +303,6 @@ export function assertNoBareHashPrefixLines(
 	);
 }
 
-/**
- * Validate + resolve hash-anchored edits against the current file content.
- *
- * For each anchor, the runtime:
- *   1. Looks up the hash in the file's precomputed hash array.
- *   2. If the hash uniquely matches a line, use it.
- *   3. If the hash matches multiple lines (rare at 24 bits, but possible),
- *      this is `[E_AMBIGUOUS_ANCHOR]` — the model must re-read to refresh.
- *   4. If the hash doesn't match any line, this is `[E_STALE_ANCHOR]`.
- *
- * Boundary / single-anchor / range warnings are appended to `warnings`.
- */
 export function validateAnchorEdits(
 	edits: HashlineEdit[],
 	fileLines: string[],
@@ -548,5 +441,4 @@ export function validateAnchorEdits(
 	return { resolved, mismatches };
 }
 
-// Re-export for apply module
 export { maybeWarnSuspiciousUnicodeEscapePlaceholder };

package/src/read.ts

@@ -95,12 +95,6 @@ export function formatHashlineReadPreview(
 		? Math.min(startLine - 1 + limit, totalLines)
 		: totalLines;
 	const selected = allLines.slice(startLine - 1, endIdx);
-	// The runtime precomputes the full per-line hash array so the model sees
-	// hashes consistent with what validation will compare against. Callers that
-	// already have one (the read tool, chained-edit tests) can pass it in;
-	// otherwise we recompute here for the visible window — acceptable for
-	// preview formatting because the hashes themselves are identical regardless
-	// of which slice of the file we look at.
 	const allHashes = precomputedHashes ?? computeLineHashes(text);
 	const selectedHashes = allHashes.slice(startLine - 1, endIdx);
 	const formatted = formatHashlineRegion(selectedHashes, selected);