@optique/core 1.0.0-dev.1810 → 1.0.0-dev.1818

package/dist/constructs.cjs

@@ -51,6 +51,7 @@ function mergeChildExec(parent, child) {
 		trace: child.trace ?? parent.trace,
 		dependencyRuntime: child.dependencyRuntime ?? parent.dependencyRuntime,
 		dependencyRegistry: child.dependencyRegistry ?? parent.dependencyRegistry,
+		commandPath: child.commandPath ?? parent.commandPath,
 		preCompletedByParser: child.preCompletedByParser ?? parent.preCompletedByParser,
 		excludedSourceFields: child.excludedSourceFields ?? parent.excludedSourceFields
 	};

package/dist/constructs.js

@@ -51,6 +51,7 @@ function mergeChildExec(parent, child) {
 		trace: child.trace ?? parent.trace,
 		dependencyRuntime: child.dependencyRuntime ?? parent.dependencyRuntime,
 		dependencyRegistry: child.dependencyRegistry ?? parent.dependencyRegistry,
+		commandPath: child.commandPath ?? parent.commandPath,
 		preCompletedByParser: child.preCompletedByParser ?? parent.preCompletedByParser,
 		excludedSourceFields: child.excludedSourceFields ?? parent.excludedSourceFields
 	};

package/dist/facade.cjs

@@ -95,11 +95,147 @@ function withPreparedParsedForContext(context, preparedParsed, run) {
 function isBufferUnchanged(previous, current) {
 	return current.length > 0 && current.length === previous.length && current.every((item, i) => item === previous[i]);
 }
+function getFailureProgress(args, buffer, consumedInStep) {
+	return {
+		remainingArgs: buffer.slice(consumedInStep),
+		consumedCount: args.length - buffer.length + consumedInStep
+	};
+}
+function createParseExec(parser) {
+	return {
+		usage: parser.usage,
+		phase: "parse",
+		path: [],
+		commandPath: [],
+		trace: require_input_trace.createInputTrace()
+	};
+}
+function getCommandPath(exec) {
+	return exec?.commandPath ?? [];
+}
+function createCompleteExec(exec, context) {
+	const runtime = require_dependency_runtime.createDependencyRuntimeContext();
+	return {
+		...exec,
+		phase: "complete",
+		dependencyRuntime: runtime,
+		dependencyRegistry: runtime.registry,
+		commandPath: getCommandPath(context.exec) ?? exec.commandPath,
+		trace: context.exec?.trace ?? context.trace ?? exec.trace
+	};
+}
+function attemptParseSync(parser, args, mode = "complete") {
+	const shouldUnwrapAnnotatedValue = require_annotations.isInjectedAnnotationWrapper(parser.initialState);
+	const exec = createParseExec(parser);
+	let context = require_parser.createParserContext({
+		buffer: args,
+		state: parser.initialState,
+		optionsTerminated: false
+	}, exec);
+	do {
+		const result = parser.parse(context);
+		if (!result.success) {
+			const progress = getFailureProgress(args, context.buffer, result.consumed);
+			return {
+				kind: "failure",
+				error: result.error,
+				remainingArgs: progress.remainingArgs,
+				consumedCount: progress.consumedCount,
+				optionsTerminated: context.optionsTerminated,
+				commandPath: getCommandPath(context.exec)
+			};
+		}
+		const previousBuffer = context.buffer;
+		context = result.next;
+		if (isBufferUnchanged(previousBuffer, context.buffer)) {
+			const progress = getFailureProgress(args, previousBuffer, result.consumed.length);
+			return {
+				kind: "failure",
+				error: require_message.message`Unexpected option or argument: ${context.buffer[0]}.`,
+				remainingArgs: progress.remainingArgs,
+				consumedCount: progress.consumedCount,
+				optionsTerminated: context.optionsTerminated,
+				commandPath: getCommandPath(context.exec)
+			};
+		}
+	} while (context.buffer.length > 0);
+	if (mode === "parse-only") return {
+		kind: "success",
+		value: void 0
+	};
+	const endResult = parser.complete(context.state, createCompleteExec(exec, context));
+	if (!endResult.success) return {
+		kind: "failure",
+		error: endResult.error,
+		remainingArgs: [],
+		consumedCount: args.length,
+		optionsTerminated: context.optionsTerminated,
+		commandPath: getCommandPath(context.exec)
+	};
+	return {
+		kind: "success",
+		value: shouldUnwrapAnnotatedValue ? require_annotations.unwrapInjectedAnnotationWrapper(endResult.value) : endResult.value
+	};
+}
+async function attemptParseAsync(parser, args, mode = "complete") {
+	const shouldUnwrapAnnotatedValue = require_annotations.isInjectedAnnotationWrapper(parser.initialState);
+	const exec = createParseExec(parser);
+	let context = require_parser.createParserContext({
+		buffer: args,
+		state: parser.initialState,
+		optionsTerminated: false
+	}, exec);
+	do {
+		const result = await parser.parse(context);
+		if (!result.success) {
+			const progress = getFailureProgress(args, context.buffer, result.consumed);
+			return {
+				kind: "failure",
+				error: result.error,
+				remainingArgs: progress.remainingArgs,
+				consumedCount: progress.consumedCount,
+				optionsTerminated: context.optionsTerminated,
+				commandPath: getCommandPath(context.exec)
+			};
+		}
+		const previousBuffer = context.buffer;
+		context = result.next;
+		if (isBufferUnchanged(previousBuffer, context.buffer)) {
+			const progress = getFailureProgress(args, previousBuffer, result.consumed.length);
+			return {
+				kind: "failure",
+				error: require_message.message`Unexpected option or argument: ${context.buffer[0]}.`,
+				remainingArgs: progress.remainingArgs,
+				consumedCount: progress.consumedCount,
+				optionsTerminated: context.optionsTerminated,
+				commandPath: getCommandPath(context.exec)
+			};
+		}
+	} while (context.buffer.length > 0);
+	if (mode === "parse-only") return {
+		kind: "success",
+		value: void 0
+	};
+	const endResult = await parser.complete(context.state, createCompleteExec(exec, context));
+	if (!endResult.success) return {
+		kind: "failure",
+		error: endResult.error,
+		remainingArgs: [],
+		consumedCount: args.length,
+		optionsTerminated: context.optionsTerminated,
+		commandPath: getCommandPath(context.exec)
+	};
+	return {
+		kind: "success",
+		value: shouldUnwrapAnnotatedValue ? require_annotations.unwrapInjectedAnnotationWrapper(endResult.value) : endResult.value
+	};
+}
 function createPhase2SeedExec(parser, context) {
 	const exec = {
 		usage: parser.usage,
 		phase: "parse",
 		path: [],
+		commandPath: [],
 		trace: require_input_trace.createInputTrace()
 	};
 	const runtime = require_dependency_runtime.createDependencyRuntimeContext();
@@ -108,6 +244,7 @@ function createPhase2SeedExec(parser, context) {
 		phase: "complete",
 		dependencyRuntime: runtime,
 		dependencyRegistry: runtime.registry,
+		commandPath: getCommandPath(context.exec),
 		trace: context.exec?.trace ?? context.trace ?? exec.trace
 	};
 }
@@ -116,6 +253,7 @@ function createPhase2SeedContext(parser, args) {
 		usage: parser.usage,
 		phase: "parse",
 		path: [],
+		commandPath: [],
 		trace: require_input_trace.createInputTrace()
 	};
 	return require_parser.createParserContext({
@@ -203,9 +341,6 @@ function createVersionParser(commandConfig, optionConfig) {
 	};
 }
 const metaResultBrand = Symbol("@optique/core/facade/meta");
-function isMetaParseResult(value$1) {
-	return typeof value$1 === "object" && value$1 != null && metaResultBrand in value$1;
-}
 /**
 * Creates completion parsers based on the sub-config.
 */
@@ -473,54 +608,115 @@ function combineWithHelpVersion(originalParser, helpParsers, versionParsers, com
 	}
 	return combined;
 }
-/**
-* Classifies the parsing result into a discriminated union for cleaner
-* handling.
-*/
-function classifyResult(result, args, helpOptionNames, helpCommandNames, versionOptionNames, versionCommandNames, completionCommandNames) {
-	if (!result.success) return {
-		type: "error",
-		error: result.error
-	};
-	const value$1 = result.value;
-	if (isMetaParseResult(value$1)) {
-		const parsedValue = value$1;
-		const hasVersionOption = versionOptionNames.some((n) => args.includes(n));
-		const hasVersionCommand = args.length > 0 && versionCommandNames.includes(args[0]);
-		const hasCompletionCommand = args.length > 0 && completionCommandNames.includes(args[0]);
-		const hasHelpOption = hasCompletionCommand ? helpOptionNames.length > 0 && args.length >= 2 && helpOptionNames.includes(args[1]) : helpOptionNames.some((n) => args.includes(n));
-		const hasHelpCommand = args.length > 0 && helpCommandNames.includes(args[0]);
-		if (hasVersionCommand && hasHelpOption && parsedValue.helpFlag) return {
-			type: "help",
-			commands: [args[0]]
+function classifyOptionMeta(scanArgs, fullArgs, helpOptionNames, versionOptionNames, completionOptionNames) {
+	let lastHelpVersion;
+	for (let i = 0; i < scanArgs.length; i++) {
+		const arg = scanArgs[i];
+		if (helpOptionNames.includes(arg)) lastHelpVersion = {
+			index: i,
+			kind: "help"
 		};
-		if (hasCompletionCommand && hasHelpOption && parsedValue.helpFlag) return {
-			type: "help",
-			commands: [args[0]]
+		else if (versionOptionNames.includes(arg)) lastHelpVersion = {
+			index: i,
+			kind: "version"
+		};
+		const equalsMatch = completionOptionNames.find((name) => arg.startsWith(name + "="));
+		if (equalsMatch != null) return {
+			lastHelpVersion,
+			completion: {
+				index: i,
+				shell: arg.slice(equalsMatch.length + 1),
+				args: fullArgs.slice(i + 1)
+			}
 		};
-		if (parsedValue.help && (hasHelpOption || hasHelpCommand)) {
-			let commandContext = [];
-			if (Array.isArray(parsedValue.commands)) commandContext = parsedValue.commands;
-			else if (typeof parsedValue.commands === "object" && parsedValue.commands != null && "length" in parsedValue.commands) commandContext = parsedValue.commands;
+		if (completionOptionNames.includes(arg)) {
+			const shell = scanArgs[i + 1] ?? "";
 			return {
-				type: "help",
-				commands: commandContext
+				lastHelpVersion,
+				completion: {
+					index: i,
+					shell,
+					args: shell === "" ? [] : fullArgs.slice(i + 2)
+				}
 			};
 		}
-		if ((hasVersionOption || hasVersionCommand) && (parsedValue.version || parsedValue.versionFlag)) return { type: "version" };
-		if (parsedValue.completion && parsedValue.completionData) return {
+	}
+	return { lastHelpVersion };
+}
+function getHelpCommandContext(commandPath, args, helpIndex) {
+	const commands = [...commandPath];
+	for (let i = 0; i < helpIndex; i++) {
+		const arg = args[i];
+		if (!arg.startsWith("-")) commands.push(arg);
+	}
+	return commands;
+}
+function classifyParseFailure(failure, helpOptionNames, helpCommandNames, versionOptionNames, versionCommandNames, completionOptionNames, completionCommandNames) {
+	if (failure.remainingArgs.length < 1) return {
+		type: "error",
+		error: failure.error
+	};
+	const hasConsumedPrefix = failure.consumedCount > 0;
+	const firstArg = failure.remainingArgs[0];
+	if (!hasConsumedPrefix && completionCommandNames.includes(firstArg)) {
+		const secondArg = failure.remainingArgs[1];
+		if (helpOptionNames.includes(secondArg)) return {
+			type: "help",
+			commands: [firstArg]
+		};
+		return {
 			type: "completion",
-			shell: parsedValue.completionData.shell ?? "",
-			args: parsedValue.completionData.args ?? []
+			source: "command",
+			shell: secondArg ?? "",
+			args: failure.remainingArgs.slice(2)
 		};
+	}
+	const optionArgs = failure.optionsTerminated ? [] : (() => {
+		const terminatorIndex = failure.remainingArgs.indexOf("--");
+		return terminatorIndex >= 0 ? failure.remainingArgs.slice(0, terminatorIndex) : failure.remainingArgs;
+	})();
+	const { lastHelpVersion, completion } = classifyOptionMeta(optionArgs, failure.remainingArgs, helpOptionNames, versionOptionNames, completionOptionNames);
+	if (!hasConsumedPrefix && versionCommandNames.includes(firstArg)) {
+		const secondArg = failure.remainingArgs[1];
+		if (helpOptionNames.includes(secondArg)) return {
+			type: "help",
+			commands: [firstArg]
+		};
+		const isCompletionImmediatelyAfter = completion?.index === 1;
+		if (secondArg == null || isCompletionImmediatelyAfter || lastHelpVersion?.index === 1 && lastHelpVersion.kind === "version") return { type: "version" };
 		return {
-			type: "success",
-			value: "result" in parsedValue ? parsedValue.result : value$1
+			type: "error",
+			error: failure.error
 		};
 	}
+	let commandAction;
+	if (!hasConsumedPrefix && helpCommandNames.includes(firstArg)) commandAction = {
+		index: 0,
+		kind: "help"
+	};
+	const winner = lastHelpVersion == null ? commandAction : commandAction == null || lastHelpVersion.index >= commandAction.index ? lastHelpVersion : commandAction;
+	if (winner?.kind === "help") {
+		if (winner === commandAction) return {
+			type: "help",
+			commands: failure.remainingArgs.slice(1)
+		};
+		return {
+			type: "help",
+			commands: getHelpCommandContext(failure.commandPath, failure.remainingArgs, winner.index),
+			preferUserCommandDocs: failure.commandPath.length > 0
+		};
+	}
+	if (winner?.kind === "version") return { type: "version" };
+	if (completion != null) return {
+		type: "completion",
+		source: "option",
+		shell: completion.shell,
+		commandPath: failure.commandPath,
+		args: completion.args
+	};
 	return {
-		type: "success",
-		value: value$1
+		type: "error",
+		error: failure.error
 	};
 }
 /**
@@ -694,12 +890,7 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 		"completion command",
 		completionCommandNames
 	]);
-	require_validate.validateMetaNameCollisions({
-		leadingNames: parser.leadingNames,
-		allOptions: require_usage.extractOptionNames(parser.usage, true),
-		allCommands: require_usage.extractCommandNames(parser.usage, true),
-		allLiterals: require_usage.extractLiteralValues(parser.usage)
-	}, activeMetaEntries);
+	require_validate.validateMetaNameCollisions(activeMetaEntries);
 	const defaultShells = {
 		bash: require_completion.bash,
 		fish: require_completion.fish,
@@ -723,50 +914,6 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 		completionCommand: null,
 		completionOption: null
 	};
-	if (options.completion) {
-		const helpTerminatorIndex = args.indexOf("--");
-		const helpOptionArgs = helpTerminatorIndex >= 0 ? args.slice(0, helpTerminatorIndex) : args;
-		const hasHelpOption = helpOptionConfig ? completionCommandConfig && completionCommandNames.includes(args[0]) ? args.length >= 2 && helpOptionNames.includes(args[1]) : helpOptionNames.some((n) => helpOptionArgs.includes(n)) : false;
-		if (completionCommandConfig && args.length >= 1 && completionCommandNames.includes(args[0]) && !hasHelpOption) return handleCompletion(args.slice(1), programName, parser, completionParsers.completionCommand, stdout, stderr, onCompletionResult, onErrorResult, availableShells, colors, maxWidth, completionCommandNames[0], completionOptionNames[0], false, sectionOrder);
-		const hasMetaEntryBefore = (endIndex) => {
-			const argsBefore = args.slice(0, endIndex);
-			if (helpOptionConfig && helpOptionNames.some((n) => argsBefore.includes(n))) return true;
-			if (versionOptionConfig && versionOptionNames.some((n) => argsBefore.includes(n))) return true;
-			if (endIndex > 0) {
-				if (helpCommandConfig && helpCommandNames.includes(args[0])) return true;
-				if (versionCommandConfig && versionCommandNames.includes(args[0])) return true;
-			}
-			return false;
-		};
-		let completionOptionIndex = -1;
-		if (completionOptionConfig) {
-			const loopBound = helpTerminatorIndex >= 0 ? helpTerminatorIndex : args.length;
-			for (let i = 0; i < loopBound; i++) {
-				const arg = args[i];
-				const equalsMatch = completionOptionNames.find((n) => arg.startsWith(n + "="));
-				if (equalsMatch) {
-					if (hasMetaEntryBefore(i)) {
-						completionOptionIndex = i;
-						break;
-					}
-					const shell = arg.slice(equalsMatch.length + 1);
-					const completionArgs = args.slice(i + 1);
-					return handleCompletion([shell, ...completionArgs], programName, parser, completionParsers.completionOption, stdout, stderr, onCompletionResult, onErrorResult, availableShells, colors, maxWidth, completionCommandNames[0], completionOptionNames[0], true, sectionOrder);
-				}
-				const exactMatch = completionOptionNames.includes(arg);
-				if (exactMatch) {
-					if (hasMetaEntryBefore(i)) {
-						completionOptionIndex = i;
-						break;
-					}
-					const shell = i + 1 < args.length ? args[i + 1] : "";
-					const completionArgs = i + 1 < args.length ? args.slice(i + 2) : [];
-					return handleCompletion([shell, ...completionArgs], programName, parser, completionParsers.completionOption, stdout, stderr, onCompletionResult, onErrorResult, availableShells, colors, maxWidth, completionCommandNames[0], completionOptionNames[0], true, sectionOrder);
-				}
-			}
-		}
-		if (completionOptionIndex >= 0) args = args.slice(0, completionOptionIndex);
-	}
 	const augmentedParser = !options.help && !options.version && !options.completion ? parser : combineWithHelpVersion(parser, helpParsers, versionParsers, completionParsers, {
 		helpCommandGroup: helpCommandConfig?.group,
 		helpOptionGroup: helpOptionConfig?.group,
@@ -775,14 +922,17 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 		completionCommandGroup: completionCommandConfig?.group,
 		completionOptionGroup: completionOptionConfig?.group
 	}, helpOptionConfig ? [...helpOptionNames] : void 0, versionOptionConfig ? [...versionOptionNames] : void 0);
-	const handleResult = (result) => {
-		const classified = classifyResult(result, args, helpOptionConfig ? [...helpOptionNames] : [], helpCommandConfig ? [...helpCommandNames] : [], versionOptionConfig ? [...versionOptionNames] : [], versionCommandConfig ? [...versionCommandNames] : [], completionCommandConfig ? [...completionCommandNames] : []);
+	const handleResult = (classified) => {
 		switch (classified.type) {
 			case "success": return classified.value;
 			case "version":
 				stdout(versionValue);
 				return onVersion(0);
-			case "completion": throw new RunParserError("Completion should be handled by early return");
+			case "completion": return handleCompletion([
+				classified.shell,
+				...classified.commandPath ?? [],
+				...classified.args
+			], programName, parser, classified.source === "command" ? completionParsers.completionCommand : completionParsers.completionOption, stdout, stderr, onCompletionResult, onErrorResult, availableShells, colors, maxWidth, completionCommandNames[0], completionOptionNames[0], classified.source === "option", sectionOrder);
 			case "help": {
 				let helpGeneratorParser;
 				const helpAsCommand = helpCommandConfig != null;
@@ -792,9 +942,9 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 				const versionAsOption = versionOptionConfig != null;
 				const completionAsOption = completionOptionConfig != null;
 				const requestedCommand = classified.commands[0];
-				if (requestedCommand != null && completionCommandNames.includes(requestedCommand) && completionAsCommand && completionParsers.completionCommand) helpGeneratorParser = completionParsers.completionCommand;
-				else if (requestedCommand != null && helpCommandNames.includes(requestedCommand) && helpAsCommand && helpParsers.helpCommand) helpGeneratorParser = helpParsers.helpCommand;
-				else if (requestedCommand != null && versionCommandNames.includes(requestedCommand) && versionAsCommand && versionParsers.versionCommand) helpGeneratorParser = versionParsers.versionCommand;
+				if (requestedCommand != null && !classified.preferUserCommandDocs && completionCommandNames.includes(requestedCommand) && completionAsCommand && completionParsers.completionCommand) helpGeneratorParser = completionParsers.completionCommand;
+				else if (requestedCommand != null && !classified.preferUserCommandDocs && helpCommandNames.includes(requestedCommand) && helpAsCommand && helpParsers.helpCommand) helpGeneratorParser = helpParsers.helpCommand;
+				else if (requestedCommand != null && !classified.preferUserCommandDocs && versionCommandNames.includes(requestedCommand) && versionAsCommand && versionParsers.versionCommand) helpGeneratorParser = versionParsers.versionCommand;
 				else {
 					const commandParsers = [parser];
 					const groupedMeta = {};
@@ -886,8 +1036,8 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 					while (validationResult === "continue") {
 						const stepResult = helpGeneratorParser.parse(validationContext);
 						if (stepResult instanceof Promise) {
-							const asyncValidate = async (result$1) => {
-								let res = processStep(result$1);
+							const asyncValidate = async (result) => {
+								let res = processStep(result);
 								while (res === "continue") {
 									const next = helpGeneratorParser.parse(validationContext);
 									const resolved = next instanceof Promise ? await next : next;
@@ -953,13 +1103,21 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 	};
 	const parserMode = parser.$mode;
 	return require_mode_dispatch.dispatchByMode(parserMode, () => {
-		const result = require_parser.parseSync(augmentedParser, args);
-		const handled = handleResult(result);
+		const attempted = attemptParseSync(parser, args);
+		const classified = attempted.kind === "success" ? {
+			type: "success",
+			value: attempted.value
+		} : classifyParseFailure(attempted, helpOptionConfig ? [...helpOptionNames] : [], helpCommandConfig ? [...helpCommandNames] : [], versionOptionConfig ? [...versionOptionNames] : [], versionCommandConfig ? [...versionCommandNames] : [], completionOptionConfig ? [...completionOptionNames] : [], completionCommandConfig ? [...completionCommandNames] : []);
+		const handled = handleResult(classified);
 		if (handled instanceof Promise) throw new RunParserError("Synchronous parser returned async result.");
 		return handled;
 	}, async () => {
-		const result = await require_parser.parseAsync(augmentedParser, args);
-		const handled = handleResult(result);
+		const attempted = await attemptParseAsync(parser, args);
+		const classified = attempted.kind === "success" ? {
+			type: "success",
+			value: attempted.value
+		} : classifyParseFailure(attempted, helpOptionConfig ? [...helpOptionNames] : [], helpCommandConfig ? [...helpCommandNames] : [], versionOptionConfig ? [...versionOptionNames] : [], versionCommandConfig ? [...versionCommandNames] : [], completionOptionConfig ? [...completionOptionNames] : [], completionCommandConfig ? [...completionCommandNames] : []);
+		const handled = handleResult(classified);
 		return handled instanceof Promise ? await handled : handled;
 	});
 }
@@ -1020,49 +1178,38 @@ var RunParserError = class extends Error {
 function indentLines(text$1, indent) {
 	return text$1.split("\n").join("\n" + " ".repeat(indent));
 }
+function isMetaEarlyExit(classified) {
+	return classified.type === "help" || classified.type === "version" || classified.type === "completion";
+}
+function classifyEarlyExitFailure(failure, options) {
+	const norm = (c) => c === true ? {} : c;
+	const helpOptionConfig = norm(options.help?.option);
+	const helpCommandConfig = norm(options.help?.command);
+	const versionOptionConfig = norm(options.version?.option);
+	const versionCommandConfig = norm(options.version?.command);
+	const completionOptionConfig = norm(options.completion?.option);
+	const completionCommandConfig = norm(options.completion?.command);
+	return classifyParseFailure(failure, helpOptionConfig ? [...helpOptionConfig.names ?? ["--help"]] : [], helpCommandConfig ? [...helpCommandConfig.names ?? ["help"]] : [], versionOptionConfig ? [...versionOptionConfig.names ?? ["--version"]] : [], versionCommandConfig ? [...versionCommandConfig.names ?? ["version"]] : [], completionOptionConfig ? [...completionOptionConfig.names ?? ["--completion"]] : [], completionCommandConfig ? [...completionCommandConfig.names ?? ["completion"]] : []);
+}
+function shouldProbeEarlyExit(options, needsTwoPhase) {
+	return needsTwoPhase && (options.help != null || options.version != null || options.completion != null);
+}
 /**
-* Checks if the arguments contain help, version, or completion requests
-* that should be handled immediately without context processing.
-*
-* This enables early exit optimization: when users request help, version,
-* or completion, we skip annotation collection and context processing
-* entirely, delegating directly to runParser().
-*
-* @param args Command-line arguments to check.
-* @param options Run options containing help/version/completion configuration.
-* @returns `true` if early exit should be performed, `false` otherwise.
+* Checks if the arguments contain parser-visible meta requests that can be
+* handled without collecting source-context annotations first.
 */
-function needsEarlyExit(args, options) {
-	const norm = (c) => c === true ? {} : c;
-	const terminatorIndex = args.indexOf("--");
-	const optionArgs = terminatorIndex >= 0 ? args.slice(0, terminatorIndex) : args;
-	if (options.help) {
-		const helpOptionConfig = norm(options.help.option);
-		const helpCommandConfig = norm(options.help.command);
-		const helpOptionNames = helpOptionConfig?.names ?? ["--help"];
-		const helpCommandNames = helpCommandConfig?.names ?? ["help"];
-		if (helpOptionConfig && helpOptionNames.some((n) => optionArgs.includes(n))) return true;
-		if (helpCommandConfig && helpCommandNames.includes(args[0])) return true;
-	}
-	if (options.version) {
-		const versionOptionConfig = norm(options.version.option);
-		const versionCommandConfig = norm(options.version.command);
-		const versionOptionNames = versionOptionConfig?.names ?? ["--version"];
-		const versionCommandNames = versionCommandConfig?.names ?? ["version"];
-		if (versionOptionConfig && versionOptionNames.some((n) => optionArgs.includes(n))) return true;
-		if (versionCommandConfig && versionCommandNames.includes(args[0])) return true;
-	}
-	if (options.completion) {
-		const completionCommandConfig = norm(options.completion.command);
-		const completionOptionConfig = norm(options.completion.option);
-		const completionCommandNames = completionCommandConfig?.names ?? ["completion"];
-		const completionOptionNames = completionOptionConfig?.names ?? ["--completion"];
-		if (completionCommandConfig && completionCommandNames.includes(args[0])) return true;
-		if (completionOptionConfig) {
-			for (const arg of optionArgs) for (const name of completionOptionNames) if (arg === name || arg.startsWith(name + "=")) return true;
-		}
-	}
-	return false;
+function needsEarlyExitSync(parser, args, options) {
+	const attempted = attemptParseSync(parser, args, "parse-only");
+	if (attempted.kind === "success") return false;
+	return isMetaEarlyExit(classifyEarlyExitFailure(attempted, options));
+}
+/**
+* Async variant of {@link needsEarlyExitSync}.
+*/
+async function needsEarlyExitAsync(parser, args, options) {
+	const attempted = await attemptParseAsync(parser, args, "parse-only");
+	if (attempted.kind === "success") return false;
+	return isMetaEarlyExit(classifyEarlyExitFailure(attempted, options));
 }
 /**
 * Merges multiple annotation objects, with earlier contexts having priority.
@@ -1250,23 +1397,25 @@ function disposeContextsSync(contexts) {
 async function runWithBody(parser, programName, contexts, args, options) {
 	require_validate.validateContextIds(contexts);
 	validateContextPhases(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, needsTwoPhase, snapshots: phase1Snapshots } = 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));
+	if (shouldProbeEarlyExit(options, needsTwoPhase)) {
+		const earlyExitParser = injectAnnotationsIntoParser(parser, phase1Annotations);
+		if (await needsEarlyExitAsync(earlyExitParser, args, options)) {
+			if (parser.$mode === "async") return runParser(earlyExitParser, programName, args, options);
+			return Promise.resolve(runParser(earlyExitParser, programName, args, options));
+		}
 	}
 	const augmentedParser1 = injectAnnotationsIntoParser(parser, phase1Annotations);
+	if (!needsTwoPhase) {
+		if (parser.$mode === "async") return runParser(augmentedParser1, programName, args, options);
+		return Promise.resolve(runParser(augmentedParser1, programName, args, options));
+	}
 	const firstPassSeed = await require_mode_dispatch.dispatchByMode(parser.$mode, () => extractPhase2SeedSync(augmentedParser1, args), () => extractPhase2SeedAsync(augmentedParser1, args));
 	if (firstPassSeed == null) {
-		const augmentedParser = injectAnnotationsIntoParser(parser, phase1Annotations);
-		if (parser.$mode === "async") return runParser(augmentedParser, programName, args, options);
-		return Promise.resolve(runParser(augmentedParser, programName, args, options));
+		const fallbackParser = injectAnnotationsIntoParser(parser, phase1Annotations);
+		if (parser.$mode === "async") return runParser(fallbackParser, programName, args, options);
+		return Promise.resolve(runParser(fallbackParser, programName, args, options));
 	}
 	const { annotations: finalAnnotations } = await collectFinalAnnotations(contexts, phase1Snapshots, firstPassSeed.value, ctxOptions, firstPassSeed.deferred, firstPassSeed.deferredKeys);
 	const augmentedParser2 = injectAnnotationsIntoParser(parser, finalAnnotations);
@@ -1368,18 +1517,18 @@ async function runWith(parser, programName, contexts, options) {
 function runWithSyncBody(parser, programName, contexts, args, options) {
 	require_validate.validateContextIds(contexts);
 	validateContextPhases(contexts);
-	if (needsEarlyExit(args, options)) return runParser(parser, programName, args, options);
 	const ctxOptions = options.contextOptions;
 	const { annotations: phase1Annotations, needsTwoPhase, snapshots: phase1Snapshots } = collectPhase1AnnotationsSync(contexts, ctxOptions);
-	if (!needsTwoPhase) {
-		const augmentedParser = injectAnnotationsIntoParser(parser, phase1Annotations);
-		return runParser(augmentedParser, programName, args, options);
+	if (shouldProbeEarlyExit(options, needsTwoPhase)) {
+		const earlyExitParser = injectAnnotationsIntoParser(parser, phase1Annotations);
+		if (needsEarlyExitSync(earlyExitParser, args, options)) return runParser(earlyExitParser, programName, args, options);
 	}
 	const augmentedParser1 = injectAnnotationsIntoParser(parser, phase1Annotations);
+	if (!needsTwoPhase) return runParser(augmentedParser1, programName, args, options);
 	const firstPassSeed = extractPhase2SeedSync(augmentedParser1, args);
 	if (firstPassSeed == null) {
-		const augmentedParser = injectAnnotationsIntoParser(parser, phase1Annotations);
-		return runParser(augmentedParser, programName, args, options);
+		const fallbackParser = injectAnnotationsIntoParser(parser, phase1Annotations);
+		return runParser(fallbackParser, programName, args, options);
 	}
 	const { annotations: finalAnnotations } = collectFinalAnnotationsSync(contexts, phase1Snapshots, firstPassSeed.value, ctxOptions, firstPassSeed.deferred, firstPassSeed.deferredKeys);
 	const augmentedParser2 = injectAnnotationsIntoParser(parser, finalAnnotations);