@gunshi/bone 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,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}.
  *
@@ -922,6 +929,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.
    *
@@ -1009,6 +1023,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.
    */

package/lib/index.js

@@ -1,4 +1,4 @@
-//#region ../../node_modules/.pnpm/args-tokens@0.27.0/node_modules/args-tokens/lib/parser.js
+//#region ../../node_modules/.pnpm/args-tokens@0.28.0/node_modules/args-tokens/lib/parser.js
 /**
 * forked from `nodejs/node` (`pkgjs/parseargs`)
 * repository url: https://github.com/nodejs/node (https://github.com/pkgjs/parseargs)
@@ -203,7 +203,7 @@ function hasOptionValue(value) {
 	return !(value == null) && value.codePointAt(0) !== HYPHEN_CODE;
 }
 //#endregion
-//#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.
 *
@@ -224,8 +224,17 @@ function hasOptionValue(value) {
 function kebabnize(str) {
 	return str.replace(/[A-Z]/g, (match, offset) => (offset > 0 ? "-" : "") + match.toLowerCase());
 }
+/**
+* Format allowed argument choices for validation error values and fallback messages.
+*
+* @param choices - Choice values to format
+* @returns JSON-quoted choices joined with `, `.
+*/
+function formatChoices(choices) {
+	return choices.map((value) => JSON.stringify(value)).join(", ");
+}
 //#endregion
-//#region ../../node_modules/.pnpm/args-tokens@0.27.0/node_modules/args-tokens/lib/resolver.js
+//#region ../../node_modules/.pnpm/args-tokens@0.28.0/node_modules/args-tokens/lib/resolver.js
 /**
 * Entry point of argument options resolver.
 *
@@ -235,6 +244,60 @@ function kebabnize(str) {
 * @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;
+}
 const SKIP_POSITIONAL_DEFAULT = -1;
 /**
 * Resolve command line arguments.
@@ -398,11 +461,9 @@ function resolveArgs(args, tokens, { shortGrouping = false, skipPositional = SKI
 							const parsed = [];
 							for (let i = positionalsCount; i < endPositionals; i++) {
 								const p = positionalTokens[i];
-								try {
-									parsed.push(schema.parse(p.value));
-								} catch (error) {
-									errors.push(error);
-								}
+								const [parsedValue, error] = parseSchemaValue(p.value, rawArg, arg, schema);
+								if (error) errors.push(error);
+								else parsed.push(parsedValue);
 							}
 							values[rawArg] = parsed;
 						} else {
@@ -412,22 +473,22 @@ function resolveArgs(args, tokens, { shortGrouping = false, skipPositional = SKI
 						}
 						positionalsCount = endPositionals;
 						explicit[rawArg] = true;
-					} else if (schema.required) errors.push(createRequireError(arg, schema));
-				} else if (schema.required) errors.push(createRequireError(arg, schema));
+					} else if (schema.required) errors.push(createRequireError(rawArg, arg, schema));
+				} else if (schema.required) errors.push(createRequireError(rawArg, arg, schema));
 			} else {
 				const positional = positionalTokens[positionalsCount];
 				if (shouldRequireMissingSinglePositional(schema)) {
 					if (positional != null) {
-						resolveSinglePositionalValue(values, errors, rawArg, schema, positional);
+						resolveSinglePositionalValue(values, errors, rawArg, arg, schema, positional);
 						explicit[rawArg] = true;
 						positionalsCount++;
-					} else errors.push(createRequireError(arg, schema));
+					} else errors.push(createRequireError(rawArg, arg, schema));
 					continue;
 				}
 				if (positional != null) {
 					const requiredPositionals = getRequiredPositionalsAfter(rawArg);
 					if (Math.max(positionalTokens.length - positionalsCount, 0) > requiredPositionals) {
-						resolveSinglePositionalValue(values, errors, rawArg, schema, positional);
+						resolveSinglePositionalValue(values, errors, rawArg, arg, schema, positional);
 						explicit[rawArg] = true;
 						positionalsCount++;
 						continue;
@@ -441,14 +502,14 @@ function resolveArgs(args, tokens, { shortGrouping = false, skipPositional = SKI
 			if (!optionTokens.find((token) => {
 				return schema.short && token.name === schema.short || token.rawName && hasLongOptionPrefix(token.rawName) && token.name === arg;
 			})) {
-				errors.push(createRequireError(arg, schema));
+				errors.push(createRequireError(rawArg, arg, schema));
 				continue;
 			}
 		}
 		for (let i = 0; i < optionTokens.length; i++) {
 			const token = optionTokens[i];
 			if (checkTokenName(arg, schema, token) && token.rawName != void 0 && hasLongOptionPrefix(token.rawName) || schema.short === token.name && token.rawName != void 0 && isShortOption(token.rawName)) {
-				const invalid = validateRequire(token, arg, schema);
+				const invalid = validateRequire(token, rawArg, arg, schema);
 				if (invalid) {
 					errors.push(invalid);
 					continue;
@@ -456,7 +517,7 @@ function resolveArgs(args, tokens, { shortGrouping = false, skipPositional = SKI
 				explicit[rawArg] = true;
 				const actualInputName = isShortOption(token.rawName) ? `-${token.name}` : `--${arg}`;
 				actualInputNames.set(rawArg, actualInputName);
-				const [parsedValue, error] = parse(token, arg, schema);
+				const [parsedValue, error] = parse(token, rawArg, arg, schema);
 				if (error) errors.push(error);
 				else if (schema.multiple) {
 					values[rawArg] ||= [];
@@ -476,39 +537,49 @@ function resolveArgs(args, tokens, { shortGrouping = false, skipPositional = SKI
 		explicit
 	};
 }
-function parse(token, option, schema) {
-	if (typeof schema.parse === "function") try {
+function parse(token, rawArg, option, schema) {
+	if (typeof schema.parse === "function") {
 		if (schema.type === "boolean") {
 			const boolValue = !(schema.negatable && token.name.startsWith("no-"));
-			return [schema.parse(String(boolValue)), void 0];
+			return parseSchemaValue(String(boolValue), rawArg, option, schema);
 		}
-		return [schema.parse(token.value ?? String(schema.default ?? "")), void 0];
-	} catch (error) {
-		return [void 0, error];
+		return parseSchemaValue(token.value ?? String(schema.default ?? ""), rawArg, option, schema);
 	}
 	switch (schema.type) {
-		case "string": return typeof token.value === "string" ? [token.value || schema.default, void 0] : [void 0, createTypeError(option, schema)];
+		case "string": return typeof token.value === "string" ? [token.value || schema.default, void 0] : [void 0, createTypeError(rawArg, option, schema, token.value)];
 		case "boolean": return [!(schema.negatable && token.name.startsWith("no-")), void 0];
 		case "number":
-			if (!isNumeric(token.value)) return [void 0, createTypeError(option, schema)];
+			if (!isNumeric(token.value)) return [void 0, createTypeError(rawArg, option, schema, token.value)];
 			return token.value ? [+token.value, void 0] : [+(schema.default || ""), void 0];
 		case "enum":
-			if (schema.choices && !schema.choices.includes(token.value)) return [void 0, new ArgResolveError(`Optional argument '--${option}' ${schema.short ? `or '-${schema.short}' ` : ""}should be chosen from '${schema.type}' [${schema.choices.map((c) => JSON.stringify(c)).join(", ")}] values`, option, "type", schema)];
+			if (schema.choices && !schema.choices.includes(token.value)) return [void 0, createChoiceError(rawArg, option, schema, token.value)];
 			return [token.value || schema.default, void 0];
 		case "custom": throw new TypeError(`argument '${option}' should have a 'parse' function`);
 		default: throw new Error(`Unsupported argument type '${schema.type}' for option '${option}'`);
 	}
 }
-function createRequireError(option, schema) {
-	return new ArgResolveError(schema.type === "positional" ? `Positional argument '${option}' is required` : `Optional argument '--${option}' ${schema.short ? `or '-${schema.short}' ` : ""}is required`, option, "required", schema);
-}
-function resolveSinglePositionalValue(values, errors, rawArg, schema, positional) {
-	if (typeof schema.parse === "function") try {
-		values[rawArg] = schema.parse(positional.value);
+function parseSchemaValue(value, rawArg, option, schema) {
+	try {
+		return [schema.parse(value), void 0];
 	} catch (error) {
-		errors.push(error);
+		return [void 0, createCustomParseError(error, rawArg, option, schema, value)];
 	}
-	else values[rawArg] = positional.value;
+}
+function createRequireError(rawArg, option, schema) {
+	return new ArgResolveError(schema.type === "positional" ? `Positional argument '${option}' is required` : `Optional argument ${createOptionDisplayName(option, schema)} is required`, option, "required", schema, {
+		code: schema.type === "positional" ? ArgsValidationErrorKeys.requiredPositional : ArgsValidationErrorKeys.requiredOption,
+		values: schema.type === "positional" ? { name: rawArg } : {
+			displayName: createOptionDisplayName(option, schema),
+			name: rawArg
+		}
+	});
+}
+function resolveSinglePositionalValue(values, errors, rawArg, option, schema, positional) {
+	if (typeof schema.parse === "function") {
+		const [parsedValue, error] = parseSchemaValue(positional.value, rawArg, option, schema);
+		if (error) errors.push(error);
+		else values[rawArg] = parsedValue;
+	} else values[rawArg] = positional.value;
 }
 function hasDefault(schema) {
 	return schema.default != null;
@@ -538,7 +609,7 @@ function createRequiredPositionalsAfter(argEntries) {
 * An error that occurs when resolving arguments.
 * This error is thrown when the argument is not valid.
 */
-var ArgResolveError = class extends Error {
+var ArgResolveError = class extends ArgsValidationError {
 	name;
 	schema;
 	type;
@@ -547,24 +618,78 @@ var ArgResolveError = class extends Error {
 	*
 	* @param message - the error message
 	* @param name - the name of the argument
-	* @param type - the type of the error, either 'type' or 'required'
+	* @param type - the type of the error: 'type', 'required', or 'conflict'
 	* @param schema - the argument schema that caused the error
+	* @param options - structured validation metadata
 	*/
-	constructor(message, name, type, schema) {
-		super(message);
+	constructor(message, name, type, schema, options = {}) {
+		super(message, options);
 		this.name = name;
 		this.type = type;
 		this.schema = schema;
 	}
 };
-function validateRequire(token, option, schema) {
-	if (schema.required && schema.type !== "boolean" && !token.value) return createRequireError(option, schema);
+function validateRequire(token, rawArg, option, schema) {
+	if (schema.required && schema.type !== "boolean" && !token.value) return createRequireError(rawArg, option, schema);
 }
 function isNumeric(str) {
 	return str.trim() !== "" && !isNaN(str);
 }
-function createTypeError(option, schema) {
-	return new ArgResolveError(`Optional argument '--${option}' ${schema.short ? `or '-${schema.short}' ` : ""}should be '${schema.type}'`, option, "type", schema);
+function createTypeError(rawArg, option, schema, actual) {
+	return new ArgResolveError(`Optional argument ${createOptionDisplayName(option, schema)} should be '${schema.type}'`, option, "type", schema, {
+		code: ArgsValidationErrorKeys.invalidType,
+		values: {
+			displayName: createOptionDisplayName(option, schema),
+			name: rawArg,
+			expected: schema.type,
+			...actual != null ? { actual } : {}
+		}
+	});
+}
+function createChoiceError(rawArg, option, schema, actual) {
+	const choices = schema.choices ?? [];
+	return new ArgResolveError(`Optional argument ${createOptionDisplayName(option, schema)} should be chosen from '${schema.type}' [${formatChoices(choices)}] values`, option, "type", schema, {
+		code: ArgsValidationErrorKeys.invalidChoice,
+		values: {
+			displayName: createOptionDisplayName(option, schema),
+			name: rawArg,
+			expected: schema.type,
+			choices: formatChoices(choices),
+			choiceValues: [...choices],
+			...actual != null ? { actual } : {}
+		}
+	});
+}
+function createCustomParseError(error, rawArg, option, schema, value) {
+	if (isArgsValidationError(error)) {
+		augmentValidationError(error, rawArg, option, schema, value);
+		return error;
+	}
+	const reason = getErrorReason(error);
+	return new ArgsValidationError(reason, {
+		code: ArgsValidationErrorKeys.customParse,
+		values: {
+			displayName: createArgumentDisplayName(option, schema),
+			name: rawArg,
+			reason
+		},
+		cause: error
+	});
+}
+function augmentValidationError(error, rawArg, option, schema, value) {
+	const values = error.values;
+	values.name ??= rawArg;
+	values.displayName ??= createArgumentDisplayName(option, schema);
+	if ((error.code === ArgsValidationErrorKeys.invalidType || error.code === ArgsValidationErrorKeys.invalidChoice) && values.actual == null) values.actual = value;
+}
+function getErrorReason(error) {
+	return error instanceof Error ? error.message : String(error);
+}
+function createArgumentDisplayName(option, schema) {
+	return schema.type === "positional" ? `'${option}'` : createOptionDisplayName(option, schema);
+}
+function createOptionDisplayName(option, schema) {
+	return `'--${option}'${schema.short ? ` or '-${schema.short}'` : ""}`;
 }
 function checkConflicts(args, explicit, toKebab, actualInputNames) {
 	for (const rawArg in args) {
@@ -583,7 +708,7 @@ function checkConflicts(args, explicit, toKebab, actualInputNames) {
 	return [];
 }
 //#endregion
-//#region ../../node_modules/.pnpm/args-tokens@0.27.0/node_modules/args-tokens/lib/index.js
+//#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
@@ -614,6 +739,7 @@ const CLI_OPTIONS_DEFAULT = {
 	middleMargin: 10,
 	usageOptionType: false,
 	usageOptionValue: true,
+	strict: false,
 	renderHeader: void 0,
 	renderUsage: void 0,
 	renderValidationErrors: void 0,
@@ -885,6 +1011,59 @@ function createDecorators() {
 	});
 }
 //#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/context.ts
 /**
 * @author kazuya kawaguchi (a.k.a. kazupon)
@@ -1008,17 +1187,35 @@ async function cliCore(argv, entry, options, plugins) {
 	const tokens = parseArgs(argv);
 	const resolved = resolveCommandTree(tokens, entry, cliOptions);
 	const { commandName: name, command, callMode, commandPath, depth, levelSubCommands } = resolved;
-	if (!command) throw new Error(`Command not found: ${name || ""}`);
-	if (levelSubCommands) cliOptions.subCommands = levelSubCommands;
-	const resolvedCommand = isLazyCommand(command) ? await resolveLazyCommand(command, name, true) : command;
+	let targetCommand = command;
+	let targetCommandName = name;
+	let targetCallMode = callMode;
+	let targetCommandPath = commandPath;
+	let targetDepth = depth;
+	let targetOmitted = resolved.omitted;
+	let targetLevelSubCommands = levelSubCommands;
+	const additionalValidationErrors = [];
+	if (!targetCommand) {
+		if (!resolved.parentCommand || !resolved.unresolvedCommandName) throw new Error(`Command not found: ${name || ""}`);
+		targetCommand = resolved.parentCommand;
+		targetCommandName = resolved.parentCommandName;
+		targetCommandPath = resolved.parentCommandPath || [];
+		targetDepth = targetCommandPath.length;
+		targetCallMode = targetDepth > 0 ? "subCommand" : "entry";
+		targetOmitted = false;
+		targetLevelSubCommands = resolved.parentSubCommands;
+		additionalValidationErrors.push(createCommandNotFoundError(resolved));
+	}
+	if (targetLevelSubCommands) cliOptions.subCommands = targetLevelSubCommands;
+	const resolvedCommand = isLazyCommand(targetCommand) ? await resolveLazyCommand(targetCommand, targetCommandName, true) : targetCommand;
 	const args = resolveArguments(pluginContext, getCommandArgs(resolvedCommand));
-	const skipPositional = depth > 0 ? depth - 1 : -1;
+	const skipPositional = targetDepth > 0 ? targetDepth - 1 : -1;
 	const { explicit, values, positionals, rest, error } = resolveArgs(args, tokens, {
 		shortGrouping: true,
 		toKebab: resolvedCommand.toKebab,
 		skipPositional
 	});
-	const omitted = resolved.omitted;
+	const validationError = mergeValidationErrors(error, [...additionalValidationErrors, ...cliOptions.strict ? createUnknownOptionErrors(findUnknownOptions(args, tokens, { toKebab: resolvedCommand.toKebab })) : []]);
 	return await executeCommand(resolvedCommand, await createCommandContext({
 		args,
 		explicit,
@@ -1027,12 +1224,12 @@ async function cliCore(argv, entry, options, plugins) {
 		rest,
 		argv,
 		tokens,
-		omitted,
-		callMode,
-		commandPath,
+		omitted: targetOmitted,
+		callMode: targetCallMode,
+		commandPath: targetCommandPath,
 		command: resolvedCommand,
 		extensions: getPluginExtensions(resolvedPlugins),
-		validationError: error,
+		validationError,
 		cliOptions
 	}), decorators.commandDecorators);
 }
@@ -1060,6 +1257,66 @@ function getCommandArgs(cmd) {
 function resolveArguments(pluginContext, args) {
 	return Object.assign(create(), Object.fromEntries(pluginContext.globalOptions), args);
 }
+const NEGATABLE_OPTION_PREFIX = "no-";
+function findUnknownOptions(args, tokens, options) {
+	const knownLongOptions = /* @__PURE__ */ new Set();
+	const knownShortOptions = /* @__PURE__ */ new Set();
+	const knownNegatableOptions = /* @__PURE__ */ new Set();
+	const knownLongOptionCandidates = /* @__PURE__ */ new Set();
+	const longOptionCandidates = [];
+	function addLongOptionCandidate(name) {
+		const candidate = `--${name}`;
+		if (knownLongOptionCandidates.has(candidate)) return;
+		knownLongOptionCandidates.add(candidate);
+		longOptionCandidates.push(candidate);
+	}
+	for (const [name, schema] of Object.entries(args)) {
+		if (schema.type === "positional") continue;
+		const optionName = resolveOptionName(name, schema, options);
+		knownLongOptions.add(optionName);
+		addLongOptionCandidate(optionName);
+		if (schema.short) knownShortOptions.add(schema.short);
+		if (schema.type === "boolean" && schema.negatable) {
+			const negatableOptionName = `${NEGATABLE_OPTION_PREFIX}${optionName}`;
+			knownNegatableOptions.add(negatableOptionName);
+			addLongOptionCandidate(negatableOptionName);
+		}
+	}
+	const unknownOptions = [];
+	for (const token of tokens) {
+		if (token.kind === "option-terminator") break;
+		if (token.kind !== "option" || !token.name || !token.rawName) continue;
+		const isLongOption = token.rawName.startsWith("--");
+		if (isLongOption) {
+			if (knownLongOptions.has(token.name) || knownNegatableOptions.has(token.name)) continue;
+		} else if (knownShortOptions.has(token.name)) continue;
+		unknownOptions.push({
+			rawName: token.rawName,
+			name: token.name,
+			candidates: isLongOption ? longOptionCandidates : []
+		});
+	}
+	return unknownOptions;
+}
+function resolveOptionName(name, schema, options) {
+	return options.toKebab || schema.toKebab ? kebabnize(name) : name;
+}
+function createUnknownOptionErrors(unknownOptions) {
+	return unknownOptions.map(({ rawName, name, candidates }) => {
+		return new ArgsValidationError(`Unknown option: ${rawName}`, {
+			code: ArgsValidationErrorKeys.unknownOption,
+			values: {
+				rawName,
+				name,
+				candidates
+			}
+		});
+	});
+}
+function mergeValidationErrors(error, additionalErrors) {
+	if (additionalErrors.length === 0) return error;
+	return new AggregateError(error ? [...error.errors, ...additionalErrors] : additionalErrors, error?.message || additionalErrors[0]?.message);
+}
 const isObject = (val) => val !== null && typeof val === "object";
 function createInitialSubCommands(options, entryCmd) {
 	const hasSubCommands = options.subCommands ? options.subCommands instanceof Map ? options.subCommands.size > 0 : isObject(options.subCommands) && Object.keys(options.subCommands).length > 0 : false;
@@ -1146,16 +1403,34 @@ function resolveCommandTree(tokens, entry, options) {
 		if (cmd == null) {
 			if (depth === 0) {
 				if (options.fallbackToEntry) return resolveAsEntry();
+				const parent = resolveAsEntry();
 				return {
 					commandName: token,
 					callMode: "unexpected",
 					commandPath: [],
 					depth: 0,
 					omitted: false,
-					levelSubCommands: void 0
+					levelSubCommands: void 0,
+					unresolvedCommandName: token,
+					parentCommand: parent.command,
+					parentCommandName: parent.commandName,
+					parentCommandPath: [],
+					parentSubCommands: options.subCommands
 				};
 			}
-			break;
+			return {
+				commandName: token,
+				callMode: "unexpected",
+				commandPath: [...commandPath],
+				depth,
+				omitted: false,
+				levelSubCommands: void 0,
+				unresolvedCommandName: token,
+				parentCommand: resolvedCommand,
+				parentCommandName: resolvedName,
+				parentCommandPath: [...commandPath],
+				parentSubCommands: currentSubCommands
+			};
 		}
 		let resolved = cmd;
 		if (typeof cmd === "function" && cmd.commandName == null) resolved = Object.assign((...args) => cmd(...args), cmd, { commandName: token });
@@ -1189,6 +1464,16 @@ function resolveCommandTree(tokens, entry, options) {
 		levelSubCommands
 	};
 }
+function createCommandNotFoundError(resolved) {
+	const commandName = resolved.unresolvedCommandName || resolved.commandName || "";
+	return new CommandNotFoundError(`Command not found: ${commandName}`, {
+		code: CommandNotFoundErrorKeys.notFound,
+		values: { commandName },
+		commandName,
+		candidates: [...resolved.parentSubCommands?.keys() || []],
+		commandPath: resolved.parentCommandPath || []
+	});
+}
 function resolveEntryName(entry) {
 	return isLazyCommand(entry) ? entry.commandName || "(anonymous)" : entry.name || "(anonymous)";
 }
@@ -1202,7 +1487,11 @@ function getPluginExtensions(plugins) {
 	return extensions;
 }
 async function executeCommand(cmd, ctx, decorators) {
-	const baseRunner = cmd.run || NOOP;
+	const commandRunner = cmd.run || NOOP;
+	const baseRunner = (ctx) => {
+		if (hasPriorityValidationError(ctx.validationError)) throw ctx.validationError;
+		return commandRunner(ctx);
+	};
 	const decoratedRunner = decorators.reduceRight((runner, decorator) => decorator(runner), baseRunner);
 	try {
 		if (ctx.env.onBeforeCommand) await ctx.env.onBeforeCommand(ctx);

package/package.json

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