nano-git 0.1.0

package/dist/pack/pack-index-reader.d.mts

@@ -0,0 +1,57 @@
+import { SHA1 } from "../core/types.mjs";
+import { PackIndexEntry } from "./pack-index-types.mjs";
+
+//#region src/pack/pack-index-reader.d.ts
+/**
+ * Packfile 索引读取器接口
+ */
+interface PackIndexReader {
+  /** 对象数量 */
+  readonly objectCount: number;
+  /**
+   * 查找对象的索引条目
+   *
+   * @param hash - 对象的 SHA-1 哈希
+   * @returns 索引条目，如果不存在则返回 undefined
+   *
+   * @example
+   * ```ts
+   * const entry = index.lookup(hash);
+   * console.log(entry?.offset);
+   * ```
+   */
+  lookup(hash: SHA1): PackIndexEntry | undefined;
+  /**
+   * 检查对象是否存在
+   *
+   * @example
+   * ```ts
+   * const exists = index.has(hash);
+   * ```
+   */
+  has(hash: SHA1): boolean;
+  /**
+   * 获取所有对象的哈希列表
+   *
+   * @example
+   * ```ts
+   * const hashes = index.listHashes();
+   * ```
+   */
+  listHashes(): SHA1[];
+}
+/**
+ * 创建 Packfile 索引读取器
+ *
+ * @param data - 完整的 .idx 文件数据
+ * @returns 索引读取器实例
+ *
+ * @example
+ * ```ts
+ * const index = createPackIndexReader(idxData);
+ * console.log(index.objectCount);
+ * ```
+ */
+declare function createPackIndexReader(data: Buffer): PackIndexReader;
+//#endregion
+export { PackIndexReader, createPackIndexReader };

package/dist/pack/pack-index-reader.mjs

@@ -0,0 +1,90 @@
+import { PackIndexError } from "../core/errors.mjs";
+import { sha1 } from "../core/types.mjs";
+import { IDX_V2_FANOUT_SIZE, IDX_V2_SIGNATURE } from "./constants.mjs";
+//#region src/pack/pack-index-reader.ts
+/**
+* Packfile 索引读取
+*/
+/**
+* 创建 Packfile 索引读取器
+*
+* @param data - 完整的 .idx 文件数据
+* @returns 索引读取器实例
+*
+* @example
+* ```ts
+* const index = createPackIndexReader(idxData);
+* console.log(index.objectCount);
+* ```
+*/
+function createPackIndexReader(data) {
+	if (data.length < 8) throw new PackIndexError("Index file too small");
+	const signature = data.subarray(0, 4);
+	if (!signature.equals(IDX_V2_SIGNATURE)) throw new PackIndexError(`Invalid signature: ${signature.toString("hex")}`);
+	const version = data.readUInt32BE(4);
+	if (version !== 2) throw new PackIndexError(`Unsupported version: ${version}`);
+	const fanout = [];
+	const fanoutStart = 8;
+	for (let i = 0; i < 256; i++) fanout.push(data.readUInt32BE(fanoutStart + i * 4));
+	const _objectCount = fanout[255];
+	const sha1TableOffset = 8 + IDX_V2_FANOUT_SIZE;
+	const crc32TableOffset = sha1TableOffset + _objectCount * 20;
+	const offsetTableOffset = crc32TableOffset + _objectCount * 4;
+	const largeOffsetTable = offsetTableOffset + _objectCount * 4;
+	/**
+	* 获取指定索引位置的哈希
+	*/
+	function getHashAt(index) {
+		const offset = sha1TableOffset + index * 20;
+		return data.subarray(offset, offset + 20).toString("hex");
+	}
+	/**
+	* 获取指定索引位置的条目
+	*/
+	function getEntryAt(index) {
+		const hash = sha1(getHashAt(index));
+		const crc32 = data.readUInt32BE(crc32TableOffset + index * 4);
+		let offset = data.readUInt32BE(offsetTableOffset + index * 4);
+		if (offset & 2147483648) {
+			const largeIndex = offset & 2147483647;
+			offset = Number(data.readBigUInt64BE(largeOffsetTable + largeIndex * 8));
+		}
+		return {
+			hash,
+			offset,
+			crc32
+		};
+	}
+	function lookup(hash) {
+		const firstByte = parseInt(hash.slice(0, 2), 16);
+		const start = firstByte > 0 ? fanout[firstByte - 1] : 0;
+		const end = fanout[firstByte];
+		let low = start;
+		let high = end;
+		while (low < high) {
+			const mid = Math.floor((low + high) / 2);
+			const cmp = getHashAt(mid).localeCompare(hash);
+			if (cmp < 0) low = mid + 1;
+			else if (cmp > 0) high = mid;
+			else return getEntryAt(mid);
+		}
+	}
+	function has(hash) {
+		return lookup(hash) !== void 0;
+	}
+	function listHashes() {
+		const hashes = [];
+		for (let i = 0; i < _objectCount; i++) hashes.push(sha1(getHashAt(i)));
+		return hashes;
+	}
+	return {
+		get objectCount() {
+			return _objectCount;
+		},
+		lookup,
+		has,
+		listHashes
+	};
+}
+//#endregion
+export { createPackIndexReader };

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

@@ -0,0 +1,16 @@
+import { SHA1 } from "../core/types.mjs";
+
+//#region src/pack/pack-index-types.d.ts
+/**
+ * 索引中的对象条目
+ */
+interface PackIndexEntry {
+  /** 对象的 SHA-1 哈希 */
+  hash: SHA1;
+  /** 对象在 packfile 中的偏移量 */
+  offset: number;
+  /** 压缩数据的 CRC32 校验和 */
+  crc32: number;
+}
+//#endregion
+export { PackIndexEntry };

package/dist/pack/pack-index-writer.d.mts

@@ -0,0 +1,45 @@
+import { PackIndexEntry } from "./pack-index-types.mjs";
+
+//#region src/pack/pack-index-writer.d.ts
+/**
+ * Packfile 索引写入器接口
+ */
+interface PackIndexWriter {
+  /**
+   * 添加一个索引条目
+   *
+   * @param entry - 索引条目
+   *
+   * @example
+   * ```ts
+   * writer.addEntry({ hash, offset: 12, crc32: 0x12345678 });
+   * ```
+   */
+  addEntry(entry: PackIndexEntry): void;
+  /**
+   * 构建索引文件数据
+   *
+   * @param packChecksum - packfile 的 SHA-1 校验和（20 字节）
+   * @returns 完整的 .idx 文件数据
+   *
+   * @example
+   * ```ts
+   * const idxData = writer.build(packChecksum);
+   * ```
+   */
+  build(packChecksum: Buffer): Buffer;
+}
+/**
+ * 创建 Packfile 索引写入器
+ *
+ * @returns 索引写入器实例
+ *
+ * @example
+ * ```ts
+ * const writer = createPackIndexWriter();
+ * writer.addEntry({ hash, offset: 12, crc32: 0x12345678 });
+ * ```
+ */
+declare function createPackIndexWriter(): PackIndexWriter;
+//#endregion
+export { PackIndexWriter, createPackIndexWriter };

package/dist/pack/pack-index-writer.mjs

@@ -0,0 +1,106 @@
+import { IDX_V2_FANOUT_SIZE, IDX_V2_SIGNATURE } from "./constants.mjs";
+import { createHash } from "node:crypto";
+//#region src/pack/pack-index-writer.ts
+/**
+* Packfile 索引写入
+*/
+/**
+* 创建 Packfile 索引写入器
+*
+* @returns 索引写入器实例
+*
+* @example
+* ```ts
+* const writer = createPackIndexWriter();
+* writer.addEntry({ hash, offset: 12, crc32: 0x12345678 });
+* ```
+*/
+function createPackIndexWriter() {
+	const entries = [];
+	/**
+	* 构建头部
+	*/
+	function createHeader() {
+		const header = Buffer.alloc(8);
+		IDX_V2_SIGNATURE.copy(header, 0);
+		header.writeUInt32BE(2, 4);
+		return header;
+	}
+	/**
+	* 构建扇出表
+	*/
+	function createFanoutTable(entries) {
+		const fanout = Buffer.alloc(IDX_V2_FANOUT_SIZE);
+		let count = 0;
+		for (let i = 0; i < 256; i++) {
+			while (count < entries.length && parseInt(entries[count].hash.slice(0, 2), 16) <= i) count++;
+			fanout.writeUInt32BE(count, i * 4);
+		}
+		return fanout;
+	}
+	/**
+	* 构建 SHA-1 表
+	*/
+	function createSha1Table(entries) {
+		const sha1Table = Buffer.alloc(entries.length * 20);
+		for (let i = 0; i < entries.length; i++) Buffer.from(entries[i].hash, "hex").copy(sha1Table, i * 20);
+		return sha1Table;
+	}
+	/**
+	* 构建 CRC32 表
+	*/
+	function createCrc32Table(entries) {
+		const crc32Table = Buffer.alloc(entries.length * 4);
+		for (let i = 0; i < entries.length; i++) crc32Table.writeUInt32BE(entries[i].crc32 >>> 0, i * 4);
+		return crc32Table;
+	}
+	/**
+	* 构建偏移量表与大偏移量列表
+	*/
+	function createOffsetTables(entries) {
+		const offsetTable = Buffer.alloc(entries.length * 4);
+		const largeOffsets = [];
+		for (let i = 0; i < entries.length; i++) {
+			const offset = entries[i].offset;
+			if (offset >= 2147483648) {
+				const largeIndex = largeOffsets.length;
+				largeOffsets.push(offset);
+				offsetTable.writeUInt32BE(2147483648 | largeIndex, i * 4);
+			} else offsetTable.writeUInt32BE(offset, i * 4);
+		}
+		return {
+			offsetTable,
+			largeOffsets
+		};
+	}
+	/**
+	* 构建大偏移量表
+	*/
+	function createLargeOffsetTable(largeOffsets) {
+		const largeOffsetTable = Buffer.alloc(largeOffsets.length * 8);
+		for (let i = 0; i < largeOffsets.length; i++) largeOffsetTable.writeBigUInt64BE(BigInt(largeOffsets[i]), i * 8);
+		return largeOffsetTable;
+	}
+	return {
+		addEntry(entry) {
+			entries.push(entry);
+		},
+		build(packChecksum) {
+			const sorted = [...entries].sort((a, b) => a.hash.localeCompare(b.hash));
+			const parts = [];
+			parts.push(createHeader());
+			parts.push(createFanoutTable(sorted));
+			parts.push(createSha1Table(sorted));
+			parts.push(createCrc32Table(sorted));
+			const { offsetTable, largeOffsets } = createOffsetTables(sorted);
+			parts.push(offsetTable);
+			if (largeOffsets.length > 0) parts.push(createLargeOffsetTable(largeOffsets));
+			parts.push(packChecksum);
+			const idxWithoutChecksum = Buffer.concat(parts);
+			const idxChecksum = createHash("sha1").update(idxWithoutChecksum).digest();
+			return Buffer.concat([idxWithoutChecksum, idxChecksum]);
+		}
+	};
+}
+//#endregion
+export { createPackIndexWriter };

package/dist/pack/pack-reader-resolver.mjs

@@ -0,0 +1,104 @@
+import { InvalidPackError } from "../core/errors.mjs";
+import { hashObject } from "../core/hash-digest.mjs";
+import { numberToObjectType } from "./constants.mjs";
+import { applyDelta } from "./delta-apply.mjs";
+import { readCompressedData } from "./pack-reader-utils.mjs";
+//#region src/pack/pack-reader-resolver.ts
+/**
+* Packfile 对象解析辅助函数
+*/
+/**
+* 解析普通对象
+*
+* @param data - 完整的 packfile 数据
+* @param offset - 压缩数据起始偏移量
+* @param objOffset - 当前对象头起始偏移量
+* @param typeNum - pack 中的对象类型编号
+* @returns 解析结果和新的偏移量
+*
+* @example
+* ```ts
+* const result = resolvePlainPackObject(packData, offset, objOffset, 3);
+* ```
+*/
+function resolvePlainPackObject(data, offset, objOffset, typeNum) {
+	const type = numberToObjectType(typeNum);
+	const [compressedData, compressedBytes] = readCompressedData(data, offset);
+	const nextOffset = offset + compressedBytes;
+	return {
+		object: {
+			type,
+			hash: hashObject(type, compressedData),
+			offset: objOffset,
+			data: compressedData
+		},
+		nextOffset
+	};
+}
+/**
+* 解析基于偏移量的 delta 对象
+*
+* @param data - 完整的 packfile 数据
+* @param offset - delta 数据起始偏移量
+* @param objOffset - 当前对象头起始偏移量
+* @param negOffset - 相对 base object 的负偏移量
+* @param objectsByOffset - 已解析对象缓存
+* @returns 解析结果和新的偏移量
+*
+* @example
+* ```ts
+* const result = resolveOfsDeltaPackObject(data, offset, objOffset, 32, cache);
+* ```
+*/
+function resolveOfsDeltaPackObject(data, offset, objOffset, negOffset, objectsByOffset) {
+	const [deltaData, compressedBytes] = readCompressedData(data, offset);
+	const nextOffset = offset + compressedBytes;
+	const baseOffset = objOffset - negOffset;
+	const baseObj = objectsByOffset.get(baseOffset);
+	if (!baseObj) throw new InvalidPackError(`Base object not found at offset ${baseOffset}`);
+	const resolvedData = applyDelta(baseObj.data, deltaData);
+	const hash = hashObject(baseObj.type, resolvedData);
+	return {
+		object: {
+			type: baseObj.type,
+			hash,
+			offset: objOffset,
+			data: resolvedData
+		},
+		nextOffset
+	};
+}
+/**
+* 解析基于哈希的 delta 对象
+*
+* @param data - 完整的 packfile 数据
+* @param offset - delta 数据起始偏移量
+* @param objOffset - 当前对象头起始偏移量
+* @param baseHash - base object 的 SHA-1 十六进制字符串
+* @param objectsByHash - 已解析对象缓存
+* @returns 解析结果和新的偏移量
+*
+* @example
+* ```ts
+* const result = resolveRefDeltaPackObject(data, offset, objOffset, hash, cache);
+* ```
+*/
+function resolveRefDeltaPackObject(data, offset, objOffset, baseHash, objectsByHash) {
+	const [deltaData, compressedBytes] = readCompressedData(data, offset);
+	const nextOffset = offset + compressedBytes;
+	const baseObj = objectsByHash.get(baseHash);
+	if (!baseObj) throw new InvalidPackError(`Base object not found: ${baseHash}`);
+	const resolvedData = applyDelta(baseObj.data, deltaData);
+	const hash = hashObject(baseObj.type, resolvedData);
+	return {
+		object: {
+			type: baseObj.type,
+			hash,
+			offset: objOffset,
+			data: resolvedData
+		},
+		nextOffset
+	};
+}
+//#endregion
+export { resolveOfsDeltaPackObject, resolvePlainPackObject, resolveRefDeltaPackObject };

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

@@ -0,0 +1,31 @@
+import { ObjectType, RawGitObject, SHA1 } from "../core/types.mjs";
+
+//#region src/pack/pack-reader-types.d.ts
+/**
+ * Packfile 中的对象信息
+ */
+interface PackObject {
+  /** 对象类型 */
+  type: ObjectType;
+  /** 对象的 SHA-1 哈希 */
+  hash: SHA1;
+  /** 对象在 packfile 中的偏移量 */
+  offset: number;
+  /** 解压后的原始数据（对应 RawGitObject.content） */
+  data: Buffer;
+}
+/**
+ * 将 PackObject 转换为 RawGitObject
+ *
+ * @param packObj - packfile 中的对象
+ * @returns 可用于 ODB 的原始对象
+ *
+ * @example
+ * ```ts
+ * const raw = packObjectToRaw(packObj);
+ * db.ingest(raw);
+ * ```
+ */
+declare function packObjectToRaw(packObj: PackObject): RawGitObject;
+//#endregion
+export { PackObject, packObjectToRaw };

package/dist/pack/pack-reader-types.mjs

@@ -0,0 +1,22 @@
+//#region src/pack/pack-reader-types.ts
+/**
+* 将 PackObject 转换为 RawGitObject
+*
+* @param packObj - packfile 中的对象
+* @returns 可用于 ODB 的原始对象
+*
+* @example
+* ```ts
+* const raw = packObjectToRaw(packObj);
+* db.ingest(raw);
+* ```
+*/
+function packObjectToRaw(packObj) {
+	return {
+		hash: packObj.hash,
+		type: packObj.type,
+		content: packObj.data
+	};
+}
+//#endregion
+export { packObjectToRaw };

package/dist/pack/pack-reader-utils.mjs

@@ -0,0 +1,61 @@
+import { InvalidPackError } from "../core/errors.mjs";
+import { PACK_SIGNATURE } from "./constants.mjs";
+import { createHash } from "node:crypto";
+import { inflateSync } from "node:zlib";
+//#region src/pack/pack-reader-utils.ts
+/**
+* Packfile 读取底层辅助函数
+*/
+/**
+* 解析并校验 packfile 头部
+*
+* @param data - 完整的 packfile 数据
+* @returns 对象数量
+*
+* @example
+* ```ts
+* const objectCount = parsePackHeader(packData);
+* ```
+*/
+function parsePackHeader(data) {
+	if (data.length < 32) throw new InvalidPackError("Packfile too small");
+	const signature = data.subarray(0, 4);
+	if (!signature.equals(PACK_SIGNATURE)) throw new InvalidPackError(`Invalid signature: ${signature.toString("hex")}`);
+	const version = data.readUInt32BE(4);
+	if (version !== 2) throw new InvalidPackError(`Unsupported version: ${version}`);
+	const objectCount = data.readUInt32BE(8);
+	const expectedChecksum = data.subarray(data.length - 20);
+	const actualChecksum = createHash("sha1").update(data.subarray(0, data.length - 20)).digest();
+	if (!expectedChecksum.equals(actualChecksum)) throw new InvalidPackError("Checksum mismatch");
+	return objectCount;
+}
+/**
+* 读取 zlib 压缩的数据
+*
+* 使用 zlib 的 `info` 选项获取实际消耗的输入字节数，
+* 从而精确定位下一个对象的起始偏移量。
+*
+* @param data - 完整的 packfile 数据
+* @param offset - 压缩数据的起始偏移量
+* @returns 解压结果和消耗的字节数
+*
+* @example
+* ```ts
+* const [buffer, bytesRead] = readCompressedData(packData, 12);
+* ```
+*/
+function readCompressedData(data, offset) {
+	const remaining = data.subarray(offset);
+	try {
+		const inflated = inflateSync(remaining, { info: true });
+		if (!inflated || typeof inflated !== "object" || !("buffer" in inflated) || !("engine" in inflated)) throw new InvalidPackError("Unexpected inflate result shape");
+		const result = inflated;
+		const consumed = result.engine?.bytesWritten;
+		if (typeof consumed !== "number" || consumed <= 0) throw new InvalidPackError("Failed to determine compressed stream length");
+		return [Buffer.from(result.buffer), consumed];
+	} catch (err) {
+		throw new InvalidPackError(`Failed to decompress data at offset ${offset}: ${String(err)}`);
+	}
+}
+//#endregion
+export { parsePackHeader, readCompressedData };

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

@@ -0,0 +1,81 @@
+import { SHA1 } from "../core/types.mjs";
+import { PackObject, packObjectToRaw } from "./pack-reader-types.mjs";
+
+//#region src/pack/pack-reader.d.ts
+/**
+ * 创建 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}`);
+ * }
+ * ```
+ */
+declare function createPackReader(data: Buffer): PackReader;
+/**
+ * Packfile 读取器类
+ *
+ * 使用惰性解析策略：对象在首次被访问时才解析。
+ * - getByHash() / getByOffset() / has() 只解析到找到目标为止
+ * - objects() / listHashes() 解析全部对象
+ */
+declare class PackReader {
+  private readonly data;
+  private readonly _objectCount;
+  private readonly objectsByOffset;
+  private readonly objectsByHash;
+  private parseOffset;
+  private parsedCount;
+  private fullyParsed;
+  constructor(data: Buffer);
+  /** 对象数量 */
+  get objectCount(): number;
+  /**
+   * 解析下一个对象
+   */
+  private parseNext;
+  /**
+   * 按需解析直到条件满足或解析全部
+   */
+  private parseUntil;
+  /**
+   * 解析所有剩余对象
+   */
+  private parseAllRemaining;
+  /**
+   * 遍历所有对象
+   *
+   * 按 offset 顺序解析并迭代所有对象。
+   */
+  objects(): Generator<PackObject>;
+  /**
+   * 根据哈希获取对象（惰性解析）
+   *
+   * 只解析到找到目标对象为止，不解析全部。
+   */
+  getByHash(hash: SHA1): PackObject | undefined;
+  /**
+   * 根据偏移量获取对象（惰性解析）
+   *
+   * 只解析到目标偏移位置为止。
+   */
+  getByOffset(offset: number): PackObject | undefined;
+  /**
+   * 检查对象是否存在（惰性查找）
+   */
+  has(hash: SHA1): boolean;
+  /**
+   * 获取所有对象的哈希列表（解析全部）
+   */
+  listHashes(): SHA1[];
+}
+//#endregion
+export { createPackReader };