nano-git 0.3.0 → 0.3.2

package/dist/workdir/core.d.mts

@@ -1,5 +1,4 @@
 import { SHA1 } from "../core/types.mjs";
-import { ObjectDatabase } from "../core/types/odb.mjs";
 import { VirtualNotDirectoryError, VirtualNotFileError, VirtualNotSymlinkError, VirtualOriginUnavailableError, VirtualPathAlreadyExistsError, VirtualPathNotFoundError, VirtualRevertNotSupportedError } from "../core/errors.mjs";
 
 //#region src/workdir/core.d.ts
@@ -40,62 +39,89 @@ interface VirtualDirEntry {
   readonly mode: string;
 }
 /**
- * 变更操作类型
- *
- * 用于 `listChanges()` 返回的变更记录。
+ * diff 中的对象描述
  */
-type VirtualChangeType = "add" | "modify" | "delete" | "rename" | "copy";
+interface VirtualDiffObject {
+  /** 条目种类 */
+  readonly kind: "blob" | "symlink";
+  /** Git 文件模式 */
+  readonly mode: "100644" | "100755" | "120000";
+  /** 对象哈希 */
+  readonly hash: SHA1;
+}
 /**
- * 单条变更记录
- *
- * 由 `listChanges()` 返回，描述 session 内的单次操作。
- * 变更记录是会话内调试/测试辅助，不保证是最小 diff。
+ * rename/copy 来源描述
  */
-interface VirtualChange {
-  /** 操作路径 */
+interface VirtualDiffSource {
+  /** 来源类型 */
+  readonly kind: "rename" | "copy";
+  /** 来源路径 */
   readonly path: string;
-  /** 变更操作类型 */
-  readonly type: VirtualChangeType;
-  /** rename/copy 操作的源路径（其他操作为 undefined） */
-  readonly oldPath?: string;
 }
 /**
- * 创建 VirtualWorkdirSession 的选项
+ * 同路径更新的变化维度
  */
-interface CreateVirtualWorkdirSessionOptions {
-  /** 基线 tree 的 SHA-1 哈希 */
-  readonly baseTree: SHA1;
+interface VirtualDiffChanges {
+  /** 条目种类是否变化 */
+  readonly kindChanged: boolean;
+  /** mode 是否变化 */
+  readonly modeChanged: boolean;
+  /** 内容哈希是否变化 */
+  readonly contentChanged: boolean;
 }
 /**
- * Virtual Workdir session 标识
+ * 单条 diff 条目
+ *
+ * 仅描述最终状态，不表达完整会话内操作历史。
  */
-type VirtualWorkdirSessionId = string & {
-  readonly __brand: "VirtualWorkdirSessionId";
+type VirtualDiffEntry = {
+  /** 新建路径 */readonly kind: "create"; /** 当前路径 */
+  readonly path: string; /** 当前对象 */
+  readonly current: VirtualDiffObject; /** rename/copy 的来源 */
+  readonly source?: VirtualDiffSource;
+} | {
+  /** 删除路径 */readonly kind: "remove"; /** 当前路径 */
+  readonly path: string; /** 删除前对象 */
+  readonly previous: VirtualDiffObject;
+} | {
+  /** 同路径更新 */readonly kind: "update"; /** 当前路径 */
+  readonly path: string; /** 更新前对象 */
+  readonly previous: VirtualDiffObject; /** 更新后对象 */
+  readonly current: VirtualDiffObject; /** 变化维度 */
+  readonly changes: VirtualDiffChanges; /** rename/copy 的来源 */
+  readonly source?: VirtualDiffSource;
 };
 /**
- * VirtualWorkdirSession（虚拟工作目录会话）
+ * 创建 VirtualWorkdir 的选项
+ */
+interface CreateVirtualWorkdirOptions {
+  /** 基线 tree 的 SHA-1 哈希 */
+  readonly baseTree: SHA1;
+}
+/**
+ * VirtualWorkdir（虚拟工作目录实例）
  *
  * 提供独立生命周期的可变 tree 视图，基于 `baseTree + CoW overlay` 模型。
  * 不绑定 commit，不涉及 Git index / 真实工作目录。
  *
- * 当前 session 对 origin 仓库对象采用弱保证：
+ * 当前实例对 origin 仓库对象采用弱保证：
  * 如果 base tree / origin blob 在后续被移除、损坏或不可读取，
  * 相关读取、`revert()`、`writeTree()` 等操作会抛出 `VirtualOriginUnavailableError`。
  *
  * @example
  * ```ts
  * import { createMemoryRepository } from "nano-git/repository/memory";
- * import { createVirtualWorkdirSession } from "nano-git/workdir/memory";
+ * import { createVirtualWorkdir } from "nano-git/workdir/memory";
  *
  * const repo = createMemoryRepository();
  * const tree = repo.writeTree(); // 初始空 tree
- * const session = createVirtualWorkdirSession(repo, { baseTree: tree });
+ * const workdir = createVirtualWorkdir(repo.objects, { baseTree: tree });
  *
- * session.writeFile("hello.txt", Buffer.from("world"));
- * const newTree = session.writeTree();
+ * workdir.writeFile("hello.txt", Buffer.from("world"));
+ * const newTree = workdir.writeTree();
  * ```
  */
-interface VirtualWorkdirSession {
+interface VirtualWorkdir {
   /** 当前基线 tree 的 SHA-1 哈希 */
   readonly baseTree: SHA1;
   /** 路径是否存在 */
@@ -128,7 +154,7 @@ interface VirtualWorkdirSession {
   /**
    * 复制路径
    *
-   * 新建 session node，共享 origin，不共享 node 身份。
+   * 新建 workdir node，共享 origin，不共享 node 身份。
    * 目录复制为浅复制，子项保持懒加载。
    */
   copy(from: string, to: string): void;
@@ -139,6 +165,12 @@ interface VirtualWorkdirSession {
    * 对纯新建节点抛出 VirtualRevertNotSupportedError。
    */
   revert(path: string): void;
+  /**
+   * 读取最终 diff
+   *
+   * 输出按路径稳定排序，仅包含文件与符号链接条目。
+   */
+  diff(): VirtualDiffEntry[];
   /**
    * 导出当前 overlay 为新 tree
    *
@@ -147,42 +179,11 @@ interface VirtualWorkdirSession {
    */
   writeTree(): SHA1;
   /**
-   * 重置 session 到指定基线 tree
+   * 重置当前实例到指定基线 tree
    *
    * 丢弃全部 overlay 与变更历史。
    */
   reset(baseTree: SHA1): void;
-  /**
-   * 列出会话内的变更记录
-   *
-   * 是会话内调试/测试辅助，不保证是最小 diff 引擎。
-   * 输出稳定、测试可断言即可。
-   */
-  listChanges(): VirtualChange[];
-}
-/**
- * VirtualWorkdirBackend
- *
- * session 内部状态存储的抽象接口。
- * memory / file / sqlite 后端通过实现此接口来提供不同的持久化策略。
- *
- * `file` / `sqlite` 持久化 backend 当前都按单进程、单写者场景收口；
- * 不承诺跨进程并发写安全，也不提供多写者协调协议。
- *
- * 本接口在后续 Phase 中会逐步补充完整方法签名。
- * 当前仅为命名冻结与角色声明。
- */
-interface VirtualWorkdirBackend {
-  /** 后端类型标识 */
-  readonly kind: "memory" | "file" | "sqlite";
-  /** 创建新 session 并返回其标识 */
-  createSession(options: CreateVirtualWorkdirSessionOptions): VirtualWorkdirSessionId;
-  /** 打开已存在的 session */
-  openSession(source: ObjectDatabase, sessionId: VirtualWorkdirSessionId): VirtualWorkdirSession;
-  /** 删除 session */
-  deleteSession(sessionId: VirtualWorkdirSessionId): void;
-  /** 列出当前后端中可完整恢复的 session */
-  listSessions(): VirtualWorkdirSessionId[];
 }
 //#endregion
-export { CreateVirtualWorkdirSessionOptions, VirtualChange, VirtualChangeType, VirtualDirEntry, VirtualEntryKind, VirtualEntryStat, VirtualNotDirectoryError, VirtualNotFileError, VirtualNotSymlinkError, VirtualOriginUnavailableError, VirtualPathAlreadyExistsError, VirtualPathNotFoundError, VirtualRevertNotSupportedError, VirtualWorkdirBackend, VirtualWorkdirSession, VirtualWorkdirSessionId };
+export { CreateVirtualWorkdirOptions, VirtualDiffChanges, VirtualDiffEntry, VirtualDiffObject, VirtualDiffSource, VirtualDirEntry, VirtualEntryKind, VirtualEntryStat, VirtualNotDirectoryError, VirtualNotFileError, VirtualNotSymlinkError, VirtualOriginUnavailableError, VirtualPathAlreadyExistsError, VirtualPathNotFoundError, VirtualRevertNotSupportedError, VirtualWorkdir };

package/dist/workdir/directory-view.mjs

@@ -0,0 +1,197 @@
+import { VirtualNotDirectoryError } from "../core/errors.mjs";
+import { ensureNodeFromTreeEntry, joinChildPath, listDirectoryChildren } from "./workdir-path.mjs";
+//#region src/workdir/directory-view.ts
+/**
+* Virtual Workdir 目录展开、观察与编译计划
+*
+* 从 workdir-path.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 "./workdir-path.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 重建策略
+*
+* 把 workdir 写路径里的脏目录摘要清理与重建逻辑集中到单独模块，
+* 让 workdir.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.d.mts

@@ -1,22 +1,44 @@
-import { VirtualWorkdirBackend } from "./core.mjs";
+import { ObjectDatabase } from "../core/types/odb.mjs";
+import { CreateVirtualWorkdirOptions, VirtualWorkdir } from "./core.mjs";
+import { VirtualWorkdirStateStore } from "./state-store.mjs";
 
 //#region src/workdir/file-backend.d.ts
-/** 创建文件系统 Virtual Workdir backend 的可选参数 */
-interface CreateFileVirtualWorkdirBackendOptions {
-  /** session 根目录名，默认 `sessions` */
-  readonly sessionsDirName?: string;
+/** 打开文件系统 VirtualWorkdir 的可选参数 */
+interface OpenFileVirtualWorkdirOptions extends CreateVirtualWorkdirOptions {
+  /** 不存在时按 baseTree 初始化 */
+  readonly create?: boolean;
 }
 /**
- * 创建基于文件系统目录的 Virtual Workdir backend
+ * 打开基于目录持久化的 VirtualWorkdir
  *
  * @example
  * ```ts
- * const backend = createFileVirtualWorkdirBackend("/tmp/workdirs");
- * const sessionId = backend.createSession({ baseTree: tree });
- * const session = backend.openSession(repo.objects, sessionId);
- * expect(session.baseTree).toBe(tree);
+ * const workdir = openFileVirtualWorkdir(repo.objects, "/tmp/workdir", {
+ *   baseTree: tree,
+ *   create: true,
+ * });
+ * expect(workdir.baseTree).toBe(tree);
  * ```
  */
-declare function createFileVirtualWorkdirBackend(rootDir: string, options?: CreateFileVirtualWorkdirBackendOptions): VirtualWorkdirBackend;
+declare function openFileVirtualWorkdir(source: ObjectDatabase, workdirDir: string, options: OpenFileVirtualWorkdirOptions): VirtualWorkdir;
+/**
+ * 删除指定目录上的持久化 VirtualWorkdir
+ *
+ * @example
+ * ```ts
+ * deleteFileVirtualWorkdir("/tmp/workdir");
+ * ```
+ */
+declare function deleteFileVirtualWorkdir(workdirDir: string): void;
+/**
+ * 创建单个文件系统 VirtualWorkdir 的状态存储
+ *
+ * @example
+ * ```ts
+ * const store = createFileVirtualWorkdirStateStore("/tmp/workdir");
+ * expect(store.kind).toBe("file");
+ * ```
+ */
+declare function createFileVirtualWorkdirStateStore(workdirDir: string): VirtualWorkdirStateStore;
 //#endregion
-export { CreateFileVirtualWorkdirBackendOptions, createFileVirtualWorkdirBackend };
+export { OpenFileVirtualWorkdirOptions, createFileVirtualWorkdirStateStore, deleteFileVirtualWorkdir, openFileVirtualWorkdir };