@optique/core 1.0.0-dev.1798 → 1.0.0-dev.1801

package/dist/context.d.cts

@@ -132,8 +132,11 @@ interface SourceContext<TRequiredOptions = void> {
    *    successfully. Dynamic contexts can use this to load external data
    *    (e.g., reading a config file whose path was determined in the first
    *    pass). Deferred or otherwise unresolved fields may be `undefined`.
-   *    If the runner cannot extract a usable value at all, this second call
-   *    is skipped and the original parse failure is reported instead.
+   *    This second return value is treated as the context's final annotation
+   *    snapshot for the second parse pass, replacing that context's phase-one
+   *    contribution. If the runner cannot extract a usable value at all, this
+   *    second call is skipped and the original parse failure is reported
+   *    instead.
    *
    * @param parsed Optional parsed result from a previous parse pass.
    *               Static contexts can ignore this parameter.
@@ -141,8 +144,10 @@ interface SourceContext<TRequiredOptions = void> {
    * @param options Optional context-required options provided by the caller
    *               of `runWith()`. These are the options declared via the
    *               `TRequiredOptions` type parameter.
-   * @returns Annotations to merge into the parsing session. Can be a Promise
-   *          for async operations (e.g., loading config files).
+   * @returns Annotations to merge into the parsing session. During phase 2,
+   *          returning `{}` clears any annotations this context contributed
+   *          during phase 1. Can be a Promise for async operations (e.g.,
+   *          loading config files).
    */
   getAnnotations(parsed?: unknown, options?: unknown): Promise<Annotations> | Annotations;
   /**

package/dist/context.d.ts

@@ -132,8 +132,11 @@ interface SourceContext<TRequiredOptions = void> {
    *    successfully. Dynamic contexts can use this to load external data
    *    (e.g., reading a config file whose path was determined in the first
    *    pass). Deferred or otherwise unresolved fields may be `undefined`.
-   *    If the runner cannot extract a usable value at all, this second call
-   *    is skipped and the original parse failure is reported instead.
+   *    This second return value is treated as the context's final annotation
+   *    snapshot for the second parse pass, replacing that context's phase-one
+   *    contribution. If the runner cannot extract a usable value at all, this
+   *    second call is skipped and the original parse failure is reported
+   *    instead.
    *
    * @param parsed Optional parsed result from a previous parse pass.
    *               Static contexts can ignore this parameter.
@@ -141,8 +144,10 @@ interface SourceContext<TRequiredOptions = void> {
    * @param options Optional context-required options provided by the caller
    *               of `runWith()`. These are the options declared via the
    *               `TRequiredOptions` type parameter.
-   * @returns Annotations to merge into the parsing session. Can be a Promise
-   *          for async operations (e.g., loading config files).
+   * @returns Annotations to merge into the parsing session. During phase 2,
+   *          returning `{}` clears any annotations this context contributed
+   *          during phase 1. Can be a Promise for async operations (e.g.,
+   *          loading config files).
    */
   getAnnotations(parsed?: unknown, options?: unknown): Promise<Annotations> | Annotations;
   /**

package/dist/facade.cjs

@@ -1101,7 +1101,6 @@ async function collectPhase1Annotations(contexts, options) {
 	}
 	return {
 		annotations: mergeAnnotations(annotationsList),
-		annotationsList,
 		hasDynamic
 	};
 }
@@ -1125,10 +1124,7 @@ async function collectAnnotations(contexts, parsed, options, deferred, deferredK
 		});
 		annotationsList.push(mergedAnnotations);
 	}
-	return {
-		annotations: mergeAnnotations(annotationsList),
-		annotationsList
-	};
+	return { annotations: mergeAnnotations(annotationsList) };
 }
 /**
 * Collects phase 1 annotations from all contexts synchronously and determines
@@ -1151,7 +1147,6 @@ function collectPhase1AnnotationsSync(contexts, options) {
 	}
 	return {
 		annotations: mergeAnnotations(annotationsList),
-		annotationsList,
 		hasDynamic
 	};
 }
@@ -1188,16 +1183,7 @@ function collectAnnotationsSync(contexts, parsed, options, deferred, deferredKey
 		});
 		annotationsList.push(mergedAnnotations);
 	}
-	return {
-		annotations: mergeAnnotations(annotationsList),
-		annotationsList
-	};
-}
-function mergeTwoPhaseAnnotations(phase1AnnotationsList, phase2AnnotationsList) {
-	const mergedPerContext = [];
-	const length = Math.max(phase1AnnotationsList.length, phase2AnnotationsList.length);
-	for (let i = 0; i < length; i++) mergedPerContext.push(mergeAnnotations([phase2AnnotationsList[i] ?? {}, phase1AnnotationsList[i] ?? {}]));
-	return mergeAnnotations(mergedPerContext);
+	return { annotations: mergeAnnotations(annotationsList) };
 }
 /**
 * Disposes all contexts that implement `AsyncDisposable` or `Disposable`.
@@ -1247,7 +1233,7 @@ async function runWithBody(parser, programName, contexts, args, options) {
 		return Promise.resolve(runParser(parser, programName, args, options));
 	}
 	const ctxOptions = options.contextOptions;
-	const { annotations: phase1Annotations, annotationsList: phase1AnnotationsList, hasDynamic: needsTwoPhase } = await collectPhase1Annotations(contexts, ctxOptions);
+	const { annotations: phase1Annotations, hasDynamic: needsTwoPhase } = await collectPhase1Annotations(contexts, ctxOptions);
 	if (!needsTwoPhase) {
 		const augmentedParser = injectAnnotationsIntoParser(parser, phase1Annotations);
 		if (parser.$mode === "async") return runParser(augmentedParser, programName, args, options);
@@ -1260,8 +1246,7 @@ async function runWithBody(parser, programName, contexts, args, options) {
 		if (parser.$mode === "async") return runParser(augmentedParser, programName, args, options);
 		return Promise.resolve(runParser(augmentedParser, programName, args, options));
 	}
-	const { annotationsList: phase2AnnotationsList } = await collectAnnotations(contexts, firstPassSeed.value, ctxOptions, firstPassSeed.deferred, firstPassSeed.deferredKeys);
-	const finalAnnotations = mergeTwoPhaseAnnotations(phase1AnnotationsList, phase2AnnotationsList);
+	const { annotations: finalAnnotations } = await collectAnnotations(contexts, firstPassSeed.value, ctxOptions, firstPassSeed.deferred, firstPassSeed.deferredKeys);
 	const augmentedParser2 = injectAnnotationsIntoParser(parser, finalAnnotations);
 	if (parser.$mode === "async") return runParser(augmentedParser2, programName, args, options);
 	return Promise.resolve(runParser(augmentedParser2, programName, args, options));
@@ -1283,8 +1268,10 @@ async function runWithBody(parser, programName, contexts, args, options) {
 *    instead.
 * 3. *Phase 2*: Call `getAnnotations(parsed)` on all contexts with the first
 *    pass value. Deferred or otherwise unresolved fields in `parsed` may be
-*    `undefined`.
-* 4. *Second parse*: Parse again with merged annotations from both phases.
+*    `undefined`. Each 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.
+* 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. Phase 2 is also skipped when the first pass does
@@ -1357,7 +1344,7 @@ function runWithSyncBody(parser, programName, contexts, args, options) {
 	require_validate.validateContextIds(contexts);
 	if (needsEarlyExit(args, options)) return runParser(parser, programName, args, options);
 	const ctxOptions = options.contextOptions;
-	const { annotations: phase1Annotations, annotationsList: phase1AnnotationsList, hasDynamic: needsTwoPhase } = collectPhase1AnnotationsSync(contexts, ctxOptions);
+	const { annotations: phase1Annotations, hasDynamic: needsTwoPhase } = collectPhase1AnnotationsSync(contexts, ctxOptions);
 	if (!needsTwoPhase) {
 		const augmentedParser = injectAnnotationsIntoParser(parser, phase1Annotations);
 		return runParser(augmentedParser, programName, args, options);
@@ -1368,8 +1355,7 @@ function runWithSyncBody(parser, programName, contexts, args, options) {
 		const augmentedParser = injectAnnotationsIntoParser(parser, phase1Annotations);
 		return runParser(augmentedParser, programName, args, options);
 	}
-	const { annotationsList: phase2AnnotationsList } = collectAnnotationsSync(contexts, firstPassSeed.value, ctxOptions, firstPassSeed.deferred, firstPassSeed.deferredKeys);
-	const finalAnnotations = mergeTwoPhaseAnnotations(phase1AnnotationsList, phase2AnnotationsList);
+	const { annotations: finalAnnotations } = collectAnnotationsSync(contexts, firstPassSeed.value, ctxOptions, firstPassSeed.deferred, firstPassSeed.deferredKeys);
 	const augmentedParser2 = injectAnnotationsIntoParser(parser, finalAnnotations);
 	return runParser(augmentedParser2, programName, args, options);
 }
@@ -1379,7 +1365,9 @@ function runWithSyncBody(parser, programName, contexts, args, options) {
 * This is the sync-only variant of {@link runWith}. All contexts must return
 * annotations synchronously (not Promises). It uses the same two-phase
 * best-effort seed extraction as {@link runWith} when dynamic contexts are
-* present.
+* present. In two-phase runs, each 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.

package/dist/facade.d.cts

@@ -419,8 +419,10 @@ type ContextOptionsParam<TContexts extends readonly SourceContext<unknown>[], TV
  *    instead.
  * 3. *Phase 2*: Call `getAnnotations(parsed)` on all contexts with the first
  *    pass value. Deferred or otherwise unresolved fields in `parsed` may be
- *    `undefined`.
- * 4. *Second parse*: Parse again with merged annotations from both phases.
+ *    `undefined`. Each 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.
+ * 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. Phase 2 is also skipped when the first pass does
@@ -468,7 +470,9 @@ declare function runWith<TParser extends Parser<Mode, unknown, unknown>, TContex
  * This is the sync-only variant of {@link runWith}. All contexts must return
  * annotations synchronously (not Promises). It uses the same two-phase
  * best-effort seed extraction as {@link runWith} when dynamic contexts are
- * present.
+ * present. In two-phase runs, each 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.

package/dist/facade.d.ts

@@ -419,8 +419,10 @@ type ContextOptionsParam<TContexts extends readonly SourceContext<unknown>[], TV
  *    instead.
  * 3. *Phase 2*: Call `getAnnotations(parsed)` on all contexts with the first
  *    pass value. Deferred or otherwise unresolved fields in `parsed` may be
- *    `undefined`.
- * 4. *Second parse*: Parse again with merged annotations from both phases.
+ *    `undefined`. Each 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.
+ * 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. Phase 2 is also skipped when the first pass does
@@ -468,7 +470,9 @@ declare function runWith<TParser extends Parser<Mode, unknown, unknown>, TContex
  * This is the sync-only variant of {@link runWith}. All contexts must return
  * annotations synchronously (not Promises). It uses the same two-phase
  * best-effort seed extraction as {@link runWith} when dynamic contexts are
- * present.
+ * present. In two-phase runs, each 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.

package/dist/facade.js

@@ -1101,7 +1101,6 @@ async function collectPhase1Annotations(contexts, options) {
 	}
 	return {
 		annotations: mergeAnnotations(annotationsList),
-		annotationsList,
 		hasDynamic
 	};
 }
@@ -1125,10 +1124,7 @@ async function collectAnnotations(contexts, parsed, options, deferred, deferredK
 		});
 		annotationsList.push(mergedAnnotations);
 	}
-	return {
-		annotations: mergeAnnotations(annotationsList),
-		annotationsList
-	};
+	return { annotations: mergeAnnotations(annotationsList) };
 }
 /**
 * Collects phase 1 annotations from all contexts synchronously and determines
@@ -1151,7 +1147,6 @@ function collectPhase1AnnotationsSync(contexts, options) {
 	}
 	return {
 		annotations: mergeAnnotations(annotationsList),
-		annotationsList,
 		hasDynamic
 	};
 }
@@ -1188,16 +1183,7 @@ function collectAnnotationsSync(contexts, parsed, options, deferred, deferredKey
 		});
 		annotationsList.push(mergedAnnotations);
 	}
-	return {
-		annotations: mergeAnnotations(annotationsList),
-		annotationsList
-	};
-}
-function mergeTwoPhaseAnnotations(phase1AnnotationsList, phase2AnnotationsList) {
-	const mergedPerContext = [];
-	const length = Math.max(phase1AnnotationsList.length, phase2AnnotationsList.length);
-	for (let i = 0; i < length; i++) mergedPerContext.push(mergeAnnotations([phase2AnnotationsList[i] ?? {}, phase1AnnotationsList[i] ?? {}]));
-	return mergeAnnotations(mergedPerContext);
+	return { annotations: mergeAnnotations(annotationsList) };
 }
 /**
 * Disposes all contexts that implement `AsyncDisposable` or `Disposable`.
@@ -1247,7 +1233,7 @@ async function runWithBody(parser, programName, contexts, args, options) {
 		return Promise.resolve(runParser(parser, programName, args, options));
 	}
 	const ctxOptions = options.contextOptions;
-	const { annotations: phase1Annotations, annotationsList: phase1AnnotationsList, hasDynamic: needsTwoPhase } = await collectPhase1Annotations(contexts, ctxOptions);
+	const { annotations: phase1Annotations, hasDynamic: needsTwoPhase } = await collectPhase1Annotations(contexts, ctxOptions);
 	if (!needsTwoPhase) {
 		const augmentedParser = injectAnnotationsIntoParser(parser, phase1Annotations);
 		if (parser.$mode === "async") return runParser(augmentedParser, programName, args, options);
@@ -1260,8 +1246,7 @@ async function runWithBody(parser, programName, contexts, args, options) {
 		if (parser.$mode === "async") return runParser(augmentedParser, programName, args, options);
 		return Promise.resolve(runParser(augmentedParser, programName, args, options));
 	}
-	const { annotationsList: phase2AnnotationsList } = await collectAnnotations(contexts, firstPassSeed.value, ctxOptions, firstPassSeed.deferred, firstPassSeed.deferredKeys);
-	const finalAnnotations = mergeTwoPhaseAnnotations(phase1AnnotationsList, phase2AnnotationsList);
+	const { annotations: finalAnnotations } = await collectAnnotations(contexts, firstPassSeed.value, ctxOptions, firstPassSeed.deferred, firstPassSeed.deferredKeys);
 	const augmentedParser2 = injectAnnotationsIntoParser(parser, finalAnnotations);
 	if (parser.$mode === "async") return runParser(augmentedParser2, programName, args, options);
 	return Promise.resolve(runParser(augmentedParser2, programName, args, options));
@@ -1283,8 +1268,10 @@ async function runWithBody(parser, programName, contexts, args, options) {
 *    instead.
 * 3. *Phase 2*: Call `getAnnotations(parsed)` on all contexts with the first
 *    pass value. Deferred or otherwise unresolved fields in `parsed` may be
-*    `undefined`.
-* 4. *Second parse*: Parse again with merged annotations from both phases.
+*    `undefined`. Each 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.
+* 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. Phase 2 is also skipped when the first pass does
@@ -1357,7 +1344,7 @@ function runWithSyncBody(parser, programName, contexts, args, options) {
 	validateContextIds(contexts);
 	if (needsEarlyExit(args, options)) return runParser(parser, programName, args, options);
 	const ctxOptions = options.contextOptions;
-	const { annotations: phase1Annotations, annotationsList: phase1AnnotationsList, hasDynamic: needsTwoPhase } = collectPhase1AnnotationsSync(contexts, ctxOptions);
+	const { annotations: phase1Annotations, hasDynamic: needsTwoPhase } = collectPhase1AnnotationsSync(contexts, ctxOptions);
 	if (!needsTwoPhase) {
 		const augmentedParser = injectAnnotationsIntoParser(parser, phase1Annotations);
 		return runParser(augmentedParser, programName, args, options);
@@ -1368,8 +1355,7 @@ function runWithSyncBody(parser, programName, contexts, args, options) {
 		const augmentedParser = injectAnnotationsIntoParser(parser, phase1Annotations);
 		return runParser(augmentedParser, programName, args, options);
 	}
-	const { annotationsList: phase2AnnotationsList } = collectAnnotationsSync(contexts, firstPassSeed.value, ctxOptions, firstPassSeed.deferred, firstPassSeed.deferredKeys);
-	const finalAnnotations = mergeTwoPhaseAnnotations(phase1AnnotationsList, phase2AnnotationsList);
+	const { annotations: finalAnnotations } = collectAnnotationsSync(contexts, firstPassSeed.value, ctxOptions, firstPassSeed.deferred, firstPassSeed.deferredKeys);
 	const augmentedParser2 = injectAnnotationsIntoParser(parser, finalAnnotations);
 	return runParser(augmentedParser2, programName, args, options);
 }
@@ -1379,7 +1365,9 @@ function runWithSyncBody(parser, programName, contexts, args, options) {
 * This is the sync-only variant of {@link runWith}. All contexts must return
 * annotations synchronously (not Promises). It uses the same two-phase
 * best-effort seed extraction as {@link runWith} when dynamic contexts are
-* present.
+* present. In two-phase runs, each 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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/core",
-  "version": "1.0.0-dev.1798+d306f46e",
+  "version": "1.0.0-dev.1801+3b666460",
   "description": "Type-safe combinatorial command-line interface parser",
   "keywords": [
     "CLI",