@gunshi/plugin 0.35.1 → 0.35.2

package/lib/index.d.ts

@@ -1,4 +1,4 @@
-//#region ../../node_modules/.pnpm/args-tokens@0.27.0/node_modules/args-tokens/lib/parser-DT7Ztcch.d.ts
+//#region ../../node_modules/.pnpm/args-tokens@0.28.0/node_modules/args-tokens/lib/parser-DT7Ztcch.d.ts
 //#region src/parser.d.ts
 /**
  * Entry point of argument parser.
@@ -55,7 +55,7 @@ interface ArgToken {
  * Parser Options.
  */
 //#endregion
-//#region ../../node_modules/.pnpm/args-tokens@0.27.0/node_modules/args-tokens/lib/resolver.d.ts
+//#region ../../node_modules/.pnpm/args-tokens@0.28.0/node_modules/args-tokens/lib/resolver.d.ts
 //#region src/resolver.d.ts
 /**
  * An argument schema definition for command-line argument parsing.
@@ -476,7 +476,7 @@ interface ArgSchema {
    *
    * @param value - Raw string value from command line
    * @returns Parsed value of any type
-   * @throws Error or subclass when value is invalid
+   * @throws {Error} Error or subclass when value is invalid
    *
    * @example
    * Custom parsing functions:
@@ -508,6 +508,64 @@ interface ArgSchema {
    */
   parse?: (value: string) => any;
 }
+/**
+ * Machine-readable error codes for {@link ArgsValidationError}.
+ *
+ * Each code identifies a validation failure category and is also suitable as an
+ * i18n resource key for localized rendering.
+ */
+declare const ArgsValidationErrorKeys: {
+  readonly requiredOption: "err:arg:required-option";
+  readonly requiredPositional: "err:arg:required-positional";
+  readonly invalidType: "err:arg:invalid-type";
+  readonly invalidChoice: "err:arg:invalid-choice";
+  readonly customParse: "err:arg:custom-parse";
+  readonly unknownOption: "err:arg:unknown-option";
+};
+/**
+ * A machine-readable argument validation error code.
+ *
+ * Each code is one of {@link ArgsValidationErrorKeys} and can also be used as
+ * an i18n resource key.
+ */
+type ArgsValidationErrorCode = (typeof ArgsValidationErrorKeys)[keyof typeof ArgsValidationErrorKeys];
+/**
+ * An error that contains structured metadata for argument validation failures.
+ *
+ * The `message` remains the English fallback message. Renderers can use `code`
+ * and `values` to localize the error, falling back to `message` when localization
+ * is unavailable.
+ */
+declare class ArgsValidationError extends Error {
+  /**
+   * Machine-readable error code for this validation failure.
+   *
+   * This code can also be used as an i18n resource key.
+   */
+  readonly code?: ArgsValidationErrorCode;
+  /**
+   * Interpolation values for `code`.
+   */
+  readonly values: Record<string, unknown>;
+  /**
+   * Create an `ArgsValidationError` instance.
+   *
+   * @param message - fallback error message
+   * @param options - structured validation metadata
+   */
+  constructor(message: string, options?: {
+    code?: ArgsValidationErrorCode;
+    values?: Record<string, unknown>;
+    cause?: unknown;
+  });
+}
+/**
+ * Check whether the given value is an {@link ArgsValidationError}.
+ *
+ * @param error - value to check
+ * @returns `true` when the value is an `ArgsValidationError`
+ */
+declare function isArgsValidationError(error: unknown): error is ArgsValidationError;
 /**
  * An object that contains {@link ArgSchema | argument schema}.
  *
@@ -1132,6 +1190,13 @@ interface CommandEnvironment<G extends GunshiParamsConstraint = DefaultGunshiPar
    * @see {@linkcode CliOptions.usageSilent}
    */
   usageSilent: boolean;
+  /**
+   * Whether to treat undefined options as argument validation errors.
+   *
+   * @default false
+   * @see {@linkcode CliOptions.strict}
+   */
+  strict: boolean;
   /**
    * Sub commands.
    *
@@ -1219,6 +1284,16 @@ interface CliOptions<G extends GunshiParamsConstraint = DefaultGunshiParams> {
    * Whether to display the command usage.
    */
   usageSilent?: boolean;
+  /**
+   * Whether to treat undefined options as argument validation errors.
+   *
+   * When enabled, option tokens that are not declared by the resolved command
+   * arguments or installed global options are reported as validation errors
+   * before the command runner is executed.
+   *
+   * @default false
+   */
+  strict?: boolean;
   /**
    * Render function the command usage.
    */
@@ -1754,6 +1829,82 @@ declare function createCommandContext<G extends GunshiParamsConstraint = Default
   validationError
 }: CommandContextParams<G, V, C, E>): Promise<CommandContextResult<G, E>>;
 //#endregion
+//#region ../gunshi/src/error.d.ts
+/**
+ * @author kazuya kawaguchi (a.k.a. kazupon)
+ * @license MIT
+ */
+/**
+ * Command not found error resource keys.
+ */
+declare const CommandNotFoundErrorKeys: {
+  readonly notFound: "err:cmd:not-found";
+};
+/**
+ * Command not found error code.
+ */
+type CommandNotFoundErrorCode = (typeof CommandNotFoundErrorKeys)[keyof typeof CommandNotFoundErrorKeys];
+/**
+ * Options for {@link CommandNotFoundError}.
+ */
+type CommandNotFoundErrorOptions = {
+  /**
+   * Localization resource key for command-not-found rendering.
+   */
+  code?: CommandNotFoundErrorCode;
+  /**
+   * Values used when localizing the message.
+   */
+  values?: Record<string, unknown>;
+  /**
+   * The command name that could not be resolved.
+   */
+  commandName: string;
+  /**
+   * Command names available at the same level.
+   */
+  candidates?: readonly string[];
+  /**
+   * Parent command path where resolution failed.
+   */
+  commandPath?: readonly string[];
+  /**
+   * Underlying cause.
+   */
+  cause?: unknown;
+};
+/**
+ * Error raised when a command cannot be resolved.
+ */
+declare class CommandNotFoundError extends Error {
+  readonly code?: CommandNotFoundErrorCode;
+  readonly values: Record<string, unknown>;
+  readonly commandName: string;
+  readonly candidates: readonly string[];
+  readonly commandPath: readonly string[];
+  /**
+   * Create a command-not-found error.
+   *
+   * @param message - Fallback error message
+   * @param options - Command-not-found metadata
+   */
+  constructor(message: string, options: CommandNotFoundErrorOptions);
+}
+/**
+ * Check whether an error is a {@link CommandNotFoundError}.
+ *
+ * @param error - An unknown error
+ * @returns `true` if the error is a {@link CommandNotFoundError}
+ */
+declare function isCommandNotFoundError(error: unknown): error is CommandNotFoundError;
+/**
+ * Check whether validation errors should be handled before version, help, or command execution.
+ *
+ * @param error - An aggregate validation error
+ * @returns `true` if the validation error must be handled with priority
+ */
+declare function hasPriorityValidationError(error: AggregateError | undefined): boolean;
+//#endregion
 //#region src/index.d.ts
 /**
 * @author kazuya kawaguchi (a.k.a. kazupon)
@@ -1761,4 +1912,4 @@ declare function createCommandContext<G extends GunshiParamsConstraint = Default
 */
 
 //#endregion
-export { ANONYMOUS_COMMAND_NAME, type ArgSchema, type ArgToken, type ArgValues, type Args, Awaitable, CLI_OPTIONS_DEFAULT, Command, CommandContext, CommandContextCore, CommandContextExtension, CommandContextParams, CommandDecorator, CommandExamplesFetcher, CommandRunner, DefaultGunshiParams, ExtendContext, ExtractArgs, ExtractExtensions, GunshiParams, GunshiParamsConstraint, LazyCommand, MergeGunshiExtensions, NormalizeToGunshiParams, OnPluginExtension, Plugin, PluginContext, PluginDependency, PluginExtension, PluginFunction, PluginOptions, PluginWithExtension, PluginWithoutExtension, Prettify, RendererDecorator, ValidationErrorsDecorator, createCommandContext, plugin };
+export { ANONYMOUS_COMMAND_NAME, type ArgSchema, type ArgToken, type ArgValues, type Args, ArgsValidationError, ArgsValidationErrorCode, ArgsValidationErrorKeys, Awaitable, CLI_OPTIONS_DEFAULT, Command, CommandContext, CommandContextCore, CommandContextExtension, CommandContextParams, CommandDecorator, CommandExamplesFetcher, CommandNotFoundError, CommandNotFoundErrorCode, CommandNotFoundErrorKeys, CommandNotFoundErrorOptions, CommandRunner, DefaultGunshiParams, ExtendContext, ExtractArgs, ExtractExtensions, GunshiParams, GunshiParamsConstraint, LazyCommand, MergeGunshiExtensions, NormalizeToGunshiParams, OnPluginExtension, Plugin, PluginContext, PluginDependency, PluginExtension, PluginFunction, PluginOptions, PluginWithExtension, PluginWithoutExtension, Prettify, RendererDecorator, ValidationErrorsDecorator, createCommandContext, hasPriorityValidationError, isArgsValidationError, isCommandNotFoundError, plugin };

package/lib/index.js

@@ -19,6 +19,7 @@ const CLI_OPTIONS_DEFAULT = {
 	middleMargin: 10,
 	usageOptionType: false,
 	usageOptionValue: true,
+	strict: false,
 	renderHeader: void 0,
 	renderUsage: void 0,
 	renderValidationErrors: void 0,
@@ -161,6 +162,144 @@ function getCommandName(cmd) {
 	else if (typeof cmd === "object") return cmd.name || "(anonymous)";
 	else return ANONYMOUS_COMMAND_NAME;
 }
+/**
+* forked from `nodejs/node` (`pkgjs/parseargs`)
+* repository url: https://github.com/nodejs/node (https://github.com/pkgjs/parseargs)
+* code url: https://github.com/nodejs/node/blob/main/lib/internal/util/parse_args/parse_args.js
+*
+* @author kazuya kawaguchi (a.k.a. kazupon)
+* @license MIT
+*/
+"-".codePointAt(0);
+"=".codePointAt(0);
+//#endregion
+//#region ../../node_modules/.pnpm/args-tokens@0.28.0/node_modules/args-tokens/lib/resolver.js
+/**
+* Entry point of argument options resolver.
+*
+* @module
+*/
+/**
+* @author kazuya kawaguchi (a.k.a. kazupon)
+* @license MIT
+*/
+/**
+* Machine-readable error codes for {@link ArgsValidationError}.
+*
+* Each code identifies a validation failure category and is also suitable as an
+* i18n resource key for localized rendering.
+*/
+const ArgsValidationErrorKeys = {
+	requiredOption: "err:arg:required-option",
+	requiredPositional: "err:arg:required-positional",
+	invalidType: "err:arg:invalid-type",
+	invalidChoice: "err:arg:invalid-choice",
+	customParse: "err:arg:custom-parse",
+	unknownOption: "err:arg:unknown-option"
+};
+/**
+* An error that contains structured metadata for argument validation failures.
+*
+* The `message` remains the English fallback message. Renderers can use `code`
+* and `values` to localize the error, falling back to `message` when localization
+* is unavailable.
+*/
+var ArgsValidationError = class extends Error {
+	/**
+	* Machine-readable error code for this validation failure.
+	*
+	* This code can also be used as an i18n resource key.
+	*/
+	code;
+	/**
+	* Interpolation values for `code`.
+	*/
+	values;
+	/**
+	* Create an `ArgsValidationError` instance.
+	*
+	* @param message - fallback error message
+	* @param options - structured validation metadata
+	*/
+	constructor(message, options = {}) {
+		super(message, { cause: options.cause });
+		this.name = "ArgsValidationError";
+		this.code = options.code;
+		this.values = options.values ?? {};
+	}
+};
+/**
+* Check whether the given value is an {@link ArgsValidationError}.
+*
+* @param error - value to check
+* @returns `true` when the value is an `ArgsValidationError`
+*/
+function isArgsValidationError(error) {
+	return error instanceof ArgsValidationError;
+}
+//#endregion
+//#region ../../node_modules/.pnpm/args-tokens@0.28.0/node_modules/args-tokens/lib/index.js
+/**
+* @author kazuya kawaguchi (a.k.a. kazupon)
+* @license MIT
+*/
+/**
+* @author kazuya kawaguchi (a.k.a. kazupon)
+* @license MIT
+*/
+//#endregion
+//#region ../gunshi/src/error.ts
+/**
+* @author kazuya kawaguchi (a.k.a. kazupon)
+* @license MIT
+*/
+/**
+* Command not found error resource keys.
+*/
+const CommandNotFoundErrorKeys = { notFound: "err:cmd:not-found" };
+/**
+* Error raised when a command cannot be resolved.
+*/
+var CommandNotFoundError = class extends Error {
+	code;
+	values;
+	commandName;
+	candidates;
+	commandPath;
+	/**
+	* Create a command-not-found error.
+	*
+	* @param message - Fallback error message
+	* @param options - Command-not-found metadata
+	*/
+	constructor(message, options) {
+		super(message, { cause: options.cause });
+		this.name = "CommandNotFoundError";
+		this.code = options.code;
+		this.values = options.values || {};
+		this.commandName = options.commandName;
+		this.candidates = options.candidates || [];
+		this.commandPath = options.commandPath || [];
+	}
+};
+/**
+* Check whether an error is a {@link CommandNotFoundError}.
+*
+* @param error - An unknown error
+* @returns `true` if the error is a {@link CommandNotFoundError}
+*/
+function isCommandNotFoundError(error) {
+	return error instanceof CommandNotFoundError;
+}
+/**
+* Check whether validation errors should be handled before version, help, or command execution.
+*
+* @param error - An aggregate validation error
+* @returns `true` if the validation error must be handled with priority
+*/
+function hasPriorityValidationError(error) {
+	return error?.errors.some((error) => isCommandNotFoundError(error) || isArgsValidationError(error) && error.code === ArgsValidationErrorKeys.unknownOption) ?? false;
+}
 //#endregion
 //#region ../gunshi/src/plugin/core.ts
 /**
@@ -213,10 +352,16 @@ function plugin(options = {}) {
 	});
 }
 //#endregion
+//#region ../gunshi/src/plugin.ts
+/**
+* @author kazuya kawaguchi (a.k.a. kazupon)
+* @license MIT
+*/
+//#endregion
 //#region src/index.ts
 /**
 * @author kazuya kawaguchi (a.k.a. kazupon)
 * @license MIT
 */
 //#endregion
-export { ANONYMOUS_COMMAND_NAME, CLI_OPTIONS_DEFAULT, createCommandContext, plugin };
+export { ANONYMOUS_COMMAND_NAME, ArgsValidationError, ArgsValidationErrorKeys, CLI_OPTIONS_DEFAULT, CommandNotFoundError, CommandNotFoundErrorKeys, createCommandContext, hasPriorityValidationError, isArgsValidationError, isCommandNotFoundError, plugin };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@gunshi/plugin",
   "description": "plugin development kit for gunshi",
-  "version": "0.35.1",
+  "version": "0.35.2",
   "author": {
     "name": "kazuya kawaguchi",
     "email": "kawakazu80@gmail.com"
@@ -56,7 +56,7 @@
     "jsr-exports-lint": "^0.4.2",
     "publint": "^0.3.20",
     "tsdown": "0.21.0",
-    "gunshi": "0.35.1"
+    "gunshi": "0.35.2"
   },
   "scripts": {
     "build": "tsdown",