@gunshi/shared 0.35.1 → 0.35.3

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,13 @@ 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.
+ */
+
 /**
  * An object that contains {@link ArgSchema | argument schema}.
  *
@@ -759,6 +766,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.
    *
@@ -1112,7 +1126,7 @@ type CommandExamplesFetcher<G extends GunshiParamsConstraint = DefaultGunshiPara
  */
 type CommandRunner<G extends GunshiParamsConstraint = DefaultGunshiParams> = (ctx: Readonly<CommandContext<G>>) => Awaitable<string | void>;
 //#endregion
-//#region ../../node_modules/.pnpm/args-tokens@0.27.0/node_modules/args-tokens/lib/utils.d.ts
+//#region ../../node_modules/.pnpm/args-tokens@0.28.0/node_modules/args-tokens/lib/utils.d.ts
 //#region src/utils.d.ts
 /**
  * Entry point of utils.
@@ -1132,7 +1146,12 @@ type CommandRunner<G extends GunshiParamsConstraint = DefaultGunshiParams> = (ct
  * @returns Converted string into kebab-case.
  */
 declare function kebabnize(str: string): string;
-//#endregion
+/**
+ * Format allowed argument choices for validation error values and fallback messages.
+ *
+ * @param choices - Choice values to format
+ * @returns JSON-quoted choices joined with `, `.
+ */
 //#endregion
 //#region ../gunshi/src/utils.d.ts
 /**
@@ -1188,9 +1207,11 @@ declare function deepFreeze<T extends Record<string, any>>(obj: T, ignores?: str
 declare const BUILT_IN_PREFIX = "_";
 declare const PLUGIN_PREFIX = "g";
 declare const ARG_PREFIX = "arg";
+declare const ERROR_PREFIX = "err";
 declare const BUILT_IN_KEY_SEPARATOR = ":";
 declare const BUILD_IN_PREFIX_AND_KEY_SEPARATOR: string;
 declare const ARG_PREFIX_AND_KEY_SEPARATOR: string;
+declare const ERROR_PREFIX_AND_KEY_SEPARATOR: string;
 declare const ARG_NEGATABLE_PREFIX = "no-";
 type CommonArgType = {
   readonly help: {
@@ -1206,6 +1227,9 @@ type CommonArgType = {
 };
 declare const COMMON_ARGS: CommonArgType;
 declare const COMMAND_BUILTIN_RESOURCE_KEYS: readonly ["USAGE", "COMMAND", "SUBCOMMAND", "COMMANDS", "ARGUMENTS", "OPTIONS", "EXAMPLES", "FORMORE", "NEGATABLE", "DEFAULT", "CHOICES"];
+declare const ARG_ERROR_RESOURCE_KEYS: readonly ["err:arg:required-option", "err:arg:required-positional", "err:arg:invalid-type", "err:arg:invalid-choice", "err:arg:custom-parse", "err:arg:unknown-option"];
+declare const COMMAND_ERROR_RESOURCE_KEYS: readonly ["err:cmd:not-found"];
+declare const SUGGESTION_ERROR_RESOURCE_KEYS: readonly ["err:suggestion:did-you-mean"];
 //#endregion
 //#region src/types.d.ts
 type RemoveIndexSignature<T> = { [K in keyof T as string extends K ? never : number extends K ? never : K]: T[K] };
@@ -1233,14 +1257,34 @@ type CommandBuiltinArgsKeys = keyof typeof COMMON_ARGS;
  * Command i18n built-in resource keys.
  */
 type CommandBuiltinResourceKeys = (typeof COMMAND_BUILTIN_RESOURCE_KEYS)[number];
+/**
+ * Args validation error resource keys.
+ */
+type ArgErrorResourceKeys = (typeof ARG_ERROR_RESOURCE_KEYS)[number];
+/**
+ * Command validation error resource keys.
+ */
+type CommandErrorResourceKeys = (typeof COMMAND_ERROR_RESOURCE_KEYS)[number];
+/**
+ * Suggestion error resource keys.
+ */
+type SuggestionErrorResourceKeys = (typeof SUGGESTION_ERROR_RESOURCE_KEYS)[number];
+/**
+ * Error resource keys.
+ */
+type ErrorResourceKeys = ArgErrorResourceKeys | CommandErrorResourceKeys | SuggestionErrorResourceKeys;
 /**
  * Built-in resource keys.
  */
-type BuiltinResourceKeys = CommandBuiltinArgsKeys | CommandBuiltinResourceKeys;
+type BuiltinResourceKeys = ErrorResourceKeys | CommandBuiltinArgsKeys | CommandBuiltinResourceKeys;
+/**
+ * Built-in resource.
+ */
+type BuiltinResource = Partial<Record<BuiltinResourceKeys, string>>;
 /**
  * Command built-in keys.
  */
-type CommandBuiltinKeys = GenerateNamespacedKey<BuiltinResourceKeys>;
+type CommandBuiltinKeys = GenerateNamespacedKey<CommandBuiltinArgsKeys | CommandBuiltinResourceKeys>;
 /**
  * Command i18n option keys.
  * The command i18n option keys are used by the i18n plugin for translation.
@@ -1257,7 +1301,7 @@ E extends Record<string, string> = {},
 // for extended resources
 R extends string = keyof RemovedIndex<E>, T extends string = (C extends {
   name: infer N;
-} ? N extends string ? GenerateNamespacedKey<R, N> : R : R | CommandBuiltinKeys), O = CommandArgKeys<A, C>> = CommandBuiltinKeys | O | T;
+} ? N extends string ? GenerateNamespacedKey<R, N> : R : R | CommandBuiltinKeys), O = CommandArgKeys<A, C>> = ErrorResourceKeys | CommandBuiltinKeys | O | T;
 /**
  * Translation function interface
  */
@@ -1301,24 +1345,39 @@ declare function localizable<A extends Args, C = {},
 E extends Record<string, string> = {},
 // for extended resources
 K = ResolveTranslationKeys<A, C, E>>(ctx: CommandContext, cmd: Command, translate?: Translation<A, C, E, K>): Localization<A, C, E>;
+/**
+ * Format a resource message by replacing placeholder values.
+ *
+ * @param resource - Resource message template
+ * @param values - Placeholder values
+ * @returns Formatted resource message
+ */
+declare function formatResource(resource: string | undefined, values?: Record<string, unknown>): string | undefined;
 //#endregion
 //#region ../resources/locales/en-US.d.ts
-declare let COMMAND: string;
-declare let COMMANDS: string;
-declare let SUBCOMMAND: string;
-declare let USAGE: string;
-declare let ARGUMENTS: string;
-declare let OPTIONS: string;
-declare let EXAMPLES: string;
-declare let FORMORE: string;
-declare let NEGATABLE: string;
-declare let DEFAULT: string;
-declare let CHOICES: string;
-declare let help: string;
-declare let version: string;
-declare namespace __json_default_export {
-  export { COMMAND, COMMANDS, SUBCOMMAND, USAGE, ARGUMENTS, OPTIONS, EXAMPLES, FORMORE, NEGATABLE, DEFAULT, CHOICES, help, version };
-}
+declare const _exports: {
+  COMMAND: string;
+  COMMANDS: string;
+  SUBCOMMAND: string;
+  USAGE: string;
+  ARGUMENTS: string;
+  OPTIONS: string;
+  EXAMPLES: string;
+  FORMORE: string;
+  NEGATABLE: string;
+  DEFAULT: string;
+  CHOICES: string;
+  help: string;
+  version: string;
+  "err:arg:required-option": string;
+  "err:arg:required-positional": string;
+  "err:arg:invalid-type": string;
+  "err:arg:invalid-choice": string;
+  "err:arg:custom-parse": string;
+  "err:arg:unknown-option": string;
+  "err:cmd:not-found": string;
+  "err:suggestion:did-you-mean": string;
+};
 //#endregion
 //#region src/utils.d.ts
 /**
@@ -1393,4 +1452,4 @@ declare function makeShortLongOptionPair(schema: ArgSchema, name: string, toKeba
 */
 
 //#endregion
-export { ARG_NEGATABLE_PREFIX, ARG_PREFIX, ARG_PREFIX_AND_KEY_SEPARATOR, BUILD_IN_PREFIX_AND_KEY_SEPARATOR, BUILT_IN_KEY_SEPARATOR, BUILT_IN_PREFIX, BuiltinResourceKeys, COMMAND_BUILTIN_RESOURCE_KEYS, COMMON_ARGS, CommandArgKeys, CommandBuiltinArgsKeys, CommandBuiltinKeys, CommandBuiltinResourceKeys, DeepWriteable, __json_default_export as DefaultResource, GenerateNamespacedKey, KeyOfArgs, Localization, PLUGIN_PREFIX, RemovedIndex, ResolveTranslationKeys, Translation, create, deepFreeze, getCommandSubCommands, isLazyCommand, kebabnize, localizable, log, makeShortLongOptionPair, namespacedId, resolveArgKey, resolveBuiltInKey, resolveExamples, resolveKey, resolveLazyCommand };
+export { ARG_ERROR_RESOURCE_KEYS, ARG_NEGATABLE_PREFIX, ARG_PREFIX, ARG_PREFIX_AND_KEY_SEPARATOR, ArgErrorResourceKeys, BUILD_IN_PREFIX_AND_KEY_SEPARATOR, BUILT_IN_KEY_SEPARATOR, BUILT_IN_PREFIX, BuiltinResource, BuiltinResourceKeys, COMMAND_BUILTIN_RESOURCE_KEYS, COMMAND_ERROR_RESOURCE_KEYS, COMMON_ARGS, CommandArgKeys, CommandBuiltinArgsKeys, CommandBuiltinKeys, CommandBuiltinResourceKeys, CommandErrorResourceKeys, DeepWriteable, _exports as DefaultResource, ERROR_PREFIX, ERROR_PREFIX_AND_KEY_SEPARATOR, ErrorResourceKeys, GenerateNamespacedKey, KeyOfArgs, Localization, PLUGIN_PREFIX, RemovedIndex, ResolveTranslationKeys, SUGGESTION_ERROR_RESOURCE_KEYS, SuggestionErrorResourceKeys, Translation, create, deepFreeze, formatResource, getCommandSubCommands, isLazyCommand, kebabnize, localizable, log, makeShortLongOptionPair, namespacedId, resolveArgKey, resolveBuiltInKey, resolveExamples, resolveKey, resolveLazyCommand };

package/lib/index.js

@@ -1,4 +1,4 @@
-//#region ../../node_modules/.pnpm/args-tokens@0.27.0/node_modules/args-tokens/lib/utils.js
+//#region ../../node_modules/.pnpm/args-tokens@0.28.0/node_modules/args-tokens/lib/utils.js
 /**
 * Entry point of utils.
 *
@@ -136,9 +136,11 @@ function deepFreeze(obj, ignores = []) {
 const BUILT_IN_PREFIX = "_";
 const PLUGIN_PREFIX = "g";
 const ARG_PREFIX = "arg";
+const ERROR_PREFIX = "err";
 const BUILT_IN_KEY_SEPARATOR = ":";
 const BUILD_IN_PREFIX_AND_KEY_SEPARATOR = `_:`;
 const ARG_PREFIX_AND_KEY_SEPARATOR = `arg:`;
+const ERROR_PREFIX_AND_KEY_SEPARATOR = `err:`;
 const ARG_NEGATABLE_PREFIX = "no-";
 const COMMON_ARGS = {
 	help: {
@@ -165,6 +167,16 @@ const COMMAND_BUILTIN_RESOURCE_KEYS = [
 	"DEFAULT",
 	"CHOICES"
 ];
+const ARG_ERROR_RESOURCE_KEYS = [
+	"err:arg:required-option",
+	"err:arg:required-positional",
+	"err:arg:invalid-type",
+	"err:arg:invalid-choice",
+	"err:arg:custom-parse",
+	"err:arg:unknown-option"
+];
+const COMMAND_ERROR_RESOURCE_KEYS = ["err:cmd:not-found"];
+const SUGGESTION_ERROR_RESOURCE_KEYS = ["err:suggestion:did-you-mean"];
 //#endregion
 //#region ../resources/locales/en-US.json
 var NEGATABLE = "Negatable of";
@@ -181,7 +193,15 @@ var en_US_default = {
 	DEFAULT: "default",
 	CHOICES: "choices",
 	help: "Display this help message",
-	version: "Display this version"
+	version: "Display this version",
+	"err:arg:required-option": "Optional argument {$displayName} is required",
+	"err:arg:required-positional": "Positional argument {$name} is required",
+	"err:arg:invalid-type": "Invalid value for {$displayName}: expected {$expected}",
+	"err:arg:invalid-choice": "Invalid value for {$displayName}: expected one of {$choices}",
+	"err:arg:custom-parse": "Invalid value for {$displayName}: {$reason}",
+	"err:arg:unknown-option": "Unknown option: {$rawName}",
+	"err:cmd:not-found": "Command not found: {$commandName}",
+	"err:suggestion:did-you-mean": "Did you mean {$name}?"
 };
 //#endregion
 //#region src/utils.ts
@@ -290,7 +310,8 @@ function makeShortLongOptionPair(schema, name, toKebab) {
 function localizable(ctx, cmd, translate) {
 	async function localize(key, values) {
 		if (translate) return translate(key, values);
-		if (key.startsWith(BUILD_IN_PREFIX_AND_KEY_SEPARATOR)) return en_US_default[key.slice(BUILD_IN_PREFIX_AND_KEY_SEPARATOR.length)] || key;
+		if (key.startsWith(BUILD_IN_PREFIX_AND_KEY_SEPARATOR)) return resolveAndFormatResource(key.slice(BUILD_IN_PREFIX_AND_KEY_SEPARATOR.length), key, values);
+		if (key.startsWith(ERROR_PREFIX_AND_KEY_SEPARATOR)) return resolveAndFormatResource(key, key, values);
 		const namaspacedArgKey = resolveKey(ARG_PREFIX_AND_KEY_SEPARATOR, ctx.name);
 		if (key.startsWith(namaspacedArgKey)) {
 			let argKey = key.slice(namaspacedArgKey.length);
@@ -309,6 +330,21 @@ function localizable(ctx, cmd, translate) {
 	}
 	return localize;
 }
+function resolveAndFormatResource(resourceKey, fallbackKey, values) {
+	return formatResource(en_US_default[resourceKey], values) || fallbackKey;
+}
+/**
+* Format a resource message by replacing placeholder values.
+*
+* @param resource - Resource message template
+* @param values - Placeholder values
+* @returns Formatted resource message
+*/
+function formatResource(resource, values = Object.create(null)) {
+	return resource?.replaceAll(/\{\$(\w+)\}/g, (_, name) => {
+		return values[name] == null ? "" : String(values[name]);
+	});
+}
 //#endregion
 //#region src/index.ts
 /**
@@ -316,4 +352,4 @@ function localizable(ctx, cmd, translate) {
 * @license MIT
 */
 //#endregion
-export { ARG_NEGATABLE_PREFIX, ARG_PREFIX, ARG_PREFIX_AND_KEY_SEPARATOR, BUILD_IN_PREFIX_AND_KEY_SEPARATOR, BUILT_IN_KEY_SEPARATOR, BUILT_IN_PREFIX, COMMAND_BUILTIN_RESOURCE_KEYS, COMMON_ARGS, en_US_default as DefaultResource, PLUGIN_PREFIX, create, deepFreeze, getCommandSubCommands, isLazyCommand, kebabnize, localizable, log, makeShortLongOptionPair, namespacedId, resolveArgKey, resolveBuiltInKey, resolveExamples, resolveKey, resolveLazyCommand };
+export { ARG_ERROR_RESOURCE_KEYS, ARG_NEGATABLE_PREFIX, ARG_PREFIX, ARG_PREFIX_AND_KEY_SEPARATOR, BUILD_IN_PREFIX_AND_KEY_SEPARATOR, BUILT_IN_KEY_SEPARATOR, BUILT_IN_PREFIX, COMMAND_BUILTIN_RESOURCE_KEYS, COMMAND_ERROR_RESOURCE_KEYS, COMMON_ARGS, en_US_default as DefaultResource, ERROR_PREFIX, ERROR_PREFIX_AND_KEY_SEPARATOR, PLUGIN_PREFIX, SUGGESTION_ERROR_RESOURCE_KEYS, create, deepFreeze, formatResource, getCommandSubCommands, isLazyCommand, kebabnize, localizable, log, makeShortLongOptionPair, namespacedId, resolveArgKey, resolveBuiltInKey, resolveExamples, resolveKey, resolveLazyCommand };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@gunshi/shared",
   "description": "shared utils for gunshi",
-  "version": "0.35.1",
+  "version": "0.35.3",
   "author": {
     "name": "kazuya kawaguchi",
     "email": "kawakazu80@gmail.com"
@@ -55,8 +55,8 @@
     "jsr-exports-lint": "^0.4.2",
     "publint": "^0.3.20",
     "tsdown": "0.21.0",
-    "@gunshi/resources": "0.35.1",
-    "gunshi": "0.35.1"
+    "@gunshi/resources": "0.35.3",
+    "gunshi": "0.35.3"
   },
   "scripts": {
     "build": "tsdown",