@optique/git 0.9.0-dev.264 → 0.9.0-dev.268

package/dist/index.cjs

@@ -26,23 +26,50 @@ const __optique_core_nonempty = __toESM(require("@optique/core/nonempty"));
 const isomorphic_git = __toESM(require("isomorphic-git"));
 const node_fs_promises = __toESM(require("node:fs/promises"));
 const node_process = __toESM(require("node:process"));
+const __logtape_logtape = __toESM(require("@logtape/logtape"));
 
 //#region src/index.ts
+const logger = (0, __logtape_logtape.getLogger)(["optique", "git"]);
+/**
+* Read-only filesystem interface passed to isomorphic-git.
+*
+* This package only performs read operations (validation and listing).
+* Write methods are implemented as stubs that throw errors if called,
+* enforcing the read-only contract and preventing accidental writes.
+*/
 const gitFs = {
 	readFile: node_fs_promises.readFile,
-	writeFile: node_fs_promises.writeFile,
-	mkdir: node_fs_promises.mkdir,
-	rmdir: node_fs_promises.rmdir,
-	unlink: node_fs_promises.unlink,
+	writeFile: () => {
+		throw new Error("gitFs is read-only: writeFile is disabled.");
+	},
+	mkdir: () => {
+		throw new Error("gitFs is read-only: mkdir is disabled.");
+	},
+	rmdir: () => {
+		throw new Error("gitFs is read-only: rmdir is disabled.");
+	},
+	unlink: () => {
+		throw new Error("gitFs is read-only: unlink is disabled.");
+	},
 	readdir: node_fs_promises.readdir,
 	readlink: node_fs_promises.readlink,
-	symlink: node_fs_promises.symlink,
+	symlink: () => {
+		throw new Error("gitFs is read-only: symlink is disabled.");
+	},
 	stat: node_fs_promises.stat,
 	lstat: node_fs_promises.lstat
 };
 const METAVAR_BRANCH = "BRANCH";
 const METAVAR_TAG = "TAG";
 const METAVAR_REMOTE = "REMOTE";
+/**
+* Resolves the repository directory from the provided option or process.cwd().
+*
+* Note: This function does not validate that the directory exists or is
+* accessible. Directory validation is deferred to the Git operations
+* themselves, which will produce appropriate error messages if the directory
+* is invalid or not a Git repository.
+*/
 function getRepoDir(dirOption) {
 	if (dirOption != null) return dirOption;
 	if (typeof node_process.default !== "undefined" && typeof node_process.default.cwd === "function") return node_process.default.cwd();
@@ -56,6 +83,8 @@ function listFailureMessage(error, dir, errors, fallback) {
 	if (hasErrorCode(error, "NotAGitRepositoryError") || hasErrorCode(error, "NotFoundError")) return __optique_core_message.message`${(0, __optique_core_message.value)(dir)} is not a git repository.`;
 	return fallback;
 }
+/** Default depth for commit suggestions. */
+const DEFAULT_SUGGESTION_DEPTH = 15;
 function createAsyncValueParser(options, metavar, parseFn, suggestFn) {
 	(0, __optique_core_nonempty.ensureNonEmptyString)(metavar);
 	return {
@@ -70,7 +99,10 @@ function createAsyncValueParser(options, metavar, parseFn, suggestFn) {
 		},
 		async *suggest(prefix) {
 			const dir = getRepoDir(options?.dir);
-			if (suggestFn) yield* suggestFn(dir, prefix);
+			if (suggestFn) {
+				const depth = options?.suggestionDepth ?? DEFAULT_SUGGESTION_DEPTH;
+				yield* suggestFn(dir, prefix, depth);
+			}
 		}
 	};
 }
@@ -119,7 +151,7 @@ function gitBranch(options) {
 				error: listFailureMessage(error, dir, errors, fallback)
 			};
 		}
-	}, async function* suggestBranch(dir, prefix) {
+	}, async function* suggestBranch(dir, prefix, _depth) {
 		try {
 			const branches = await isomorphic_git.listBranches({
 				fs: gitFs,
@@ -129,7 +161,13 @@ function gitBranch(options) {
 				kind: "literal",
 				text: branch
 			};
-		} catch {}
+		} catch (error) {
+			logger.debug("Failed to list branches for suggestions.", {
+				dir,
+				prefix,
+				error
+			});
+		}
 	});
 }
 /**
@@ -179,7 +217,7 @@ function gitRemoteBranch(remote, options) {
 				error: listFailureMessage(error, dir, errors, fallback)
 			};
 		}
-	}, async function* suggestRemoteBranch(dir, prefix) {
+	}, async function* suggestRemoteBranch(dir, prefix, _depth) {
 		try {
 			const branches = await isomorphic_git.listBranches({
 				fs: gitFs,
@@ -190,7 +228,14 @@ function gitRemoteBranch(remote, options) {
 				kind: "literal",
 				text: branch
 			};
-		} catch {}
+		} catch (error) {
+			logger.debug("Failed to list remote branches for suggestions.", {
+				dir,
+				remote,
+				prefix,
+				error
+			});
+		}
 	});
 }
 /**
@@ -227,7 +272,7 @@ function gitTag(options) {
 				error: listFailureMessage(error, dir, errors, fallback)
 			};
 		}
-	}, async function* suggestTag(dir, prefix) {
+	}, async function* suggestTag(dir, prefix, _depth) {
 		try {
 			const tags = await isomorphic_git.listTags({
 				fs: gitFs,
@@ -237,7 +282,13 @@ function gitTag(options) {
 				kind: "literal",
 				text: tag
 			};
-		} catch {}
+		} catch (error) {
+			logger.debug("Failed to list tags for suggestions.", {
+				dir,
+				prefix,
+				error
+			});
+		}
 	});
 }
 /**
@@ -275,7 +326,7 @@ function gitRemote(options) {
 				error: listFailureMessage(error, dir, errors, fallback)
 			};
 		}
-	}, async function* suggestRemote(dir, prefix) {
+	}, async function* suggestRemote(dir, prefix, _depth) {
 		try {
 			const remotes = await isomorphic_git.listRemotes({
 				fs: gitFs,
@@ -285,7 +336,13 @@ function gitRemote(options) {
 				kind: "literal",
 				text: r.remote
 			};
-		} catch {}
+		} catch (error) {
+			logger.debug("Failed to list remotes for suggestions.", {
+				dir,
+				prefix,
+				error
+			});
+		}
 	});
 }
 /**
@@ -301,26 +358,14 @@ function gitRemote(options) {
 function gitCommit(options) {
 	const metavar = options?.metavar ?? "COMMIT";
 	return createAsyncValueParser(options, metavar, async (dir, input, errors) => {
-		try {
-			(0, __optique_core_nonempty.ensureNonEmptyString)(input);
-		} catch {
-			if (errors?.invalidFormat) return {
-				success: false,
-				error: errors.invalidFormat(input)
-			};
-			return {
-				success: false,
-				error: __optique_core_message.message`Invalid commit SHA: ${(0, __optique_core_message.value)(input)}`
-			};
-		}
-		if (input.length < 4 || input.length > 40) {
+		if (!/^[0-9a-f]{4,40}$/i.test(input)) {
 			if (errors?.invalidFormat) return {
 				success: false,
 				error: errors.invalidFormat(input)
 			};
 			return {
 				success: false,
-				error: __optique_core_message.message`Commit ${(0, __optique_core_message.value)(input)} must be between 4 and 40 characters.`
+				error: __optique_core_message.message`Invalid commit SHA: ${(0, __optique_core_message.value)(input)}. Provide an abbreviated (4+) or full (40) hexadecimal commit SHA.`
 			};
 		}
 		try {
@@ -343,12 +388,12 @@ function gitCommit(options) {
 				error: __optique_core_message.message`Commit ${(0, __optique_core_message.value)(input)} does not exist. Provide a valid commit SHA.`
 			};
 		}
-	}, async function* suggestCommit(dir, prefix) {
+	}, async function* suggestCommit(dir, prefix, depth) {
 		try {
 			const commits = await isomorphic_git.log({
 				fs: gitFs,
 				dir,
-				depth: 15
+				depth
 			});
 			for (const commit of commits) if (commit.oid.startsWith(prefix)) {
 				const shortOid = commit.oid.slice(0, 7);
@@ -359,7 +404,13 @@ function gitCommit(options) {
 					description: __optique_core_message.message`${firstLine}`
 				};
 			}
-		} catch {}
+		} catch (error) {
+			logger.debug("Failed to list commits for suggestions.", {
+				dir,
+				prefix,
+				error
+			});
+		}
 	});
 }
 /**
@@ -375,39 +426,39 @@ function gitCommit(options) {
 function gitRef(options) {
 	const metavar = options?.metavar ?? "REF";
 	return createAsyncValueParser(options, metavar, async (dir, input, errors) => {
+		let resolved;
 		try {
-			const resolved = await isomorphic_git.resolveRef({
+			resolved = await isomorphic_git.resolveRef({
 				fs: gitFs,
 				dir,
 				ref: input
 			});
+		} catch {}
+		if (resolved) return {
+			success: true,
+			value: resolved
+		};
+		try {
+			const oid = await isomorphic_git.expandOid({
+				fs: gitFs,
+				dir,
+				oid: input
+			});
 			return {
 				success: true,
-				value: resolved
+				value: oid
 			};
 		} catch {
-			try {
-				const oid = await isomorphic_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: __optique_core_message.message`Reference ${(0, __optique_core_message.value)(input)} does not exist. Provide a valid branch, tag, or commit SHA.`
-				};
-			}
+			if (errors?.notFound) return {
+				success: false,
+				error: errors.notFound(input)
+			};
+			return {
+				success: false,
+				error: __optique_core_message.message`Reference ${(0, __optique_core_message.value)(input)} does not exist. Provide a valid branch, tag, or commit SHA.`
+			};
 		}
-	}, async function* suggestRef(dir, prefix) {
+	}, async function* suggestRef(dir, prefix, depth) {
 		try {
 			const [branches, tags, commits] = await Promise.all([
 				isomorphic_git.listBranches({
@@ -421,7 +472,7 @@ function gitRef(options) {
 				isomorphic_git.log({
 					fs: gitFs,
 					dir,
-					depth: 10
+					depth
 				})
 			]);
 			for (const branch of branches) if (branch.startsWith(prefix)) yield {
@@ -441,7 +492,13 @@ function gitRef(options) {
 					description: __optique_core_message.message`${firstLine}`
 				};
 			}
-		} catch {}
+		} catch (error) {
+			logger.debug("Failed to list refs for suggestions.", {
+				dir,
+				prefix,
+				error
+			});
+		}
 	});
 }
 /**
@@ -453,12 +510,30 @@ function gitRef(options) {
 */
 function createGitParsers(options) {
 	return {
-		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)
+		branch: (branchOptions) => gitBranch({
+			...options,
+			...branchOptions
+		}),
+		remoteBranch: (remote, branchOptions) => gitRemoteBranch(remote, {
+			...options,
+			...branchOptions
+		}),
+		tag: (tagOptions) => gitTag({
+			...options,
+			...tagOptions
+		}),
+		remote: (remoteOptions) => gitRemote({
+			...options,
+			...remoteOptions
+		}),
+		commit: (commitOptions) => gitCommit({
+			...options,
+			...commitOptions
+		}),
+		ref: (refOptions) => gitRef({
+			...options,
+			...refOptions
+		})
 	};
 }
 

package/dist/index.d.cts

@@ -27,6 +27,14 @@ interface GitParserOptions {
    * @since 0.9.0
    */
   errors?: GitParserErrors;
+  /**
+   * Maximum number of recent commits to include in shell completion suggestions.
+   * Only applies to `gitCommit()` and `gitRef()` parsers.
+   * Defaults to 15.
+   *
+   * @since 0.9.0
+   */
+  suggestionDepth?: number;
 }
 /**
  * Custom error messages for git value parsers.

package/dist/index.d.ts

@@ -27,6 +27,14 @@ interface GitParserOptions {
    * @since 0.9.0
    */
   errors?: GitParserErrors;
+  /**
+   * Maximum number of recent commits to include in shell completion suggestions.
+   * Only applies to `gitCommit()` and `gitRef()` parsers.
+   * Defaults to 15.
+   *
+   * @since 0.9.0
+   */
+  suggestionDepth?: number;
 }
 /**
  * Custom error messages for git value parsers.

package/dist/index.js

@@ -4,23 +4,50 @@ 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";
+import { getLogger } from "@logtape/logtape";
 
 //#region src/index.ts
+const logger = getLogger(["optique", "git"]);
+/**
+* Read-only filesystem interface passed to isomorphic-git.
+*
+* This package only performs read operations (validation and listing).
+* Write methods are implemented as stubs that throw errors if called,
+* enforcing the read-only contract and preventing accidental writes.
+*/
 const gitFs = {
 	readFile: fs.readFile,
-	writeFile: fs.writeFile,
-	mkdir: fs.mkdir,
-	rmdir: fs.rmdir,
-	unlink: fs.unlink,
+	writeFile: () => {
+		throw new Error("gitFs is read-only: writeFile is disabled.");
+	},
+	mkdir: () => {
+		throw new Error("gitFs is read-only: mkdir is disabled.");
+	},
+	rmdir: () => {
+		throw new Error("gitFs is read-only: rmdir is disabled.");
+	},
+	unlink: () => {
+		throw new Error("gitFs is read-only: unlink is disabled.");
+	},
 	readdir: fs.readdir,
 	readlink: fs.readlink,
-	symlink: fs.symlink,
+	symlink: () => {
+		throw new Error("gitFs is read-only: symlink is disabled.");
+	},
 	stat: fs.stat,
 	lstat: fs.lstat
 };
 const METAVAR_BRANCH = "BRANCH";
 const METAVAR_TAG = "TAG";
 const METAVAR_REMOTE = "REMOTE";
+/**
+* Resolves the repository directory from the provided option or process.cwd().
+*
+* Note: This function does not validate that the directory exists or is
+* accessible. Directory validation is deferred to the Git operations
+* themselves, which will produce appropriate error messages if the directory
+* is invalid or not a Git repository.
+*/
 function getRepoDir(dirOption) {
 	if (dirOption != null) return dirOption;
 	if (typeof process !== "undefined" && typeof process.cwd === "function") return process.cwd();
@@ -34,6 +61,8 @@ function listFailureMessage(error, dir, errors, fallback) {
 	if (hasErrorCode(error, "NotAGitRepositoryError") || hasErrorCode(error, "NotFoundError")) return message`${value(dir)} is not a git repository.`;
 	return fallback;
 }
+/** Default depth for commit suggestions. */
+const DEFAULT_SUGGESTION_DEPTH = 15;
 function createAsyncValueParser(options, metavar, parseFn, suggestFn) {
 	ensureNonEmptyString(metavar);
 	return {
@@ -48,7 +77,10 @@ function createAsyncValueParser(options, metavar, parseFn, suggestFn) {
 		},
 		async *suggest(prefix) {
 			const dir = getRepoDir(options?.dir);
-			if (suggestFn) yield* suggestFn(dir, prefix);
+			if (suggestFn) {
+				const depth = options?.suggestionDepth ?? DEFAULT_SUGGESTION_DEPTH;
+				yield* suggestFn(dir, prefix, depth);
+			}
 		}
 	};
 }
@@ -97,7 +129,7 @@ function gitBranch(options) {
 				error: listFailureMessage(error, dir, errors, fallback)
 			};
 		}
-	}, async function* suggestBranch(dir, prefix) {
+	}, async function* suggestBranch(dir, prefix, _depth) {
 		try {
 			const branches = await git.listBranches({
 				fs: gitFs,
@@ -107,7 +139,13 @@ function gitBranch(options) {
 				kind: "literal",
 				text: branch
 			};
-		} catch {}
+		} catch (error) {
+			logger.debug("Failed to list branches for suggestions.", {
+				dir,
+				prefix,
+				error
+			});
+		}
 	});
 }
 /**
@@ -157,7 +195,7 @@ function gitRemoteBranch(remote, options) {
 				error: listFailureMessage(error, dir, errors, fallback)
 			};
 		}
-	}, async function* suggestRemoteBranch(dir, prefix) {
+	}, async function* suggestRemoteBranch(dir, prefix, _depth) {
 		try {
 			const branches = await git.listBranches({
 				fs: gitFs,
@@ -168,7 +206,14 @@ function gitRemoteBranch(remote, options) {
 				kind: "literal",
 				text: branch
 			};
-		} catch {}
+		} catch (error) {
+			logger.debug("Failed to list remote branches for suggestions.", {
+				dir,
+				remote,
+				prefix,
+				error
+			});
+		}
 	});
 }
 /**
@@ -205,7 +250,7 @@ function gitTag(options) {
 				error: listFailureMessage(error, dir, errors, fallback)
 			};
 		}
-	}, async function* suggestTag(dir, prefix) {
+	}, async function* suggestTag(dir, prefix, _depth) {
 		try {
 			const tags = await git.listTags({
 				fs: gitFs,
@@ -215,7 +260,13 @@ function gitTag(options) {
 				kind: "literal",
 				text: tag
 			};
-		} catch {}
+		} catch (error) {
+			logger.debug("Failed to list tags for suggestions.", {
+				dir,
+				prefix,
+				error
+			});
+		}
 	});
 }
 /**
@@ -253,7 +304,7 @@ function gitRemote(options) {
 				error: listFailureMessage(error, dir, errors, fallback)
 			};
 		}
-	}, async function* suggestRemote(dir, prefix) {
+	}, async function* suggestRemote(dir, prefix, _depth) {
 		try {
 			const remotes = await git.listRemotes({
 				fs: gitFs,
@@ -263,7 +314,13 @@ function gitRemote(options) {
 				kind: "literal",
 				text: r.remote
 			};
-		} catch {}
+		} catch (error) {
+			logger.debug("Failed to list remotes for suggestions.", {
+				dir,
+				prefix,
+				error
+			});
+		}
 	});
 }
 /**
@@ -279,26 +336,14 @@ function gitRemote(options) {
 function gitCommit(options) {
 	const metavar = options?.metavar ?? "COMMIT";
 	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: ${value(input)}`
-			};
-		}
-		if (input.length < 4 || input.length > 40) {
+		if (!/^[0-9a-f]{4,40}$/i.test(input)) {
 			if (errors?.invalidFormat) return {
 				success: false,
 				error: errors.invalidFormat(input)
 			};
 			return {
 				success: false,
-				error: message`Commit ${value(input)} must be between 4 and 40 characters.`
+				error: message`Invalid commit SHA: ${value(input)}. Provide an abbreviated (4+) or full (40) hexadecimal commit SHA.`
 			};
 		}
 		try {
@@ -321,12 +366,12 @@ function gitCommit(options) {
 				error: message`Commit ${value(input)} does not exist. Provide a valid commit SHA.`
 			};
 		}
-	}, async function* suggestCommit(dir, prefix) {
+	}, async function* suggestCommit(dir, prefix, depth) {
 		try {
 			const commits = await git.log({
 				fs: gitFs,
 				dir,
-				depth: 15
+				depth
 			});
 			for (const commit of commits) if (commit.oid.startsWith(prefix)) {
 				const shortOid = commit.oid.slice(0, 7);
@@ -337,7 +382,13 @@ function gitCommit(options) {
 					description: message`${firstLine}`
 				};
 			}
-		} catch {}
+		} catch (error) {
+			logger.debug("Failed to list commits for suggestions.", {
+				dir,
+				prefix,
+				error
+			});
+		}
 	});
 }
 /**
@@ -353,39 +404,39 @@ function gitCommit(options) {
 function gitRef(options) {
 	const metavar = options?.metavar ?? "REF";
 	return createAsyncValueParser(options, metavar, async (dir, input, errors) => {
+		let resolved;
 		try {
-			const resolved = await git.resolveRef({
+			resolved = await git.resolveRef({
 				fs: gitFs,
 				dir,
 				ref: input
 			});
+		} catch {}
+		if (resolved) return {
+			success: true,
+			value: resolved
+		};
+		try {
+			const oid = await git.expandOid({
+				fs: gitFs,
+				dir,
+				oid: input
+			});
 			return {
 				success: true,
-				value: resolved
+				value: oid
 			};
 		} catch {
-			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 ${value(input)} does not exist. Provide a valid branch, tag, or commit SHA.`
-				};
-			}
+			if (errors?.notFound) return {
+				success: false,
+				error: errors.notFound(input)
+			};
+			return {
+				success: false,
+				error: message`Reference ${value(input)} does not exist. Provide a valid branch, tag, or commit SHA.`
+			};
 		}
-	}, async function* suggestRef(dir, prefix) {
+	}, async function* suggestRef(dir, prefix, depth) {
 		try {
 			const [branches, tags, commits] = await Promise.all([
 				git.listBranches({
@@ -399,7 +450,7 @@ function gitRef(options) {
 				git.log({
 					fs: gitFs,
 					dir,
-					depth: 10
+					depth
 				})
 			]);
 			for (const branch of branches) if (branch.startsWith(prefix)) yield {
@@ -419,7 +470,13 @@ function gitRef(options) {
 					description: message`${firstLine}`
 				};
 			}
-		} catch {}
+		} catch (error) {
+			logger.debug("Failed to list refs for suggestions.", {
+				dir,
+				prefix,
+				error
+			});
+		}
 	});
 }
 /**
@@ -431,12 +488,30 @@ function gitRef(options) {
 */
 function createGitParsers(options) {
 	return {
-		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)
+		branch: (branchOptions) => gitBranch({
+			...options,
+			...branchOptions
+		}),
+		remoteBranch: (remote, branchOptions) => gitRemoteBranch(remote, {
+			...options,
+			...branchOptions
+		}),
+		tag: (tagOptions) => gitTag({
+			...options,
+			...tagOptions
+		}),
+		remote: (remoteOptions) => gitRemote({
+			...options,
+			...remoteOptions
+		}),
+		commit: (commitOptions) => gitCommit({
+			...options,
+			...commitOptions
+		}),
+		ref: (refOptions) => gitRef({
+			...options,
+			...refOptions
+		})
 	};
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/git",
-  "version": "0.9.0-dev.264+07364667",
+  "version": "0.9.0-dev.268+5fccc2e2",
   "description": "Git value parsers for Optique",
   "keywords": [
     "CLI",
@@ -57,8 +57,9 @@
   },
   "sideEffects": false,
   "dependencies": {
-    "isomorphic-git": "^1.36.1",
-    "@optique/core": ""
+    "@logtape/logtape": "^1.2.2",
+    "@optique/core": "",
+    "isomorphic-git": "^1.36.1"
   },
   "devDependencies": {
     "@types/node": "^20.19.9",