@optique/run 1.0.0-dev.586 → 1.0.0-dev.588

package/dist/run.d.cts

@@ -226,12 +226,32 @@ interface RunOptions {
    */
   readonly contexts?: readonly SourceContext<unknown>[];
 }
+/**
+ * Rejects context tuples that are statically known to be empty so those calls
+ * fall back to the synchronous no-context overloads.
+ */
 type RejectEmptyContexts<TContexts extends readonly SourceContext<unknown>[]> = TContexts extends readonly [] ? never : unknown;
+/**
+ * Represents a context tuple that is statically known to contain at least one
+ * source context.
+ */
 type NonEmptySourceContexts = readonly [SourceContext<unknown>, ...SourceContext<unknown>[]];
+/**
+ * Rejects option shapes that may carry a non-empty `contexts` array so plain
+ * Program overloads do not bypass the context-aware overloads.
+ */
 type RejectContextfulOptions<TOptions> = TOptions extends {
   readonly contexts?: infer TContexts extends readonly SourceContext<unknown>[] | undefined;
 } ? [TContexts] extends [undefined | readonly []] ? unknown : never : unknown;
+/**
+ * Rejects option shapes that introduce keys outside the public `RunOptions`
+ * contract, preserving excess-property checks for direct object literals.
+ */
 type RejectUnknownRunOptionKeys<TOptions> = [TOptions] extends [undefined] ? unknown : Exclude<keyof TOptions, keyof RunOptions> extends never ? unknown : never;
+/**
+ * Accepts only values typed exactly as `RunOptions`, which are widened to the
+ * conservative fallback overloads because they may hide context presence.
+ */
 type AcceptExactRunOptions<TOptions> = [TOptions] extends [RunOptions] ? [RunOptions] extends [TOptions] ? unknown : never : never;
 /**
  * Runs a command-line parser with automatic process integration.
@@ -304,7 +324,13 @@ declare function run<T extends Parser<Mode, unknown, unknown>, const TContexts e
 declare function run<T extends Parser<Mode, unknown, unknown>, const TContexts extends readonly SourceContext<unknown>[]>(parser: T, options: RunOptions & {
   readonly contexts: TContexts;
 } & RejectEmptyContexts<TContexts> & ExtractRequiredOptions<TContexts, InferValue<T>>): ModeValue<InferMode<T>, InferValue<T>> | Promise<InferValue<T>>;
-declare function run<M extends Mode, T, const TContexts extends readonly SourceContext<unknown>[]>(program: Program<M, T>, options: RunOptions & {
+declare function run<M extends Mode, T, const TContexts extends NonEmptySourceContexts>(program: Program<M, T>, options: RunOptions & {
+  readonly contexts: TContexts;
+} & ExtractRequiredOptions<TContexts, T>): Promise<T>;
+declare function run<T, const TContexts extends readonly SourceContext<unknown>[]>(program: Program<"sync", T>, options: RunOptions & {
+  readonly contexts: TContexts;
+} & RejectEmptyContexts<TContexts> & ExtractRequiredOptions<TContexts, T>): T | Promise<T>;
+declare function run<T, const TContexts extends readonly SourceContext<unknown>[]>(program: Program<"async", T>, options: RunOptions & {
   readonly contexts: TContexts;
 } & RejectEmptyContexts<TContexts> & ExtractRequiredOptions<TContexts, T>): Promise<T>;
 declare function run<T, const TOptions extends RunOptions | undefined>(program: Program<"sync", T>, options?: TOptions & RejectContextfulOptions<TOptions> & RejectUnknownRunOptionKeys<TOptions>): T;

package/dist/run.d.ts

@@ -226,12 +226,32 @@ interface RunOptions {
    */
   readonly contexts?: readonly SourceContext<unknown>[];
 }
+/**
+ * Rejects context tuples that are statically known to be empty so those calls
+ * fall back to the synchronous no-context overloads.
+ */
 type RejectEmptyContexts<TContexts extends readonly SourceContext<unknown>[]> = TContexts extends readonly [] ? never : unknown;
+/**
+ * Represents a context tuple that is statically known to contain at least one
+ * source context.
+ */
 type NonEmptySourceContexts = readonly [SourceContext<unknown>, ...SourceContext<unknown>[]];
+/**
+ * Rejects option shapes that may carry a non-empty `contexts` array so plain
+ * Program overloads do not bypass the context-aware overloads.
+ */
 type RejectContextfulOptions<TOptions> = TOptions extends {
   readonly contexts?: infer TContexts extends readonly SourceContext<unknown>[] | undefined;
 } ? [TContexts] extends [undefined | readonly []] ? unknown : never : unknown;
+/**
+ * Rejects option shapes that introduce keys outside the public `RunOptions`
+ * contract, preserving excess-property checks for direct object literals.
+ */
 type RejectUnknownRunOptionKeys<TOptions> = [TOptions] extends [undefined] ? unknown : Exclude<keyof TOptions, keyof RunOptions> extends never ? unknown : never;
+/**
+ * Accepts only values typed exactly as `RunOptions`, which are widened to the
+ * conservative fallback overloads because they may hide context presence.
+ */
 type AcceptExactRunOptions<TOptions> = [TOptions] extends [RunOptions] ? [RunOptions] extends [TOptions] ? unknown : never : never;
 /**
  * Runs a command-line parser with automatic process integration.
@@ -304,7 +324,13 @@ declare function run<T extends Parser<Mode, unknown, unknown>, const TContexts e
 declare function run<T extends Parser<Mode, unknown, unknown>, const TContexts extends readonly SourceContext<unknown>[]>(parser: T, options: RunOptions & {
   readonly contexts: TContexts;
 } & RejectEmptyContexts<TContexts> & ExtractRequiredOptions<TContexts, InferValue<T>>): ModeValue<InferMode<T>, InferValue<T>> | Promise<InferValue<T>>;
-declare function run<M extends Mode, T, const TContexts extends readonly SourceContext<unknown>[]>(program: Program<M, T>, options: RunOptions & {
+declare function run<M extends Mode, T, const TContexts extends NonEmptySourceContexts>(program: Program<M, T>, options: RunOptions & {
+  readonly contexts: TContexts;
+} & ExtractRequiredOptions<TContexts, T>): Promise<T>;
+declare function run<T, const TContexts extends readonly SourceContext<unknown>[]>(program: Program<"sync", T>, options: RunOptions & {
+  readonly contexts: TContexts;
+} & RejectEmptyContexts<TContexts> & ExtractRequiredOptions<TContexts, T>): T | Promise<T>;
+declare function run<T, const TContexts extends readonly SourceContext<unknown>[]>(program: Program<"async", T>, options: RunOptions & {
   readonly contexts: TContexts;
 } & RejectEmptyContexts<TContexts> & ExtractRequiredOptions<TContexts, T>): Promise<T>;
 declare function run<T, const TOptions extends RunOptions | undefined>(program: Program<"sync", T>, options?: TOptions & RejectContextfulOptions<TOptions> & RejectUnknownRunOptionKeys<TOptions>): T;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/run",
-  "version": "1.0.0-dev.586+a66615c7",
+  "version": "1.0.0-dev.588+73f34b2e",
   "description": "Type-safe combinatorial command-line interface parser",
   "keywords": [
     "CLI",
@@ -70,7 +70,7 @@
   },
   "sideEffects": false,
   "dependencies": {
-    "@optique/core": "1.0.0-dev.586+a66615c7"
+    "@optique/core": "1.0.0-dev.588+73f34b2e"
   },
   "devDependencies": {
     "@types/node": "^20.19.9",