@optique/git 0.9.0-dev.266 → 0.9.0-dev.270

package/dist/index.cjs

@@ -26,31 +26,40 @@ 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"]);
 /**
-* Filesystem interface passed to isomorphic-git.
+* Read-only filesystem interface passed to isomorphic-git.
 *
-* Although this package only performs read operations (validation and listing),
-* isomorphic-git's FsClient type requires write methods to be present.
-* These methods are included for type compatibility but are never called
-* by our read-only operations.
+* This package only performs read operations (validation and listing).
+* Write methods are implemented as stubs that return rejected promises,
+* 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: () => Promise.reject(/* @__PURE__ */ new Error("gitFs is read-only: writeFile is disabled.")),
+	mkdir: () => Promise.reject(/* @__PURE__ */ new Error("gitFs is read-only: mkdir is disabled.")),
+	rmdir: () => Promise.reject(/* @__PURE__ */ new Error("gitFs is read-only: rmdir is disabled.")),
+	unlink: () => Promise.reject(/* @__PURE__ */ 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: () => Promise.reject(/* @__PURE__ */ 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();
@@ -64,6 +73,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 {
@@ -78,7 +89,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);
+			}
 		}
 	};
 }
@@ -127,7 +141,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,
@@ -137,7 +151,13 @@ function gitBranch(options) {
 				kind: "literal",
 				text: branch
 			};
-		} catch {}
+		} catch (error) {
+			logger.debug("Failed to list branches for suggestions.", {
+				dir,
+				prefix,
+				error
+			});
+		}
 	});
 }
 /**
@@ -187,7 +207,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,
@@ -198,7 +218,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
+			});
+		}
 	});
 }
 /**
@@ -235,7 +262,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,
@@ -245,7 +272,13 @@ function gitTag(options) {
 				kind: "literal",
 				text: tag
 			};
-		} catch {}
+		} catch (error) {
+			logger.debug("Failed to list tags for suggestions.", {
+				dir,
+				prefix,
+				error
+			});
+		}
 	});
 }
 /**
@@ -283,7 +316,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,
@@ -293,7 +326,13 @@ function gitRemote(options) {
 				kind: "literal",
 				text: r.remote
 			};
-		} catch {}
+		} catch (error) {
+			logger.debug("Failed to list remotes for suggestions.", {
+				dir,
+				prefix,
+				error
+			});
+		}
 	});
 }
 /**
@@ -316,7 +355,7 @@ function gitCommit(options) {
 			};
 			return {
 				success: false,
-				error: __optique_core_message.message`Invalid commit SHA: ${(0, __optique_core_message.value)(input)}. Commits must be 4–40 hexadecimal 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 {
@@ -329,7 +368,11 @@ function gitCommit(options) {
 				success: true,
 				value: oid
 			};
-		} catch {
+		} catch (e) {
+			if (hasErrorCode(e, "AmbiguousShortOidError")) return {
+				success: false,
+				error: __optique_core_message.message`Commit SHA ${(0, __optique_core_message.value)(input)} is ambiguous. Provide more characters to disambiguate.`
+			};
 			if (errors?.notFound) return {
 				success: false,
 				error: errors.notFound(input)
@@ -339,12 +382,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);
@@ -355,7 +398,13 @@ function gitCommit(options) {
 					description: __optique_core_message.message`${firstLine}`
 				};
 			}
-		} catch {}
+		} catch (error) {
+			logger.debug("Failed to list commits for suggestions.", {
+				dir,
+				prefix,
+				error
+			});
+		}
 	});
 }
 /**
@@ -393,7 +442,11 @@ function gitRef(options) {
 				success: true,
 				value: oid
 			};
-		} catch {
+		} catch (e) {
+			if (hasErrorCode(e, "AmbiguousShortOidError")) return {
+				success: false,
+				error: __optique_core_message.message`Reference ${(0, __optique_core_message.value)(input)} is ambiguous. Provide more characters to disambiguate.`
+			};
 			if (errors?.notFound) return {
 				success: false,
 				error: errors.notFound(input)
@@ -403,7 +456,7 @@ function gitRef(options) {
 				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({
@@ -417,7 +470,7 @@ function gitRef(options) {
 				isomorphic_git.log({
 					fs: gitFs,
 					dir,
-					depth: 10
+					depth
 				})
 			]);
 			for (const branch of branches) if (branch.startsWith(prefix)) yield {
@@ -437,7 +490,13 @@ function gitRef(options) {
 					description: __optique_core_message.message`${firstLine}`
 				};
 			}
-		} catch {}
+		} catch (error) {
+			logger.debug("Failed to list refs for suggestions.", {
+				dir,
+				prefix,
+				error
+			});
+		}
 	});
 }
 /**

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,31 +4,40 @@ 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"]);
 /**
-* Filesystem interface passed to isomorphic-git.
+* Read-only filesystem interface passed to isomorphic-git.
 *
-* Although this package only performs read operations (validation and listing),
-* isomorphic-git's FsClient type requires write methods to be present.
-* These methods are included for type compatibility but are never called
-* by our read-only operations.
+* This package only performs read operations (validation and listing).
+* Write methods are implemented as stubs that return rejected promises,
+* 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: () => Promise.reject(/* @__PURE__ */ new Error("gitFs is read-only: writeFile is disabled.")),
+	mkdir: () => Promise.reject(/* @__PURE__ */ new Error("gitFs is read-only: mkdir is disabled.")),
+	rmdir: () => Promise.reject(/* @__PURE__ */ new Error("gitFs is read-only: rmdir is disabled.")),
+	unlink: () => Promise.reject(/* @__PURE__ */ new Error("gitFs is read-only: unlink is disabled.")),
 	readdir: fs.readdir,
 	readlink: fs.readlink,
-	symlink: fs.symlink,
+	symlink: () => Promise.reject(/* @__PURE__ */ 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();
@@ -42,6 +51,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 {
@@ -56,7 +67,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);
+			}
 		}
 	};
 }
@@ -105,7 +119,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,
@@ -115,7 +129,13 @@ function gitBranch(options) {
 				kind: "literal",
 				text: branch
 			};
-		} catch {}
+		} catch (error) {
+			logger.debug("Failed to list branches for suggestions.", {
+				dir,
+				prefix,
+				error
+			});
+		}
 	});
 }
 /**
@@ -165,7 +185,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,
@@ -176,7 +196,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
+			});
+		}
 	});
 }
 /**
@@ -213,7 +240,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,
@@ -223,7 +250,13 @@ function gitTag(options) {
 				kind: "literal",
 				text: tag
 			};
-		} catch {}
+		} catch (error) {
+			logger.debug("Failed to list tags for suggestions.", {
+				dir,
+				prefix,
+				error
+			});
+		}
 	});
 }
 /**
@@ -261,7 +294,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,
@@ -271,7 +304,13 @@ function gitRemote(options) {
 				kind: "literal",
 				text: r.remote
 			};
-		} catch {}
+		} catch (error) {
+			logger.debug("Failed to list remotes for suggestions.", {
+				dir,
+				prefix,
+				error
+			});
+		}
 	});
 }
 /**
@@ -294,7 +333,7 @@ function gitCommit(options) {
 			};
 			return {
 				success: false,
-				error: message`Invalid commit SHA: ${value(input)}. Commits must be 4–40 hexadecimal characters.`
+				error: message`Invalid commit SHA: ${value(input)}. Provide an abbreviated (4+) or full (40) hexadecimal commit SHA.`
 			};
 		}
 		try {
@@ -307,7 +346,11 @@ function gitCommit(options) {
 				success: true,
 				value: oid
 			};
-		} catch {
+		} catch (e) {
+			if (hasErrorCode(e, "AmbiguousShortOidError")) return {
+				success: false,
+				error: message`Commit SHA ${value(input)} is ambiguous. Provide more characters to disambiguate.`
+			};
 			if (errors?.notFound) return {
 				success: false,
 				error: errors.notFound(input)
@@ -317,12 +360,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);
@@ -333,7 +376,13 @@ function gitCommit(options) {
 					description: message`${firstLine}`
 				};
 			}
-		} catch {}
+		} catch (error) {
+			logger.debug("Failed to list commits for suggestions.", {
+				dir,
+				prefix,
+				error
+			});
+		}
 	});
 }
 /**
@@ -371,7 +420,11 @@ function gitRef(options) {
 				success: true,
 				value: oid
 			};
-		} catch {
+		} catch (e) {
+			if (hasErrorCode(e, "AmbiguousShortOidError")) return {
+				success: false,
+				error: message`Reference ${value(input)} is ambiguous. Provide more characters to disambiguate.`
+			};
 			if (errors?.notFound) return {
 				success: false,
 				error: errors.notFound(input)
@@ -381,7 +434,7 @@ function gitRef(options) {
 				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({
@@ -395,7 +448,7 @@ function gitRef(options) {
 				git.log({
 					fs: gitFs,
 					dir,
-					depth: 10
+					depth
 				})
 			]);
 			for (const branch of branches) if (branch.startsWith(prefix)) yield {
@@ -415,7 +468,13 @@ function gitRef(options) {
 					description: message`${firstLine}`
 				};
 			}
-		} catch {}
+		} catch (error) {
+			logger.debug("Failed to list refs for suggestions.", {
+				dir,
+				prefix,
+				error
+			});
+		}
 	});
 }
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/git",
-  "version": "0.9.0-dev.266+49a4cc82",
+  "version": "0.9.0-dev.270+b5894625",
   "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",