@optique/core 1.0.0-dev.908 → 1.0.0

package/dist/facade.d.cts

@@ -1,9 +1,9 @@
 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 { InferMode, InferValue, Mode, ModeValue, Parser } from "./internal/parser.cjs";
 import { ShellCompletion } from "./completion.cjs";
-import { ParserValuePlaceholder, SourceContext } from "./context.cjs";
+import { ParserValuePlaceholder, SourceContext, SourceContextRequest } from "./context.cjs";
 import { Program } from "./program.cjs";
 
 //#region src/facade.d.ts
@@ -272,6 +272,13 @@ interface RunOptions<THelp, TError> {
  * @param options Configuration options for output formatting and callbacks.
  * @returns The parsed result value, or the return value of `onHelp`/`onError`
  *          callbacks.
+ * @throws {TypeError} If `programName` (or `program.metadata.name`) is not
+ *          a string, is empty, is whitespace-only, or contains control
+ *          characters.  Also thrown if `options.version.value` is not a
+ *          non-empty string without ASCII control characters, or if any
+ *          meta command/option name is empty, whitespace-only, contains
+ *          whitespace or control characters, or (for option names) lacks a
+ *          valid prefix (`--`, `-`, `/`, or `+`).
  * @throws {RunParserError} When parsing fails and no `onError` callback is
  *          provided.
  * @since 0.10.0 Added support for {@link Program} objects.
@@ -296,6 +303,8 @@ declare function runParser<TParser extends Parser<Mode, unknown, unknown>, THelp
  * @param args The command-line arguments to parse.
  * @param options Configuration options for customizing behavior.
  * @returns The parsed result if successful.
+ * @throws {TypeError} If an async parser is passed at runtime.  Use
+ * {@link runParser} or {@link runParserAsync} for async parsers.
  * @since 0.9.0
  */
 declare function runParserSync<TParser extends Parser<"sync", unknown, unknown>, THelp = void, TError = never>(parser: TParser, programName: string, args: readonly string[], options?: RunOptions<THelp, TError>): InferValue<TParser>;
@@ -367,24 +376,58 @@ 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.
  *
- * This function automatically handles static and dynamic contexts with proper
- * priority. Earlier contexts in the array override later ones.
+ * This function automatically handles single-pass and two-pass contexts with
+ * proper priority. Earlier contexts in the array override later ones.
  *
  * The function uses a smart two-phase approach:
  *
- * 1. *Phase 1*: Collect annotations from all contexts (static contexts return
- *    their data, dynamic contexts may return empty).
- * 2. *First parse*: Parse with Phase 1 annotations.
- * 3. *Phase 2*: Call `getAnnotations(parsed)` on all contexts with the first
- *    parse result.
- * 4. *Second parse*: Parse again with merged annotations from both phases.
+ * 1. *Phase 1*: Collect annotations from all contexts.
+ * 2. *First parse*: Parse with Phase 1 annotations. If that pass finishes
+ *    successfully, its value becomes the phase-two input. If the parser
+ *    reaches a usable intermediate state but still does not complete
+ *    successfully, the runner extracts a best-effort seed from that state
+ *    instead.
+ * 3. *Phase 2*: Call `getAnnotations({ phase: "phase2", parsed })` on all
+ *    two-pass contexts with the first pass value. Deferred or otherwise
+ *    unresolved fields in `parsed` may be `undefined`. Each two-pass
+ *    context's phase-two return
+ *    value replaces its own phase-one contribution for the final parse, so
+ *    returning `{}` clears any annotations that context provided during
+ *    phase 1. Single-pass contexts reuse their phase-one snapshot.
+ * 4. *Second parse*: Parse again with the merged phase-two annotations.
  *
- * If all contexts are static (no dynamic contexts), the second parse is skipped
- * for optimization.
+ * If all contexts are single-pass, the second parse is skipped for
+ * optimization. Phase 2 is also skipped when the first pass does not yield
+ * any usable seed at all.
  *
  * @template TParser The parser type.
  * @template THelp Return type when help is shown.
@@ -394,6 +437,13 @@ interface RunWithOptions<THelp, TError> extends RunOptions<THelp, TError> {
  * @param contexts Source contexts to use (priority: earlier overrides later).
  * @param options Run options including args, help, version, etc.
  * @returns Promise that resolves to the parsed result.
+ * @throws {TypeError} If two or more contexts share the same
+ * {@link SourceContext.id}.
+ * @throws {TypeError} If any context omits `phase` or declares an invalid
+ * phase value.
+ * @throws {SuppressedError} If the runner throws and a context's disposal
+ * also throws.  The original error is available via `.suppressed` and the
+ * disposal error via `.error`.
  * @since 0.10.0
  *
  * @example
@@ -403,6 +453,7 @@ interface RunWithOptions<THelp, TError> extends RunOptions<THelp, TError> {
  *
  * const envContext: SourceContext = {
  *   id: Symbol.for("@myapp/env"),
+ *   phase: "single-pass",
  *   getAnnotations() {
  *     return { [Symbol.for("@myapp/env")]: process.env };
  *   }
@@ -416,12 +467,16 @@ 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.
  *
  * This is the sync-only variant of {@link runWith}. All contexts must return
- * annotations synchronously (not Promises).
+ * annotations synchronously (not Promises). It uses the same two-phase
+ * best-effort seed extraction as {@link runWith} when two-pass contexts are
+ * present. In two-phase runs, each two-pass context's phase-two return value
+ * replaces that context's phase-one contribution for the final parse, so
+ * returning `{}` clears any annotations that context provided during phase 1.
  *
  * @template TParser The sync parser type.
  * @template THelp Return type when help is shown.
@@ -431,11 +486,20 @@ 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 or if a context's
+ * @throws {TypeError} If an async parser is passed at runtime.  Use
+ * {@link runWith} or {@link runWithAsync} for async parsers.
+ * @throws {TypeError} If two or more contexts share the same
+ * {@link SourceContext.id}.
+ * @throws {TypeError} If any context omits `phase` or declares an invalid
+ * phase value.
+ * @throws {TypeError} If any context returns a Promise or if a context's
  * `[Symbol.asyncDispose]` returns a Promise.
+ * @throws {SuppressedError} If the runner throws and a context's disposal
+ * also throws.  The original error is available via `.suppressed` and the
+ * disposal error via `.error`.
  * @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.
  *
@@ -450,8 +514,13 @@ declare function runWithSync<TParser extends Parser<"sync", unknown, unknown>, T
  * @param contexts Source contexts to use (priority: earlier overrides later).
  * @param options Run options including args, help, version, etc.
  * @returns Promise that resolves to the parsed result.
+ * @throws {TypeError} If two or more contexts share the same
+ * {@link SourceContext.id}.
+ * @throws {SuppressedError} If the runner throws and a context's disposal
+ * also throws.  The original error is available via `.suppressed` and the
+ * disposal error via `.error`.
  * @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 { CommandSubConfig, ExtractRequiredOptions, OptionSubConfig, 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, type SourceContextRequest, SubstituteParserValue, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync };

package/dist/facade.d.ts

@@ -1,9 +1,9 @@
 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 { InferMode, InferValue, Mode, ModeValue, Parser } from "./internal/parser.js";
 import { ShellCompletion } from "./completion.js";
-import { ParserValuePlaceholder, SourceContext } from "./context.js";
+import { ParserValuePlaceholder, SourceContext, SourceContextRequest } from "./context.js";
 import { Program } from "./program.js";
 
 //#region src/facade.d.ts
@@ -272,6 +272,13 @@ interface RunOptions<THelp, TError> {
  * @param options Configuration options for output formatting and callbacks.
  * @returns The parsed result value, or the return value of `onHelp`/`onError`
  *          callbacks.
+ * @throws {TypeError} If `programName` (or `program.metadata.name`) is not
+ *          a string, is empty, is whitespace-only, or contains control
+ *          characters.  Also thrown if `options.version.value` is not a
+ *          non-empty string without ASCII control characters, or if any
+ *          meta command/option name is empty, whitespace-only, contains
+ *          whitespace or control characters, or (for option names) lacks a
+ *          valid prefix (`--`, `-`, `/`, or `+`).
  * @throws {RunParserError} When parsing fails and no `onError` callback is
  *          provided.
  * @since 0.10.0 Added support for {@link Program} objects.
@@ -296,6 +303,8 @@ declare function runParser<TParser extends Parser<Mode, unknown, unknown>, THelp
  * @param args The command-line arguments to parse.
  * @param options Configuration options for customizing behavior.
  * @returns The parsed result if successful.
+ * @throws {TypeError} If an async parser is passed at runtime.  Use
+ * {@link runParser} or {@link runParserAsync} for async parsers.
  * @since 0.9.0
  */
 declare function runParserSync<TParser extends Parser<"sync", unknown, unknown>, THelp = void, TError = never>(parser: TParser, programName: string, args: readonly string[], options?: RunOptions<THelp, TError>): InferValue<TParser>;
@@ -367,24 +376,58 @@ 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.
  *
- * This function automatically handles static and dynamic contexts with proper
- * priority. Earlier contexts in the array override later ones.
+ * This function automatically handles single-pass and two-pass contexts with
+ * proper priority. Earlier contexts in the array override later ones.
  *
  * The function uses a smart two-phase approach:
  *
- * 1. *Phase 1*: Collect annotations from all contexts (static contexts return
- *    their data, dynamic contexts may return empty).
- * 2. *First parse*: Parse with Phase 1 annotations.
- * 3. *Phase 2*: Call `getAnnotations(parsed)` on all contexts with the first
- *    parse result.
- * 4. *Second parse*: Parse again with merged annotations from both phases.
+ * 1. *Phase 1*: Collect annotations from all contexts.
+ * 2. *First parse*: Parse with Phase 1 annotations. If that pass finishes
+ *    successfully, its value becomes the phase-two input. If the parser
+ *    reaches a usable intermediate state but still does not complete
+ *    successfully, the runner extracts a best-effort seed from that state
+ *    instead.
+ * 3. *Phase 2*: Call `getAnnotations({ phase: "phase2", parsed })` on all
+ *    two-pass contexts with the first pass value. Deferred or otherwise
+ *    unresolved fields in `parsed` may be `undefined`. Each two-pass
+ *    context's phase-two return
+ *    value replaces its own phase-one contribution for the final parse, so
+ *    returning `{}` clears any annotations that context provided during
+ *    phase 1. Single-pass contexts reuse their phase-one snapshot.
+ * 4. *Second parse*: Parse again with the merged phase-two annotations.
  *
- * If all contexts are static (no dynamic contexts), the second parse is skipped
- * for optimization.
+ * If all contexts are single-pass, the second parse is skipped for
+ * optimization. Phase 2 is also skipped when the first pass does not yield
+ * any usable seed at all.
  *
  * @template TParser The parser type.
  * @template THelp Return type when help is shown.
@@ -394,6 +437,13 @@ interface RunWithOptions<THelp, TError> extends RunOptions<THelp, TError> {
  * @param contexts Source contexts to use (priority: earlier overrides later).
  * @param options Run options including args, help, version, etc.
  * @returns Promise that resolves to the parsed result.
+ * @throws {TypeError} If two or more contexts share the same
+ * {@link SourceContext.id}.
+ * @throws {TypeError} If any context omits `phase` or declares an invalid
+ * phase value.
+ * @throws {SuppressedError} If the runner throws and a context's disposal
+ * also throws.  The original error is available via `.suppressed` and the
+ * disposal error via `.error`.
  * @since 0.10.0
  *
  * @example
@@ -403,6 +453,7 @@ interface RunWithOptions<THelp, TError> extends RunOptions<THelp, TError> {
  *
  * const envContext: SourceContext = {
  *   id: Symbol.for("@myapp/env"),
+ *   phase: "single-pass",
  *   getAnnotations() {
  *     return { [Symbol.for("@myapp/env")]: process.env };
  *   }
@@ -416,12 +467,16 @@ 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.
  *
  * This is the sync-only variant of {@link runWith}. All contexts must return
- * annotations synchronously (not Promises).
+ * annotations synchronously (not Promises). It uses the same two-phase
+ * best-effort seed extraction as {@link runWith} when two-pass contexts are
+ * present. In two-phase runs, each two-pass context's phase-two return value
+ * replaces that context's phase-one contribution for the final parse, so
+ * returning `{}` clears any annotations that context provided during phase 1.
  *
  * @template TParser The sync parser type.
  * @template THelp Return type when help is shown.
@@ -431,11 +486,20 @@ 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 or if a context's
+ * @throws {TypeError} If an async parser is passed at runtime.  Use
+ * {@link runWith} or {@link runWithAsync} for async parsers.
+ * @throws {TypeError} If two or more contexts share the same
+ * {@link SourceContext.id}.
+ * @throws {TypeError} If any context omits `phase` or declares an invalid
+ * phase value.
+ * @throws {TypeError} If any context returns a Promise or if a context's
  * `[Symbol.asyncDispose]` returns a Promise.
+ * @throws {SuppressedError} If the runner throws and a context's disposal
+ * also throws.  The original error is available via `.suppressed` and the
+ * disposal error via `.error`.
  * @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.
  *
@@ -450,8 +514,13 @@ declare function runWithSync<TParser extends Parser<"sync", unknown, unknown>, T
  * @param contexts Source contexts to use (priority: earlier overrides later).
  * @param options Run options including args, help, version, etc.
  * @returns Promise that resolves to the parsed result.
+ * @throws {TypeError} If two or more contexts share the same
+ * {@link SourceContext.id}.
+ * @throws {SuppressedError} If the runner throws and a context's disposal
+ * also throws.  The original error is available via `.suppressed` and the
+ * disposal error via `.error`.
  * @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 { CommandSubConfig, ExtractRequiredOptions, OptionSubConfig, 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, type SourceContextRequest, SubstituteParserValue, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync };