nano-git 0.1.0 → 0.2.1

package/README.md

@@ -8,13 +8,14 @@
 - ✅ **SHA-1 哈希计算** — 与 Git 完全兼容的对象哈希
 - ✅ **Git 对象模型** — 支持 blob、tree、commit、tag 四种对象类型
 - ✅ **对象序列化/反序列化** — 完整的二进制格式支持
-- ✅ **对象存储** — 文件系统存储和内存存储两种模式
+- ✅ **对象存储** — 文件系统存储、内存存储和 SQLite 存储三种模式
 - ✅ **Packfile 支持** — 读取、写入、索引生成、delta 编解码
 - ✅ **引用管理** — refs 验证、解析、存储（文件系统 + 内存）
 - ✅ **仓库 API** — 类似 Git plumbing 命令的高层接口（init、hash-object、cat-file、commit-tree、update-ref 等）
 - ✅ **增量 Tree Patch** — 不经暂存区直接修改目录结构（`patchTree`、`readTree`、`walkTree`）
 - ✅ **可达性遍历与 GC** — 基于 refs 的可达对象收集、repack、gc
 - ✅ **Smart HTTP 传输** — 基于 Bun fetch 的 Git 协议客户端，支持 `fetch()`/`push()` 与完整的 Import Session 物化流程
+- ✅ **远端查询 API** — 将 refs 快照、`object-info` 等纯远端能力独立出 `Repository`
 - ✅ **类型安全** — 完整的 TypeScript 类型定义
 - ✅ **Reference Transaction** — 批量 ref 更新的原子性保障，支持 Hooks 回调与自动回滚
 
@@ -55,6 +56,22 @@ await repo.fetch("https://github.com/user/repo.git");
 console.log(repo.listBranches());
 ```
 
+### 查询远端 refs / object-info
+
+```typescript
+import { createHttpRemote } from "nano-git/remote/http";
+
+const remote = createHttpRemote({
+  url: "https://github.com/user/repo.git",
+});
+
+const snapshot = await remote.readRefAdvertisement();
+console.log(snapshot.defaultBranch);
+
+const info = await remote.fetchObjectInfo(["95d09f2b10159347eece71399a7e2e907ea3df4f"]);
+console.log(info.objects[0]?.size);
+```
+
 ### 内存仓库完整工作流
 
 ```typescript
@@ -138,6 +155,43 @@ repo.updateRef("refs/heads/main", commitHash);
 
 `openRepository()` 默认会同时读取 `.git/objects/` 下的 loose objects 和 `.git/objects/pack/` 下的 packed objects，因此可以直接打开经过 `git gc` 或 `git repack` 的真实仓库（包括裸仓库）。搭配 `initRepository()` 的第二个参数可初始化为裸仓库布局。
 
+### 使用 SQLite 仓库（Bun 运行时）
+
+适用于需要持久化但又不想管理松散文件的场景——
+所有对象和引用存在一个 `.sqlite` 文件中。
+
+```typescript
+import { createSqliteRepository } from "nano-git/repository/sqlite";
+
+// 创建或打开 SQLite 持久化仓库（支持 using 自动释放）
+using repo = createSqliteRepository("/tmp/cache.sqlite");
+
+// 与普通 repo 使用方式完全一致
+const hash = repo.writeBlob(Buffer.from("persistent data"));
+const treeHash = repo.createTree([{ mode: "100644", name: "data.txt", hash }]);
+const commitHash = repo.createCommit(treeHash, [], "SQLite commit", {
+  name: "You",
+  email: "you@example.com",
+  timestamp: Math.floor(Date.now() / 1000),
+  timezone: "+0800",
+});
+console.log(`Committed: ${commitHash}`);
+
+// 作用域结束时自动关闭数据库连接
+```
+
+也可拆分使用底层后端：
+
+```typescript
+import { createSqliteRepositoryBackend } from "nano-git/backend/sqlite";
+import { createRepository } from "nano-git/repository/core";
+
+const backend = createSqliteRepositoryBackend("/tmp/repo.sqlite");
+const repo = createRepository(backend);
+// 用完记得释放
+backend[Symbol.dispose]();
+```
+
 ### 生成 Packfile
 
 ```typescript
@@ -305,6 +359,8 @@ bun run examples/demo.ts
 
 本库默认入口 `"nano-git"` 直接提供高频的纯计算能力：类型、错误、对象编解码、refs 工具和 SHA-1 工具。
 带 `node:fs` / `node:zlib` 的运行时能力通过子路径显式导入，例如 `nano-git/repository/file`、`nano-git/pack`、`nano-git/transport/http`。
+纯远端查询能力通过 `nano-git/remote/http` 导入。
+基于 `bun:sqlite` 的存储后端通过 `nano-git/odb/sqlite`、`nano-git/refs/sqlite`、`nano-git/backend/sqlite`、`nano-git/repository/sqlite` 等子路径导入。
 tree-shaking 主要依赖模块本身的无副作用结构，而不是把所有 API 都拆成叶子级子路径。完整入口表见 `package.json` 的 `exports` 与 `src/index.ts` 的 JSDoc。
 
 ## Git 对象模型
@@ -381,6 +437,7 @@ bun test
 - [x] 可达性遍历与 GC（repack、gc）
 - [x] **Smart HTTP 传输** — pkt-line 编解码、ref 广告解析、side-band 解复用、Fetch / Push 协议、Import Session 集成
 - [x] **Reference Transaction** — 批量 ref 更新原子性、lock-then-rename 文件事务、生命周期 Hooks
+- [x] **SQLite 存储后端** — 基于 `bun:sqlite` 的单文件持久化，支持对象/refs/shallow 存储、ACID 事务、`Symbol.dispose` 生命周期管理
 
 - [x] **Smart HTTP 服务端（upload-pack）** — 类 git-http-backend、框架无关的 HTTP handler，支持 ls-refs 和 fetch 命令，协议实现与编排器解耦
 - [x] **Smart HTTP 服务端（v1 receive-pack）** — 服务端 push 支持，基于 v1 协议，含 ref 广告、packfile 解包、ref 校验与 report-status

package/dist/backend/sqlite.d.mts

@@ -0,0 +1,44 @@
+import { RepositoryBackend } from "./types.mjs";
+
+//#region src/backend/sqlite.d.ts
+/** 创建 SQLite 仓库后端的可选参数 */
+interface CreateSqliteRepositoryBackendOptions {
+  /** 开启 WAL 模式，默认 true */
+  readonly walMode?: boolean;
+}
+/**
+ * SQLite 仓库后端（含资源释放能力）
+ *
+ * 在 RepositoryBackend 的基础上增加了 [Symbol.dispose]()，
+ * 支持 `using backend = createSqliteRepositoryBackend(...)` 语法。
+ */
+interface SqliteRepositoryBackend extends RepositoryBackend {
+  /** 释放 SQLite 数据库连接 */
+  [Symbol.dispose](): void;
+}
+/**
+ * 创建基于 SQLite 文件的完整仓库后端
+ *
+ * 内部创建 Database 实例并组合三个子 store。
+ * 返回的 backend 实现了 [Symbol.dispose]()，可使用 `using` 语法
+ * 或在不再使用时手动调用 `backend[Symbol.dispose]()`。
+ *
+ * @param dbPath - SQLite 数据库文件路径
+ * @returns 实现了 SqliteRepositoryBackend 的仓库后端（可用 `using` 管理）
+ *
+ * @example
+ * ```ts
+ * // 使用 using 自动释放（推荐）
+ * using backend = createSqliteRepositoryBackend("/tmp/repo.sqlite");
+ * const repo = createRepository(backend);
+ *
+ * // 或手动管理
+ * const backend = createSqliteRepositoryBackend("/tmp/repo.sqlite");
+ * const repo = createRepository(backend);
+ * // ... 使用完毕 ...
+ * backend[Symbol.dispose]();
+ * ```
+ */
+declare function createSqliteRepositoryBackend(dbPath: string, options?: CreateSqliteRepositoryBackendOptions): SqliteRepositoryBackend;
+//#endregion
+export { CreateSqliteRepositoryBackendOptions, SqliteRepositoryBackend, createSqliteRepositoryBackend };

package/dist/backend/sqlite.mjs

@@ -0,0 +1,59 @@
+import { HEADS_PREFIX, HEAD_REF } from "../core/types/refs.mjs";
+import { createSqliteObjectStore } from "../odb/sqlite.mjs";
+import { createSqliteRefStore } from "../refs/sqlite.mjs";
+import { createSqliteShallowStore } from "../refs/shallow/sqlite.mjs";
+import { Database } from "bun:sqlite";
+//#region src/backend/sqlite.ts
+/**
+* 基于 SQLite 的仓库后端
+*
+* 将 SQLite 中的 objects、refs、shallow 存储
+* 组合为统一的 RepositoryBackend。
+*
+* 支持 [Symbol.dispose]() 释放数据库连接，
+* 可使用 `using` 语法管理生命周期。
+*/
+/**
+* 创建基于 SQLite 文件的完整仓库后端
+*
+* 内部创建 Database 实例并组合三个子 store。
+* 返回的 backend 实现了 [Symbol.dispose]()，可使用 `using` 语法
+* 或在不再使用时手动调用 `backend[Symbol.dispose]()`。
+*
+* @param dbPath - SQLite 数据库文件路径
+* @returns 实现了 SqliteRepositoryBackend 的仓库后端（可用 `using` 管理）
+*
+* @example
+* ```ts
+* // 使用 using 自动释放（推荐）
+* using backend = createSqliteRepositoryBackend("/tmp/repo.sqlite");
+* const repo = createRepository(backend);
+*
+* // 或手动管理
+* const backend = createSqliteRepositoryBackend("/tmp/repo.sqlite");
+* const repo = createRepository(backend);
+* // ... 使用完毕 ...
+* backend[Symbol.dispose]();
+* ```
+*/
+function createSqliteRepositoryBackend(dbPath, options = {}) {
+	const db = new Database(dbPath);
+	if (options.walMode !== false) db.run("PRAGMA journal_mode = WAL");
+	db.run("CREATE TABLE IF NOT EXISTS objects (hash TEXT PRIMARY KEY, type TEXT NOT NULL, content BLOB NOT NULL)");
+	db.run("CREATE TABLE IF NOT EXISTS refs (name TEXT PRIMARY KEY, target TEXT NOT NULL)");
+	db.run("CREATE TABLE IF NOT EXISTS shallow (hash TEXT PRIMARY KEY)");
+	db.run("INSERT OR IGNORE INTO refs (name, target) VALUES (?, ?)", [HEAD_REF, `ref: ${HEADS_PREFIX}main`]);
+	return {
+		gitDir: dbPath,
+		objects: createSqliteObjectStore(db),
+		refs: createSqliteRefStore(db),
+		shallow: createSqliteShallowStore(db),
+		packs: null,
+		/** 释放 SQLite 数据库连接 */
+		[Symbol.dispose]() {
+			db.close();
+		}
+	};
+}
+//#endregion
+export { createSqliteRepositoryBackend };

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/index.d.mts

@@ -1,6 +1,7 @@
 import { GitAuthor, GitBlob, GitCommit, GitCommitExtraHeader, GitObject, GitTag, GitTree, ObjectType, RawGitObject, SHA1, TreeEntry, assertObjectType, sha1 } from "./core/types.mjs";
 import { PackRepackOptions, RepositoryBackend, RepositoryGCOptions, RepositoryPackSupport, RepositoryRepackOptions } from "./backend/types.mjs";
 import { CircularReferenceError, DeltaError, GitError, InvalidObjectError, InvalidPackError, InvalidSHA1Error, ObjectNotFoundError, PackError, PackIndexError, PreconditionCheckError, RefNotFoundError, RepositoryError, TransactionError } from "./core/errors.mjs";
+import { RemoteSource } from "./remote/types.mjs";
 import { FileRepository, Repository } from "./repository/types.mjs";
 import { hashData, hashObject } from "./core/hash-digest.mjs";
 import { isValidSHA1 } from "./core/hash-path.mjs";
@@ -13,4 +14,4 @@ import { deserialize, deserializeContent, serialize, serializeContent } from "./
 import { decodeObject, encodeObject, readObject, tryReadObject, writeObject } from "./objects/raw.mjs";
 import { branchNameToRef, normalizeShortRefName, tagNameToRef, validateRefName, validateRefPrefix } from "./refs/names.mjs";
 import { resolveRefHash, resolveSymbolicRef, resolveTargetHash } from "./refs/resolve.mjs";
-export { CircularReferenceError, DeltaError, type FileRepository, type GitAuthor, type GitBlob, type GitCommit, type GitCommitExtraHeader, GitError, type GitObject, type GitTag, type GitTree, InvalidObjectError, InvalidPackError, InvalidSHA1Error, ObjectNotFoundError, type ObjectType, PackError, PackIndexError, type PackRepackOptions, PreconditionCheckError, type RawGitObject, RefNotFoundError, type Repository, type RepositoryBackend, RepositoryError, type RepositoryGCOptions, type RepositoryPackSupport, type RepositoryRepackOptions, type SHA1, TransactionError, type TreeEntry, assertObjectType, branchNameToRef, decodeObject, deserialize, deserializeBlob, deserializeCommit, deserializeContent, deserializeTag, deserializeTree, encodeObject, formatAuthor, hashData, hashObject, isValidSHA1, normalizeShortRefName, parseAuthor, readObject, resolveRefHash, resolveSymbolicRef, resolveTargetHash, serialize, serializeBlob, serializeCommit, serializeContent, serializeTag, serializeTree, sha1, tagNameToRef, tryReadObject, validateRefName, validateRefPrefix, writeObject };
+export { CircularReferenceError, DeltaError, type FileRepository, type GitAuthor, type GitBlob, type GitCommit, type GitCommitExtraHeader, GitError, type GitObject, type GitTag, type GitTree, InvalidObjectError, InvalidPackError, InvalidSHA1Error, ObjectNotFoundError, type ObjectType, PackError, PackIndexError, type PackRepackOptions, PreconditionCheckError, type RawGitObject, RefNotFoundError, type RemoteSource, type Repository, type RepositoryBackend, RepositoryError, type RepositoryGCOptions, type RepositoryPackSupport, type RepositoryRepackOptions, type SHA1, TransactionError, type TreeEntry, assertObjectType, branchNameToRef, decodeObject, deserialize, deserializeBlob, deserializeCommit, deserializeContent, deserializeTag, deserializeTree, encodeObject, formatAuthor, hashData, hashObject, isValidSHA1, normalizeShortRefName, parseAuthor, readObject, resolveRefHash, resolveSymbolicRef, resolveTargetHash, serialize, serializeBlob, serializeCommit, serializeContent, serializeTag, serializeTree, sha1, tagNameToRef, tryReadObject, validateRefName, validateRefPrefix, writeObject };

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 };