@d3ara1n/pi-hashline-edit 0.1.0

package/src/core/parse.test.ts

@@ -0,0 +1,117 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { parsePatch } from "./parse.ts";
+
+test("解析 replace 单行", () => {
+	const r = parsePatch("file: f.ts\n\nreplace 4#ABCD:\n+new line\n");
+	assert.equal(r.ok, true);
+	if (r.ok) {
+		assert.equal(r.patch.path, "f.ts");
+		assert.equal(r.patch.edits.length, 1);
+		assert.equal(r.patch.edits[0].op, "replace");
+	}
+});
+
+test("解析 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) {
+		const e = r.patch.edits[0];
+		if (e.op === "replace") {
+			assert.equal(e.start.line, 3);
+			assert.equal(e.end?.line, 5);
+			assert.deepEqual(e.body, ["a", "b"]);
+		}
+	}
+});
+
+test("解析 delete（无 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", () => {
+	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", () => {
+	const r = parsePatch("file: f.ts\nappend:\n+z\n\nprepend:\n+w\n");
+	assert.equal(r.ok, true);
+	if (r.ok) {
+		assert.equal(r.patch.edits[0].op, "append");
+		assert.equal(r.patch.edits[1].op, "prepend");
+	}
+});
+
+test("多操作混合", () => {
+	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）", () => {
+	const r = parsePatch("file: f.ts\nreplace 1#A:\n++i\n+- item\n+\n");
+	assert.equal(r.ok, true);
+	if (r.ok) {
+		const e = r.patch.edits[0];
+		if (e.op === "replace") assert.deepEqual(e.body, ["+i", "- item", ""]);
+	}
+});
+
+test("冒号可选", () => {
+	const r = parsePatch("file: f.ts\nreplace 1#A\n+x\n");
+	assert.equal(r.ok, true);
+});
+
+test("CRLF 归一", () => {
+	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
+	}
+});
+
+// —— 错误路径 ——
+
+test("缺 file 头报错", () => {
+	const r = parsePatch("replace 1#A:\n+x\n");
+	assert.equal(r.ok, false);
+});
+
+test("空输入报错", () => {
+	assert.equal(parsePatch("").ok, false);
+	assert.equal(parsePatch("\n\n").ok, false);
+});
+
+test("空 body 报错", () => {
+	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）", () => {
+	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 报错", () => {
+	const r = parsePatch("file: f.ts\n+x\n");
+	assert.equal(r.ok, false);
+});
+
+test("delete 带 body 报错", () => {
+	const r = parsePatch("file: f.ts\ndelete 2#X\n+leak\n");
+	// delete 后紧跟 + 行 → 下一轮判为 stray body
+	assert.equal(r.ok, false);
+});
+
+test("错误含输入行号", () => {
+	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);
+});

package/src/core/parse.ts

@@ -0,0 +1,165 @@
+/**
+ * 严格解析器：patch 字符串 → {@link ParsedPatch}。
+ *
+ * 核心零猜测：只接受规范格式（正确 verb + 正确锚 + `+` body 行），
+ * 任何变体（裸行、旧 `oldText`/`newText`、`SWAP`/`DEL` 等）一律拒绝，
+ * 交给 `transforms/normalize-legacy` 中间件归一化后再进入解析。
+ *
+ * 格式：
+ *
+ * ```
+ * file: <path>
+ *
+ * replace <line>#<hash>[..<line>#<hash>]:
+ * +<text>
+ *
+ * delete <line>#<hash>[..<line>#<hash>]
+ *
+ * insert_after <line>#<hash>:
+ * +<text>
+ *
+ * append:
+ * +<text>
+ * ```
+ *
+ * @module pi-hashline-edit/core
+ */
+
+import type { Anchor, Edit, ParsedPatch, PatchError } from "./types.ts";
+
+export type ParseResult =
+	| { readonly ok: true; readonly patch: ParsedPatch }
+	| { readonly ok: false; readonly error: PatchError };
+
+function parseError(message: string, line?: number): PatchError {
+	return { kind: "parse", message, line };
+}
+
+const ANCHOR_RE = /^(\d+)#([0-9A-Za-z]+)$/;
+
+function parseAnchorStr(s: string): Anchor | null {
+	const m = ANCHOR_RE.exec(s);
+	return m ? { line: Number(m[1]), hash: m[2] } : null;
+}
+
+function parseRangeStr(s: string): { start: Anchor; end?: Anchor } | null {
+	const idx = s.indexOf("..");
+	if (idx === -1) {
+		const a = parseAnchorStr(s);
+		return a ? { start: a } : null;
+	}
+	const a = parseAnchorStr(s.slice(0, idx));
+	const b = parseAnchorStr(s.slice(idx + 2));
+	if (!a || !b) return null;
+	return { start: a, end: b };
+}
+
+type ParsedHeader =
+	| { readonly error: string }
+	| {
+			readonly verb: string;
+			readonly hasBody: boolean;
+			readonly build: (body: string[]) => Edit;
+	  };
+
+/** 解析单个操作头（已 trim）。末尾冒号可选（有 body 的 verb）。 */
+function parseOpHeader(s: string): ParsedHeader {
+	let core = s;
+	if (core.endsWith(":")) core = core.slice(0, -1).trimEnd();
+
+	const sp = core.indexOf(" ");
+	const verb = sp === -1 ? core : core.slice(0, sp);
+	const rest = sp === -1 ? "" : core.slice(sp + 1).trim();
+
+	switch (verb) {
+		case "replace": {
+			const r = parseRangeStr(rest);
+			if (!r) return { error: `replace needs "<line>#<hash>[..<line>#<hash>]", got: "${s}"` };
+			return { verb, hasBody: true, build: (body) => ({ op: "replace", start: r.start, end: r.end, body }) };
+		}
+		case "delete": {
+			const r = parseRangeStr(rest);
+			if (!r) return { error: `delete needs "<line>#<hash>[..<line>#<hash>]", got: "${s}"` };
+			return { verb, hasBody: false, build: () => ({ op: "delete", start: r.start, end: r.end }) };
+		}
+		case "insert_after":
+		case "insert_before": {
+			const a = parseAnchorStr(rest);
+			if (!a) return { error: `${verb} needs "<line>#<hash>", got: "${s}"` };
+			return { verb, hasBody: true, build: (body) => ({ op: verb, anchor: a, body }) };
+		}
+		case "append":
+		case "prepend": {
+			if (rest !== "") return { error: `${verb} takes no anchor, got: "${s}"` };
+			return { verb, hasBody: true, build: (body) => ({ op: verb, body }) };
+		}
+		default:
+			return {
+				error: `unknown verb "${verb}". Use replace / delete / insert_after / insert_before / append / prepend`,
+			};
+	}
+}
+
+/**
+ * 严格解析 patch。
+ *
+ * @param input patch 字符串（CRLF 自动归一为 LF）
+ * @returns 解析结果；非法格式返回 `ok: false` + PatchError（含输入行号）
+ */
+export function parsePatch(input: string): ParseResult {
+	const normalized = input.replace(/\r\n/g, "\n");
+	const lines = normalized.split("\n");
+	const n = lines.length;
+	let i = 0;
+
+	while (i < n && lines[i].trim() === "") i++;
+	if (i >= n) return { ok: false, error: parseError("empty input", 1) };
+
+	const fileMatch = /^file:\s*(.+?)\s*$/i.exec(lines[i]);
+	if (!fileMatch) {
+		return {
+			ok: false,
+			error: parseError(`expected "file: <path>" on first non-blank line, got: "${lines[i]}"`, i + 1),
+		};
+	}
+	const path = fileMatch[1];
+	i++;
+
+	const edits: Edit[] = [];
+	while (i < n) {
+		while (i < n && lines[i].trim() === "") i++;
+		if (i >= n) break;
+
+		const headerLineNo = i + 1;
+		const raw = lines[i];
+		const trimmed = raw.trim();
+
+		if (trimmed.startsWith("+")) {
+			return { ok: false, error: parseError(`stray body row has no preceding header: "${raw}"`, headerLineNo) };
+		}
+
+		const parsed = parseOpHeader(trimmed);
+		if ("error" in parsed) {
+			return { ok: false, error: parseError(parsed.error, headerLineNo) };
+		}
+		i++;
+
+		let body: string[] = [];
+		if (parsed.hasBody) {
+			while (i < n && lines[i].startsWith("+")) {
+				body.push(lines[i].slice(1));
+				i++;
+			}
+			if (body.length === 0) {
+				return {
+					ok: false,
+					error: parseError(`"${parsed.verb}" needs at least one "+TEXT" body row`, headerLineNo),
+				};
+			}
+		}
+
+		edits.push(parsed.build(body));
+	}
+
+	return { ok: true, patch: { path, edits } };
+}

package/src/core/snapshot.test.ts

@@ -0,0 +1,60 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { splitLines, joinLines, createSnapshot, verifyAnchor } from "./snapshot.ts";
+
+test("splitLines 边界", () => {
+	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 去掉 CRLF 的 \\r", () => {
+	assert.deepEqual(splitLines("a\r\nb\r\n"), ["a", "b"]);
+	assert.deepEqual(splitLines("a\r\nb"), ["a", "b"]);
+});
+
+test("joinLines 行尾恢复", () => {
+	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("createSnapshot 记录 path/text/hashLen", () => {
+	const s = createSnapshot("f.ts", "a\nb\nc\n");
+	assert.equal(s.path, "f.ts");
+	assert.equal(s.text, "a\nb\nc\n");
+	assert.equal(s.lineHashes.length, 3);
+	assert.equal(s.hashLen, 4);
+});
+
+test("createSnapshot 自定义 hashLen", () => {
+	assert.equal(createSnapshot("f", "a\n", 6).hashLen, 6);
+});
+
+test("createSnapshot 记录 lineEnding", () => {
+	assert.equal(createSnapshot("f", "a\nb\n").lineEnding, "lf");
+	assert.equal(createSnapshot("f", "a\r\nb\r\n").lineEnding, "crlf");
+});
+
+test("verifyAnchor 匹配", () => {
+	const s = createSnapshot("f", "a\nb\n");
+	assert.deepEqual(verifyAnchor(s, { line: 2, hash: s.lineHashes[1] }), { ok: true, line: 2 });
+});
+
+test("verifyAnchor hash_not_found", () => {
+	const s = createSnapshot("f", "a\nb\n");
+	const r = verifyAnchor(s, { line: 1, hash: "ZZZZ" });
+	assert.equal(r.ok, false);
+	if (!r.ok) assert.equal(r.error, "hash_not_found");
+});
+
+test("verifyAnchor line_mismatch（漂移）", () => {
+	const s = createSnapshot("f", "a\nb\n");
+	const r = verifyAnchor(s, { line: 1, hash: s.lineHashes[1] });
+	assert.equal(r.ok, false);
+	if (!r.ok) assert.equal(r.error, "line_mismatch");
+});

package/src/core/snapshot.ts

@@ -0,0 +1,78 @@
+/**
+ * 文件快照与锚校验。
+ *
+ * 快照在 read 时记录原文 + 每行 hash；apply 时校验「当前文件 == 快照」
+ * （stale 检查）以及每个锚的 hash 与行号对得上（防模型记错）。
+ *
+ * CRLF：splitLines 归一化去掉每行尾的 \r（hash 基于干净行，与模型从显示中
+ * 复制的无 \r 内容一致），createSnapshot 记录原行尾，joinLines 按记录的
+ * 行尾恢复——保证 CRLF 文件 edit 后行尾不变。
+ *
+ * @module pi-hashline-edit/core
+ */
+
+import { hashFileLines } from "./hash.ts";
+import type { Anchor, FileSnapshot, LineEnding } from "./types.ts";
+
+/**
+ * 按行分割文本，去掉每行尾的 \r（CRLF 归一化，hash 基于干净行）。
+ *
+ * 约定：末尾换行视为最后一行的终止符，不产生多余空尾行。
+ * - `"a\nb\n"` → `["a", "b"]`
+ * - `"a\r\nb\r\n"` → `["a", "b"]`（\r 去掉）
+ * - `"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));
+}
+
+/** 检测文本的主导行尾（含 \r\n 即视为 CRLF）。 */
+export function detectLineEnding(text: string): LineEnding {
+	return text.includes("\r\n") ? "crlf" : "lf";
+}
+
+/** 把行数组 join 成文本，按指定行尾恢复（默认 LF）。非空文件末尾带换行。 */
+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;
+}
+
+/** 为文件创建快照：记录原文 + 行尾 + 每行 context-aware hash。 */
+export function createSnapshot(path: string, text: string, len = 4): FileSnapshot {
+	const lines = splitLines(text);
+	const lineHashes = hashFileLines(lines, len);
+	return { path, lineHashes, text, hashLen: len, lineEnding: detectLineEnding(text) };
+}
+
+/** 锚校验结果。 */
+export type AnchorVerifyResult =
+	| { readonly ok: true; readonly line: number }
+	| {
+			readonly ok: false;
+			readonly error: "hash_not_found" | "line_mismatch" | "collision";
+			/** hash 实际出现的行号（1-based）。 */
+			readonly found?: readonly number[];
+	  };
+
+/**
+ * 在快照中校验锚。
+ *
+ * - hash 唯一存在且行号匹配 → `ok`
+ * - hash 唯一存在但行号不符 → `line_mismatch`（`found` 给真实行号；漂移，可由 relocate 中间件处理）
+ * - hash 多处出现 → `collision`（`found` 给所有位置）
+ * - hash 不存在 → `hash_not_found`（文件已变，需重读）
+ */
+export function verifyAnchor(snapshot: FileSnapshot, anchor: Anchor): AnchorVerifyResult {
+	const found: number[] = [];
+	for (let i = 0; i < snapshot.lineHashes.length; i++) {
+		if (snapshot.lineHashes[i] === anchor.hash) found.push(i + 1);
+	}
+	if (found.length === 0) return { ok: false, error: "hash_not_found" };
+	if (found.length > 1) return { ok: false, error: "collision", found };
+	if (found[0] !== anchor.line) return { ok: false, error: "line_mismatch", found };
+	return { ok: true, line: anchor.line };
+}

package/src/core/types.ts

@@ -0,0 +1,70 @@
+/**
+ * Hashline 核心类型定义。
+ *
+ * @module pi-hashline-edit/core
+ */
+
+/** 行锚：行号（1-based）+ 内容 hash 双重引用。 */
+export interface Anchor {
+	readonly line: number;
+	readonly hash: string;
+}
+
+/**
+ * 编辑操作。所有带行号的操作都通过 {@link Anchor} 引用——
+ * 行号给人读，hash 给机器校验，二者必须同时匹配快照。
+ */
+export type Edit =
+	| { readonly op: "replace"; readonly start: Anchor; readonly end?: Anchor; readonly body: string[] }
+	| { readonly op: "delete"; readonly start: Anchor; readonly end?: Anchor }
+	| { readonly op: "insert_after"; readonly anchor: Anchor; readonly body: string[] }
+	| { readonly op: "insert_before"; readonly anchor: Anchor; readonly body: string[] }
+	| { readonly op: "append"; readonly body: string[] }
+	| { readonly op: "prepend"; readonly body: string[] };
+
+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[];
+}
+
+/** 错误种类。 */
+export type PatchErrorKind =
+	| "parse" // 输入格式错误
+	| "stale" // 文件已变（当前 text !== snapshot.text）
+	| "anchor" // 锚 hash 不匹配快照（模型记错）或行号越界
+	| "collision" // hash 在文件中多处出现，无法唯一定位
+	| "range" // 操作范围非法（重叠、逆序、跨空等）
+	| "noop"; // 编辑未产生变化（body 与目标行字节相同）
+
+export interface PatchError {
+	readonly kind: PatchErrorKind;
+	readonly message: string;
+	/** 输入 patch 中的行号（1-based），用于错误定位。 */
+	readonly line?: number;
+}
+
+/** 应用结果。 */
+export type ApplyResult =
+	| {
+			readonly ok: true;
+			readonly text: string;
+			readonly newSnapshot: FileSnapshot;
+			readonly changed: boolean;
+			readonly diff: string;
+	  }
+	| { readonly ok: false; readonly error: PatchError };

package/src/index.ts

@@ -0,0 +1,31 @@
+/**
+ * pi-hashline-edit 扩展入口。
+ *
+ * override 内置 read/edit：read 输出「行号#hash│内容」并记录快照，
+ * edit 只接受 hashline patch（LINE#HASH 锚），旧 oldText/newText 明确拒绝
+ * （不静默降级）。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 { makeEditOverride } from "./pi/edit-tool.ts";
+import { makeReadOverride } from "./pi/read-tool.ts";
+
+export default function (pi: ExtensionAPI) {
+	const cwd = process.cwd();
+
+	// session 启动/重载时刷新配置与快照
+	pi.on("session_start", async () => {
+		const config = loadConfig(cwd);
+		const state = getState();
+		state.config = config;
+		state.hashLen = config.hashLen;
+		clearSnapshots();
+	});
+
+	pi.registerTool(makeReadOverride(cwd));
+	pi.registerTool(makeEditOverride(cwd));
+}

package/src/pi/config.ts

@@ -0,0 +1,52 @@
+/**
+ * 配置加载：项目 `.pi/settings.json` 替换全局，per-field `??` DEFAULT 兜底。
+ * 配置字段 `hashlineEdit`（去 `pi-` 前缀转 camelCase）。
+ *
+ * @module pi-hashline-edit/pi
+ */
+
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+
+export interface HashlineEditConfig {
+	/** 是否启用 hashline（false 时透传内置 read/edit）。 */
+	enabled: boolean;
+	/** 行 hash 长度（默认 4）。 */
+	hashLen: number;
+}
+
+const DEFAULT_CONFIG: HashlineEditConfig = { enabled: true, hashLen: 4 };
+
+function getAgentDir(): string {
+	const envDir = process.env.PI_AGENT_DIR;
+	if (envDir) return envDir;
+	return path.join(os.homedir(), ".pi", "agent");
+}
+
+/** 直接 JSON.parse，不剥注释（标准 JSON 禁止注释，出错降级默认）。 */
+function readSettings(filePath: string): Record<string, unknown> {
+	try {
+		if (!fs.existsSync(filePath)) return {};
+		return JSON.parse(fs.readFileSync(filePath, "utf-8")) as Record<string, unknown>;
+	} catch {
+		return {};
+	}
+}
+
+/**
+ * 加载配置。项目 `cwd/.pi/settings.json` 的 `hashlineEdit` 整块替换全局，
+ * 缺失字段由 DEFAULT_CONFIG 兜底。
+ */
+export function loadConfig(cwd?: string): HashlineEditConfig {
+	const globalSettings = readSettings(path.join(getAgentDir(), "settings.json"));
+	const projectSettings = cwd ? readSettings(path.join(cwd, ".pi", "settings.json")) : {};
+	const raw = (projectSettings.hashlineEdit ?? globalSettings.hashlineEdit ?? {}) as Record<string, unknown>;
+	return {
+		enabled: typeof raw.enabled === "boolean" ? raw.enabled : DEFAULT_CONFIG.enabled,
+		hashLen:
+			typeof raw.hashLen === "number" && raw.hashLen >= 2 && raw.hashLen <= 8
+				? raw.hashLen
+				: DEFAULT_CONFIG.hashLen,
+	};
+}