@optique/core 0.10.0-dev.332 → 0.10.0-dev.335

package/dist/context.d.cts

@@ -2,6 +2,40 @@ import { Annotations } from "./annotations.cjs";
 
 //#region src/context.d.ts
 
+/**
+ * Brand symbol for ParserValuePlaceholder type.
+ * @internal
+ */
+declare const parserValuePlaceholderBrand: unique symbol;
+/**
+ * A placeholder type that represents the parser's result value type.
+ *
+ * Use this type in `SourceContext<TRequiredOptions>` when the required options
+ * depend on the parser's result type. The `runWith()` function will substitute
+ * this placeholder with the actual parser value type at call site.
+ *
+ * @example
+ * ```typescript
+ * import type { SourceContext, ParserValuePlaceholder } from "@optique/core/context";
+ *
+ * // Define a context that requires options depending on parser result
+ * interface MyContext extends SourceContext<{
+ *   extractPath: (parsed: ParserValuePlaceholder) => string | undefined;
+ * }> {
+ *   // ...
+ * }
+ *
+ * // When used with runWith(), the placeholder becomes the actual parser type:
+ * // runWith(parser, "app", [myContext], {
+ * //   extractPath: (parsed) => parsed.configPath  // 'parsed' is typed!
+ * // });
+ * ```
+ *
+ * @since 0.10.0
+ */
+type ParserValuePlaceholder = {
+  readonly [parserValuePlaceholderBrand]: "ParserValuePlaceholder";
+};
 /**
  * A source context that can provide data to parsers via annotations.
  *
@@ -12,9 +46,14 @@ import { Annotations } from "./annotations.cjs";
  * - *Dynamic*: Data depends on parsing results (e.g., config files whose path
  *   is determined by a CLI option)
  *
+ * @template TRequiredOptions Additional options that `runWith()` must provide
+ *   when this context is used. Use `void` (the default) for contexts that
+ *   don't require extra options. Use {@link ParserValuePlaceholder} in option
+ *   types that depend on the parser's result type.
+ *
  * @example
  * ```typescript
- * // Static context example (environment variables)
+ * // Static context example (environment variables) - no extra options needed
  * const envContext: SourceContext = {
  *   id: Symbol.for("@myapp/env"),
  *   getAnnotations() {
@@ -27,24 +66,17 @@ import { Annotations } from "./annotations.cjs";
  *   }
  * };
  *
- * // Dynamic context example (config file)
- * const configContext: SourceContext = {
- *   id: Symbol.for("@myapp/config"),
- *   async getAnnotations(parsed?: unknown) {
- *     if (!parsed) return {}; // Return empty on first pass
- *     const result = parsed as { config?: string };
- *     if (!result.config) return {};
- *     const data = await loadConfigFile(result.config);
- *     return {
- *       [Symbol.for("@myapp/config")]: data
- *     };
- *   }
- * };
+ * // Dynamic context that requires options from runWith()
+ * interface ConfigContext extends SourceContext<{
+ *   getConfigPath: (parsed: ParserValuePlaceholder) => string | undefined;
+ * }> {
+ *   // ...
+ * }
  * ```
  *
  * @since 0.10.0
  */
-interface SourceContext {
+interface SourceContext<TRequiredOptions = void> {
   /**
    * Unique identifier for this context.
    *
@@ -52,6 +84,11 @@ interface SourceContext {
    * that consume this context's data.
    */
   readonly id: symbol;
+  /**
+   * Type-level marker for the required options. Not used at runtime.
+   * @internal
+   */
+  readonly _requiredOptions?: TRequiredOptions;
   /**
    * Get annotations to inject into parsing.
    *
@@ -82,6 +119,6 @@ interface SourceContext {
  * @returns `true` if the context is static, `false` otherwise.
  * @since 0.10.0
  */
-declare function isStaticContext(context: SourceContext): boolean;
+declare function isStaticContext(context: SourceContext<unknown>): boolean;
 //#endregion
-export { type Annotations, SourceContext, isStaticContext };
+export { type Annotations, ParserValuePlaceholder, SourceContext, isStaticContext };

package/dist/context.d.ts

@@ -2,6 +2,40 @@ import { Annotations } from "./annotations.js";
 
 //#region src/context.d.ts
 
+/**
+ * Brand symbol for ParserValuePlaceholder type.
+ * @internal
+ */
+declare const parserValuePlaceholderBrand: unique symbol;
+/**
+ * A placeholder type that represents the parser's result value type.
+ *
+ * Use this type in `SourceContext<TRequiredOptions>` when the required options
+ * depend on the parser's result type. The `runWith()` function will substitute
+ * this placeholder with the actual parser value type at call site.
+ *
+ * @example
+ * ```typescript
+ * import type { SourceContext, ParserValuePlaceholder } from "@optique/core/context";
+ *
+ * // Define a context that requires options depending on parser result
+ * interface MyContext extends SourceContext<{
+ *   extractPath: (parsed: ParserValuePlaceholder) => string | undefined;
+ * }> {
+ *   // ...
+ * }
+ *
+ * // When used with runWith(), the placeholder becomes the actual parser type:
+ * // runWith(parser, "app", [myContext], {
+ * //   extractPath: (parsed) => parsed.configPath  // 'parsed' is typed!
+ * // });
+ * ```
+ *
+ * @since 0.10.0
+ */
+type ParserValuePlaceholder = {
+  readonly [parserValuePlaceholderBrand]: "ParserValuePlaceholder";
+};
 /**
  * A source context that can provide data to parsers via annotations.
  *
@@ -12,9 +46,14 @@ import { Annotations } from "./annotations.js";
  * - *Dynamic*: Data depends on parsing results (e.g., config files whose path
  *   is determined by a CLI option)
  *
+ * @template TRequiredOptions Additional options that `runWith()` must provide
+ *   when this context is used. Use `void` (the default) for contexts that
+ *   don't require extra options. Use {@link ParserValuePlaceholder} in option
+ *   types that depend on the parser's result type.
+ *
  * @example
  * ```typescript
- * // Static context example (environment variables)
+ * // Static context example (environment variables) - no extra options needed
  * const envContext: SourceContext = {
  *   id: Symbol.for("@myapp/env"),
  *   getAnnotations() {
@@ -27,24 +66,17 @@ import { Annotations } from "./annotations.js";
  *   }
  * };
  *
- * // Dynamic context example (config file)
- * const configContext: SourceContext = {
- *   id: Symbol.for("@myapp/config"),
- *   async getAnnotations(parsed?: unknown) {
- *     if (!parsed) return {}; // Return empty on first pass
- *     const result = parsed as { config?: string };
- *     if (!result.config) return {};
- *     const data = await loadConfigFile(result.config);
- *     return {
- *       [Symbol.for("@myapp/config")]: data
- *     };
- *   }
- * };
+ * // Dynamic context that requires options from runWith()
+ * interface ConfigContext extends SourceContext<{
+ *   getConfigPath: (parsed: ParserValuePlaceholder) => string | undefined;
+ * }> {
+ *   // ...
+ * }
  * ```
  *
  * @since 0.10.0
  */
-interface SourceContext {
+interface SourceContext<TRequiredOptions = void> {
   /**
    * Unique identifier for this context.
    *
@@ -52,6 +84,11 @@ interface SourceContext {
    * that consume this context's data.
    */
   readonly id: symbol;
+  /**
+   * Type-level marker for the required options. Not used at runtime.
+   * @internal
+   */
+  readonly _requiredOptions?: TRequiredOptions;
   /**
    * Get annotations to inject into parsing.
    *
@@ -82,6 +119,6 @@ interface SourceContext {
  * @returns `true` if the context is static, `false` otherwise.
  * @since 0.10.0
  */
-declare function isStaticContext(context: SourceContext): boolean;
+declare function isStaticContext(context: SourceContext<unknown>): boolean;
 //#endregion
-export { type Annotations, SourceContext, isStaticContext };
+export { type Annotations, ParserValuePlaceholder, SourceContext, isStaticContext };

package/dist/facade.d.cts

@@ -2,7 +2,7 @@ import { Message } from "./message.cjs";
 import { ShowDefaultOptions } from "./doc.cjs";
 import { InferMode, InferValue, Mode, ModeValue, Parser } from "./parser.cjs";
 import { ShellCompletion } from "./completion.cjs";
-import { SourceContext } from "./context.cjs";
+import { ParserValuePlaceholder, SourceContext } from "./context.cjs";
 import { Program } from "./program.cjs";
 
 //#region src/facade.d.ts
@@ -283,6 +283,35 @@ declare function runParserAsync<TParser extends Parser<Mode, unknown, unknown>,
 declare class RunParserError extends Error {
   constructor(message: string);
 }
+/**
+ * Substitutes {@link ParserValuePlaceholder} with the actual parser value type.
+ *
+ * This type recursively traverses `T` and replaces any occurrence of
+ * `ParserValuePlaceholder` with `TValue`. Used by `runWith()` to compute
+ * the required options type based on the parser's result type.
+ *
+ * @template T The type to transform.
+ * @template TValue The parser value type to substitute.
+ * @since 0.10.0
+ */
+type SubstituteParserValue<T, TValue> = T extends ParserValuePlaceholder ? TValue : T extends ((...args: infer A) => infer R) ? (...args: { [K in keyof A]: SubstituteParserValue<A[K], TValue> }) => SubstituteParserValue<R, TValue> : T extends object ? { [K in keyof T]: SubstituteParserValue<T[K], TValue> } : T;
+/**
+ * Converts a union type to an intersection type.
+ * @internal
+ */
+type UnionToIntersection<U> = (U extends unknown ? (k: U) => void : never) extends ((k: infer I) => void) ? I : never;
+/**
+ * Extracts and merges required options from an array of source contexts.
+ *
+ * For each context in the array, extracts its `TRequiredOptions` type parameter,
+ * substitutes any `ParserValuePlaceholder` with `TValue`, and intersects all
+ * the resulting option types.
+ *
+ * @template TContexts The tuple/array type of source contexts.
+ * @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>;
 /**
  * Options for runWith functions.
  * Extends RunOptions with additional context-related settings.
@@ -346,7 +375,7 @@ interface RunWithOptions<THelp, TError> extends RunOptions<THelp, TError> {
  * );
  * ```
  */
-declare function runWith<TParser extends Parser<Mode, unknown, unknown>, THelp = void, TError = never>(parser: TParser, programName: string, contexts: readonly SourceContext[], options?: RunWithOptions<THelp, TError>): 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> & ExtractRequiredOptions<TContexts, InferValue<TParser>>): Promise<InferValue<TParser>>;
 /**
  * Runs a synchronous parser with multiple source contexts.
  *
@@ -364,7 +393,7 @@ declare function runWith<TParser extends Parser<Mode, unknown, unknown>, THelp =
  * @throws Error if any context returns a Promise.
  * @since 0.10.0
  */
-declare function runWithSync<TParser extends Parser<"sync", unknown, unknown>, THelp = void, TError = never>(parser: TParser, programName: string, contexts: readonly SourceContext[], options?: RunWithOptions<THelp, TError>): 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> & ExtractRequiredOptions<TContexts, InferValue<TParser>>): InferValue<TParser>;
 /**
  * Runs any parser asynchronously with multiple source contexts.
  *
@@ -381,6 +410,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>, THelp = void, TError = never>(parser: TParser, programName: string, contexts: readonly SourceContext[], options?: RunWithOptions<THelp, TError>): 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> & ExtractRequiredOptions<TContexts, InferValue<TParser>>): Promise<InferValue<TParser>>;
 //#endregion
-export { RunOptions, RunParserError, RunWithOptions, type SourceContext, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync };
+export { ExtractRequiredOptions, type ParserValuePlaceholder, RunOptions, RunParserError, RunWithOptions, type SourceContext, SubstituteParserValue, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync };

package/dist/facade.d.ts

@@ -2,7 +2,7 @@ import { Message } from "./message.js";
 import { ShowDefaultOptions } from "./doc.js";
 import { InferMode, InferValue, Mode, ModeValue, Parser } from "./parser.js";
 import { ShellCompletion } from "./completion.js";
-import { SourceContext } from "./context.js";
+import { ParserValuePlaceholder, SourceContext } from "./context.js";
 import { Program } from "./program.js";
 
 //#region src/facade.d.ts
@@ -283,6 +283,35 @@ declare function runParserAsync<TParser extends Parser<Mode, unknown, unknown>,
 declare class RunParserError extends Error {
   constructor(message: string);
 }
+/**
+ * Substitutes {@link ParserValuePlaceholder} with the actual parser value type.
+ *
+ * This type recursively traverses `T` and replaces any occurrence of
+ * `ParserValuePlaceholder` with `TValue`. Used by `runWith()` to compute
+ * the required options type based on the parser's result type.
+ *
+ * @template T The type to transform.
+ * @template TValue The parser value type to substitute.
+ * @since 0.10.0
+ */
+type SubstituteParserValue<T, TValue> = T extends ParserValuePlaceholder ? TValue : T extends ((...args: infer A) => infer R) ? (...args: { [K in keyof A]: SubstituteParserValue<A[K], TValue> }) => SubstituteParserValue<R, TValue> : T extends object ? { [K in keyof T]: SubstituteParserValue<T[K], TValue> } : T;
+/**
+ * Converts a union type to an intersection type.
+ * @internal
+ */
+type UnionToIntersection<U> = (U extends unknown ? (k: U) => void : never) extends ((k: infer I) => void) ? I : never;
+/**
+ * Extracts and merges required options from an array of source contexts.
+ *
+ * For each context in the array, extracts its `TRequiredOptions` type parameter,
+ * substitutes any `ParserValuePlaceholder` with `TValue`, and intersects all
+ * the resulting option types.
+ *
+ * @template TContexts The tuple/array type of source contexts.
+ * @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>;
 /**
  * Options for runWith functions.
  * Extends RunOptions with additional context-related settings.
@@ -346,7 +375,7 @@ interface RunWithOptions<THelp, TError> extends RunOptions<THelp, TError> {
  * );
  * ```
  */
-declare function runWith<TParser extends Parser<Mode, unknown, unknown>, THelp = void, TError = never>(parser: TParser, programName: string, contexts: readonly SourceContext[], options?: RunWithOptions<THelp, TError>): 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> & ExtractRequiredOptions<TContexts, InferValue<TParser>>): Promise<InferValue<TParser>>;
 /**
  * Runs a synchronous parser with multiple source contexts.
  *
@@ -364,7 +393,7 @@ declare function runWith<TParser extends Parser<Mode, unknown, unknown>, THelp =
  * @throws Error if any context returns a Promise.
  * @since 0.10.0
  */
-declare function runWithSync<TParser extends Parser<"sync", unknown, unknown>, THelp = void, TError = never>(parser: TParser, programName: string, contexts: readonly SourceContext[], options?: RunWithOptions<THelp, TError>): 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> & ExtractRequiredOptions<TContexts, InferValue<TParser>>): InferValue<TParser>;
 /**
  * Runs any parser asynchronously with multiple source contexts.
  *
@@ -381,6 +410,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>, THelp = void, TError = never>(parser: TParser, programName: string, contexts: readonly SourceContext[], options?: RunWithOptions<THelp, TError>): 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> & ExtractRequiredOptions<TContexts, InferValue<TParser>>): Promise<InferValue<TParser>>;
 //#endregion
-export { RunOptions, RunParserError, RunWithOptions, type SourceContext, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync };
+export { ExtractRequiredOptions, type ParserValuePlaceholder, RunOptions, RunParserError, RunWithOptions, type SourceContext, SubstituteParserValue, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync };

package/dist/index.d.cts

@@ -10,6 +10,6 @@ import { AnyDependencySource, CombineMode, CombinedDependencyMode, DeferredParse
 import { ArgumentErrorOptions, ArgumentOptions, CommandErrorOptions, CommandOptions, FlagErrorOptions, FlagOptions, OptionErrorOptions, OptionOptions, OptionState, PassThroughFormat, PassThroughOptions, argument, command, constant, flag, option, passThrough } from "./primitives.cjs";
 import { CombineModes, DocState, InferMode, InferValue, Mode, ModeIterable, ModeValue, Parser, ParserContext, ParserResult, Result, Suggestion, getDocPage, getDocPageAsync, getDocPageSync, parse, parseAsync, parseSync, suggest, suggestAsync, suggestSync } from "./parser.cjs";
 import { ShellCompletion, bash, fish, nu, pwsh, zsh } from "./completion.cjs";
-import { SourceContext } from "./context.cjs";
-import { RunOptions, RunParserError, RunWithOptions, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync } from "./facade.cjs";
-export { type Annotations, AnyDependencySource, ArgumentErrorOptions, ArgumentOptions, ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CombineMode, CombineModes, CombinedDependencyMode, CommandErrorOptions, CommandOptions, ConditionalErrorOptions, ConditionalOptions, DeferredParseState, DependencyError, DependencyMode, DependencyRegistry, DependencySource, DependencySourceState, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, DocState, DuplicateOptionError, FlagErrorOptions, FlagOptions, FloatOptions, InferMode, InferValue, IntegerOptionsBigInt, IntegerOptionsNumber, LocaleOptions, LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, type Message, type MessageFormatOptions, type MessageTerm, Mode, ModeIterable, ModeValue, MultipleErrorOptions, MultipleOptions, NoMatchContext, NonEmptyString, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionName, OptionOptions, OptionState, OrErrorOptions, OrOptions, type ParseOptions, Parser, ParserContext, ParserResult, PassThroughFormat, PassThroughOptions, PendingDependencySourceState, ResolvedDependency, Result, RunOptions, RunParserError, RunWithOptions, ShellCompletion, ShowDefaultOptions, SourceContext, StringOptions, Suggestion, TupleOptions, UrlOptions, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, type ValueSetOptions, WithDefaultError, WithDefaultOptions, annotationKey, argument, bash, choice, command, commandLine, concat, conditional, constant, createDeferredParseState, createDependencySourceState, createPendingDependencySourceState, defaultValues, deferredParseMarker, dependency, dependencyId, dependencyIds, dependencySourceMarker, dependencySourceStateMarker, deriveFrom, deriveFromAsync, deriveFromSync, derivedValueParserMarker, ensureNonEmptyString, envVar, extractArgumentMetavars, extractCommandNames, extractOptionNames, fish, flag, float, formatDependencyError, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getAnnotations, getDefaultValuesFunction, getDependencyIds, getDocPage, getDocPageAsync, getDocPageSync, group, integer, isDeferredParseState, isDependencySource, isDependencySourceState, isDerivedValueParser, isNonEmptyString, isPendingDependencySourceState, isValueParser, isWrappedDependencySource, link, locale, longestMatch, map, merge, message, metavar, multiple, nonEmpty, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, parse, parseAsync, parseSync, parseWithDependency, passThrough, pendingDependencySourceStateMarker, pwsh, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync, string, suggest, suggestAsync, suggestSync, suggestWithDependency, text, transformsDependencyValue, transformsDependencyValueMarker, tuple, url, uuid, value, valueSet, values, withDefault, wrappedDependencySourceMarker, zsh };
+import { ParserValuePlaceholder, SourceContext } from "./context.cjs";
+import { ExtractRequiredOptions, RunOptions, RunParserError, RunWithOptions, SubstituteParserValue, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync } from "./facade.cjs";
+export { type Annotations, AnyDependencySource, ArgumentErrorOptions, ArgumentOptions, ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CombineMode, CombineModes, CombinedDependencyMode, CommandErrorOptions, CommandOptions, ConditionalErrorOptions, ConditionalOptions, DeferredParseState, DependencyError, DependencyMode, DependencyRegistry, DependencySource, DependencySourceState, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, DocState, DuplicateOptionError, ExtractRequiredOptions, FlagErrorOptions, FlagOptions, FloatOptions, InferMode, InferValue, IntegerOptionsBigInt, IntegerOptionsNumber, LocaleOptions, LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, type Message, type MessageFormatOptions, type MessageTerm, Mode, ModeIterable, ModeValue, MultipleErrorOptions, MultipleOptions, NoMatchContext, NonEmptyString, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionName, OptionOptions, OptionState, OrErrorOptions, OrOptions, type ParseOptions, Parser, ParserContext, ParserResult, ParserValuePlaceholder, PassThroughFormat, PassThroughOptions, PendingDependencySourceState, ResolvedDependency, Result, RunOptions, RunParserError, RunWithOptions, ShellCompletion, ShowDefaultOptions, SourceContext, StringOptions, SubstituteParserValue, Suggestion, TupleOptions, UrlOptions, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, type ValueSetOptions, WithDefaultError, WithDefaultOptions, annotationKey, argument, bash, choice, command, commandLine, concat, conditional, constant, createDeferredParseState, createDependencySourceState, createPendingDependencySourceState, defaultValues, deferredParseMarker, dependency, dependencyId, dependencyIds, dependencySourceMarker, dependencySourceStateMarker, deriveFrom, deriveFromAsync, deriveFromSync, derivedValueParserMarker, ensureNonEmptyString, envVar, extractArgumentMetavars, extractCommandNames, extractOptionNames, fish, flag, float, formatDependencyError, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getAnnotations, getDefaultValuesFunction, getDependencyIds, getDocPage, getDocPageAsync, getDocPageSync, group, integer, isDeferredParseState, isDependencySource, isDependencySourceState, isDerivedValueParser, isNonEmptyString, isPendingDependencySourceState, isValueParser, isWrappedDependencySource, link, locale, longestMatch, map, merge, message, metavar, multiple, nonEmpty, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, parse, parseAsync, parseSync, parseWithDependency, passThrough, pendingDependencySourceStateMarker, pwsh, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync, string, suggest, suggestAsync, suggestSync, suggestWithDependency, text, transformsDependencyValue, transformsDependencyValueMarker, tuple, url, uuid, value, valueSet, values, withDefault, wrappedDependencySourceMarker, zsh };

package/dist/index.d.ts

@@ -10,6 +10,6 @@ import { AnyDependencySource, CombineMode, CombinedDependencyMode, DeferredParse
 import { ArgumentErrorOptions, ArgumentOptions, CommandErrorOptions, CommandOptions, FlagErrorOptions, FlagOptions, OptionErrorOptions, OptionOptions, OptionState, PassThroughFormat, PassThroughOptions, argument, command, constant, flag, option, passThrough } from "./primitives.js";
 import { CombineModes, DocState, InferMode, InferValue, Mode, ModeIterable, ModeValue, Parser, ParserContext, ParserResult, Result, Suggestion, getDocPage, getDocPageAsync, getDocPageSync, parse, parseAsync, parseSync, suggest, suggestAsync, suggestSync } from "./parser.js";
 import { ShellCompletion, bash, fish, nu, pwsh, zsh } from "./completion.js";
-import { SourceContext } from "./context.js";
-import { RunOptions, RunParserError, RunWithOptions, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync } from "./facade.js";
-export { type Annotations, AnyDependencySource, ArgumentErrorOptions, ArgumentOptions, ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CombineMode, CombineModes, CombinedDependencyMode, CommandErrorOptions, CommandOptions, ConditionalErrorOptions, ConditionalOptions, DeferredParseState, DependencyError, DependencyMode, DependencyRegistry, DependencySource, DependencySourceState, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, DocState, DuplicateOptionError, FlagErrorOptions, FlagOptions, FloatOptions, InferMode, InferValue, IntegerOptionsBigInt, IntegerOptionsNumber, LocaleOptions, LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, type Message, type MessageFormatOptions, type MessageTerm, Mode, ModeIterable, ModeValue, MultipleErrorOptions, MultipleOptions, NoMatchContext, NonEmptyString, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionName, OptionOptions, OptionState, OrErrorOptions, OrOptions, type ParseOptions, Parser, ParserContext, ParserResult, PassThroughFormat, PassThroughOptions, PendingDependencySourceState, ResolvedDependency, Result, RunOptions, RunParserError, RunWithOptions, ShellCompletion, ShowDefaultOptions, SourceContext, StringOptions, Suggestion, TupleOptions, UrlOptions, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, type ValueSetOptions, WithDefaultError, WithDefaultOptions, annotationKey, argument, bash, choice, command, commandLine, concat, conditional, constant, createDeferredParseState, createDependencySourceState, createPendingDependencySourceState, defaultValues, deferredParseMarker, dependency, dependencyId, dependencyIds, dependencySourceMarker, dependencySourceStateMarker, deriveFrom, deriveFromAsync, deriveFromSync, derivedValueParserMarker, ensureNonEmptyString, envVar, extractArgumentMetavars, extractCommandNames, extractOptionNames, fish, flag, float, formatDependencyError, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getAnnotations, getDefaultValuesFunction, getDependencyIds, getDocPage, getDocPageAsync, getDocPageSync, group, integer, isDeferredParseState, isDependencySource, isDependencySourceState, isDerivedValueParser, isNonEmptyString, isPendingDependencySourceState, isValueParser, isWrappedDependencySource, link, locale, longestMatch, map, merge, message, metavar, multiple, nonEmpty, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, parse, parseAsync, parseSync, parseWithDependency, passThrough, pendingDependencySourceStateMarker, pwsh, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync, string, suggest, suggestAsync, suggestSync, suggestWithDependency, text, transformsDependencyValue, transformsDependencyValueMarker, tuple, url, uuid, value, valueSet, values, withDefault, wrappedDependencySourceMarker, zsh };
+import { ParserValuePlaceholder, SourceContext } from "./context.js";
+import { ExtractRequiredOptions, RunOptions, RunParserError, RunWithOptions, SubstituteParserValue, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync } from "./facade.js";
+export { type Annotations, AnyDependencySource, ArgumentErrorOptions, ArgumentOptions, ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CombineMode, CombineModes, CombinedDependencyMode, CommandErrorOptions, CommandOptions, ConditionalErrorOptions, ConditionalOptions, DeferredParseState, DependencyError, DependencyMode, DependencyRegistry, DependencySource, DependencySourceState, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, DocState, DuplicateOptionError, ExtractRequiredOptions, FlagErrorOptions, FlagOptions, FloatOptions, InferMode, InferValue, IntegerOptionsBigInt, IntegerOptionsNumber, LocaleOptions, LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, type Message, type MessageFormatOptions, type MessageTerm, Mode, ModeIterable, ModeValue, MultipleErrorOptions, MultipleOptions, NoMatchContext, NonEmptyString, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionName, OptionOptions, OptionState, OrErrorOptions, OrOptions, type ParseOptions, Parser, ParserContext, ParserResult, ParserValuePlaceholder, PassThroughFormat, PassThroughOptions, PendingDependencySourceState, ResolvedDependency, Result, RunOptions, RunParserError, RunWithOptions, ShellCompletion, ShowDefaultOptions, SourceContext, StringOptions, SubstituteParserValue, Suggestion, TupleOptions, UrlOptions, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, type ValueSetOptions, WithDefaultError, WithDefaultOptions, annotationKey, argument, bash, choice, command, commandLine, concat, conditional, constant, createDeferredParseState, createDependencySourceState, createPendingDependencySourceState, defaultValues, deferredParseMarker, dependency, dependencyId, dependencyIds, dependencySourceMarker, dependencySourceStateMarker, deriveFrom, deriveFromAsync, deriveFromSync, derivedValueParserMarker, ensureNonEmptyString, envVar, extractArgumentMetavars, extractCommandNames, extractOptionNames, fish, flag, float, formatDependencyError, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getAnnotations, getDefaultValuesFunction, getDependencyIds, getDocPage, getDocPageAsync, getDocPageSync, group, integer, isDeferredParseState, isDependencySource, isDependencySourceState, isDerivedValueParser, isNonEmptyString, isPendingDependencySourceState, isValueParser, isWrappedDependencySource, link, locale, longestMatch, map, merge, message, metavar, multiple, nonEmpty, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, parse, parseAsync, parseSync, parseWithDependency, passThrough, pendingDependencySourceStateMarker, pwsh, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync, string, suggest, suggestAsync, suggestSync, suggestWithDependency, text, transformsDependencyValue, transformsDependencyValueMarker, tuple, url, uuid, value, valueSet, values, withDefault, wrappedDependencySourceMarker, zsh };

package/dist/primitives.cjs

@@ -965,21 +965,23 @@ function command(name, parser, options = {}) {
 			return suggestCommandSync(context, prefix, name, parser, options);
 		},
 		getDocFragments(state, defaultValue) {
-			if (options.hidden) return {
-				fragments: [],
-				description: options.description
-			};
-			if (state.kind === "unavailable" || typeof state.state === "undefined") return {
-				description: options.description,
-				fragments: [{
-					type: "entry",
-					term: {
-						type: "command",
-						name
-					},
-					description: options.brief ?? options.description
-				}]
-			};
+			if (state.kind === "unavailable" || typeof state.state === "undefined") {
+				if (options.hidden) return {
+					fragments: [],
+					description: options.description
+				};
+				return {
+					description: options.description,
+					fragments: [{
+						type: "entry",
+						term: {
+							type: "command",
+							name
+						},
+						description: options.brief ?? options.description
+					}]
+				};
+			}
 			const innerState = state.state[0] === "parsing" ? {
 				kind: "available",
 				state: state.state[1]

package/dist/primitives.js

@@ -965,21 +965,23 @@ function command(name, parser, options = {}) {
 			return suggestCommandSync(context, prefix, name, parser, options);
 		},
 		getDocFragments(state, defaultValue) {
-			if (options.hidden) return {
-				fragments: [],
-				description: options.description
-			};
-			if (state.kind === "unavailable" || typeof state.state === "undefined") return {
-				description: options.description,
-				fragments: [{
-					type: "entry",
-					term: {
-						type: "command",
-						name
-					},
-					description: options.brief ?? options.description
-				}]
-			};
+			if (state.kind === "unavailable" || typeof state.state === "undefined") {
+				if (options.hidden) return {
+					fragments: [],
+					description: options.description
+				};
+				return {
+					description: options.description,
+					fragments: [{
+						type: "entry",
+						term: {
+							type: "command",
+							name
+						},
+						description: options.brief ?? options.description
+					}]
+				};
+			}
 			const innerState = state.state[0] === "parsing" ? {
 				kind: "available",
 				state: state.state[1]

package/dist/usage.cjs

@@ -123,6 +123,8 @@ function formatUsage(programName, usage, options = {}) {
 		if (usage.length > 0 && usage.slice(0, -1).every((t) => t.type === "command") && lastTerm.type === "exclusive" && lastTerm.terms.every((t) => t.length > 0 && (t[0].type === "command" || t[0].type === "option" || t[0].type === "argument" || t[0].type === "optional" && t[0].terms.length === 1 && (t[0].terms[0].type === "command" || t[0].terms[0].type === "option" || t[0].terms[0].type === "argument")))) {
 			const lines = [];
 			for (let command of lastTerm.terms) {
+				const firstTerm = command[0];
+				if (firstTerm?.type === "command" && firstTerm.hidden) continue;
 				if (usage.length > 1) command = [...usage.slice(0, -1), ...command];
 				lines.push(formatUsage(programName, command, options));
 			}

package/dist/usage.js

@@ -122,6 +122,8 @@ function formatUsage(programName, usage, options = {}) {
 		if (usage.length > 0 && usage.slice(0, -1).every((t) => t.type === "command") && lastTerm.type === "exclusive" && lastTerm.terms.every((t) => t.length > 0 && (t[0].type === "command" || t[0].type === "option" || t[0].type === "argument" || t[0].type === "optional" && t[0].terms.length === 1 && (t[0].terms[0].type === "command" || t[0].terms[0].type === "option" || t[0].terms[0].type === "argument")))) {
 			const lines = [];
 			for (let command of lastTerm.terms) {
+				const firstTerm = command[0];
+				if (firstTerm?.type === "command" && firstTerm.hidden) continue;
 				if (usage.length > 1) command = [...usage.slice(0, -1), ...command];
 				lines.push(formatUsage(programName, command, options));
 			}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/core",
-  "version": "0.10.0-dev.332+be2882ab",
+  "version": "0.10.0-dev.335+bfcb880a",
   "description": "Type-safe combinatorial command-line interface parser",
   "keywords": [
     "CLI",