@optique/core 0.10.7 → 1.0.0-dev.1116

package/dist/facade.d.cts

@@ -1,5 +1,6 @@
 import { Message } from "./message.cjs";
-import { ShowChoicesOptions, ShowDefaultOptions } from "./doc.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";
 import { ParserValuePlaceholder, SourceContext } from "./context.cjs";
@@ -8,101 +9,57 @@ 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.
+   * - `"help"`: Hidden from usage and documentation only.
    */
-  readonly shells?: Record<string, ShellCompletion>;
+  readonly hidden?: HiddenVisibility;
+}
+/**
+ * Sub-configuration for a meta command's option form.
+ *
+ * @since 1.0.0
+ */
+interface OptionSubConfig {
   /**
-   * 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.
+   * Option names (all shown in help, e.g., `"-h"`, `"--help"`).
    */
-  readonly onShow?: (() => THelp) | ((exitCode: number) => THelp);
-} | {
+  readonly names?: readonly [OptionName, ...OptionName[]];
   /**
-   * Determines how completion is made available:
-   *
-   * - `"option"`: Only the `--completion` option is available
+   * Group label for the option in help output.
    */
-  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 group?: string;
   /**
-   * Determines whether to use singular or plural naming for completion command/option.
+   * Granular visibility control.
    *
-   * - `"singular"`: Use `completion` / `--completion`
-   * - `"plural"`: Use `completions` / `--completions`
-   * - `"both"`: Use both singular and plural forms
-   *
-   * @default `"both"`
+   * - `true`: Hidden from usage, documentation, and suggestions.
+   * - `"usage"`: Hidden from usage lines only.
+   * - `"doc"`: Hidden from documentation only.
+   * - `"help"`: Hidden from usage and documentation only.
    */
-  readonly name?: "both";
-  /**
-   * 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
-   *
-   * @default Matches `name`
-   * @since 0.10.0
-   */
-  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.
  *
@@ -149,125 +106,76 @@ interface RunOptions<THelp, TError> {
    */
   readonly showChoices?: boolean | ShowChoicesOptions;
   /**
-   * Help configuration. When provided, enables help functionality.
+   * A custom comparator function to control the order of sections in the
+   * help output.  When provided, it is used instead of the default smart
+   * sort (command-only sections first, then mixed, then option/argument-only
+   * sections).  Sections that compare equal (return `0`) preserve their
+   * original relative order.
+   *
+   * @param a The first section to compare.
+   * @param b The second section to compare.
+   * @returns A negative number if `a` should appear before `b`, a positive
+   *   number if `a` should appear after `b`, or `0` if they are equal.
+   * @since 1.0.0
+   */
+  readonly sectionOrder?: (a: DocSection, b: DocSection) => number;
+  /**
+   * 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
@@ -444,7 +352,7 @@ type UnionToIntersection<U> = (U extends unknown ? (k: U) => void : never) exten
  * @template TValue The parser value type for placeholder substitution.
  * @since 0.10.0
  */
-type ExtractRequiredOptions<TContexts extends readonly SourceContext<unknown>[], TValue> = UnionToIntersection<TContexts[number] extends SourceContext<infer O> ? O extends void ? unknown : SubstituteParserValue<O, TValue> : unknown>;
+type ExtractRequiredOptions<TContexts extends readonly SourceContext<unknown>[], TValue> = [TContexts[number] extends SourceContext<infer O> ? O extends void ? never : SubstituteParserValue<O, TValue> : never] extends [never] ? unknown : UnionToIntersection<TContexts[number] extends SourceContext<infer O> ? O extends void ? never : SubstituteParserValue<O, TValue> : never>;
 /**
  * Options for runWith functions.
  * Extends RunOptions with additional context-related settings.
@@ -459,7 +367,32 @@ interface RunWithOptions<THelp, TError> extends RunOptions<THelp, TError> {
    * `process.argv.slice(2)` on Node.js/Bun or `Deno.args` on Deno.
    */
   readonly args?: readonly string[];
+  /**
+   * Options to forward to source contexts.  When contexts declare
+   * required options (via `$requiredOptions`), pass them here to
+   * avoid name collisions with runner-level options such as `args`,
+   * `help`, or `colors`.
+   *
+   * @since 1.0.0
+   */
+  readonly contextOptions?: Record<string, unknown>;
 }
+/**
+ * When contexts require options, demands a `contextOptions` property
+ * typed to those requirements.  When no context needs options
+ * (`void`, `unknown`, or `{}`), resolves to `unknown` (intersection no-op).
+ * When all context option keys are optional, `contextOptions` itself becomes
+ * optional so callers are not forced to pass an empty wrapper.
+ *
+ * @template TContexts The tuple/array type of source contexts.
+ * @template TValue The parser value type for placeholder substitution.
+ * @since 1.0.0
+ */
+type ContextOptionsParam<TContexts extends readonly SourceContext<unknown>[], TValue> = keyof ExtractRequiredOptions<TContexts, TValue> extends never ? unknown : Record<string, never> extends ExtractRequiredOptions<TContexts, TValue> ? {
+  readonly contextOptions?: ExtractRequiredOptions<TContexts, TValue>;
+} : {
+  readonly contextOptions: ExtractRequiredOptions<TContexts, TValue>;
+};
 /**
  * Runs a parser with multiple source contexts.
  *
@@ -508,7 +441,7 @@ interface RunWithOptions<THelp, TError> extends RunOptions<THelp, TError> {
  * );
  * ```
  */
-declare function runWith<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>>;
+declare function runWith<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> & ContextOptionsParam<TContexts, InferValue<TParser>>): Promise<InferValue<TParser>>;
 /**
  * Runs a synchronous parser with multiple source contexts.
  *
@@ -523,10 +456,11 @@ declare function runWith<TParser extends Parser<Mode, unknown, unknown>, TContex
  * @param contexts Source contexts to use (priority: earlier overrides later).
  * @param options Run options including args, help, version, etc.
  * @returns The parsed result.
- * @throws Error if any context returns a Promise.
+ * @throws Error if any context returns a Promise or if a context's
+ * `[Symbol.asyncDispose]` returns a Promise.
  * @since 0.10.0
  */
-declare function runWithSync<TParser extends Parser<"sync", 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>>): InferValue<TParser>;
+declare function runWithSync<TParser extends Parser<"sync", unknown, unknown>, TContexts extends readonly SourceContext<unknown>[], THelp = void, TError = never>(parser: TParser, programName: string, contexts: TContexts, options: RunWithOptions<THelp, TError> & ContextOptionsParam<TContexts, InferValue<TParser>>): InferValue<TParser>;
 /**
  * Runs any parser asynchronously with multiple source contexts.
  *
@@ -543,6 +477,6 @@ declare function runWithSync<TParser extends Parser<"sync", unknown, unknown>, T
  * @returns Promise that resolves to the parsed result.
  * @since 0.10.0
  */
-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>>;
+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> & ContextOptionsParam<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, ContextOptionsParam, ExtractRequiredOptions, OptionSubConfig, type ParserValuePlaceholder, RunOptions, RunParserError, RunWithOptions, type SourceContext, SubstituteParserValue, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync };