nano-git 0.3.0 → 0.3.2

package/dist/workdir/workdir-path.mjs

@@ -0,0 +1,348 @@
+import { VirtualNotDirectoryError, VirtualNotFileError, VirtualPathAlreadyExistsError, VirtualPathNotFoundError } from "../core/errors.mjs";
+import { VIRTUAL_ROOT_NODE_ID, originBackedNodeId } from "./ids.mjs";
+import { readRepoTree, treeEntryToNodeOrigin } from "./origin.mjs";
+import { mergeDirectoryChildren } from "./overlay.mjs";
+import { assertValidVirtualPath, baseName, joinPath, parentPath, splitPathSegments } from "./path.mjs";
+//#region src/workdir/workdir-path.ts
+/**
+* Virtual Workdir 路径解析与共享读视图
+*
+* 供 workdir.ts 与 write-tree.ts 复用：
+* - 路径解析（resolvePath / resolveWriteTarget*）
+* - 目录子项展开（listDirectoryChildren / getDirectoryChildrenView）
+* - origin 节点懒注册（ensureNodeFromTreeEntry）
+*
+* 目录观察与编译计划相关的类型和函数已拆分到 directory-view.ts。
+*/
+/**
+* 基于目录路径与子项名称拼出子路径。
+*
+* @example
+* ```ts
+* expect(joinChildPath("", "a.txt")).toBe("a.txt");
+* expect(joinChildPath("src", "a.txt")).toBe("src/a.txt");
+* ```
+*/
+function joinChildPath(dirPath, name) {
+	return dirPath === "" ? name : `${dirPath}/${name}`;
+}
+function getRootNode(state) {
+	const root = state.getNode(VIRTUAL_ROOT_NODE_ID);
+	if (root === null) throw new Error("Virtual workdir is missing root node");
+	return root;
+}
+/**
+* 从根目录沿路径分段解析到目标节点
+*/
+function resolvePath(source, state, path) {
+	assertValidVirtualPath(path);
+	const segments = splitPathSegments(path);
+	let current = getRootNode(state);
+	let currentPath = "";
+	for (const segment of segments) {
+		if (current.state.kind !== "directory") return {
+			found: false,
+			node: null
+		};
+		const child = getDirectoryChildrenView(source, state, current, currentPath).get(segment);
+		if (child === void 0) return {
+			found: false,
+			node: null
+		};
+		currentPath = joinPath(currentPath === "" ? null : currentPath, segment);
+		const childNode = state.getNode(child.nodeId);
+		if (childNode === null) return {
+			found: false,
+			node: null
+		};
+		current = childNode;
+	}
+	return {
+		found: true,
+		node: current
+	};
+}
+/**
+* 解析写路径的父目录，并保证其存在且为目录。
+*
+* @example
+* ```ts
+* const target = resolveWriteParentDirectory(source, state, "src/a.txt");
+* expect(target.parentPath).toBe("src");
+* expect(target.name).toBe("a.txt");
+* ```
+*/
+function resolveWriteParentDirectory(source, state, path) {
+	const target = resolvePathParentLookupContext(source, state, path);
+	if (target.parentNode === null) throw new VirtualPathNotFoundError(target.parentPath || path);
+	if (target.parentNode.state.kind !== "directory") throw new VirtualNotDirectoryError(target.parentPath || path);
+	return {
+		parentPath: target.parentPath,
+		name: target.name,
+		parentNode: target.parentNode
+	};
+}
+/**
+* 解析写路径对应的父目录与当前可见目标子项。
+*
+* @example
+* ```ts
+* const target = resolveWriteTargetInParent(source, state, "src/a.txt");
+* expect(target.parentPath).toBe("src");
+* ```
+*/
+function resolveWriteTargetInParent(source, state, path) {
+	const parent = resolveWriteParentDirectory(source, state, path);
+	const existing = resolveDirectoryChild(source, state, parent.parentNode, parent.parentPath, parent.name);
+	return {
+		...parent,
+		existing: existing.found ? existing : null
+	};
+}
+/**
+* 解析写路径，并要求当前目标已存在。
+*
+* @example
+* ```ts
+* const target = requireExistingWriteTarget(source, state, "a.txt");
+* expect(target.existing.child.name).toBe("a.txt");
+* ```
+*/
+function requireExistingWriteTarget(source, state, path) {
+	const target = resolveWriteTargetInParent(source, state, path);
+	if (target.existing === null) throw new VirtualPathNotFoundError(path);
+	return {
+		parentPath: target.parentPath,
+		name: target.name,
+		parentNode: target.parentNode,
+		existing: target.existing
+	};
+}
+/**
+* 解析写路径，并要求目标当前不存在。
+*
+* @example
+* ```ts
+* const target = requireMissingWriteTarget(source, state, "a.txt");
+* expect(target.name).toBe("a.txt");
+* ```
+*/
+function requireMissingWriteTarget(source, state, path) {
+	const target = resolveWriteTargetInParent(source, state, path);
+	if (target.existing !== null) throw new VirtualPathAlreadyExistsError(path);
+	return {
+		parentPath: target.parentPath,
+		name: target.name,
+		parentNode: target.parentNode
+	};
+}
+/**
+* 解析允许写入 blob/symlink 的目标。
+*
+* 若目标已存在且为目录，则抛出 `VirtualNotFileError`。
+*
+* @example
+* ```ts
+* const target = resolveLeafWriteTarget(source, state, "a.txt");
+* expect(target.name).toBe("a.txt");
+* ```
+*/
+function resolveLeafWriteTarget(source, state, path) {
+	const target = resolveWriteTargetInParent(source, state, path);
+	if (target.existing !== null && target.existing.node.state.kind === "directory") throw new VirtualNotFileError(path);
+	return {
+		parentPath: target.parentPath,
+		name: target.name,
+		parentNode: target.parentNode,
+		existing: target.existing === null ? null : {
+			child: target.existing.child,
+			node: target.existing.node
+		}
+	};
+}
+/**
+* 按路径定向解析当前叶子节点。
+*
+* 目录或不存在的路径都会返回 `null`。
+*
+* @example
+* ```ts
+* const leaf = resolveCurrentLeafAtPath(source, state, "a.txt");
+* expect(leaf?.node.state.kind).toBe("file");
+* ```
+*/
+function resolveCurrentLeafAtPath(source, state, path) {
+	const resolved = resolvePathByParentLookup(source, state, path);
+	if (!resolved.found || resolved.node === null || resolved.node.state.kind === "directory") return null;
+	return {
+		path,
+		node: resolved.node
+	};
+}
+/**
+* 解析 `rename` / `copy` 这类“已存在源 -> 目标路径”的双路径上下文。
+*
+* @example
+* ```ts
+* const transfer = resolveWriteTransfer(source, state, "a.txt", "b.txt");
+* expect(transfer.from.existing.child.name).toBe("a.txt");
+* expect(transfer.to.name).toBe("b.txt");
+* ```
+*/
+function resolveWriteTransfer(source, state, from, to) {
+	assertValidVirtualPath(from);
+	assertValidVirtualPath(to);
+	return {
+		from: requireExistingWriteTarget(source, state, from),
+		to: resolveWriteTargetInParent(source, state, to)
+	};
+}
+/**
+* 根据父目录与子项名称定向解析当前可见子项及其节点。
+*/
+function resolveDirectoryChild(source, state, parentNode, parentPath, name) {
+	if (parentNode.state.kind !== "directory") return {
+		found: false,
+		child: null,
+		node: null
+	};
+	const child = getDirectoryChildrenView(source, state, parentNode, parentPath).get(name);
+	if (child === void 0) return {
+		found: false,
+		child: null,
+		node: null
+	};
+	const childNode = state.getNode(child.nodeId);
+	if (childNode === null) return {
+		found: false,
+		child: null,
+		node: null
+	};
+	return {
+		found: true,
+		child,
+		node: childNode
+	};
+}
+/**
+* 获取目录当前视图，包含排序后的完整子项与按名查询能力。
+*
+* @example
+* ```ts
+* const view = getDirectoryChildrenView(source, state, dirNode, "");
+* expect(view.children.length).toBeGreaterThanOrEqual(0);
+* ```
+*/
+function getDirectoryChildrenView(source, state, dirNode, dirPath) {
+	const children = listDirectoryChildren(source, state, dirNode, dirPath);
+	const childrenByName = new Map(children.map((child) => [child.name, child]));
+	return {
+		children,
+		get(name) {
+			return childrenByName.get(name);
+		}
+	};
+}
+/**
+* 以“先父目录、后最后一段”的方式解析路径。
+*
+* 适用于只关心最终条目的场景，便于复用目录级定向解析 helper。
+*/
+function resolvePathByParentLookup(source, state, path) {
+	const target = resolvePathParentLookupContext(source, state, path);
+	if (target.parentNode === null) return {
+		found: false,
+		node: null
+	};
+	const resolved = resolveDirectoryChild(source, state, target.parentNode, target.parentPath, target.name);
+	if (!resolved.found) return {
+		found: false,
+		node: null
+	};
+	return {
+		found: true,
+		node: resolved.node
+	};
+}
+/**
+* 确保 origin 条目对应的 workdir 节点已懒注册
+*/
+function ensureNodeFromTreeEntry(state, entry) {
+	const id = originBackedNodeId(entry.hash);
+	if (state.getNode(id) === null) {
+		const origin = treeEntryToNodeOrigin(entry);
+		let nodeState;
+		if (entry.mode === "40000") nodeState = {
+			kind: "directory",
+			overlay: {
+				addedEntries: /* @__PURE__ */ new Map(),
+				deletedNames: /* @__PURE__ */ new Set()
+			}
+		};
+		else if (entry.mode === "120000") nodeState = {
+			kind: "symlink",
+			mode: "120000"
+		};
+		else nodeState = {
+			kind: "file",
+			mode: entry.mode === "100755" ? "100755" : "100644"
+		};
+		state.setNode({
+			id,
+			origin,
+			state: nodeState
+		});
+	}
+	return id;
+}
+/**
+* 展开目录的完整子项列表（origin + overlay 合成）
+*/
+function listDirectoryChildren(source, state, dirNode, dirPath) {
+	if (dirNode.state.kind !== "directory") throw new VirtualNotDirectoryError(dirPath);
+	let originChildren = [];
+	if (dirNode.origin.kind === "repo-tree") originChildren = readRepoTree(source, dirNode.origin.hash, dirPath).entries.map((entry) => {
+		const childNodeId = ensureNodeFromTreeEntry(state, entry);
+		return {
+			name: entry.name,
+			mode: entry.mode,
+			nodeId: childNodeId
+		};
+	});
+	const addedModes = buildAddedModes(state, dirNode);
+	return mergeDirectoryChildren(originChildren, dirNode.state.overlay, addedModes);
+}
+/**
+* 构建 overlay addedEntries 对应的 mode map
+*/
+function buildAddedModes(state, dirNode) {
+	if (dirNode.state.kind !== "directory") return /* @__PURE__ */ new Map();
+	const addedModes = /* @__PURE__ */ new Map();
+	for (const name of dirNode.state.overlay.addedEntries.keys()) {
+		const nodeId = dirNode.state.overlay.addedEntries.get(name);
+		const node = state.getNode(nodeId);
+		if (node !== null) addedModes.set(name, workdirNodeMode(node));
+	}
+	return addedModes;
+}
+function workdirNodeMode(node) {
+	if (node.state.kind === "directory") return "40000";
+	if (node.state.kind === "symlink") return "120000";
+	return node.state.mode;
+}
+function resolvePathParentLookupContext(source, state, path) {
+	assertValidVirtualPath(path);
+	const parent = parentPath(path);
+	const name = baseName(path);
+	const parentResolved = parent !== null ? resolvePath(source, state, parent) : {
+		found: true,
+		node: getRootNode(state)
+	};
+	return {
+		parentPath: parent ?? "",
+		name,
+		parentNode: parentResolved.found ? parentResolved.node : null
+	};
+}
+//#endregion
+export { ensureNodeFromTreeEntry, getDirectoryChildrenView, getRootNode, joinChildPath, listDirectoryChildren, requireExistingWriteTarget, requireMissingWriteTarget, resolveCurrentLeafAtPath, resolveLeafWriteTarget, resolvePath, resolveWriteTransfer };

package/dist/workdir/workdir-transaction.mjs

@@ -0,0 +1,115 @@
+import { createNodeId } from "./ids.mjs";
+import { readRepoBlobContent } from "./origin.mjs";
+import { overlayBindEntry } from "./overlay.mjs";
+import { listDirectoryChildren } from "./workdir-path.mjs";
+import { observeListedDirectoryChild } from "./directory-view.mjs";
+import { cloneWorkdirNodeForCopy } from "./nodes.mjs";
+//#region src/workdir/workdir-transaction.ts
+/**
+* Virtual Workdir 写事务与节点辅助函数
+*
+* 从 workdir.ts 提取，降低编排层复杂度：
+* - 写操作事务生命周期管理
+* - 父目录 overlay 更新
+* - 节点状态统计（stat）
+* - 递归节点图克隆（copy）
+*/
+/**
+* 在 state store 事务边界内执行写操作。
+*
+* @param state - workdir 内部状态存储
+* @param onBeforeCommit - 提交前回调（在事务 callback 内执行）；可为 null
+* @param onCommitted - 提交后回调（在事务 callback 外执行）
+* @param fn - 实际写入逻辑
+*/
+function runInWriteTransaction(state, onBeforeCommit, onCommitted, fn) {
+	const result = onBeforeCommit === null ? state.transact(fn) : state.transact(() => {
+		const innerResult = fn();
+		onBeforeCommit();
+		return innerResult;
+	});
+	onCommitted();
+	return result;
+}
+/**
+* 更新父节点的 overlay（创建新节点对象替代 Map 中的旧引用）
+*/
+function updateParentOverlay(state, parentId, newOverlay) {
+	const parentNode = state.getNode(parentId);
+	if (parentNode === null || parentNode.state.kind !== "directory") throw new Error("updateParentOverlay: parent is not a directory");
+	state.setNode({
+		...parentNode,
+		state: {
+			...parentNode.state,
+			overlay: newOverlay
+		}
+	});
+}
+/**
+* 获取节点统计信息（用于 workdir.stat() 实现）
+*/
+function statNode(source, node, path) {
+	if (node.state.kind === "directory") return statDirectoryNode(node);
+	if (node.state.kind === "symlink") {
+		const hash = node.origin.kind === "repo-blob" ? node.origin.hash : null;
+		let size = 0;
+		if (node.state.target !== void 0) size = node.state.target.length;
+		else if (hash !== null) size = readRepoBlobContent(source, hash, path).length;
+		return {
+			kind: "symlink",
+			mode: "120000",
+			size,
+			hash
+		};
+	}
+	const hash = node.origin.kind === "repo-blob" ? node.origin.hash : null;
+	let size = 0;
+	if (node.state.content !== void 0) size = node.state.content.length;
+	else if (hash !== null) size = readRepoBlobContent(source, hash, path).length;
+	return {
+		kind: "blob",
+		mode: node.state.mode,
+		size,
+		hash
+	};
+}
+/**
+* 目录节点统计信息（无大小，hash 取 origin）
+*/
+function statDirectoryNode(node) {
+	return {
+		kind: "tree",
+		mode: "40000",
+		size: 0,
+		hash: node.origin.kind === "repo-tree" ? node.origin.hash : null
+	};
+}
+/**
+* 递归克隆节点图（用于 copy 语义）。
+*
+* 为新节点分配新身份，避免 copy 后源与目标共享子节点身份。
+*/
+function cloneNodeGraphForCopy(source, state, node, path) {
+	const newNodeId = createNodeId();
+	const cloned = cloneWorkdirNodeForCopy(node, newNodeId);
+	state.setNode(cloned);
+	if (node.state.kind !== "directory" || cloned.state.kind !== "directory") return newNodeId;
+	let overlay = cloned.state.overlay;
+	const children = listDirectoryChildren(source, state, node, path);
+	for (const child of children) {
+		const observedChild = observeListedDirectoryChild(state, path, child);
+		if (observedChild === null) continue;
+		const clonedChildId = cloneNodeGraphForCopy(source, state, observedChild.node, observedChild.path);
+		overlay = overlayBindEntry(overlay, observedChild.name, clonedChildId);
+	}
+	state.setNode({
+		...cloned,
+		state: {
+			kind: "directory",
+			overlay
+		}
+	});
+	return newNodeId;
+}
+//#endregion
+export { cloneNodeGraphForCopy, runInWriteTransaction, statDirectoryNode, statNode, updateParentOverlay };

package/dist/workdir/workdir.d.mts

@@ -0,0 +1,30 @@
+import { ObjectDatabase } from "../core/types/odb.mjs";
+import { CreateVirtualWorkdirOptions, VirtualWorkdir } from "./core.mjs";
+import { VirtualWorkdirStateStore } from "./state-store.mjs";
+
+//#region src/workdir/workdir.d.ts
+/**
+ * 基于 ObjectDatabase 创建 VirtualWorkdir
+ *
+ * @example
+ * ```ts
+ * const repo = createMemoryRepository();
+ * const tree = repo.createTree([]);
+ * const workdir = createVirtualWorkdir(repo.objects, { baseTree: tree });
+ * expect(workdir.readdir()).toEqual([]);
+ * ```
+ */
+declare function createVirtualWorkdir(source: ObjectDatabase, options: CreateVirtualWorkdirOptions): VirtualWorkdir;
+/**
+ * 基于已有状态存储打开 VirtualWorkdir
+ *
+ * @example
+ * ```ts
+ * const store = createVirtualWorkdirMemoryStateStore(tree);
+ * const workdir = openVirtualWorkdir(repo.objects, store);
+ * expect(workdir.baseTree).toBe(tree);
+ * ```
+ */
+declare function openVirtualWorkdir(source: ObjectDatabase, state: VirtualWorkdirStateStore): VirtualWorkdir;
+//#endregion
+export { createVirtualWorkdir, openVirtualWorkdir };