@optique/core 1.0.0-dev.908 → 1.0.0

package/dist/context.cjs

@@ -1,23 +0,0 @@
-
-//#region src/context.ts
-/**
-* Checks whether a context is static (returns annotations without needing
-* parsed results).
-*
-* A context is considered static if it declares `mode: "static"` or if
-* `getAnnotations()` called without arguments returns a non-empty
-* annotations object synchronously.
-*
-* @param context The source context to check.
-* @returns `true` if the context is static, `false` otherwise.
-* @since 0.10.0
-*/
-function isStaticContext(context) {
-	if (context.mode !== void 0) return context.mode === "static";
-	const result = context.getAnnotations();
-	if (result instanceof Promise) return false;
-	return Object.getOwnPropertySymbols(result).length > 0;
-}
-
-//#endregion
-exports.isStaticContext = isStaticContext;

package/dist/context.d.cts

@@ -1,18 +1,57 @@
-import { Annotations } from "./annotations.cjs";
+import { Annotations } from "./internal/annotations.cjs";
 
 //#region src/context.d.ts
 
 /**
- * Declares whether a {@link SourceContext} provides its annotations
- * immediately (`"static"`) or only after a prior parse pass (`"dynamic"`).
+ * Declares whether a {@link SourceContext} participates only in the initial
+ * annotation collection (`"single-pass"`) or is recollected after a usable
+ * first parse pass (`"two-pass"`).
  *
- * Used as the type of the optional `mode` field on {@link SourceContext}.
- * When set, {@link isStaticContext} reads this value directly instead of
- * calling `getAnnotations()`, preventing any side effects.
+ * Used as the type of the required `phase` field on {@link SourceContext}.
  *
  * @since 1.0.0
  */
-type SourceContextMode = "static" | "dynamic";
+type SourceContextPhase = "single-pass" | "two-pass";
+/**
+ * Phase-1 annotation collection request for a {@link SourceContext}.
+ *
+ * @since 1.0.0
+ */
+interface SourceContextPhase1Request {
+  /**
+   * Indicates that the runner is collecting initial annotations before the
+   * first parse pass.
+   */
+  readonly phase: "phase1";
+}
+/**
+ * Phase-2 annotation collection request for a {@link SourceContext}.
+ *
+ * @since 1.0.0
+ */
+interface SourceContextPhase2Request {
+  /**
+   * Indicates that the runner is recollecting annotations after a usable
+   * first parse pass.
+   */
+  readonly phase: "phase2";
+  /**
+   * Parsed result from the first pass, or a best-effort partial value
+   * extracted from parser state when the first pass reached a usable
+   * intermediate state but did not complete successfully.
+   */
+  readonly parsed: unknown;
+}
+/**
+ * Request object passed to {@link SourceContext.getAnnotations} and
+ * {@link SourceContext.getInternalAnnotations}.
+ *
+ * This makes phase 1 and phase 2 explicit so successful parser results of
+ * `undefined` are no longer ambiguous.
+ *
+ * @since 1.0.0
+ */
+type SourceContextRequest = SourceContextPhase1Request | SourceContextPhase2Request;
 /**
  * Brand symbol for ParserValuePlaceholder type.
  * @internal
@@ -50,16 +89,20 @@ type ParserValuePlaceholder = {
 /**
  * A source context that can provide data to parsers via annotations.
  *
- * Source contexts are used to inject external data (like environment variables
- * or config files) into the parsing process. They can be either:
+ * Source contexts are used to inject external data (like environment
+ * variables or config files) into the parsing process. They can be either:
  *
- * - *Static*: Data is immediately available (e.g., environment variables)
- * - *Dynamic*: Data depends on parsing results (e.g., config files whose path
- *   is determined by a CLI option)
+ * - *Single-pass*: The runner collects annotations once before parsing
+ *   (e.g., environment variables)
+ * - *Two-pass*: The runner collects annotations before parsing and then
+ *   recollects them after a usable first parse pass (e.g., config files whose
+ *   path is determined by a CLI option)
  *
  * Contexts may optionally implement `Disposable` or `AsyncDisposable` for
  * cleanup.  When present, `runWith()` and `runWithSync()` call the dispose
- * method in a `finally` block after parsing completes.
+ * method after parsing completes.  In async runners, cleanup waits for the
+ * full `runWith()` Promise to settle, including later asynchronous
+ * `complete()` work.
  *
  * @template TRequiredOptions Additional options that `runWith()` must provide
  *   when this context is used. Use `void` (the default) for contexts that
@@ -68,9 +111,10 @@ type ParserValuePlaceholder = {
  *
  * @example
  * ```typescript
- * // Static context example (environment variables) - no extra options needed
+ * // Single-pass context example (environment variables)
  * const envContext: SourceContext = {
  *   id: Symbol.for("@myapp/env"),
+ *   phase: "single-pass",
  *   getAnnotations() {
  *     return {
  *       [Symbol.for("@myapp/env")]: {
@@ -81,7 +125,7 @@ type ParserValuePlaceholder = {
  *   }
  * };
  *
- * // Dynamic context that requires options from runWith()
+ * // Two-pass context that requires options from runWith()
  * interface ConfigContext extends SourceContext<{
  *   getConfigPath: (parsed: ParserValuePlaceholder) => string | undefined;
  * }> {
@@ -96,7 +140,9 @@ interface SourceContext<TRequiredOptions = void> {
    * Unique identifier for this context.
    *
    * This symbol is typically the same as the annotation key used by parsers
-   * that consume this context's data.
+   * that consume this context's data.  Passing multiple contexts with the
+   * same id to {@link runWith}, {@link runWithSync}, or {@link runWithAsync}
+   * throws a `TypeError`.
    */
   readonly id: symbol;
   /**
@@ -105,65 +151,85 @@ interface SourceContext<TRequiredOptions = void> {
    */
   readonly $requiredOptions?: TRequiredOptions;
   /**
-   * Optional declaration of whether this context is static or dynamic.
+   * Declares whether this context is collected once or recollected after a
+   * usable first parse pass.
    *
-   * When present, {@link isStaticContext} reads this field directly instead
-   * of calling {@link getAnnotations}, avoiding any side effects that
-   * `getAnnotations` might have (such as mutating a global registry).
-   *
-   * If omitted, {@link isStaticContext} falls back to calling
-   * `getAnnotations()` with no arguments to determine static-ness.
+   * `single-pass` contexts contribute only their phase-1 annotations to the
+   * final parse. `two-pass` contexts are called again with the first-pass
+   * parsed value (or a best-effort seed extracted from parser state) and that
+   * second return value becomes the context's final annotation snapshot.
    *
    * @since 1.0.0
    */
-  readonly mode?: SourceContextMode;
+  readonly phase: SourceContextPhase;
   /**
    * Get annotations to inject into parsing.
    *
-   * This method is called twice during `runWith()` execution:
+   * This method is called during phase 1 for every context and during phase 2
+   * only for `two-pass` contexts:
+   *
+   * 1. *Phase 1*: `request.phase` is `"phase1"`.
+   * 2. *Phase 2*: `request.phase` is `"phase2"` and `request.parsed`
+   *    contains the first pass result, or a best-effort partial value
+   *    extracted from parser state when the first pass reached a usable
+   *    intermediate state but still did not complete successfully.
+   *    Deferred or otherwise unresolved fields may be `undefined`. 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.
    *
-   * 1. *First call*: `parsed` is `undefined`. Static contexts should return
-   *    their annotations, while dynamic contexts should return an empty object.
-   * 2. *Second call*: `parsed` contains the result from the first parse pass.
-   *    Dynamic contexts can use this to load external data (e.g., reading
-   *    a config file whose path was determined in the first pass).
+   * Omitting the request is treated as a manual phase-1 call for
+   * convenience, so `context.getAnnotations()` continues to work for
+   * simple one-shot annotation reads.
    *
-   * @param parsed Optional parsed result from a previous parse pass.
-   *               Static contexts can ignore this parameter.
-   *               Dynamic contexts use this to extract necessary data.
+   * @param request Optional request describing which collection phase the
+   *                runner is performing. `single-pass` contexts can ignore
+   *                this parameter. `two-pass` contexts should branch on
+   *                `request.phase` rather than inferring phases from
+   *                `request.parsed`.
    * @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(request?: SourceContextRequest, options?: unknown): Promise<Annotations> | Annotations;
+  /**
+   * Optional hook to provide additional internal annotations during
+   * annotation collection.  Called after {@link getAnnotations} with the
+   * same request object and the annotations returned by `getAnnotations()`.
+   *
+   * Returns additional annotations to merge, or `undefined` to add nothing.
+   * This enables contexts to inject phase-specific markers without
+   * exposing them through the primary `getAnnotations()` API.
+   *
+   * @param request The request describing the current collection phase.
+   * @param annotations The annotations returned by `getAnnotations()`.
+   * @returns Additional annotations to merge, or `undefined`.
+   * @since 1.0.0
    */
-  getAnnotations(parsed?: unknown, options?: unknown): Promise<Annotations> | Annotations;
+  getInternalAnnotations?(request: SourceContextRequest, annotations: Annotations): Annotations | undefined;
   /**
    * Optional synchronous cleanup method.  Called by `runWith()` and
-   * `runWithSync()` in a `finally` block after parsing completes.
+   * `runWithSync()` after parsing completes.  In `runWith()`, this happens
+   * only after the full Promise settles, including any later async
+   * `complete()` work.
    */
   [Symbol.dispose]?(): void;
   /**
-   * Optional asynchronous cleanup method.  Called by `runWith()` in a
-   * `finally` block after parsing completes.  Takes precedence over
+   * Optional asynchronous cleanup method.  Called by `runWith()` after
+   * parsing completes.  Cleanup starts only after the full `runWith()`
+   * Promise settles, including any later async `complete()` work.  Takes
+   * precedence over
    * `[Symbol.dispose]` in async runners.  `runWithSync()` also calls this
    * method when `[Symbol.dispose]` is absent, but throws if it returns a
    * Promise.
    */
   [Symbol.asyncDispose]?(): void | PromiseLike<void>;
 }
-/**
- * Checks whether a context is static (returns annotations without needing
- * parsed results).
- *
- * A context is considered static if it declares `mode: "static"` or if
- * `getAnnotations()` called without arguments returns a non-empty
- * annotations object synchronously.
- *
- * @param context The source context to check.
- * @returns `true` if the context is static, `false` otherwise.
- * @since 0.10.0
- */
-declare function isStaticContext(context: SourceContext<unknown>): boolean;
 //#endregion
-export { type Annotations, ParserValuePlaceholder, SourceContext, SourceContextMode, isStaticContext };
+export { type Annotations, ParserValuePlaceholder, SourceContext, SourceContextPhase, SourceContextPhase1Request, SourceContextPhase2Request, SourceContextRequest };

package/dist/context.d.ts

@@ -1,18 +1,57 @@
-import { Annotations } from "./annotations.js";
+import { Annotations } from "./internal/annotations.js";
 
 //#region src/context.d.ts
 
 /**
- * Declares whether a {@link SourceContext} provides its annotations
- * immediately (`"static"`) or only after a prior parse pass (`"dynamic"`).
+ * Declares whether a {@link SourceContext} participates only in the initial
+ * annotation collection (`"single-pass"`) or is recollected after a usable
+ * first parse pass (`"two-pass"`).
  *
- * Used as the type of the optional `mode` field on {@link SourceContext}.
- * When set, {@link isStaticContext} reads this value directly instead of
- * calling `getAnnotations()`, preventing any side effects.
+ * Used as the type of the required `phase` field on {@link SourceContext}.
  *
  * @since 1.0.0
  */
-type SourceContextMode = "static" | "dynamic";
+type SourceContextPhase = "single-pass" | "two-pass";
+/**
+ * Phase-1 annotation collection request for a {@link SourceContext}.
+ *
+ * @since 1.0.0
+ */
+interface SourceContextPhase1Request {
+  /**
+   * Indicates that the runner is collecting initial annotations before the
+   * first parse pass.
+   */
+  readonly phase: "phase1";
+}
+/**
+ * Phase-2 annotation collection request for a {@link SourceContext}.
+ *
+ * @since 1.0.0
+ */
+interface SourceContextPhase2Request {
+  /**
+   * Indicates that the runner is recollecting annotations after a usable
+   * first parse pass.
+   */
+  readonly phase: "phase2";
+  /**
+   * Parsed result from the first pass, or a best-effort partial value
+   * extracted from parser state when the first pass reached a usable
+   * intermediate state but did not complete successfully.
+   */
+  readonly parsed: unknown;
+}
+/**
+ * Request object passed to {@link SourceContext.getAnnotations} and
+ * {@link SourceContext.getInternalAnnotations}.
+ *
+ * This makes phase 1 and phase 2 explicit so successful parser results of
+ * `undefined` are no longer ambiguous.
+ *
+ * @since 1.0.0
+ */
+type SourceContextRequest = SourceContextPhase1Request | SourceContextPhase2Request;
 /**
  * Brand symbol for ParserValuePlaceholder type.
  * @internal
@@ -50,16 +89,20 @@ type ParserValuePlaceholder = {
 /**
  * A source context that can provide data to parsers via annotations.
  *
- * Source contexts are used to inject external data (like environment variables
- * or config files) into the parsing process. They can be either:
+ * Source contexts are used to inject external data (like environment
+ * variables or config files) into the parsing process. They can be either:
  *
- * - *Static*: Data is immediately available (e.g., environment variables)
- * - *Dynamic*: Data depends on parsing results (e.g., config files whose path
- *   is determined by a CLI option)
+ * - *Single-pass*: The runner collects annotations once before parsing
+ *   (e.g., environment variables)
+ * - *Two-pass*: The runner collects annotations before parsing and then
+ *   recollects them after a usable first parse pass (e.g., config files whose
+ *   path is determined by a CLI option)
  *
  * Contexts may optionally implement `Disposable` or `AsyncDisposable` for
  * cleanup.  When present, `runWith()` and `runWithSync()` call the dispose
- * method in a `finally` block after parsing completes.
+ * method after parsing completes.  In async runners, cleanup waits for the
+ * full `runWith()` Promise to settle, including later asynchronous
+ * `complete()` work.
  *
  * @template TRequiredOptions Additional options that `runWith()` must provide
  *   when this context is used. Use `void` (the default) for contexts that
@@ -68,9 +111,10 @@ type ParserValuePlaceholder = {
  *
  * @example
  * ```typescript
- * // Static context example (environment variables) - no extra options needed
+ * // Single-pass context example (environment variables)
  * const envContext: SourceContext = {
  *   id: Symbol.for("@myapp/env"),
+ *   phase: "single-pass",
  *   getAnnotations() {
  *     return {
  *       [Symbol.for("@myapp/env")]: {
@@ -81,7 +125,7 @@ type ParserValuePlaceholder = {
  *   }
  * };
  *
- * // Dynamic context that requires options from runWith()
+ * // Two-pass context that requires options from runWith()
  * interface ConfigContext extends SourceContext<{
  *   getConfigPath: (parsed: ParserValuePlaceholder) => string | undefined;
  * }> {
@@ -96,7 +140,9 @@ interface SourceContext<TRequiredOptions = void> {
    * Unique identifier for this context.
    *
    * This symbol is typically the same as the annotation key used by parsers
-   * that consume this context's data.
+   * that consume this context's data.  Passing multiple contexts with the
+   * same id to {@link runWith}, {@link runWithSync}, or {@link runWithAsync}
+   * throws a `TypeError`.
    */
   readonly id: symbol;
   /**
@@ -105,65 +151,85 @@ interface SourceContext<TRequiredOptions = void> {
    */
   readonly $requiredOptions?: TRequiredOptions;
   /**
-   * Optional declaration of whether this context is static or dynamic.
+   * Declares whether this context is collected once or recollected after a
+   * usable first parse pass.
    *
-   * When present, {@link isStaticContext} reads this field directly instead
-   * of calling {@link getAnnotations}, avoiding any side effects that
-   * `getAnnotations` might have (such as mutating a global registry).
-   *
-   * If omitted, {@link isStaticContext} falls back to calling
-   * `getAnnotations()` with no arguments to determine static-ness.
+   * `single-pass` contexts contribute only their phase-1 annotations to the
+   * final parse. `two-pass` contexts are called again with the first-pass
+   * parsed value (or a best-effort seed extracted from parser state) and that
+   * second return value becomes the context's final annotation snapshot.
    *
    * @since 1.0.0
    */
-  readonly mode?: SourceContextMode;
+  readonly phase: SourceContextPhase;
   /**
    * Get annotations to inject into parsing.
    *
-   * This method is called twice during `runWith()` execution:
+   * This method is called during phase 1 for every context and during phase 2
+   * only for `two-pass` contexts:
+   *
+   * 1. *Phase 1*: `request.phase` is `"phase1"`.
+   * 2. *Phase 2*: `request.phase` is `"phase2"` and `request.parsed`
+   *    contains the first pass result, or a best-effort partial value
+   *    extracted from parser state when the first pass reached a usable
+   *    intermediate state but still did not complete successfully.
+   *    Deferred or otherwise unresolved fields may be `undefined`. 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.
    *
-   * 1. *First call*: `parsed` is `undefined`. Static contexts should return
-   *    their annotations, while dynamic contexts should return an empty object.
-   * 2. *Second call*: `parsed` contains the result from the first parse pass.
-   *    Dynamic contexts can use this to load external data (e.g., reading
-   *    a config file whose path was determined in the first pass).
+   * Omitting the request is treated as a manual phase-1 call for
+   * convenience, so `context.getAnnotations()` continues to work for
+   * simple one-shot annotation reads.
    *
-   * @param parsed Optional parsed result from a previous parse pass.
-   *               Static contexts can ignore this parameter.
-   *               Dynamic contexts use this to extract necessary data.
+   * @param request Optional request describing which collection phase the
+   *                runner is performing. `single-pass` contexts can ignore
+   *                this parameter. `two-pass` contexts should branch on
+   *                `request.phase` rather than inferring phases from
+   *                `request.parsed`.
    * @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(request?: SourceContextRequest, options?: unknown): Promise<Annotations> | Annotations;
+  /**
+   * Optional hook to provide additional internal annotations during
+   * annotation collection.  Called after {@link getAnnotations} with the
+   * same request object and the annotations returned by `getAnnotations()`.
+   *
+   * Returns additional annotations to merge, or `undefined` to add nothing.
+   * This enables contexts to inject phase-specific markers without
+   * exposing them through the primary `getAnnotations()` API.
+   *
+   * @param request The request describing the current collection phase.
+   * @param annotations The annotations returned by `getAnnotations()`.
+   * @returns Additional annotations to merge, or `undefined`.
+   * @since 1.0.0
    */
-  getAnnotations(parsed?: unknown, options?: unknown): Promise<Annotations> | Annotations;
+  getInternalAnnotations?(request: SourceContextRequest, annotations: Annotations): Annotations | undefined;
   /**
    * Optional synchronous cleanup method.  Called by `runWith()` and
-   * `runWithSync()` in a `finally` block after parsing completes.
+   * `runWithSync()` after parsing completes.  In `runWith()`, this happens
+   * only after the full Promise settles, including any later async
+   * `complete()` work.
    */
   [Symbol.dispose]?(): void;
   /**
-   * Optional asynchronous cleanup method.  Called by `runWith()` in a
-   * `finally` block after parsing completes.  Takes precedence over
+   * Optional asynchronous cleanup method.  Called by `runWith()` after
+   * parsing completes.  Cleanup starts only after the full `runWith()`
+   * Promise settles, including any later async `complete()` work.  Takes
+   * precedence over
    * `[Symbol.dispose]` in async runners.  `runWithSync()` also calls this
    * method when `[Symbol.dispose]` is absent, but throws if it returns a
    * Promise.
    */
   [Symbol.asyncDispose]?(): void | PromiseLike<void>;
 }
-/**
- * Checks whether a context is static (returns annotations without needing
- * parsed results).
- *
- * A context is considered static if it declares `mode: "static"` or if
- * `getAnnotations()` called without arguments returns a non-empty
- * annotations object synchronously.
- *
- * @param context The source context to check.
- * @returns `true` if the context is static, `false` otherwise.
- * @since 0.10.0
- */
-declare function isStaticContext(context: SourceContext<unknown>): boolean;
 //#endregion
-export { type Annotations, ParserValuePlaceholder, SourceContext, SourceContextMode, isStaticContext };
+export { type Annotations, ParserValuePlaceholder, SourceContext, SourceContextPhase, SourceContextPhase1Request, SourceContextPhase2Request, SourceContextRequest };

package/dist/context.js

@@ -1,22 +0,0 @@
-//#region src/context.ts
-/**
-* Checks whether a context is static (returns annotations without needing
-* parsed results).
-*
-* A context is considered static if it declares `mode: "static"` or if
-* `getAnnotations()` called without arguments returns a non-empty
-* annotations object synchronously.
-*
-* @param context The source context to check.
-* @returns `true` if the context is static, `false` otherwise.
-* @since 0.10.0
-*/
-function isStaticContext(context) {
-	if (context.mode !== void 0) return context.mode === "static";
-	const result = context.getAnnotations();
-	if (result instanceof Promise) return false;
-	return Object.getOwnPropertySymbols(result).length > 0;
-}
-
-//#endregion
-export { isStaticContext };