nano-git 0.2.3 → 0.3.1

package/dist/workdir/session-internal.mjs

@@ -1,17 +1,31 @@
-import { VirtualNotDirectoryError } from "../core/errors.mjs";
+import { VirtualNotDirectoryError, VirtualNotFileError, VirtualPathAlreadyExistsError, VirtualPathNotFoundError } from "../core/errors.mjs";
 import { VIRTUAL_ROOT_NODE_ID, originBackedNodeId } from "./ids.mjs";
 import { mergeDirectoryChildren } from "./overlay.mjs";
 import { readRepoTree, treeEntryToNodeOrigin } from "./origin.mjs";
-import { assertValidVirtualPath, joinPath, splitPathSegments } from "./path.mjs";
+import { assertValidVirtualPath, baseName, joinPath, parentPath, splitPathSegments } from "./path.mjs";
 //#region src/workdir/session-internal.ts
 /**
 * Virtual Workdir session 内部共享逻辑
 *
 * 供 session.ts 与 write-tree.ts 复用：
-* - 路径解析（resolvePath）
-* - 目录子项展开（listDirectoryChildren）
+* - 路径解析（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 session is missing root node");
@@ -30,7 +44,7 @@ function resolvePath(source, state, path) {
 			found: false,
 			node: null
 		};
-		const child = listDirectoryChildren(source, state, current, currentPath).find((c) => c.name === segment);
+		const child = getDirectoryChildrenView(source, state, current, currentPath).get(segment);
 		if (child === void 0) return {
 			found: false,
 			node: null
@@ -49,29 +63,208 @@ function resolvePath(source, state, path) {
 	};
 }
 /**
-* 根据父节点与子条目名解析子节点
+* 解析写路径的父目录，并保证其存在且为目录。
+*
+* @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 resolveChild(source, state, parentNode, parentPath, name) {
+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 = listDirectoryChildren(source, state, parentNode, parentPath).find((c) => c.name === name);
+	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 条目对应的 session 节点已懒注册
 */
 function ensureNodeFromTreeEntry(state, entry) {
@@ -137,5 +330,19 @@ function sessionNodeMode(node) {
 	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 { listDirectoryChildren, resolveChild, resolvePath };
+export { ensureNodeFromTreeEntry, getDirectoryChildrenView, getRootNode, joinChildPath, listDirectoryChildren, requireExistingWriteTarget, requireMissingWriteTarget, resolveCurrentLeafAtPath, resolveLeafWriteTarget, resolvePath, resolveWriteTransfer };

package/dist/workdir/session-transaction.mjs

@@ -0,0 +1,115 @@
+import { createNodeId } from "./ids.mjs";
+import { overlayBindEntry } from "./overlay.mjs";
+import { cloneSessionNodeForCopy } from "./nodes.mjs";
+import { readRepoBlobContent } from "./origin.mjs";
+import { listDirectoryChildren } from "./session-internal.mjs";
+import { observeListedDirectoryChild } from "./directory-view.mjs";
+//#region src/workdir/session-transaction.ts
+/**
+* Virtual Workdir 事务包装与会话辅助函数
+*
+* 从 session.ts 提取，降低编排层的复杂度：
+* - 写操作事务生命周期管理
+* - 父目录 overlay 更新
+* - 节点状态统计（stat）
+* - 递归节点图克隆（copy）
+*/
+/**
+* 在 state store 事务边界内执行写操作。
+*
+* @param state - session 内部状态存储
+* @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
+		}
+	});
+}
+/**
+* 获取节点统计信息（用于 session.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 = cloneSessionNodeForCopy(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 };