nano-git 0.1.0

package/dist/objects/commit.mjs

@@ -0,0 +1,160 @@
+import { InvalidObjectError } from "../core/errors.mjs";
+import { sha1 } from "../core/types.mjs";
+import { formatAuthor, parseAuthor } from "./author.mjs";
+//#region src/objects/commit.ts
+/**
+* Commit 对象序列化/反序列化
+*
+* Commit 的文本格式：
+* ```
+* tree <hash>
+* parent <hash>
+* parent <hash>
+* author <name> <email> <timestamp> <timezone>
+* committer <name> <email> <timestamp> <timezone>
+*
+* <message>
+* ```
+*/
+const BUILTIN_COMMIT_HEADERS = /* @__PURE__ */ new Set([
+	"tree",
+	"parent",
+	"author",
+	"committer",
+	"encoding",
+	"gpgsig",
+	"mergetag"
+]);
+function validateExtraHeaderName(name) {
+	if (name.length === 0 || /\s/.test(name) || name.includes("\0")) throw new InvalidObjectError(`invalid commit extra header name: ${name}`);
+	if (BUILTIN_COMMIT_HEADERS.has(name)) throw new InvalidObjectError(`commit extra header "${name}" 与内建字段冲突，请改用对应的专用字段。`);
+}
+function parseCommitHeaders(headerText) {
+	if (headerText.length === 0) return [];
+	const rawLines = headerText.split("\n");
+	const headers = [];
+	let current;
+	for (const line of rawLines) {
+		if (line.startsWith(" ")) {
+			if (!current) throw new InvalidObjectError("invalid commit header continuation without base header");
+			current.value += `\n${line.slice(1)}`;
+			continue;
+		}
+		const spaceIndex = line.indexOf(" ");
+		if (spaceIndex === -1) throw new InvalidObjectError(`invalid commit header: ${line}`);
+		current = {
+			name: line.slice(0, spaceIndex),
+			value: line.slice(spaceIndex + 1)
+		};
+		headers.push(current);
+	}
+	return headers;
+}
+function applyParsedHeader(state, header) {
+	switch (header.name) {
+		case "tree":
+			if (state.tree !== void 0) throw new InvalidObjectError("commit has multiple tree headers");
+			state.tree = sha1(header.value);
+			return;
+		case "parent":
+			state.parents.push(sha1(header.value));
+			return;
+		case "author":
+			if (state.author !== void 0) throw new InvalidObjectError("commit has multiple author headers");
+			state.author = parseAuthor(header.value);
+			return;
+		case "committer":
+			if (state.committer !== void 0) throw new InvalidObjectError("commit has multiple committer headers");
+			state.committer = parseAuthor(header.value);
+			return;
+		case "encoding":
+			if (state.encoding !== void 0) throw new InvalidObjectError("commit has multiple encoding headers");
+			state.encoding = header.value;
+			return;
+		case "gpgsig":
+			if (state.gpgsig !== void 0) throw new InvalidObjectError("commit has multiple gpgsig headers");
+			state.gpgsig = header.value;
+			return;
+		case "mergetag":
+			state.mergetag.push(header.value);
+			return;
+		default: state.extraHeaders.push({
+			name: header.name,
+			value: header.value
+		});
+	}
+}
+function encodeCommitHeader(name, value) {
+	const parts = value.split("\n");
+	const encoded = [`${name} ${parts[0] ?? ""}`];
+	for (let i = 1; i < parts.length; i++) encoded.push(` ${parts[i] ?? ""}`);
+	return encoded;
+}
+function buildCommitHeaderLines(commit) {
+	const lines = [];
+	lines.push(`tree ${commit.tree}`);
+	for (const parent of commit.parents) lines.push(`parent ${parent}`);
+	lines.push(`author ${formatAuthor(commit.author)}`);
+	lines.push(`committer ${formatAuthor(commit.committer)}`);
+	if (commit.encoding !== void 0) lines.push(...encodeCommitHeader("encoding", commit.encoding));
+	if (commit.gpgsig !== void 0) lines.push(...encodeCommitHeader("gpgsig", commit.gpgsig));
+	for (const tag of commit.mergetag ?? []) lines.push(...encodeCommitHeader("mergetag", tag));
+	for (const header of commit.extraHeaders ?? []) {
+		validateExtraHeaderName(header.name);
+		lines.push(...encodeCommitHeader(header.name, header.value));
+	}
+	return lines;
+}
+/**
+* 序列化 Commit 对象
+*
+* @example
+* ```ts
+* const commit: GitCommit = {
+*   type: "commit",
+*   tree: sha1("abc..."),
+*   parents: [],
+*   author: { name: "John", email: "j@e.com", timestamp: 123, timezone: "+0800" },
+*   committer: { name: "John", email: "j@e.com", timestamp: 123, timezone: "+0800" },
+*   message: "Initial commit",
+* };
+* const buf = serializeCommit(commit);
+* ```
+*/
+function serializeCommit(commit) {
+	const headerLines = buildCommitHeaderLines(commit);
+	return Buffer.from(`${headerLines.join("\n")}\n\n${commit.message.replace(/\n+$/, "")}\n`, "utf-8");
+}
+/**
+* 反序列化 Commit 对象
+*/
+function deserializeCommit(content) {
+	const text = content.toString("utf-8");
+	const separatorIndex = text.indexOf("\n\n");
+	const headerText = separatorIndex === -1 ? text : text.slice(0, separatorIndex);
+	const rawMessage = separatorIndex === -1 ? "" : text.slice(separatorIndex + 2);
+	const parsedHeaders = parseCommitHeaders(headerText);
+	const state = {
+		parents: [],
+		mergetag: [],
+		extraHeaders: []
+	};
+	for (const header of parsedHeaders) applyParsedHeader(state, header);
+	if (!state.tree) throw new InvalidObjectError("commit missing tree");
+	if (!state.author) throw new InvalidObjectError("commit missing author");
+	if (!state.committer) throw new InvalidObjectError("commit missing committer");
+	return {
+		type: "commit",
+		tree: state.tree,
+		parents: state.parents,
+		author: state.author,
+		committer: state.committer,
+		encoding: state.encoding,
+		gpgsig: state.gpgsig,
+		mergetag: state.mergetag.length > 0 ? state.mergetag : void 0,
+		extraHeaders: state.extraHeaders.length > 0 ? state.extraHeaders : void 0,
+		message: rawMessage.replace(/\n$/, "")
+	};
+}
+//#endregion
+export { deserializeCommit, serializeCommit };

package/dist/objects/index.d.mts

@@ -0,0 +1,8 @@
+import { deserializeBlob, serializeBlob } from "./blob.mjs";
+import { deserializeTree, serializeTree } from "./tree.mjs";
+import { deserializeCommit, serializeCommit } from "./commit.mjs";
+import { deserializeTag, serializeTag } from "./tag.mjs";
+import { formatAuthor, parseAuthor } from "./author.mjs";
+import { deserialize, deserializeContent, serialize, serializeContent } from "./codec.mjs";
+import { decodeObject, encodeObject, readObject, tryReadObject, writeObject } from "./raw.mjs";
+export { decodeObject, deserialize, deserializeBlob, deserializeCommit, deserializeContent, deserializeTag, deserializeTree, encodeObject, formatAuthor, parseAuthor, readObject, serialize, serializeBlob, serializeCommit, serializeContent, serializeTag, serializeTree, tryReadObject, writeObject };

package/dist/objects/index.mjs

@@ -0,0 +1,8 @@
+import { deserializeBlob, serializeBlob } from "./blob.mjs";
+import { deserializeTree, serializeTree } from "./tree.mjs";
+import { formatAuthor, parseAuthor } from "./author.mjs";
+import { deserializeCommit, serializeCommit } from "./commit.mjs";
+import { deserializeTag, serializeTag } from "./tag.mjs";
+import { deserialize, deserializeContent, serialize, serializeContent } from "./codec.mjs";
+import { decodeObject, encodeObject, readObject, tryReadObject, writeObject } from "./raw.mjs";
+export { decodeObject, deserialize, deserializeBlob, deserializeCommit, deserializeContent, deserializeTag, deserializeTree, encodeObject, formatAuthor, parseAuthor, readObject, serialize, serializeBlob, serializeCommit, serializeContent, serializeTag, serializeTree, tryReadObject, writeObject };

package/dist/objects/raw.d.mts

@@ -0,0 +1,85 @@
+import { GitObject, RawGitObject, SHA1 } from "../core/types.mjs";
+import { ObjectDatabase, ObjectSource } from "../core/types/odb.mjs";
+
+//#region src/objects/raw.d.ts
+/**
+ * 将语义对象编码为 RawGitObject
+ *
+ * 内部复用 serializeContent() 计算内容字节，
+ * 并用 hashObject() 计算 canonical SHA-1。
+ *
+ * @param obj - 语义层 Git 对象
+ * @returns 可用于 ODB ingest 的原始对象
+ *
+ * @example
+ * ```ts
+ * const blob: GitBlob = { type: "blob", content: Buffer.from("hello") };
+ * const raw = encodeObject(blob);
+ * console.log(raw.hash); // => SHA-1
+ * console.log(raw.content); // => Buffer("hello")
+ * ```
+ */
+declare function encodeObject(obj: GitObject): RawGitObject;
+/**
+ * 将 RawGitObject 解码为语义对象
+ *
+ * 内部复用 deserializeContent() 解析对象内容。
+ *
+ * @param raw - 来自 ODB 的原始对象
+ * @returns 语义层 Git 对象（含类型特定的字段）
+ *
+ * @example
+ * ```ts
+ * const raw: RawGitObject = { hash, type: "blob", content: Buffer.from("hello") };
+ * const obj = decodeObject(raw);
+ * console.log(obj.type); // => "blob"
+ * ```
+ */
+declare function decodeObject(raw: RawGitObject): GitObject;
+/**
+ * 将语义对象写入对象数据库
+ *
+ * 先 encode 再 ingest，返回计算得到的哈希。
+ *
+ * @param db - 对象数据库
+ * @param obj - 语义层 Git 对象
+ * @returns 对象的 SHA-1 哈希
+ *
+ * @example
+ * ```ts
+ * const hash = writeObject(db, { type: "blob", content: Buffer.from("hello") });
+ * ```
+ */
+declare function writeObject(db: ObjectDatabase, obj: GitObject): SHA1;
+/**
+ * 从对象源读取并解码语义对象
+ *
+ * @param source - 只读对象源
+ * @param hash - 对象哈希
+ * @returns 语义层 Git 对象
+ *
+ * @example
+ * ```ts
+ * const obj = readObject(source, hash);
+ * if (obj.type === "commit") console.log(obj.message);
+ * ```
+ */
+declare function readObject(source: ObjectSource, hash: SHA1): GitObject;
+/**
+ * 尝试从对象源读取并解码语义对象
+ *
+ * 对象不存在时返回 undefined，不抛出异常。
+ *
+ * @param source - 只读对象源
+ * @param hash - 对象哈希
+ * @returns 语义层 Git 对象，或 undefined
+ *
+ * @example
+ * ```ts
+ * const obj = tryReadObject(source, hash);
+ * if (obj) { ... }
+ * ```
+ */
+declare function tryReadObject(source: ObjectSource, hash: SHA1): GitObject | undefined;
+//#endregion
+export { decodeObject, encodeObject, readObject, tryReadObject, writeObject };

package/dist/objects/raw.mjs

@@ -0,0 +1,111 @@
+import { hashObject } from "../core/hash-digest.mjs";
+import { deserializeContent, serializeContent } from "./codec.mjs";
+//#region src/objects/raw.ts
+/**
+* 语义层 <-> Raw 对象转换 helper
+*
+* ODB 的真实边界是 RawGitObject，不是 GitObject。
+* 本模块提供两者之间的双向转换工具，以及便捷的读写封装。
+*
+* 创建路径：GitObject → encodeObject() → RawGitObject → db.ingest()
+* 读取路径：source.read() → RawGitObject → decodeObject() → GitObject
+*/
+/**
+* 将语义对象编码为 RawGitObject
+*
+* 内部复用 serializeContent() 计算内容字节，
+* 并用 hashObject() 计算 canonical SHA-1。
+*
+* @param obj - 语义层 Git 对象
+* @returns 可用于 ODB ingest 的原始对象
+*
+* @example
+* ```ts
+* const blob: GitBlob = { type: "blob", content: Buffer.from("hello") };
+* const raw = encodeObject(blob);
+* console.log(raw.hash); // => SHA-1
+* console.log(raw.content); // => Buffer("hello")
+* ```
+*/
+function encodeObject(obj) {
+	const content = serializeContent(obj);
+	return {
+		hash: hashObject(obj.type, content),
+		type: obj.type,
+		content
+	};
+}
+/**
+* 将 RawGitObject 解码为语义对象
+*
+* 内部复用 deserializeContent() 解析对象内容。
+*
+* @param raw - 来自 ODB 的原始对象
+* @returns 语义层 Git 对象（含类型特定的字段）
+*
+* @example
+* ```ts
+* const raw: RawGitObject = { hash, type: "blob", content: Buffer.from("hello") };
+* const obj = decodeObject(raw);
+* console.log(obj.type); // => "blob"
+* ```
+*/
+function decodeObject(raw) {
+	return deserializeContent(raw.type, raw.content);
+}
+/**
+* 将语义对象写入对象数据库
+*
+* 先 encode 再 ingest，返回计算得到的哈希。
+*
+* @param db - 对象数据库
+* @param obj - 语义层 Git 对象
+* @returns 对象的 SHA-1 哈希
+*
+* @example
+* ```ts
+* const hash = writeObject(db, { type: "blob", content: Buffer.from("hello") });
+* ```
+*/
+function writeObject(db, obj) {
+	const raw = encodeObject(obj);
+	db.ingest(raw);
+	return raw.hash;
+}
+/**
+* 从对象源读取并解码语义对象
+*
+* @param source - 只读对象源
+* @param hash - 对象哈希
+* @returns 语义层 Git 对象
+*
+* @example
+* ```ts
+* const obj = readObject(source, hash);
+* if (obj.type === "commit") console.log(obj.message);
+* ```
+*/
+function readObject(source, hash) {
+	return decodeObject(source.read(hash));
+}
+/**
+* 尝试从对象源读取并解码语义对象
+*
+* 对象不存在时返回 undefined，不抛出异常。
+*
+* @param source - 只读对象源
+* @param hash - 对象哈希
+* @returns 语义层 Git 对象，或 undefined
+*
+* @example
+* ```ts
+* const obj = tryReadObject(source, hash);
+* if (obj) { ... }
+* ```
+*/
+function tryReadObject(source, hash) {
+	const raw = source.tryRead(hash);
+	return raw ? decodeObject(raw) : void 0;
+}
+//#endregion
+export { decodeObject, encodeObject, readObject, tryReadObject, writeObject };

package/dist/objects/tag.d.mts

@@ -0,0 +1,26 @@
+import { GitTag } from "../core/types.mjs";
+
+//#region src/objects/tag.d.ts
+/**
+ * 序列化 Tag 对象
+ *
+ * @example
+ * ```ts
+ * const tag: GitTag = {
+ *   type: "tag",
+ *   object: sha1("abc..."),
+ *   objectType: "commit",
+ *   tag: "v1.0.0",
+ *   tagger: { name: "John", email: "j@e.com", timestamp: 123, timezone: "+0800" },
+ *   message: "Release v1.0.0",
+ * };
+ * const buf = serializeTag(tag);
+ * ```
+ */
+declare function serializeTag(tag: GitTag): Buffer;
+/**
+ * 反序列化 Tag 对象
+ */
+declare function deserializeTag(content: Buffer): GitTag;
+//#endregion
+export { deserializeTag, serializeTag };

package/dist/objects/tag.mjs

@@ -0,0 +1,148 @@
+import { InvalidObjectError } from "../core/errors.mjs";
+import { assertObjectType, sha1 } from "../core/types.mjs";
+import { formatAuthor, parseAuthor } from "./author.mjs";
+//#region src/objects/tag.ts
+/**
+* Tag 对象序列化/反序列化
+*
+* Tag 的文本格式：
+* ```
+* object <hash>
+* type <type>
+* tag <name>
+* tagger <name> <email> <timestamp> <timezone>
+*
+* <message>
+* ```
+*/
+const BUILTIN_TAG_HEADERS = /* @__PURE__ */ new Set([
+	"object",
+	"type",
+	"tag",
+	"tagger",
+	"gpgsig"
+]);
+function validateExtraHeaderName(name) {
+	if (name.length === 0 || /\s/.test(name) || name.includes("\0")) throw new InvalidObjectError(`invalid tag extra header name: ${name}`);
+	if (BUILTIN_TAG_HEADERS.has(name)) throw new InvalidObjectError(`tag extra header "${name}" 与内建字段冲突，请改用对应的专用字段。`);
+}
+function parseTagHeaders(headerText) {
+	if (headerText.length === 0) return [];
+	const rawLines = headerText.split("\n");
+	const headers = [];
+	let current;
+	for (const line of rawLines) {
+		if (line.startsWith(" ")) {
+			if (!current) throw new InvalidObjectError("invalid tag header continuation without base header");
+			current.value += `\n${line.slice(1)}`;
+			continue;
+		}
+		const spaceIndex = line.indexOf(" ");
+		if (spaceIndex === -1) throw new InvalidObjectError(`invalid tag header: ${line}`);
+		current = {
+			name: line.slice(0, spaceIndex),
+			value: line.slice(spaceIndex + 1)
+		};
+		headers.push(current);
+	}
+	return headers;
+}
+function applyParsedHeader(state, header) {
+	switch (header.name) {
+		case "object":
+			if (state.object !== void 0) throw new InvalidObjectError("tag has multiple object headers");
+			state.object = sha1(header.value);
+			return;
+		case "type":
+			if (state.objectType !== void 0) throw new InvalidObjectError("tag has multiple type headers");
+			state.objectType = assertObjectType(header.value);
+			return;
+		case "tag":
+			if (state.tag !== void 0) throw new InvalidObjectError("tag has multiple tag headers");
+			state.tag = header.value;
+			return;
+		case "tagger":
+			if (state.tagger !== void 0) throw new InvalidObjectError("tag has multiple tagger headers");
+			state.tagger = parseAuthor(header.value);
+			return;
+		case "gpgsig":
+			if (state.gpgsig !== void 0) throw new InvalidObjectError("tag has multiple gpgsig headers");
+			state.gpgsig = header.value;
+			return;
+		default: state.extraHeaders.push({
+			name: header.name,
+			value: header.value
+		});
+	}
+}
+function encodeTagHeader(name, value) {
+	const parts = value.split("\n");
+	const encoded = [`${name} ${parts[0] ?? ""}`];
+	for (let i = 1; i < parts.length; i++) encoded.push(` ${parts[i] ?? ""}`);
+	return encoded;
+}
+function buildTagHeaderLines(tag) {
+	const lines = [];
+	lines.push(`object ${tag.object}`);
+	lines.push(`type ${tag.objectType}`);
+	lines.push(`tag ${tag.tag}`);
+	lines.push(`tagger ${formatAuthor(tag.tagger)}`);
+	if (tag.gpgsig !== void 0) lines.push(...encodeTagHeader("gpgsig", tag.gpgsig));
+	for (const header of tag.extraHeaders ?? []) {
+		validateExtraHeaderName(header.name);
+		lines.push(...encodeTagHeader(header.name, header.value));
+	}
+	return lines;
+}
+/**
+* 序列化 Tag 对象
+*
+* @example
+* ```ts
+* const tag: GitTag = {
+*   type: "tag",
+*   object: sha1("abc..."),
+*   objectType: "commit",
+*   tag: "v1.0.0",
+*   tagger: { name: "John", email: "j@e.com", timestamp: 123, timezone: "+0800" },
+*   message: "Release v1.0.0",
+* };
+* const buf = serializeTag(tag);
+* ```
+*/
+function serializeTag(tag) {
+	const lines = [
+		...buildTagHeaderLines(tag),
+		"",
+		tag.message.replace(/\n+$/, "")
+	];
+	return Buffer.from(lines.join("\n") + "\n", "utf-8");
+}
+/**
+* 反序列化 Tag 对象
+*/
+function deserializeTag(content) {
+	const text = content.toString("utf-8");
+	const headerEnd = text.indexOf("\n\n");
+	if (headerEnd === -1) throw new InvalidObjectError("tag missing header/body separator");
+	const parsedHeaders = parseTagHeaders(text.slice(0, headerEnd));
+	const state = { extraHeaders: [] };
+	for (const header of parsedHeaders) applyParsedHeader(state, header);
+	if (!state.object) throw new InvalidObjectError("tag missing object");
+	if (!state.objectType) throw new InvalidObjectError("tag missing type");
+	if (!state.tag) throw new InvalidObjectError("tag missing tag name");
+	if (!state.tagger) throw new InvalidObjectError("tag missing tagger");
+	const message = text.slice(headerEnd + 2).replace(/\n$/, "");
+	return {
+		type: "tag",
+		object: state.object,
+		objectType: state.objectType,
+		tag: state.tag,
+		tagger: state.tagger,
+		gpgsig: state.gpgsig,
+		extraHeaders: state.extraHeaders.length > 0 ? state.extraHeaders : void 0,
+		message
+	};
+}
+//#endregion
+export { deserializeTag, serializeTag };

package/dist/objects/tree.d.mts

@@ -0,0 +1,22 @@
+import { GitTree } from "../core/types.mjs";
+
+//#region src/objects/tree.d.ts
+/**
+ * 序列化 Tree 对象
+ *
+ * @example
+ * ```ts
+ * const tree: GitTree = {
+ *   type: "tree",
+ *   entries: [{ mode: "100644", name: "README.md", hash: sha1("abc...") }],
+ * };
+ * const buf = serializeTree(tree);
+ * ```
+ */
+declare function serializeTree(tree: GitTree): Buffer;
+/**
+ * 反序列化 Tree 对象
+ */
+declare function deserializeTree(content: Buffer): GitTree;
+//#endregion
+export { deserializeTree, serializeTree };

package/dist/objects/tree.mjs

@@ -0,0 +1,66 @@
+import { InvalidObjectError } from "../core/errors.mjs";
+import { sha1 } from "../core/types.mjs";
+//#region src/objects/tree.ts
+/**
+* Tree 对象序列化/反序列化
+*
+* Tree 对象存储目录结构，使用二进制格式：
+* 每个条目: "<mode> <name>\0<20-byte-hash>"
+* - mode: 文件模式（如 "100644"）
+* - name: 文件名
+* - hash: 20 字节的原始 SHA-1（不是十六进制字符串）
+*/
+/**
+* 序列化 Tree 对象
+*
+* @example
+* ```ts
+* const tree: GitTree = {
+*   type: "tree",
+*   entries: [{ mode: "100644", name: "README.md", hash: sha1("abc...") }],
+* };
+* const buf = serializeTree(tree);
+* ```
+*/
+function serializeTree(tree) {
+	const buffers = [];
+	for (const entry of tree.entries) {
+		const entryHeader = Buffer.from(`${entry.mode} ${entry.name}\0`, "utf-8");
+		const entryHash = Buffer.from(entry.hash, "hex");
+		if (entryHash.length !== 20) throw new InvalidObjectError(`invalid SHA-1 hash length: ${entryHash.length}`);
+		buffers.push(entryHeader, entryHash);
+	}
+	return Buffer.concat(buffers);
+}
+/**
+* 反序列化 Tree 对象
+*/
+function deserializeTree(content) {
+	const entries = [];
+	let offset = 0;
+	while (offset < content.length) {
+		const nullIndex = content.indexOf(0, offset);
+		if (nullIndex === -1) throw new InvalidObjectError("tree: missing null byte");
+		const entryHeader = content.subarray(offset, nullIndex).toString("utf-8");
+		const spaceIndex = entryHeader.indexOf(" ");
+		if (spaceIndex === -1) throw new InvalidObjectError(`invalid tree entry: ${entryHeader}`);
+		const mode = entryHeader.slice(0, spaceIndex);
+		const name = entryHeader.slice(spaceIndex + 1);
+		const hashStart = nullIndex + 1;
+		const hashEnd = hashStart + 20;
+		if (hashEnd > content.length) throw new InvalidObjectError("tree: truncated hash");
+		const hash = content.subarray(hashStart, hashEnd).toString("hex");
+		entries.push({
+			mode,
+			name,
+			hash: sha1(hash)
+		});
+		offset = hashEnd;
+	}
+	return {
+		type: "tree",
+		entries
+	};
+}
+//#endregion
+export { deserializeTree, serializeTree };