@optique/core 1.0.0-dev.921 → 1.0.1

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>;
@@ -396,20 +405,29 @@ type ContextOptionsParam<TContexts extends readonly SourceContext<unknown>[], TV
 /**
  * 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.
@@ -419,6 +437,13 @@ type ContextOptionsParam<TContexts extends readonly SourceContext<unknown>[], TV
  * @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
@@ -428,6 +453,7 @@ type ContextOptionsParam<TContexts extends readonly SourceContext<unknown>[], TV
  *
  * const envContext: SourceContext = {
  *   id: Symbol.for("@myapp/env"),
+ *   phase: "single-pass",
  *   getAnnotations() {
  *     return { [Symbol.for("@myapp/env")]: process.env };
  *   }
@@ -446,7 +472,11 @@ declare function runWith<TParser extends Parser<Mode, unknown, unknown>, TContex
  * 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.
@@ -456,8 +486,17 @@ 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> & ContextOptionsParam<TContexts, InferValue<TParser>>): InferValue<TParser>;
@@ -475,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> & ContextOptionsParam<TContexts, InferValue<TParser>>): Promise<InferValue<TParser>>;
 //#endregion
-export { CommandSubConfig, ContextOptionsParam, 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>;
@@ -396,20 +405,29 @@ type ContextOptionsParam<TContexts extends readonly SourceContext<unknown>[], TV
 /**
  * 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.
@@ -419,6 +437,13 @@ type ContextOptionsParam<TContexts extends readonly SourceContext<unknown>[], TV
  * @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
@@ -428,6 +453,7 @@ type ContextOptionsParam<TContexts extends readonly SourceContext<unknown>[], TV
  *
  * const envContext: SourceContext = {
  *   id: Symbol.for("@myapp/env"),
+ *   phase: "single-pass",
  *   getAnnotations() {
  *     return { [Symbol.for("@myapp/env")]: process.env };
  *   }
@@ -446,7 +472,11 @@ declare function runWith<TParser extends Parser<Mode, unknown, unknown>, TContex
  * 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.
@@ -456,8 +486,17 @@ 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> & ContextOptionsParam<TContexts, InferValue<TParser>>): InferValue<TParser>;
@@ -475,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> & ContextOptionsParam<TContexts, InferValue<TParser>>): Promise<InferValue<TParser>>;
 //#endregion
-export { CommandSubConfig, ContextOptionsParam, 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 };