@optique/git 0.9.0-dev.217 → 0.9.0-dev.248

package/dist/index.cjs

@@ -46,6 +46,14 @@ const METAVAR_REMOTE = "REMOTE";
 function getRepoDir(dirOption) {
 	return dirOption ?? (typeof node_process.default !== "undefined" ? node_process.default.cwd() : ".");
 }
+function formatChoiceList(choices) {
+	let result = [];
+	for (let i = 0; i < choices.length; i++) {
+		if (i > 0) result = [...result, ...__optique_core_message.message`, `];
+		result = [...result, ...__optique_core_message.message`${choices[i]}`];
+	}
+	return result;
+}
 function createAsyncValueParser(options, metavar, parseFn, suggestFn) {
 	return {
 		$mode: "async",
@@ -53,7 +61,7 @@ function createAsyncValueParser(options, metavar, parseFn, suggestFn) {
 		parse(input) {
 			const dir = getRepoDir(options?.dir);
 			(0, __optique_core_nonempty.ensureNonEmptyString)(metavar);
-			return parseFn(dir, input);
+			return parseFn(dir, input, options?.errors);
 		},
 		format(value) {
 			return value;
@@ -84,7 +92,7 @@ function createAsyncValueParser(options, metavar, parseFn, suggestFn) {
 */
 function gitBranch(options) {
 	const metavar = options?.metavar ?? METAVAR_BRANCH;
-	return createAsyncValueParser(options, metavar, async (dir, input) => {
+	return createAsyncValueParser(options, metavar, async (dir, input, errors) => {
 		try {
 			const branches = await isomorphic_git.listBranches({
 				fs: gitFs,
@@ -94,11 +102,19 @@ function gitBranch(options) {
 				success: true,
 				value: input
 			};
+			if (errors?.notFound) return {
+				success: false,
+				error: errors.notFound(input, branches)
+			};
 			return {
 				success: false,
-				error: __optique_core_message.message`Branch ${(0, __optique_core_message.text)(input)} does not exist. Available branches: ${branches.join(", ")}`
+				error: __optique_core_message.message`Branch ${(0, __optique_core_message.text)(input)} does not exist. Available branches: ${formatChoiceList(branches)}`
 			};
 		} catch {
+			if (errors?.listFailed) return {
+				success: false,
+				error: errors.listFailed(dir)
+			};
 			return {
 				success: false,
 				error: __optique_core_message.message`Failed to list branches. Ensure ${(0, __optique_core_message.text)(dir)} is a valid git repository.`
@@ -138,7 +154,7 @@ function gitBranch(options) {
 */
 function gitRemoteBranch(remote, options) {
 	const metavar = options?.metavar ?? METAVAR_BRANCH;
-	return createAsyncValueParser(options, metavar, async (dir, input) => {
+	return createAsyncValueParser(options, metavar, async (dir, input, errors) => {
 		try {
 			const branches = await isomorphic_git.listBranches({
 				fs: gitFs,
@@ -149,11 +165,19 @@ function gitRemoteBranch(remote, options) {
 				success: true,
 				value: input
 			};
+			if (errors?.notFound) return {
+				success: false,
+				error: errors.notFound(input, branches)
+			};
 			return {
 				success: false,
-				error: __optique_core_message.message`Remote branch ${(0, __optique_core_message.text)(input)} does not exist on remote ${(0, __optique_core_message.text)(remote)}. Available branches: ${branches.join(", ")}`
+				error: __optique_core_message.message`Remote branch ${(0, __optique_core_message.text)(input)} does not exist on remote ${(0, __optique_core_message.text)(remote)}. Available branches: ${formatChoiceList(branches)}`
 			};
 		} catch {
+			if (errors?.listFailed) return {
+				success: false,
+				error: errors.listFailed(dir)
+			};
 			return {
 				success: false,
 				error: __optique_core_message.message`Failed to list remote branches. Ensure remote ${(0, __optique_core_message.text)(remote)} exists.`
@@ -182,7 +206,7 @@ function gitRemoteBranch(remote, options) {
 */
 function gitTag(options) {
 	const metavar = options?.metavar ?? METAVAR_TAG;
-	return createAsyncValueParser(options, metavar, async (dir, input) => {
+	return createAsyncValueParser(options, metavar, async (dir, input, errors) => {
 		try {
 			const tags = await isomorphic_git.listTags({
 				fs: gitFs,
@@ -192,11 +216,19 @@ function gitTag(options) {
 				success: true,
 				value: input
 			};
+			if (errors?.notFound) return {
+				success: false,
+				error: errors.notFound(input, tags)
+			};
 			return {
 				success: false,
-				error: __optique_core_message.message`Tag ${(0, __optique_core_message.text)(input)} does not exist. Available tags: ${tags.join(", ")}`
+				error: __optique_core_message.message`Tag ${(0, __optique_core_message.text)(input)} does not exist. Available tags: ${formatChoiceList(tags)}`
 			};
 		} catch {
+			if (errors?.listFailed) return {
+				success: false,
+				error: errors.listFailed(dir)
+			};
 			return {
 				success: false,
 				error: __optique_core_message.message`Failed to list tags. Ensure ${(0, __optique_core_message.text)(dir)} is a valid git repository.`
@@ -224,7 +256,7 @@ function gitTag(options) {
 */
 function gitRemote(options) {
 	const metavar = options?.metavar ?? METAVAR_REMOTE;
-	return createAsyncValueParser(options, metavar, async (dir, input) => {
+	return createAsyncValueParser(options, metavar, async (dir, input, errors) => {
 		try {
 			const remotes = await isomorphic_git.listRemotes({
 				fs: gitFs,
@@ -235,11 +267,19 @@ function gitRemote(options) {
 				success: true,
 				value: input
 			};
+			if (errors?.notFound) return {
+				success: false,
+				error: errors.notFound(input, names)
+			};
 			return {
 				success: false,
-				error: __optique_core_message.message`Remote ${(0, __optique_core_message.text)(input)} does not exist. Available remotes: ${names.join(", ")}`
+				error: __optique_core_message.message`Remote ${(0, __optique_core_message.text)(input)} does not exist. Available remotes: ${formatChoiceList(names)}`
 			};
 		} catch {
+			if (errors?.listFailed) return {
+				success: false,
+				error: errors.listFailed(dir)
+			};
 			return {
 				success: false,
 				error: __optique_core_message.message`Failed to list remotes. Ensure ${(0, __optique_core_message.text)(dir)} is a valid git repository.`
@@ -270,19 +310,29 @@ function gitRemote(options) {
 */
 function gitCommit(options) {
 	const metavar = options?.metavar ?? "COMMIT";
-	return createAsyncValueParser(options, metavar, async (dir, input) => {
+	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.text)(input)}`
 			};
 		}
-		if (input.length < 4 || input.length > 40) return {
-			success: false,
-			error: __optique_core_message.message`Commit ${(0, __optique_core_message.text)(input)} must be between 4 and 40 characters.`
-		};
+		if (input.length < 4 || input.length > 40) {
+			if (errors?.invalidFormat) return {
+				success: false,
+				error: errors.invalidFormat(input)
+			};
+			return {
+				success: false,
+				error: __optique_core_message.message`Commit ${(0, __optique_core_message.text)(input)} must be between 4 and 40 characters.`
+			};
+		}
 		try {
 			const oid = await isomorphic_git.expandOid({
 				fs: gitFs,
@@ -294,6 +344,10 @@ function gitCommit(options) {
 				value: oid
 			};
 		} catch {
+			if (errors?.notFound) return {
+				success: false,
+				error: errors.notFound(input)
+			};
 			return {
 				success: false,
 				error: __optique_core_message.message`Commit ${(0, __optique_core_message.text)(input)} does not exist. Provide a valid commit SHA.`
@@ -313,7 +367,7 @@ function gitCommit(options) {
 */
 function gitRef(options) {
 	const metavar = options?.metavar ?? "REF";
-	return createAsyncValueParser(options, metavar, async (dir, input) => {
+	return createAsyncValueParser(options, metavar, async (dir, input, errors) => {
 		try {
 			const resolved = await isomorphic_git.resolveRef({
 				fs: gitFs,
@@ -336,6 +390,10 @@ function gitRef(options) {
 					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.text)(input)} does not exist. Provide a valid branch, tag, or commit SHA.`

package/dist/index.d.cts

@@ -1,4 +1,5 @@
 import { ValueParser } from "@optique/core/valueparser";
+import { Message } from "@optique/core/message";
 import { NonEmptyString } from "@optique/core/nonempty";
 import { expandOid, listBranches, listRemotes, listTags, readObject, resolveRef } from "isomorphic-git";
 
@@ -20,6 +21,43 @@ interface GitParserOptions {
    * Used in help messages to indicate what kind of value this parser expects.
    */
   metavar?: NonEmptyString;
+  /**
+   * Custom error messages for validation failures.
+   *
+   * @since 0.9.0
+   */
+  errors?: GitParserErrors;
+}
+/**
+ * Custom error messages for git value parsers.
+ *
+ * @since 0.9.0
+ */
+interface GitParserErrors {
+  /**
+   * Error message when the git reference (branch, tag, remote, commit) is not found.
+   *
+   * @param input The user-provided input that was not found.
+   * @param available List of available references (if applicable).
+   * @returns A custom error message.
+   */
+  notFound?: (input: string, available?: readonly string[]) => Message;
+  /**
+   * Error message when listing git references fails.
+   * This typically occurs when the directory is not a valid git repository.
+   *
+   * @param dir The directory that was being accessed.
+   * @returns A custom error message.
+   */
+  listFailed?: (dir: string) => Message;
+  /**
+   * Error message when the input format is invalid.
+   * Applies to parsers that validate format (e.g., commit SHA).
+   *
+   * @param input The user-provided input that has invalid format.
+   * @returns A custom error message.
+   */
+  invalidFormat?: (input: string) => Message;
 }
 /**
  * Git parsers factory interface.
@@ -152,4 +190,4 @@ declare function gitRef(options?: GitParserOptions): ValueParser<"async", string
  */
 declare function createGitParsers(options?: GitParserOptions): GitParsers;
 //#endregion
-export { GitParserOptions, GitParsers, createGitParsers, expandOid, gitBranch, gitCommit, gitRef, gitRemote, gitRemoteBranch, gitTag, listBranches, listRemotes, listTags, readObject, resolveRef };
+export { GitParserErrors, GitParserOptions, GitParsers, createGitParsers, expandOid, gitBranch, gitCommit, gitRef, gitRemote, gitRemoteBranch, gitTag, listBranches, listRemotes, listTags, readObject, resolveRef };

package/dist/index.d.ts

@@ -1,3 +1,4 @@
+import { Message } from "@optique/core/message";
 import { NonEmptyString } from "@optique/core/nonempty";
 import { expandOid, listBranches, listRemotes, listTags, readObject, resolveRef } from "isomorphic-git";
 import { ValueParser } from "@optique/core/valueparser";
@@ -20,6 +21,43 @@ interface GitParserOptions {
    * Used in help messages to indicate what kind of value this parser expects.
    */
   metavar?: NonEmptyString;
+  /**
+   * Custom error messages for validation failures.
+   *
+   * @since 0.9.0
+   */
+  errors?: GitParserErrors;
+}
+/**
+ * Custom error messages for git value parsers.
+ *
+ * @since 0.9.0
+ */
+interface GitParserErrors {
+  /**
+   * Error message when the git reference (branch, tag, remote, commit) is not found.
+   *
+   * @param input The user-provided input that was not found.
+   * @param available List of available references (if applicable).
+   * @returns A custom error message.
+   */
+  notFound?: (input: string, available?: readonly string[]) => Message;
+  /**
+   * Error message when listing git references fails.
+   * This typically occurs when the directory is not a valid git repository.
+   *
+   * @param dir The directory that was being accessed.
+   * @returns A custom error message.
+   */
+  listFailed?: (dir: string) => Message;
+  /**
+   * Error message when the input format is invalid.
+   * Applies to parsers that validate format (e.g., commit SHA).
+   *
+   * @param input The user-provided input that has invalid format.
+   * @returns A custom error message.
+   */
+  invalidFormat?: (input: string) => Message;
 }
 /**
  * Git parsers factory interface.
@@ -152,4 +190,4 @@ declare function gitRef(options?: GitParserOptions): ValueParser<"async", string
  */
 declare function createGitParsers(options?: GitParserOptions): GitParsers;
 //#endregion
-export { GitParserOptions, GitParsers, createGitParsers, expandOid, gitBranch, gitCommit, gitRef, gitRemote, gitRemoteBranch, gitTag, listBranches, listRemotes, listTags, readObject, resolveRef };
+export { GitParserErrors, GitParserOptions, GitParsers, createGitParsers, expandOid, gitBranch, gitCommit, gitRef, gitRemote, gitRemoteBranch, gitTag, listBranches, listRemotes, listTags, readObject, resolveRef };

package/dist/index.js

@@ -24,6 +24,14 @@ const METAVAR_REMOTE = "REMOTE";
 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",
@@ -31,7 +39,7 @@ function createAsyncValueParser(options, metavar, parseFn, suggestFn) {
 		parse(input) {
 			const dir = getRepoDir(options?.dir);
 			ensureNonEmptyString(metavar);
-			return parseFn(dir, input);
+			return parseFn(dir, input, options?.errors);
 		},
 		format(value) {
 			return value;
@@ -62,7 +70,7 @@ function createAsyncValueParser(options, metavar, parseFn, suggestFn) {
 */
 function gitBranch(options) {
 	const metavar = options?.metavar ?? METAVAR_BRANCH;
-	return createAsyncValueParser(options, metavar, async (dir, input) => {
+	return createAsyncValueParser(options, metavar, async (dir, input, errors) => {
 		try {
 			const branches = await git.listBranches({
 				fs: gitFs,
@@ -72,11 +80,19 @@ function gitBranch(options) {
 				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.`
@@ -116,7 +132,7 @@ function gitBranch(options) {
 */
 function gitRemoteBranch(remote, options) {
 	const metavar = options?.metavar ?? METAVAR_BRANCH;
-	return createAsyncValueParser(options, metavar, async (dir, input) => {
+	return createAsyncValueParser(options, metavar, async (dir, input, errors) => {
 		try {
 			const branches = await git.listBranches({
 				fs: gitFs,
@@ -127,11 +143,19 @@ 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.`
@@ -160,7 +184,7 @@ function gitRemoteBranch(remote, options) {
 */
 function gitTag(options) {
 	const metavar = options?.metavar ?? METAVAR_TAG;
-	return createAsyncValueParser(options, metavar, async (dir, input) => {
+	return createAsyncValueParser(options, metavar, async (dir, input, errors) => {
 		try {
 			const tags = await git.listTags({
 				fs: gitFs,
@@ -170,11 +194,19 @@ function gitTag(options) {
 				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.`
@@ -202,7 +234,7 @@ function gitTag(options) {
 */
 function gitRemote(options) {
 	const metavar = options?.metavar ?? METAVAR_REMOTE;
-	return createAsyncValueParser(options, metavar, async (dir, input) => {
+	return createAsyncValueParser(options, metavar, async (dir, input, errors) => {
 		try {
 			const remotes = await git.listRemotes({
 				fs: gitFs,
@@ -213,11 +245,19 @@ function gitRemote(options) {
 				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: ${names.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.`
@@ -248,19 +288,29 @@ function gitRemote(options) {
 */
 function gitCommit(options) {
 	const metavar = options?.metavar ?? "COMMIT";
-	return createAsyncValueParser(options, metavar, async (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) return {
-			success: false,
-			error: message`Commit ${text(input)} must be between 4 and 40 characters.`
-		};
+		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: gitFs,
@@ -272,6 +322,10 @@ function gitCommit(options) {
 				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.`
@@ -291,7 +345,7 @@ function gitCommit(options) {
 */
 function gitRef(options) {
 	const metavar = options?.metavar ?? "REF";
-	return createAsyncValueParser(options, metavar, async (dir, input) => {
+	return createAsyncValueParser(options, metavar, async (dir, input, errors) => {
 		try {
 			const resolved = await git.resolveRef({
 				fs: gitFs,
@@ -314,6 +368,10 @@ function gitRef(options) {
 					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.`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/git",
-  "version": "0.9.0-dev.217+7fc9df46",
+  "version": "0.9.0-dev.248+a552207e",
   "description": "Git value parsers for Optique",
   "keywords": [
     "CLI",