nano-git 0.1.0

package/dist/odb/file-utils.mjs

@@ -0,0 +1,136 @@
+import { InvalidObjectError } from "../core/errors.mjs";
+import { assertObjectType, sha1 } from "../core/types.mjs";
+import { hashToPath } from "../core/hash-path.mjs";
+import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, unlinkSync, writeFileSync } from "node:fs";
+import { deflateSync, inflateSync } from "node:zlib";
+import { join } from "node:path";
+//#region src/odb/file-utils.ts
+/**
+* loose object 文件系统辅助函数
+*
+* 负责对象路径计算、压缩读写与对象目录枚举。
+*/
+/**
+* 计算 loose object 文件路径
+*
+* @example
+* ```ts
+* const path = getLooseObjectPath("/repo/.git/objects", hash);
+* console.log(path);
+* ```
+*/
+function getLooseObjectPath(objectsDir, hash) {
+	return join(objectsDir, hashToPath(hash));
+}
+/**
+* 检查 loose object 是否存在
+*
+* @example
+* ```ts
+* if (hasLooseObject(objectsDir, hash)) {
+*   console.log("对象已存在");
+* }
+* ```
+*/
+function hasLooseObject(objectsDir, hash) {
+	return existsSync(getLooseObjectPath(objectsDir, hash));
+}
+/**
+* 删除 loose object 文件
+*
+* 删除不存在的对象时静默成功（no-op）。
+*
+* @param objectsDir - .git/objects 目录路径
+* @param hash - 要删除的对象哈希
+*
+* @example
+* ```ts
+* deleteLooseObject(objectsDir, hash);
+* ```
+*/
+function deleteLooseObject(objectsDir, hash) {
+	const objectPath = getLooseObjectPath(objectsDir, hash);
+	if (existsSync(objectPath)) unlinkSync(objectPath);
+}
+/**
+* 枚举所有 loose object 哈希
+*
+* @example
+* ```ts
+* const hashes = listLooseObjects(objectsDir);
+* console.log(hashes.length);
+* ```
+*/
+function listLooseObjects(objectsDir) {
+	if (!existsSync(objectsDir)) return [];
+	const hashes = [];
+	const dirs = readdirSync(objectsDir).sort();
+	for (const dirName of dirs) {
+		if (dirName === "info" || dirName === "pack" || dirName.length !== 2) continue;
+		const dirPath = join(objectsDir, dirName);
+		if (!statSync(dirPath).isDirectory()) continue;
+		const files = readdirSync(dirPath).sort();
+		for (const fileName of files) {
+			if (fileName.length !== 38) continue;
+			hashes.push(sha1(`${dirName}${fileName}`));
+		}
+	}
+	return hashes;
+}
+/**
+* 写入 raw loose object 文件（使用 canonical bytes）
+*
+* 直接以 "<type> <size>\0<content>" 格式 deflate 写入，
+* 不经过语义序列化。
+*
+* @param objectsDir - .git/objects 目录路径
+* @param raw - 原始对象
+*
+* @example
+* ```ts
+* writeRawLooseObject(objectsDir, raw);
+* ```
+*/
+function writeRawLooseObject(objectsDir, raw) {
+	const objectPath = getLooseObjectPath(objectsDir, raw.hash);
+	mkdirSync(join(objectsDir, raw.hash.slice(0, 2)), { recursive: true });
+	const header = `${raw.type} ${raw.content.length}\0`;
+	writeFileSync(objectPath, deflateSync(Buffer.concat([Buffer.from(header), raw.content])));
+}
+/**
+* 读取 raw loose object 文件
+*
+* 读取后直接返回 { hash, type, content }，
+* 不经过语义反序列化。
+*
+* @param objectsDir - .git/objects 目录路径
+* @param hash - 对象哈希
+* @returns 原始对象
+*
+* @example
+* ```ts
+* const raw = readRawLooseObject(objectsDir, hash);
+* console.log(raw.type, raw.content.length);
+* ```
+*/
+function readRawLooseObject(objectsDir, hash) {
+	const objectPath = getLooseObjectPath(objectsDir, hash);
+	if (!existsSync(objectPath)) throw new Error(`Object not found: ${hash}`);
+	const data = inflateSync(readFileSync(objectPath));
+	const nullIndex = data.indexOf(0);
+	if (nullIndex === -1) throw new InvalidObjectError("missing null byte in loose object");
+	const header = data.subarray(0, nullIndex).toString("utf-8");
+	const match = header.match(/^(blob|tree|commit|tag) (\d+)$/);
+	if (!match) throw new InvalidObjectError(`invalid loose object header: ${header}`);
+	const type = assertObjectType(match[1]);
+	const size = parseInt(match[2], 10);
+	const content = data.subarray(nullIndex + 1);
+	if (content.length !== size) throw new InvalidObjectError(`size mismatch: header says ${size}, got ${content.length}`);
+	return {
+		hash,
+		type,
+		content
+	};
+}
+//#endregion
+export { deleteLooseObject, hasLooseObject, listLooseObjects, readRawLooseObject, writeRawLooseObject };

package/dist/odb/file.d.mts

@@ -0,0 +1,22 @@
+import { ObjectDatabase } from "../core/types/odb.mjs";
+
+//#region src/odb/file.d.ts
+/**
+ * 创建基于文件系统的对象数据库
+ *
+ * @param gitDir - .git 目录的路径
+ *
+ * @example
+ * ```ts
+ * const db = createFileObjectStore("/path/to/repo/.git");
+ *
+ * // 摄入一个原始对象
+ * db.ingest(raw);
+ *
+ * // 读取回来
+ * const obj = db.read(hash);
+ * ```
+ */
+declare function createFileObjectStore(gitDir: string): ObjectDatabase;
+//#endregion
+export { createFileObjectStore };

package/dist/odb/file.mjs

@@ -0,0 +1,66 @@
+import { hashObject } from "../core/hash-digest.mjs";
+import { deleteLooseObject, hasLooseObject, listLooseObjects, readRawLooseObject, writeRawLooseObject } from "./file-utils.mjs";
+import { join } from "node:path";
+//#region src/odb/file.ts
+/**
+* 基于文件系统的对象数据库（raw-first）
+*
+* Git 将对象存储在 .git/objects/ 目录下：
+* - 每个对象以 zlib 压缩格式存储
+* - 路径格式: .git/objects/<前2字符>/<剩余38字符>
+* - 例如: .git/objects/95/d09f2b10159347eece71399a7e2e907ea3df4f
+*
+* ODB 的真实边界是 RawGitObject，不是 GitObject。
+* 写入路径直接接收 RawGitObject，不再经过语义序列化。
+*/
+/**
+* 创建基于文件系统的对象数据库
+*
+* @param gitDir - .git 目录的路径
+*
+* @example
+* ```ts
+* const db = createFileObjectStore("/path/to/repo/.git");
+*
+* // 摄入一个原始对象
+* db.ingest(raw);
+*
+* // 读取回来
+* const obj = db.read(hash);
+* ```
+*/
+function createFileObjectStore(gitDir) {
+	const objectsDir = join(gitDir, "objects");
+	return {
+		ingest(raw) {
+			const expectedHash = hashObject(raw.type, raw.content);
+			if (expectedHash !== raw.hash) throw new Error(`RawGitObject hash mismatch: expected ${expectedHash}, got ${raw.hash}`);
+			if (hasLooseObject(objectsDir, raw.hash)) return;
+			writeRawLooseObject(objectsDir, raw);
+		},
+		ingestMany(objects) {
+			for (const raw of objects) this.ingest(raw);
+		},
+		read(hash) {
+			return readRawLooseObject(objectsDir, hash);
+		},
+		tryRead(hash) {
+			try {
+				return readRawLooseObject(objectsDir, hash);
+			} catch {
+				return;
+			}
+		},
+		exists(hash) {
+			return hasLooseObject(objectsDir, hash);
+		},
+		list() {
+			return listLooseObjects(objectsDir);
+		},
+		delete(hash) {
+			deleteLooseObject(objectsDir, hash);
+		}
+	};
+}
+//#endregion
+export { createFileObjectStore };

package/dist/odb/memory.d.mts

@@ -0,0 +1,22 @@
+import { ObjectDatabase } from "../core/types/odb.mjs";
+
+//#region src/odb/memory.d.ts
+/**
+ * 内存对象数据库接口
+ */
+type MemoryObjectDatabase = ObjectDatabase;
+/**
+ * 创建基于内存的对象数据库
+ *
+ * 所有对象存储在内存中，程序退出后丢失。
+ *
+ * @example
+ * ```ts
+ * const db = createMemoryObjectStore();
+ * db.ingest(raw);
+ * const obj = db.read(hash);
+ * ```
+ */
+declare function createMemoryObjectStore(): MemoryObjectDatabase;
+//#endregion
+export { MemoryObjectDatabase, type ObjectDatabase, createMemoryObjectStore };

package/dist/odb/memory.mjs

@@ -0,0 +1,54 @@
+import { hashObject } from "../core/hash-digest.mjs";
+//#region src/odb/memory.ts
+/**
+* 基于内存的对象数据库（raw-first）
+*
+* 所有对象以 RawGitObject 形式存储在内存 Map 中，程序退出后丢失。
+* 适用于单元测试和临时操作场景。
+*
+* ODB 的真实边界是 RawGitObject，不是 GitObject。
+*/
+/**
+* 创建基于内存的对象数据库
+*
+* 所有对象存储在内存中，程序退出后丢失。
+*
+* @example
+* ```ts
+* const db = createMemoryObjectStore();
+* db.ingest(raw);
+* const obj = db.read(hash);
+* ```
+*/
+function createMemoryObjectStore() {
+	const store = /* @__PURE__ */ new Map();
+	return {
+		ingest(raw) {
+			const expectedHash = hashObject(raw.type, raw.content);
+			if (expectedHash !== raw.hash) throw new Error(`RawGitObject hash mismatch: expected ${expectedHash}, got ${raw.hash}`);
+			if (!store.has(raw.hash)) store.set(raw.hash, raw);
+		},
+		ingestMany(objects) {
+			for (const raw of objects) this.ingest(raw);
+		},
+		read(hash) {
+			const obj = store.get(hash);
+			if (!obj) throw new Error(`Object not found: ${hash}`);
+			return obj;
+		},
+		tryRead(hash) {
+			return store.get(hash);
+		},
+		exists(hash) {
+			return store.has(hash);
+		},
+		list() {
+			return Array.from(store.keys());
+		},
+		delete(hash) {
+			store.delete(hash);
+		}
+	};
+}
+//#endregion
+export { createMemoryObjectStore };

package/dist/pack/composite-store.d.mts

@@ -0,0 +1,76 @@
+import { RawGitObject, SHA1 } from "../core/types.mjs";
+import { ObjectDatabase, ObjectSource } from "../core/types/odb.mjs";
+
+//#region src/pack/composite-store.d.ts
+/**
+ * 创建组合对象数据库
+ *
+ * @param primary - 主数据库（用于摄入）
+ * @param secondary - 辅助源列表（只读，按顺序查找）
+ * @returns 组合对象数据库
+ *
+ * @example
+ * ```ts
+ * const looseDb = createFileObjectStore(gitDir);
+ * const packSource = createPackObjectStore(gitDir);
+ * const db = createCompositeObjectDatabase(looseDb, packSource);
+ *
+ * // 读取时自动在所有存储中查找
+ * const raw = db.read(hash);
+ *
+ * // 摄入时只写入主数据库
+ * db.ingest(raw);
+ * ```
+ */
+declare function createCompositeObjectDatabase(primary: ObjectDatabase, ...secondary: ObjectSource[]): CompositeObjectDatabase;
+/**
+ * 组合对象数据库类
+ */
+declare class CompositeObjectDatabase implements ObjectDatabase {
+  private readonly primary;
+  private readonly secondary;
+  constructor(primary: ObjectDatabase, secondary: ObjectSource[]);
+  /**
+   * 摄入原始对象到主数据库
+   */
+  ingest(raw: RawGitObject): void;
+  /**
+   * 批量摄入原始对象到主数据库
+   */
+  ingestMany(objects: Iterable<RawGitObject>): void;
+  /**
+   * 删除对象
+   *
+   * 委托给主数据库的 delete。
+   */
+  delete(hash: SHA1): void;
+  /**
+   * 尝试读取原始对象，不存在时返回 undefined
+   */
+  tryRead(hash: SHA1): RawGitObject | undefined;
+  /**
+   * 尝试从指定源中读取对象，不存在时返回 undefined
+   */
+  private tryReadSource;
+  /**
+   * 读取原始对象
+   *
+   * 按顺序在所有存储中查找，返回第一个找到的对象。
+   * （跳过 exists() 前置检查，直接尝试 read() 以消除 N+1 双重调用）
+   *
+   * @throws ObjectNotFoundError 如果对象在所有存储中都不存在
+   */
+  read(hash: SHA1): RawGitObject;
+  /**
+   * 检查对象是否存在
+   */
+  exists(hash: SHA1): boolean;
+  /**
+   * 列出所有对象哈希
+   *
+   * 主数据库排在前面，重复哈希自动去重。
+   */
+  list(): SHA1[];
+}
+//#endregion
+export { CompositeObjectDatabase, createCompositeObjectDatabase };

package/dist/pack/composite-store.mjs

@@ -0,0 +1,133 @@
+import { ObjectNotFoundError } from "../core/errors.mjs";
+//#region src/pack/composite-store.ts
+/**
+* 组合对象源/数据库
+*
+* 将多个对象源/数据库组合在一起，按优先级顺序查找对象。
+* 典型用法：loose objects（文件系统）+ packfile 存储。
+*
+* 查找顺序：
+* 1. 先在主数据库中查找（最新写入/摄入的对象）
+* 2. 再在辅助源中查找（已打包的对象）
+*
+* 摄入操作始终写入到主数据库。
+*
+* @example
+* ```ts
+* const db = createCompositeObjectDatabase(fileDb, packSource);
+* const raw = db.read(hash); // 自动在所有存储中查找
+* ```
+*/
+/**
+* 创建组合对象数据库
+*
+* @param primary - 主数据库（用于摄入）
+* @param secondary - 辅助源列表（只读，按顺序查找）
+* @returns 组合对象数据库
+*
+* @example
+* ```ts
+* const looseDb = createFileObjectStore(gitDir);
+* const packSource = createPackObjectStore(gitDir);
+* const db = createCompositeObjectDatabase(looseDb, packSource);
+*
+* // 读取时自动在所有存储中查找
+* const raw = db.read(hash);
+*
+* // 摄入时只写入主数据库
+* db.ingest(raw);
+* ```
+*/
+function createCompositeObjectDatabase(primary, ...secondary) {
+	return new CompositeObjectDatabase(primary, secondary);
+}
+/**
+* 组合对象数据库类
+*/
+var CompositeObjectDatabase = class {
+	primary;
+	secondary;
+	constructor(primary, secondary) {
+		this.primary = primary;
+		this.secondary = secondary;
+	}
+	/**
+	* 摄入原始对象到主数据库
+	*/
+	ingest(raw) {
+		return this.primary.ingest(raw);
+	}
+	/**
+	* 批量摄入原始对象到主数据库
+	*/
+	ingestMany(objects) {
+		for (const raw of objects) this.ingest(raw);
+	}
+	/**
+	* 删除对象
+	*
+	* 委托给主数据库的 delete。
+	*/
+	delete(hash) {
+		this.primary.delete(hash);
+	}
+	/**
+	* 尝试读取原始对象，不存在时返回 undefined
+	*/
+	tryRead(hash) {
+		const primaryResult = this.tryReadSource(this.primary, hash);
+		if (primaryResult !== void 0) return primaryResult;
+		for (const source of this.secondary) {
+			const result = this.tryReadSource(source, hash);
+			if (result !== void 0) return result;
+		}
+	}
+	/**
+	* 尝试从指定源中读取对象，不存在时返回 undefined
+	*/
+	tryReadSource(source, hash) {
+		try {
+			return source.read(hash);
+		} catch {
+			return;
+		}
+	}
+	/**
+	* 读取原始对象
+	*
+	* 按顺序在所有存储中查找，返回第一个找到的对象。
+	* （跳过 exists() 前置检查，直接尝试 read() 以消除 N+1 双重调用）
+	*
+	* @throws ObjectNotFoundError 如果对象在所有存储中都不存在
+	*/
+	read(hash) {
+		const primaryResult = this.tryReadSource(this.primary, hash);
+		if (primaryResult !== void 0) return primaryResult;
+		for (const source of this.secondary) {
+			const result = this.tryReadSource(source, hash);
+			if (result !== void 0) return result;
+		}
+		throw new ObjectNotFoundError(hash);
+	}
+	/**
+	* 检查对象是否存在
+	*/
+	exists(hash) {
+		if (this.primary.exists(hash)) return true;
+		for (const source of this.secondary) if (source.exists(hash)) return true;
+		return false;
+	}
+	/**
+	* 列出所有对象哈希
+	*
+	* 主数据库排在前面，重复哈希自动去重。
+	*/
+	list() {
+		const hashes = /* @__PURE__ */ new Set();
+		for (const hash of this.primary.list()) hashes.add(hash);
+		for (const source of this.secondary) for (const hash of source.list()) hashes.add(hash);
+		return Array.from(hashes).sort();
+	}
+};
+//#endregion
+export { CompositeObjectDatabase, createCompositeObjectDatabase };

package/dist/pack/constants.mjs

@@ -0,0 +1,48 @@
+/** Packfile 魔数 "PACK" */
+const PACK_SIGNATURE = Buffer.from("PACK");
+/** idx v2 文件魔数 */
+const IDX_V2_SIGNATURE = Buffer.from([
+	255,
+	116,
+	79,
+	99
+]);
+/** idx v2 扇出表大小：256 个 4 字节整数 */
+const IDX_V2_FANOUT_SIZE = 256 * 4;
+/**
+* 将 Git 对象类型字符串转换为 Packfile 类型编号
+*
+* @example
+* ```ts
+* objectTypeToNumber("commit") // => 1
+* objectTypeToNumber("blob")   // => 3
+* ```
+*/
+function objectTypeToNumber(type) {
+	switch (type) {
+		case "commit": return 1;
+		case "tree": return 2;
+		case "blob": return 3;
+		case "tag": return 4;
+	}
+}
+/**
+* 将 Packfile 类型编号转换为 Git 对象类型字符串
+*
+* @example
+* ```ts
+* numberToObjectType(1) // => "commit"
+* numberToObjectType(3) // => "blob"
+* ```
+*/
+function numberToObjectType(n) {
+	switch (n) {
+		case 1: return "commit";
+		case 2: return "tree";
+		case 3: return "blob";
+		case 4: return "tag";
+		default: throw new Error(`Unknown object type number: ${n}`);
+	}
+}
+//#endregion
+export { IDX_V2_FANOUT_SIZE, IDX_V2_SIGNATURE, PACK_SIGNATURE, numberToObjectType, objectTypeToNumber };

package/dist/pack/crc32.mjs

@@ -0,0 +1,38 @@
+//#region src/pack/crc32.ts
+/**
+* CRC32 计算工具
+*/
+/** CRC32 查找表缓存 */
+let crc32Table = null;
+/**
+* 计算数据的 CRC32 校验和
+*
+* 使用标准 CRC32 算法（与 Git 兼容）。
+*
+* @example
+* ```ts
+* const crc = crc32Value(Buffer.from("hello"));
+* ```
+*/
+function crc32Value(data) {
+	const table = getCRC32Table();
+	let crc = 4294967295;
+	for (let i = 0; i < data.length; i++) crc = crc >>> 8 ^ table[(crc ^ data[i]) & 255];
+	return (crc ^ 4294967295) >>> 0;
+}
+/**
+* 获取或生成 CRC32 查找表
+*/
+function getCRC32Table() {
+	if (crc32Table) return crc32Table;
+	crc32Table = /* @__PURE__ */ new Uint32Array(256);
+	for (let i = 0; i < 256; i++) {
+		let crc = i;
+		for (let j = 0; j < 8; j++) if (crc & 1) crc = crc >>> 1 ^ 3988292384;
+		else crc = crc >>> 1;
+		crc32Table[i] = crc;
+	}
+	return crc32Table;
+}
+//#endregion
+export { crc32Value };

package/dist/pack/delta-apply.d.mts

@@ -0,0 +1,21 @@
+//#region src/pack/delta-apply.d.ts
+/**
+ * Delta 应用（解码）
+ */
+/**
+ * 将 delta 数据应用到 base object，生成目标对象
+ *
+ * @param base - base object 的原始数据
+ * @param delta - delta 数据
+ * @returns 目标对象的原始数据
+ *
+ * @example
+ * ```ts
+ * const base = Buffer.from("hello world");
+ * const delta = createDelta(base, Buffer.from("hello git"));
+ * const result = applyDelta(base, delta);
+ * ```
+ */
+declare function applyDelta(base: Buffer, delta: Buffer): Buffer;
+//#endregion
+export { applyDelta };

package/dist/pack/delta-apply.mjs

@@ -0,0 +1,71 @@
+import { DeltaError } from "../core/errors.mjs";
+import { decodeVarint } from "./varint.mjs";
+//#region src/pack/delta-apply.ts
+/**
+* Delta 应用（解码）
+*/
+/**
+* 将 delta 数据应用到 base object，生成目标对象
+*
+* @param base - base object 的原始数据
+* @param delta - delta 数据
+* @returns 目标对象的原始数据
+*
+* @example
+* ```ts
+* const base = Buffer.from("hello world");
+* const delta = createDelta(base, Buffer.from("hello git"));
+* const result = applyDelta(base, delta);
+* ```
+*/
+function applyDelta(base, delta) {
+	let offset = 0;
+	const [_srcSize, srcBytes] = decodeVarint(delta, offset);
+	offset += srcBytes;
+	const [destSize, destBytes] = decodeVarint(delta, offset);
+	offset += destBytes;
+	const result = Buffer.alloc(destSize);
+	let destOffset = 0;
+	while (offset < delta.length) {
+		const cmd = delta[offset];
+		offset++;
+		if (cmd & 128) {
+			const copy = decodeCopyInstruction(delta, offset, cmd);
+			offset += copy.bytesRead;
+			if (copy.offset + copy.size > base.length) throw new DeltaError(`Copy out of bounds: offset=${copy.offset}, size=${copy.size}, base.length=${base.length}`);
+			base.copy(result, destOffset, copy.offset, copy.offset + copy.size);
+			destOffset += copy.size;
+			continue;
+		}
+		if (cmd > 0) {
+			if (offset + cmd > delta.length) throw new DeltaError("Insert out of bounds");
+			delta.copy(result, destOffset, offset, offset + cmd);
+			destOffset += cmd;
+			offset += cmd;
+			continue;
+		}
+		throw new DeltaError("Unexpected delta command: 0");
+	}
+	if (destOffset !== destSize) throw new DeltaError(`Delta size mismatch: expected ${destSize}, got ${destOffset}`);
+	return result;
+}
+function decodeCopyInstruction(delta, offset, cmd) {
+	const start = offset;
+	let copyOffset = 0;
+	let copySize = 0;
+	if (cmd & 1) copyOffset = delta[offset++];
+	if (cmd & 2) copyOffset |= delta[offset++] << 8;
+	if (cmd & 4) copyOffset |= delta[offset++] << 16;
+	if (cmd & 8) copyOffset |= delta[offset++] << 24;
+	if (cmd & 16) copySize = delta[offset++];
+	if (cmd & 32) copySize |= delta[offset++] << 8;
+	if (cmd & 64) copySize |= delta[offset++] << 16;
+	if (copySize === 0) copySize = 65536;
+	return {
+		offset: copyOffset,
+		size: copySize,
+		bytesRead: offset - start
+	};
+}
+//#endregion
+export { applyDelta };