nano-git 0.1.0

package/dist/refs/file.mjs

@@ -0,0 +1,222 @@
+import { RefNotFoundError, TransactionError } from "../core/errors.mjs";
+import { validateRefName, validateRefPrefix } from "./names.mjs";
+import { listLooseRefsRecursive } from "./fs-utils.mjs";
+import { existsSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+//#region src/refs/file.ts
+/**
+* 基于文件系统的 Refs 存储
+*/
+function readPackedRefs(gitDir) {
+	const packedRefsPath = join(gitDir, "packed-refs");
+	if (!existsSync(packedRefsPath)) return /* @__PURE__ */ new Map();
+	const packedRefs = /* @__PURE__ */ new Map();
+	const lines = readFileSync(packedRefsPath, "utf-8").split("\n");
+	for (const line of lines) {
+		if (!line || line.startsWith("#") || line.startsWith("^")) continue;
+		const spaceIndex = line.indexOf(" ");
+		if (spaceIndex === -1) continue;
+		const hash = line.slice(0, spaceIndex);
+		const ref = line.slice(spaceIndex + 1);
+		packedRefs.set(ref, hash);
+	}
+	return packedRefs;
+}
+/**
+* 从 packed-refs 中删除指定引用
+*
+* 会同时删除该引用可能携带的 peeled 行（`^...`）。
+*
+* @param gitDir - Git 目录
+* @param ref - 完整引用路径
+* @returns 是否实际删除了 packed-refs 条目
+*/
+function deletePackedRef(gitDir, ref) {
+	const packedRefsPath = join(gitDir, "packed-refs");
+	if (!existsSync(packedRefsPath)) return false;
+	const lines = readFileSync(packedRefsPath, "utf-8").split("\n");
+	const keptLines = [];
+	let removed = false;
+	let skipNextPeeledLine = false;
+	for (const line of lines) {
+		if (skipNextPeeledLine && line.startsWith("^")) {
+			skipNextPeeledLine = false;
+			removed = true;
+			continue;
+		}
+		skipNextPeeledLine = false;
+		if (line.length === 0 || line.startsWith("#")) {
+			keptLines.push(line);
+			continue;
+		}
+		const spaceIndex = line.indexOf(" ");
+		if (spaceIndex === -1) {
+			keptLines.push(line);
+			continue;
+		}
+		if (line.slice(spaceIndex + 1) === ref) {
+			removed = true;
+			skipNextPeeledLine = true;
+			continue;
+		}
+		keptLines.push(line);
+	}
+	if (!removed) return false;
+	writeFileSync(packedRefsPath, keptLines.join("\n"));
+	return true;
+}
+/**
+* 创建基于文件系统的 Refs 存储
+*
+* @example
+* ```ts
+* const store = createFileRefStore("/path/to/repo/.git");
+* ```
+*/
+/**
+* Lock 文件路径
+*/
+function lockPath(gitDir, ref) {
+	return join(gitDir, ref) + ".lock";
+}
+/**
+* 创建 Lock 文件（占位）
+*
+* 如果 lock 文件已存在，说明有并发写入或残留 lock，抛出异常。
+*/
+function createLockFile(gitDir, ref) {
+	const lock = lockPath(gitDir, ref);
+	mkdirSync(dirname(lock), { recursive: true });
+	if (existsSync(lock)) throw new TransactionError(`Cannot lock ref "${ref}": lock file already exists. This may indicate a concurrent write or a stale lock file.`);
+	writeFileSync(lock, "");
+	return lock;
+}
+/**
+* 将 pending Map 冻结为只读快照
+*/
+function freezePending(pending) {
+	const writes = [];
+	const deletes = [];
+	for (const [ref, content] of pending) if (content === null) deletes.push({ ref });
+	else writes.push({
+		ref,
+		content
+	});
+	return Object.freeze({
+		pendingCount: pending.size,
+		writes: Object.freeze(writes),
+		deletes: Object.freeze(deletes)
+	});
+}
+function createFileRefStore(gitDir) {
+	function beginTransaction(hooks) {
+		const pending = /* @__PURE__ */ new Map();
+		let committed = false;
+		return {
+			get pendingCount() {
+				return pending.size;
+			},
+			write(ref, content) {
+				if (committed) throw new TransactionError("Transaction already committed");
+				validateRefName(ref);
+				pending.set(ref, content.trimEnd());
+			},
+			delete(ref) {
+				if (committed) throw new TransactionError("Transaction already committed");
+				validateRefName(ref);
+				const hasLooseRef = existsSync(join(gitDir, ref));
+				const hasPackedRef = readPackedRefs(gitDir).has(ref);
+				if (!hasLooseRef && !hasPackedRef && !pending.has(ref)) throw new RefNotFoundError(ref);
+				pending.set(ref, null);
+			},
+			commit() {
+				if (committed) throw new TransactionError("Transaction already committed");
+				committed = true;
+				const txSnapshot = freezePending(pending);
+				const locks = [];
+				try {
+					for (const refName of pending.keys()) {
+						const lock = createLockFile(gitDir, refName);
+						locks.push(lock);
+					}
+					for (const hook of hooks ?? []) hook.onPrepare?.(txSnapshot);
+					let idx = 0;
+					for (const [, content] of pending) {
+						const lock = locks[idx];
+						idx++;
+						if (content === null) writeFileSync(lock, "");
+						else writeFileSync(lock, `${content}\n`);
+					}
+					idx = 0;
+					for (const [ref, content] of pending) {
+						const lock = locks[idx];
+						idx++;
+						const target = join(gitDir, ref);
+						if (content === null) {
+							if (existsSync(target)) unlinkSync(target);
+							deletePackedRef(gitDir, ref);
+							unlinkSync(lock);
+						} else {
+							mkdirSync(dirname(target), { recursive: true });
+							renameSync(lock, target);
+							deletePackedRef(gitDir, ref);
+						}
+					}
+					for (const hook of hooks ?? []) hook.onCommitted?.(txSnapshot);
+				} catch (e) {
+					for (const lock of locks) try {
+						if (existsSync(lock)) unlinkSync(lock);
+					} catch {}
+					for (const hook of hooks ?? []) hook.onAborted?.(txSnapshot);
+					throw e;
+				}
+			},
+			rollback() {
+				if (committed) return;
+				committed = true;
+				const txSnapshot = freezePending(pending);
+				for (const hook of hooks ?? []) hook.onAborted?.(txSnapshot);
+			}
+		};
+	}
+	return {
+		read(ref) {
+			validateRefName(ref);
+			const refPath = join(gitDir, ref);
+			if (existsSync(refPath)) return readFileSync(refPath, "utf-8").trimEnd();
+			return readPackedRefs(gitDir).get(ref) ?? null;
+		},
+		write(ref, content) {
+			validateRefName(ref);
+			const refPath = join(gitDir, ref);
+			mkdirSync(dirname(refPath), { recursive: true });
+			writeFileSync(refPath, `${content.trimEnd()}\n`);
+		},
+		delete(ref) {
+			validateRefName(ref);
+			const refPath = join(gitDir, ref);
+			const hasLooseRef = existsSync(refPath);
+			const removedPackedRef = deletePackedRef(gitDir, ref);
+			if (!hasLooseRef && !removedPackedRef) throw new RefNotFoundError(ref);
+			if (hasLooseRef) unlinkSync(refPath);
+		},
+		list(prefix) {
+			validateRefPrefix(prefix);
+			const baseDir = join(gitDir, prefix);
+			const refs = /* @__PURE__ */ new Set();
+			if (existsSync(baseDir)) for (const ref of listLooseRefsRecursive(baseDir, prefix)) refs.add(ref);
+			for (const ref of readPackedRefs(gitDir).keys()) if (ref.startsWith(prefix)) refs.add(ref);
+			return Array.from(refs).sort();
+		},
+		listAll() {
+			const refs = /* @__PURE__ */ new Set();
+			const refsDir = join(gitDir, "refs");
+			if (existsSync(refsDir)) for (const ref of listLooseRefsRecursive(refsDir, "refs/")) refs.add(ref);
+			for (const ref of readPackedRefs(gitDir).keys()) if (ref.startsWith("refs/")) refs.add(ref);
+			return Array.from(refs).sort();
+		},
+		beginTransaction
+	};
+}
+//#endregion
+export { createFileRefStore };

package/dist/refs/fs-utils.mjs

@@ -0,0 +1,30 @@
+import { readdirSync, statSync } from "node:fs";
+import { join } from "node:path";
+//#region src/refs/fs-utils.ts
+/**
+* 文件系统 Refs 辅助函数
+*/
+/**
+* 递归列出目录下的所有引用文件
+*
+* @example
+* ```ts
+* const refs = listLooseRefsRecursive("/tmp/repo/.git/refs", "refs/");
+* ```
+*/
+function listLooseRefsRecursive(baseDir, prefix) {
+	const refs = [];
+	const entries = readdirSync(baseDir).sort();
+	for (const entry of entries) {
+		const fullPath = join(baseDir, entry);
+		const stat = statSync(fullPath);
+		if (stat.isDirectory()) {
+			refs.push(...listLooseRefsRecursive(fullPath, `${prefix}${entry}/`));
+			continue;
+		}
+		if (stat.isFile()) refs.push(`${prefix}${entry}`);
+	}
+	return refs;
+}
+//#endregion
+export { listLooseRefsRecursive };

package/dist/refs/memory.d.mts

@@ -0,0 +1,14 @@
+import { RefStore } from "../core/types/refs.mjs";
+
+//#region src/refs/memory.d.ts
+/**
+ * 创建基于内存的 Refs 存储
+ *
+ * @example
+ * ```ts
+ * const store = createMemoryRefStore();
+ * ```
+ */
+declare function createMemoryRefStore(initial?: Map<string, string>): RefStore;
+//#endregion
+export { createMemoryRefStore };

package/dist/refs/memory.mjs

@@ -0,0 +1,104 @@
+import { RefNotFoundError, TransactionError } from "../core/errors.mjs";
+import { validateRefName, validateRefPrefix } from "./names.mjs";
+//#region src/refs/memory.ts
+/**
+* 基于内存的 Refs 存储
+*/
+/**
+* 创建基于内存的 Refs 存储
+*
+* @example
+* ```ts
+* const store = createMemoryRefStore();
+* ```
+*/
+function createMemoryRefStore(initial) {
+	const active = new Map(initial);
+	function beginTransaction(hooks) {
+		const pending = /* @__PURE__ */ new Map();
+		const snapshot = new Map(active);
+		let committed = false;
+		return {
+			get pendingCount() {
+				return pending.size;
+			},
+			write(ref, content) {
+				if (committed) throw new TransactionError("Transaction already committed");
+				validateRefName(ref);
+				pending.set(ref, content.trimEnd());
+			},
+			delete(ref) {
+				if (committed) throw new TransactionError("Transaction already committed");
+				validateRefName(ref);
+				if (!active.has(ref) && !pending.has(ref)) throw new RefNotFoundError(ref);
+				pending.set(ref, null);
+			},
+			commit() {
+				if (committed) throw new TransactionError("Transaction already committed");
+				committed = true;
+				const txSnapshot = freezePending(pending);
+				try {
+					for (const hook of hooks ?? []) hook.onPrepare?.(txSnapshot);
+					for (const [ref, content] of pending) if (content === null) {
+						if (!active.has(ref)) throw new RefNotFoundError(ref);
+						active.delete(ref);
+					} else active.set(ref, content);
+					for (const hook of hooks ?? []) hook.onCommitted?.(txSnapshot);
+				} catch (e) {
+					active.clear();
+					for (const [k, v] of snapshot) active.set(k, v);
+					for (const hook of hooks ?? []) hook.onAborted?.(txSnapshot);
+					throw e;
+				}
+			},
+			rollback() {
+				if (committed) return;
+				committed = true;
+				const txSnapshot = freezePending(pending);
+				for (const hook of hooks ?? []) hook.onAborted?.(txSnapshot);
+			}
+		};
+	}
+	return {
+		read(ref) {
+			validateRefName(ref);
+			return active.get(ref) ?? null;
+		},
+		write(ref, content) {
+			validateRefName(ref);
+			active.set(ref, content.trimEnd());
+		},
+		delete(ref) {
+			validateRefName(ref);
+			if (!active.has(ref)) throw new RefNotFoundError(ref);
+			active.delete(ref);
+		},
+		list(prefix) {
+			validateRefPrefix(prefix);
+			return Array.from(active.keys()).filter((key) => key.startsWith(prefix)).sort();
+		},
+		listAll() {
+			return Array.from(active.keys()).filter((key) => key.startsWith("refs/")).sort();
+		},
+		beginTransaction
+	};
+}
+/**
+* 将 pending Map 冻结为只读快照
+*/
+function freezePending(pending) {
+	const writes = [];
+	const deletes = [];
+	for (const [ref, content] of pending) if (content === null) deletes.push({ ref });
+	else writes.push({
+		ref,
+		content
+	});
+	return Object.freeze({
+		pendingCount: pending.size,
+		writes: Object.freeze(writes),
+		deletes: Object.freeze(deletes)
+	});
+}
+//#endregion
+export { createMemoryRefStore };

package/dist/refs/names.d.mts

@@ -0,0 +1,57 @@
+//#region src/refs/names.d.ts
+/**
+ * Refs 名称校验与名称转换工具
+ */
+/**
+ * 验证引用前缀是否合法
+ *
+ * @param prefix - 引用前缀，如 "refs/heads/"
+ * @throws 如果前缀格式无效
+ *
+ * @example
+ * ```ts
+ * validateRefPrefix("refs/heads/");
+ * ```
+ */
+declare function validateRefPrefix(prefix: string): void;
+/**
+ * 验证引用名称是否合法
+ *
+ * @param ref - 完整引用路径
+ * @throws 如果引用名称无效
+ *
+ * @example
+ * ```ts
+ * validateRefName("refs/heads/main");
+ * ```
+ */
+declare function validateRefName(ref: string): void;
+/**
+ * 将分支短名转换为完整引用路径
+ *
+ * @example
+ * ```ts
+ * branchNameToRef("main");
+ * ```
+ */
+declare function branchNameToRef(name: string): string;
+/**
+ * 将标签短名转换为完整引用路径
+ *
+ * @example
+ * ```ts
+ * tagNameToRef("v1.0.0");
+ * ```
+ */
+declare function tagNameToRef(name: string): string;
+/**
+ * 规范化短引用名称
+ *
+ * @example
+ * ```ts
+ * normalizeShortRefName("main", "branch");
+ * ```
+ */
+declare function normalizeShortRefName(name: string, kind: "branch" | "tag"): string;
+//#endregion
+export { branchNameToRef, normalizeShortRefName, tagNameToRef, validateRefName, validateRefPrefix };

package/dist/refs/names.mjs

@@ -0,0 +1,80 @@
+import { HEADS_PREFIX, TAGS_PREFIX } from "../core/types/refs.mjs";
+//#region src/refs/names.ts
+/**
+* Refs 名称校验与名称转换工具
+*/
+/**
+* 验证引用前缀是否合法
+*
+* @param prefix - 引用前缀，如 "refs/heads/"
+* @throws 如果前缀格式无效
+*
+* @example
+* ```ts
+* validateRefPrefix("refs/heads/");
+* ```
+*/
+function validateRefPrefix(prefix) {
+	if (!prefix.startsWith("refs/") || !prefix.endsWith("/")) throw new Error(`Invalid ref prefix: ${prefix}`);
+	validateRefName(`${prefix}placeholder`);
+}
+/**
+* 验证引用名称是否合法
+*
+* @param ref - 完整引用路径
+* @throws 如果引用名称无效
+*
+* @example
+* ```ts
+* validateRefName("refs/heads/main");
+* ```
+*/
+function validateRefName(ref) {
+	if (ref === "HEAD") return;
+	if (!ref.startsWith("refs/")) throw new Error(`Invalid ref name: ${ref}`);
+	if (ref.includes("\\") || ref.includes("..") || ref.includes("@{") || ref.includes("//") || ref.endsWith("/") || ref.endsWith(".")) throw new Error(`Invalid ref name: ${ref}`);
+	for (const char of ref) {
+		const code = char.charCodeAt(0);
+		if (code <= 31 || code === 127 || char === " " || char === "~" || char === "^" || char === ":" || char === "?" || char === "*" || char === "[") throw new Error(`Invalid ref name: ${ref}`);
+	}
+	const parts = ref.split("/");
+	if (parts.length < 3) throw new Error(`Invalid ref name: ${ref}`);
+	for (const part of parts) if (!part || part === "." || part === ".." || part.endsWith(".lock")) throw new Error(`Invalid ref name: ${ref}`);
+}
+/**
+* 将分支短名转换为完整引用路径
+*
+* @example
+* ```ts
+* branchNameToRef("main");
+* ```
+*/
+function branchNameToRef(name) {
+	return `${HEADS_PREFIX}${normalizeShortRefName(name, "branch")}`;
+}
+/**
+* 将标签短名转换为完整引用路径
+*
+* @example
+* ```ts
+* tagNameToRef("v1.0.0");
+* ```
+*/
+function tagNameToRef(name) {
+	return `${TAGS_PREFIX}${normalizeShortRefName(name, "tag")}`;
+}
+/**
+* 规范化短引用名称
+*
+* @example
+* ```ts
+* normalizeShortRefName("main", "branch");
+* ```
+*/
+function normalizeShortRefName(name, kind) {
+	if (!name) throw new Error(`${kind} name cannot be empty`);
+	validateRefName(`refs/x/${name}`);
+	return name;
+}
+//#endregion
+export { branchNameToRef, normalizeShortRefName, tagNameToRef, validateRefName, validateRefPrefix };

package/dist/refs/resolve.d.mts

@@ -0,0 +1,33 @@
+import { SHA1 } from "../core/types.mjs";
+import { RefStore } from "../core/types/refs.mjs";
+
+//#region src/refs/resolve.d.ts
+/**
+ * 解析引用为 SHA-1 哈希
+ *
+ * @example
+ * ```ts
+ * const hash = resolveRefHash(store, "HEAD");
+ * ```
+ */
+declare function resolveRefHash(store: RefStore, ref: string, seen?: Set<string>): SHA1 | null;
+/**
+ * 解析符号引用为目标引用路径
+ *
+ * @example
+ * ```ts
+ * const target = resolveSymbolicRef(store, "HEAD");
+ * ```
+ */
+declare function resolveSymbolicRef(store: RefStore, ref: string, seen?: Set<string>): string | null;
+/**
+ * 解析可选的哈希值，未提供时基于 HEAD 获取
+ *
+ * @example
+ * ```ts
+ * const hash = resolveTargetHash(store, undefined);
+ * ```
+ */
+declare function resolveTargetHash(store: RefStore, hash: SHA1 | undefined): SHA1;
+//#endregion
+export { resolveRefHash, resolveSymbolicRef, resolveTargetHash };

package/dist/refs/resolve.mjs

@@ -0,0 +1,55 @@
+import { CircularReferenceError } from "../core/errors.mjs";
+import { sha1 } from "../core/types.mjs";
+import { HEAD_REF } from "../core/types/refs.mjs";
+//#region src/refs/resolve.ts
+/**
+* Refs 解析工具
+*/
+/**
+* 解析引用为 SHA-1 哈希
+*
+* @example
+* ```ts
+* const hash = resolveRefHash(store, "HEAD");
+* ```
+*/
+function resolveRefHash(store, ref, seen = /* @__PURE__ */ new Set()) {
+	if (seen.has(ref)) throw new CircularReferenceError(ref);
+	seen.add(ref);
+	const content = store.read(ref);
+	if (content === null) return null;
+	if (content.startsWith("ref: ")) return resolveRefHash(store, content.slice(5), seen);
+	return sha1(content);
+}
+/**
+* 解析符号引用为目标引用路径
+*
+* @example
+* ```ts
+* const target = resolveSymbolicRef(store, "HEAD");
+* ```
+*/
+function resolveSymbolicRef(store, ref, seen = /* @__PURE__ */ new Set()) {
+	if (seen.has(ref)) throw new CircularReferenceError(ref);
+	seen.add(ref);
+	const content = store.read(ref);
+	if (content === null || !content.startsWith("ref: ")) return null;
+	const target = content.slice(5);
+	return resolveSymbolicRef(store, target, seen) ?? target;
+}
+/**
+* 解析可选的哈希值，未提供时基于 HEAD 获取
+*
+* @example
+* ```ts
+* const hash = resolveTargetHash(store, undefined);
+* ```
+*/
+function resolveTargetHash(store, hash) {
+	if (hash) return hash;
+	const headHash = resolveRefHash(store, HEAD_REF);
+	if (!headHash) throw new Error("Cannot resolve HEAD to create ref");
+	return headHash;
+}
+//#endregion
+export { resolveRefHash, resolveSymbolicRef, resolveTargetHash };

package/dist/refs/shallow/file.d.mts

@@ -0,0 +1,17 @@
+import { ShallowStore } from "../../core/types/shallow.mjs";
+
+//#region src/refs/shallow/file.d.ts
+/**
+ * 创建基于文件系统的 Shallow 存储
+ *
+ * @param gitDir - .git 目录的路径
+ *
+ * @example
+ * ```ts
+ * const store = createFileShallowStore("/repo/.git");
+ * console.log(store.read());
+ * ```
+ */
+declare function createFileShallowStore(gitDir: string): ShallowStore;
+//#endregion
+export { createFileShallowStore };

package/dist/refs/shallow/file.mjs

@@ -0,0 +1,61 @@
+import { sha1 } from "../../core/types.mjs";
+import { existsSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+//#region src/refs/shallow/file.ts
+/**
+* 基于文件系统的 Shallow 存储
+*
+* 读写 .git/shallow 文件。
+* 格式：每行一个 40 字符 SHA1 哈希。
+*
+* @example
+* ```ts
+* const store = createFileShallowStore("/path/to/repo/.git");
+* ```
+*/
+/**
+* 创建基于文件系统的 Shallow 存储
+*
+* @param gitDir - .git 目录的路径
+*
+* @example
+* ```ts
+* const store = createFileShallowStore("/repo/.git");
+* console.log(store.read());
+* ```
+*/
+function createFileShallowStore(gitDir) {
+	const shallowFilePath = join(gitDir, "shallow");
+	function readFromFile() {
+		if (!existsSync(shallowFilePath)) return [];
+		const content = readFileSync(shallowFilePath, "utf8").trim();
+		if (content.length === 0) return [];
+		return content.split("\n").map((line) => line.trim()).filter((line) => line.length > 0).map((hash) => sha1(hash));
+	}
+	function writeToFile(boundaries) {
+		if (boundaries.length === 0) {
+			if (existsSync(shallowFilePath)) unlinkSync(shallowFilePath);
+			return;
+		}
+		writeFileSync(shallowFilePath, [...boundaries].sort().join("\n") + "\n");
+	}
+	return {
+		read() {
+			return readFromFile();
+		},
+		write(boundaries) {
+			writeToFile(boundaries);
+		},
+		applyUpdate(update) {
+			const current = new Set(readFromFile());
+			for (const hash of update.unshallow) current.delete(hash);
+			for (const hash of update.shallow) current.add(hash);
+			writeToFile(Array.from(current));
+		},
+		isShallow(hash) {
+			return readFromFile().includes(hash);
+		}
+	};
+}
+//#endregion
+export { createFileShallowStore };

package/dist/refs/shallow/memory.d.mts

@@ -0,0 +1,18 @@
+import { SHA1 } from "../../core/types.mjs";
+import { ShallowStore } from "../../core/types/shallow.mjs";
+
+//#region src/refs/shallow/memory.d.ts
+/**
+ * 创建基于内存的 Shallow 存储
+ *
+ * @param initial - 初始 shallow 边界集合（可选）
+ *
+ * @example
+ * ```ts
+ * const store = createMemoryShallowStore([hashA]);
+ * console.log(store.isShallow(hashA)); // true
+ * ```
+ */
+declare function createMemoryShallowStore(initial?: SHA1[]): ShallowStore;
+//#endregion
+export { createMemoryShallowStore };