@gunshi/bone 0.37.2 → 0.37.3

package/lib/index.d.ts

@@ -1,4 +1,4 @@
-//#region ../../node_modules/.pnpm/args-tokens@0.28.2/node_modules/args-tokens/lib/parser-DT7Ztcch.d.ts
+//#region ../../node_modules/.pnpm/args-tokens@0.29.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.28.2/node_modules/args-tokens/lib/resolver.d.ts
+//#region ../../node_modules/.pnpm/args-tokens@0.29.0/node_modules/args-tokens/lib/resolver.d.ts
 //#region src/resolver.d.ts
 /**
  * An argument schema definition for command-line argument parsing.
@@ -508,13 +508,6 @@ 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}.
  *
@@ -582,38 +575,6 @@ type IsRequiredPositionalArg<A extends ArgSchema> = A['type'] extends 'positiona
  * @typeParam A - {@link Args | Arguments}, which is an object that defines the command line arguments.
  */
 type ArgExplicitlyProvided<A extends Args> = { [K in keyof A]: boolean };
-/**
- * Resolve command line arguments.
- *
- * @typeParam A - {@link Args | Arguments}, which is an object that defines the command line arguments.
- *
- * @param args - An arguments that contains {@link ArgSchema | arguments schema}.
- * @param tokens - An array of {@link ArgToken | tokens}.
- * @param resolveArgs - An arguments that contains {@link ResolveArgs | resolve arguments}.
- * @returns An object that contains the values of the arguments, positional arguments, rest arguments, {@link AggregateError | validation errors}, and explicit provision status.
- *
- * @example
- * ```typescript
- * // passed tokens: --port 3000
- *
- * const { values, explicit } = resolveArgs({
- *   port: {
- *     type: 'number',
- *     default: 8080
- *   },
- *   host: {
- *     type: 'string',
- *     default: 'localhost'
- *   }
- * }, parsedTokens)
- *
- * values.port // 3000
- * values.host // 'localhost'
- *
- * explicit.port // true (explicitly provided)
- * explicit.host // false (not provided, fallback to default)
- * ```
- */
 //#endregion
 //#region ../gunshi/src/plugin/context.d.ts
 /**

package/lib/index.js

@@ -1,4 +1,4 @@
-//#region ../../node_modules/.pnpm/args-tokens@0.28.2/node_modules/args-tokens/lib/parser.js
+//#region ../../node_modules/.pnpm/args-tokens@0.29.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.28.2/node_modules/args-tokens/lib/utils.js
+//#region ../../node_modules/.pnpm/args-tokens@0.29.0/node_modules/args-tokens/lib/utils.js
 /**
 * Entry point of utils.
 *
@@ -234,7 +234,7 @@ function formatChoices(choices) {
 	return choices.map((value) => JSON.stringify(value)).join(", ");
 }
 //#endregion
-//#region ../../node_modules/.pnpm/args-tokens@0.28.2/node_modules/args-tokens/lib/resolver.js
+//#region ../../node_modules/.pnpm/args-tokens@0.29.0/node_modules/args-tokens/lib/resolver.js
 /**
 * Entry point of argument options resolver.
 *
@@ -259,11 +259,24 @@ const ArgsValidationErrorKeys = {
 	unknownOption: "err:arg:unknown-option"
 };
 /**
+* Brand that marks {@link ArgsValidationError} instances.
+*
+* The brand is looked up in the global symbol registry with `Symbol.for`, so it stays
+* identical across bundled copies of this module and across realms. It lets
+* {@link isArgsValidationError} recognize errors created by another copy of `args-tokens`,
+* where `instanceof` cannot match.
+*/
+const ARGS_VALIDATION_ERROR_BRAND = Symbol.for("args-tokens.ArgsValidationError");
+/**
 * 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.
+*
+* Each instance carries a non-enumerable brand keyed by
+* `Symbol.for('args-tokens.ArgsValidationError')`, which {@link isArgsValidationError}
+* uses to recognize instances created by another bundled copy of `args-tokens`.
 */
 var ArgsValidationError = class extends Error {
 	/**
@@ -287,16 +300,35 @@ var ArgsValidationError = class extends Error {
 		this.name = "ArgsValidationError";
 		this.code = options.code;
 		this.values = options.values ?? {};
+		Object.defineProperty(this, ARGS_VALIDATION_ERROR_BRAND, {
+			value: true,
+			enumerable: false,
+			writable: false,
+			configurable: false
+		});
 	}
 };
 /**
 * Check whether the given value is an {@link ArgsValidationError}.
 *
+* This guard also recognizes errors created by another bundled copy of `args-tokens`
+* (0.29.0 or later), where `instanceof` does not match. Such an error must have an own brand
+* keyed by `Symbol.for('args-tokens.ArgsValidationError')` set to `true`, and a `values` object.
+* The guard does not rely on `error.name`, so subclasses such as {@link ArgResolveError} that
+* override `name` are still recognized.
+*
+* The guard narrows to `ArgsValidationError` only. Across bundled copies,
+* `instanceof ArgResolveError` still does not match.
+*
 * @param error - value to check
 * @returns `true` when the value is an `ArgsValidationError`
 */
-function isArgsValidationError(error) {
-	return error instanceof ArgsValidationError;
+function isArgsValidationError$1(error) {
+	if (error instanceof ArgsValidationError) return true;
+	if (typeof error !== "object" || error === null) return false;
+	if (!Object.hasOwn(error, ARGS_VALIDATION_ERROR_BRAND) || error[ARGS_VALIDATION_ERROR_BRAND] !== true) return false;
+	const values = error.values;
+	return typeof values === "object" && values !== null;
 }
 const SKIP_POSITIONAL_DEFAULT = -1;
 /**
@@ -679,10 +711,8 @@ function createChoiceError(rawArg, option, schema, actual) {
 	});
 }
 function createCustomParseError(error, rawArg, option, schema, value) {
-	if (isArgsValidationError(error)) {
-		augmentValidationError(error, rawArg, option, schema, value);
-		return error;
-	}
+	const reused = reuseValidationError(error, rawArg, option, schema, value);
+	if (reused) return reused;
 	const reason = getErrorReason(error);
 	return new ArgsValidationError(reason, {
 		code: ArgsValidationErrorKeys.customParse,
@@ -694,6 +724,26 @@ function createCustomParseError(error, rawArg, option, schema, value) {
 		cause: error
 	});
 }
+/**
+* Reuse an {@link ArgsValidationError} thrown from a custom `parse` function, filling in missing values.
+*
+* @param error - The value thrown from `parse`
+* @param rawArg - The argument key in the schema
+* @param option - The option name used on the command line
+* @param schema - The argument schema
+* @param value - The raw input value
+* @returns The same error when it can be reused, otherwise `undefined` so the caller wraps it.
+* Inspecting or updating the thrown value can throw, for example when its `values` object is frozen
+* or an accessor throws; such values are not reused, so a custom `parse` cannot make `resolveArgs` throw this way.
+*/
+function reuseValidationError(error, rawArg, option, schema, value) {
+	try {
+		if (isArgsValidationError$1(error)) {
+			augmentValidationError(error, rawArg, option, schema, value);
+			return error;
+		}
+	} catch {}
+}
 function augmentValidationError(error, rawArg, option, schema, value) {
 	const values = error.values;
 	values.name ??= rawArg;
@@ -726,7 +776,7 @@ function checkConflicts(args, explicit, toKebab, actualInputNames) {
 	return [];
 }
 //#endregion
-//#region ../../node_modules/.pnpm/args-tokens@0.28.2/node_modules/args-tokens/lib/index.js
+//#region ../../node_modules/.pnpm/args-tokens@0.29.0/node_modules/args-tokens/lib/index.js
 /**
 * @author kazuya kawaguchi (a.k.a. kazupon)
 * @license MIT
@@ -1039,7 +1089,20 @@ function createDecorators() {
 */
 const CommandNotFoundErrorKeys = { notFound: "err:cmd:not-found" };
 /**
+* Brand that marks {@link CommandNotFoundError} instances.
+*
+* The brand is looked up in the global symbol registry with `Symbol.for`, so it stays
+* identical across bundled copies of gunshi (`gunshi`, `@gunshi/plugin`, `@gunshi/bone`)
+* and across realms. It lets {@link isCommandNotFoundError} recognize errors created by
+* another copy, where `instanceof` cannot match.
+*/
+const COMMAND_NOT_FOUND_ERROR_BRAND = Symbol.for("gunshi.CommandNotFoundError");
+/**
 * Error raised when a command cannot be resolved.
+*
+* Each instance carries a non-enumerable brand keyed by
+* `Symbol.for('gunshi.CommandNotFoundError')`, so that {@link isCommandNotFoundError}
+* recognizes it even when it was created by another bundled copy of gunshi.
 */
 var CommandNotFoundError = class extends Error {
 	code;
@@ -1061,16 +1124,77 @@ var CommandNotFoundError = class extends Error {
 		this.commandName = options.commandName;
 		this.candidates = options.candidates || [];
 		this.commandPath = options.commandPath || [];
+		Object.defineProperty(this, COMMAND_NOT_FOUND_ERROR_BRAND, {
+			value: true,
+			enumerable: false,
+			writable: false,
+			configurable: false
+		});
 	}
 };
 /**
 * Check whether an error is a {@link CommandNotFoundError}.
 *
+* `instanceof` alone is not enough: `@gunshi/plugin` is bundled with its own copy of this
+* class (`noExternal: ['gunshi/plugin']`), so an error thrown by `gunshi` is never an instance
+* of the class a plugin imports. Errors from another copy are recognized through the
+* `Symbol.for('gunshi.CommandNotFoundError')` brand, which does not depend on `error.name`.
+*
 * @param error - An unknown error
 * @returns `true` if the error is a {@link CommandNotFoundError}
 */
 function isCommandNotFoundError(error) {
-	return error instanceof CommandNotFoundError;
+	if (error instanceof CommandNotFoundError) return true;
+	if (!isRecord(error) || !hasCommandNotFoundErrorShape(error)) return false;
+	if (Object.hasOwn(error, COMMAND_NOT_FOUND_ERROR_BRAND) && error[COMMAND_NOT_FOUND_ERROR_BRAND] === true) return true;
+	return error instanceof Error && error.name === "CommandNotFoundError";
+}
+/**
+* Check whether an error is an {@link ArgsValidationError}.
+*
+* Prefer this over the `args-tokens` guard of the same name. Both recognize errors from another
+* bundled copy through the `Symbol.for('args-tokens.ArgsValidationError')` brand that
+* `args-tokens` 0.29.0 or later sets, including subclasses such as `ArgResolveError` that
+* override `name` with the argument name. This guard additionally:
+*
+* - recognizes direct `ArgsValidationError` instances from copies bundling `args-tokens`
+*   older than 0.29.0, which do not set the brand
+* - checks that `code` and `values` of an error from another copy have the expected types
+*
+* The guard narrows only to {@link ArgsValidationError}: across copies,
+* `instanceof ArgResolveError` still fails, so do not rely on `type` or `schema` for such errors.
+*
+* @param error - An unknown error
+* @returns `true` if the error is an {@link ArgsValidationError}
+*/
+function isArgsValidationError(error) {
+	if (error instanceof ArgsValidationError) return true;
+	if (!isRecord(error) || !hasArgsValidationErrorShape(error)) return false;
+	if (isArgsValidationError$1(error)) return true;
+	return error instanceof Error && error.name === "ArgsValidationError";
+}
+function isRecord(value) {
+	return typeof value === "object" && value !== null;
+}
+function isStringArray(value) {
+	return Array.isArray(value) && value.every((item) => typeof item === "string");
+}
+/**
+* Check whether `code` is an own or inherited property that is a string or `undefined`.
+*
+* Constructors always assign `code`, even when the option is omitted.
+*
+* @param error - An error from another copy
+* @returns `true` if `code` has the expected type
+*/
+function hasOptionalStringCode(error) {
+	return "code" in error && (error.code === void 0 || typeof error.code === "string");
+}
+function hasCommandNotFoundErrorShape(error) {
+	return hasOptionalStringCode(error) && isRecord(error.values) && typeof error.commandName === "string" && isStringArray(error.candidates) && isStringArray(error.commandPath);
+}
+function hasArgsValidationErrorShape(error) {
+	return hasOptionalStringCode(error) && isRecord(error.values);
 }
 /**
 * Check whether validation errors should be handled before version, help, or command execution.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@gunshi/bone",
   "description": "gunshi minimum",
-  "version": "0.37.2",
+  "version": "0.37.3",
   "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/plugin-global": "0.37.2",
-    "@gunshi/definition": "0.37.2",
-    "@gunshi/plugin-renderer": "0.37.2",
-    "gunshi": "0.37.2"
+    "@gunshi/definition": "0.37.3",
+    "@gunshi/plugin-global": "0.37.3",
+    "@gunshi/plugin-renderer": "0.37.3",
+    "gunshi": "0.37.3"
   },
   "scripts": {
     "build": "tsdown",