nano-git 0.2.0 → 0.2.2

package/dist/workdir/memory-backend.mjs

@@ -0,0 +1,159 @@
+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";
+import { openVirtualWorkdirSession } from "./session.mjs";
+//#region src/workdir/memory-backend.ts
+/**
+* Virtual Workdir 内存状态存储
+*/
+/**
+* 创建内存版状态存储
+*
+* @example
+* ```ts
+* const store = createVirtualWorkdirMemoryStateStore(tree);
+* expect(store.readBaseTree()).toBe(tree);
+* ```
+*/
+function createVirtualWorkdirMemoryStateStore(baseTree) {
+	const state = {
+		baseTree,
+		nodes: /* @__PURE__ */ new Map(),
+		changeLog: createVirtualChangeLog()
+	};
+	resetState(state, baseTree);
+	return {
+		kind: "memory",
+		transact(fn) {
+			const snapshot = snapshotState(state);
+			try {
+				return fn();
+			} catch (error) {
+				restoreState(state, snapshot);
+				throw error;
+			}
+		},
+		readBaseTree() {
+			return state.baseTree;
+		},
+		writeBaseTree(nextBaseTree) {
+			state.baseTree = nextBaseTree;
+		},
+		getNode(id) {
+			return state.nodes.get(id) ?? null;
+		},
+		setNode(node) {
+			state.nodes.set(node.id, node);
+		},
+		deleteNode(id) {
+			state.nodes.delete(id);
+		},
+		appendChange(record) {
+			state.changeLog.append(record);
+		},
+		listChangeRecords() {
+			return state.changeLog.snapshot();
+		},
+		clearChanges() {
+			state.changeLog.clear();
+		},
+		reset(nextBaseTree) {
+			resetState(state, nextBaseTree);
+		}
+	};
+}
+/**
+* 创建内存版 Virtual Workdir backend
+*
+* @example
+* ```ts
+* const backend = createMemoryVirtualWorkdirBackend();
+* const sessionId = backend.createSession({ baseTree: tree });
+* const session = backend.openSession(repo.objects, sessionId);
+* expect(session.baseTree).toBe(tree);
+* ```
+*/
+function createMemoryVirtualWorkdirBackend() {
+	const sessions = /* @__PURE__ */ new Map();
+	return {
+		kind: "memory",
+		createSession(options) {
+			const sessionId = createVirtualWorkdirSessionId();
+			sessions.set(sessionId, createVirtualWorkdirMemoryStateStore(options.baseTree));
+			return sessionId;
+		},
+		openSession(source, sessionId) {
+			const store = sessions.get(sessionId);
+			if (store === void 0) throw new Error(`Virtual workdir session not found: ${sessionId}`);
+			return openVirtualWorkdirSession(source, store);
+		},
+		deleteSession(sessionId) {
+			if (!sessions.delete(sessionId)) throw new Error(`Virtual workdir session not found: ${sessionId}`);
+		},
+		listSessions() {
+			return Array.from(sessions.keys());
+		}
+	};
+}
+function resetState(state, baseTree) {
+	state.baseTree = baseTree;
+	state.nodes.clear();
+	state.nodes.set(VIRTUAL_ROOT_NODE_ID, createRootDirectoryNode(baseTree));
+	state.changeLog.clear();
+}
+function snapshotState(state) {
+	const nodes = /* @__PURE__ */ new Map();
+	for (const [nodeId, node] of state.nodes) nodes.set(nodeId, cloneSessionNode(node));
+	return {
+		baseTree: state.baseTree,
+		nodes,
+		changes: state.changeLog.snapshot()
+	};
+}
+function restoreState(state, snapshot) {
+	state.baseTree = snapshot.baseTree;
+	state.nodes.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);
+}
+function cloneSessionNode(node) {
+	if (node.state.kind === "directory") return {
+		id: node.id,
+		origin: node.origin,
+		state: {
+			kind: "directory",
+			overlay: {
+				addedEntries: new Map(node.state.overlay.addedEntries),
+				deletedNames: new Set(node.state.overlay.deletedNames)
+			}
+		}
+	};
+	if (node.state.kind === "file") return {
+		id: node.id,
+		origin: node.origin,
+		state: node.state.content === void 0 ? {
+			kind: "file",
+			mode: node.state.mode
+		} : {
+			kind: "file",
+			mode: node.state.mode,
+			content: Buffer.from(node.state.content)
+		}
+	};
+	return {
+		id: node.id,
+		origin: node.origin,
+		state: node.state.target === void 0 ? {
+			kind: "symlink",
+			mode: "120000"
+		} : {
+			kind: "symlink",
+			mode: "120000",
+			target: Buffer.from(node.state.target)
+		}
+	};
+}
+//#endregion
+export { createMemoryVirtualWorkdirBackend, createVirtualWorkdirMemoryStateStore };

package/dist/workdir/memory.d.mts

@@ -0,0 +1,3 @@
+import { createMemoryVirtualWorkdirBackend } from "./memory-backend.mjs";
+import { createVirtualWorkdirSession, openVirtualWorkdirSession } from "./session.mjs";
+export { createMemoryVirtualWorkdirBackend, createVirtualWorkdirSession, openVirtualWorkdirSession };

package/dist/workdir/memory.mjs

@@ -0,0 +1,3 @@
+import { createVirtualWorkdirSession, openVirtualWorkdirSession } from "./session.mjs";
+import { createMemoryVirtualWorkdirBackend } from "./memory-backend.mjs";
+export { createMemoryVirtualWorkdirBackend, createVirtualWorkdirSession, openVirtualWorkdirSession };

package/dist/workdir/nodes.d.mts

@@ -0,0 +1,57 @@
+import { SHA1 } from "../core/types.mjs";
+import { NodeId } from "./ids.mjs";
+import { DirectoryOverlay } from "./overlay.mjs";
+
+//#region src/workdir/nodes.d.ts
+/** Blob / 符号链接在 origin 与 state 中使用的 mode */
+type BlobObjectMode = "100644" | "100755" | "120000";
+/**
+ * 节点来源（repo 对象或纯 session 新建）
+ */
+type NodeOrigin = {
+  readonly kind: "none";
+} | {
+  readonly kind: "repo-tree";
+  readonly hash: SHA1;
+} | {
+  readonly kind: "repo-blob";
+  readonly mode: BlobObjectMode;
+  readonly hash: SHA1;
+};
+/**
+ * 目录节点当前状态
+ *
+ * `overlay` 表达 session 层增删改；子项 nodeId 通过 overlay 合成与懒加载解析。
+ */
+interface DirectoryNodeState {
+  readonly kind: "directory";
+  readonly overlay: DirectoryOverlay;
+}
+/**
+ * 文件节点当前状态（raw content overlay）
+ */
+interface FileNodeState {
+  readonly kind: "file";
+  readonly mode: "100644" | "100755";
+  /** 未设置时表示未 materialize，可读 origin */
+  readonly content?: Buffer;
+}
+/**
+ * 符号链接节点当前状态
+ */
+interface SymlinkNodeState {
+  readonly kind: "symlink";
+  readonly mode: "120000";
+  readonly target?: Buffer;
+}
+type SessionNodeState = DirectoryNodeState | FileNodeState | SymlinkNodeState;
+/**
+ * 完整的会话节点记录
+ */
+interface SessionNode {
+  readonly id: NodeId;
+  readonly origin: NodeOrigin;
+  readonly state: SessionNodeState;
+}
+//#endregion
+export { SessionNode };

package/dist/workdir/nodes.mjs

@@ -0,0 +1,112 @@
+import { VIRTUAL_ROOT_NODE_ID } from "./ids.mjs";
+import { cloneDirectoryOverlay, createEmptyDirectoryOverlay } from "./overlay.mjs";
+//#region src/workdir/nodes.ts
+/**
+* Virtual Workdir 会话节点状态模型
+*
+* 节点身份（nodeId）与目录路径绑定分离；origin 描述 repo-backed 来源。
+*/
+/**
+* 创建绑定 repo 根 tree 的目录节点（带空 overlay）
+*/
+function createRootDirectoryNode(originTreeHash) {
+	return {
+		id: VIRTUAL_ROOT_NODE_ID,
+		origin: {
+			kind: "repo-tree",
+			hash: originTreeHash
+		},
+		state: {
+			kind: "directory",
+			overlay: createEmptyDirectoryOverlay()
+		}
+	};
+}
+/**
+* 节点是否携带可 revert 的 repo origin
+*/
+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 时返回原状态引用，由上层决定是否抛错。
+*/
+function revertNodeState(node) {
+	if (!nodeHasRepoOrigin(node)) return node;
+	if (node.state.kind === "directory") return {
+		...node,
+		state: {
+			kind: "directory",
+			overlay: createEmptyDirectoryOverlay()
+		}
+	};
+	if (node.state.kind === "file") {
+		const mode = node.state.mode;
+		return {
+			...node,
+			state: {
+				kind: "file",
+				mode
+			}
+		};
+	}
+	return {
+		...node,
+		state: {
+			kind: "symlink",
+			mode: "120000"
+		}
+	};
+}
+/**
+* 为 `copy` 创建新节点：共享 origin，目录为浅复制（子项绑定保留，但 nodeId 为新）
+*/
+function cloneSessionNodeForCopy(source, newId) {
+	const origin = source.origin;
+	if (source.state.kind === "directory") return {
+		id: newId,
+		origin,
+		state: {
+			kind: "directory",
+			overlay: cloneDirectoryOverlay(source.state.overlay)
+		}
+	};
+	if (source.state.kind === "file") {
+		const content = source.state.content;
+		return {
+			id: newId,
+			origin,
+			state: content === void 0 ? {
+				kind: "file",
+				mode: source.state.mode
+			} : {
+				kind: "file",
+				mode: source.state.mode,
+				content: Buffer.from(content)
+			}
+		};
+	}
+	const target = source.state.target;
+	return {
+		id: newId,
+		origin,
+		state: target === void 0 ? {
+			kind: "symlink",
+			mode: "120000"
+		} : {
+			kind: "symlink",
+			mode: "120000",
+			target: Buffer.from(target)
+		}
+	};
+}
+//#endregion
+export { cloneSessionNodeForCopy, createRootDirectoryNode, isDirectoryOverlayDirty, revertNodeState };

package/dist/workdir/origin.mjs

@@ -0,0 +1,55 @@
+import { VirtualOriginUnavailableError } from "../core/errors.mjs";
+import { tryReadObject } from "../objects/raw.mjs";
+//#region src/workdir/origin.ts
+/**
+* 从对象源读取 repo-backed origin（tree/blob）
+*
+* 仅依赖 ObjectSource，不绑定具体 ODB 后端实现。
+*/
+/**
+* 读取 tree 对象；缺失时抛 VirtualOriginUnavailableError
+*/
+function readRepoTree(source, hash, path) {
+	const obj = tryReadObject(source, hash);
+	if (obj === void 0) throw new VirtualOriginUnavailableError(path, `Origin tree object missing: ${hash}`);
+	if (obj.type !== "tree") throw new VirtualOriginUnavailableError(path, `Expected tree at origin, got ${obj.type}`);
+	return obj;
+}
+/**
+* 读取 blob 原始内容；缺失时抛 VirtualOriginUnavailableError
+*/
+function readRepoBlobContent(source, hash, path) {
+	const obj = tryReadObject(source, hash);
+	if (obj === void 0) throw new VirtualOriginUnavailableError(path, `Origin blob object missing: ${hash}`);
+	if (obj.type !== "blob") throw new VirtualOriginUnavailableError(path, `Expected blob at origin, got ${obj.type}`);
+	return obj.content;
+}
+/**
+* 根据 tree 条目构造节点 origin
+*/
+function treeEntryToNodeOrigin(entry) {
+	if (entry.mode === "40000") return {
+		kind: "repo-tree",
+		hash: entry.hash
+	};
+	if (entry.mode === "100644" || entry.mode === "100755" || entry.mode === "120000") return {
+		kind: "repo-blob",
+		mode: entry.mode,
+		hash: entry.hash
+	};
+	return {
+		kind: "repo-blob",
+		mode: "100644",
+		hash: entry.hash
+	};
+}
+/**
+* Git mode 转为 VirtualEntryKind
+*/
+function modeToVirtualEntryKind(mode) {
+	if (mode === "40000") return "tree";
+	if (mode === "120000") return "symlink";
+	return "blob";
+}
+//#endregion
+export { modeToVirtualEntryKind, readRepoBlobContent, readRepoTree, treeEntryToNodeOrigin };

package/dist/workdir/overlay.d.mts

@@ -0,0 +1,14 @@
+import { NodeId } from "./ids.mjs";
+
+//#region src/workdir/overlay.d.ts
+/**
+ * 目录 overlay 状态（挂在目录 SessionNode 上）
+ */
+interface DirectoryOverlay {
+  /** session 新增或覆盖：条目名 -> 绑定的 nodeId */
+  readonly addedEntries: Map<string, NodeId>;
+  /** session 删除的 origin/先前条目名（tombstone） */
+  readonly deletedNames: Set<string>;
+}
+//#endregion
+export { DirectoryOverlay };

package/dist/workdir/overlay.mjs

@@ -0,0 +1,95 @@
+//#region src/workdir/overlay.ts
+/**
+* 创建空目录 overlay
+*/
+function createEmptyDirectoryOverlay() {
+	return {
+		addedEntries: /* @__PURE__ */ new Map(),
+		deletedNames: /* @__PURE__ */ new Set()
+	};
+}
+/**
+* 克隆目录 overlay（深拷贝 Map/Set）
+*/
+function cloneDirectoryOverlay(overlay) {
+	return {
+		addedEntries: new Map(overlay.addedEntries),
+		deletedNames: new Set(overlay.deletedNames)
+	};
+}
+/**
+* 按 RFC 规则合成目录子项列表
+*
+* 1. 从 origin 去掉 deletedNames
+* 2. addedEntries 覆盖同名 origin
+* 3. 仅存在于 addedEntries 的条目追加
+* 4. 按 Git tree 名称排序
+*/
+function mergeDirectoryChildren(originChildren, overlay, addedEntryModes) {
+	const byName = /* @__PURE__ */ new Map();
+	for (const child of originChildren) {
+		if (overlay.deletedNames.has(child.name)) continue;
+		const overrideId = overlay.addedEntries.get(child.name);
+		if (overrideId !== void 0) {
+			const mode = addedEntryModes.get(child.name) ?? child.mode;
+			byName.set(child.name, {
+				name: child.name,
+				mode,
+				nodeId: overrideId
+			});
+		} else byName.set(child.name, {
+			name: child.name,
+			mode: child.mode,
+			nodeId: child.nodeId
+		});
+	}
+	for (const [name, nodeId] of overlay.addedEntries) {
+		if (byName.has(name)) continue;
+		const mode = addedEntryModes.get(name);
+		if (mode === void 0) throw new Error(`Missing mode for added directory entry '${name}'`);
+		byName.set(name, {
+			name,
+			mode,
+			nodeId
+		});
+	}
+	const merged = Array.from(byName.values());
+	merged.sort((a, b) => a.name.localeCompare(b.name));
+	return merged;
+}
+/**
+* 在目录 overlay 中绑定或覆盖条目（create / modify / rename 目标 / copy 目标）
+*/
+function overlayBindEntry(overlay, name, nodeId) {
+	const addedEntries = new Map(overlay.addedEntries);
+	const deletedNames = new Set(overlay.deletedNames);
+	addedEntries.set(name, nodeId);
+	deletedNames.delete(name);
+	return {
+		addedEntries,
+		deletedNames
+	};
+}
+/**
+* 在目录 overlay 中删除条目（tombstone；不递归清理子节点存储）
+*/
+function overlayTombstoneEntry(overlay, name) {
+	const addedEntries = new Map(overlay.addedEntries);
+	const deletedNames = new Set(overlay.deletedNames);
+	if (addedEntries.has(name)) addedEntries.delete(name);
+	else deletedNames.add(name);
+	return {
+		addedEntries,
+		deletedNames
+	};
+}
+/**
+* 在同一目录内重命名：复用 nodeId，仅改绑定名
+*/
+function overlayRenameEntry(overlay, fromName, toName, nodeId) {
+	let next = overlayTombstoneEntry(overlay, fromName);
+	next = overlayBindEntry(next, toName, nodeId);
+	return next;
+}
+//#endregion
+export { cloneDirectoryOverlay, createEmptyDirectoryOverlay, mergeDirectoryChildren, overlayBindEntry, overlayRenameEntry, overlayTombstoneEntry };

package/dist/workdir/path.mjs

@@ -0,0 +1,70 @@
+/**
+* 规范化 readdir 等 API 的目录路径参数
+*
+* `undefined` 与 `""` 均视为根目录。
+*/
+function normalizeDirectoryPath(path) {
+	if (path === void 0 || path === "") return "";
+	assertValidVirtualPath(path);
+	return path;
+}
+/**
+* 校验非根虚拟路径格式（用于文件/子路径操作）
+*
+* @throws 路径为空或格式非法时抛出 Error
+*/
+function assertValidVirtualPath(path) {
+	if (path === "") throw new Error("Path must not be empty");
+	validateVirtualPathSegments(path);
+}
+/**
+* 校验路径段规则（根路径 `""` 由调用方单独处理）
+*/
+function validateVirtualPathSegments(path) {
+	if (path.startsWith("/")) throw new Error(`Path must not start with '/': ${path}`);
+	if (path.endsWith("/")) throw new Error(`Path must not end with '/': ${path}`);
+	if (path.includes("//")) throw new Error(`Path must not contain consecutive slashes: ${path}`);
+	for (const segment of path.split("/")) {
+		if (segment === "." || segment === "..") throw new Error(`Path must not contain '.' or '..': ${path}`);
+		if (segment === "") throw new Error(`Path must not contain empty segments: ${path}`);
+	}
+}
+/**
+* 将路径拆分为段（不含空段）
+*
+* 调用前须保证路径已通过 `assertValidVirtualPath`。
+*/
+function splitPathSegments(path) {
+	return path.split("/");
+}
+/**
+* 返回父路径；单段路径返回 `null`（表示无父目录，父为根）
+*/
+function parentPath(path) {
+	assertValidVirtualPath(path);
+	const lastSlash = path.lastIndexOf("/");
+	if (lastSlash === -1) return null;
+	return path.slice(0, lastSlash);
+}
+/**
+* 返回路径最后一段（条目名）
+*/
+function baseName(path) {
+	assertValidVirtualPath(path);
+	const lastSlash = path.lastIndexOf("/");
+	return lastSlash === -1 ? path : path.slice(lastSlash + 1);
+}
+/**
+* 组合父路径与条目名
+*
+* @param parent - `null` 表示根下直接子项
+*/
+function joinPath(parent, name) {
+	if (name === "" || name.includes("/")) throw new Error(`Invalid entry name: ${name}`);
+	if (parent === null) return name;
+	if (parent === "") return name;
+	assertValidVirtualPath(parent);
+	return `${parent}/${name}`;
+}
+//#endregion
+export { assertValidVirtualPath, baseName, joinPath, normalizeDirectoryPath, parentPath, splitPathSegments };

package/dist/workdir/session-id.mjs

@@ -0,0 +1,18 @@
+//#region src/workdir/session-id.ts
+let nextSessionCounter = 1;
+/**
+* 分配新的 session ID
+*
+* @example
+* ```ts
+* const sessionId = createVirtualWorkdirSessionId();
+* expect(String(sessionId).startsWith("session:")).toBe(true);
+* ```
+*/
+function createVirtualWorkdirSessionId() {
+	const id = `session:${nextSessionCounter}`;
+	nextSessionCounter += 1;
+	return id;
+}
+//#endregion
+export { createVirtualWorkdirSessionId };