@d3ara1n/pi-hashline-edit 0.1.0 → 0.1.2

package/src/core/hash.ts

@@ -1,19 +1,37 @@
 /**
- * 行级 context-aware hash。
+ * Per-line content hash.
  *
- * 每行的 hash 把「上一行 + 本行 + 下一行」拼起来一起算，使内容相同的行
- * （空行、`}`、`return`）因邻居不同而 hash 不同，文件内碰撞实际接近 0。
- * 残余碰撞由 {@link hashFileLines} 自动扩展长度解决（per-file 无碰撞保证）。
+ * The hash mixes the 1-based line number into the line content, so every line
+ * gets a unique hash by construction — line numbers are unique, therefore no
+ * in-file collision is possible, and no length extension / fallback is ever
+ * needed.
+ *
+ * Why line + content (not content alone, not content + neighbors):
+ *
+ * - The line number is the address; the hash is a checksum that the line at
+ *   that address is still what was read. Mixing the number in makes the hash a
+ *   pure fingerprint of (position, content): it changes only when the line's
+ *   own content changes, never when a neighbor changes. (A neighbor-aware hash
+ *   would change an unchanged line's hash when an adjacent line is edited — a
+ *   spurious dependency with no benefit under this design's position-fixed
+ *   apply.)
+ * - Content alone would leave identical lines (blank lines, `}`) sharing a
+ *   hash; mixing the line number disambiguates them for free.
+ *
+ * Drift (file changed since read) is caught up-front by the global stale check
+ * (`text !== snapshot.text`). This hash's job is to verify the model actually
+ * read the line — it cannot forge a `(line, content)` hash without reading.
  *
  * @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 +42,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,60 +53,20 @@ function toBase32(n: number, len: number): string {
 }
 
 /**
- * 计算单行的 context-aware hash。
+ * Compute the hash of a single line from its 1-based line number and content.
  *
- * @param prev 上一行内容（首行传 `""`）
- * @param cur  本行内容
- * @param next 下一行内容（末行传 `""`）
- * @param len  hash 长度（默认 4，20 bits ≈ 100 万值）
+ * @param line    1-based line number
+ * @param content the line's content (no line terminator)
+ * @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（不处理碰撞）。 */
-function rawHashes(lines: readonly string[], len: number): string[] {
-	return lines.map((line, i) =>
-		computeLineHash(lines[i - 1] ?? "", line, lines[i + 1] ?? "", len),
-	);
-}
-
-/** 找出出现 >1 次的 hash 值。 */
-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 下理论不可达）。 */
-function forceUnique(hashes: string[]): string[] {
-	const seen = new Map<string, number>();
-	return hashes.map((h) => {
-		const c = seen.get(h) ?? 0;
-		seen.set(h, c + 1);
-		return c === 0 ? h : `${h}${c}`;
-	});
+export function computeLineHash(line: number, content: string, len = 4): string {
+	return toBase32(fnv1a32(`${line}\n${content}`), len);
 }
 
 /**
- * 给整个文件的每行算 hash，并解决文件内碰撞：
- * 碰撞的行自动用更长 len 重算，直到文件内唯一（per-file 无碰撞保证）。
- *
- * 设计依据：context-aware 已使碰撞概率接近 0；此处扩展是防御性兜底，
- * 保证 apply 永远不会因 hash 歧义而误定位。
+ * Compute per-line hashes for a file. Unique by construction — the 1-based line
+ * number is part of each hash, so two identical content lines always differ.
  */
 export function hashFileLines(lines: readonly string[], len = 4): string[] {
-	if (lines.length === 0) return [];
-	let hashes = rawHashes(lines, len);
-	for (let curLen = len; curLen <= len + 4; curLen++) {
-		const dups = duplicatedHashes(hashes);
-		if (dups.size === 0) return hashes;
-		hashes = hashes.map((h, i) =>
-			dups.has(h)
-				? computeLineHash(lines[i - 1] ?? "", lines[i] ?? "", lines[i + 1] ?? "", curLen + 1)
-				: h,
-		);
-	}
-	return forceUnique(hashes);
+	return lines.map((content, i) => computeLineHash(i + 1, content, len));
 }

package/src/core/index.ts

@@ -1,17 +1,13 @@
 /**
- * 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
  */
 
 export * from "./types.ts";
 export { computeLineHash, hashFileLines } from "./hash.ts";
-export { splitLines, joinLines, createSnapshot, verifyAnchor } from "./snapshot.ts";
-export type { AnchorVerifyResult } from "./snapshot.ts";
-export { parsePatch } from "./parse.ts";
-export type { ParseResult } from "./parse.ts";
+export { splitLines, joinLines, detectLineEnding } from "./lines.ts";
 export { applyEdits } from "./apply.ts";
-export { buildDiff } from "./diff.ts";

package/src/core/lines.test.ts

@@ -0,0 +1,30 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { splitLines, joinLines, detectLineEnding } from "./lines.ts";
+
+test("splitLines edge cases", () => {
+	assert.deepEqual(splitLines(""), []);
+	assert.deepEqual(splitLines("a"), ["a"]);
+	assert.deepEqual(splitLines("a\nb"), ["a", "b"]);
+	assert.deepEqual(splitLines("a\nb\n"), ["a", "b"]);
+	assert.deepEqual(splitLines("a\n\n"), ["a", ""]);
+	assert.deepEqual(splitLines("\n"), [""]);
+});
+
+test("splitLines strips CRLF \\r", () => {
+	assert.deepEqual(splitLines("a\r\nb\r\n"), ["a", "b"]);
+	assert.deepEqual(splitLines("a\r\nb"), ["a", "b"]);
+});
+
+test("joinLines restores line endings", () => {
+	assert.equal(joinLines(["a", "b"]), "a\nb\n");
+	assert.equal(joinLines([]), "");
+	assert.equal(joinLines(["a", "b"], "crlf"), "a\r\nb\r\n");
+	assert.equal(joinLines(["a", "b"], "lf"), "a\nb\n");
+});
+
+test("detectLineEnding", () => {
+	assert.equal(detectLineEnding("a\nb\n"), "lf");
+	assert.equal(detectLineEnding("a\r\nb\r\n"), "crlf");
+	assert.equal(detectLineEnding("a\nb\r\nc\n"), "crlf");
+});

package/src/core/lines.ts

@@ -0,0 +1,42 @@
+/**
+ * Line text helpers: split/join with CRLF normalization and line-ending
+ * detection.
+ *
+ * CRLF: splitLines strips the trailing `\r` from each line (hashes are based on
+ * clean lines, matching the `\r`-free content the model copies from the
+ * display); detectLineEnding records the original ending so joinLines can
+ * restore it — guaranteeing a CRLF file keeps its endings after edit.
+ *
+ * @module pi-hashline-edit/core
+ */
+
+import type { LineEnding } from "./types.ts";
+
+/**
+ * Split text into lines, stripping the trailing `\r` of each line (CRLF
+ * normalization, so hashes are based on clean lines).
+ *
+ * Convention: a trailing newline is treated as the terminator of the last line,
+ * not as producing an extra empty trailing line.
+ * - `"a\nb\n"` → `["a", "b"]`
+ * - `"a\r\nb\r\n"` → `["a", "b"]` (`\r` stripped)
+ * - `"a\n\n"` → `["a", ""]`
+ * - `""` → `[]`
+ */
+export function splitLines(text: string): string[] {
+	if (text === "") return [];
+	const normalized = text.endsWith("\n") ? text.slice(0, -1) : text;
+	return normalized.split("\n").map((l) => (l.endsWith("\r") ? l.slice(0, -1) : l));
+}
+
+/** Detect the dominant line ending of the text (any `\r\n` counts as CRLF). */
+export function detectLineEnding(text: string): LineEnding {
+	return text.includes("\r\n") ? "crlf" : "lf";
+}
+
+/** Join a line array back into text, restoring the given line ending (default LF). Non-empty files end with a newline. */
+export function joinLines(lines: readonly string[], ending: LineEnding = "lf"): string {
+	if (lines.length === 0) return "";
+	const sep = ending === "crlf" ? "\r\n" : "\n";
+	return lines.join(sep) + sep;
+}

package/src/core/types.ts

@@ -1,18 +1,19 @@
 /**
- * Hashline 核心类型定义。
+ * Hashline core type definitions.
  *
  * @module pi-hashline-edit/core
  */
 
-/** 行锚：行号（1-based）+ 内容 hash 双重引用。 */
+/** Line anchor: dual reference of line number (1-based) + content hash. */
 export interface Anchor {
 	readonly line: number;
 	readonly hash: string;
 }
 
 /**
- * 编辑操作。所有带行号的操作都通过 {@link Anchor} 引用——
- * 行号给人读，hash 给机器校验，二者必须同时匹配快照。
+ * Edit operation. Every line-numbered op references a line via {@link Anchor} —
+ * the line number is the address, the hash a checksum that the line at that
+ * address is still what was read; both must match at apply time.
  */
 export type Edit =
 	| { readonly op: "replace"; readonly start: Anchor; readonly end?: Anchor; readonly body: string[] }
@@ -24,47 +25,28 @@ export type Edit =
 
 export type LineEnding = "lf" | "crlf";
 
-/** 文件快照：read 时记录的原文 + 每行 context-aware hash。 */
-export interface FileSnapshot {
-	readonly path: string;
-	/** `lineHashes[i]` = 第 (i+1) 行的 hash，长度恒等于文件行数。 */
-	readonly lineHashes: readonly string[];
-	readonly text: string;
-	/** 生成 lineHashes 时用的 hash 长度；apply 生成新快照时须沿用，避免长度不一致导致下次校验失败。 */
-	readonly hashLen: number;
-	/** 原文件行尾（lf/crlf）；apply 据此恢复，保证 CRLF 文件 edit 后行尾不变。 */
-	readonly lineEnding: LineEnding;
-}
-
-/** 解析出的单个文件 patch。 */
-export interface ParsedPatch {
-	readonly path: string;
-	readonly edits: Edit[];
-}
-
-/** 错误种类。 */
+/** Error kinds. */
 export type PatchErrorKind =
-	| "parse" // 输入格式错误
-	| "stale" // 文件已变（当前 text !== snapshot.text）
-	| "anchor" // 锚 hash 不匹配快照（模型记错）或行号越界
-	| "collision" // hash 在文件中多处出现，无法唯一定位
-	| "range" // 操作范围非法（重叠、逆序、跨空等）
-	| "noop"; // 编辑未产生变化（body 与目标行字节相同）
+	| "anchor" // anchor hash does not match the current line content (line changed, or model misremembered) or line out of range
+	| "range" // illegal operation range (overlap, reverse order, etc.)
+	| "noop"; // edit produced no change (body byte-identical to the target)
 
 export interface PatchError {
 	readonly kind: PatchErrorKind;
 	readonly message: string;
-	/** 输入 patch 中的行号（1-based），用于错误定位。 */
-	readonly line?: number;
 }
 
-/** 应用结果。 */
+/**
+ * Apply result. On success, `touchedLines` lists the 0-based line indices in
+ * the NEW file that this edit produced (inserted or replaced) — callers use it
+ * to surface fresh `LINE#HASH` anchors so the model can chain edits without a
+ * re-read.
+ */
 export type ApplyResult =
 	| {
 			readonly ok: true;
 			readonly text: string;
-			readonly newSnapshot: FileSnapshot;
 			readonly changed: boolean;
-			readonly diff: string;
+			readonly touchedLines: readonly number[];
 	  }
 	| { readonly ok: false; readonly error: PatchError };

package/src/index.ts

@@ -1,29 +1,27 @@
 /**
- * pi-hashline-edit 扩展入口。
+ * pi-hashline-edit extension entry.
  *
- * override 内置 read/edit：read 输出「行号#hash│内容」并记录快照，
- * edit 只接受 hashline patch（LINE#HASH 锚），旧 oldText/newText 明确拒绝
- * （不静默降级）。renderer 自动继承内置渲染。
+ * Overrides the built-in read/edit: read outputs "lineNo#hash│content";
+ * edit accepts structured hashline ops (edits[] with LINE#HASH anchors), and
+ * legacy oldText/newText is rejected explicitly (no silent degradation). Each
+ * tool carries its own renderer.
  *
  * @module pi-hashline-edit
  */
 
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { loadConfig } from "./pi/config.ts";
-import { clearSnapshots, getState } from "./pi/state.ts";
+import { getState } from "./pi/state.ts";
 import { makeEditOverride } from "./pi/edit-tool.ts";
 import { makeReadOverride } from "./pi/read-tool.ts";
 
 export default function (pi: ExtensionAPI) {
 	const cwd = process.cwd();
 
-	// session 启动/重载时刷新配置与快照
+	// refresh config on session start / reload
 	pi.on("session_start", async () => {
-		const config = loadConfig(cwd);
 		const state = getState();
-		state.config = config;
-		state.hashLen = config.hashLen;
-		clearSnapshots();
+		state.config = loadConfig(cwd);
 	});
 
 	pi.registerTool(makeReadOverride(cwd));

package/src/pi/config.ts

@@ -1,6 +1,7 @@
 /**
- * 配置加载：项目 `.pi/settings.json` 替换全局，per-field `??` DEFAULT 兜底。
- * 配置字段 `hashlineEdit`（去 `pi-` 前缀转 camelCase）。
+ * Config loading: project `.pi/settings.json` replaces global, per-field `??`
+ * falls back to DEFAULT. Config field `hashlineEdit` (drop the `pi-` prefix,
+ * camelCase).
  *
  * @module pi-hashline-edit/pi
  */
@@ -10,9 +11,9 @@ import * as os from "node:os";
 import * as path from "node:path";
 
 export interface HashlineEditConfig {
-	/** 是否启用 hashline（false 时透传内置 read/edit）。 */
+	/** Whether hashline is enabled (when false, delegate to the built-in read/edit). */
 	enabled: boolean;
-	/** 行 hash 长度（默认 4）。 */
+	/** Line hash length (default 4). */
 	hashLen: number;
 }
 
@@ -24,7 +25,7 @@ function getAgentDir(): string {
 	return path.join(os.homedir(), ".pi", "agent");
 }
 
-/** 直接 JSON.parse，不剥注释（标准 JSON 禁止注释，出错降级默认）。 */
+/** Parse JSON directly without stripping comments (standard JSON forbids comments; on error fall back to default). */
 function readSettings(filePath: string): Record<string, unknown> {
 	try {
 		if (!fs.existsSync(filePath)) return {};
@@ -35,8 +36,8 @@ function readSettings(filePath: string): Record<string, unknown> {
 }
 
 /**
- * 加载配置。项目 `cwd/.pi/settings.json` 的 `hashlineEdit` 整块替换全局，
- * 缺失字段由 DEFAULT_CONFIG 兜底。
+ * Load config. The `hashlineEdit` in project `cwd/.pi/settings.json` replaces
+ * the global one wholesale; missing fields fall back to DEFAULT_CONFIG.
  */
 export function loadConfig(cwd?: string): HashlineEditConfig {
 	const globalSettings = readSettings(path.join(getAgentDir(), "settings.json"));