@optique/core 1.0.0-dev.1681 → 1.0.0-dev.1684

package/dist/facade.cjs

@@ -12,6 +12,19 @@ const require_parser = require('./parser.cjs');
 const require_constructs = require('./constructs.cjs');
 
 //#region src/facade.ts
+const SuppressedErrorCtor = typeof SuppressedError === "function" ? SuppressedError : (() => {
+	class SuppressedErrorPolyfill extends Error {
+		error;
+		suppressed;
+		constructor(error, suppressed, message$1) {
+			super(message$1);
+			this.name = "SuppressedError";
+			this.error = error;
+			this.suppressed = suppressed;
+		}
+	}
+	return SuppressedErrorPolyfill;
+})();
 function finalizeParsedForContext(context, parsed) {
 	return context.finalizeParsed != null ? context.finalizeParsed(parsed) : parsed;
 }
@@ -1216,57 +1229,104 @@ function disposeContextsSync(contexts) {
 * );
 * ```
 */
+async function runWithBody(parser, programName, contexts, args, options) {
+	require_validate.validateContextIds(contexts);
+	if (needsEarlyExit(args, options)) {
+		if (parser.$mode === "async") return runParser(parser, programName, 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);
+	if (!needsTwoPhase) {
+		const augmentedParser = injectAnnotationsIntoParser(parser, phase1Annotations);
+		if (parser.$mode === "async") return runParser(augmentedParser, programName, args, options);
+		return Promise.resolve(runParser(augmentedParser, programName, args, options));
+	}
+	const augmentedParser1 = injectAnnotationsIntoParser(parser, phase1Annotations);
+	let firstPassResult;
+	let firstPassDeferred;
+	let firstPassDeferredKeys;
+	let firstPassFailed = false;
+	try {
+		if (parser.$mode === "async") firstPassResult = await require_parser.parseAsync(augmentedParser1, args);
+		else firstPassResult = require_parser.parseSync(augmentedParser1, args);
+		if (typeof firstPassResult === "object" && firstPassResult !== null && "success" in firstPassResult) {
+			const result = firstPassResult;
+			if (result.success) {
+				firstPassResult = result.value;
+				firstPassDeferred = result.deferred;
+				firstPassDeferredKeys = result.deferredKeys;
+			} else firstPassFailed = true;
+		}
+	} catch {
+		firstPassFailed = true;
+	}
+	if (firstPassFailed) {
+		const augmentedParser = injectAnnotationsIntoParser(parser, phase1Annotations);
+		if (parser.$mode === "async") return runParser(augmentedParser, programName, args, options);
+		return Promise.resolve(runParser(augmentedParser, programName, args, options));
+	}
+	const { annotationsList: phase2AnnotationsList } = await collectAnnotations(contexts, firstPassResult, ctxOptions, firstPassDeferred, firstPassDeferredKeys);
+	const finalAnnotations = mergeTwoPhaseAnnotations(phase1AnnotationsList, phase2AnnotationsList);
+	const augmentedParser2 = injectAnnotationsIntoParser(parser, finalAnnotations);
+	if (parser.$mode === "async") return runParser(augmentedParser2, programName, args, options);
+	return Promise.resolve(runParser(augmentedParser2, programName, args, options));
+}
 async function runWith(parser, programName, contexts, options) {
 	const args = options?.args ?? [];
 	if (contexts.length === 0) {
 		if (parser.$mode === "async") return runParser(parser, programName, args, options);
 		return Promise.resolve(runParser(parser, programName, args, options));
 	}
+	let result;
+	let primaryError;
+	let hasPrimaryError = false;
+	try {
+		result = await runWithBody(parser, programName, contexts, args, options);
+	} catch (error) {
+		hasPrimaryError = true;
+		primaryError = error;
+	}
 	try {
-		require_validate.validateContextIds(contexts);
-		if (needsEarlyExit(args, options)) {
-			if (parser.$mode === "async") return runParser(parser, programName, 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);
-		if (!needsTwoPhase) {
-			const augmentedParser = injectAnnotationsIntoParser(parser, phase1Annotations);
-			if (parser.$mode === "async") return runParser(augmentedParser, programName, args, options);
-			return Promise.resolve(runParser(augmentedParser, programName, args, options));
-		}
-		const augmentedParser1 = injectAnnotationsIntoParser(parser, phase1Annotations);
-		let firstPassResult;
-		let firstPassDeferred;
-		let firstPassDeferredKeys;
-		let firstPassFailed = false;
-		try {
-			if (parser.$mode === "async") firstPassResult = await require_parser.parseAsync(augmentedParser1, args);
-			else firstPassResult = require_parser.parseSync(augmentedParser1, args);
-			if (typeof firstPassResult === "object" && firstPassResult !== null && "success" in firstPassResult) {
-				const result = firstPassResult;
-				if (result.success) {
-					firstPassResult = result.value;
-					firstPassDeferred = result.deferred;
-					firstPassDeferredKeys = result.deferredKeys;
-				} else firstPassFailed = true;
-			}
-		} catch {
-			firstPassFailed = true;
-		}
-		if (firstPassFailed) {
-			const augmentedParser = injectAnnotationsIntoParser(parser, phase1Annotations);
-			if (parser.$mode === "async") return runParser(augmentedParser, programName, args, options);
-			return Promise.resolve(runParser(augmentedParser, programName, args, options));
-		}
-		const { annotationsList: phase2AnnotationsList } = await collectAnnotations(contexts, firstPassResult, ctxOptions, firstPassDeferred, firstPassDeferredKeys);
-		const finalAnnotations = mergeTwoPhaseAnnotations(phase1AnnotationsList, phase2AnnotationsList);
-		const augmentedParser2 = injectAnnotationsIntoParser(parser, finalAnnotations);
-		if (parser.$mode === "async") return runParser(augmentedParser2, programName, args, options);
-		return Promise.resolve(runParser(augmentedParser2, programName, args, options));
-	} finally {
 		await disposeContexts(contexts);
+	} catch (disposeError) {
+		if (hasPrimaryError) throw new SuppressedErrorCtor(disposeError, primaryError, "An error was suppressed during context disposal.");
+		throw disposeError;
+	}
+	if (hasPrimaryError) throw primaryError;
+	return result;
+}
+/**
+* Body of {@link runWithSync}, extracted so that the caller can handle
+* disposal outside a `finally` block (avoiding `no-unsafe-finally` lint).
+*/
+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);
+	if (!needsTwoPhase) {
+		const augmentedParser = injectAnnotationsIntoParser(parser, phase1Annotations);
+		return runParser(augmentedParser, programName, args, options);
+	}
+	const augmentedParser1 = injectAnnotationsIntoParser(parser, phase1Annotations);
+	let firstPassResult;
+	let firstPassDeferred;
+	let firstPassDeferredKeys;
+	try {
+		const result = require_parser.parseSync(augmentedParser1, args);
+		if (result.success) {
+			firstPassResult = result.value;
+			firstPassDeferred = result.deferred;
+			firstPassDeferredKeys = result.deferredKeys;
+		} else return runParser(augmentedParser1, programName, args, options);
+	} catch {
+		return runParser(augmentedParser1, programName, args, options);
 	}
+	const { annotationsList: phase2AnnotationsList } = collectAnnotationsSync(contexts, firstPassResult, ctxOptions, firstPassDeferred, firstPassDeferredKeys);
+	const finalAnnotations = mergeTwoPhaseAnnotations(phase1AnnotationsList, phase2AnnotationsList);
+	const augmentedParser2 = injectAnnotationsIntoParser(parser, finalAnnotations);
+	return runParser(augmentedParser2, programName, args, options);
 }
 /**
 * Runs a synchronous parser with multiple source contexts.
@@ -1294,36 +1354,23 @@ function runWithSync(parser, programName, contexts, options) {
 	if (parser.$mode !== "sync") throw new TypeError("Cannot use an async parser with runWithSync(). Use runWith() or runWithAsync() instead.");
 	const args = options?.args ?? [];
 	if (contexts.length === 0) return runParser(parser, programName, args, options);
+	let result;
+	let primaryError;
+	let hasPrimaryError = false;
+	try {
+		result = runWithSyncBody(parser, programName, contexts, args, options);
+	} catch (error) {
+		hasPrimaryError = true;
+		primaryError = error;
+	}
 	try {
-		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);
-		if (!needsTwoPhase) {
-			const augmentedParser = injectAnnotationsIntoParser(parser, phase1Annotations);
-			return runParser(augmentedParser, programName, args, options);
-		}
-		const augmentedParser1 = injectAnnotationsIntoParser(parser, phase1Annotations);
-		let firstPassResult;
-		let firstPassDeferred;
-		let firstPassDeferredKeys;
-		try {
-			const result = require_parser.parseSync(augmentedParser1, args);
-			if (result.success) {
-				firstPassResult = result.value;
-				firstPassDeferred = result.deferred;
-				firstPassDeferredKeys = result.deferredKeys;
-			} else return runParser(augmentedParser1, programName, args, options);
-		} catch {
-			return runParser(augmentedParser1, programName, args, options);
-		}
-		const { annotationsList: phase2AnnotationsList } = collectAnnotationsSync(contexts, firstPassResult, ctxOptions, firstPassDeferred, firstPassDeferredKeys);
-		const finalAnnotations = mergeTwoPhaseAnnotations(phase1AnnotationsList, phase2AnnotationsList);
-		const augmentedParser2 = injectAnnotationsIntoParser(parser, finalAnnotations);
-		return runParser(augmentedParser2, programName, args, options);
-	} finally {
 		disposeContextsSync(contexts);
+	} catch (disposeError) {
+		if (hasPrimaryError) throw new SuppressedErrorCtor(disposeError, primaryError, "An error was suppressed during context disposal.");
+		throw disposeError;
 	}
+	if (hasPrimaryError) throw primaryError;
+	return result;
 }
 /**
 * Runs any parser asynchronously with multiple source contexts.

package/dist/facade.d.cts

@@ -402,56 +402,6 @@ type ContextOptionsParam<TContexts extends readonly SourceContext<unknown>[], TV
 } : {
   readonly contextOptions: ExtractRequiredOptions<TContexts, TValue>;
 };
-/**
- * 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.
- *
- * 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.
- *
- * If all contexts are static (no dynamic contexts), the second parse is skipped
- * for optimization.
- *
- * @template TParser The parser type.
- * @template THelp Return type when help is shown.
- * @template TError Return type when an error occurs.
- * @param parser The parser to execute.
- * @param programName Name of the program for help/error output.
- * @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}.
- * @since 0.10.0
- *
- * @example
- * ```typescript
- * import { runWith } from "@optique/core/facade";
- * import type { SourceContext } from "@optique/core/context";
- *
- * const envContext: SourceContext = {
- *   id: Symbol.for("@myapp/env"),
- *   getAnnotations() {
- *     return { [Symbol.for("@myapp/env")]: process.env };
- *   }
- * };
- *
- * const result = await runWith(
- *   parser,
- *   "myapp",
- *   [envContext],
- *   { args: process.argv.slice(2) }
- * );
- * ```
- */
 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> & ContextOptionsParam<TContexts, InferValue<TParser>>): Promise<InferValue<TParser>>;
 /**
  * Runs a synchronous parser with multiple source contexts.

package/dist/facade.d.ts

@@ -402,56 +402,6 @@ type ContextOptionsParam<TContexts extends readonly SourceContext<unknown>[], TV
 } : {
   readonly contextOptions: ExtractRequiredOptions<TContexts, TValue>;
 };
-/**
- * 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.
- *
- * 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.
- *
- * If all contexts are static (no dynamic contexts), the second parse is skipped
- * for optimization.
- *
- * @template TParser The parser type.
- * @template THelp Return type when help is shown.
- * @template TError Return type when an error occurs.
- * @param parser The parser to execute.
- * @param programName Name of the program for help/error output.
- * @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}.
- * @since 0.10.0
- *
- * @example
- * ```typescript
- * import { runWith } from "@optique/core/facade";
- * import type { SourceContext } from "@optique/core/context";
- *
- * const envContext: SourceContext = {
- *   id: Symbol.for("@myapp/env"),
- *   getAnnotations() {
- *     return { [Symbol.for("@myapp/env")]: process.env };
- *   }
- * };
- *
- * const result = await runWith(
- *   parser,
- *   "myapp",
- *   [envContext],
- *   { args: process.argv.slice(2) }
- * );
- * ```
- */
 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> & ContextOptionsParam<TContexts, InferValue<TParser>>): Promise<InferValue<TParser>>;
 /**
  * Runs a synchronous parser with multiple source contexts.

package/dist/facade.js

@@ -12,6 +12,19 @@ import { getDocPage, parseAsync, parseSync, suggest, suggestAsync } from "./pars
 import { group, longestMatch, object } from "./constructs.js";
 
 //#region src/facade.ts
+const SuppressedErrorCtor = typeof SuppressedError === "function" ? SuppressedError : (() => {
+	class SuppressedErrorPolyfill extends Error {
+		error;
+		suppressed;
+		constructor(error, suppressed, message$1) {
+			super(message$1);
+			this.name = "SuppressedError";
+			this.error = error;
+			this.suppressed = suppressed;
+		}
+	}
+	return SuppressedErrorPolyfill;
+})();
 function finalizeParsedForContext(context, parsed) {
 	return context.finalizeParsed != null ? context.finalizeParsed(parsed) : parsed;
 }
@@ -1216,57 +1229,104 @@ function disposeContextsSync(contexts) {
 * );
 * ```
 */
+async function runWithBody(parser, programName, contexts, args, options) {
+	validateContextIds(contexts);
+	if (needsEarlyExit(args, options)) {
+		if (parser.$mode === "async") return runParser(parser, programName, 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);
+	if (!needsTwoPhase) {
+		const augmentedParser = injectAnnotationsIntoParser(parser, phase1Annotations);
+		if (parser.$mode === "async") return runParser(augmentedParser, programName, args, options);
+		return Promise.resolve(runParser(augmentedParser, programName, args, options));
+	}
+	const augmentedParser1 = injectAnnotationsIntoParser(parser, phase1Annotations);
+	let firstPassResult;
+	let firstPassDeferred;
+	let firstPassDeferredKeys;
+	let firstPassFailed = false;
+	try {
+		if (parser.$mode === "async") firstPassResult = await parseAsync(augmentedParser1, args);
+		else firstPassResult = parseSync(augmentedParser1, args);
+		if (typeof firstPassResult === "object" && firstPassResult !== null && "success" in firstPassResult) {
+			const result = firstPassResult;
+			if (result.success) {
+				firstPassResult = result.value;
+				firstPassDeferred = result.deferred;
+				firstPassDeferredKeys = result.deferredKeys;
+			} else firstPassFailed = true;
+		}
+	} catch {
+		firstPassFailed = true;
+	}
+	if (firstPassFailed) {
+		const augmentedParser = injectAnnotationsIntoParser(parser, phase1Annotations);
+		if (parser.$mode === "async") return runParser(augmentedParser, programName, args, options);
+		return Promise.resolve(runParser(augmentedParser, programName, args, options));
+	}
+	const { annotationsList: phase2AnnotationsList } = await collectAnnotations(contexts, firstPassResult, ctxOptions, firstPassDeferred, firstPassDeferredKeys);
+	const finalAnnotations = mergeTwoPhaseAnnotations(phase1AnnotationsList, phase2AnnotationsList);
+	const augmentedParser2 = injectAnnotationsIntoParser(parser, finalAnnotations);
+	if (parser.$mode === "async") return runParser(augmentedParser2, programName, args, options);
+	return Promise.resolve(runParser(augmentedParser2, programName, args, options));
+}
 async function runWith(parser, programName, contexts, options) {
 	const args = options?.args ?? [];
 	if (contexts.length === 0) {
 		if (parser.$mode === "async") return runParser(parser, programName, args, options);
 		return Promise.resolve(runParser(parser, programName, args, options));
 	}
+	let result;
+	let primaryError;
+	let hasPrimaryError = false;
+	try {
+		result = await runWithBody(parser, programName, contexts, args, options);
+	} catch (error) {
+		hasPrimaryError = true;
+		primaryError = error;
+	}
 	try {
-		validateContextIds(contexts);
-		if (needsEarlyExit(args, options)) {
-			if (parser.$mode === "async") return runParser(parser, programName, 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);
-		if (!needsTwoPhase) {
-			const augmentedParser = injectAnnotationsIntoParser(parser, phase1Annotations);
-			if (parser.$mode === "async") return runParser(augmentedParser, programName, args, options);
-			return Promise.resolve(runParser(augmentedParser, programName, args, options));
-		}
-		const augmentedParser1 = injectAnnotationsIntoParser(parser, phase1Annotations);
-		let firstPassResult;
-		let firstPassDeferred;
-		let firstPassDeferredKeys;
-		let firstPassFailed = false;
-		try {
-			if (parser.$mode === "async") firstPassResult = await parseAsync(augmentedParser1, args);
-			else firstPassResult = parseSync(augmentedParser1, args);
-			if (typeof firstPassResult === "object" && firstPassResult !== null && "success" in firstPassResult) {
-				const result = firstPassResult;
-				if (result.success) {
-					firstPassResult = result.value;
-					firstPassDeferred = result.deferred;
-					firstPassDeferredKeys = result.deferredKeys;
-				} else firstPassFailed = true;
-			}
-		} catch {
-			firstPassFailed = true;
-		}
-		if (firstPassFailed) {
-			const augmentedParser = injectAnnotationsIntoParser(parser, phase1Annotations);
-			if (parser.$mode === "async") return runParser(augmentedParser, programName, args, options);
-			return Promise.resolve(runParser(augmentedParser, programName, args, options));
-		}
-		const { annotationsList: phase2AnnotationsList } = await collectAnnotations(contexts, firstPassResult, ctxOptions, firstPassDeferred, firstPassDeferredKeys);
-		const finalAnnotations = mergeTwoPhaseAnnotations(phase1AnnotationsList, phase2AnnotationsList);
-		const augmentedParser2 = injectAnnotationsIntoParser(parser, finalAnnotations);
-		if (parser.$mode === "async") return runParser(augmentedParser2, programName, args, options);
-		return Promise.resolve(runParser(augmentedParser2, programName, args, options));
-	} finally {
 		await disposeContexts(contexts);
+	} catch (disposeError) {
+		if (hasPrimaryError) throw new SuppressedErrorCtor(disposeError, primaryError, "An error was suppressed during context disposal.");
+		throw disposeError;
+	}
+	if (hasPrimaryError) throw primaryError;
+	return result;
+}
+/**
+* Body of {@link runWithSync}, extracted so that the caller can handle
+* disposal outside a `finally` block (avoiding `no-unsafe-finally` lint).
+*/
+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);
+	if (!needsTwoPhase) {
+		const augmentedParser = injectAnnotationsIntoParser(parser, phase1Annotations);
+		return runParser(augmentedParser, programName, args, options);
+	}
+	const augmentedParser1 = injectAnnotationsIntoParser(parser, phase1Annotations);
+	let firstPassResult;
+	let firstPassDeferred;
+	let firstPassDeferredKeys;
+	try {
+		const result = parseSync(augmentedParser1, args);
+		if (result.success) {
+			firstPassResult = result.value;
+			firstPassDeferred = result.deferred;
+			firstPassDeferredKeys = result.deferredKeys;
+		} else return runParser(augmentedParser1, programName, args, options);
+	} catch {
+		return runParser(augmentedParser1, programName, args, options);
 	}
+	const { annotationsList: phase2AnnotationsList } = collectAnnotationsSync(contexts, firstPassResult, ctxOptions, firstPassDeferred, firstPassDeferredKeys);
+	const finalAnnotations = mergeTwoPhaseAnnotations(phase1AnnotationsList, phase2AnnotationsList);
+	const augmentedParser2 = injectAnnotationsIntoParser(parser, finalAnnotations);
+	return runParser(augmentedParser2, programName, args, options);
 }
 /**
 * Runs a synchronous parser with multiple source contexts.
@@ -1294,36 +1354,23 @@ function runWithSync(parser, programName, contexts, options) {
 	if (parser.$mode !== "sync") throw new TypeError("Cannot use an async parser with runWithSync(). Use runWith() or runWithAsync() instead.");
 	const args = options?.args ?? [];
 	if (contexts.length === 0) return runParser(parser, programName, args, options);
+	let result;
+	let primaryError;
+	let hasPrimaryError = false;
+	try {
+		result = runWithSyncBody(parser, programName, contexts, args, options);
+	} catch (error) {
+		hasPrimaryError = true;
+		primaryError = error;
+	}
 	try {
-		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);
-		if (!needsTwoPhase) {
-			const augmentedParser = injectAnnotationsIntoParser(parser, phase1Annotations);
-			return runParser(augmentedParser, programName, args, options);
-		}
-		const augmentedParser1 = injectAnnotationsIntoParser(parser, phase1Annotations);
-		let firstPassResult;
-		let firstPassDeferred;
-		let firstPassDeferredKeys;
-		try {
-			const result = parseSync(augmentedParser1, args);
-			if (result.success) {
-				firstPassResult = result.value;
-				firstPassDeferred = result.deferred;
-				firstPassDeferredKeys = result.deferredKeys;
-			} else return runParser(augmentedParser1, programName, args, options);
-		} catch {
-			return runParser(augmentedParser1, programName, args, options);
-		}
-		const { annotationsList: phase2AnnotationsList } = collectAnnotationsSync(contexts, firstPassResult, ctxOptions, firstPassDeferred, firstPassDeferredKeys);
-		const finalAnnotations = mergeTwoPhaseAnnotations(phase1AnnotationsList, phase2AnnotationsList);
-		const augmentedParser2 = injectAnnotationsIntoParser(parser, finalAnnotations);
-		return runParser(augmentedParser2, programName, args, options);
-	} finally {
 		disposeContextsSync(contexts);
+	} catch (disposeError) {
+		if (hasPrimaryError) throw new SuppressedErrorCtor(disposeError, primaryError, "An error was suppressed during context disposal.");
+		throw disposeError;
 	}
+	if (hasPrimaryError) throw primaryError;
+	return result;
 }
 /**
 * Runs any parser asynchronously with multiple source contexts.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/core",
-  "version": "1.0.0-dev.1681+85e1e6ac",
+  "version": "1.0.0-dev.1684+b4ee4c18",
   "description": "Type-safe combinatorial command-line interface parser",
   "keywords": [
     "CLI",