@d3ara1n/pi-hashline-edit 0.1.1 → 0.2.0

package/README.md

@@ -2,14 +2,44 @@
 
 > Hashline-style file editing for [pi](https://github.com/earendil-works/pi-coding-agent) — line-anchored edits verified by content hash, replacing `oldText`/`newText` matching.
 
-Edits reference lines by `LINE#HASH` anchors (copied from `read` output) instead of retyping the code to be changed — eliminating string-not-found loops and whitespace battles at the root.
+Edits reference lines by `LINE#HASH` anchors (copied from `read`/`grep` output) instead of retyping the code to be changed — eliminating string-not-found loops and whitespace battles at the root.
+
+## Why hashline?
+
+The built-in `edit` matches `oldText`/`newText` exactly. When the model can't reproduce the source verbatim — wrong indentation, a non-unique snippet, or a line that drifted since the read — the edit fails and you loop. Hashline sidesteps all of it:
+
+- **No string-not-found loops** — you edit by reference (`LINE#HASH`), not by retyping the line you want to change.
+- **No whitespace battles** — the new content is the only thing you type; nothing has to match what's already there. Indentation mistakes on the *old* code are impossible.
+- **Unique-by-construction hashes** — the line number is folded into the hash, so identical lines (blank lines, `}`) never share a hash and never collide.
+- **Chain edits without re-reading** — a successful `edit` returns fresh anchors for the lines it produced, so the next edit cites them directly instead of forcing a full re-read.
+- **Grep-to-edit, no detour** — search results carry the same `LINE#HASH` anchors (grouped by file, context lines included); grab one and edit directly, skipping the read you'd otherwise need.
+- **Surgical drift detection** — each cited anchor is rechecked against the current line only; an unrelated change elsewhere never blocks your edit.
+- **Self-healing stale anchors** — a drifted anchor (content shifted by an edit above it) doesn't force a full re-read: the applicator rescans ±lines for the original content and hands back a fresh `LINE#HASH` to retry with, only asking for a re-read when the content genuinely changed.
+
+## When to use it
+
+Routine local code editing in pi — the common case. If you spend turns fighting "old_string not found" or fixing indentation the model dropped, this is the fix.
+
+## When to turn it off
+
+Set `hashlineEdit.enabled = false` (or uninstall) to fall back to the built-in `read`/`edit`/`grep` when you need **remote or custom-storage files** — the overrides read/write/search the local filesystem directly, so pi's custom `ReadOperations`/`GrepOperations` (SSH, etc.) aren't supported. The same switch lets you opt out per-project.
+
+## Gotchas (vs. the built-in `read`/`edit`)
+
+Once hashline overrides the built-ins, a few things behave differently:
+
+- **`read` is globally overridden.** Every read shows the `LINE#HASH│` prefix on each line — even reads that won't lead to an edit. This is expected (it's the substrate the reliability is built on), just don't be surprised when the format changes for all files.
+- **Conservative overlap.** Two ops whose ranges touch (e.g. `insert_after` immediately followed by `replace` at the same line) are rejected to avoid backfill ambiguity — issue them as two separate `edit` calls.
 
 ## Design
 
-- **Per-line hash + line number, dual anchor**: `read` shows each line with a short hash (`3#aF3│code`); `edit` references `LINE#HASH`. The line number is for humans, the hash for the machine — naturally resilient to line drift.
-- **Context-aware hash**: each line's hash incorporates its neighbors, so identical lines (blank lines, `}`) get different hashes when their context differs — in-file collisions approach zero.
-- **Strict core + pluggable tolerance**: the core `parse → apply` makes zero guesses and fails fast; tolerance (boundary repair, drift relocation, block ops) is layered as independently toggleable middleware.
-- **No legacy compatibility**: overrides the built-in `edit`/`read`. `edit` accepts only the hashline `input`; sending legacy `oldText`/`newText` returns an explicit error (never silently degrades) — so you always know whether hashline is actually in use.
+- **Per-line hash + line number, dual anchor**: `read` shows each line as `3#aF3│code`; `edit` references `LINE#HASH`. The line number is the address; the hash is a checksum that the line at that address is still what was read.
+- **Line folded into the hash**: each line's hash mixes its 1-based line number into its content, so every line is unique by construction — no in-file collisions, no length extension. The hash changes only when the line's own content changes, never when a neighbor changes.
+- **Live, surgical verification**: at apply time each cited anchor's hash is recomputed from the current line content and compared — no stored snapshot, no whole-file stale check. A line that changed (or was misremembered) fails its own anchor; an unrelated change elsewhere never blocks the edit. No fuzzy matching, no boundary repair.
+- **Shifted-anchor recovery**: a mismatched anchor isn't a dead end. The applicator rescans ±`shiftRadius` lines for the original content — holding the original line number fixed and re-hashing each candidate (`hash(line, candidate) === cited` iff the candidate *is* the original) — and returns a ready-to-resend anchor on a unique hit, the candidate list when ambiguous, or the cited line's live content when nothing matches. The model retries without a re-read in the common drift case.
+- **Atomic batches, all failures collected**: every op in one `edit` is verified against the same snapshot; if any anchor fails, *all* failures (each with its recovery) are returned together and nothing is written — partial writes would shift lines and invalidate the very recovery info just returned.
+- **Chain edits without re-reading**: a successful `edit` returns `Updated anchors` for the lines it produced (and the line that shifted into a deletion gap), so the next edit can cite them directly.
+- **No legacy compatibility**: `edit` accepts only structured hashline ops; sending legacy `oldText`/`newText` is rejected at the schema layer (never silently degrades) — so you always know whether hashline is actually in use.
 
 ## Protocol
 
@@ -17,23 +47,49 @@ Edits reference lines by `LINE#HASH` anchors (copied from `read` output) instead
 
 ```
 src/foo.ts · 6 lines
-   1#aF3│import { compute } from "./util"
-   2#7Qk│
-   3#mP0│export function foo(x: number) {
+1#aF3│import { compute } from "./util"
+2#7Qk│
+3#mP0│export function foo(x: number) {
 ```
 
-`edit` `input` — `path` is a tool parameter; `input` holds only ops (no `file:` header, the tool injects it):
+`grep` output (results grouped by file, each line anchored — copy `LINE#HASH` straight into an edit):
 
 ```
-replace 4#kLp:
-+  if (x < 0) throw new Error("neg")
+src/foo.ts · 2 matches
+3#mP0│export function foo(x: number) {
+4#kLp│  return x + 1
+src/util.ts · 1 match
+10#aF3│  const z = compute(x)
+```
+
 
-insert_after 6#b2H:
-+
-+export const bar = foo
+`edit` takes `path` + `edits` (an array of ops, each with `op`, `anchor`/`end` `{line, hash}` from read, and `body` string[]):
+
+```jsonc
+{
+  "path": "src/foo.ts",
+  "edits": [
+    { "op": "replace", "anchor": { "line": 4, "hash": "kLp" }, "body": ["  return x + 1"] },
+    { "op": "insert_after", "anchor": { "line": 6, "hash": "b2H" }, "body": ["", "export const bar = foo"] }
+  ]
+}
 ```
 
-Ops: `replace LINE#HASH[..LINE#HASH]:` · `delete LINE#HASH` · `insert_after LINE#HASH:` · `insert_before LINE#HASH:` · `append:` · `prepend:`. Body rows start with `+`; `+` alone is a blank line; literal `+`/`-` lines become `++`/`+-`.
+Ops: `replace` · `delete` · `insert_after` · `insert_before` · `append` · `prepend`. `anchor`/`end` = `{line, hash}` from read; `body` = new content lines (string[], omit for `delete`).
+
+## Configuration
+
+Add a `hashlineEdit` field to `~/.pi/agent/settings.json` (global) or `.pi/settings.json` in a project (project replaces global):
+
+```jsonc
+{
+  "hashlineEdit": {
+    "enabled": true,     // set false to fall back to the built-in read/edit
+    "hashLen": 4,        // hash length, 2–8 (default 4)
+    "shiftRadius": 15    // ±lines scanned to rescue a stale anchor (default 15; 0 disables)
+  }
+}
+```
 
 ## Installation
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@d3ara1n/pi-hashline-edit",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "type": "module",
   "description": "Hashline-style file editing for pi — line-anchored edits verified by content hash, replacing oldText/newText matching",
   "keywords": [

package/src/core/apply.test.ts

@@ -1,185 +1,264 @@
 import { test } from "node:test";
 import assert from "node:assert/strict";
-import { createSnapshot } from "./snapshot.ts";
+import { computeLineHash } from "./hash.ts";
+import { splitLines } from "./lines.ts";
 import { applyEdits } from "./apply.ts";
-import type { Edit, FileSnapshot } from "./types.ts";
+import type { Anchor } from "./types.ts";
 
-const snap = (text: string): FileSnapshot => createSnapshot("f.ts", text);
-const ln = (s: FileSnapshot, line: number) => ({ line, hash: s.lineHashes[line - 1] });
+/** Live anchor: hash the current content at the given line (1-based). */
+function at(text: string, line: number): Anchor {
+	return { line, hash: computeLineHash(line, splitLines(text)[line - 1]) };
+}
 
 // --- happy paths ---
 
 test("replace single line", () => {
 	const text = "a\nb\nc\n";
-	const s = snap(text);
-	const r = applyEdits(text, [{ op: "replace", start: ln(s, 2), body: ["B"] }], s);
+	const r = applyEdits(text, [{ op: "replace", start: at(text, 2), body: ["B"] }]);
 	assert.equal(r.ok, true);
 	if (r.ok) assert.equal(r.text, "a\nB\nc\n");
 });
 
 test("replace range", () => {
 	const text = "a\nb\nc\nd\ne\n";
-	const s = snap(text);
-	const r = applyEdits(
-		text,
-		[{ op: "replace", start: ln(s, 2), end: ln(s, 4), body: ["X", "Y"] }],
-		s,
-	);
+	const r = applyEdits(text, [{ op: "replace", start: at(text, 2), end: at(text, 4), body: ["X", "Y"] }]);
 	assert.equal(r.ok, true);
 	if (r.ok) assert.equal(r.text, "a\nX\nY\ne\n");
 });
 
 test("delete single line / range", () => {
 	const text = "a\nb\nc\nd\n";
-	const s = snap(text);
-	const r = applyEdits(text, [{ op: "delete", start: ln(s, 2), end: ln(s, 3) }], s);
+	const r = applyEdits(text, [{ op: "delete", start: at(text, 2), end: at(text, 3) }]);
 	assert.equal(r.ok, true);
 	if (r.ok) assert.equal(r.text, "a\nd\n");
 });
 
 test("insert_after", () => {
 	const text = "a\nb\n";
-	const s = snap(text);
-	const r = applyEdits(text, [{ op: "insert_after", anchor: ln(s, 1), body: ["x"] }], s);
+	const r = applyEdits(text, [{ op: "insert_after", anchor: at(text, 1), body: ["x"] }]);
 	assert.equal(r.ok, true);
 	if (r.ok) assert.equal(r.text, "a\nx\nb\n");
 });
 
 test("insert_before", () => {
 	const text = "a\nb\n";
-	const s = snap(text);
-	const r = applyEdits(text, [{ op: "insert_before", anchor: ln(s, 2), body: ["x"] }], s);
+	const r = applyEdits(text, [{ op: "insert_before", anchor: at(text, 2), body: ["x"] }]);
 	assert.equal(r.ok, true);
 	if (r.ok) assert.equal(r.text, "a\nx\nb\n");
 });
 
 test("append / prepend", () => {
 	const text = "a\nb\n";
-	const s = snap(text);
-	const r = applyEdits(
-		text,
-		[
-			{ op: "prepend", body: ["head"] },
-			{ op: "append", body: ["tail"] },
-		],
-		s,
-	);
+	const r = applyEdits(text, [
+		{ op: "prepend", body: ["head"] },
+		{ op: "append", body: ["tail"] },
+	]);
 	assert.equal(r.ok, true);
 	if (r.ok) assert.equal(r.text, "head\na\nb\ntail\n");
 });
 
 test("multiple out-of-order ops → applied at the right positions", () => {
 	const text = "a\nb\nc\n";
-	const s = snap(text);
-	const r = applyEdits(
-		text,
-		[
-			{ op: "insert_after", anchor: ln(s, 3), body: ["z"] },
-			{ op: "replace", start: ln(s, 1), body: ["A"] },
-		],
-		s,
-	);
+	const r = applyEdits(text, [
+		{ op: "insert_after", anchor: at(text, 3), body: ["z"] },
+		{ op: "replace", start: at(text, 1), body: ["A"] },
+	]);
 	assert.equal(r.ok, true);
 	if (r.ok) assert.equal(r.text, "A\nb\nc\nz\n");
 });
 
-test("result carries diff and newSnapshot", () => {
-	const text = "a\nb\n";
-	const s = snap(text);
-	const r = applyEdits(text, [{ op: "replace", start: ln(s, 1), body: ["A"] }], s);
+test("touchedLines covers exactly the lines this edit produced (new-file indices)", () => {
+	const text = "a\nb\nc\n";
+	const r = applyEdits(text, [
+		{ op: "insert_after", anchor: at(text, 3), body: ["z"] },
+		{ op: "replace", start: at(text, 1), body: ["A"] },
+	]);
 	assert.equal(r.ok, true);
 	if (r.ok) {
-		assert.ok(r.diff.includes("@@"));
-		assert.equal(r.newSnapshot.text, "A\nb\n");
-		assert.equal(r.newSnapshot.lineHashes.length, 2);
+		// new file: [A, b, c, z]; this edit produced line index 0 (A) and 3 (z)
+		assert.deepEqual([...r.touchedLines], [0, 3]);
 	}
 });
 
-test("closed loop: newSnapshot can be used for the next edit", () => {
-	let s = snap("a\nb\n");
-	let cur = s.text;
-	const r1 = applyEdits(cur, [{ op: "replace", start: ln(s, 1), body: ["A"] }], s);
-	assert.equal(r1.ok, true);
-	if (r1.ok) {
-		cur = r1.text;
-		s = r1.newSnapshot;
-		const r2 = applyEdits(cur, [{ op: "replace", start: ln(s, 2), body: ["B"] }], s);
-		assert.equal(r2.ok, true);
-		if (r2.ok) assert.equal(r2.text, "A\nB\n");
+test("touchedLines for append", () => {
+	const text = "a\n";
+	const r = applyEdits(text, [{ op: "append", body: ["b", "c"] }]);
+	assert.equal(r.ok, true);
+	if (r.ok) assert.deepEqual([...r.touchedLines], [1, 2]);
+});
+
+test("touchedLines for delete re-anchors the line that shifted into the gap", () => {
+	const text = "a\nb\nc\nd\n";
+	const r = applyEdits(text, [{ op: "delete", start: at(text, 2) }]);
+	assert.equal(r.ok, true);
+	if (r.ok) {
+		// new file: [a, c, d]; deleting line 2 (b) shifts c into index 1
+		assert.deepEqual([...r.touchedLines], [1]);
 	}
 });
 
 // --- error paths ---
 
-test("stale (file changed) rejected", () => {
-	const s = snap("a\nb\n");
-	const r = applyEdits("a\nCHANGED\n", [{ op: "replace", start: ln(s, 1), body: ["x"] }], s);
-	assert.equal(r.ok, false);
-	if (!r.ok) assert.equal(r.error.kind, "stale");
-});
-
-test("anchor hash mismatch rejected (guards against misremembering)", () => {
+test("anchor hash mismatch rejected (line changed)", () => {
 	const text = "a\nb\n";
-	const s = snap(text);
-	const r = applyEdits(text, [{ op: "replace", start: { line: 1, hash: "WRONG" }, body: ["x"] }], s);
+	const r = applyEdits(text, [{ op: "replace", start: { line: 1, hash: "WRONG" }, body: ["x"] }]);
 	assert.equal(r.ok, false);
-	if (!r.ok) assert.equal(r.error.kind, "anchor");
+	if (!r.ok) assert.equal(r.failure.kind, "anchor");
 });
 
 test("line out of range rejected", () => {
 	const text = "a\n";
-	const s = snap(text);
-	const r = applyEdits(text, [{ op: "replace", start: { line: 5, hash: s.lineHashes[0] }, body: ["x"] }], s);
+	const r = applyEdits(text, [{ op: "replace", start: { line: 5, hash: computeLineHash(1, "a") }, body: ["x"] }]);
 	assert.equal(r.ok, false);
-	if (!r.ok) assert.equal(r.error.kind, "anchor");
+	if (!r.ok) assert.equal(r.failure.kind, "anchor");
+});
+
+test("anchor mismatch when the cited line's content differs (live verification)", () => {
+	// hash for line 2's content, but cited as line 1 → must fail because line 1's live content differs
+	const text = "a\nb\n";
+	const r = applyEdits(text, [{ op: "replace", start: { line: 1, hash: computeLineHash(2, "b") }, body: ["x"] }]);
+	assert.equal(r.ok, false);
+	if (!r.ok) assert.equal(r.failure.kind, "anchor");
 });
 
 test("reverse-order range rejected", () => {
 	const text = "a\nb\nc\n";
-	const s = snap(text);
-	const r = applyEdits(
-		text,
-		[{ op: "replace", start: ln(s, 3), end: ln(s, 1), body: ["x"] }],
-		s,
-	);
+	const r = applyEdits(text, [{ op: "replace", start: at(text, 3), end: at(text, 1), body: ["x"] }]);
 	assert.equal(r.ok, false);
-	if (!r.ok) assert.equal(r.error.kind, "range");
+	if (!r.ok) assert.equal(r.failure.kind, "range");
 });
 
 test("overlapping edits rejected", () => {
 	const text = "a\nb\nc\nd\n";
-	const s = snap(text);
-	const r = applyEdits(
-		text,
-		[
-			{ op: "replace", start: ln(s, 2), end: ln(s, 3), body: ["x"] },
-			{ op: "replace", start: ln(s, 3), body: ["y"] },
-		],
-		s,
-	);
+	const r = applyEdits(text, [
+		{ op: "replace", start: at(text, 2), end: at(text, 3), body: ["x"] },
+		{ op: "replace", start: at(text, 3), body: ["y"] },
+	]);
 	assert.equal(r.ok, false);
-	if (!r.ok) assert.equal(r.error.kind, "range");
+	if (!r.ok) assert.equal(r.failure.kind, "range");
 });
 
 test("conflict at the same insertion point rejected", () => {
 	const text = "a\nb\n";
-	const s = snap(text);
-	const r = applyEdits(
-		text,
-		[
-			{ op: "insert_after", anchor: ln(s, 1), body: ["x"] },
-			{ op: "insert_after", anchor: ln(s, 1), body: ["y"] },
-		],
-		s,
-	);
+	const r = applyEdits(text, [
+		{ op: "insert_after", anchor: at(text, 1), body: ["x"] },
+		{ op: "insert_after", anchor: at(text, 1), body: ["y"] },
+	]);
 	assert.equal(r.ok, false);
-	if (!r.ok) assert.equal(r.error.kind, "range");
+	if (!r.ok) assert.equal(r.failure.kind, "range");
 });
 
 test("noop (byte-identical body) rejected", () => {
 	const text = "a\nb\n";
-	const s = snap(text);
-	const r = applyEdits(text, [{ op: "replace", start: ln(s, 1), body: ["a"] }], s);
+	const r = applyEdits(text, [{ op: "replace", start: at(text, 1), body: ["a"] }]);
+	assert.equal(r.ok, false);
+	if (!r.ok) assert.equal(r.failure.kind, "noop");
+});
+
+test("unrelated change elsewhere does NOT block the edit (no global stale check)", () => {
+	// read-time text and current text differ at line 3, but we only touch line 1 — must succeed
+	const readText = "a\nb\nc\n";
+	const currentText = "a\nb\nCHANGED\n";
+	const r = applyEdits(currentText, [{ op: "replace", start: at(readText, 1), body: ["A"] }]);
+	assert.equal(r.ok, true);
+	if (r.ok) assert.equal(r.text, "A\nb\nCHANGED\n");
+});
+
+test("CRLF line endings preserved", () => {
+	const text = "a\r\nb\r\n";
+	const r = applyEdits(text, [{ op: "replace", start: at(text, 1), body: ["A"] }]);
+	assert.equal(r.ok, true);
+	if (r.ok) assert.equal(r.text, "A\r\nb\r\n");
+});
+
+// --- shifted-anchor recovery ---
+
+test("shifted recovery: content moved down → found with a fresh anchor", () => {
+	const readText = "a\nb\nc\nd\ne\n";
+	const currentText = "a\nX\nb\nc\nd\ne\n"; // inserted X after line 1 → "c" moved 3→4
+	const r = applyEdits(currentText, [{ op: "replace", start: at(readText, 3), body: ["C"] }]);
+	assert.equal(r.ok, false);
+	if (!r.ok && r.failure.kind === "anchor") {
+		const f = r.failure.failures[0];
+		assert.equal(f.recovery.kind, "found");
+		if (f.recovery.kind === "found") {
+			assert.equal(f.recovery.newLine, 4);
+			// the rescued anchor must verify against the current file
+			assert.equal(computeLineHash(4, splitLines(currentText)[3]), f.recovery.newHash);
+		}
+	}
+});
+
+test("rescued anchor lets the retry succeed without a re-read", () => {
+	const readText = "a\nb\nc\nd\ne\n";
+	const currentText = "a\nX\nb\nc\nd\ne\n";
+	// first attempt with a stale anchor → rescued
+	const r1 = applyEdits(currentText, [{ op: "replace", start: at(readText, 3), body: ["C"] }]);
+	assert.equal(r1.ok, false);
+	if (r1.ok) return;
+	if (r1.failure.kind !== "anchor") return;
+	const f = r1.failure.failures[0];
+	assert.equal(f.recovery.kind, "found");
+	if (f.recovery.kind !== "found") return;
+	// retry with the rescued anchor → succeeds, file unchanged elsewhere
+	const r2 = applyEdits(currentText, [
+		{ op: "replace", start: { line: f.recovery.newLine, hash: f.recovery.newHash }, body: ["C"] },
+	]);
+	assert.equal(r2.ok, true);
+	if (r2.ok) assert.equal(r2.text, "a\nX\nb\nC\nd\ne\n");
+});
+
+test("shifted recovery: duplicate content → ambiguous candidates", () => {
+	const readText = "a\nx\nb\nx\nc\n";
+	const currentText = "a\nY\nx\nb\nx\nc\n"; // both "x" shifted
+	const r = applyEdits(currentText, [{ op: "replace", start: at(readText, 2), body: ["Z"] }]);
 	assert.equal(r.ok, false);
-	if (!r.ok) assert.equal(r.error.kind, "noop");
+	if (!r.ok && r.failure.kind === "anchor") {
+		const f = r.failure.failures[0];
+		assert.equal(f.recovery.kind, "ambiguous");
+		if (f.recovery.kind === "ambiguous") {
+			assert.deepEqual(
+				f.recovery.candidates.map((c) => c.line),
+				[3, 5],
+			);
+		}
+	}
 });
+
+test("shifted recovery: content genuinely changed → none, with live content", () => {
+	const readText = "a\nb\nc\n";
+	const currentText = "a\nBCHANGED\nc\n"; // "b" is gone
+	const r = applyEdits(currentText, [{ op: "replace", start: at(readText, 2), body: ["B"] }]);
+	assert.equal(r.ok, false);
+	if (!r.ok && r.failure.kind === "anchor") {
+		const f = r.failure.failures[0];
+		assert.equal(f.recovery.kind, "none");
+		assert.equal(f.current?.content, "BCHANGED");
+	}
+});
+
+test("collect-all: two stale anchors in one batch → both failures returned", () => {
+	const readText = "a\nb\nc\nd\n";
+	const currentText = "X\na\nb\nc\nd\n"; // inserted X at top → all shifted +1
+	const r = applyEdits(currentText, [
+		{ op: "replace", start: at(readText, 2), body: ["B"] },
+		{ op: "replace", start: at(readText, 4), body: ["D"] },
+	]);
+	assert.equal(r.ok, false);
+	if (!r.ok && r.failure.kind === "anchor") {
+		assert.equal(r.failure.failures.length, 2);
+		const found = r.failure.failures.map((f) => (f.recovery.kind === "found" ? f.recovery.newLine : -1));
+		assert.deepEqual(found, [3, 5]);
+	}
+});
+
+test("shiftRadius=0 disables rescue (always none)", () => {
+	const readText = "a\nb\nc\nd\ne\n";
+	const currentText = "a\nX\nb\nc\nd\ne\n";
+	const r = applyEdits(currentText, [{ op: "replace", start: at(readText, 3), body: ["C"] }], 4, 0);
+	assert.equal(r.ok, false);
+	if (!r.ok && r.failure.kind === "anchor") {
+		assert.equal(r.failure.failures[0].recovery.kind, "none");
+	}
+});
+