@optique/core 1.0.0-dev.431 → 1.0.0-dev.434

package/dist/facade.d.cts

@@ -1,4 +1,5 @@
 import { Message } from "./message.cjs";
+import { HiddenVisibility, OptionName } from "./usage.cjs";
 import { DocSection, ShowChoicesOptions, ShowDefaultOptions } from "./doc.cjs";
 import { InferMode, InferValue, Mode, ModeValue, Parser } from "./parser.cjs";
 import { ShellCompletion } from "./completion.cjs";
@@ -8,101 +9,55 @@ import { Program } from "./program.cjs";
 //#region src/facade.d.ts
 
 /**
- * Naming style for shell completion command and option aliases.
+ * Sub-configuration for a meta command's command form.
  *
- * @since 0.10.0
- */
-type CompletionName = "singular" | "plural" | "both";
-/**
- * Visibility policy for completion entries in help and usage output.
- *
- * @since 0.10.0
+ * @since 1.0.0
  */
-type CompletionHelpVisibility = CompletionName | "none";
-type CompletionConfigBase<THelp> = {
+interface CommandSubConfig {
   /**
-   * Determines how completion is made available:
-   *
-   * - `"command"`: Only the `completion` subcommand is available
-   * - `"both"`: Both `completion` subcommand and `--completion` option
-   *   are available
-   *
-   * @default `"both"`
+   * Command names.  The first element is the display name shown in help
+   * output; additional elements are hidden aliases that are accepted but
+   * not shown.
    */
-  readonly mode?: "command" | "both";
+  readonly names?: readonly [string, ...string[]];
   /**
-   * Group label for the completion command in help output. When specified,
-   * the completion command appears under a titled section with this name
-   * instead of alongside user-defined commands.
-   *
-   * @since 0.10.0
+   * Group label for the command in help output.  When specified, the command
+   * appears under a titled section with this name instead of alongside
+   * user-defined commands.
    */
   readonly group?: string;
   /**
-   * Available shell completions. By default, includes `bash`, `fish`, `nu`,
-   * `pwsh`, and `zsh`. You can provide additional custom shell completions
-   * or override the defaults.
+   * Granular visibility control.
    *
-   * @default `{ bash, fish, nu, pwsh, zsh }`
+   * - `true`: Hidden from usage, documentation, and suggestions.
+   * - `"usage"`: Hidden from usage lines only.
+   * - `"doc"`: Hidden from documentation only.
    */
-  readonly shells?: Record<string, ShellCompletion>;
-  /**
-   * Callback function invoked when completion is requested. The function
-   * can optionally receive an exit code parameter.
-   *
-   * You usually want to pass `process.exit` on Node.js or Bun and
-   * `Deno.exit` on Deno to this option.
-   *
-   * @default Returns `void` when completion is shown.
-   */
-  readonly onShow?: (() => THelp) | ((exitCode: number) => THelp);
-} | {
+  readonly hidden?: HiddenVisibility;
+}
+/**
+ * Sub-configuration for a meta command's option form.
+ *
+ * @since 1.0.0
+ */
+interface OptionSubConfig {
   /**
-   * Determines how completion is made available:
-   *
-   * - `"option"`: Only the `--completion` option is available
+   * Option names (all shown in help, e.g., `"-h"`, `"--help"`).
    */
-  readonly mode: "option";
-  /** @since 0.10.0 */
-  readonly group?: never;
-  /** @default `{ bash, fish, nu, pwsh, zsh }` */
-  readonly shells?: Record<string, ShellCompletion>;
-  /** @default Returns `void` when completion is shown. */
-  readonly onShow?: (() => THelp) | ((exitCode: number) => THelp);
-};
-type CompletionConfigBoth<THelp> = CompletionConfigBase<THelp> & {
+  readonly names?: readonly [OptionName, ...OptionName[]];
   /**
-   * Determines whether to use singular or plural naming for completion command/option.
-   *
-   * - `"singular"`: Use `completion` / `--completion`
-   * - `"plural"`: Use `completions` / `--completions`
-   * - `"both"`: Use both singular and plural forms
-   *
-   * @default `"both"`
+   * Group label for the option in help output.
    */
-  readonly name?: "both";
+  readonly group?: string;
   /**
-   * Controls which completion entries appear in help and usage output.
-   *
-   * - `"both"`: Show both singular and plural entries
-   * - `"singular"`: Show only singular entries
-   * - `"plural"`: Show only plural entries
-   * - `"none"`: Hide completion entries from help and usage
+   * Granular visibility control.
    *
-   * @default Matches `name`
-   * @since 0.10.0
+   * - `true`: Hidden from usage, documentation, and suggestions.
+   * - `"usage"`: Hidden from usage lines only.
+   * - `"doc"`: Hidden from documentation only.
    */
-  readonly helpVisibility?: CompletionHelpVisibility;
-};
-type CompletionConfigSingular<THelp> = CompletionConfigBase<THelp> & {
-  readonly name: "singular";
-  readonly helpVisibility?: "singular" | "none";
-};
-type CompletionConfigPlural<THelp> = CompletionConfigBase<THelp> & {
-  readonly name: "plural";
-  readonly helpVisibility?: "plural" | "none";
-};
-type CompletionConfig<THelp> = CompletionConfigBoth<THelp> | CompletionConfigSingular<THelp> | CompletionConfigPlural<THelp>;
+  readonly hidden?: HiddenVisibility;
+}
 /**
  * Configuration options for the {@link run} function.
  *
@@ -163,125 +118,62 @@ interface RunOptions<THelp, TError> {
    */
   readonly sectionOrder?: (a: DocSection, b: DocSection) => number;
   /**
-   * Help configuration. When provided, enables help functionality.
+   * Help configuration.  When provided, enables help functionality.
+   * At least one of `command` or `option` must be specified.
+   *
+   * @since 1.0.0
    */
   readonly help?: {
-    /**
-     * Determines how help is made available:
-     *
-     * - `"command"`: Only the `help` subcommand is available
-     * - `"both"`: Both `help` subcommand and `--help` option are available
-     *
-     * @default `"option"`
-     */
-    readonly mode: "command" | "both";
-    /**
-     * Group label for the help command in help output. When specified,
-     * the help command appears under a titled section with this name
-     * instead of alongside user-defined commands.
-     *
-     * @since 0.10.0
-     */
-    readonly group?: string;
-    /**
-     * Callback function invoked when help is requested. The function can
-     * optionally receive an exit code parameter.
-     *
-     * You usually want to pass `process.exit` on Node.js or Bun and
-     * `Deno.exit` on Deno to this option.
-     *
-     * @default Returns `void` when help is shown.
-     */
+    /** Callback invoked when help is requested. */
     readonly onShow?: (() => THelp) | ((exitCode: number) => THelp);
+  } & ({
+    readonly command: true | CommandSubConfig;
+    readonly option?: true | OptionSubConfig;
   } | {
-    /**
-     * Determines how help is made available:
-     *
-     * - `"option"`: Only the `--help` option is available
-     *
-     * @default `"option"`
-     */
-    readonly mode?: "option";
-    /** @since 0.10.0 */
-    readonly group?: never;
-    /**
-     * Callback function invoked when help is requested. The function can
-     * optionally receive an exit code parameter.
-     *
-     * You usually want to pass `process.exit` on Node.js or Bun and
-     * `Deno.exit` on Deno to this option.
-     *
-     * @default Returns `void` when help is shown.
-     */
-    readonly onShow?: (() => THelp) | ((exitCode: number) => THelp);
-  };
+    readonly option: true | OptionSubConfig;
+    readonly command?: true | CommandSubConfig;
+  });
   /**
-   * Version configuration. When provided, enables version functionality.
+   * Version configuration.  When provided, enables version functionality.
+   * At least one of `command` or `option` must be specified.
+   *
+   * @since 1.0.0
    */
   readonly version?: {
-    /**
-     * Determines how version is made available:
-     *
-     * - `"command"`: Only the `version` subcommand is available
-     * - `"both"`: Both `version` subcommand and `--version` option are
-     *   available
-     *
-     * @default `"option"`
-     */
-    readonly mode: "command" | "both";
-    /**
-     * The version string to display when version is requested.
-     */
+    /** The version string to display when version is requested. */
     readonly value: string;
-    /**
-     * Group label for the version command in help output. When specified,
-     * the version command appears under a titled section with this name
-     * instead of alongside user-defined commands.
-     *
-     * @since 0.10.0
-     */
-    readonly group?: string;
-    /**
-     * Callback function invoked when version is requested. The function can
-     * optionally receive an exit code parameter.
-     *
-     * You usually want to pass `process.exit` on Node.js or Bun and
-     * `Deno.exit` on Deno to this option.
-     *
-     * @default Returns `void` when version is shown.
-     */
+    /** Callback invoked when version is requested. */
     readonly onShow?: (() => THelp) | ((exitCode: number) => THelp);
+  } & ({
+    readonly command: true | CommandSubConfig;
+    readonly option?: true | OptionSubConfig;
   } | {
+    readonly option: true | OptionSubConfig;
+    readonly command?: true | CommandSubConfig;
+  });
+  /**
+   * Completion configuration.  When provided, enables shell completion.
+   * At least one of `command` or `option` must be specified.
+   *
+   * @since 1.0.0
+   */
+  readonly completion?: {
     /**
-     * Determines how version is made available:
-     *
-     * - `"option"`: Only the `--version` option is available
-     *
-     * @default `"option"`
-     */
-    readonly mode?: "option";
-    /**
-     * The version string to display when version is requested.
-     */
-    readonly value: string;
-    /** @since 0.10.0 */
-    readonly group?: never;
-    /**
-     * Callback function invoked when version is requested. The function can
-     * optionally receive an exit code parameter.
+     * Available shell completions.  By default, includes `bash`, `fish`,
+     * `nu`, `pwsh`, and `zsh`.
      *
-     * You usually want to pass `process.exit` on Node.js or Bun and
-     * `Deno.exit` on Deno to this option.
-     *
-     * @default Returns `void` when version is shown.
+     * @default `{ bash, fish, nu, pwsh, zsh }`
      */
+    readonly shells?: Record<string, ShellCompletion>;
+    /** Callback invoked when completion is requested. */
     readonly onShow?: (() => THelp) | ((exitCode: number) => THelp);
-  };
-  /**
-   * Completion configuration. When provided, enables shell completion functionality.
-   * @since 0.6.0
-   */
-  readonly completion?: CompletionConfig<THelp>;
+  } & ({
+    readonly command: true | CommandSubConfig;
+    readonly option?: true | OptionSubConfig;
+  } | {
+    readonly option: true | OptionSubConfig;
+    readonly command?: true | CommandSubConfig;
+  });
   /**
    * What to display above error messages:
    * - `"usage"`: Show usage information
@@ -559,4 +451,4 @@ declare function runWithSync<TParser extends Parser<"sync", unknown, unknown>, T
  */
 declare function runWithAsync<TParser extends Parser<Mode, unknown, unknown>, TContexts extends readonly SourceContext<unknown>[], THelp = void, TError = never>(parser: TParser, programName: string, contexts: TContexts, options: RunWithOptions<THelp, TError> & ExtractRequiredOptions<TContexts, InferValue<TParser>>): Promise<InferValue<TParser>>;
 //#endregion
-export { CompletionHelpVisibility, CompletionName, ExtractRequiredOptions, type ParserValuePlaceholder, RunOptions, RunParserError, RunWithOptions, type SourceContext, SubstituteParserValue, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync };
+export { CommandSubConfig, ExtractRequiredOptions, OptionSubConfig, type ParserValuePlaceholder, RunOptions, RunParserError, RunWithOptions, type SourceContext, SubstituteParserValue, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync };

package/dist/facade.d.ts

@@ -1,4 +1,5 @@
 import { Message } from "./message.js";
+import { HiddenVisibility, OptionName } from "./usage.js";
 import { DocSection, ShowChoicesOptions, ShowDefaultOptions } from "./doc.js";
 import { InferMode, InferValue, Mode, ModeValue, Parser } from "./parser.js";
 import { ShellCompletion } from "./completion.js";
@@ -8,101 +9,55 @@ import { Program } from "./program.js";
 //#region src/facade.d.ts
 
 /**
- * Naming style for shell completion command and option aliases.
+ * Sub-configuration for a meta command's command form.
  *
- * @since 0.10.0
- */
-type CompletionName = "singular" | "plural" | "both";
-/**
- * Visibility policy for completion entries in help and usage output.
- *
- * @since 0.10.0
+ * @since 1.0.0
  */
-type CompletionHelpVisibility = CompletionName | "none";
-type CompletionConfigBase<THelp> = {
+interface CommandSubConfig {
   /**
-   * Determines how completion is made available:
-   *
-   * - `"command"`: Only the `completion` subcommand is available
-   * - `"both"`: Both `completion` subcommand and `--completion` option
-   *   are available
-   *
-   * @default `"both"`
+   * Command names.  The first element is the display name shown in help
+   * output; additional elements are hidden aliases that are accepted but
+   * not shown.
    */
-  readonly mode?: "command" | "both";
+  readonly names?: readonly [string, ...string[]];
   /**
-   * Group label for the completion command in help output. When specified,
-   * the completion command appears under a titled section with this name
-   * instead of alongside user-defined commands.
-   *
-   * @since 0.10.0
+   * Group label for the command in help output.  When specified, the command
+   * appears under a titled section with this name instead of alongside
+   * user-defined commands.
    */
   readonly group?: string;
   /**
-   * Available shell completions. By default, includes `bash`, `fish`, `nu`,
-   * `pwsh`, and `zsh`. You can provide additional custom shell completions
-   * or override the defaults.
+   * Granular visibility control.
    *
-   * @default `{ bash, fish, nu, pwsh, zsh }`
+   * - `true`: Hidden from usage, documentation, and suggestions.
+   * - `"usage"`: Hidden from usage lines only.
+   * - `"doc"`: Hidden from documentation only.
    */
-  readonly shells?: Record<string, ShellCompletion>;
-  /**
-   * Callback function invoked when completion is requested. The function
-   * can optionally receive an exit code parameter.
-   *
-   * You usually want to pass `process.exit` on Node.js or Bun and
-   * `Deno.exit` on Deno to this option.
-   *
-   * @default Returns `void` when completion is shown.
-   */
-  readonly onShow?: (() => THelp) | ((exitCode: number) => THelp);
-} | {
+  readonly hidden?: HiddenVisibility;
+}
+/**
+ * Sub-configuration for a meta command's option form.
+ *
+ * @since 1.0.0
+ */
+interface OptionSubConfig {
   /**
-   * Determines how completion is made available:
-   *
-   * - `"option"`: Only the `--completion` option is available
+   * Option names (all shown in help, e.g., `"-h"`, `"--help"`).
    */
-  readonly mode: "option";
-  /** @since 0.10.0 */
-  readonly group?: never;
-  /** @default `{ bash, fish, nu, pwsh, zsh }` */
-  readonly shells?: Record<string, ShellCompletion>;
-  /** @default Returns `void` when completion is shown. */
-  readonly onShow?: (() => THelp) | ((exitCode: number) => THelp);
-};
-type CompletionConfigBoth<THelp> = CompletionConfigBase<THelp> & {
+  readonly names?: readonly [OptionName, ...OptionName[]];
   /**
-   * Determines whether to use singular or plural naming for completion command/option.
-   *
-   * - `"singular"`: Use `completion` / `--completion`
-   * - `"plural"`: Use `completions` / `--completions`
-   * - `"both"`: Use both singular and plural forms
-   *
-   * @default `"both"`
+   * Group label for the option in help output.
    */
-  readonly name?: "both";
+  readonly group?: string;
   /**
-   * Controls which completion entries appear in help and usage output.
-   *
-   * - `"both"`: Show both singular and plural entries
-   * - `"singular"`: Show only singular entries
-   * - `"plural"`: Show only plural entries
-   * - `"none"`: Hide completion entries from help and usage
+   * Granular visibility control.
    *
-   * @default Matches `name`
-   * @since 0.10.0
+   * - `true`: Hidden from usage, documentation, and suggestions.
+   * - `"usage"`: Hidden from usage lines only.
+   * - `"doc"`: Hidden from documentation only.
    */
-  readonly helpVisibility?: CompletionHelpVisibility;
-};
-type CompletionConfigSingular<THelp> = CompletionConfigBase<THelp> & {
-  readonly name: "singular";
-  readonly helpVisibility?: "singular" | "none";
-};
-type CompletionConfigPlural<THelp> = CompletionConfigBase<THelp> & {
-  readonly name: "plural";
-  readonly helpVisibility?: "plural" | "none";
-};
-type CompletionConfig<THelp> = CompletionConfigBoth<THelp> | CompletionConfigSingular<THelp> | CompletionConfigPlural<THelp>;
+  readonly hidden?: HiddenVisibility;
+}
 /**
  * Configuration options for the {@link run} function.
  *
@@ -163,125 +118,62 @@ interface RunOptions<THelp, TError> {
    */
   readonly sectionOrder?: (a: DocSection, b: DocSection) => number;
   /**
-   * Help configuration. When provided, enables help functionality.
+   * Help configuration.  When provided, enables help functionality.
+   * At least one of `command` or `option` must be specified.
+   *
+   * @since 1.0.0
    */
   readonly help?: {
-    /**
-     * Determines how help is made available:
-     *
-     * - `"command"`: Only the `help` subcommand is available
-     * - `"both"`: Both `help` subcommand and `--help` option are available
-     *
-     * @default `"option"`
-     */
-    readonly mode: "command" | "both";
-    /**
-     * Group label for the help command in help output. When specified,
-     * the help command appears under a titled section with this name
-     * instead of alongside user-defined commands.
-     *
-     * @since 0.10.0
-     */
-    readonly group?: string;
-    /**
-     * Callback function invoked when help is requested. The function can
-     * optionally receive an exit code parameter.
-     *
-     * You usually want to pass `process.exit` on Node.js or Bun and
-     * `Deno.exit` on Deno to this option.
-     *
-     * @default Returns `void` when help is shown.
-     */
+    /** Callback invoked when help is requested. */
     readonly onShow?: (() => THelp) | ((exitCode: number) => THelp);
+  } & ({
+    readonly command: true | CommandSubConfig;
+    readonly option?: true | OptionSubConfig;
   } | {
-    /**
-     * Determines how help is made available:
-     *
-     * - `"option"`: Only the `--help` option is available
-     *
-     * @default `"option"`
-     */
-    readonly mode?: "option";
-    /** @since 0.10.0 */
-    readonly group?: never;
-    /**
-     * Callback function invoked when help is requested. The function can
-     * optionally receive an exit code parameter.
-     *
-     * You usually want to pass `process.exit` on Node.js or Bun and
-     * `Deno.exit` on Deno to this option.
-     *
-     * @default Returns `void` when help is shown.
-     */
-    readonly onShow?: (() => THelp) | ((exitCode: number) => THelp);
-  };
+    readonly option: true | OptionSubConfig;
+    readonly command?: true | CommandSubConfig;
+  });
   /**
-   * Version configuration. When provided, enables version functionality.
+   * Version configuration.  When provided, enables version functionality.
+   * At least one of `command` or `option` must be specified.
+   *
+   * @since 1.0.0
    */
   readonly version?: {
-    /**
-     * Determines how version is made available:
-     *
-     * - `"command"`: Only the `version` subcommand is available
-     * - `"both"`: Both `version` subcommand and `--version` option are
-     *   available
-     *
-     * @default `"option"`
-     */
-    readonly mode: "command" | "both";
-    /**
-     * The version string to display when version is requested.
-     */
+    /** The version string to display when version is requested. */
     readonly value: string;
-    /**
-     * Group label for the version command in help output. When specified,
-     * the version command appears under a titled section with this name
-     * instead of alongside user-defined commands.
-     *
-     * @since 0.10.0
-     */
-    readonly group?: string;
-    /**
-     * Callback function invoked when version is requested. The function can
-     * optionally receive an exit code parameter.
-     *
-     * You usually want to pass `process.exit` on Node.js or Bun and
-     * `Deno.exit` on Deno to this option.
-     *
-     * @default Returns `void` when version is shown.
-     */
+    /** Callback invoked when version is requested. */
     readonly onShow?: (() => THelp) | ((exitCode: number) => THelp);
+  } & ({
+    readonly command: true | CommandSubConfig;
+    readonly option?: true | OptionSubConfig;
   } | {
+    readonly option: true | OptionSubConfig;
+    readonly command?: true | CommandSubConfig;
+  });
+  /**
+   * Completion configuration.  When provided, enables shell completion.
+   * At least one of `command` or `option` must be specified.
+   *
+   * @since 1.0.0
+   */
+  readonly completion?: {
     /**
-     * Determines how version is made available:
-     *
-     * - `"option"`: Only the `--version` option is available
-     *
-     * @default `"option"`
-     */
-    readonly mode?: "option";
-    /**
-     * The version string to display when version is requested.
-     */
-    readonly value: string;
-    /** @since 0.10.0 */
-    readonly group?: never;
-    /**
-     * Callback function invoked when version is requested. The function can
-     * optionally receive an exit code parameter.
+     * Available shell completions.  By default, includes `bash`, `fish`,
+     * `nu`, `pwsh`, and `zsh`.
      *
-     * You usually want to pass `process.exit` on Node.js or Bun and
-     * `Deno.exit` on Deno to this option.
-     *
-     * @default Returns `void` when version is shown.
+     * @default `{ bash, fish, nu, pwsh, zsh }`
      */
+    readonly shells?: Record<string, ShellCompletion>;
+    /** Callback invoked when completion is requested. */
     readonly onShow?: (() => THelp) | ((exitCode: number) => THelp);
-  };
-  /**
-   * Completion configuration. When provided, enables shell completion functionality.
-   * @since 0.6.0
-   */
-  readonly completion?: CompletionConfig<THelp>;
+  } & ({
+    readonly command: true | CommandSubConfig;
+    readonly option?: true | OptionSubConfig;
+  } | {
+    readonly option: true | OptionSubConfig;
+    readonly command?: true | CommandSubConfig;
+  });
   /**
    * What to display above error messages:
    * - `"usage"`: Show usage information
@@ -559,4 +451,4 @@ declare function runWithSync<TParser extends Parser<"sync", unknown, unknown>, T
  */
 declare function runWithAsync<TParser extends Parser<Mode, unknown, unknown>, TContexts extends readonly SourceContext<unknown>[], THelp = void, TError = never>(parser: TParser, programName: string, contexts: TContexts, options: RunWithOptions<THelp, TError> & ExtractRequiredOptions<TContexts, InferValue<TParser>>): Promise<InferValue<TParser>>;
 //#endregion
-export { CompletionHelpVisibility, CompletionName, ExtractRequiredOptions, type ParserValuePlaceholder, RunOptions, RunParserError, RunWithOptions, type SourceContext, SubstituteParserValue, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync };
+export { CommandSubConfig, ExtractRequiredOptions, OptionSubConfig, type ParserValuePlaceholder, RunOptions, RunParserError, RunWithOptions, type SourceContext, SubstituteParserValue, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync };