@gunshi/plugin 0.37.1 → 0.37.3

package/lib/index.d.ts

@@ -1,4 +1,4 @@
-//#region ../../node_modules/.pnpm/args-tokens@0.28.1/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.1/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.
@@ -515,12 +515,12 @@ interface ArgSchema {
  * 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";
+  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.
@@ -535,6 +535,10 @@ type ArgsValidationErrorCode = (typeof ArgsValidationErrorKeys)[keyof typeof Arg
  * 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`.
  */
 declare class ArgsValidationError extends Error {
   /**
@@ -559,13 +563,6 @@ declare class ArgsValidationError extends Error {
     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}.
  *
@@ -599,7 +596,7 @@ type ResolveOptionValue<A extends ArgSchema, T> = A['multiple'] extends true ? T
  *
  * @internal
  */
-type ResolveArgValues<A extends Args, V extends Record<keyof A, unknown>> = { -readonly [Arg in keyof A]?: V[Arg] } & FilterArgs<A, V, 'default'> & FilterArgs<A, V, 'required'> & FilterPositionalArgs<A, V> extends infer P ? { [K in keyof P]: P[K] } : never;
+type ResolveArgValues<A extends Args, V extends Record<keyof A, unknown>> = { -readonly [Arg in keyof A]?: V[Arg] } & FilterArgs<A, V, 'default'> & FilterArgs<A, V, 'required'> & FilterPositionalArgs<A, V> extends (infer P) ? { [K in keyof P]: P[K] } : never;
 /**
  * Filters the arguments based on their default values.
  *
@@ -633,38 +630,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
 /**
@@ -1830,10 +1795,6 @@ declare function createCommandContext<G extends GunshiParamsConstraint = Default
 }: 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.
  */
@@ -1875,6 +1836,10 @@ type CommandNotFoundErrorOptions = {
 };
 /**
  * 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.
  */
 declare class CommandNotFoundError extends Error {
   readonly code?: CommandNotFoundErrorCode;
@@ -1893,10 +1858,34 @@ declare class CommandNotFoundError extends Error {
 /**
  * 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}
  */
 declare function isCommandNotFoundError(error: unknown): error is 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}
+ */
+declare function isArgsValidationError(error: unknown): error is ArgsValidationError;
 /**
  * Check whether validation errors should be handled before version, help, or command execution.
  *

package/lib/index.js

@@ -173,7 +173,7 @@ function getCommandName(cmd) {
 "-".codePointAt(0);
 "=".codePointAt(0);
 //#endregion
-//#region ../../node_modules/.pnpm/args-tokens@0.28.1/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.
 *
@@ -198,11 +198,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 {
 	/**
@@ -226,19 +239,38 @@ 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;
 }
 //#endregion
-//#region ../../node_modules/.pnpm/args-tokens@0.28.1/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
@@ -258,7 +290,20 @@ function isArgsValidationError(error) {
 */
 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;
@@ -280,16 +325,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/plugin",
   "description": "plugin development kit for gunshi",
-  "version": "0.37.1",
+  "version": "0.37.3",
   "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.37.1"
+    "gunshi": "0.37.3"
   },
   "scripts": {
     "build": "tsdown",