@optique/git 0.9.0-dev.215 → 0.9.0-dev.227

package/dist/index.js

@@ -2,97 +2,51 @@ import { message, text } from "@optique/core/message";
 import { ensureNonEmptyString } from "@optique/core/nonempty";
 import * as git from "isomorphic-git";
 import { expandOid, listBranches, listRemotes, listTags, readObject, resolveRef } from "isomorphic-git";
+import * as fs from "node:fs/promises";
 import process from "node:process";
 
 //#region src/index.ts
+const gitFs = {
+	readFile: fs.readFile,
+	writeFile: fs.writeFile,
+	mkdir: fs.mkdir,
+	rmdir: fs.rmdir,
+	unlink: fs.unlink,
+	readdir: fs.readdir,
+	readlink: fs.readlink,
+	symlink: fs.symlink,
+	stat: fs.stat,
+	lstat: fs.lstat
+};
 const METAVAR_BRANCH = "BRANCH";
 const METAVAR_TAG = "TAG";
 const METAVAR_REMOTE = "REMOTE";
-let defaultFs = null;
-let fsLoading = null;
-async function getDefaultFs() {
-	if (defaultFs) return await defaultFs;
-	if (fsLoading) return await fsLoading;
-	fsLoading = (async () => {
-		const nodeFs = await import("node:fs/promises");
-		const { TextDecoder } = await import("node:util");
-		const decoder = new TextDecoder();
-		defaultFs = {
-			async readFile(path) {
-				const data = await nodeFs.readFile(path);
-				if (path.endsWith("/index") || path.endsWith(".idx")) return data;
-				return decoder.decode(data);
-			},
-			async writeFile(path, data) {
-				await nodeFs.writeFile(path, data);
-			},
-			async mkdir(path, options) {
-				await nodeFs.mkdir(path, options);
-			},
-			async rmdir(path, options) {
-				await nodeFs.rmdir(path, options);
-			},
-			async unlink(path) {
-				await nodeFs.unlink(path);
-			},
-			async readdir(path) {
-				const entries = await nodeFs.readdir(path, { withFileTypes: false });
-				return entries.filter((e) => typeof e === "string");
-			},
-			async lstat(path) {
-				return await nodeFs.lstat(path);
-			},
-			async stat(path) {
-				return await nodeFs.stat(path);
-			},
-			async readlink(path) {
-				return await nodeFs.readlink(path);
-			},
-			async symlink(target, path) {
-				await nodeFs.symlink(target, path, "file");
-			},
-			async chmod(path, mode) {
-				await nodeFs.chmod(path, mode);
-			},
-			async chown(path, uid, gid) {
-				await nodeFs.chown(path, uid, gid);
-			},
-			async rename(oldPath, newPath) {
-				await nodeFs.rename(oldPath, newPath);
-			},
-			async copyFile(srcPath, destPath) {
-				await nodeFs.copyFile(srcPath, destPath);
-			},
-			async exists(path) {
-				try {
-					await nodeFs.stat(path);
-					return true;
-				} catch {
-					return false;
-				}
-			}
-		};
-		return defaultFs;
-	})();
-	return fsLoading;
+function getRepoDir(dirOption) {
+	return dirOption ?? (typeof process !== "undefined" ? process.cwd() : ".");
+}
+function formatChoiceList(choices) {
+	let result = [];
+	for (let i = 0; i < choices.length; i++) {
+		if (i > 0) result = [...result, ...message`, `];
+		result = [...result, ...message`${choices[i]}`];
+	}
+	return result;
 }
 function createAsyncValueParser(options, metavar, parseFn, suggestFn) {
 	return {
 		$mode: "async",
 		metavar,
-		async parse(input) {
-			const fs = options?.fs ?? await getDefaultFs();
-			const dir = options?.dir ?? (typeof process !== "undefined" ? process.cwd() : ".");
+		parse(input) {
+			const dir = getRepoDir(options?.dir);
 			ensureNonEmptyString(metavar);
-			return parseFn(fs, dir, input);
+			return parseFn(dir, input, options?.errors);
 		},
 		format(value) {
 			return value;
 		},
 		async *suggest(prefix) {
-			const fs = options?.fs ?? await getDefaultFs();
-			const dir = options?.dir ?? (typeof process !== "undefined" ? process.cwd() : ".");
-			if (suggestFn) yield* suggestFn(fs, dir, prefix);
+			const dir = getRepoDir(options?.dir);
+			if (suggestFn) yield* suggestFn(dir, prefix);
 		}
 	};
 }
@@ -116,30 +70,38 @@ function createAsyncValueParser(options, metavar, parseFn, suggestFn) {
 */
 function gitBranch(options) {
 	const metavar = options?.metavar ?? METAVAR_BRANCH;
-	return createAsyncValueParser(options, metavar, async (fs, dir, input) => {
+	return createAsyncValueParser(options, metavar, async (dir, input, errors) => {
 		try {
 			const branches = await git.listBranches({
-				fs,
+				fs: gitFs,
 				dir
 			});
 			if (branches.includes(input)) return {
 				success: true,
 				value: input
 			};
+			if (errors?.notFound) return {
+				success: false,
+				error: errors.notFound(input, branches)
+			};
 			return {
 				success: false,
-				error: message`Branch ${text(input)} does not exist. Available branches: ${branches.join(", ")}`
+				error: message`Branch ${text(input)} does not exist. Available branches: ${formatChoiceList(branches)}`
 			};
 		} catch {
+			if (errors?.listFailed) return {
+				success: false,
+				error: errors.listFailed(dir)
+			};
 			return {
 				success: false,
 				error: message`Failed to list branches. Ensure ${text(dir)} is a valid git repository.`
 			};
 		}
-	}, async function* suggestBranch(fs, dir, prefix) {
+	}, async function* suggestBranch(dir, prefix) {
 		try {
 			const branches = await git.listBranches({
-				fs,
+				fs: gitFs,
 				dir
 			});
 			for (const branch of branches) if (branch.startsWith(prefix)) yield {
@@ -170,10 +132,10 @@ function gitBranch(options) {
 */
 function gitRemoteBranch(remote, options) {
 	const metavar = options?.metavar ?? METAVAR_BRANCH;
-	return createAsyncValueParser(options, metavar, async (fs, dir, input) => {
+	return createAsyncValueParser(options, metavar, async (dir, input, errors) => {
 		try {
 			const branches = await git.listBranches({
-				fs,
+				fs: gitFs,
 				dir,
 				remote
 			});
@@ -181,20 +143,28 @@ function gitRemoteBranch(remote, options) {
 				success: true,
 				value: input
 			};
+			if (errors?.notFound) return {
+				success: false,
+				error: errors.notFound(input, branches)
+			};
 			return {
 				success: false,
-				error: message`Remote branch ${text(input)} does not exist on remote ${text(remote)}. Available branches: ${branches.join(", ")}`
+				error: message`Remote branch ${text(input)} does not exist on remote ${text(remote)}. Available branches: ${formatChoiceList(branches)}`
 			};
 		} catch {
+			if (errors?.listFailed) return {
+				success: false,
+				error: errors.listFailed(dir)
+			};
 			return {
 				success: false,
 				error: message`Failed to list remote branches. Ensure remote ${text(remote)} exists.`
 			};
 		}
-	}, async function* suggestRemoteBranch(fs, dir, prefix) {
+	}, async function* suggestRemoteBranch(dir, prefix) {
 		try {
 			const branches = await git.listBranches({
-				fs,
+				fs: gitFs,
 				dir,
 				remote
 			});
@@ -208,47 +178,44 @@ function gitRemoteBranch(remote, options) {
 /**
 * Creates a value parser that validates tag names.
 *
-* This parser uses isomorphic-git to verify that the provided input
-* matches an existing tag in the repository.
-*
 * @param options Configuration options for the parser.
 * @returns A value parser that accepts existing tag names.
 * @since 0.9.0
-*
-* @example
-* ~~~~ typescript
-* import { gitTag } from "@optique/git";
-* import { option } from "@optique/core/primitives";
-*
-* const parser = option("-t", "--tag", gitTag());
-* ~~~~
 */
 function gitTag(options) {
 	const metavar = options?.metavar ?? METAVAR_TAG;
-	return createAsyncValueParser(options, metavar, async (fs, dir, input) => {
+	return createAsyncValueParser(options, metavar, async (dir, input, errors) => {
 		try {
 			const tags = await git.listTags({
-				fs,
+				fs: gitFs,
 				dir
 			});
 			if (tags.includes(input)) return {
 				success: true,
 				value: input
 			};
+			if (errors?.notFound) return {
+				success: false,
+				error: errors.notFound(input, tags)
+			};
 			return {
 				success: false,
-				error: message`Tag ${text(input)} does not exist. Available tags: ${tags.join(", ")}`
+				error: message`Tag ${text(input)} does not exist. Available tags: ${formatChoiceList(tags)}`
 			};
 		} catch {
+			if (errors?.listFailed) return {
+				success: false,
+				error: errors.listFailed(dir)
+			};
 			return {
 				success: false,
 				error: message`Failed to list tags. Ensure ${text(dir)} is a valid git repository.`
 			};
 		}
-	}, async function* suggestTag(fs, dir, prefix) {
+	}, async function* suggestTag(dir, prefix) {
 		try {
 			const tags = await git.listTags({
-				fs,
+				fs: gitFs,
 				dir
 			});
 			for (const tag of tags) if (tag.startsWith(prefix)) yield {
@@ -261,52 +228,48 @@ function gitTag(options) {
 /**
 * Creates a value parser that validates remote names.
 *
-* This parser uses isomorphic-git to verify that the provided input
-* matches an existing remote in the repository.
-*
 * @param options Configuration options for the parser.
 * @returns A value parser that accepts existing remote names.
 * @since 0.9.0
-*
-* @example
-* ~~~~ typescript
-* import { gitRemote } from "@optique/git";
-* import { option } from "@optique/core/primitives";
-*
-* const parser = option("-r", "--remote", gitRemote());
-* ~~~~
 */
 function gitRemote(options) {
 	const metavar = options?.metavar ?? METAVAR_REMOTE;
-	return createAsyncValueParser(options, metavar, async (fs, dir, input) => {
+	return createAsyncValueParser(options, metavar, async (dir, input, errors) => {
 		try {
 			const remotes = await git.listRemotes({
-				fs,
+				fs: gitFs,
 				dir
 			});
-			const remoteNames = [];
-			for (const r of remotes) if ("remote" in r && typeof r.remote === "string") remoteNames.push(r.remote);
-			if (remoteNames.includes(input)) return {
+			const names = remotes.map((r) => r.remote);
+			if (names.includes(input)) return {
 				success: true,
 				value: input
 			};
+			if (errors?.notFound) return {
+				success: false,
+				error: errors.notFound(input, names)
+			};
 			return {
 				success: false,
-				error: message`Remote ${text(input)} does not exist. Available remotes: ${remoteNames.join(", ")}`
+				error: message`Remote ${text(input)} does not exist. Available remotes: ${formatChoiceList(names)}`
 			};
 		} catch {
+			if (errors?.listFailed) return {
+				success: false,
+				error: errors.listFailed(dir)
+			};
 			return {
 				success: false,
 				error: message`Failed to list remotes. Ensure ${text(dir)} is a valid git repository.`
 			};
 		}
-	}, async function* suggestRemote(fs, dir, prefix) {
+	}, async function* suggestRemote(dir, prefix) {
 		try {
 			const remotes = await git.listRemotes({
-				fs,
+				fs: gitFs,
 				dir
 			});
-			for (const r of remotes) if ("remote" in r && typeof r.remote === "string" && r.remote.startsWith(prefix)) yield {
+			for (const r of remotes) if (r.remote.startsWith(prefix)) yield {
 				kind: "literal",
 				text: r.remote
 			};
@@ -316,119 +279,119 @@ function gitRemote(options) {
 /**
 * Creates a value parser that validates commit SHAs.
 *
-* This parser uses isomorphic-git to verify that the provided input
-* is a valid commit SHA (full or shortened) that exists in the repository.
+* This parser resolves the provided commit reference to its full 40-character
+* OID.
 *
 * @param options Configuration options for the parser.
-* @returns A value parser that accepts valid commit SHAs.
+* @returns A value parser that accepts existing commit SHAs.
 * @since 0.9.0
-*
-* @example
-* ~~~~ typescript
-* import { gitCommit } from "@optique/git";
-* import { option } from "@optique/core/primitives";
-*
-* const parser = option("-c", "--commit", gitCommit());
-* ~~~~
 */
 function gitCommit(options) {
 	const metavar = options?.metavar ?? "COMMIT";
-	return createAsyncValueParser(options, metavar, async (fs, dir, input) => {
+	return createAsyncValueParser(options, metavar, async (dir, input, errors) => {
+		try {
+			ensureNonEmptyString(input);
+		} catch {
+			if (errors?.invalidFormat) return {
+				success: false,
+				error: errors.invalidFormat(input)
+			};
+			return {
+				success: false,
+				error: message`Invalid commit SHA: ${text(input)}`
+			};
+		}
+		if (input.length < 4 || input.length > 40) {
+			if (errors?.invalidFormat) return {
+				success: false,
+				error: errors.invalidFormat(input)
+			};
+			return {
+				success: false,
+				error: message`Commit ${text(input)} must be between 4 and 40 characters.`
+			};
+		}
 		try {
 			const oid = await git.expandOid({
-				fs,
+				fs: gitFs,
 				dir,
 				oid: input
 			});
-			await git.readObject({
-				fs,
-				dir,
-				oid
-			});
 			return {
 				success: true,
 				value: oid
 			};
 		} catch {
+			if (errors?.notFound) return {
+				success: false,
+				error: errors.notFound(input)
+			};
 			return {
 				success: false,
 				error: message`Commit ${text(input)} does not exist. Provide a valid commit SHA.`
 			};
 		}
-	}, async function* suggestCommit(fs, dir, prefix) {
-		try {
-			const branches = await git.listBranches({
-				fs,
-				dir
-			});
-			const commits = [];
-			for (const branch of branches.slice(0, 10)) try {
-				const oid = await git.resolveRef({
-					fs,
-					dir,
-					ref: branch
-				});
-				if (oid.startsWith(prefix)) commits.push(oid);
-			} catch {}
-			for (const commit of [...new Set(commits)].slice(0, 10)) yield {
-				kind: "literal",
-				text: commit
-			};
-		} catch {}
 	});
 }
 /**
-* Creates a value parser that validates any git reference
-* (branches, tags, or commits).
+* Creates a value parser that validates any git reference.
 *
-* This parser uses isomorphic-git to verify that the provided input
-* resolves to a valid git reference (branch, tag, or commit SHA).
+* Accepts branch names, tag names, or commit SHAs and resolves them to the
+* corresponding commit OID.
 *
 * @param options Configuration options for the parser.
-* @returns A value parser that accepts branches, tags, or commit SHAs.
+* @returns A value parser that accepts any git reference.
 * @since 0.9.0
-*
-* @example
-* ~~~~ typescript
-* import { gitRef } from "@optique/git";
-* import { option } from "@optique/core/primitives";
-*
-* const parser = option("--ref", gitRef());
-* ~~~~
 */
 function gitRef(options) {
 	const metavar = options?.metavar ?? "REF";
-	return createAsyncValueParser(options, metavar, async (fs, dir, input) => {
+	return createAsyncValueParser(options, metavar, async (dir, input, errors) => {
 		try {
-			const oid = await git.resolveRef({
-				fs,
+			const resolved = await git.resolveRef({
+				fs: gitFs,
 				dir,
 				ref: input
 			});
 			return {
 				success: true,
-				value: oid
+				value: resolved
 			};
 		} catch {
-			return {
-				success: false,
-				error: message`Reference ${text(input)} does not exist. Provide a valid branch, tag, or commit SHA.`
-			};
+			try {
+				const oid = await git.expandOid({
+					fs: gitFs,
+					dir,
+					oid: input
+				});
+				return {
+					success: true,
+					value: oid
+				};
+			} catch {
+				if (errors?.notFound) return {
+					success: false,
+					error: errors.notFound(input)
+				};
+				return {
+					success: false,
+					error: message`Reference ${text(input)} does not exist. Provide a valid branch, tag, or commit SHA.`
+				};
+			}
 		}
-	}, async function* suggestRef(fs, dir, prefix) {
+	}, async function* suggestRef(dir, prefix) {
 		try {
 			const branches = await git.listBranches({
-				fs,
+				fs: gitFs,
+				dir
+			});
+			const tags = await git.listTags({
+				fs: gitFs,
 				dir
 			});
 			for (const branch of branches) if (branch.startsWith(prefix)) yield {
 				kind: "literal",
 				text: branch
 			};
-			const tags = await git.listTags({
-				fs,
-				dir
-			});
 			for (const tag of tags) if (tag.startsWith(prefix)) yield {
 				kind: "literal",
 				text: tag
@@ -437,51 +400,20 @@ function gitRef(options) {
 	});
 }
 /**
-* Creates a factory for git parsers with shared configuration.
-*
-* This function returns an object with methods for creating individual git
-* parsers that share the same configuration (filesystem and directory).
+* Creates a set of git parsers with shared configuration.
 *
-* @param options Shared configuration options for all parsers.
-* @returns An object with methods for creating individual git parsers.
+* @param options Shared configuration for the parsers.
+* @returns An object containing git parsers.
 * @since 0.9.0
-*
-* @example
-* ~~~~ typescript
-* import { createGitParsers } from "@optique/git";
-*
-* const git = createGitParsers({ dir: "/path/to/repo" });
-*
-* const branchParser = git.branch();
-* const tagParser = git.tag();
-* ~~~~
 */
 function createGitParsers(options) {
 	return {
-		branch: (parserOptions) => gitBranch({
-			...options,
-			...parserOptions
-		}),
-		remoteBranch: (remote, parserOptions) => gitRemoteBranch(remote, {
-			...options,
-			...parserOptions
-		}),
-		tag: (parserOptions) => gitTag({
-			...options,
-			...parserOptions
-		}),
-		remote: (parserOptions) => gitRemote({
-			...options,
-			...parserOptions
-		}),
-		commit: (parserOptions) => gitCommit({
-			...options,
-			...parserOptions
-		}),
-		ref: (parserOptions) => gitRef({
-			...options,
-			...parserOptions
-		})
+		branch: (branchOptions) => gitBranch(branchOptions ?? options),
+		remoteBranch: (remote, branchOptions) => gitRemoteBranch(remote, branchOptions ?? options),
+		tag: (tagOptions) => gitTag(tagOptions ?? options),
+		remote: (remoteOptions) => gitRemote(remoteOptions ?? options),
+		commit: (commitOptions) => gitCommit(commitOptions ?? options),
+		ref: (refOptions) => gitRef(refOptions ?? options)
 	};
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/git",
-  "version": "0.9.0-dev.215+13b302c0",
+  "version": "0.9.0-dev.227+a31da310",
   "description": "Git value parsers for Optique",
   "keywords": [
     "CLI",