@gunshi/plugin-i18n 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]
 
 > internationalization (i18n) plugin for gunshi.
 
@@ -20,9 +19,6 @@ pnpm add @gunshi/plugin-i18n
 # yarn
 yarn add @gunshi/plugin-i18n
 
-# deno
-deno add jsr:@gunshi/plugin-i18n
-
 # bun
 bun add @gunshi/plugin-i18n
 ```
@@ -112,6 +108,7 @@ This means:
 - If you're using the globals plugin (which adds `--help` and `--version` options), the i18n plugin will automatically handle their translations
 - The translations for "Display this help message" and "Display this version" will be available in your configured locale
 - You can override these translations by providing your own `help` and `version` keys in your built-in resources
+- The description of `--json` of a command that spreads `jsonArgs` ("Output the result as JSON") is translated by the `json` key of the built-in resources in the same way, unless the resource of the command has its own `arg:json`
 
 Example with globals plugin:
 
@@ -761,6 +758,4 @@ See the [API References](./docs/index.md)
 
 [npm-version-src]: https://img.shields.io/npm/v/@gunshi/plugin-i18n?style=flat
 [npm-version-href]: https://npmjs.com/package/@gunshi/plugin-i18n@alpha
-[jsr-src]: https://jsr.io/badges/@gunshi/plugin-i18n
-[jsr-href]: https://jsr.io/@gunshi/plugin-i18n
 [install-size-src]: https://pkg-size.dev/badge/install/67599

package/lib/index.d.ts

@@ -1,6 +1,5 @@
-import { Args, Awaitable, Command, CommandContext, DefaultGunshiParams, ExtendContext, ExtractArgs, ExtractExtensions, GunshiParams, GunshiParamsConstraint, PluginWithExtension, Prettify } from "@gunshi/plugin";
-//#region ../../node_modules/.pnpm/args-tokens@1.0.0/node_modules/args-tokens/lib/resolver.d.ts
-//#region src/resolver.d.ts
+import { Args, Awaitable, Command, CommandContext, DefaultGunshiParams, ExtendContext, ExtractArgs, ExtractExtensions, GunshiParams, GunshiParamsConstraint, PluginWithExtension, Prettify, SubCommandable } from "@gunshi/plugin";
+//#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.
  *
@@ -362,9 +361,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
@@ -374,9 +373,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,
@@ -415,7 +413,7 @@ interface ArgSchema {
    *   }
    * }
    * // Usage: --summer --autumn reports an error
-   * // Error: "Optional argument '--summer' conflicts with '--autumn'"
+   * // Error: "'--summer' conflicts with '--autumn'"
    * ```
    *
    * @example
@@ -455,7 +453,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[];
@@ -625,11 +623,13 @@ 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_RESOURCE_KEYS: readonly ["json", "json:invalid-arguments", "json:next:help", "json:next:help-placeholder"];
+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]; };
@@ -669,14 +669,23 @@ 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];
+/**
+ * Resource keys of the description of the `json` argument of `jsonArgs`, and of the texts that only
+ * the JSON errors print.
+ */
+type JsonResourceKeys = (typeof JSON_RESOURCE_KEYS)[number];
 /**
  * Error resource keys.
  */
-type ErrorResourceKeys = ArgErrorResourceKeys | ArgErrorHintResourceKeys | CommandErrorResourceKeys | SuggestionErrorResourceKeys;
+type ErrorResourceKeys = ArgErrorResourceKeys | ArgErrorHintResourceKeys | CommandErrorResourceKeys | SuggestionErrorResourceKeys | JsonErrorResourceKeys;
 /**
  * Built-in resource keys.
  */
-type BuiltinResourceKeys = ErrorResourceKeys | CommandBuiltinArgsKeys | CommandBuiltinResourceKeys;
+type BuiltinResourceKeys = ErrorResourceKeys | CommandBuiltinArgsKeys | CommandBuiltinResourceKeys | JsonResourceKeys;
 /**
  * Built-in resource.
  */
@@ -918,7 +927,7 @@ type I18nCommandDefinitionResult<G extends GunshiParamsConstraint = DefaultGunsh
  *
  * @internal
  */
-type WithI18nResourceResult<G extends GunshiParamsConstraint = DefaultGunshiParams, C extends Command<G> = Command<G>> = Prettify<C & {
+type WithI18nResourceResult<G extends GunshiParamsConstraint = DefaultGunshiParams, C extends Command<G> | SubCommandable = Command<G>> = Prettify<C & {
   resource: CommandResourceFetcher<G>;
 } & { [K in Exclude<keyof I18nCommand<G>, keyof C | 'resource'>]?: I18nCommand<G>[K]; }>;
 /**
@@ -1067,7 +1076,7 @@ declare function defineI18nWithTypes<G extends GunshiParamsConstraint>(): Define
  * @param resource - A {@link CommandResourceFetcher | resource fetcher} for the command
  * @returns A {@link I18nCommand | command} with i18n resource support
  */
-declare function withI18nResource<G extends GunshiParamsConstraint, C extends Command<G>>(command: C, resource: CommandResourceFetcher<G>): WithI18nResourceResult<G, C>;
+declare function withI18nResource<G extends GunshiParamsConstraint, C extends Command<G> | SubCommandable>(command: C, resource: CommandResourceFetcher<G>): WithI18nResourceResult<G, C>;
 //#endregion
 //#region src/translation.d.ts
 /**

package/lib/index.js

@@ -3,6 +3,25 @@ import { plugin } from "@gunshi/plugin";
 * @author kazuya kawaguchi (a.k.a. kazupon)
 * @license MIT
 */
+//#endregion
+//#region ../gunshi/src/utils.ts
+/**
+* @author kazuya kawaguchi (a.k.a. kazupon)
+* @license MIT
+*/
+/**
+* Check whether an argument schema is the `json` argument of `jsonArgs`, by its mark.
+*
+* @param schema - An argument schema
+* @returns `true` if the schema has the mark of `jsonArgs`
+*/
+function isJsonArg(schema) {
+	return typeof schema === "object" && schema !== null && schema["~gunshi.json-arg"] === true;
+}
+/**
+* @author kazuya kawaguchi (a.k.a. kazupon)
+* @license MIT
+*/
 const ARG_PREFIX_AND_KEY_SEPARATOR = `arg:`;
 const ERROR_PREFIX_AND_KEY_SEPARATOR = `err:`;
 const COMMON_ARGS = {
@@ -31,16 +50,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}",
@@ -48,6 +72,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
@@ -139,6 +166,11 @@ function formatResource(resource, values = Object.create(null)) {
 		return values[name] == null ? "" : String(values[name]);
 	});
 }
+/**
+* @author kazuya kawaguchi (a.k.a. kazupon)
+* @license MIT
+*/
+namespacedId("i18n");
 //#endregion
 //#region ../shared/src/index.ts
 /**
@@ -449,6 +481,16 @@ function i18n(options = {}) {
 				if (originalResource) loaded = true;
 				const localeStr = toLocaleString(locale);
 				const resource = originalResource ? await normalizeResource(originalResource, ctx) : Object.create(null);
+				/**
+				* NOTE(kazupon): the `json` argument of `jsonArgs` is described by the built-in resources, as the
+				* global options are, unless the resource of the command describes it. A command without a
+				* translation of its own keeps the English description of `jsonArgs`.
+				*/
+				if (isJsonArg(ctx.args.json)) {
+					const jsonKey = resolveArgKey("json", ctx.name);
+					const description = builtinResources[localeStr]?.json;
+					if (resource[jsonKey] === void 0 && description) resource[jsonKey] = description;
+				}
 				for (const globalOption of getGlobalOptions()) if (globalOptionResources.has(globalOption)) {
 					const optionResource = globalOptionResources.get(globalOption);
 					const globalOptionKey = resolveArgKey(globalOption, ctx.name);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@gunshi/plugin-i18n",
   "description": "internationalization plugin for gunshi",
-  "version": "1.0.0-rc.4",
+  "version": "1.0.0-rc.6",
   "author": {
     "name": "kazuya kawaguchi",
     "email": "kawakazu80@gmail.com"
@@ -53,10 +53,10 @@
     }
   },
   "dependencies": {
-    "@gunshi/plugin": "1.0.0-rc.4"
+    "@gunshi/plugin": "1.0.0-rc.6"
   },
   "peerDependencies": {
-    "@gunshi/plugin-global": "1.0.0-rc.4"
+    "@gunshi/plugin-global": "1.0.0-rc.6"
   },
   "peerDependenciesMeta": {
     "@gunshi/plugin-global": {
@@ -64,24 +64,19 @@
     }
   },
   "devDependencies": {
-    "@gunshi/bone": "1.0.0-rc.4",
-    "@gunshi/plugin-global": "1.0.0-rc.4",
-    "@gunshi/plugin-renderer": "1.0.0-rc.4",
-    "@gunshi/resources": "1.0.0-rc.4",
-    "@gunshi/shared": "1.0.0-rc.4",
+    "@gunshi/bone": "1.0.0-rc.6",
+    "@gunshi/plugin-global": "1.0.0-rc.6",
+    "@gunshi/plugin-renderer": "1.0.0-rc.6",
+    "@gunshi/resources": "1.0.0-rc.6",
+    "@gunshi/shared": "1.0.0-rc.6",
     "@intlify/core-base": "12.0.0-alpha.7",
-    "deno": "^2.7.14",
-    "gunshi": "1.0.0-rc.4",
-    "jsr": "^0.14.3",
-    "jsr-exports-lint": "^0.4.2",
+    "gunshi": "1.0.0-rc.6",
     "messageformat": "4.1.0",
     "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"
   }
 }