nano-git 0.2.3 → 0.3.1

package/dist/workdir/directory-view.mjs

@@ -0,0 +1,197 @@
+import { VirtualNotDirectoryError } from "../core/errors.mjs";
+import { ensureNodeFromTreeEntry, joinChildPath, listDirectoryChildren } from "./session-internal.mjs";
+//#region src/workdir/directory-view.ts
+/**
+* Virtual Workdir 目录展开、观察与编译计划
+*
+* 从 session-internal.ts 拆分，聚焦以下职责：
+* - 目录子项观察（observeDirectoryChildren / observeListedDirectoryChild / observeNamedDirectoryChild）
+* - origin 按名查询视图（createNamedOriginChildLookup）
+* - 受影响子项编译计划（planAffectedDirectoryChildren）
+*/
+/**
+* 在不展开整个目录列表的前提下，按名称定向解析单个子节点。
+*
+* 优先读取 overlay 绑定；若 overlay 未覆盖，再按需从 origin 条目懒注册。
+*/
+function resolveNamedChild(state, dirNode, originLookup, name) {
+	if (dirNode.state.kind !== "directory") return {
+		found: false,
+		node: null
+	};
+	const overlayNodeId = dirNode.state.overlay.addedEntries.get(name);
+	if (overlayNodeId !== void 0) {
+		const overlayNode = state.getNode(overlayNodeId);
+		return overlayNode === null ? {
+			found: false,
+			node: null
+		} : {
+			found: true,
+			node: overlayNode
+		};
+	}
+	if (dirNode.state.overlay.deletedNames.has(name)) return {
+		found: false,
+		node: null
+	};
+	const originEntry = originLookup.get(name);
+	if (originEntry === void 0) return {
+		found: false,
+		node: null
+	};
+	const originNodeId = ensureNodeFromTreeEntry(state, originEntry);
+	const originNode = state.getNode(originNodeId);
+	return originNode === null ? {
+		found: false,
+		node: null
+	} : {
+		found: true,
+		node: originNode
+	};
+}
+/**
+* 基于已展开的目录子项读取当前节点与完整路径。
+*
+* 节点不存在时返回 `null`。
+*
+* @example
+* ```ts
+* const observed = observeListedDirectoryChild(state, "", child);
+* expect(observed?.path).toBe("a.txt");
+* ```
+*/
+function observeListedDirectoryChild(state, dirPath, child) {
+	const node = state.getNode(child.nodeId);
+	if (node === null) return null;
+	return {
+		name: child.name,
+		path: joinChildPath(dirPath, child.name),
+		child,
+		node
+	};
+}
+/**
+* 基于目录节点与子项名称定向读取当前节点与完整路径。
+*
+* 适用于已持有 origin lookup、但不想手工重复拼装 `{ name, path, node }`
+* 局部协议的场景。
+*
+* @example
+* ```ts
+* const observed = observeNamedDirectoryChild(state, dirNode, "", lookup, "a.txt");
+* expect(observed?.path).toBe("a.txt");
+* ```
+*/
+function observeNamedDirectoryChild(state, dirNode, dirPath, originLookup, name) {
+	if (dirNode.state.kind !== "directory") return null;
+	const resolved = resolveNamedChild(state, dirNode, originLookup, name);
+	if (!resolved.found) return null;
+	return {
+		name,
+		path: joinChildPath(dirPath, name),
+		node: resolved.node
+	};
+}
+/**
+* 观察目录当前子项，归纳直接受影响名字与更深层脏项数。
+*
+* 目录自身 overlay 的 add/delete 会直接计入 `affectedNames`；
+* 子目录是否脏、叶子节点是否脏由调用方回调决定。
+*
+* @example
+* ```ts
+* const observed = observeDirectoryChildren(source, state, node, "", {
+*   onDirectoryChild() {
+*     return 0;
+*   },
+*   isLeafChildDirty() {
+*     return false;
+*   },
+* });
+* expect(observed.affectedNames.size).toBeGreaterThanOrEqual(0);
+* ```
+*/
+function observeDirectoryChildren(source, state, dirNode, dirPath, options) {
+	if (dirNode.state.kind !== "directory") throw new VirtualNotDirectoryError(dirPath);
+	const affectedNames = /* @__PURE__ */ new Set([...dirNode.state.overlay.addedEntries.keys(), ...dirNode.state.overlay.deletedNames.values()]);
+	let dirtyDescendantCount = 0;
+	const children = listDirectoryChildren(source, state, dirNode, dirPath);
+	for (const child of children) {
+		const observedChild = observeListedDirectoryChild(state, dirPath, child);
+		if (observedChild === null) continue;
+		if (observedChild.node.state.kind === "directory") {
+			const childDirtyCount = options.onDirectoryChild({
+				name: observedChild.name,
+				path: observedChild.path,
+				node: observedChild.node
+			});
+			if (childDirtyCount > 0) {
+				affectedNames.add(observedChild.name);
+				dirtyDescendantCount += childDirtyCount;
+			}
+			continue;
+		}
+		if (options.isLeafChildDirty({
+			name: observedChild.name,
+			path: observedChild.path,
+			node: observedChild.node
+		})) affectedNames.add(observedChild.name);
+	}
+	return {
+		affectedNames,
+		dirtyDescendantCount
+	};
+}
+/**
+* 为目录 origin 条目创建按名查询视图。
+*
+* @example
+* ```ts
+* const lookup = createNamedOriginChildLookup(tree.entries);
+* expect(lookup.has("a.txt")).toBe(true);
+* ```
+*/
+function createNamedOriginChildLookup(entries) {
+	const entriesByName = new Map(entries.map((entry) => [entry.name, entry]));
+	return {
+		entries,
+		has(name) {
+			return entriesByName.has(name);
+		},
+		get(name) {
+			return entriesByName.get(name);
+		}
+	};
+}
+/**
+* 基于 origin 顺序和受影响名字生成目录子项编译计划。
+*
+* 1. origin 中未受影响的条目保持原顺序并标记为直接复用
+* 2. origin 中受影响的条目保持原顺序并标记为需要编译
+* 3. 不在 origin 中的受影响名字补在末尾
+*
+* @example
+* ```ts
+* const plan = planAffectedDirectoryChildren(lookup, new Set(["b.txt", "c.txt"]));
+* expect(plan.map((entry) => entry.name)).toEqual(["a.txt", "b.txt", "c.txt"]);
+* ```
+*/
+function planAffectedDirectoryChildren(originLookup, affectedNames) {
+	const out = [];
+	for (const entry of originLookup.entries) out.push({
+		name: entry.name,
+		originEntry: entry,
+		shouldCompile: affectedNames.has(entry.name)
+	});
+	for (const name of affectedNames) {
+		if (originLookup.has(name)) continue;
+		out.push({
+			name,
+			originEntry: null,
+			shouldCompile: true
+		});
+	}
+	return out;
+}
+//#endregion
+export { createNamedOriginChildLookup, observeDirectoryChildren, observeListedDirectoryChild, observeNamedDirectoryChild, planAffectedDirectoryChildren };

package/dist/workdir/dirty-dir-plan.mjs

@@ -0,0 +1,73 @@
+import { getRootNode } from "./session-internal.mjs";
+import { observeDirectoryChildren } from "./directory-view.mjs";
+import { createDirtyDirSummary } from "./dirty-dir.mjs";
+//#region src/workdir/dirty-dir-plan.ts
+/**
+* Virtual Workdir dirty-dir summary 重建策略
+*
+* 把 session 写路径里的脏目录摘要清理与重建逻辑集中到单独模块，
+* 让 session.ts 更接近纯编排层。
+*/
+/**
+* 创建 dirty-dir summary 策略器。
+*
+* @example
+* ```ts
+* const planner = createDirtyDirPlanner(source, state);
+* planner.rebuild(["src/index.ts"]);
+* ```
+*/
+function createDirtyDirPlanner(source, state) {
+	return {
+		clear() {
+			for (const summary of state.listDirtyDirSummaries()) state.deleteDirtyDirSummary(summary.path);
+		},
+		rebuild(touchedPaths) {
+			const nextSummaries = /* @__PURE__ */ new Map();
+			const invalidatedDirPaths = collectInvalidatedSummaryPaths(touchedPaths);
+			const visitDirectory = (node, dirPath) => {
+				if (node.state.kind !== "directory") throw new Error(`rebuildDirtyDirectorySummaries: '${dirPath}' is not a directory`);
+				const { affectedNames, dirtyDescendantCount } = observeDirectoryChildren(source, state, node, dirPath, {
+					onDirectoryChild(child) {
+						return visitDirectory(child.node, child.path);
+					},
+					isLeafChildDirty(child) {
+						return state.getChangeRecord(child.path) !== null;
+					}
+				});
+				if (affectedNames.size === 0 && dirtyDescendantCount === 0) return 0;
+				const existing = state.getDirtyDirSummary(dirPath);
+				const preserveHash = existing !== null && !invalidatedDirPaths.has(dirPath);
+				nextSummaries.set(dirPath, {
+					...createDirtyDirSummary(dirPath, Array.from(affectedNames)),
+					dirtyDescendantCount,
+					currentTreeHash: preserveHash ? existing.currentTreeHash : null,
+					hashState: preserveHash ? existing.hashState : "stale"
+				});
+				return affectedNames.size + dirtyDescendantCount;
+			};
+			visitDirectory(getRootNode(state), "");
+			for (const summary of state.listDirtyDirSummaries()) if (!nextSummaries.has(summary.path)) state.deleteDirtyDirSummary(summary.path);
+			for (const summary of nextSummaries.values()) state.setDirtyDirSummary(summary);
+		}
+	};
+}
+function collectInvalidatedSummaryPaths(paths) {
+	const out = /* @__PURE__ */ new Set();
+	for (const path of paths) {
+		out.add(path);
+		let cursor = path;
+		while (true) {
+			const slashIndex = cursor.lastIndexOf("/");
+			if (slashIndex < 0) {
+				out.add("");
+				break;
+			}
+			cursor = cursor.slice(0, slashIndex);
+			out.add(cursor);
+		}
+	}
+	return out;
+}
+//#endregion
+export { createDirtyDirPlanner };

package/dist/workdir/dirty-dir.d.mts

@@ -0,0 +1,28 @@
+import { SHA1 } from "../core/types.mjs";
+
+//#region src/workdir/dirty-dir.d.ts
+/**
+ * 目录摘要中的 hash 状态
+ */
+type DirtyDirHashState = "stale" | "materialized";
+/**
+ * 脏目录摘要
+ */
+interface DirtyDirSummary {
+  /** 目录路径，根目录为 "" */
+  readonly path: string;
+  /** 当前目录是否脏 */
+  readonly isDirty: boolean;
+  /** 当前目录下受影响的直接子项数量 */
+  readonly dirtyEntryCount: number;
+  /** 当前目录更深层受影响子项数量 */
+  readonly dirtyDescendantCount: number;
+  /** 当前目录下受影响的直接子项名称 */
+  readonly affectedNames: readonly string[];
+  /** 当前物化 tree hash；未计算时为 null */
+  readonly currentTreeHash: SHA1 | null;
+  /** 当前 tree hash 的可信状态 */
+  readonly hashState: DirtyDirHashState;
+}
+//#endregion
+export { DirtyDirSummary };

package/dist/workdir/dirty-dir.mjs

@@ -0,0 +1,32 @@
+//#region src/workdir/dirty-dir.ts
+/**
+* 创建脏目录摘要记录
+*/
+function createDirtyDirSummary(path, affectedNames = []) {
+	const names = [...new Set(affectedNames)].sort((left, right) => left.localeCompare(right));
+	return {
+		path,
+		isDirty: true,
+		dirtyEntryCount: names.length,
+		dirtyDescendantCount: 0,
+		affectedNames: names,
+		currentTreeHash: null,
+		hashState: "stale"
+	};
+}
+/**
+* 将目录摘要标记为已物化 tree hash。
+*/
+function materializeDirtyDirSummary(current, path, treeHash) {
+	return {
+		path,
+		isDirty: true,
+		dirtyEntryCount: current?.dirtyEntryCount ?? 0,
+		dirtyDescendantCount: current?.dirtyDescendantCount ?? 0,
+		affectedNames: [...current?.affectedNames ?? []].sort((left, right) => left.localeCompare(right)),
+		currentTreeHash: treeHash,
+		hashState: "materialized"
+	};
+}
+//#endregion
+export { createDirtyDirSummary, materializeDirtyDirSummary };

package/dist/workdir/file-backend.mjs

@@ -1,3 +1,4 @@
+import { sha1 } from "../core/types.mjs";
 import { createRootDirectoryNode } from "./nodes.mjs";
 import { createVirtualWorkdirSessionId } from "./session-id.mjs";
 import { openVirtualWorkdirSession } from "./session.mjs";
@@ -7,7 +8,7 @@ import { dirname, join } from "node:path";
 /**
 * Virtual Workdir 文件系统 backend
 */
-const FILE_WORKDIR_MANIFEST_VERSION = 1;
+const FILE_WORKDIR_MANIFEST_VERSION = 5;
 const FILE_WORKDIR_TRANSACTION_SNAPSHOT_SUFFIX = ".txn-snapshot";
 /**
 * 创建基于文件系统目录的 Virtual Workdir backend
@@ -129,19 +130,46 @@ function createFileVirtualWorkdirStateStore(sessionsRoot, sessionId) {
 				};
 			});
 		},
-		appendChange(record) {
+		listChangeRecords() {
+			return readManifest(manifestPath).changeRecords.map(restoreChangeRecord);
+		},
+		getChangeRecord(path) {
+			return readManifest(manifestPath).changeRecords.map(restoreChangeRecord).find((record) => record.path === path) ?? null;
+		},
+		setChangeRecord(record) {
+			updateManifest(sessionDir, (manifest) => {
+				const others = manifest.changeRecords.filter((item) => item.path !== record.path);
+				return {
+					...manifest,
+					changeRecords: [...others, serializeChangeRecord(record)].sort((left, right) => left.path.localeCompare(right.path))
+				};
+			});
+		},
+		deleteChangeRecord(path) {
 			updateManifest(sessionDir, (manifest) => ({
 				...manifest,
-				changes: [...manifest.changes, record]
+				changeRecords: manifest.changeRecords.filter((item) => item.path !== path)
 			}));
 		},
-		listChangeRecords() {
-			return readManifest(manifestPath).changes;
+		listDirtyDirSummaries() {
+			return readManifest(manifestPath).dirtyDirSummaries.map(restoreDirtyDirSummary);
+		},
+		getDirtyDirSummary(path) {
+			return readManifest(manifestPath).dirtyDirSummaries.map(restoreDirtyDirSummary).find((summary) => summary.path === path) ?? null;
+		},
+		setDirtyDirSummary(summary) {
+			updateManifest(sessionDir, (manifest) => {
+				const others = manifest.dirtyDirSummaries.filter((item) => item.path !== summary.path);
+				return {
+					...manifest,
+					dirtyDirSummaries: [...others, serializeDirtyDirSummary(summary)].sort((left, right) => left.path.localeCompare(right.path))
+				};
+			});
 		},
-		clearChanges() {
+		deleteDirtyDirSummary(path) {
 			updateManifest(sessionDir, (manifest) => ({
 				...manifest,
-				changes: []
+				dirtyDirSummaries: manifest.dirtyDirSummaries.filter((item) => item.path !== path)
 			}));
 		},
 		reset(baseTree) {
@@ -197,8 +225,9 @@ function createManifest(baseTree, nodes) {
 	return {
 		formatVersion: FILE_WORKDIR_MANIFEST_VERSION,
 		baseTree,
-		changes: [],
-		nodes
+		nodes,
+		changeRecords: [],
+		dirtyDirSummaries: []
 	};
 }
 function updateManifest(sessionDir, updater) {
@@ -217,8 +246,9 @@ function readManifest(manifestPath) {
 }
 function validateManifest(manifest) {
 	if (typeof manifest.baseTree !== "string" || manifest.baseTree.length === 0) throw new Error("Invalid virtual workdir manifest baseTree");
-	if (!Array.isArray(manifest.changes)) throw new Error("Invalid virtual workdir manifest changes");
 	if (typeof manifest.nodes !== "object" || manifest.nodes === null || Array.isArray(manifest.nodes)) throw new Error("Invalid virtual workdir manifest nodes");
+	if (!Array.isArray(manifest.changeRecords)) throw new Error("Invalid virtual workdir manifest changeRecords");
+	if (!Array.isArray(manifest.dirtyDirSummaries)) throw new Error("Invalid virtual workdir manifest dirtyDirSummaries");
 	if (manifest.formatVersion !== FILE_WORKDIR_MANIFEST_VERSION) throw new Error(`Unsupported virtual workdir file manifest version: expected ${FILE_WORKDIR_MANIFEST_VERSION}, got ${manifest.formatVersion}`);
 }
 function persistNode(contentDir, node) {
@@ -339,6 +369,62 @@ function restoreOrigin(record) {
 		hash: origin.hash
 	};
 }
+function serializeChangeRecord(record) {
+	return {
+		path: record.path,
+		previous: record.previous,
+		current: record.current,
+		source: record.source
+	};
+}
+function restoreChangeRecord(record) {
+	return {
+		path: record.path,
+		previous: record.previous === null ? null : {
+			...record.previous,
+			hash: record.previous.hash
+		},
+		current: record.current === null ? null : {
+			...record.current,
+			hash: record.current.hash
+		},
+		source: record.source
+	};
+}
+function serializeDirtyDirSummary(summary) {
+	return {
+		path: summary.path,
+		isDirty: summary.isDirty,
+		dirtyEntryCount: summary.dirtyEntryCount,
+		dirtyDescendantCount: summary.dirtyDescendantCount,
+		affectedNames: [...summary.affectedNames],
+		currentTreeHash: summary.currentTreeHash,
+		hashState: summary.hashState
+	};
+}
+function restoreDirtyDirSummary(summary) {
+	return {
+		path: summary.path,
+		isDirty: summary.isDirty,
+		dirtyEntryCount: readDirtyDirCount(summary.dirtyEntryCount, "dirtyEntryCount"),
+		dirtyDescendantCount: readDirtyDirCount(summary.dirtyDescendantCount, "dirtyDescendantCount"),
+		affectedNames: readDirtyDirAffectedNames(summary.affectedNames),
+		currentTreeHash: summary.currentTreeHash === null ? null : sha1(summary.currentTreeHash),
+		hashState: readDirtyDirHashState(summary.hashState)
+	};
+}
+function readDirtyDirCount(raw, field) {
+	if (typeof raw !== "number" || !Number.isInteger(raw) || raw < 0) throw new Error(`Invalid file workdir dirty dir summary ${field}`);
+	return raw;
+}
+function readDirtyDirAffectedNames(raw) {
+	if (!Array.isArray(raw) || raw.some((item) => typeof item !== "string")) throw new Error("Invalid file workdir dirty dir summary affectedNames");
+	return [...raw].sort((left, right) => left.localeCompare(right));
+}
+function readDirtyDirHashState(raw) {
+	if (raw === "stale" || raw === "materialized") return raw;
+	throw new Error(`Invalid file workdir dirty dir summary hashState: ${String(raw)}`);
+}
 function readPayload(contentDir, payloadRef) {
 	const path = getContentPath(contentDir, payloadRef);
 	if (!existsSync(path)) throw new Error(`Virtual workdir payload not found: ${payloadRef}`);

package/dist/workdir/memory-backend.mjs

@@ -1,4 +1,3 @@
-import { createVirtualChangeLog } from "./change-log.mjs";
 import { VIRTUAL_ROOT_NODE_ID } from "./ids.mjs";
 import { createRootDirectoryNode } from "./nodes.mjs";
 import { createVirtualWorkdirSessionId } from "./session-id.mjs";
@@ -20,7 +19,8 @@ function createVirtualWorkdirMemoryStateStore(baseTree) {
 	const state = {
 		baseTree,
 		nodes: /* @__PURE__ */ new Map(),
-		changeLog: createVirtualChangeLog()
+		changeRecords: /* @__PURE__ */ new Map(),
+		dirtyDirSummaries: /* @__PURE__ */ new Map()
 	};
 	resetState(state, baseTree);
 	return {
@@ -49,14 +49,29 @@ function createVirtualWorkdirMemoryStateStore(baseTree) {
 		deleteNode(id) {
 			state.nodes.delete(id);
 		},
-		appendChange(record) {
-			state.changeLog.append(record);
-		},
 		listChangeRecords() {
-			return state.changeLog.snapshot();
+			return Array.from(state.changeRecords.values()).sort((left, right) => left.path.localeCompare(right.path));
+		},
+		getChangeRecord(path) {
+			return state.changeRecords.get(path) ?? null;
+		},
+		setChangeRecord(record) {
+			state.changeRecords.set(record.path, record);
+		},
+		deleteChangeRecord(path) {
+			state.changeRecords.delete(path);
+		},
+		listDirtyDirSummaries() {
+			return Array.from(state.dirtyDirSummaries.values()).sort((left, right) => left.path.localeCompare(right.path));
+		},
+		getDirtyDirSummary(path) {
+			return state.dirtyDirSummaries.get(path) ?? null;
+		},
+		setDirtyDirSummary(summary) {
+			state.dirtyDirSummaries.set(summary.path, summary);
 		},
-		clearChanges() {
-			state.changeLog.clear();
+		deleteDirtyDirSummary(path) {
+			state.dirtyDirSummaries.delete(path);
 		},
 		reset(nextBaseTree) {
 			resetState(state, nextBaseTree);
@@ -99,8 +114,9 @@ function createMemoryVirtualWorkdirBackend() {
 function resetState(state, baseTree) {
 	state.baseTree = baseTree;
 	state.nodes.clear();
+	state.changeRecords.clear();
+	state.dirtyDirSummaries.clear();
 	state.nodes.set(VIRTUAL_ROOT_NODE_ID, createRootDirectoryNode(baseTree));
-	state.changeLog.clear();
 }
 function snapshotState(state) {
 	const nodes = /* @__PURE__ */ new Map();
@@ -108,15 +124,18 @@ function snapshotState(state) {
 	return {
 		baseTree: state.baseTree,
 		nodes,
-		changes: state.changeLog.snapshot()
+		changeRecords: new Map(state.changeRecords),
+		dirtyDirSummaries: new Map(state.dirtyDirSummaries)
 	};
 }
 function restoreState(state, snapshot) {
 	state.baseTree = snapshot.baseTree;
 	state.nodes.clear();
+	state.changeRecords.clear();
+	state.dirtyDirSummaries.clear();
 	for (const [nodeId, node] of snapshot.nodes) state.nodes.set(nodeId, cloneSessionNode(node));
-	state.changeLog.clear();
-	for (const record of snapshot.changes) state.changeLog.append(record);
+	for (const [path, record] of snapshot.changeRecords) state.changeRecords.set(path, record);
+	for (const [path, summary] of snapshot.dirtyDirSummaries) state.dirtyDirSummaries.set(path, summary);
 }
 function cloneSessionNode(node) {
 	if (node.state.kind === "directory") return {

package/dist/workdir/nodes.mjs

@@ -29,12 +29,6 @@ function nodeHasRepoOrigin(node) {
 	return node.origin.kind === "repo-tree" || node.origin.kind === "repo-blob";
 }
 /**
-* 目录 overlay 是否有 session 层修改
-*/
-function isDirectoryOverlayDirty(overlay) {
-	return overlay.addedEntries.size > 0 || overlay.deletedNames.size > 0;
-}
-/**
 * 将节点状态恢复到 origin 语义（丢弃 materialize / 目录 overlay）
 *
 * 无 repo origin 时返回原状态引用，由上层决定是否抛错。
@@ -109,4 +103,4 @@ function cloneSessionNodeForCopy(source, newId) {
 	};
 }
 //#endregion
-export { cloneSessionNodeForCopy, createRootDirectoryNode, isDirectoryOverlayDirty, revertNodeState };
+export { cloneSessionNodeForCopy, createRootDirectoryNode, revertNodeState };