nano-git 0.1.0

package/dist/pack/pack-reader.mjs

@@ -0,0 +1,171 @@
+import { InvalidPackError } from "../core/errors.mjs";
+import { decodeObjectHeader } from "./object-header.mjs";
+import { decodeOfsDeltaOffset } from "./ofs-delta-offset.mjs";
+import { parsePackHeader } from "./pack-reader-utils.mjs";
+import { resolveOfsDeltaPackObject, resolvePlainPackObject, resolveRefDeltaPackObject } from "./pack-reader-resolver.mjs";
+import "./pack-reader-types.mjs";
+//#region src/pack/pack-reader.ts
+/**
+* Packfile 读取
+*
+* Git Packfile 格式：
+* - 头部：4 字节签名 "PACK" + 4 字节版本 + 4 字节对象数
+* - 对象序列：每个对象包含头部 + zlib 压缩数据
+* - 尾部：20 字节 SHA-1 校验和
+*
+* 对象类型：
+* - 非 delta 对象：直接存储压缩后的对象数据
+* - ofs_delta：基于偏移量的 delta，引用同一 packfile 中的其他对象
+* - ref_delta：基于 SHA-1 的 delta，可引用任意对象
+*
+* @example
+* ```ts
+* const reader = createPackReader(packData);
+* for (const obj of reader.objects()) {
+*   console.log(obj.type, obj.hash);
+* }
+* ```
+*
+* 拆分共享类型与底层辅助函数后，
+* 当前文件只保留对象遍历与 delta 解析主流程。
+*/
+/**
+* 创建 Packfile 读取器
+*
+* @param data - 完整的 packfile 数据
+* @returns Packfile 读取器实例
+*
+* @example
+* ```ts
+* const reader = createPackReader(packData);
+* console.log(`Packfile 包含 ${reader.objectCount} 个对象`);
+*
+* // 遍历所有对象
+* for (const obj of reader.objects()) {
+*   console.log(`${obj.type} ${obj.hash}`);
+* }
+* ```
+*/
+function createPackReader(data) {
+	return new PackReader(data);
+}
+/**
+* Packfile 读取器类
+*
+* 使用惰性解析策略：对象在首次被访问时才解析。
+* - getByHash() / getByOffset() / has() 只解析到找到目标为止
+* - objects() / listHashes() 解析全部对象
+*/
+var PackReader = class {
+	data;
+	_objectCount;
+	objectsByOffset = /* @__PURE__ */ new Map();
+	objectsByHash = /* @__PURE__ */ new Map();
+	parseOffset;
+	parsedCount = 0;
+	fullyParsed = false;
+	constructor(data) {
+		this.data = data;
+		this._objectCount = parsePackHeader(data);
+		this.parseOffset = 12;
+	}
+	/** 对象数量 */
+	get objectCount() {
+		return this._objectCount;
+	}
+	/**
+	* 解析下一个对象
+	*/
+	parseNext() {
+		if (this.fullyParsed) return;
+		const endOffset = this.data.length - 20;
+		if (this.parsedCount >= this._objectCount || this.parseOffset >= endOffset) {
+			this.fullyParsed = true;
+			if (this.parsedCount < this._objectCount) throw new InvalidPackError(`Unexpected end of packfile at object ${this.parsedCount}`);
+			return;
+		}
+		const objOffset = this.parseOffset;
+		const [typeNum, _size, headerBytes] = decodeObjectHeader(this.data, this.parseOffset);
+		this.parseOffset += headerBytes;
+		let obj;
+		if (typeNum === 6) {
+			const [negOffset, offsetBytes] = decodeOfsDeltaOffset(this.data, this.parseOffset);
+			this.parseOffset += offsetBytes;
+			const resolved = resolveOfsDeltaPackObject(this.data, this.parseOffset, objOffset, negOffset, this.objectsByOffset);
+			obj = resolved.object;
+			this.parseOffset = resolved.nextOffset;
+		} else if (typeNum === 7) {
+			const baseHash = this.data.subarray(this.parseOffset, this.parseOffset + 20).toString("hex");
+			this.parseOffset += 20;
+			const resolved = resolveRefDeltaPackObject(this.data, this.parseOffset, objOffset, baseHash, this.objectsByHash);
+			obj = resolved.object;
+			this.parseOffset = resolved.nextOffset;
+		} else {
+			const resolved = resolvePlainPackObject(this.data, this.parseOffset, objOffset, typeNum);
+			obj = resolved.object;
+			this.parseOffset = resolved.nextOffset;
+		}
+		this.objectsByOffset.set(objOffset, obj);
+		this.objectsByHash.set(obj.hash, obj);
+		this.parsedCount++;
+		if (this.parsedCount >= this._objectCount) this.fullyParsed = true;
+	}
+	/**
+	* 按需解析直到条件满足或解析全部
+	*/
+	parseUntil(condition) {
+		while (!this.fullyParsed && !condition()) this.parseNext();
+	}
+	/**
+	* 解析所有剩余对象
+	*/
+	parseAllRemaining() {
+		this.parseUntil(() => this.fullyParsed);
+	}
+	/**
+	* 遍历所有对象
+	*
+	* 按 offset 顺序解析并迭代所有对象。
+	*/
+	*objects() {
+		this.parseAllRemaining();
+		yield* this.objectsByOffset.values();
+	}
+	/**
+	* 根据哈希获取对象（惰性解析）
+	*
+	* 只解析到找到目标对象为止，不解析全部。
+	*/
+	getByHash(hash) {
+		if (this.objectsByHash.has(hash)) return this.objectsByHash.get(hash);
+		this.parseUntil(() => this.objectsByHash.has(hash));
+		return this.objectsByHash.get(hash);
+	}
+	/**
+	* 根据偏移量获取对象（惰性解析）
+	*
+	* 只解析到目标偏移位置为止。
+	*/
+	getByOffset(offset) {
+		if (this.objectsByOffset.has(offset)) return this.objectsByOffset.get(offset);
+		this.parseUntil(() => this.objectsByOffset.has(offset) || this.fullyParsed);
+		return this.objectsByOffset.get(offset);
+	}
+	/**
+	* 检查对象是否存在（惰性查找）
+	*/
+	has(hash) {
+		if (this.objectsByHash.has(hash)) return true;
+		this.parseUntil(() => this.objectsByHash.has(hash));
+		return this.objectsByHash.has(hash);
+	}
+	/**
+	* 获取所有对象的哈希列表（解析全部）
+	*/
+	listHashes() {
+		this.parseAllRemaining();
+		return Array.from(this.objectsByHash.keys());
+	}
+};
+//#endregion
+export { PackReader, createPackReader };

package/dist/pack/pack-store-loader.mjs

@@ -0,0 +1,79 @@
+import { PackReader } from "./pack-reader.mjs";
+import { createPackIndexReader } from "./pack-index-reader.mjs";
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+//#region src/pack/pack-store-loader.ts
+/**
+* Pack 对象存储加载辅助函数
+*/
+/**
+* 扫描 pack 目录并加载索引信息
+*
+* @param packDir - `.git/objects/pack` 目录
+* @returns 已发现的 pack 文件对
+*
+* @example
+* ```ts
+* const pairs = loadPackPairs("/tmp/repo/.git/objects/pack");
+* ```
+*/
+function loadPackPairs(packDir) {
+	if (!existsSync(packDir)) return [];
+	const pairs = [];
+	const idxFiles = readdirSync(packDir).filter((file) => file.endsWith(".idx"));
+	for (const idxFile of idxFiles) {
+		const match = idxFile.match(/^pack-([0-9a-f]{40})\.idx$/);
+		if (!match) continue;
+		const checksum = match[1];
+		if (!existsSync(join(packDir, `pack-${checksum}.pack`))) continue;
+		const idxData = readFileSync(join(packDir, idxFile));
+		pairs.push({
+			checksum,
+			index: createPackIndexReader(idxData),
+			reader: null,
+			packData: null
+		});
+	}
+	return pairs;
+}
+/**
+* 按需加载 packfile 读取器
+*
+* @param packDir - `.git/objects/pack` 目录
+* @param pair - pack 文件对
+* @returns PackReader 实例
+*
+* @example
+* ```ts
+* const reader = getPackReader(packDir, pair);
+* ```
+*/
+function getPackReader(packDir, pair) {
+	if (!pair.reader) {
+		pair.packData = readFileSync(join(packDir, `pack-${pair.checksum}.pack`));
+		pair.reader = new PackReader(pair.packData);
+	}
+	return pair.reader;
+}
+/**
+* 将 pack 文件对转换为对外展示信息
+*
+* @param packDir - `.git/objects/pack` 目录
+* @param pair - pack 文件对
+* @returns pack 文件信息
+*
+* @example
+* ```ts
+* const info = toPackFileInfo(packDir, pair);
+* ```
+*/
+function toPackFileInfo(packDir, pair) {
+	return {
+		checksum: pair.checksum,
+		packPath: join(packDir, `pack-${pair.checksum}.pack`),
+		idxPath: join(packDir, `pack-${pair.checksum}.idx`),
+		objectCount: pair.index.objectCount
+	};
+}
+//#endregion
+export { getPackReader, loadPackPairs, toPackFileInfo };

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

@@ -0,0 +1,16 @@
+//#region src/pack/pack-store-types.d.ts
+/**
+ * 一个已发现的 pack 文件对
+ */
+interface PackFileInfo {
+  /** pack 文件校验和 */
+  checksum: string;
+  /** .pack 文件路径 */
+  packPath: string;
+  /** .idx 文件路径 */
+  idxPath: string;
+  /** 索引中的对象数量 */
+  objectCount: number;
+}
+//#endregion
+export { PackFileInfo };

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

@@ -0,0 +1,55 @@
+import { SHA1 } from "../core/types.mjs";
+import { ObjectSource } from "../core/types/odb.mjs";
+import { PackFileInfo } from "./pack-store-types.mjs";
+
+//#region src/pack/pack-store.d.ts
+/**
+ * 基于 Packfile 的对象源接口
+ */
+interface PackObjectStore extends ObjectSource {
+  /**
+   * 刷新 pack 目录缓存
+   *
+   * 当外部新增或删除 packfile 后，需要调用此方法重新扫描。
+   */
+  refresh(): void;
+  /**
+   * 列出当前可见的 pack 文件对
+   */
+  listPacks(): PackFileInfo[];
+  /**
+   * 获取所有 packfile 中的对象哈希列表
+   *
+   * 保留此方法作为更明确的命名别名。
+   */
+  listHashes(): SHA1[];
+  /** 获取 packfile 数量 */
+  readonly packCount: number;
+  /** 获取所有对象数量 */
+  readonly objectCount: number;
+}
+/**
+ * 创建基于 Packfile 的对象源
+ *
+ * 扫描 .git/objects/pack/ 目录，加载所有 .idx 文件。
+ * packfile 数据按需加载（首次读取时才加载）。
+ *
+ * @param gitDir - .git 目录的路径
+ * @returns 基于 Packfile 的对象源
+ *
+ * @example
+ * ```ts
+ * const store = createPackObjectStore("/path/to/.git");
+ *
+ * // 读取原始对象
+ * const raw = store.read(hash);
+ *
+ * // 检查对象是否存在
+ * if (store.exists(hash)) {
+ *   console.log("对象在 packfile 中");
+ * }
+ * ```
+ */
+declare function createPackObjectStore(gitDir: string): PackObjectStore;
+//#endregion
+export { PackObjectStore, createPackObjectStore };

package/dist/pack/pack-store.mjs

@@ -0,0 +1,114 @@
+import { ObjectNotFoundError } from "../core/errors.mjs";
+import { packObjectToRaw } from "./pack-reader-types.mjs";
+import { getPackReader, loadPackPairs, toPackFileInfo } from "./pack-store-loader.mjs";
+import { join } from "node:path";
+//#region src/pack/pack-store.ts
+/**
+* 基于 Packfile 的对象源（raw-first）
+*
+* 从 .git/objects/pack/ 目录中读取 packfile 和索引文件，
+* 提供只读的原始对象读取接口。
+*
+* Git 的 pack 目录结构：
+* - pack-<checksum>.pack  — 打包的对象数据
+* - pack-<checksum>.idx   — 对应的索引文件
+*
+* @example
+* ```ts
+* const store = createPackObjectStore("/path/to/.git");
+* const raw = store.read(hash);
+* ```
+*/
+/**
+* 创建基于 Packfile 的对象源
+*
+* 扫描 .git/objects/pack/ 目录，加载所有 .idx 文件。
+* packfile 数据按需加载（首次读取时才加载）。
+*
+* @param gitDir - .git 目录的路径
+* @returns 基于 Packfile 的对象源
+*
+* @example
+* ```ts
+* const store = createPackObjectStore("/path/to/.git");
+*
+* // 读取原始对象
+* const raw = store.read(hash);
+*
+* // 检查对象是否存在
+* if (store.exists(hash)) {
+*   console.log("对象在 packfile 中");
+* }
+* ```
+*/
+function createPackObjectStore(gitDir) {
+	const packDir = join(gitDir, "objects", "pack");
+	const pairs = [];
+	let loaded = false;
+	/**
+	* 扫描 pack 目录并加载索引
+	*/
+	function ensureLoaded() {
+		if (loaded) return;
+		loaded = true;
+		pairs.push(...loadPackPairs(packDir));
+	}
+	function read(hash) {
+		ensureLoaded();
+		for (const pair of pairs) if (pair.index.lookup(hash)) {
+			const obj = getPackReader(packDir, pair).getByHash(hash);
+			if (obj) return packObjectToRaw(obj);
+		}
+		throw new ObjectNotFoundError(hash);
+	}
+	function tryRead(hash) {
+		ensureLoaded();
+		for (const pair of pairs) if (pair.index.lookup(hash)) {
+			const obj = getPackReader(packDir, pair).getByHash(hash);
+			if (obj) return packObjectToRaw(obj);
+		}
+	}
+	function exists(hash) {
+		ensureLoaded();
+		for (const pair of pairs) if (pair.index.has(hash)) return true;
+		return false;
+	}
+	function list() {
+		ensureLoaded();
+		const hashes = [];
+		for (const pair of pairs) hashes.push(...pair.index.listHashes());
+		return hashes;
+	}
+	function listHashes() {
+		return list();
+	}
+	function listPacks() {
+		ensureLoaded();
+		return pairs.map((pair) => toPackFileInfo(packDir, pair));
+	}
+	function refresh() {
+		loaded = false;
+		pairs.length = 0;
+	}
+	return {
+		refresh,
+		read,
+		tryRead,
+		exists,
+		list,
+		listHashes,
+		listPacks,
+		get packCount() {
+			ensureLoaded();
+			return pairs.length;
+		},
+		get objectCount() {
+			ensureLoaded();
+			let count = 0;
+			for (const pair of pairs) count += pair.index.objectCount;
+			return count;
+		}
+	};
+}
+//#endregion
+export { createPackObjectStore };

package/dist/pack/pack-writer.mjs

@@ -0,0 +1,96 @@
+import { buildEncodedPack, toEncodedPackObject } from "./pack-encoding.mjs";
+//#region src/pack/pack-writer.ts
+/**
+* Packfile 写入
+*
+* 将多个 Git 对象打包成一个 packfile。
+*
+* Packfile 格式：
+* - 头部：4 字节签名 "PACK" + 4 字节版本 + 4 字节对象数
+* - 对象序列：每个对象包含头部 + zlib 压缩数据
+* - 尾部：20 字节 SHA-1 校验和（对整个 packfile 的哈希）
+*
+* 当前实现不生成 delta 对象，所有对象都以非 delta 形式存储。
+* 这简化了实现，但牺牲了一些压缩效率。
+*
+* @example
+* ```ts
+* const writer = createPackWriter();
+* writer.addObject({ type: "blob", content: Buffer.from("hello") });
+* const packData = writer.build();
+* ```
+*/
+/**
+* 创建 Packfile 写入器
+*
+* @returns Packfile 写入器实例
+*
+* @example
+* ```ts
+* const writer = createPackWriter();
+*
+* // 添加对象
+* writer.addObject({ type: "blob", content: Buffer.from("hello") });
+* writer.addObject({ type: "blob", content: Buffer.from("world") });
+*
+* // 构建 packfile
+* const packData = writer.build();
+* ```
+*/
+function createPackWriter() {
+	return new PackWriter();
+}
+/**
+* Packfile 写入器类
+*/
+var PackWriter = class {
+	entries = [];
+	hashes = /* @__PURE__ */ new Set();
+	/**
+	* 添加一个原始对象到 packfile
+	*
+	* @param raw - 原始 Git 对象
+	* @returns 对象的 SHA-1 哈希
+	*
+	* @example
+	* ```ts
+	* const hash = writer.addRaw(raw);
+	* ```
+	*/
+	addRaw(raw) {
+		const entry = toEncodedPackObject(raw);
+		const hash = entry.hash;
+		if (this.hashes.has(hash)) return hash;
+		this.entries.push(entry);
+		this.hashes.add(hash);
+		return hash;
+	}
+	/**
+	* 获取已添加的对象数量
+	*/
+	get objectCount() {
+		return this.entries.length;
+	}
+	/**
+	* 构建 packfile 数据
+	*
+	* @returns 完整的 packfile 二进制数据
+	*
+	* @example
+	* ```ts
+	* const packData = writer.build();
+	* writeFileSync("objects/pack/pack-xxx.pack", packData);
+	* ```
+	*/
+	build() {
+		return buildEncodedPack(this.entries).packData;
+	}
+	/**
+	* 获取所有已添加对象的哈希列表
+	*/
+	listHashes() {
+		return this.entries.map((e) => e.hash);
+	}
+};
+//#endregion
+export { createPackWriter };

package/dist/pack/varint.d.mts

@@ -0,0 +1,34 @@
+//#region src/pack/varint.d.ts
+/**
+ * Packfile 通用变长整数编码/解码
+ */
+/**
+ * 解码变长整数（通用版本）
+ *
+ * 用于 delta 指令中的变长整数，每个字节高 1 位是继续标志，
+ * 低 7 位是数据，小端序。
+ *
+ * @param buf - 数据缓冲区
+ * @param offset - 起始偏移量
+ * @returns [值, 消耗的字节数]
+ *
+ * @example
+ * ```ts
+ * const [value, bytesRead] = decodeVarint(buf, 0);
+ * ```
+ */
+declare function decodeVarint(buf: Buffer, offset: number): [value: number, bytesRead: number];
+/**
+ * 编码变长整数（通用版本）
+ *
+ * @param value - 要编码的值
+ * @returns 编码后的字节缓冲区
+ *
+ * @example
+ * ```ts
+ * const encoded = encodeVarint(123);
+ * ```
+ */
+declare function encodeVarint(value: number): Buffer;
+//#endregion
+export { decodeVarint, encodeVarint };

package/dist/pack/varint.mjs

@@ -0,0 +1,57 @@
+import { InvalidPackError } from "../core/errors.mjs";
+//#region src/pack/varint.ts
+/**
+* Packfile 通用变长整数编码/解码
+*/
+/**
+* 解码变长整数（通用版本）
+*
+* 用于 delta 指令中的变长整数，每个字节高 1 位是继续标志，
+* 低 7 位是数据，小端序。
+*
+* @param buf - 数据缓冲区
+* @param offset - 起始偏移量
+* @returns [值, 消耗的字节数]
+*
+* @example
+* ```ts
+* const [value, bytesRead] = decodeVarint(buf, 0);
+* ```
+*/
+function decodeVarint(buf, offset) {
+	let value = 0;
+	let shift = 0;
+	let bytesRead = 0;
+	let byte;
+	do {
+		if (offset + bytesRead >= buf.length) throw new InvalidPackError("Unexpected end of data in varint");
+		byte = buf[offset + bytesRead];
+		value |= (byte & 127) << shift;
+		shift += 7;
+		bytesRead++;
+	} while (byte & 128);
+	return [value, bytesRead];
+}
+/**
+* 编码变长整数（通用版本）
+*
+* @param value - 要编码的值
+* @returns 编码后的字节缓冲区
+*
+* @example
+* ```ts
+* const encoded = encodeVarint(123);
+* ```
+*/
+function encodeVarint(value) {
+	const bytes = [];
+	do {
+		let byte = value & 127;
+		value >>>= 7;
+		if (value > 0) byte |= 128;
+		bytes.push(byte);
+	} while (value > 0);
+	return Buffer.from(bytes);
+}
+//#endregion
+export { decodeVarint, encodeVarint };

package/dist/refs/file.d.mts

@@ -0,0 +1,6 @@
+import { RefStore } from "../core/types/refs.mjs";
+
+//#region src/refs/file.d.ts
+declare function createFileRefStore(gitDir: string): RefStore;
+//#endregion
+export { createFileRefStore };