nano-git 0.2.0 → 0.2.1

package/dist/core/errors.d.mts

@@ -120,5 +120,75 @@ declare class TransactionError extends GitError {
 declare class PreconditionCheckError extends GitError {
   constructor(message: string);
 }
+/**
+ * 虚拟路径未找到错误
+ *
+ * 当操作的路径在 session 中不存在时抛出。
+ */
+declare class VirtualPathNotFoundError extends GitError {
+  /** 不存在的路径 */
+  path: string;
+  constructor(path: string, message?: string);
+}
+/**
+ * 虚拟路径已存在错误
+ *
+ * 当创建的路径已在 session 中存在时抛出。
+ */
+declare class VirtualPathAlreadyExistsError extends GitError {
+  /** 已存在的路径 */
+  path: string;
+  constructor(path: string, message?: string);
+}
+/**
+ * 非目录错误
+ *
+ * 当期望路径为目录但实际不是时抛出。
+ */
+declare class VirtualNotDirectoryError extends GitError {
+  /** 路径 */
+  path: string;
+  constructor(path: string, message?: string);
+}
+/**
+ * 非文件错误
+ *
+ * 当期望路径为文件但实际不是时抛出。
+ */
+declare class VirtualNotFileError extends GitError {
+  /** 路径 */
+  path: string;
+  constructor(path: string, message?: string);
+}
+/**
+ * 非符号链接错误
+ *
+ * 当期望路径为符号链接但实际不是时抛出。
+ */
+declare class VirtualNotSymlinkError extends GitError {
+  /** 路径 */
+  path: string;
+  constructor(path: string, message?: string);
+}
+/**
+ * 虚拟工作目录 origin 不可用错误
+ *
+ * 当操作的路径在 repo 中的 origin 对象缺失时抛出（弱保证场景）。
+ */
+declare class VirtualOriginUnavailableError extends GitError {
+  /** 路径 */
+  path: string;
+  constructor(path: string, message?: string);
+}
+/**
+ * 虚拟工作目录 revert 不支持错误
+ *
+ * 当对纯新建节点调用 revert 时抛出，因为其没有可恢复的 origin。
+ */
+declare class VirtualRevertNotSupportedError extends GitError {
+  /** 路径 */
+  path: string;
+  constructor(path: string, message?: string);
+}
 //#endregion
-export { CircularReferenceError, DeltaError, GitError, InvalidObjectError, InvalidPackError, InvalidSHA1Error, ObjectNotFoundError, PackError, PackIndexError, PreconditionCheckError, RefNotFoundError, RepositoryError, TransactionError };
+export { CircularReferenceError, DeltaError, GitError, InvalidObjectError, InvalidPackError, InvalidSHA1Error, ObjectNotFoundError, PackError, PackIndexError, PreconditionCheckError, RefNotFoundError, RepositoryError, TransactionError, VirtualNotDirectoryError, VirtualNotFileError, VirtualNotSymlinkError, VirtualOriginUnavailableError, VirtualPathAlreadyExistsError, VirtualPathNotFoundError, VirtualRevertNotSupportedError };

package/dist/core/errors.mjs

@@ -164,5 +164,103 @@ var PreconditionCheckError = class extends GitError {
 		this.name = "PreconditionCheckError";
 	}
 };
+/**
+* 虚拟路径未找到错误
+*
+* 当操作的路径在 session 中不存在时抛出。
+*/
+var VirtualPathNotFoundError = class extends GitError {
+	/** 不存在的路径 */
+	path;
+	constructor(path, message) {
+		super(message ?? `Virtual path not found: ${path}`);
+		this.name = "VirtualPathNotFoundError";
+		this.path = path;
+	}
+};
+/**
+* 虚拟路径已存在错误
+*
+* 当创建的路径已在 session 中存在时抛出。
+*/
+var VirtualPathAlreadyExistsError = class extends GitError {
+	/** 已存在的路径 */
+	path;
+	constructor(path, message) {
+		super(message ?? `Virtual path already exists: ${path}`);
+		this.name = "VirtualPathAlreadyExistsError";
+		this.path = path;
+	}
+};
+/**
+* 非目录错误
+*
+* 当期望路径为目录但实际不是时抛出。
+*/
+var VirtualNotDirectoryError = class extends GitError {
+	/** 路径 */
+	path;
+	constructor(path, message) {
+		super(message ?? `Virtual path is not a directory: ${path}`);
+		this.name = "VirtualNotDirectoryError";
+		this.path = path;
+	}
+};
+/**
+* 非文件错误
+*
+* 当期望路径为文件但实际不是时抛出。
+*/
+var VirtualNotFileError = class extends GitError {
+	/** 路径 */
+	path;
+	constructor(path, message) {
+		super(message ?? `Virtual path is not a file: ${path}`);
+		this.name = "VirtualNotFileError";
+		this.path = path;
+	}
+};
+/**
+* 非符号链接错误
+*
+* 当期望路径为符号链接但实际不是时抛出。
+*/
+var VirtualNotSymlinkError = class extends GitError {
+	/** 路径 */
+	path;
+	constructor(path, message) {
+		super(message ?? `Virtual path is not a symlink: ${path}`);
+		this.name = "VirtualNotSymlinkError";
+		this.path = path;
+	}
+};
+/**
+* 虚拟工作目录 origin 不可用错误
+*
+* 当操作的路径在 repo 中的 origin 对象缺失时抛出（弱保证场景）。
+*/
+var VirtualOriginUnavailableError = class extends GitError {
+	/** 路径 */
+	path;
+	constructor(path, message) {
+		super(message ?? `Virtual origin unavailable for: ${path}`);
+		this.name = "VirtualOriginUnavailableError";
+		this.path = path;
+	}
+};
+/**
+* 虚拟工作目录 revert 不支持错误
+*
+* 当对纯新建节点调用 revert 时抛出，因为其没有可恢复的 origin。
+*/
+var VirtualRevertNotSupportedError = class extends GitError {
+	/** 路径 */
+	path;
+	constructor(path, message) {
+		super(message ?? `Virtual revert not supported for purely new path: ${path}`);
+		this.name = "VirtualRevertNotSupportedError";
+		this.path = path;
+	}
+};
 //#endregion
-export { CircularReferenceError, DeltaError, GitError, InvalidObjectError, InvalidPackError, InvalidSHA1Error, ObjectNotFoundError, PackError, PackIndexError, PreconditionCheckError, RefNotFoundError, RepositoryError, TransactionError };
+export { CircularReferenceError, DeltaError, GitError, InvalidObjectError, InvalidPackError, InvalidSHA1Error, ObjectNotFoundError, PackError, PackIndexError, PreconditionCheckError, RefNotFoundError, RepositoryError, TransactionError, VirtualNotDirectoryError, VirtualNotFileError, VirtualNotSymlinkError, VirtualOriginUnavailableError, VirtualPathAlreadyExistsError, VirtualPathNotFoundError, VirtualRevertNotSupportedError };

package/dist/errors.d.mts

@@ -1,2 +1,2 @@
-import { CircularReferenceError, DeltaError, GitError, InvalidObjectError, InvalidPackError, InvalidSHA1Error, ObjectNotFoundError, PackError, PackIndexError, PreconditionCheckError, RefNotFoundError, RepositoryError, TransactionError } from "./core/errors.mjs";
-export { CircularReferenceError, DeltaError, GitError, InvalidObjectError, InvalidPackError, InvalidSHA1Error, ObjectNotFoundError, PackError, PackIndexError, PreconditionCheckError, RefNotFoundError, RepositoryError, TransactionError };
+import { CircularReferenceError, DeltaError, GitError, InvalidObjectError, InvalidPackError, InvalidSHA1Error, ObjectNotFoundError, PackError, PackIndexError, PreconditionCheckError, RefNotFoundError, RepositoryError, TransactionError, VirtualNotDirectoryError, VirtualNotFileError, VirtualNotSymlinkError, VirtualOriginUnavailableError, VirtualPathAlreadyExistsError, VirtualPathNotFoundError, VirtualRevertNotSupportedError } from "./core/errors.mjs";
+export { CircularReferenceError, DeltaError, GitError, InvalidObjectError, InvalidPackError, InvalidSHA1Error, ObjectNotFoundError, PackError, PackIndexError, PreconditionCheckError, RefNotFoundError, RepositoryError, TransactionError, VirtualNotDirectoryError, VirtualNotFileError, VirtualNotSymlinkError, VirtualOriginUnavailableError, VirtualPathAlreadyExistsError, VirtualPathNotFoundError, VirtualRevertNotSupportedError };

package/dist/errors.mjs

@@ -1,2 +1,2 @@
-import { CircularReferenceError, DeltaError, GitError, InvalidObjectError, InvalidPackError, InvalidSHA1Error, ObjectNotFoundError, PackError, PackIndexError, PreconditionCheckError, RefNotFoundError, RepositoryError, TransactionError } from "./core/errors.mjs";
-export { CircularReferenceError, DeltaError, GitError, InvalidObjectError, InvalidPackError, InvalidSHA1Error, ObjectNotFoundError, PackError, PackIndexError, PreconditionCheckError, RefNotFoundError, RepositoryError, TransactionError };
+import { CircularReferenceError, DeltaError, GitError, InvalidObjectError, InvalidPackError, InvalidSHA1Error, ObjectNotFoundError, PackError, PackIndexError, PreconditionCheckError, RefNotFoundError, RepositoryError, TransactionError, VirtualNotDirectoryError, VirtualNotFileError, VirtualNotSymlinkError, VirtualOriginUnavailableError, VirtualPathAlreadyExistsError, VirtualPathNotFoundError, VirtualRevertNotSupportedError } from "./core/errors.mjs";
+export { CircularReferenceError, DeltaError, GitError, InvalidObjectError, InvalidPackError, InvalidSHA1Error, ObjectNotFoundError, PackError, PackIndexError, PreconditionCheckError, RefNotFoundError, RepositoryError, TransactionError, VirtualNotDirectoryError, VirtualNotFileError, VirtualNotSymlinkError, VirtualOriginUnavailableError, VirtualPathAlreadyExistsError, VirtualPathNotFoundError, VirtualRevertNotSupportedError };

package/dist/log/index.d.mts

@@ -0,0 +1,3 @@
+import { CommitWalkOrder, LogEntry, LogWalkOptions } from "./types.mjs";
+import { walkLogEntries } from "./walk.mjs";
+export { type CommitWalkOrder, type LogEntry, type LogWalkOptions, walkLogEntries };

package/dist/log/index.mjs

@@ -0,0 +1,2 @@
+import { walkLogEntries } from "./walk.mjs";
+export { walkLogEntries };

package/dist/log/types.d.mts

@@ -0,0 +1,71 @@
+import { GitCommit, SHA1 } from "../core/types.mjs";
+
+//#region src/log/types.d.ts
+/** 单条提交日志条目 */
+interface LogEntry {
+  /** 提交哈希 */
+  readonly hash: SHA1;
+  /** 解码后的提交对象 */
+  readonly commit: GitCommit;
+}
+/** 提交遍历排序策略 */
+type CommitWalkOrder = "date" | "topo";
+/** 日志遍历选项 */
+interface LogWalkOptions {
+  /**
+   * 遍历起点哈希列表。
+   *
+   * 为空时立即返回空结果。
+   * 调用方应自行将 ref 名称（如 HEAD、branch names）解析为 SHA1。
+   */
+  readonly from?: SHA1[];
+  /**
+   * 排除哈希列表（及其所有祖先）。
+   *
+   * 等价于 `git log <from> ^<exclude>` 或 `<exclude>..<from>` 范围语法。
+   * 被排除的提交及其全部祖先不会出现在结果中。
+   */
+  readonly exclude?: SHA1[];
+  /**
+   * 最多输出的提交数量。
+   *
+   * 等价于 `git log --max-count=<n>`。
+   */
+  readonly maxCount?: number;
+  /**
+   * 跳过开头 N 个提交再输出。
+   *
+   * 等价于 `git log --skip=<n>`。
+   */
+  readonly skip?: number;
+  /**
+   * 提交排序策略。
+   *
+   * - `"date"`（默认）：按提交时间降序。时间相同时不保证严格拓扑序，
+   *   但在实践中 parent 的 timestamp 通常 ≤ child，结果与 git log 默认一致。
+   * - `"topo"`：严格拓扑排序，所有子提交在父提交之前输出。
+   *   同层级的提交按时间戳降序。需要预先收集全部提交，额外开销较大。
+   */
+  readonly order?: CommitWalkOrder;
+  /**
+   * 仅输出此 Unix 时间戳（含）之后的提交。
+   *
+   * 等价于 `git log --since=<timestamp>`。
+   */
+  readonly since?: number;
+  /**
+   * 仅输出此 Unix 时间戳（含）之前的提交。
+   *
+   * 等价于 `git log --until=<timestamp>`。
+   */
+  readonly until?: number;
+  /**
+   * 仅沿第一条父链行走。
+   *
+   * 启用后只追踪每个提交的第一个 parent，忽略 merge 的其他分支。
+   * 等价于 `git log --first-parent`。
+   */
+  readonly firstParent?: boolean;
+}
+//#endregion
+export { CommitWalkOrder, LogEntry, LogWalkOptions };

package/dist/log/walk.d.mts

@@ -0,0 +1,37 @@
+import { ObjectSource } from "../core/types/odb.mjs";
+import { LogEntry, LogWalkOptions } from "./types.mjs";
+
+//#region src/log/walk.d.ts
+/**
+ * 遍历提交历史日志
+ *
+ * 从指定的起点哈希出发，沿 parent 链回溯，按指定排序策略输出提交。
+ * 不涉及 ref 解析——调用方需自行将 ref 名称解析为 SHA1。
+ *
+ * @param source - 对象源（通常是 `Repository.objects`）
+ * @param options - 遍历选项
+ * @returns 按序输出的提交日志条目生成器
+ *
+ * @example
+ * ```ts
+ * const headHash = resolveRefHash(repo.refs, "HEAD")!;
+ * for (const entry of walkLogEntries(repo.objects, { from: [headHash], maxCount: 5 })) {
+ *   console.log(entry.hash, entry.commit.subject);
+ * }
+ * ```
+ *
+ * @example
+ * ```ts
+ * // 等价于 git log --oneline --since=1600000000 --until=1700000000
+ * for (const entry of walkLogEntries(repo.objects, {
+ *   from: [headHash],
+ *   since: 1600000000,
+ *   until: 1700000000,
+ * })) {
+ *   console.log(entry.hash.slice(0, 7), entry.commit.message.split("\n")[0]);
+ * }
+ * ```
+ */
+declare function walkLogEntries(source: ObjectSource, options?: LogWalkOptions): Generator<LogEntry, void, undefined>;
+//#endregion
+export { walkLogEntries };

package/dist/log/walk.mjs

@@ -0,0 +1,274 @@
+import { tryReadObject } from "../objects/raw.mjs";
+//#region src/log/walk.ts
+/**
+* 提交日志遍历核心实现
+*
+* 提供 Generator 风格的 `walkLogEntries`，支持按提交时间降序
+* 或严格拓扑序遍历提交历史。
+*
+* @example
+* ```ts
+* // 从 HEAD 开始遍历最近 10 条提交
+* const headHash = resolveRefHash(repo.refs, "HEAD")!;
+* for (const entry of walkLogEntries(repo.objects, { from: [headHash], maxCount: 10 })) {
+*   console.log(entry.hash, entry.commit.message);
+* }
+*
+* // 等价于 git log main..feature
+* const featureHash = resolveRefHash(repo.refs, "refs/heads/feature")!;
+* const mainHash = resolveRefHash(repo.refs, "refs/heads/main")!;
+* for (const entry of walkLogEntries(repo.objects, { from: [featureHash], exclude: [mainHash] })) {
+*   console.log(entry.hash, entry.commit.message);
+* }
+* ```
+*/
+var MaxHeapByTimestamp = class {
+	heap = [];
+	get size() {
+		return this.heap.length;
+	}
+	push(entry) {
+		this.heap.push(entry);
+		this.siftUp(this.heap.length - 1);
+	}
+	pop() {
+		if (this.heap.length === 0) return void 0;
+		const top = this.heap[0];
+		const bottom = this.heap.pop();
+		if (this.heap.length > 0) {
+			this.heap[0] = bottom;
+			this.siftDown(0);
+		}
+		return top;
+	}
+	siftUp(idx) {
+		const heap = this.heap;
+		while (idx > 0) {
+			const parent = idx - 1 >> 1;
+			if (heap[parent].commit.committer.timestamp >= heap[idx].commit.committer.timestamp) break;
+			[heap[parent], heap[idx]] = [heap[idx], heap[parent]];
+			idx = parent;
+		}
+	}
+	siftDown(idx) {
+		const heap = this.heap;
+		const end = heap.length;
+		while (true) {
+			let largest = idx;
+			const left = (idx << 1) + 1;
+			const right = left + 1;
+			if (left < end && heap[left].commit.committer.timestamp > heap[largest].commit.committer.timestamp) largest = left;
+			if (right < end && heap[right].commit.committer.timestamp > heap[largest].commit.committer.timestamp) largest = right;
+			if (largest === idx) break;
+			[heap[idx], heap[largest]] = [heap[largest], heap[idx]];
+			idx = largest;
+		}
+	}
+};
+/**
+* 递归标记排除提交及其所有祖先
+*/
+function markExcluded(source, hash, excluded) {
+	const stack = [hash];
+	while (stack.length > 0) {
+		const current = stack.pop();
+		if (excluded.has(current)) continue;
+		excluded.add(current);
+		const obj = tryReadObject(source, current);
+		if (obj?.type === "commit") {
+			for (const parent of obj.parents) if (!excluded.has(parent)) stack.push(parent);
+		}
+	}
+}
+/**
+* 按提交时间降序遍历提交历史
+*
+* 使用最大堆按时间戳排序，每次弹出最新提交后将其 parent 入堆。
+* 可配合 firstParent、since、until、skip、maxCount 等过滤条件。
+*/
+function* walkByDate(source, from, excluded, firstParent, skip, maxCount, since, until) {
+	const queue = new MaxHeapByTimestamp();
+	const seen = /* @__PURE__ */ new Set();
+	const visited = /* @__PURE__ */ new Set();
+	for (const hash of from) {
+		if (excluded.has(hash) || seen.has(hash)) continue;
+		const obj = tryReadObject(source, hash);
+		if (obj?.type !== "commit") continue;
+		seen.add(hash);
+		queue.push({
+			hash,
+			commit: obj
+		});
+	}
+	let skipped = 0;
+	let emitted = 0;
+	while (queue.size > 0) {
+		if (maxCount !== void 0 && emitted >= maxCount) break;
+		const entry = queue.pop();
+		if (visited.has(entry.hash)) continue;
+		if (excluded.has(entry.hash)) continue;
+		if (since !== void 0 && entry.commit.committer.timestamp < since) continue;
+		if (until !== void 0 && entry.commit.committer.timestamp > until) {
+			enqueueParents(source, entry.commit.parents, firstParent, excluded, seen, visited, queue);
+			continue;
+		}
+		if (skipped < skip) {
+			skipped++;
+			visited.add(entry.hash);
+			enqueueParents(source, entry.commit.parents, firstParent, excluded, seen, visited, queue);
+			continue;
+		}
+		visited.add(entry.hash);
+		emitted++;
+		yield {
+			hash: entry.hash,
+			commit: entry.commit
+		};
+		enqueueParents(source, entry.commit.parents, firstParent, excluded, seen, visited, queue);
+	}
+}
+/**
+* 将提交的 parent 批量入堆
+*/
+function enqueueParents(source, parents, firstParent, excluded, seen, visited, queue) {
+	const targetParents = firstParent && parents.length > 0 ? [parents[0]] : parents;
+	for (const parentHash of targetParents) {
+		if (seen.has(parentHash) || excluded.has(parentHash)) continue;
+		seen.add(parentHash);
+		const obj = tryReadObject(source, parentHash);
+		if (obj?.type !== "commit") continue;
+		queue.push({
+			hash: parentHash,
+			commit: obj
+		});
+	}
+}
+/**
+* 生成严格拓扑序（子提交先于父提交）的提交迭代器
+*
+* 实现 Kahn 算法：
+* 1. 收集所有起点可达的提交，构建 parent→children 映射
+* 2. 统计每个提交的未输出子提交数（childCount）
+* 3. 将 childCount === 0 的提交入堆（同层按时间戳降序）
+* 4. 每次弹出堆顶输出，递减其 parent 的 childCount
+* 5. parent 的 childCount 归零时入堆
+*/
+function* walkTopo(source, from, excluded, firstParent, skip, maxCount, since, until) {
+	const commits = /* @__PURE__ */ new Map();
+	const children = /* @__PURE__ */ new Map();
+	const stack = [...from];
+	while (stack.length > 0) {
+		const hash = stack.pop();
+		if (commits.has(hash) || excluded.has(hash)) continue;
+		const obj = tryReadObject(source, hash);
+		if (obj?.type !== "commit") continue;
+		commits.set(hash, obj);
+		if (!children.has(hash)) children.set(hash, []);
+		const targetParents = firstParent && obj.parents.length > 0 ? [obj.parents[0]] : obj.parents;
+		for (const parentHash of targetParents) {
+			if (commits.has(parentHash) || excluded.has(parentHash)) continue;
+			if (!children.has(parentHash)) children.set(parentHash, []);
+			children.get(parentHash).push(hash);
+			stack.push(parentHash);
+		}
+	}
+	if (commits.size === 0) return;
+	const childCount = /* @__PURE__ */ new Map();
+	const pq = new MaxHeapByTimestamp();
+	for (const hash of commits.keys()) {
+		const count = children.get(hash)?.length ?? 0;
+		childCount.set(hash, count);
+		if (count === 0) pq.push({
+			hash,
+			commit: commits.get(hash)
+		});
+	}
+	let skipped = 0;
+	let emitted = 0;
+	while (pq.size > 0) {
+		if (maxCount !== void 0 && emitted >= maxCount) break;
+		const entry = pq.pop();
+		if (since !== void 0 && entry.commit.committer.timestamp < since) {
+			decrementParentCounts(entry.commit.parents, firstParent, childCount, commits, pq);
+			continue;
+		}
+		if (until !== void 0 && entry.commit.committer.timestamp > until) {
+			decrementParentCounts(entry.commit.parents, firstParent, childCount, commits, pq);
+			continue;
+		}
+		if (skipped < skip) {
+			skipped++;
+			decrementParentCounts(entry.commit.parents, firstParent, childCount, commits, pq);
+			continue;
+		}
+		emitted++;
+		yield {
+			hash: entry.hash,
+			commit: entry.commit
+		};
+		decrementParentCounts(entry.commit.parents, firstParent, childCount, commits, pq);
+	}
+}
+/**
+* 递减 parent 的 childCount，归零时入堆
+*/
+function decrementParentCounts(parents, firstParent, childCount, commits, pq) {
+	const targetParents = firstParent && parents.length > 0 ? [parents[0]] : parents;
+	for (const parentHash of targetParents) {
+		const count = childCount.get(parentHash);
+		if (count === void 0) continue;
+		const newCount = count - 1;
+		childCount.set(parentHash, newCount);
+		if (newCount === 0) {
+			const parentCommit = commits.get(parentHash);
+			if (parentCommit) pq.push({
+				hash: parentHash,
+				commit: parentCommit
+			});
+		}
+	}
+}
+/**
+* 遍历提交历史日志
+*
+* 从指定的起点哈希出发，沿 parent 链回溯，按指定排序策略输出提交。
+* 不涉及 ref 解析——调用方需自行将 ref 名称解析为 SHA1。
+*
+* @param source - 对象源（通常是 `Repository.objects`）
+* @param options - 遍历选项
+* @returns 按序输出的提交日志条目生成器
+*
+* @example
+* ```ts
+* const headHash = resolveRefHash(repo.refs, "HEAD")!;
+* for (const entry of walkLogEntries(repo.objects, { from: [headHash], maxCount: 5 })) {
+*   console.log(entry.hash, entry.commit.subject);
+* }
+* ```
+*
+* @example
+* ```ts
+* // 等价于 git log --oneline --since=1600000000 --until=1700000000
+* for (const entry of walkLogEntries(repo.objects, {
+*   from: [headHash],
+*   since: 1600000000,
+*   until: 1700000000,
+* })) {
+*   console.log(entry.hash.slice(0, 7), entry.commit.message.split("\n")[0]);
+* }
+* ```
+*/
+function walkLogEntries(source, options = {}) {
+	const { from = [], exclude = [], skip: skipCount = 0, order = "date", since, until, firstParent = false, maxCount } = options;
+	if (from.length === 0) return emptyGenerator();
+	const excluded = /* @__PURE__ */ new Set();
+	for (const hash of exclude) markExcluded(source, hash, excluded);
+	if (order === "topo") return walkTopo(source, from, excluded, firstParent, skipCount, maxCount, since, until);
+	return walkByDate(source, from, excluded, firstParent, skipCount, maxCount, since, until);
+}
+/** 返回一个空的 Generator（不产生任何值，直接 done） */
+function emptyGenerator() {
+	return [][Symbol.iterator]();
+}
+//#endregion
+export { walkLogEntries };

package/dist/workdir/change-log.mjs

@@ -0,0 +1,63 @@
+//#region src/workdir/change-log.ts
+/**
+* 创建空的变更日志
+*
+* @example
+* ```ts
+* const log = createVirtualChangeLog();
+* log.append({ op: "add", path: "a.txt" });
+* expect(log.toVirtualChanges()).toEqual([{ path: "a.txt", type: "add" }]);
+* ```
+*/
+function createVirtualChangeLog() {
+	const records = [];
+	return {
+		append(record) {
+			records.push(record);
+		},
+		clear() {
+			records.length = 0;
+		},
+		snapshot() {
+			return records.slice();
+		},
+		toVirtualChanges() {
+			const out = [];
+			for (const record of records) {
+				const mapped = mapInternalToVirtual(record);
+				if (mapped !== null) out.push(mapped);
+			}
+			return out;
+		}
+	};
+}
+function mapInternalToVirtual(record) {
+	switch (record.op) {
+		case "add": return {
+			path: record.path,
+			type: "add"
+		};
+		case "modify": return {
+			path: record.path,
+			type: "modify"
+		};
+		case "delete": return {
+			path: record.path,
+			type: "delete"
+		};
+		case "rename": return {
+			path: record.to,
+			type: "rename",
+			oldPath: record.from
+		};
+		case "copy": return {
+			path: record.to,
+			type: "copy",
+			oldPath: record.from
+		};
+		case "revert": return null;
+		default: return record;
+	}
+}
+//#endregion
+export { createVirtualChangeLog };