@d3ara1n/pi-hashline-edit 0.1.0 → 0.1.1

package/README.md

@@ -2,32 +2,27 @@
 
 > 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.
 
-用「行级内容 hash + 行号」双重锚替代 pi 内置的 `oldText`/`newText` 精确匹配编辑。模型指出要改的行（带 hash 校验），而不是重打要改的代码——从根上消除 string-not-found 死循环与空白战争。
+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.
 
-## 设计要点
+## Design
 
-- **行级 hash + 行号双重锚**：`read` 每行带短 hash（`3#aF3│code`），`edit` 引用 `行号#hash`。行号给人读，hash 给机器校验——天然抗行号漂移。
-- **context-aware hash**：每行 hash 把上下两行一起算，使内容相同的行（空行、`}`）因邻居不同而 hash 不同，文件内碰撞接近 0。
-- **严格核心 + 可插拔容错**：核心 `parse → apply` 零猜测、失败快；容错（旧格式归一化、漂移重定位、块解析）做成独立开关的中间件。
-- **不兼容旧格式**：override 内置 `edit`/`read`。edit 只接受 hashline `input`；模型误发 `oldText`/`newText` 会收到明确错误（而非静默降级到旧方案）——让开发者知道 hashline 是否真在用。容错仅限不影响结果的格式归一化。
+- **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.
 
-> **状态**：Phase 1 纯核心库（`src/core/`）已完成，可独立测试。pi 接入层（`src/pi/`）开发中。
+## Protocol
 
-## 协议速览
-
-`read` 输出（每行带锚）：
+`read` output (each line anchored):
 
 ```
 src/foo.ts · 6 lines
    1#aF3│import { compute } from "./util"
    2#7Qk│
    3#mP0│export function foo(x: number) {
-   4#kLp│  if (x < 0) return 0
-   5#xY9│  return compute(x)
-   6#b2H│}
 ```
 
-`edit` 的 `input`：path 在工具参数里，input 只含 ops（无需 `file:` 头，工具自动注入）
+`edit` `input` — `path` is a tool parameter; `input` holds only ops (no `file:` header, the tool injects it):
 
 ```
 replace 4#kLp:
@@ -38,6 +33,8 @@ insert_after 6#b2H:
 +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 `++`/`+-`.
+
 ## Installation
 
 ```bash
@@ -56,4 +53,4 @@ Or add to `~/.pi/agent/settings.json`:
 
 ## Dependencies
 
-- 无额外 `@d3ara1n/pi-*` 依赖；peer `@earendil-works/pi-coding-agent` 随 pi 附带（框架级，按惯例不列）。
+- No additional `@d3ara1n/pi-*` dependencies; peer `@earendil-works/pi-coding-agent` ships with pi (framework-level, not listed by convention).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@d3ara1n/pi-hashline-edit",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "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

@@ -7,9 +7,9 @@ import type { Edit, FileSnapshot } from "./types.ts";
 const snap = (text: string): FileSnapshot => createSnapshot("f.ts", text);
 const ln = (s: FileSnapshot, line: number) => ({ line, hash: s.lineHashes[line - 1] });
 
-// —— 正常路径 ——
+// --- happy paths ---
 
-test("replace 单行", () => {
+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);
@@ -29,7 +29,7 @@ test("replace range", () => {
 	if (r.ok) assert.equal(r.text, "a\nX\nY\ne\n");
 });
 
-test("delete 单行 / range", () => {
+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);
@@ -68,7 +68,7 @@ test("append / prepend", () => {
 	if (r.ok) assert.equal(r.text, "head\na\nb\ntail\n");
 });
 
-test("多操作乱序 → 按位置正确应用", () => {
+test("multiple out-of-order ops → applied at the right positions", () => {
 	const text = "a\nb\nc\n";
 	const s = snap(text);
 	const r = applyEdits(
@@ -83,7 +83,7 @@ test("多操作乱序 → 按位置正确应用", () => {
 	if (r.ok) assert.equal(r.text, "A\nb\nc\nz\n");
 });
 
-test("结果带 diff 与 newSnapshot", () => {
+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);
@@ -95,7 +95,7 @@ test("结果带 diff 与 newSnapshot", () => {
 	}
 });
 
-test("闭环：newSnapshot 可用于下一次 edit", () => {
+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);
@@ -109,16 +109,16 @@ test("闭环：newSnapshot 可用于下一次 edit", () => {
 	}
 });
 
-// —— 错误路径 ——
+// --- error paths ---
 
-test("stale（文件已变）拒绝", () => {
+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 不匹配拒绝（防记错）", () => {
+test("anchor hash mismatch rejected (guards against misremembering)", () => {
 	const text = "a\nb\n";
 	const s = snap(text);
 	const r = applyEdits(text, [{ op: "replace", start: { line: 1, hash: "WRONG" }, body: ["x"] }], s);
@@ -126,7 +126,7 @@ test("anchor hash 不匹配拒绝（防记错）", () => {
 	if (!r.ok) assert.equal(r.error.kind, "anchor");
 });
 
-test("行号越界拒绝", () => {
+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);
@@ -134,7 +134,7 @@ test("行号越界拒绝", () => {
 	if (!r.ok) assert.equal(r.error.kind, "anchor");
 });
 
-test("range 逆序拒绝", () => {
+test("reverse-order range rejected", () => {
 	const text = "a\nb\nc\n";
 	const s = snap(text);
 	const r = applyEdits(
@@ -146,7 +146,7 @@ test("range 逆序拒绝", () => {
 	if (!r.ok) assert.equal(r.error.kind, "range");
 });
 
-test("重叠编辑拒绝", () => {
+test("overlapping edits rejected", () => {
 	const text = "a\nb\nc\nd\n";
 	const s = snap(text);
 	const r = applyEdits(
@@ -161,7 +161,7 @@ test("重叠编辑拒绝", () => {
 	if (!r.ok) assert.equal(r.error.kind, "range");
 });
 
-test("同插入点冲突拒绝", () => {
+test("conflict at the same insertion point rejected", () => {
 	const text = "a\nb\n";
 	const s = snap(text);
 	const r = applyEdits(
@@ -176,7 +176,7 @@ test("同插入点冲突拒绝", () => {
 	if (!r.ok) assert.equal(r.error.kind, "range");
 });
 
-test("noop（body 字节相同）拒绝", () => {
+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);

package/src/core/apply.ts

@@ -1,12 +1,15 @@
 /**
- * 纯函数应用器：在快照对应的文件上应用编辑。
+ * Pure-function applicator: applies edits to the file backing a snapshot.
  *
- * 严格语义：
- * - 要求当前 `text === snapshot.text`（stale 检查）；漂移由 `transforms/relocate`
- *   中间件在调用 apply 前处理，纯 apply 不猜。
- * - 每个锚的 hash 必须匹配快照中对应行（防模型记错行号/hash）。
- * - 操作范围不得重叠（含同插入点）。
- * - body 与目标字节相同 → `noop` 错误（引导模型查 bug 而非盲目重试）。
+ * Strict semantics:
+ * - Requires the current `text === snapshot.text` (stale check); drift is
+ *   handled by the `transforms/relocate` middleware before calling apply — pure
+ *   apply does not guess.
+ * - Each anchor's hash must match its corresponding line in the snapshot
+ *   (guards against the model misremembering line numbers / hashes).
+ * - Operation ranges must not overlap (including the same insertion point).
+ * - body byte-identical to the target → `noop` error (guides the model to
+ *   investigate the bug rather than blindly retry).
  *
  * @module pi-hashline-edit/core
  */
@@ -15,14 +18,14 @@ import { buildDiff } from "./diff.ts";
 import { createSnapshot, joinLines, splitLines } from "./snapshot.ts";
 import type { ApplyResult, Edit, FileSnapshot, PatchError } from "./types.ts";
 
-/** 行级操作：把 `[lo, hi)`（0-based，hi exclusive）区间的原始行替换为 newLines。 */
+/** Line-level operation: replace the raw lines in the `[lo, hi)` range (0-based, hi exclusive) with newLines. */
 interface SpanOp {
 	lo: number;
 	hi: number;
 	newLines: string[];
 }
 
-/** 校验锚匹配快照（纯 apply：text 已等于 snapshot.text，故只防记错）。 */
+/** Verify the anchor matches the snapshot (pure apply: text already equals snapshot.text, so this only guards against misremembering). */
 function checkAnchor(snapshot: FileSnapshot, line: number, hash: string): PatchError | null {
 	if (line < 1 || line > snapshot.lineHashes.length) {
 		return {
@@ -39,7 +42,7 @@ function checkAnchor(snapshot: FileSnapshot, line: number, hash: string): PatchE
 	return null;
 }
 
-/** 把 Edit 翻译成 SpanOp，同时校验锚与范围。 */
+/** Translate an Edit into a SpanOp, while verifying anchors and ranges. */
 function translateEdit(edit: Edit, snapshot: FileSnapshot): { op: SpanOp } | { error: PatchError } {
 	switch (edit.op) {
 		case "replace":
@@ -82,18 +85,18 @@ function translateEdit(edit: Edit, snapshot: FileSnapshot): { op: SpanOp } | { e
 	}
 }
 
-/** 零宽区间（插入点）的"最后影响位"是 lo；非零宽是 hi-1。 */
+/** The "last affected position" of a zero-width range (insertion point) is lo; otherwise hi-1. */
 function maxAffected(op: SpanOp): number {
 	return op.lo === op.hi ? op.lo : op.hi - 1;
 }
 
 /**
- * 在快照对应的文件上应用编辑。
+ * Apply edits to the file backing a snapshot.
  *
- * @param text     当前文件全文
- * @param edits    解析出的编辑操作
- * @param snapshot read 时记录的快照（text 必须等于当前 text）
- * @returns 应用结果；失败返回结构化错误
+ * @param text     current full file text
+ * @param edits    parsed edit operations
+ * @param snapshot snapshot recorded at read time (text must equal current text)
+ * @returns apply result; on failure returns a structured error
  */
 export function applyEdits(text: string, edits: Edit[], snapshot: FileSnapshot): ApplyResult {
 	if (text !== snapshot.text) {
@@ -112,7 +115,7 @@ export function applyEdits(text: string, edits: Edit[], snapshot: FileSnapshot):
 		ops.push(t.op);
 	}
 
-	// 重叠检查：按 lo 升序，相邻 op 的起点不得落在前一个的影响区内
+	// Overlap check: sort ascending by lo; the next op's start must not fall inside the previous op's affected range
 	const sorted = [...ops].sort((a, b) => a.lo - b.lo || a.hi - b.hi);
 	for (let k = 1; k < sorted.length; k++) {
 		if (sorted[k].lo <= maxAffected(sorted[k - 1])) {
@@ -126,7 +129,7 @@ export function applyEdits(text: string, edits: Edit[], snapshot: FileSnapshot):
 		}
 	}
 
-	// 从后往前应用（lo 降序），避免行号偏移
+	// Apply back-to-front (lo descending) to avoid line-number shifts
 	let result = [...lines];
 	for (const op of [...sorted].sort((a, b) => b.lo - a.lo)) {
 		result = [...result.slice(0, op.lo), ...op.newLines, ...result.slice(op.hi)];

package/src/core/diff.test.ts

@@ -2,7 +2,7 @@ import { test } from "node:test";
 import assert from "node:assert/strict";
 import { buildDiff } from "./diff.ts";
 
-test("单 hunk", () => {
+test("single hunk", () => {
 	const d = buildDiff("f.ts", ["a", "b", "c"], [{ lo: 1, hi: 2, newLines: ["X"] }]);
 	assert.ok(d.startsWith("--- a/f.ts\n"));
 	assert.ok(d.includes("+++ b/f.ts"));
@@ -11,11 +11,11 @@ test("单 hunk", () => {
 	assert.ok(d.includes("+X"));
 });
 
-test("多行 range hunk 带计数", () => {
+test("multi-line range hunk carries counts", () => {
 	const d = buildDiff("f", ["a", "b", "c", "d"], [{ lo: 0, hi: 3, newLines: ["X"] }]);
-	assert.ok(d.includes("@@ -1,3 +1 @@")); // newCount=1 时省略计数（git 惯例）
+	assert.ok(d.includes("@@ -1,3 +1 @@")); // newCount=1 omits the count (git convention)
 });
 
-test("空 ops 返回空串", () => {
+test("empty ops returns empty string", () => {
 	assert.equal(buildDiff("f", ["a"], []), "");
 });

package/src/core/diff.ts

@@ -1,8 +1,10 @@
 /**
- * 基于 ops 的 unified diff 预览。
+ * Ops-based unified diff preview.
  *
- * 每个 SpanOp 生成一个 hunk，`@@` 行号基于原始文件（多 op 时各自的原始位置），
- * 内容准确。这是 Phase 1 的近似实现；如需精确的多 op 行号可后续换 LCS。
+ * Each SpanOp produces one hunk; the `@@` line numbers are based on the
+ * original file (each op's own original position), so the content is accurate.
+ * This is a Phase 1 approximation; if precise multi-op line numbers are needed,
+ * LCS can replace it later.
  *
  * @module pi-hashline-edit/core
  */
@@ -14,21 +16,21 @@ interface SpanOpLike {
 }
 
 /**
- * 生成 unified diff。
+ * Build a unified diff.
  *
- * @param path     文件路径（用于 diff 头）
- * @param oldLines 应用前的原始行数组
- * @param ops      已应用的行级操作
+ * @param path     file path (for the diff header)
+ * @param oldLines original line array before applying
+ * @param ops      line-level operations applied
  */
 export function buildDiff(path: string, oldLines: readonly string[], ops: readonly SpanOpLike[]): string {
 	if (ops.length === 0) return "";
 	const out: string[] = [`--- a/${path}`, `+++ b/${path}`];
 	for (const op of ops) {
 		const oldCount = op.hi - op.lo;
-		const oldStart = oldCount === 0 ? op.lo : op.lo + 1; // 零宽（插入点）用 lo，符合 unified-diff "after line N" 惯例
+		const oldStart = oldCount === 0 ? op.lo : op.lo + 1; // zero-width (insertion point) uses lo, following the unified-diff "after line N" convention
 		const newCount = op.newLines.length;
 		const newStart = op.lo + 1;
-		// 单行 hunk 省略计数，符合 unified-diff 惯例
+		// single-line hunks omit the count, following the unified-diff convention
 		const oldRange = oldCount === 1 ? `${oldStart}` : `${oldStart},${oldCount}`;
 		const newRange = newCount === 1 ? `${newStart}` : `${newStart},${newCount}`;
 		out.push(`@@ -${oldRange} +${newRange} @@`);

package/src/core/hash.test.ts

@@ -4,7 +4,7 @@ import { computeLineHash, hashFileLines } from "./hash.ts";
 
 const ALLOWED = new Set("0123456789ABCDEFGHJKMNPQRSTVWXYZ");
 
-test("computeLineHash 稳定且为 base32", () => {
+test("computeLineHash is stable and base32", () => {
 	const a = computeLineHash("p", "c", "n", 4);
 	const b = computeLineHash("p", "c", "n", 4);
 	assert.equal(a, b);
@@ -12,38 +12,38 @@ test("computeLineHash 稳定且为 base32", () => {
 	for (const ch of a) assert.ok(ALLOWED.has(ch), `bad char ${ch}`);
 });
 
-test("context-aware：相同行不同邻居 → 不同 hash", () => {
+test("context-aware: same line, different neighbors → different hash", () => {
 	const h1 = computeLineHash("a", "x", "b");
 	const h2 = computeLineHash("c", "x", "d");
 	assert.notEqual(h1, h2);
 });
 
-test("context-aware：相同三元组 → 相同 hash", () => {
+test("context-aware: same triple → same hash", () => {
 	assert.equal(computeLineHash("a", "x", "b"), computeLineHash("a", "x", "b"));
 });
 
-test("base32 字符集（去 I/L/O/U）批量", () => {
+test("base32 alphabet (without I/L/O/U) in bulk", () => {
 	for (let i = 0; i < 2000; i++) {
 		const h = computeLineHash("", `line ${i}`, "", 4);
 		for (const ch of h) assert.ok(ALLOWED.has(ch), `bad char ${ch} in ${h}`);
 	}
 });
 
-test("hashFileLines 长度等于行数", () => {
+test("hashFileLines length equals line count", () => {
 	assert.equal(hashFileLines(["a", "b", "c"]).length, 3);
 });
 
-test("hashFileLines 空文件", () => {
+test("hashFileLines empty file", () => {
 	assert.deepEqual(hashFileLines([]), []);
 });
 
-test("hashFileLines 文件内无碰撞（大量重复行）", () => {
+test("hashFileLines has no in-file collisions (many duplicate lines)", () => {
 	const lines = ["", "", "", "", "", "}", "}", "}", "return", "return", ",", ","];
 	const hashes = hashFileLines(lines);
 	assert.equal(new Set(hashes).size, hashes.length, "collision not resolved");
 });
 
-test("hashFileLines 长度参数生效", () => {
+test("hashFileLines respects the length parameter", () => {
 	assert.equal(hashFileLines(["a", "b"], 6)[0].length, 6);
 	assert.equal(hashFileLines(["a", "b"], 4)[0].length, 4);
 });

package/src/core/hash.ts

@@ -1,19 +1,22 @@
 /**
- * 行级 context-aware hash。
+ * Per-line context-aware hash.
  *
- * 每行的 hash 把「上一行 + 本行 + 下一行」拼起来一起算，使内容相同的行
- * （空行、`}`、`return`）因邻居不同而 hash 不同，文件内碰撞实际接近 0。
- * 残余碰撞由 {@link hashFileLines} 自动扩展长度解决（per-file 无碰撞保证）。
+ * Each line's hash is computed by concatenating "previous line + this line +
+ * next line", so identical content lines (blank lines, `}`, `return`) get
+ * different hashes due to different neighbors, making in-file collisions
+ * effectively zero. Residual collisions are resolved by {@link hashFileLines}
+ * via automatic length extension (per-file zero-collision guarantee).
  *
  * @module pi-hashline-edit/core
  */
 
-/** Crockford base32 字符表（去 I/L/O/U，避免易混字符）。正好 32 个。 */
+/** Crockford base32 alphabet (without I/L/O/U to avoid ambiguous characters). Exactly 32 characters. */
 const BASE32 = "0123456789ABCDEFGHJKMNPQRSTVWXYZ";
 
 /**
- * FNV-1a 32-bit。稳定（同一输入永远同一输出）、分布均匀、非加密用途。
- * 用 `Math.imul` 保证 32-bit 整数乘法在 JS 下正确。
+ * FNV-1a 32-bit. Stable (same input always yields the same output), evenly
+ * distributed, non-cryptographic. Uses `Math.imul` for correct 32-bit integer
+ * multiplication under JS.
  */
 function fnv1a32(str: string): number {
 	let h = 0x811c9dc5;
@@ -24,7 +27,7 @@ function fnv1a32(str: string): number {
 	return h >>> 0;
 }
 
-/** 把 32-bit 整数编码为指定长度的 base32 字符串。 */
+/** Encode a 32-bit integer into a base32 string of the given length. */
 function toBase32(n: number, len: number): string {
 	let s = "";
 	for (let i = 0; i < len; i++) {
@@ -35,33 +38,33 @@ function toBase32(n: number, len: number): string {
 }
 
 /**
- * 计算单行的 context-aware hash。
+ * Compute the context-aware hash of a single line.
  *
- * @param prev 上一行内容（首行传 `""`）
- * @param cur  本行内容
- * @param next 下一行内容（末行传 `""`）
- * @param len  hash 长度（默认 4，20 bits ≈ 100 万值）
+ * @param prev previous line content (`""` for the first line)
+ * @param cur  this line's content
+ * @param next next line content (`""` for the last line)
+ * @param len  hash length (default 4, 20 bits ≈ 1M values)
  */
 export function computeLineHash(prev: string, cur: string, next: string, len = 4): string {
 	const h = fnv1a32(`${prev}\n${cur}\n${next}`);
 	return toBase32(h, len);
 }
 
-/** 给每行算 raw hash（不处理碰撞）。 */
+/** Compute raw per-line hashes (no collision handling). */
 function rawHashes(lines: readonly string[], len: number): string[] {
 	return lines.map((line, i) =>
 		computeLineHash(lines[i - 1] ?? "", line, lines[i + 1] ?? "", len),
 	);
 }
 
-/** 找出出现 >1 次的 hash 值。 */
+/** Find hash values that appear more than once. */
 function duplicatedHashes(hashes: readonly string[]): Set<string> {
 	const counts = new Map<string, number>();
 	for (const h of hashes) counts.set(h, (counts.get(h) ?? 0) + 1);
 	return new Set([...counts.entries()].filter(([, c]) => c > 1).map(([h]) => h));
 }
 
-/** 兜底：用序号后缀强制唯一（context-aware 下理论不可达）。 */
+/** Fallback: force uniqueness with an index suffix (theoretically unreachable under context-aware hashing). */
 function forceUnique(hashes: string[]): string[] {
 	const seen = new Map<string, number>();
 	return hashes.map((h) => {
@@ -72,11 +75,13 @@ function forceUnique(hashes: string[]): string[] {
 }
 
 /**
- * 给整个文件的每行算 hash，并解决文件内碰撞：
- * 碰撞的行自动用更长 len 重算，直到文件内唯一（per-file 无碰撞保证）。
+ * Compute per-line hashes for the whole file and resolve in-file collisions:
+ * colliding lines are recomputed with a longer len until unique within the file
+ * (per-file zero-collision guarantee).
  *
- * 设计依据：context-aware 已使碰撞概率接近 0；此处扩展是防御性兜底，
- * 保证 apply 永远不会因 hash 歧义而误定位。
+ * Design rationale: context-aware hashing already drives the collision
+ * probability near zero; this extension is a defensive fallback guaranteeing
+ * apply never mislocates due to hash ambiguity.
  */
 export function hashFileLines(lines: readonly string[], len = 4): string[] {
 	if (lines.length === 0) return [];

package/src/core/index.ts

@@ -1,8 +1,8 @@
 /**
- * pi-hashline-edit 核心库公共 API。
+ * Public API of the pi-hashline-edit core library.
  *
- * 纯 hashline 引擎，零 pi 依赖，可独立 `node --test`。
- * pi 接入层在 `../pi/` 下。
+ * The pure hashline engine, with zero pi dependencies, runnable standalone via
+ * `node --test`. The pi integration layer lives under `../pi/`.
  *
  * @module pi-hashline-edit/core
  */

package/src/core/parse.test.ts

@@ -2,7 +2,7 @@ import { test } from "node:test";
 import assert from "node:assert/strict";
 import { parsePatch } from "./parse.ts";
 
-test("解析 replace 单行", () => {
+test("parse replace single line", () => {
 	const r = parsePatch("file: f.ts\n\nreplace 4#ABCD:\n+new line\n");
 	assert.equal(r.ok, true);
 	if (r.ok) {
@@ -12,7 +12,7 @@ test("解析 replace 单行", () => {
 	}
 });
 
-test("解析 replace range", () => {
+test("parse replace range", () => {
 	const r = parsePatch("file: f.ts\nreplace 3#AAA..5#BBB:\n+a\n+b\n");
 	assert.equal(r.ok, true);
 	if (r.ok) {
@@ -25,19 +25,19 @@ test("解析 replace range", () => {
 	}
 });
 
-test("解析 delete（无 body）", () => {
+test("parse delete (no body)", () => {
 	const r = parsePatch("file: f.ts\ndelete 2#XYZ\n");
 	assert.equal(r.ok, true);
 	if (r.ok) assert.equal(r.patch.edits[0].op, "delete");
 });
 
-test("解析 insert_after / insert_before", () => {
+test("parse insert_after / insert_before", () => {
 	const r = parsePatch("file: f.ts\ninsert_after 3#ABC:\n+x\n\ninsert_before 5#DEF:\n+y\n");
 	assert.equal(r.ok, true);
 	if (r.ok) assert.equal(r.patch.edits.length, 2);
 });
 
-test("解析 append / prepend", () => {
+test("parse append / prepend", () => {
 	const r = parsePatch("file: f.ts\nappend:\n+z\n\nprepend:\n+w\n");
 	assert.equal(r.ok, true);
 	if (r.ok) {
@@ -46,13 +46,13 @@ test("解析 append / prepend", () => {
 	}
 });
 
-test("多操作混合", () => {
+test("multiple mixed operations", () => {
 	const r = parsePatch("file: f.ts\n\nreplace 1#A:\n+x\n\ndelete 3#C\n\ninsert_after 5#E:\n+y\n");
 	assert.equal(r.ok, true);
 	if (r.ok) assert.equal(r.patch.edits.length, 3);
 });
 
-test("body 保留字面（含 + 前缀、markdown）", () => {
+test("body kept literally (with + prefix, markdown)", () => {
 	const r = parsePatch("file: f.ts\nreplace 1#A:\n++i\n+- item\n+\n");
 	assert.equal(r.ok, true);
 	if (r.ok) {
@@ -61,56 +61,56 @@ test("body 保留字面（含 + 前缀、markdown）", () => {
 	}
 });
 
-test("冒号可选", () => {
+test("colon is optional", () => {
 	const r = parsePatch("file: f.ts\nreplace 1#A\n+x\n");
 	assert.equal(r.ok, true);
 });
 
-test("CRLF 归一", () => {
+test("CRLF normalization", () => {
 	const r = parsePatch("file: f.ts\r\nreplace 1#A:\r\n+x\r\n");
 	assert.equal(r.ok, true);
 	if (r.ok) {
 		const e = r.patch.edits[0];
-		if (e.op === "replace") assert.deepEqual(e.body, ["x"]); // 无 \r
+		if (e.op === "replace") assert.deepEqual(e.body, ["x"]); // no \r
 	}
 });
 
-// —— 错误路径 ——
+// --- error paths ---
 
-test("缺 file 头报错", () => {
+test("missing file header errors", () => {
 	const r = parsePatch("replace 1#A:\n+x\n");
 	assert.equal(r.ok, false);
 });
 
-test("空输入报错", () => {
+test("empty input errors", () => {
 	assert.equal(parsePatch("").ok, false);
 	assert.equal(parsePatch("\n\n").ok, false);
 });
 
-test("空 body 报错", () => {
+test("empty body errors", () => {
 	const r = parsePatch("file: f.ts\nreplace 1#A:\n");
 	assert.equal(r.ok, false);
 	if (!r.ok) assert.equal(r.error.kind, "parse");
 });
 
-test("未知 verb 报错（拒绝 SWAP/DEL）", () => {
+test("unknown verb errors (rejects SWAP/DEL)", () => {
 	const r = parsePatch("file: f.ts\nSWAP 1#A:\n+x\n");
 	assert.equal(r.ok, false);
 	if (!r.ok) assert.equal(r.error.kind, "parse");
 });
 
-test("stray body 报错", () => {
+test("stray body errors", () => {
 	const r = parsePatch("file: f.ts\n+x\n");
 	assert.equal(r.ok, false);
 });
 
-test("delete 带 body 报错", () => {
+test("delete with body errors", () => {
 	const r = parsePatch("file: f.ts\ndelete 2#X\n+leak\n");
-	// delete 后紧跟 + 行 → 下一轮判为 stray body
+	// a + line right after delete → the next round treats it as a stray body
 	assert.equal(r.ok, false);
 });
 
-test("错误含输入行号", () => {
+test("error includes the input line number", () => {
 	const r = parsePatch("file: f.ts\n\nreplace 1#A:\n+x\n\nSWAP 2#B:\n+y\n");
 	assert.equal(r.ok, false);
 	if (!r.ok) assert.ok(r.error.line && r.error.line >= 5);