@optique/git 0.10.7 → 1.0.0-dev.1116

package/README.md

@@ -30,7 +30,8 @@ Quick start
 
 ~~~~ typescript
 import { gitBranch, gitTag, gitCommit } from "@optique/git";
-import { argument, option, object } from "@optique/core/primitives";
+import { object } from "@optique/core/constructs";
+import { argument, option } from "@optique/core/primitives";
 import { parseAsync } from "@optique/core/parser";
 
 const parser = object({
@@ -53,7 +54,8 @@ Use `createGitParsers()` to create parsers for a different repository:
 
 ~~~~ typescript
 import { createGitParsers } from "@optique/git";
-import { argument, object } from "@optique/core/primitives";
+import { object } from "@optique/core/constructs";
+import { argument, option } from "@optique/core/primitives";
 import { parseAsync } from "@optique/core/parser";
 
 const git = createGitParsers({ dir: "/path/to/repo" });
@@ -79,7 +81,8 @@ existing branch in the repository.
 
 ~~~~ typescript
 import { gitBranch } from "@optique/git";
-import { argument, object } from "@optique/core/primitives";
+import { object } from "@optique/core/constructs";
+import { argument } from "@optique/core/primitives";
 import { parseAsync } from "@optique/core/parser";
 
 const parser = object({
@@ -102,7 +105,8 @@ existing branch on the specified remote.
 
 ~~~~ typescript
 import { gitRemoteBranch } from "@optique/git";
-import { option, object } from "@optique/core/primitives";
+import { object } from "@optique/core/constructs";
+import { option } from "@optique/core/primitives";
 import { parseAsync } from "@optique/core/parser";
 
 const parser = object({
@@ -120,7 +124,8 @@ in the repository.
 
 ~~~~ typescript
 import { gitTag } from "@optique/git";
-import { option, object } from "@optique/core/primitives";
+import { object } from "@optique/core/constructs";
+import { option } from "@optique/core/primitives";
 import { parseAsync } from "@optique/core/parser";
 
 const parser = object({
@@ -138,7 +143,8 @@ remote in the repository.
 
 ~~~~ typescript
 import { gitRemote } from "@optique/git";
-import { option, object } from "@optique/core/primitives";
+import { object } from "@optique/core/constructs";
+import { option } from "@optique/core/primitives";
 import { parseAsync } from "@optique/core/parser";
 
 const parser = object({
@@ -156,7 +162,8 @@ A value parser for commit SHAs. Validates that the input is a valid commit SHA
 
 ~~~~ typescript
 import { gitCommit } from "@optique/git";
-import { option, object } from "@optique/core/primitives";
+import { object } from "@optique/core/constructs";
+import { option } from "@optique/core/primitives";
 import { parseAsync } from "@optique/core/parser";
 
 const parser = object({
@@ -174,7 +181,8 @@ that the input resolves to a valid Git reference.
 
 ~~~~ typescript
 import { gitRef } from "@optique/git";
-import { option, object } from "@optique/core/primitives";
+import { object } from "@optique/core/constructs";
+import { option } from "@optique/core/primitives";
 import { parseAsync } from "@optique/core/parser";
 
 const parser = object({
@@ -192,7 +200,8 @@ created by the factory share the same filesystem and directory options.
 
 ~~~~ typescript
 import { createGitParsers } from "@optique/git";
-import { argument, option, object } from "@optique/core/primitives";
+import { object } from "@optique/core/constructs";
+import { argument, option } from "@optique/core/primitives";
 import { parseAsync } from "@optique/core/parser";
 
 const git = createGitParsers({ dir: "/path/to/repo" });
@@ -224,7 +233,8 @@ the user's input prefix.
 
 ~~~~ typescript
 import { gitBranch } from "@optique/git";
-import { argument, object } from "@optique/core/primitives";
+import { object } from "@optique/core/constructs";
+import { argument } from "@optique/core/primitives";
 
 const parser = object({
   branch: argument(gitBranch()),

package/dist/index.cjs

@@ -37,15 +37,16 @@ const logger = (0, __logtape_logtape.getLogger)(["optique", "git"]);
 * Write methods are implemented as stubs that return rejected promises,
 * enforcing the read-only contract and preventing accidental writes.
 */
+const readOnlyFsMethod = () => Promise.reject(/* @__PURE__ */ new Error("gitFs is read-only for write operations."));
 const gitFs = {
 	readFile: node_fs_promises.readFile,
-	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.")),
+	writeFile: readOnlyFsMethod,
+	mkdir: readOnlyFsMethod,
+	rmdir: readOnlyFsMethod,
+	unlink: readOnlyFsMethod,
 	readdir: node_fs_promises.readdir,
 	readlink: node_fs_promises.readlink,
-	symlink: () => Promise.reject(/* @__PURE__ */ new Error("gitFs is read-only: symlink is disabled.")),
+	symlink: readOnlyFsMethod,
 	stat: node_fs_promises.stat,
 	lstat: node_fs_promises.lstat
 };
@@ -75,8 +76,55 @@ function listFailureMessage(error, dir, errors, fallback) {
 }
 /** Default depth for commit suggestions. */
 const DEFAULT_SUGGESTION_DEPTH = 15;
+/**
+* Computes the shortest unique short OID for each given full OID within the
+* provided set, starting from a minimum length.  When two or more OIDs share
+* the same short prefix, their prefixes are lengthened until each is unique
+* (up to the full 40-char OID).
+*
+* Note: this only disambiguates within the given set, not against the entire
+* object database.  In the rare case that a suggested short OID collides with
+* an older commit outside the suggestion window, the parser will report a
+* clear "ambiguous" error prompting the user to type more characters.
+*/
+function uniqueShortOids(oids, minLength) {
+	const result = /* @__PURE__ */ new Map();
+	const lengths = /* @__PURE__ */ new Map();
+	for (const oid of oids) lengths.set(oid, minLength);
+	let remaining = new Set(oids);
+	while (remaining.size > 0) {
+		const groups = /* @__PURE__ */ new Map();
+		for (const oid of remaining) {
+			const len = lengths.get(oid);
+			const short = oid.slice(0, len);
+			const group = groups.get(short);
+			if (group != null) group.push(oid);
+			else groups.set(short, [oid]);
+		}
+		const nextRemaining = /* @__PURE__ */ new Set();
+		for (const [short, group] of groups) if (group.length === 1) result.set(group[0], short);
+		else for (const oid of group) {
+			const currentLen = lengths.get(oid);
+			if (currentLen >= oid.length) result.set(oid, oid);
+			else {
+				lengths.set(oid, currentLen + 1);
+				nextRemaining.add(oid);
+			}
+		}
+		remaining = nextRemaining;
+	}
+	return result;
+}
 function createAsyncValueParser(options, metavar, parseFn, suggestFn) {
 	(0, __optique_core_nonempty.ensureNonEmptyString)(metavar);
+	if (options?.suggestionDepth !== void 0) {
+		if (!Number.isInteger(options.suggestionDepth) || options.suggestionDepth < 1) {
+			const depth = options.suggestionDepth;
+			const repr = typeof depth === "number" ? String(depth) : typeof depth === "string" ? JSON.stringify(depth) : `${typeof depth} ${String(depth)}`;
+			throw new RangeError(`Invalid suggestionDepth (must be a positive integer): ${repr}`);
+		}
+	}
+	const validatedDepth = options?.suggestionDepth ?? DEFAULT_SUGGESTION_DEPTH;
 	return {
 		$mode: "async",
 		metavar,
@@ -89,10 +137,7 @@ function createAsyncValueParser(options, metavar, parseFn, suggestFn) {
 		},
 		async *suggest(prefix) {
 			const dir = getRepoDir(options?.dir);
-			if (suggestFn) {
-				const depth = options?.suggestionDepth ?? DEFAULT_SUGGESTION_DEPTH;
-				yield* suggestFn(dir, prefix, depth);
-			}
+			if (suggestFn) yield* suggestFn(dir, prefix, validatedDepth);
 		}
 	};
 }
@@ -104,6 +149,7 @@ function createAsyncValueParser(options, metavar, parseFn, suggestFn) {
 *
 * @param options Configuration options for the parser.
 * @returns A value parser that accepts existing branch names.
+* @throws {RangeError} If `suggestionDepth` is not a positive integer.
 * @since 0.9.0
 *
 * @example
@@ -169,6 +215,7 @@ function gitBranch(options) {
 * @param remote The remote name to validate against.
 * @param options Configuration options for the parser.
 * @returns A value parser that accepts existing remote branch names.
+* @throws {RangeError} If `suggestionDepth` is not a positive integer.
 * @since 0.9.0
 *
 * @example
@@ -192,6 +239,27 @@ function gitRemoteBranch(remote, options) {
 				success: true,
 				value: input
 			};
+			if (branches.length === 0) {
+				const remotes = await isomorphic_git.listRemotes({
+					fs: gitFs,
+					dir
+				});
+				const names = remotes.map((r) => r.remote);
+				if (!names.includes(remote)) {
+					if (errors?.remoteNotFound) return {
+						success: false,
+						error: errors.remoteNotFound(remote, names)
+					};
+					if (errors?.notFound) return {
+						success: false,
+						error: errors.notFound(input, branches)
+					};
+					return {
+						success: false,
+						error: __optique_core_message.message`Remote ${(0, __optique_core_message.value)(remote)} does not exist. Available remotes: ${(0, __optique_core_message.valueSet)(names)}`
+					};
+				}
+			}
 			if (errors?.notFound) return {
 				success: false,
 				error: errors.notFound(input, branches)
@@ -233,6 +301,7 @@ function gitRemoteBranch(remote, options) {
 *
 * @param options Configuration options for the parser.
 * @returns A value parser that accepts existing tag names.
+* @throws {RangeError} If `suggestionDepth` is not a positive integer.
 * @since 0.9.0
 */
 function gitTag(options) {
@@ -286,6 +355,7 @@ function gitTag(options) {
 *
 * @param options Configuration options for the parser.
 * @returns A value parser that accepts existing remote names.
+* @throws {RangeError} If `suggestionDepth` is not a positive integer.
 * @since 0.9.0
 */
 function gitRemote(options) {
@@ -343,6 +413,7 @@ function gitRemote(options) {
 *
 * @param options Configuration options for the parser.
 * @returns A value parser that accepts existing commit SHAs.
+* @throws {RangeError} If `suggestionDepth` is not a positive integer.
 * @since 0.9.0
 */
 function gitCommit(options) {
@@ -369,7 +440,7 @@ function gitCommit(options) {
 				value: oid
 			};
 		} catch (e) {
-			if (hasErrorCode(e, "AmbiguousShortOidError")) return {
+			if (hasErrorCode(e, "AmbiguousShortOidError") || hasErrorCode(e, "AmbiguousError")) return {
 				success: false,
 				error: __optique_core_message.message`Commit SHA ${(0, __optique_core_message.value)(input)} is ambiguous. Provide more characters to disambiguate.`
 			};
@@ -389,8 +460,11 @@ function gitCommit(options) {
 				dir,
 				depth
 			});
-			for (const commit of commits) if (commit.oid.startsWith(prefix)) {
-				const shortOid = commit.oid.slice(0, 7);
+			const matching = commits.filter((c) => c.oid.startsWith(prefix));
+			const minLen = Math.max(7, prefix.length);
+			const shortOids = uniqueShortOids(matching.map((c) => c.oid), minLen);
+			for (const commit of matching) {
+				const shortOid = shortOids.get(commit.oid);
 				const firstLine = commit.commit.message.split("\n")[0];
 				yield {
 					kind: "literal",
@@ -415,6 +489,7 @@ function gitCommit(options) {
 *
 * @param options Configuration options for the parser.
 * @returns A value parser that accepts any git reference.
+* @throws {RangeError} If `suggestionDepth` is not a positive integer.
 * @since 0.9.0
 */
 function gitRef(options) {
@@ -443,7 +518,7 @@ function gitRef(options) {
 				value: oid
 			};
 		} catch (e) {
-			if (hasErrorCode(e, "AmbiguousShortOidError")) return {
+			if (hasErrorCode(e, "AmbiguousShortOidError") || hasErrorCode(e, "AmbiguousError")) return {
 				success: false,
 				error: __optique_core_message.message`Reference ${(0, __optique_core_message.value)(input)} is ambiguous. Provide more characters to disambiguate.`
 			};
@@ -473,16 +548,28 @@ function gitRef(options) {
 					depth
 				})
 			]);
-			for (const branch of branches) if (branch.startsWith(prefix)) yield {
-				kind: "literal",
-				text: branch
-			};
-			for (const tag of tags) if (tag.startsWith(prefix)) yield {
-				kind: "literal",
-				text: tag
-			};
-			for (const commit of commits) if (commit.oid.startsWith(prefix)) {
-				const shortOid = commit.oid.slice(0, 7);
+			const seen = /* @__PURE__ */ new Set();
+			for (const branch of branches) if (branch.startsWith(prefix) && !seen.has(branch)) {
+				seen.add(branch);
+				yield {
+					kind: "literal",
+					text: branch
+				};
+			}
+			for (const tag of tags) if (tag.startsWith(prefix) && !seen.has(tag)) {
+				seen.add(tag);
+				yield {
+					kind: "literal",
+					text: tag
+				};
+			}
+			const matching = commits.filter((c) => c.oid.startsWith(prefix));
+			const minLen = Math.max(7, prefix.length);
+			const shortOids = uniqueShortOids(matching.map((c) => c.oid), minLen);
+			for (const commit of matching) {
+				const shortOid = shortOids.get(commit.oid);
+				if (seen.has(shortOid)) continue;
+				seen.add(shortOid);
 				const firstLine = commit.commit.message.split("\n")[0];
 				yield {
 					kind: "literal",
@@ -503,7 +590,9 @@ function gitRef(options) {
 * Creates a set of git parsers with shared configuration.
 *
 * @param options Shared configuration for the parsers.
-* @returns An object containing git parsers.
+* @returns An object containing git parsers.  Each returned method may throw
+*   a {@link RangeError} if the merged `suggestionDepth` is not a positive
+*   integer.
 * @since 0.9.0
 */
 function createGitParsers(options) {

package/dist/index.d.cts

@@ -29,7 +29,9 @@ interface GitParserOptions {
   errors?: GitParserErrors;
   /**
    * Maximum number of recent commits to include in shell completion suggestions.
-   * Only applies to `gitCommit()` and `gitRef()` parsers.
+   * Only affects suggestions from `gitCommit()` and `gitRef()` parsers, but
+   * is validated by all git parser functions.
+   * Must be a positive integer.
    * Defaults to 15.
    *
    * @since 0.9.0
@@ -66,6 +68,16 @@ interface GitParserErrors {
    * @returns A custom error message.
    */
   invalidFormat?: (input: string) => Message;
+  /**
+   * Error message when the remote does not exist.
+   * Only used by {@link gitRemoteBranch}.
+   *
+   * @param remote The remote name that was not found.
+   * @param availableRemotes List of available remote names.
+   * @returns A custom error message.
+   * @since 1.0.0
+   */
+  remoteNotFound?: (remote: string, availableRemotes: readonly string[]) => Message;
 }
 /**
  * Git parsers factory interface.
@@ -77,6 +89,7 @@ interface GitParsers {
    * Creates a value parser that validates local branch names.
    * @param options Configuration options for the parser.
    * @returns A value parser that accepts existing branch names.
+   * @throws {RangeError} If `suggestionDepth` is not a positive integer.
    */
   branch(options?: GitParserOptions): ValueParser<"async", string>;
   /**
@@ -84,24 +97,28 @@ interface GitParsers {
    * @param remote The remote name to validate against.
    * @param options Configuration options for the parser.
    * @returns A value parser that accepts existing remote branch names.
+   * @throws {RangeError} If `suggestionDepth` is not a positive integer.
    */
   remoteBranch(remote: string, options?: GitParserOptions): ValueParser<"async", string>;
   /**
    * Creates a value parser that validates tag names.
    * @param options Configuration options for the parser.
    * @returns A value parser that accepts existing tag names.
+   * @throws {RangeError} If `suggestionDepth` is not a positive integer.
    */
   tag(options?: GitParserOptions): ValueParser<"async", string>;
   /**
    * Creates a value parser that validates remote names.
    * @param options Configuration options for the parser.
    * @returns A value parser that accepts existing remote names.
+   * @throws {RangeError} If `suggestionDepth` is not a positive integer.
    */
   remote(options?: GitParserOptions): ValueParser<"async", string>;
   /**
    * Creates a value parser that validates commit SHAs.
    * @param options Configuration options for the parser.
    * @returns A value parser that accepts existing commit SHAs.
+   * @throws {RangeError} If `suggestionDepth` is not a positive integer.
    */
   commit(options?: GitParserOptions): ValueParser<"async", string>;
   /**
@@ -109,6 +126,7 @@ interface GitParsers {
    * Accepts branch names, tag names, or commit SHAs.
    * @param options Configuration options for the parser.
    * @returns A value parser that accepts any git reference.
+   * @throws {RangeError} If `suggestionDepth` is not a positive integer.
    */
   ref(options?: GitParserOptions): ValueParser<"async", string>;
 }
@@ -120,6 +138,7 @@ interface GitParsers {
  *
  * @param options Configuration options for the parser.
  * @returns A value parser that accepts existing branch names.
+ * @throws {RangeError} If `suggestionDepth` is not a positive integer.
  * @since 0.9.0
  *
  * @example
@@ -140,6 +159,7 @@ declare function gitBranch(options?: GitParserOptions): ValueParser<"async", str
  * @param remote The remote name to validate against.
  * @param options Configuration options for the parser.
  * @returns A value parser that accepts existing remote branch names.
+ * @throws {RangeError} If `suggestionDepth` is not a positive integer.
  * @since 0.9.0
  *
  * @example
@@ -156,6 +176,7 @@ declare function gitRemoteBranch(remote: string, options?: GitParserOptions): Va
  *
  * @param options Configuration options for the parser.
  * @returns A value parser that accepts existing tag names.
+ * @throws {RangeError} If `suggestionDepth` is not a positive integer.
  * @since 0.9.0
  */
 declare function gitTag(options?: GitParserOptions): ValueParser<"async", string>;
@@ -164,6 +185,7 @@ declare function gitTag(options?: GitParserOptions): ValueParser<"async", string
  *
  * @param options Configuration options for the parser.
  * @returns A value parser that accepts existing remote names.
+ * @throws {RangeError} If `suggestionDepth` is not a positive integer.
  * @since 0.9.0
  */
 declare function gitRemote(options?: GitParserOptions): ValueParser<"async", string>;
@@ -175,6 +197,7 @@ declare function gitRemote(options?: GitParserOptions): ValueParser<"async", str
  *
  * @param options Configuration options for the parser.
  * @returns A value parser that accepts existing commit SHAs.
+ * @throws {RangeError} If `suggestionDepth` is not a positive integer.
  * @since 0.9.0
  */
 declare function gitCommit(options?: GitParserOptions): ValueParser<"async", string>;
@@ -186,6 +209,7 @@ declare function gitCommit(options?: GitParserOptions): ValueParser<"async", str
  *
  * @param options Configuration options for the parser.
  * @returns A value parser that accepts any git reference.
+ * @throws {RangeError} If `suggestionDepth` is not a positive integer.
  * @since 0.9.0
  */
 declare function gitRef(options?: GitParserOptions): ValueParser<"async", string>;
@@ -193,7 +217,9 @@ declare function gitRef(options?: GitParserOptions): ValueParser<"async", string
  * Creates a set of git parsers with shared configuration.
  *
  * @param options Shared configuration for the parsers.
- * @returns An object containing git parsers.
+ * @returns An object containing git parsers.  Each returned method may throw
+ *   a {@link RangeError} if the merged `suggestionDepth` is not a positive
+ *   integer.
  * @since 0.9.0
  */
 declare function createGitParsers(options?: GitParserOptions): GitParsers;

package/dist/index.d.ts

@@ -29,7 +29,9 @@ interface GitParserOptions {
   errors?: GitParserErrors;
   /**
    * Maximum number of recent commits to include in shell completion suggestions.
-   * Only applies to `gitCommit()` and `gitRef()` parsers.
+   * Only affects suggestions from `gitCommit()` and `gitRef()` parsers, but
+   * is validated by all git parser functions.
+   * Must be a positive integer.
    * Defaults to 15.
    *
    * @since 0.9.0
@@ -66,6 +68,16 @@ interface GitParserErrors {
    * @returns A custom error message.
    */
   invalidFormat?: (input: string) => Message;
+  /**
+   * Error message when the remote does not exist.
+   * Only used by {@link gitRemoteBranch}.
+   *
+   * @param remote The remote name that was not found.
+   * @param availableRemotes List of available remote names.
+   * @returns A custom error message.
+   * @since 1.0.0
+   */
+  remoteNotFound?: (remote: string, availableRemotes: readonly string[]) => Message;
 }
 /**
  * Git parsers factory interface.
@@ -77,6 +89,7 @@ interface GitParsers {
    * Creates a value parser that validates local branch names.
    * @param options Configuration options for the parser.
    * @returns A value parser that accepts existing branch names.
+   * @throws {RangeError} If `suggestionDepth` is not a positive integer.
    */
   branch(options?: GitParserOptions): ValueParser<"async", string>;
   /**
@@ -84,24 +97,28 @@ interface GitParsers {
    * @param remote The remote name to validate against.
    * @param options Configuration options for the parser.
    * @returns A value parser that accepts existing remote branch names.
+   * @throws {RangeError} If `suggestionDepth` is not a positive integer.
    */
   remoteBranch(remote: string, options?: GitParserOptions): ValueParser<"async", string>;
   /**
    * Creates a value parser that validates tag names.
    * @param options Configuration options for the parser.
    * @returns A value parser that accepts existing tag names.
+   * @throws {RangeError} If `suggestionDepth` is not a positive integer.
    */
   tag(options?: GitParserOptions): ValueParser<"async", string>;
   /**
    * Creates a value parser that validates remote names.
    * @param options Configuration options for the parser.
    * @returns A value parser that accepts existing remote names.
+   * @throws {RangeError} If `suggestionDepth` is not a positive integer.
    */
   remote(options?: GitParserOptions): ValueParser<"async", string>;
   /**
    * Creates a value parser that validates commit SHAs.
    * @param options Configuration options for the parser.
    * @returns A value parser that accepts existing commit SHAs.
+   * @throws {RangeError} If `suggestionDepth` is not a positive integer.
    */
   commit(options?: GitParserOptions): ValueParser<"async", string>;
   /**
@@ -109,6 +126,7 @@ interface GitParsers {
    * Accepts branch names, tag names, or commit SHAs.
    * @param options Configuration options for the parser.
    * @returns A value parser that accepts any git reference.
+   * @throws {RangeError} If `suggestionDepth` is not a positive integer.
    */
   ref(options?: GitParserOptions): ValueParser<"async", string>;
 }
@@ -120,6 +138,7 @@ interface GitParsers {
  *
  * @param options Configuration options for the parser.
  * @returns A value parser that accepts existing branch names.
+ * @throws {RangeError} If `suggestionDepth` is not a positive integer.
  * @since 0.9.0
  *
  * @example
@@ -140,6 +159,7 @@ declare function gitBranch(options?: GitParserOptions): ValueParser<"async", str
  * @param remote The remote name to validate against.
  * @param options Configuration options for the parser.
  * @returns A value parser that accepts existing remote branch names.
+ * @throws {RangeError} If `suggestionDepth` is not a positive integer.
  * @since 0.9.0
  *
  * @example
@@ -156,6 +176,7 @@ declare function gitRemoteBranch(remote: string, options?: GitParserOptions): Va
  *
  * @param options Configuration options for the parser.
  * @returns A value parser that accepts existing tag names.
+ * @throws {RangeError} If `suggestionDepth` is not a positive integer.
  * @since 0.9.0
  */
 declare function gitTag(options?: GitParserOptions): ValueParser<"async", string>;
@@ -164,6 +185,7 @@ declare function gitTag(options?: GitParserOptions): ValueParser<"async", string
  *
  * @param options Configuration options for the parser.
  * @returns A value parser that accepts existing remote names.
+ * @throws {RangeError} If `suggestionDepth` is not a positive integer.
  * @since 0.9.0
  */
 declare function gitRemote(options?: GitParserOptions): ValueParser<"async", string>;
@@ -175,6 +197,7 @@ declare function gitRemote(options?: GitParserOptions): ValueParser<"async", str
  *
  * @param options Configuration options for the parser.
  * @returns A value parser that accepts existing commit SHAs.
+ * @throws {RangeError} If `suggestionDepth` is not a positive integer.
  * @since 0.9.0
  */
 declare function gitCommit(options?: GitParserOptions): ValueParser<"async", string>;
@@ -186,6 +209,7 @@ declare function gitCommit(options?: GitParserOptions): ValueParser<"async", str
  *
  * @param options Configuration options for the parser.
  * @returns A value parser that accepts any git reference.
+ * @throws {RangeError} If `suggestionDepth` is not a positive integer.
  * @since 0.9.0
  */
 declare function gitRef(options?: GitParserOptions): ValueParser<"async", string>;
@@ -193,7 +217,9 @@ declare function gitRef(options?: GitParserOptions): ValueParser<"async", string
  * Creates a set of git parsers with shared configuration.
  *
  * @param options Shared configuration for the parsers.
- * @returns An object containing git parsers.
+ * @returns An object containing git parsers.  Each returned method may throw
+ *   a {@link RangeError} if the merged `suggestionDepth` is not a positive
+ *   integer.
  * @since 0.9.0
  */
 declare function createGitParsers(options?: GitParserOptions): GitParsers;

package/dist/index.js

@@ -15,15 +15,16 @@ const logger = getLogger(["optique", "git"]);
 * Write methods are implemented as stubs that return rejected promises,
 * enforcing the read-only contract and preventing accidental writes.
 */
+const readOnlyFsMethod = () => Promise.reject(/* @__PURE__ */ new Error("gitFs is read-only for write operations."));
 const gitFs = {
 	readFile: fs.readFile,
-	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.")),
+	writeFile: readOnlyFsMethod,
+	mkdir: readOnlyFsMethod,
+	rmdir: readOnlyFsMethod,
+	unlink: readOnlyFsMethod,
 	readdir: fs.readdir,
 	readlink: fs.readlink,
-	symlink: () => Promise.reject(/* @__PURE__ */ new Error("gitFs is read-only: symlink is disabled.")),
+	symlink: readOnlyFsMethod,
 	stat: fs.stat,
 	lstat: fs.lstat
 };
@@ -53,8 +54,55 @@ function listFailureMessage(error, dir, errors, fallback) {
 }
 /** Default depth for commit suggestions. */
 const DEFAULT_SUGGESTION_DEPTH = 15;
+/**
+* Computes the shortest unique short OID for each given full OID within the
+* provided set, starting from a minimum length.  When two or more OIDs share
+* the same short prefix, their prefixes are lengthened until each is unique
+* (up to the full 40-char OID).
+*
+* Note: this only disambiguates within the given set, not against the entire
+* object database.  In the rare case that a suggested short OID collides with
+* an older commit outside the suggestion window, the parser will report a
+* clear "ambiguous" error prompting the user to type more characters.
+*/
+function uniqueShortOids(oids, minLength) {
+	const result = /* @__PURE__ */ new Map();
+	const lengths = /* @__PURE__ */ new Map();
+	for (const oid of oids) lengths.set(oid, minLength);
+	let remaining = new Set(oids);
+	while (remaining.size > 0) {
+		const groups = /* @__PURE__ */ new Map();
+		for (const oid of remaining) {
+			const len = lengths.get(oid);
+			const short = oid.slice(0, len);
+			const group = groups.get(short);
+			if (group != null) group.push(oid);
+			else groups.set(short, [oid]);
+		}
+		const nextRemaining = /* @__PURE__ */ new Set();
+		for (const [short, group] of groups) if (group.length === 1) result.set(group[0], short);
+		else for (const oid of group) {
+			const currentLen = lengths.get(oid);
+			if (currentLen >= oid.length) result.set(oid, oid);
+			else {
+				lengths.set(oid, currentLen + 1);
+				nextRemaining.add(oid);
+			}
+		}
+		remaining = nextRemaining;
+	}
+	return result;
+}
 function createAsyncValueParser(options, metavar, parseFn, suggestFn) {
 	ensureNonEmptyString(metavar);
+	if (options?.suggestionDepth !== void 0) {
+		if (!Number.isInteger(options.suggestionDepth) || options.suggestionDepth < 1) {
+			const depth = options.suggestionDepth;
+			const repr = typeof depth === "number" ? String(depth) : typeof depth === "string" ? JSON.stringify(depth) : `${typeof depth} ${String(depth)}`;
+			throw new RangeError(`Invalid suggestionDepth (must be a positive integer): ${repr}`);
+		}
+	}
+	const validatedDepth = options?.suggestionDepth ?? DEFAULT_SUGGESTION_DEPTH;
 	return {
 		$mode: "async",
 		metavar,
@@ -67,10 +115,7 @@ function createAsyncValueParser(options, metavar, parseFn, suggestFn) {
 		},
 		async *suggest(prefix) {
 			const dir = getRepoDir(options?.dir);
-			if (suggestFn) {
-				const depth = options?.suggestionDepth ?? DEFAULT_SUGGESTION_DEPTH;
-				yield* suggestFn(dir, prefix, depth);
-			}
+			if (suggestFn) yield* suggestFn(dir, prefix, validatedDepth);
 		}
 	};
 }
@@ -82,6 +127,7 @@ function createAsyncValueParser(options, metavar, parseFn, suggestFn) {
 *
 * @param options Configuration options for the parser.
 * @returns A value parser that accepts existing branch names.
+* @throws {RangeError} If `suggestionDepth` is not a positive integer.
 * @since 0.9.0
 *
 * @example
@@ -147,6 +193,7 @@ function gitBranch(options) {
 * @param remote The remote name to validate against.
 * @param options Configuration options for the parser.
 * @returns A value parser that accepts existing remote branch names.
+* @throws {RangeError} If `suggestionDepth` is not a positive integer.
 * @since 0.9.0
 *
 * @example
@@ -170,6 +217,27 @@ function gitRemoteBranch(remote, options) {
 				success: true,
 				value: input
 			};
+			if (branches.length === 0) {
+				const remotes = await git.listRemotes({
+					fs: gitFs,
+					dir
+				});
+				const names = remotes.map((r) => r.remote);
+				if (!names.includes(remote)) {
+					if (errors?.remoteNotFound) return {
+						success: false,
+						error: errors.remoteNotFound(remote, names)
+					};
+					if (errors?.notFound) return {
+						success: false,
+						error: errors.notFound(input, branches)
+					};
+					return {
+						success: false,
+						error: message`Remote ${value(remote)} does not exist. Available remotes: ${valueSet(names)}`
+					};
+				}
+			}
 			if (errors?.notFound) return {
 				success: false,
 				error: errors.notFound(input, branches)
@@ -211,6 +279,7 @@ function gitRemoteBranch(remote, options) {
 *
 * @param options Configuration options for the parser.
 * @returns A value parser that accepts existing tag names.
+* @throws {RangeError} If `suggestionDepth` is not a positive integer.
 * @since 0.9.0
 */
 function gitTag(options) {
@@ -264,6 +333,7 @@ function gitTag(options) {
 *
 * @param options Configuration options for the parser.
 * @returns A value parser that accepts existing remote names.
+* @throws {RangeError} If `suggestionDepth` is not a positive integer.
 * @since 0.9.0
 */
 function gitRemote(options) {
@@ -321,6 +391,7 @@ function gitRemote(options) {
 *
 * @param options Configuration options for the parser.
 * @returns A value parser that accepts existing commit SHAs.
+* @throws {RangeError} If `suggestionDepth` is not a positive integer.
 * @since 0.9.0
 */
 function gitCommit(options) {
@@ -347,7 +418,7 @@ function gitCommit(options) {
 				value: oid
 			};
 		} catch (e) {
-			if (hasErrorCode(e, "AmbiguousShortOidError")) return {
+			if (hasErrorCode(e, "AmbiguousShortOidError") || hasErrorCode(e, "AmbiguousError")) return {
 				success: false,
 				error: message`Commit SHA ${value(input)} is ambiguous. Provide more characters to disambiguate.`
 			};
@@ -367,8 +438,11 @@ function gitCommit(options) {
 				dir,
 				depth
 			});
-			for (const commit of commits) if (commit.oid.startsWith(prefix)) {
-				const shortOid = commit.oid.slice(0, 7);
+			const matching = commits.filter((c) => c.oid.startsWith(prefix));
+			const minLen = Math.max(7, prefix.length);
+			const shortOids = uniqueShortOids(matching.map((c) => c.oid), minLen);
+			for (const commit of matching) {
+				const shortOid = shortOids.get(commit.oid);
 				const firstLine = commit.commit.message.split("\n")[0];
 				yield {
 					kind: "literal",
@@ -393,6 +467,7 @@ function gitCommit(options) {
 *
 * @param options Configuration options for the parser.
 * @returns A value parser that accepts any git reference.
+* @throws {RangeError} If `suggestionDepth` is not a positive integer.
 * @since 0.9.0
 */
 function gitRef(options) {
@@ -421,7 +496,7 @@ function gitRef(options) {
 				value: oid
 			};
 		} catch (e) {
-			if (hasErrorCode(e, "AmbiguousShortOidError")) return {
+			if (hasErrorCode(e, "AmbiguousShortOidError") || hasErrorCode(e, "AmbiguousError")) return {
 				success: false,
 				error: message`Reference ${value(input)} is ambiguous. Provide more characters to disambiguate.`
 			};
@@ -451,16 +526,28 @@ function gitRef(options) {
 					depth
 				})
 			]);
-			for (const branch of branches) if (branch.startsWith(prefix)) yield {
-				kind: "literal",
-				text: branch
-			};
-			for (const tag of tags) if (tag.startsWith(prefix)) yield {
-				kind: "literal",
-				text: tag
-			};
-			for (const commit of commits) if (commit.oid.startsWith(prefix)) {
-				const shortOid = commit.oid.slice(0, 7);
+			const seen = /* @__PURE__ */ new Set();
+			for (const branch of branches) if (branch.startsWith(prefix) && !seen.has(branch)) {
+				seen.add(branch);
+				yield {
+					kind: "literal",
+					text: branch
+				};
+			}
+			for (const tag of tags) if (tag.startsWith(prefix) && !seen.has(tag)) {
+				seen.add(tag);
+				yield {
+					kind: "literal",
+					text: tag
+				};
+			}
+			const matching = commits.filter((c) => c.oid.startsWith(prefix));
+			const minLen = Math.max(7, prefix.length);
+			const shortOids = uniqueShortOids(matching.map((c) => c.oid), minLen);
+			for (const commit of matching) {
+				const shortOid = shortOids.get(commit.oid);
+				if (seen.has(shortOid)) continue;
+				seen.add(shortOid);
 				const firstLine = commit.commit.message.split("\n")[0];
 				yield {
 					kind: "literal",
@@ -481,7 +568,9 @@ function gitRef(options) {
 * Creates a set of git parsers with shared configuration.
 *
 * @param options Shared configuration for the parsers.
-* @returns An object containing git parsers.
+* @returns An object containing git parsers.  Each returned method may throw
+*   a {@link RangeError} if the merged `suggestionDepth` is not a positive
+*   integer.
 * @since 0.9.0
 */
 function createGitParsers(options) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/git",
-  "version": "0.10.7",
+  "version": "1.0.0-dev.1116+6084dd3a",
   "description": "Git value parsers for Optique",
   "keywords": [
     "CLI",
@@ -59,7 +59,7 @@
   "dependencies": {
     "@logtape/logtape": "^1.2.2",
     "isomorphic-git": "^1.36.1",
-    "@optique/core": "0.10.7"
+    "@optique/core": "1.0.0-dev.1116+6084dd3a"
   },
   "devDependencies": {
     "@types/node": "^20.19.9",