@gunshi/plugin-renderer 1.0.0-rc.4 → 1.0.0-rc.6

package/README.md

@@ -2,7 +2,6 @@
 
 [![Version][npm-version-src]][npm-version-href]
 [![InstallSize][install-size-src]][install-size-src]
-[![JSR][jsr-src]][jsr-href]
 
 > usage renderer plugin for gunshi.
 
@@ -20,9 +19,6 @@ pnpm add @gunshi/plugin-renderer
 # yarn
 yarn add @gunshi/plugin-renderer
 
-# deno
-deno add jsr:@gunshi/plugin-renderer
-
 # bun
 bun add @gunshi/plugin-renderer
 ```
@@ -119,7 +115,7 @@ EXAMPLES:
 
 - **`renderHeader(ctx: CommandContext): Promise<string>`**: Renders the command header section
 - **`renderUsage(ctx: CommandContext): Promise<string>`**: Renders the complete usage/help information
-- **`renderValidationErrors(ctx: CommandContext, error: AggregateError): Promise<string>`**: Renders validation errors
+- **`renderValidationErrors(ctx: CommandContext, error: AggregateError): Promise<string>`**: Renders validation errors. With `--json`, the global options plugin prints the validation errors as one line of JSON, and does not call the renderer of the validation errors
 
 ## 🧩 Context Extensions
 
@@ -270,6 +266,4 @@ See the [API References](./docs/index.md)
 
 [npm-version-src]: https://img.shields.io/npm/v/@gunshi/plugin-renderer?style=flat
 [npm-version-href]: https://npmjs.com/package/@gunshi/plugin-renderer@alpha
-[jsr-src]: https://jsr.io/badges/@gunshi/plugin-renderer
-[jsr-href]: https://jsr.io/@gunshi/plugin-renderer
 [install-size-src]: https://pkg-size.dev/badge/install/101075

package/lib/index.d.ts

@@ -1,7 +1,6 @@
 import { Args, Command, CommandContext, DefaultGunshiParams, GunshiParams, PluginWithExtension } from "@gunshi/plugin";
 import "@gunshi/plugin-i18n";
-//#region ../../node_modules/.pnpm/args-tokens@1.0.0/node_modules/args-tokens/lib/resolver.d.ts
-//#region src/resolver.d.ts
+//#region ../../node_modules/.pnpm/args-tokens@1.0.2/node_modules/args-tokens/lib/resolver.d.ts
 /**
  * An argument schema definition for command-line argument parsing.
  *
@@ -363,9 +362,9 @@ interface ArgSchema {
    */
   toKebab?: true;
   /**
-   * Names of other options that conflict with this option.
+   * Names of other arguments that conflict with this argument.
    *
-   * When this option is used together with any of the conflicting options, the error is an
+   * When this argument is used together with any of the conflicting arguments, the error is an
    * `ArgResolveError` with type 'conflict' and the code `err:arg:conflict`
    * ({@link ArgsValidationErrorKeys}.conflict). Its `values` has the `displayName` and `name` of
    * the argument whose `conflicts` names the other one, and the `conflictDisplayName` and
@@ -375,9 +374,8 @@ interface ArgSchema {
    *
    * A positional argument can be on either side, such as `[file]` and `--stdin`. It conflicts when
    * it is given, and it is shown by its name, such as `'file'` (in kebab-case with `toKebab`), as
-   * in its other errors. The message starts with the kind of the argument given as `name`:
-   * `Positional argument 'file' conflicts with '--stdin'` or
-   * `Optional argument '--stdin' conflicts with 'file'`.
+   * in its other errors. The message names the argument given as `name` first:
+   * `'file' conflicts with '--stdin'` or `'--stdin' conflicts with 'file'`.
    *
    * Conflicts only need to be defined on one side - if option A defines a conflict
    * with option B, the conflict is automatically detected when both are used,
@@ -416,7 +414,7 @@ interface ArgSchema {
    *   }
    * }
    * // Usage: --summer --autumn reports an error
-   * // Error: "Optional argument '--summer' conflicts with '--autumn'"
+   * // Error: "'--summer' conflicts with '--autumn'"
    * ```
    *
    * @example
@@ -456,7 +454,7 @@ interface ArgSchema {
    *     toKebab: true  // Accessible as --autumn-season
    *   }
    * }
-   * // Error: "Optional argument '--summer-season' conflicts with '--autumn-season'"
+   * // Error: "'--summer-season' conflicts with '--autumn-season'"
    * ```
    */
   conflicts?: string | string[];
@@ -583,11 +581,12 @@ 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 COMMAND_BUILTIN_RESOURCE_KEYS: readonly ["USAGE", "COMMAND", "SUBCOMMAND", "COMMANDS", "ARGUMENTS", "OPTIONS", "EXAMPLES", "FORMORE", "NEGATABLE", "DEFAULT", "CHOICES", "CAUSEDBY"];
 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", "err:arg:unexpected-value", "err:arg:missing-value", "err:arg:conflict", "err:arg:invalid-default"];
 declare const ARG_ERROR_HINT_RESOURCE_KEYS: readonly ["err:arg:missing-value:hint"];
 declare const COMMAND_ERROR_RESOURCE_KEYS: readonly ["err:cmd:not-found", "err:cmd:ambiguous", "err:cmd:inconsistent-options", "err:cmd:lazy-schema-mismatch"];
 declare const SUGGESTION_ERROR_RESOURCE_KEYS: readonly ["err:suggestion:did-you-mean"];
+declare const JSON_ERROR_RESOURCE_KEYS: readonly ["err:json:not-supported", "err:json:invalid-result", "err:json:unserializable-result"];
 //#endregion
 //#region ../shared/src/types.d.ts
 type RemoveIndexSignature<T> = { [K in keyof T as string extends K ? never : number extends K ? never : K]: T[K]; };
@@ -627,10 +626,14 @@ type CommandErrorResourceKeys = (typeof COMMAND_ERROR_RESOURCE_KEYS)[number];
  * Suggestion error resource keys.
  */
 type SuggestionErrorResourceKeys = (typeof SUGGESTION_ERROR_RESOURCE_KEYS)[number];
+/**
+ * Resource keys of the errors of the JSON output.
+ */
+type JsonErrorResourceKeys = (typeof JSON_ERROR_RESOURCE_KEYS)[number];
 /**
  * Error resource keys.
  */
-type ErrorResourceKeys = ArgErrorResourceKeys | ArgErrorHintResourceKeys | CommandErrorResourceKeys | SuggestionErrorResourceKeys;
+type ErrorResourceKeys = ArgErrorResourceKeys | ArgErrorHintResourceKeys | CommandErrorResourceKeys | SuggestionErrorResourceKeys | JsonErrorResourceKeys;
 /**
  * Command built-in keys.
  */

package/lib/index.js

@@ -1,5 +1,5 @@
 import { ANONYMOUS_COMMAND_NAME, ArgsValidationErrorKeys, createCommandContext, isArgsValidationError, isCommandNotFoundError, isCommandResolutionError, plugin } from "@gunshi/plugin";
-//#region ../../node_modules/.pnpm/args-tokens@1.0.0/node_modules/args-tokens/lib/utils.js
+//#region ../../node_modules/.pnpm/args-tokens@1.0.2/node_modules/args-tokens/lib/utils.js
 /**
 * Entry point of utils.
 *
@@ -150,16 +150,21 @@ var en_US_default = {
 	NEGATABLE: "Negatable of",
 	DEFAULT: "default",
 	CHOICES: "choices",
+	CAUSEDBY: "Caused by",
 	help: "Display this help message",
 	version: "Display this version",
-	"err:arg:required-option": "Optional argument {$displayName} is required",
+	json: "Output the result as JSON",
+	"json:invalid-arguments": "{$count} arguments are invalid",
+	"json:next:help": "See the arguments of the command",
+	"json:next:help-placeholder": "Replace <COMMAND> with how you ran this CLI, to see the arguments of the command",
+	"err:arg:required-option": "Option {$displayName} is required",
 	"err:arg:required-positional": "Positional argument {$displayName} 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:arg:unexpected-value": "Optional argument {$displayName} does not take a value",
-	"err:arg:missing-value": "Optional argument {$displayName} requires a value",
+	"err:arg:unexpected-value": "Option {$displayName} does not take a value",
+	"err:arg:missing-value": "Option {$displayName} requires a value",
 	"err:arg:missing-value:hint": "(to pass '{$next}' as its value, write '{$suggestion}')",
 	"err:arg:conflict": "{$displayName} conflicts with {$conflictDisplayName}",
 	"err:arg:invalid-default": "Invalid default for {$displayName}: {$actual} is not one of {$choices}",
@@ -167,6 +172,9 @@ var en_US_default = {
 	"err:cmd:ambiguous": "The command is ambiguous. Move options after the command name: {$candidatePaths}",
 	"err:cmd:inconsistent-options": "The options do not identify a consistent command. Move options after the command name.",
 	"err:cmd:lazy-schema-mismatch": "The lazy command definition does not match its loaded options. Declare leading options in the lazy definition or move options after the command name: {$commandPath}",
+	"err:json:not-supported": "This command does not support --json",
+	"err:json:invalid-result": "The command finished, but did not return an object to output as JSON. A plugin that decorates the command may have dropped its result",
+	"err:json:unserializable-result": "The command finished, but its result cannot be converted to JSON: {$message}",
 	"err:suggestion:did-you-mean": "Did you mean {$name}?"
 };
 //#endregion
@@ -344,6 +352,84 @@ function formatResource(resource, values = Object.create(null)) {
 	});
 }
 //#endregion
+//#region ../shared/src/validation.ts
+/**
+* @author kazuya kawaguchi (a.k.a. kazupon)
+* @license MIT
+*/
+const i18nPluginId$1 = namespacedId("i18n");
+const missingValueHintKey = "err:arg:missing-value:hint";
+/**
+* Localize the message of a validation error, as gunshi shows it to the user: with the i18n plugin when
+* it is installed, and otherwise the message of the error.
+*
+* NOTE(kazupon): the renderer plugin renders the validation errors for people, and the global options
+* plugin prints them as JSON with `--json`. Both take the messages from here, so that a message is the
+* same in both.
+*
+* @param ctx - A {@link CommandContext | command context}
+* @param error - A validation error: an {@link ArgsValidationError}, a command-not-found error, or a
+* command-resolution error
+* @returns The localized message
+*/
+async function localizeValidationError(ctx, error) {
+	if (isCommandNotFoundError(error) && error.code) {
+		const message = await localize(ctx, error.code, error.values);
+		if (message && message !== error.code) return message;
+	}
+	if (isCommandResolutionError(error) && error.code) {
+		const message = await localize(ctx, error.code, error.values);
+		if (message && message !== error.code) return message;
+	}
+	if (isArgsValidationError(error) && error.code) {
+		const values = await resolveValidationValues(ctx, error);
+		const message = await localize(ctx, error.code, values);
+		if (message && message !== error.code) {
+			const hint = await localizeHint(ctx, error, values);
+			return hint ? `${message} ${hint}` : message;
+		}
+	}
+	return error.message;
+}
+/**
+* Localize the hint that args-tokens adds to the message of an error.
+*
+* A translation replaces the whole message, hint included, so the hint is translated by a key of
+* its own and follows the translated error. args-tokens gives one today: for an option given without
+* a value, when the argument after it may be the value, the long form with `=` (`--port=-5` for
+* `--port -5`), in `values.next` and `values.suggestion`.
+*
+* @param ctx - A {@link CommandContext | command context}
+* @param error - An args validation error
+* @param values - The values of the error, as given to its translation
+* @returns The localized hint, or `undefined` when the error has none.
+*/
+async function localizeHint(ctx, error, values) {
+	if (error.code !== ArgsValidationErrorKeys.missingValue || typeof values.next !== "string" || typeof values.suggestion !== "string") return;
+	const hint = await localize(ctx, missingValueHintKey, values);
+	return hint && hint !== missingValueHintKey ? hint : void 0;
+}
+async function resolveValidationValues(ctx, error) {
+	if (error.code !== ArgsValidationErrorKeys.customParse) return error.values;
+	const { reasonKey, reasonValues } = error.values;
+	if (typeof reasonKey !== "string") return error.values;
+	const key = resolveKey(reasonKey, ctx.name);
+	const localizedReason = await localize(ctx, key, toRecord(reasonValues));
+	if (!localizedReason || localizedReason === key) return error.values;
+	return {
+		...error.values,
+		reason: localizedReason
+	};
+}
+async function localize(ctx, key, values) {
+	const i18n = ctx.extensions?.[i18nPluginId$1];
+	if (i18n?.translate) return i18n.translate(key, values);
+	return key;
+}
+function toRecord(value) {
+	return value != null && typeof value === "object" ? value : Object.create(null);
+}
+//#endregion
 //#region ../shared/src/index.ts
 /**
 * @author kazuya kawaguchi (a.k.a. kazupon)
@@ -795,8 +881,6 @@ function isRequiredSinglePositionalArg(arg) {
 * @author kazuya kawaguchi (a.k.a. kazupon)
 * @license MIT
 */
-const i18nPluginId$1 = namespacedId("i18n");
-const missingValueHintKey = "err:arg:missing-value:hint";
 /**
 * Render the validation errors.
 *
@@ -806,66 +890,9 @@ const missingValueHintKey = "err:arg:missing-value:hint";
 */
 async function renderValidationErrors(ctx, error) {
 	const messages = [];
-	for (const err of error.errors) messages.push(await renderValidationError(ctx, err));
+	for (const err of error.errors) messages.push(await localizeValidationError(ctx, err));
 	return messages.join("\n");
 }
-async function renderValidationError(ctx, error) {
-	if (isCommandNotFoundError(error) && error.code) {
-		const message = await localize(ctx, error.code, error.values);
-		if (message && message !== error.code) return message;
-	}
-	if (isCommandResolutionError(error) && error.code) {
-		const message = await localize(ctx, error.code, error.values);
-		if (message && message !== error.code) return message;
-	}
-	if (isArgsValidationError(error) && error.code) {
-		const values = await resolveValidationValues(ctx, error);
-		const message = await localize(ctx, error.code, values);
-		if (message && message !== error.code) {
-			const hint = await localizeHint(ctx, error, values);
-			return hint ? `${message} ${hint}` : message;
-		}
-	}
-	return error.message;
-}
-/**
-* Localize the hint that args-tokens adds to the message of an error.
-*
-* A translation replaces the whole message, hint included, so the hint is translated by a key of
-* its own and follows the translated error. args-tokens gives one today: for an option given without
-* a value, when the argument after it may be the value, the long form with `=` (`--port=-5` for
-* `--port -5`), in `values.next` and `values.suggestion`.
-*
-* @param ctx - A {@link CommandContext | command context}
-* @param error - An args validation error
-* @param values - The values of the error, as given to its translation
-* @returns The localized hint, or `undefined` when the error has none.
-*/
-async function localizeHint(ctx, error, values) {
-	if (error.code !== ArgsValidationErrorKeys.missingValue || typeof values.next !== "string" || typeof values.suggestion !== "string") return;
-	const hint = await localize(ctx, missingValueHintKey, values);
-	return hint && hint !== missingValueHintKey ? hint : void 0;
-}
-async function resolveValidationValues(ctx, error) {
-	if (error.code !== ArgsValidationErrorKeys.customParse) return error.values;
-	const { reasonKey, reasonValues } = error.values;
-	if (typeof reasonKey !== "string") return error.values;
-	const key = resolveKey(reasonKey, ctx.name);
-	const localizedReason = await localize(ctx, key, toRecord(reasonValues));
-	if (!localizedReason || localizedReason === key) return error.values;
-	return {
-		...error.values,
-		reason: localizedReason
-	};
-}
-async function localize(ctx, key, values) {
-	const i18n = ctx.extensions?.[i18nPluginId$1];
-	if (i18n?.translate) return i18n.translate(key, values);
-	return key;
-}
-function toRecord(value) {
-	return value != null && typeof value === "object" ? value : Object.create(null);
-}
 //#endregion
 //#region src/index.ts
 /**

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@gunshi/plugin-renderer",
   "description": "usage renderer plugin for gunshi",
-  "version": "1.0.0-rc.4",
+  "version": "1.0.0-rc.6",
   "author": {
     "name": "kazuya kawaguchi",
     "email": "kawakazu80@gmail.com"
@@ -53,23 +53,18 @@
     }
   },
   "dependencies": {
-    "@gunshi/plugin": "1.0.0-rc.4"
+    "@gunshi/plugin": "1.0.0-rc.6"
   },
   "peerDependencies": {
-    "@gunshi/plugin-i18n": "1.0.0-rc.4"
+    "@gunshi/plugin-i18n": "1.0.0-rc.6"
   },
   "devDependencies": {
-    "@gunshi/shared": "1.0.0-rc.4",
-    "deno": "^2.7.14",
-    "jsr": "^0.14.3",
-    "jsr-exports-lint": "^0.4.2",
+    "@gunshi/shared": "1.0.0-rc.6",
     "publint": "^0.3.20",
     "tsdown": "0.22.14"
   },
   "scripts": {
     "build": "tsdown",
-    "build:docs": "tsx ../../scripts/api-references.ts",
-    "lint:jsr": "jsr publish --dry-run --allow-dirty",
-    "typecheck:deno": "deno check --import-map=../../importmap.json ./src"
+    "build:docs": "tsx ../../scripts/api-references.ts"
   }
 }