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

package/README.md

@@ -115,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
 

package/lib/index.d.ts

@@ -581,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]; };
@@ -625,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

@@ -150,8 +150,13 @@ var en_US_default = {
 	NEGATABLE: "Negatable of",
 	DEFAULT: "default",
 	CHOICES: "choices",
+	CAUSEDBY: "Caused by",
 	help: "Display this help message",
 	version: "Display this version",
+	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}",
@@ -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.5",
+  "version": "1.0.0-rc.6",
   "author": {
     "name": "kazuya kawaguchi",
     "email": "kawakazu80@gmail.com"
@@ -53,13 +53,13 @@
     }
   },
   "dependencies": {
-    "@gunshi/plugin": "1.0.0-rc.5"
+    "@gunshi/plugin": "1.0.0-rc.6"
   },
   "peerDependencies": {
-    "@gunshi/plugin-i18n": "1.0.0-rc.5"
+    "@gunshi/plugin-i18n": "1.0.0-rc.6"
   },
   "devDependencies": {
-    "@gunshi/shared": "1.0.0-rc.5",
+    "@gunshi/shared": "1.0.0-rc.6",
     "publint": "^0.3.20",
     "tsdown": "0.22.14"
   },