feat: show option value on help usage (#107)

kazupon · web-flow · commit cc690cfeed3a · 2025-05-03T22:49:08.000+09:00
* feat: show option value on help usage

* refactor
diff --git a/src/__snapshots__/cli.test.ts.snap b/src/__snapshots__/cli.test.ts.snap
@@ -79,7 +79,7 @@ exports[`auto generate usage > loosely sub commands > command2 1`] = `
   COMMAND command2 <OPTIONS>
 
 OPTIONS:
-  -b, --bar [bar]          
+  -b, --bar [bar]           (default: 42)
   -h, --help               Display this help message
   -v, --version            Display this version
 "
@@ -109,7 +109,7 @@ USAGE:
   COMMAND command2 <OPTIONS>
 
 OPTIONS:
-  -b, --bar [bar]          
+  -b, --bar [bar]           (default: 42)
   -h, --help               Display this help message
   -v, --version            Display this version
 "
@@ -154,7 +154,7 @@ USAGE:
   gunshi command2 <OPTIONS>
 
 OPTIONS:
-  -b, --bar [bar]          The bar option
+  -b, --bar [bar]          The bar option (default: 42)
   -h, --help               Display this help message
   -v, --version            Display this version
 
@@ -225,7 +225,7 @@ USAGE:
   gunshi command2 <OPTIONS>
 
 OPTIONS:
-  -b, --bar [bar]          The bar option
+  -b, --bar [bar]          The bar option (default: 42)
   -h, --help               Display this help message
   -v, --version            Display this version
 
@@ -274,7 +274,7 @@ USAGE:
 OPTIONS:
   -f, --foo <foo>          this is foo option
   --bar                    this is bar option
-  -b, --baz [baz]          this is baz option
+  -b, --baz [baz]          this is baz option (default: 42)
   -h, --help               Display this help message
   -v, --version            Display this version
 "
diff --git a/src/__snapshots__/generator.test.ts.snap b/src/__snapshots__/generator.test.ts.snap
@@ -6,7 +6,7 @@ USAGE:
   generator <OPTIONS> 
 
 OPTIONS:
-  -c, --catalog             Display the catalog only
+  -c, --catalog             Display the catalog only (default: false)
   -d, --dependency          Display the catalogable dependencies only
   --no-dependency           Negatable of -d, --dependency
   -h, --help                Display this help message
@@ -26,7 +26,7 @@ USAGE:
   generator show <OPTIONS>
 
 OPTIONS:
-  -c, --catalog             Display the catalog only
+  -c, --catalog             Display the catalog only (default: false)
   -d, --dependency          Display the catalogable dependencies only
   --no-dependency           Negatable of -d, --dependency
   -h, --help                Display this help message
diff --git a/src/__snapshots__/renderer.test.ts.snap b/src/__snapshots__/renderer.test.ts.snap
@@ -9,7 +9,7 @@ USAGE:
 OPTIONS:
   -f, --foo <foo>          The foo option
   --bar                    The bar option
-  -b, --baz [baz]          The baz option
+  -b, --baz [baz]          The baz option (default: 42)
   -q, --qux <qux>          The qux option
 
 EXAMPLES:
@@ -29,7 +29,7 @@ USAGE:
 OPTIONS:
     -f, --foo <foo>            [string]  The foo option
     --bar                      [boolean] The bar option
-    -b, --baz [baz]            [number]  The baz option
+    -b, --baz [baz]            [number]  The baz option (default: 42)
     -q, --qux <qux>            [string]  The qux option
 
 EXAMPLES:
@@ -49,7 +49,7 @@ USAGE:
 OPTIONS:
   -f, --foo <foo>          The foo option
   --bar                    The bar option
-  -b, --baz [baz]          The baz option
+  -b, --baz [baz]          The baz option (default: 42)
   -q, --qux <qux>          The qux option
 "
 `;
@@ -77,7 +77,7 @@ USAGE:
 OPTIONS:
   -f, --foo <foo>          The foo option
   --bar                    The bar option
-  -b, --baz [baz]          The baz option
+  -b, --baz [baz]          The baz option (default: 42)
 "
 `;
 
@@ -99,8 +99,9 @@ For more info, run any command with the \`--help\` flag:
 OPTIONS:
   -f, --foo <foo>          The foo option
   --bar                    The bar option
-  -b, --baz [baz]          The baz option
+  -b, --baz [baz]          The baz option (default: 42)
   -q, --qux <qux>          The qux option
+  -l, --log [log]          The log option (default: info, choices: debug | info | warn | error)
 
 EXAMPLES:
   # Example 1
diff --git a/src/constants.ts b/src/constants.ts
@@ -55,6 +55,7 @@ export const COMMAND_OPTIONS_DEFAULT: CommandOptions<ArgOptions> = {
   leftMargin: 2,
   middleMargin: 10,
   usageOptionType: false,
+  usageOptionValue: true,
   renderHeader: undefined,
   renderUsage: undefined,
   renderValidationErrors: undefined,
@@ -69,5 +70,7 @@ export const COMMAND_BUILTIN_RESOURCE_KEYS = [
   'OPTIONS',
   'EXAMPLES',
   'FORMORE',
-  'NEGATABLE'
+  'NEGATABLE',
+  'DEFAULT',
+  'CHOICES'
 ] as const
diff --git a/src/locales/en-US.json b/src/locales/en-US.json
@@ -7,6 +7,8 @@
   "EXAMPLES": "EXAMPLES",
   "FORMORE": "For more info, run any command with the `--help` flag:",
   "NEGATABLE": "Negatable of",
+  "DEFAULT": "default",
+  "CHOICES": "choices",
   "help": "Display this help message",
   "version": "Display this version"
 }
diff --git a/src/locales/ja-JP.json b/src/locales/ja-JP.json
@@ -7,6 +7,8 @@
   "EXAMPLES": "例",
   "FORMORE": "詳細は、コマンドと`--help`フラグを実行してください:",
   "NEGATABLE": "否定可能な",
+  "DEFAULT": "デフォルト",
+  "CHOICES": "選択肢",
   "help": "このヘルプメッセージを表示",
   "version": "このバージョンを表示"
 }
diff --git a/src/renderer.test.ts b/src/renderer.test.ts
@@ -33,6 +33,13 @@ const SHOW = {
       short: 'q',
       required: true,
       description: 'The qux option'
+    },
+    log: {
+      type: 'enum',
+      short: 'l',
+      description: 'The log option',
+      choices: ['debug', 'info', 'warn', 'error'],
+      default: 'info'
     }
   },
   name: 'show',
diff --git a/src/renderer/usage.ts b/src/renderer/usage.ts
@@ -3,11 +3,14 @@
  * @license MIT
  */
 
+import { COMMON_OPTIONS } from '../constants.ts'
 import { create, resolveBuiltInKey, resolveOptionKey } from '../utils.ts'
 
 import type { ArgOptions, ArgOptionSchema } from 'args-tokens'
 import type { Command, CommandContext } from '../types.ts'
 
+const COMMON_OPTIONS_KEYS = Object.keys(COMMON_OPTIONS)
+
 /**
  * Render the usage.
  * @param ctx A {@link CommandContext | command context}
@@ -243,7 +246,7 @@ function getOptionsPairs<Options extends ArgOptions>(
       key = value.default ? `${key} [${name}]` : `${key} <${name}>`
     }
     acc[name] = key
-    if (value.type === 'boolean' && value.negatable && !(name === 'help' || name === 'version')) {
+    if (value.type === 'boolean' && value.negatable && !COMMON_OPTIONS_KEYS.includes(name)) {
       acc[`no-${name}`] = `--no-${name}`
     }
     return acc
@@ -259,6 +262,40 @@ function resolveNegatableType<Options extends ArgOptions>(
   return ctx.options[key.startsWith('no-') ? resolveNegatableKey(key) : key].type
 }
 
+function generateDefaultDisplayValue<Options extends ArgOptions>(
+  ctx: Readonly<CommandContext<Options>>,
+  schema: ArgOptionSchema
+): string {
+  return `${ctx.translate(resolveBuiltInKey('DEFAULT'))}: ${schema.default}`
+}
+
+function resolveDisplayValue<Options extends ArgOptions>(
+  ctx: Readonly<CommandContext<Options>>,
+  key: string
+): string {
+  if (COMMON_OPTIONS_KEYS.includes(key)) {
+    return ''
+  }
+
+  const schema = ctx.options[key]
+  if (
+    (schema.type === 'boolean' || schema.type === 'number' || schema.type === 'string') &&
+    schema.default !== undefined
+  ) {
+    return `(${generateDefaultDisplayValue(ctx, schema)})`
+  }
+  if (schema.type === 'enum') {
+    const _default =
+      schema.default !== undefined // eslint-disable-line unicorn/no-negated-condition
+        ? generateDefaultDisplayValue(ctx, schema)
+        : ''
+    const choices = `${ctx.translate(resolveBuiltInKey('CHOICES'))}: ${schema.choices!.join(' | ')}`
+    return `(${_default ? `${_default}, ${choices}` : choices})`
+  }
+
+  return ''
+}
+
 /**
  * Generate options usage
  * @param ctx A {@link CommandContext | command context}
@@ -289,9 +326,10 @@ async function generateOptionsUsage<Options extends ArgOptions>(
         rawDesc = `${ctx.translate(resolveBuiltInKey('NEGATABLE'))} ${optionKey}`
       }
       const optionsSchema = ctx.env.usageOptionType ? `[${resolveNegatableType(key, ctx)}] ` : ''
+      const valueDesc = key.startsWith('no-') ? '' : resolveDisplayValue(ctx, key)
       // padEnd is used to align the `[]` symbols
       const desc = `${optionsSchema ? optionsSchema.padEnd(optionSchemaMaxLength + 3) : ''}${rawDesc}`
-      const option = `${value.padEnd(optionsMaxLength + ctx.env.middleMargin)}${desc}`
+      const option = `${value.padEnd(optionsMaxLength + ctx.env.middleMargin)}${desc}${valueDesc ? ` ${valueDesc}` : ''}`
       return `${option.padStart(ctx.env.leftMargin + option.length)}`
     })
   )
diff --git a/src/types.ts b/src/types.ts
@@ -111,10 +111,16 @@ export interface CommandEnvironment<Options extends ArgOptions = ArgOptions> {
    * @see {@link CommandOptions.usageOptionType}
    */
   usageOptionType: boolean
+  /**
+   * Whether to display the option value.
+   * @default true
+   * @see {@link CommandOptions.usageOptionValue}
+   */
+  usageOptionValue: boolean
   /**
    * Whether to display the command usage.
    * @default false
-   * @see {@link}
+   * @see {@link CommandOptions.usageSilent}
    */
   usageSilent: boolean
   /**
@@ -180,6 +186,10 @@ export interface CommandOptions<Options extends ArgOptions = ArgOptions> {
    * Whether to display the usage option type.
    */
   usageOptionType?: boolean
+  /**
+   * Whether to display the option value.
+   */
+  usageOptionValue?: boolean
   /**
    * Whether to display the command usage.
    */

Original file line number	Diff line number	Diff line change
`@@ -7,6 +7,8 @@`
`7`	`7`	`"EXAMPLES": "EXAMPLES",`
`8`	`8`	"FORMORE": "For more info, run any command with the `--help` flag:",
`9`	`9`	`"NEGATABLE": "Negatable of",`
	`10`	`+ "DEFAULT": "default",`
	`11`	`+ "CHOICES": "choices",`
`10`	`12`	`"help": "Display this help message",`
`11`	`13`	`"version": "Display this version"`
`12`	`14`	`}`
Original file line number	Diff line number	Diff line change
`@@ -7,6 +7,8 @@`
`7`	`7`	`"EXAMPLES": "例",`
`8`	`8`	"FORMORE": "詳細は、コマンドと`--help`フラグを実行してください:",
`9`	`9`	`"NEGATABLE": "否定可能な",`
	`10`	`+ "DEFAULT": "デフォルト",`
	`11`	`+ "CHOICES": "選択肢",`
`10`	`12`	`"help": "このヘルプメッセージを表示",`
`11`	`13`	`"version": "このバージョンを表示"`
`12`	`14`	`}`