@optique/core 1.4.0-dev.2606 → 1.4.0-dev.2607

package/dist/constructs.js

@@ -8,12 +8,13 @@ import { createDependencySourceState, dependencyId, isDependencySourceState, isP
 import { buildRuntimeNodesFromArray, buildRuntimeNodesFromPairs, collectExplicitSourceValues, collectExplicitSourceValuesAsync, collectSourcesFromState, completeEffectfulSourcesAsync, createDependencyRuntimeContext, effectfulSchedulingNodesKey, exclusiveSourceScopeKey, extractRawInputFromState, fillMissingSourceDefaults, fillMissingSourceDefaultsAsync, forkRuntimeForCommittedSubtree, getDefaultDependencySnapshot, guaranteedStaticSourceIdsKey, hasInactiveCompletion, isMatchedState, recordSourceScope, releaseUncollectedSourceValues, replaceCachedBarrierFailure, resolveDerivedSourceValues, resolveDerivedSourceValuesAsync, resolveStateWithRuntime, resolveStateWithRuntimeAsync, serializeSchedulingPath, sourceCollectionExpansionKey, staticSourceScopeKey } from "./dependency-runtime.js";
 import { defineInheritedAnnotationParser, defineParseLanes, getOwnParseLanes, getParserSuggestRuntimeNodes, unmatchedNonCliDependencySourceStateMarker } from "./internal/parser.js";
 import { annotationViewTargets, getWrappedChildParseState, getWrappedChildState, reconcileObjectChildState, unwrapAnnotationView } from "./annotation-state.js";
+import { collectLeadingCandidates } from "./usage-internals.js";
+import { adoptOptionScope, combinedOptionScope, conditionalOptionScope, forkOptionScope, restoreOptionScope, scopeParser, selectableOptionScope, withOptionScope, withParserOptionScope } from "./short-option.js";
 import { allowDuplicateLeadingCommandNamesKey } from "./internal/command-alias.js";
 import { mergeChildExec, withChildContext, withChildExecPath } from "./execution-context.js";
 import { completeOrExtractPhase2Seed, extractPhase2Seed, extractPhase2SeedKey, phase2SeedFromValueResult } from "./phase2-seed.js";
 import { fluent } from "./modifiers.js";
 import { DEFAULT_FIND_SIMILAR_OPTIONS, createErrorWithSuggestions, createSuggestionMessage, deduplicateSuggestions, expandCommandAliasSuggestions, findSimilar } from "./suggestion.js";
-import { collectLeadingCandidates } from "./usage-internals.js";
 
 //#region src/constructs.ts
 /**
@@ -48,7 +49,7 @@ function withoutRepublishInstruction(exec) {
 }
 function withChildContext$1(context, segment, state, parser, usage) {
 	const childState = parser == null ? state : getWrappedChildParseState(context.state, state, parser);
-	return withChildContext(context, segment, childState, usage);
+	return withChildContext(parser == null ? context : withParserOptionScope(context, parser), segment, childState, usage);
 }
 function isUnmatchedDependencyState(state, parser) {
 	if (state === void 0) return true;
@@ -1402,7 +1403,7 @@ function or(...args) {
 		let optionsTerminatorResult = null;
 		let provisionalAmbiguous = false;
 		for (const [parser, i] of orderedParsers) {
-			const result = parser.parse(withChildContext$1(context, i, activeState == null || activeState[0] !== i || !activeState[1].success ? parser.initialState : activeState[1].next.state, parser));
+			const result = parser.parse(withChildContext$1(forkOptionScope(context), i, activeState == null || activeState[0] !== i || !activeState[1].success ? parser.initialState : activeState[1].next.state, parser));
 			if (isOptionsTerminatorOnlyResult(context, result)) {
 				if (activeState?.[0] === i && activeState[1].success && activeState[1].consumed.length > 0 && result.next.buffer.length < 1) return preserveExclusiveStateAfterOptionsTerminator(context, result);
 				optionsTerminatorResult ??= result;
@@ -1437,7 +1438,7 @@ function or(...args) {
 						return {
 							success: true,
 							next: {
-								...context,
+								...adoptOptionScope(context, result.next),
 								buffer: result.next.buffer,
 								optionsTerminated: result.next.optionsTerminated,
 								state: createExclusiveState(context.state, i, parser, result),
@@ -1473,7 +1474,7 @@ function or(...args) {
 					return {
 						success: true,
 						next: {
-							...context,
+							...adoptOptionScope(context, replayedResult.next),
 							buffer: replayedResult.next.buffer,
 							optionsTerminated: replayedResult.next.optionsTerminated,
 							state: createExclusiveState(context.state, i, parser, {
@@ -1492,7 +1493,7 @@ function or(...args) {
 				return {
 					success: true,
 					next: {
-						...context,
+						...adoptOptionScope(context, result.next),
 						buffer: result.next.buffer,
 						optionsTerminated: result.next.optionsTerminated,
 						state: createExclusiveState(context.state, i, parser, result),
@@ -1518,7 +1519,7 @@ function or(...args) {
 				success: true,
 				...zeroConsumedBranch.result.provisional ? { provisional: true } : {},
 				next: {
-					...context,
+					...adoptOptionScope(context, zeroConsumedBranch.result.next),
 					state: createExclusiveState(context.state, zeroConsumedBranch.index, zeroConsumedBranch.parser, zeroConsumedBranch.result),
 					...mergedExec != null ? {
 						exec: mergedExec,
@@ -1536,7 +1537,7 @@ function or(...args) {
 					success: true,
 					provisional: true,
 					next: {
-						...context,
+						...adoptOptionScope(context, provisionalConsuming.result.next),
 						buffer: provisionalConsuming.result.next.buffer,
 						optionsTerminated: provisionalConsuming.result.next.optionsTerminated,
 						state: createExclusiveState(context.state, provisionalConsuming.index, provisionalConsuming.parser, provisionalConsuming.result),
@@ -1551,7 +1552,7 @@ function or(...args) {
 			if (activeState != null && activeState[1].success) {
 				const previouslyConsumed = activeState[1].consumed;
 				const checkResult = provisionalConsuming.parser.parse({
-					...withChildContext$1(context, provisionalConsuming.index, provisionalConsuming.parser.initialState, provisionalConsuming.parser),
+					...withChildContext$1(forkOptionScope(context), provisionalConsuming.index, provisionalConsuming.parser.initialState, provisionalConsuming.parser),
 					buffer: previouslyConsumed
 				});
 				const canConsumeShared = checkResult.success && checkResult.consumed.length === previouslyConsumed.length && checkResult.consumed.every((c, idx) => c === previouslyConsumed[idx]);
@@ -1570,7 +1571,7 @@ function or(...args) {
 						success: true,
 						provisional: true,
 						next: {
-							...context,
+							...adoptOptionScope(context, replayedResult.next),
 							buffer: replayedResult.next.buffer,
 							optionsTerminated: replayedResult.next.optionsTerminated,
 							state: createExclusiveState(context.state, provisionalConsuming.index, provisionalConsuming.parser, {
@@ -1605,7 +1606,7 @@ function or(...args) {
 		let optionsTerminatorResult = null;
 		let provisionalAmbiguous = false;
 		for (const [parser, i] of orderedParsers) {
-			const resultOrPromise = parser.parse(withChildContext$1(context, i, activeState == null || activeState[0] !== i || !activeState[1].success ? parser.initialState : activeState[1].next.state, parser));
+			const resultOrPromise = parser.parse(withChildContext$1(forkOptionScope(context), i, activeState == null || activeState[0] !== i || !activeState[1].success ? parser.initialState : activeState[1].next.state, parser));
 			const result = await resultOrPromise;
 			if (isOptionsTerminatorOnlyResult(context, result)) {
 				if (activeState?.[0] === i && activeState[1].success && activeState[1].consumed.length > 0 && result.next.buffer.length < 1) return preserveExclusiveStateAfterOptionsTerminator(context, result);
@@ -1641,7 +1642,7 @@ function or(...args) {
 						return {
 							success: true,
 							next: {
-								...context,
+								...adoptOptionScope(context, result.next),
 								buffer: result.next.buffer,
 								optionsTerminated: result.next.optionsTerminated,
 								state: createExclusiveState(context.state, i, parser, result),
@@ -1679,7 +1680,7 @@ function or(...args) {
 					return {
 						success: true,
 						next: {
-							...context,
+							...adoptOptionScope(context, replayedResult.next),
 							buffer: replayedResult.next.buffer,
 							optionsTerminated: replayedResult.next.optionsTerminated,
 							state: createExclusiveState(context.state, i, parser, {
@@ -1698,7 +1699,7 @@ function or(...args) {
 				return {
 					success: true,
 					next: {
-						...context,
+						...adoptOptionScope(context, result.next),
 						buffer: result.next.buffer,
 						optionsTerminated: result.next.optionsTerminated,
 						state: createExclusiveState(context.state, i, parser, result),
@@ -1724,7 +1725,7 @@ function or(...args) {
 				success: true,
 				...zeroConsumedBranch.result.provisional ? { provisional: true } : {},
 				next: {
-					...context,
+					...adoptOptionScope(context, zeroConsumedBranch.result.next),
 					state: createExclusiveState(context.state, zeroConsumedBranch.index, zeroConsumedBranch.parser, zeroConsumedBranch.result),
 					...mergedExec != null ? {
 						exec: mergedExec,
@@ -1742,7 +1743,7 @@ function or(...args) {
 					success: true,
 					provisional: true,
 					next: {
-						...context,
+						...adoptOptionScope(context, provisionalConsuming.result.next),
 						buffer: provisionalConsuming.result.next.buffer,
 						optionsTerminated: provisionalConsuming.result.next.optionsTerminated,
 						state: createExclusiveState(context.state, provisionalConsuming.index, provisionalConsuming.parser, provisionalConsuming.result),
@@ -1757,7 +1758,7 @@ function or(...args) {
 			if (activeState != null && activeState[1].success) {
 				const previouslyConsumed = activeState[1].consumed;
 				const checkResult = await provisionalConsuming.parser.parse({
-					...withChildContext$1(context, provisionalConsuming.index, provisionalConsuming.parser.initialState, provisionalConsuming.parser),
+					...withChildContext$1(forkOptionScope(context), provisionalConsuming.index, provisionalConsuming.parser.initialState, provisionalConsuming.parser),
 					buffer: previouslyConsumed
 				});
 				const canConsumeShared = checkResult.success && checkResult.consumed.length === previouslyConsumed.length && checkResult.consumed.every((c, idx) => c === previouslyConsumed[idx]);
@@ -1776,7 +1777,7 @@ function or(...args) {
 						success: true,
 						provisional: true,
 						next: {
-							...context,
+							...adoptOptionScope(context, replayedResult.next),
 							buffer: replayedResult.next.buffer,
 							optionsTerminated: replayedResult.next.optionsTerminated,
 							state: createExclusiveState(context.state, provisionalConsuming.index, provisionalConsuming.parser, {
@@ -1863,7 +1864,7 @@ function or(...args) {
 	if (singleDependencyMetadata != null) singleResult.dependencyMetadata = singleDependencyMetadata;
 	defineExclusiveSchedulingNodes(singleResult, parsers);
 	defineInheritedAnnotationParser(singleResult);
-	return fluent(singleResult);
+	return fluent(scopeParser(singleResult, combinedOptionScope(parsers)));
 }
 /**
 * @since 0.5.0
@@ -1912,7 +1913,7 @@ function createLongestMatch(...args) {
 		return {
 			success: true,
 			next: {
-				...context,
+				...adoptOptionScope(context, selectedResult.next),
 				buffer: selectedResult.next.buffer,
 				optionsTerminated: selectedResult.next.optionsTerminated,
 				state: createExclusiveState(context.state, match.index, parser, selectedResult),
@@ -1952,7 +1953,7 @@ function createLongestMatch(...args) {
 		const activeState = normalizeExclusiveState(context.state);
 		for (let i = 0; i < syncParsers.length; i++) {
 			const parser = syncParsers[i];
-			const childContext = withChildContext$1(context, i, activeState == null || activeState[0] !== i || !activeState[1].success ? parser.initialState : activeState[1].next.state, parser);
+			const childContext = withChildContext$1(forkOptionScope(context), i, activeState == null || activeState[0] !== i || !activeState[1].success ? parser.initialState : activeState[1].next.state, parser);
 			const result = parser.parse(childContext);
 			if (isOptionsTerminatorOnlyResult(context, result)) {
 				optionsTerminatorMatches.push({
@@ -1988,7 +1989,7 @@ function createLongestMatch(...args) {
 		const activeState = normalizeExclusiveState(context.state);
 		for (let i = 0; i < parsers.length; i++) {
 			const parser = parsers[i];
-			const childContext = withChildContext$1(context, i, activeState == null || activeState[0] !== i || !activeState[1].success ? parser.initialState : activeState[1].next.state, parser);
+			const childContext = withChildContext$1(forkOptionScope(context), i, activeState == null || activeState[0] !== i || !activeState[1].success ? parser.initialState : activeState[1].next.state, parser);
 			const resultOrPromise = parser.parse(childContext);
 			const result = await resultOrPromise;
 			if (isOptionsTerminatorOnlyResult(context, result)) {
@@ -2079,7 +2080,7 @@ function createLongestMatch(...args) {
 	if (multiDependencyMetadata != null) multiResult.dependencyMetadata = multiDependencyMetadata;
 	defineExclusiveSchedulingNodes(multiResult, parsers);
 	defineInheritedAnnotationParser(multiResult);
-	return fluent(multiResult);
+	return fluent(scopeParser(multiResult, combinedOptionScope(parsers)));
 }
 /**
 * Creates the initial parse error shared by object-like combinators.
@@ -3093,15 +3094,15 @@ function object(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 	});
 	defineParseLanes(objectParser, objectParseLanes);
 	defineInheritedAnnotationParser(objectParser);
-	return fluent(objectParser);
+	return fluent(scopeParser(objectParser, combinedOptionScope(parserPairs.map(([, p]) => p))));
 }
 function isParserLike(value) {
 	return value != null && (typeof value === "object" || typeof value === "function") && "parse" in value && "$valueType" in value && "$stateType" in value;
 }
 function tokenMatchesLeadingName(token, candidates) {
 	if (token == null) return false;
-	for (const name of candidates.optionNames) if (token === name) return true;
-	for (const name of candidates.joinedOptionNames) if (name.startsWith("/") && token.startsWith(`${name}:`) || (name.startsWith("--") || name.startsWith("-") && name.length > 2) && token.startsWith(`${name}=`)) return true;
+	for (const name of candidates.optionNames) if (token === name || name.startsWith("-") && !name.startsWith("--") && name.length > 2 && token.startsWith(`${name}=`)) return true;
+	for (const name of candidates.joinedOptionNames) if (/^-[^-]$/.test(name) && token.startsWith(name) || name.startsWith("/") && token.startsWith(`${name}:`) || (name.startsWith("--") || name.startsWith("-") && name.length > 2) && token.startsWith(`${name}=`)) return true;
 	for (const name of candidates.commandNames) if (token === name) return true;
 	return false;
 }
@@ -3327,6 +3328,7 @@ function advanceSeqSuggestContextSync(context, parsers, initialStates) {
 	while (currentContext.state.index < parsers.length) {
 		const index = currentContext.state.index;
 		const parser = parsers[index];
+		currentContext = withParserOptionScope(currentContext, parser);
 		const parserState = getSeqChildState(currentContext.state, index, parser);
 		if (currentContext.buffer.length < 1) break;
 		if (shouldAdvanceSeqBeforeParse(parser, parserState, initialStates[index], currentContext, index, parsers)) {
@@ -3353,6 +3355,7 @@ async function advanceSeqSuggestContextAsync(context, parsers, initialStates) {
 	while (currentContext.state.index < parsers.length) {
 		const index = currentContext.state.index;
 		const parser = parsers[index];
+		currentContext = withParserOptionScope(currentContext, parser);
 		const parserState = getSeqChildState(currentContext.state, index, parser);
 		if (currentContext.buffer.length < 1) break;
 		if (shouldAdvanceSeqBeforeParse(parser, parserState, initialStates[index], currentContext, index, parsers)) {
@@ -4109,7 +4112,7 @@ function tuple(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 		enumerable: false
 	});
 	defineInheritedAnnotationParser(tupleParser);
-	return fluent(tupleParser);
+	return fluent(scopeParser(tupleParser, combinedOptionScope(parsers)));
 }
 function seq(...rawArgs) {
 	const label = typeof rawArgs[0] === "string" ? rawArgs[0] : void 0;
@@ -4127,12 +4130,31 @@ function seq(...rawArgs) {
 		...result,
 		consumed: consumed.length + result.consumed
 	});
+	const reachableSeqScope = (context) => {
+		let end = Math.min(context.state.index + 1, parsers.length);
+		while (end < parsers.length) {
+			const index = end - 1;
+			const child = parsers[index];
+			if (context.buffer.length > 0 && !tokenMatchesLeadingName(context.buffer[0], leadingCandidatesAfter(parsers, end))) break;
+			if (!parserCanSkipAt(child, getSeqChildState(context.state, index, child), context.exec, index)) break;
+			end++;
+		}
+		return combinedOptionScope(parsers.slice(0, end));
+	};
+	const seqScope = selectableOptionScope(reachableSeqScope({
+		state: initialState,
+		buffer: [],
+		usage: [],
+		optionsTerminated: false
+	}));
 	const parseSync = (context) => {
 		let currentContext = context;
 		const allConsumed = [];
 		while (currentContext.state.index < syncParsers.length) {
 			const index = currentContext.state.index;
 			const parser = syncParsers[index];
+			seqScope.select(currentContext, reachableSeqScope(currentContext));
+			currentContext = withParserOptionScope(currentContext, parser);
 			const parserState = getSeqChildState(currentContext.state, index, parser);
 			if (currentContext.buffer.length < 1) break;
 			if (shouldAdvanceSeqBeforeParse(parser, parserState, initialState.states[index], currentContext, index, syncParsers)) {
@@ -4175,6 +4197,8 @@ function seq(...rawArgs) {
 		while (currentContext.state.index < parsers.length) {
 			const index = currentContext.state.index;
 			const parser = parsers[index];
+			seqScope.select(currentContext, reachableSeqScope(currentContext));
+			currentContext = withParserOptionScope(currentContext, parser);
 			const parserState = getSeqChildState(currentContext.state, index, parser);
 			if (currentContext.buffer.length < 1) break;
 			if (shouldAdvanceSeqBeforeParse(parser, parserState, initialState.states[index], currentContext, index, parsers)) {
@@ -4443,7 +4467,9 @@ function seq(...rawArgs) {
 		enumerable: false
 	});
 	defineInheritedAnnotationParser(seqParser);
-	return fluent(seqParser);
+	return fluent(scopeParser(seqParser, seqScope.source, (context) => {
+		seqScope.select(context, reachableSeqScope(context));
+	}));
 }
 function merge(...args) {
 	const label = typeof args[0] === "string" ? args[0] : void 0;
@@ -5437,7 +5463,7 @@ function merge(...args) {
 	};
 	defineParseLanes(mergeParser, mergeParseLanes);
 	defineInheritedAnnotationParser(mergeParser);
-	return fluent(mergeParser);
+	return fluent(scopeParser(mergeParser, combinedOptionScope(parsers)));
 }
 /**
 * Builds a dependency registry from the pre-parsed context state and returns
@@ -6064,7 +6090,7 @@ function concat(...parsers) {
 		}
 	};
 	defineInheritedAnnotationParser(concatParser);
-	return fluent(concatParser);
+	return fluent(scopeParser(concatParser, combinedOptionScope(parsers)));
 }
 function group(label, parser, options = {}) {
 	validateLabel(label);
@@ -6174,7 +6200,7 @@ function group(label, parser, options = {}) {
 		configurable: true,
 		enumerable: false
 	});
-	return fluent(groupParser);
+	return fluent(scopeParser(groupParser, combinedOptionScope([parser])));
 }
 /**
 * Creates a conditional parser that selects different branch parsers based on
@@ -6283,6 +6309,7 @@ function conditional(discriminator, branches, defaultBranch, options) {
 		const noMatchContext = analyzeNoMatchContext([discriminator, ...allBranchParsers]);
 		return options?.errors?.noMatch ? typeof options.errors.noMatch === "function" ? options.errors.noMatch(noMatchContext) : options.errors.noMatch : generateNoMatchError(noMatchContext);
 	};
+	const optionScope = conditionalOptionScope(discriminator, defaultBranch, branchParsers.map(([, p]) => p));
 	const parseSync = (context) => {
 		const state = context.state ?? initialState;
 		const syncDiscriminator = discriminator;
@@ -6319,10 +6346,12 @@ function conditional(discriminator, branches, defaultBranch, options) {
 				const value = completionResult.value;
 				const branchParser = syncBranches[value];
 				if (branchParser) {
+					const branchContext = forkOptionScope(context);
+					optionScope.select(branchContext, branchParser);
 					const discriminatorExec = mergeChildExec(context.exec, discriminatorResult.next.exec);
 					const branchParseResult = branchParser.parse({
 						...withChildContext$1({
-							...context,
+							...branchContext,
 							...discriminatorExec != null ? {
 								exec: discriminatorExec,
 								dependencyRegistry: discriminatorExec.dependencyRegistry
@@ -6332,6 +6361,7 @@ function conditional(discriminator, branches, defaultBranch, options) {
 						optionsTerminated: discriminatorResult.next.optionsTerminated
 					});
 					if (branchParseResult.success) {
+						if (discriminatorResult.consumed.length > 0 || branchParseResult.consumed.length > 0) adoptOptionScope(context, branchParseResult.next);
 						const mergedExec = mergeChildExec(discriminatorExec, branchParseResult.next.exec);
 						const isProvisional = branchParseResult.provisional || discriminatorResult.consumed.length === 0 && branchParseResult.consumed.length === 0 && (branchParser.leadingNames.size > 0 || branchParser.acceptingAnyToken);
 						return {
@@ -6356,26 +6386,29 @@ function conditional(discriminator, branches, defaultBranch, options) {
 							consumed: [...discriminatorResult.consumed, ...branchParseResult.consumed]
 						};
 					}
-					if (discriminatorResult.consumed.length > 0) return {
-						success: true,
-						next: {
-							...discriminatorResult.next,
-							state: {
-								discriminatorState: annotatedDiscriminatorState,
-								discriminatorValue: value,
-								selectedBranch: {
-									kind: "branch",
-									key: value
+					if (discriminatorResult.consumed.length > 0) {
+						optionScope.select(context, branchParser);
+						return {
+							success: true,
+							next: {
+								...discriminatorResult.next,
+								state: {
+									discriminatorState: annotatedDiscriminatorState,
+									discriminatorValue: value,
+									selectedBranch: {
+										kind: "branch",
+										key: value
+									},
+									branchState: getWrappedChildState(state, branchParser.initialState, branchParser)
 								},
-								branchState: getWrappedChildState(state, branchParser.initialState, branchParser)
+								...discriminatorExec != null ? {
+									exec: discriminatorExec,
+									dependencyRegistry: discriminatorExec.dependencyRegistry
+								} : {}
 							},
-							...discriminatorExec != null ? {
-								exec: discriminatorExec,
-								dependencyRegistry: discriminatorExec.dependencyRegistry
-							} : {}
-						},
-						consumed: discriminatorResult.consumed
-					};
+							consumed: discriminatorResult.consumed
+						};
+					}
 					return branchParseResult;
 				}
 			}
@@ -6448,7 +6481,7 @@ function conditional(discriminator, branches, defaultBranch, options) {
 			if (discriminatorResult.consumed.length === 0 && discriminator.mode === "async") {
 				const discriminatorExec = mergeChildExec(context.exec, discriminatorResult.next.exec);
 				const speculationContext = {
-					...context,
+					...withOptionScope(context, unionLeadingNames([...branchParsers.map(([, p]) => p), ...defaultBranch ? [defaultBranch] : []])),
 					buffer: discriminatorResult.next.buffer,
 					optionsTerminated: discriminatorResult.next.optionsTerminated,
 					...discriminatorExec != null ? {
@@ -6462,7 +6495,7 @@ function conditional(discriminator, branches, defaultBranch, options) {
 				let speculativeError;
 				let ambiguous = false;
 				for (const [key, bp] of branchParsers) {
-					const branchResult = await bp.parse(withChildContext$1(speculationContext, "_branch", bp.initialState, bp, bp.usage));
+					const branchResult = await bp.parse(withChildContext$1(forkOptionScope(speculationContext), "_branch", bp.initialState, bp, bp.usage));
 					if (branchResult.success && branchResult.consumed.length > 0) {
 						if (branchResult.provisional) {
 							if (provisionalHit == null && !provisionalAmbiguous) provisionalHit = {
@@ -6495,11 +6528,12 @@ function conditional(discriminator, branches, defaultBranch, options) {
 					if (branchResult.success) {
 						const annotatedDiscriminatorState$2 = getWrappedChildState(state, discriminatorResult.next.state, discriminator);
 						const mergedExec = mergeChildExec(discriminatorExec, branchResult.next.exec);
+						optionScope.select(context, bp);
 						return {
 							success: true,
 							provisional: true,
 							next: {
-								...branchResult.next,
+								...restoreOptionScope(branchResult.next, context),
 								state: {
 									...state,
 									discriminatorState: annotatedDiscriminatorState$2,
@@ -6521,14 +6555,15 @@ function conditional(discriminator, branches, defaultBranch, options) {
 				}
 				let deferredBranchState = state.branchState;
 				if (defaultBranch !== void 0 && !ambiguous && !provisionalAmbiguous) {
-					const defaultResult = await defaultBranch.parse(withChildContext$1(speculationContext, "_branch", state.branchState ?? defaultBranch.initialState, defaultBranch, defaultBranch.usage));
+					const defaultResult = await defaultBranch.parse(withChildContext$1(forkOptionScope(speculationContext), "_branch", state.branchState ?? defaultBranch.initialState, defaultBranch, defaultBranch.usage));
 					if (defaultResult.success && defaultResult.consumed.length > 0) {
 						const defaultExec = mergeChildExec(discriminatorExec ?? context.exec, defaultResult.next.exec);
+						optionScope.select(context, defaultBranch);
 						return {
 							success: true,
 							...defaultResult.provisional ? { provisional: true } : {},
 							next: {
-								...defaultResult.next,
+								...restoreOptionScope(defaultResult.next, context),
 								state: {
 									...state,
 									selectedBranch: { kind: "default" },
@@ -6551,7 +6586,7 @@ function conditional(discriminator, branches, defaultBranch, options) {
 					success: true,
 					provisional: true,
 					next: {
-						...speculationContext,
+						...restoreOptionScope(speculationContext, context),
 						state: {
 							...state,
 							discriminatorState: annotatedDiscriminatorState$1,
@@ -6567,10 +6602,12 @@ function conditional(discriminator, branches, defaultBranch, options) {
 				const value = completionResult.value;
 				const branchParser = branches[value];
 				if (branchParser) {
+					const branchContext = forkOptionScope(context);
+					optionScope.select(branchContext, branchParser);
 					const discriminatorExec = mergeChildExec(context.exec, discriminatorResult.next.exec);
 					const branchParseResult = await branchParser.parse({
 						...withChildContext$1({
-							...context,
+							...branchContext,
 							...discriminatorExec != null ? {
 								exec: discriminatorExec,
 								dependencyRegistry: discriminatorExec.dependencyRegistry
@@ -6580,6 +6617,7 @@ function conditional(discriminator, branches, defaultBranch, options) {
 						optionsTerminated: discriminatorResult.next.optionsTerminated
 					});
 					if (branchParseResult.success) {
+						if (discriminatorResult.consumed.length > 0 || branchParseResult.consumed.length > 0) adoptOptionScope(context, branchParseResult.next);
 						const mergedExec = mergeChildExec(discriminatorExec, branchParseResult.next.exec);
 						return {
 							success: true,
@@ -6603,26 +6641,29 @@ function conditional(discriminator, branches, defaultBranch, options) {
 							consumed: [...discriminatorResult.consumed, ...branchParseResult.consumed]
 						};
 					}
-					if (discriminatorResult.consumed.length > 0) return {
-						success: true,
-						next: {
-							...discriminatorResult.next,
-							state: {
-								discriminatorState: annotatedDiscriminatorState,
-								discriminatorValue: value,
-								selectedBranch: {
-									kind: "branch",
-									key: value
+					if (discriminatorResult.consumed.length > 0) {
+						optionScope.select(context, branchParser);
+						return {
+							success: true,
+							next: {
+								...discriminatorResult.next,
+								state: {
+									discriminatorState: annotatedDiscriminatorState,
+									discriminatorValue: value,
+									selectedBranch: {
+										kind: "branch",
+										key: value
+									},
+									branchState: getWrappedChildState(state, branchParser.initialState, branchParser)
 								},
-								branchState: getWrappedChildState(state, branchParser.initialState, branchParser)
+								...discriminatorExec != null ? {
+									exec: discriminatorExec,
+									dependencyRegistry: discriminatorExec.dependencyRegistry
+								} : {}
 							},
-							...discriminatorExec != null ? {
-								exec: discriminatorExec,
-								dependencyRegistry: discriminatorExec.dependencyRegistry
-							} : {}
-						},
-						consumed: discriminatorResult.consumed
-					};
+							consumed: discriminatorResult.consumed
+						};
+					}
 					return branchParseResult;
 				}
 			}
@@ -7296,7 +7337,9 @@ function conditional(discriminator, branches, defaultBranch, options) {
 			} : void 0, "_discriminator"));
 			if (discComplete.success && syncBranches[discComplete.value] !== void 0) {
 				const resolvedBranch = syncBranches[discComplete.value];
-				yield* resolvedBranch.suggest(withChildContext$1(suggestContext, "_branch", state.branchState ?? resolvedBranch.initialState, resolvedBranch), prefix);
+				const branchContext = forkOptionScope(suggestContext);
+				optionScope.select(branchContext, resolvedBranch);
+				yield* resolvedBranch.suggest(withChildContext$1(branchContext, "_branch", state.branchState ?? resolvedBranch.initialState, resolvedBranch), prefix);
 			} else if (syncDefaultBranch !== void 0) yield* syncDefaultBranch.suggest(withChildContext$1(suggestContext, "_branch", state.branchState ?? syncDefaultBranch.initialState, syncDefaultBranch), prefix);
 		} else {
 			const branchParser = state.selectedBranch.kind === "default" ? syncDefaultBranch : syncBranches[state.selectedBranch.key];
@@ -7350,7 +7393,9 @@ function conditional(discriminator, branches, defaultBranch, options) {
 				} : void 0, "_discriminator"));
 				if (discComplete.success && branches[discComplete.value] !== void 0) {
 					const resolvedBranch = branches[discComplete.value];
-					yield* resolvedBranch.suggest(withChildContext$1(suggestContext, "_branch", state.branchState ?? resolvedBranch.initialState, resolvedBranch), prefix);
+					const branchContext = forkOptionScope(suggestContext);
+					optionScope.select(branchContext, resolvedBranch);
+					yield* resolvedBranch.suggest(withChildContext$1(branchContext, "_branch", state.branchState ?? resolvedBranch.initialState, resolvedBranch), prefix);
 					discResolved = true;
 				}
 			}
@@ -7501,7 +7546,13 @@ function conditional(discriminator, branches, defaultBranch, options) {
 		configurable: true,
 		enumerable: false
 	});
-	return fluent(conditionalParser);
+	return fluent(scopeParser(conditionalParser, optionScope.source, (context) => {
+		const selected = context.state?.selectedBranch;
+		if (selected != null) {
+			const branch = selected.kind === "default" ? defaultBranch : branches[selected.key];
+			if (branch != null) optionScope.select(context, branch);
+		}
+	}));
 }
 
 //#endregion

package/dist/facade.cjs

@@ -12,6 +12,7 @@ const require_dependency_runtime = require('./dependency-runtime.cjs');
 const require_input_trace = require('./input-trace.cjs');
 const require_internal_parser = require('./internal/parser.cjs');
 const require_completion = require('./completion.cjs');
+const require_usage_internals = require('./usage-internals.cjs');
 const require_command_alias = require('./internal/command-alias.cjs');
 const require_phase2_seed = require('./phase2-seed.cjs');
 const require_modifiers = require('./modifiers.cjs');
@@ -749,83 +750,16 @@ function collectActiveValueOptionNames(usage, commandPath, includeDirectAfterCom
 		flag: /* @__PURE__ */ new Set()
 	};
 	if (commandPath.length === 0) {
-		collectRootOptionNames(usage, optionNames, rootLeadingNames);
+		require_usage_internals.collectRootOptionNames(usage, optionNames, rootLeadingNames);
 		return optionNames.value;
-	} else collectActiveOptionNames(usage, commandPath, optionNames, false, includeDirectAfterCommandOptions);
+	} else require_usage_internals.collectActiveOptionNames(usage, commandPath, optionNames, false, includeDirectAfterCommandOptions);
 	const names = new Set(optionNames.value);
 	for (const name of optionNames.flag) names.delete(name);
 	return names;
 }
-function collectRootOptionNames(usage, names, rootLeadingNames) {
-	for (const term of usage) collectRootOptionNamesFromTerm(term, names, rootLeadingNames);
-}
-function collectRootOptionNamesFromTerm(term, names, rootLeadingNames) {
-	switch (term.type) {
-		case "option":
-			for (const name of term.names) {
-				if (!rootLeadingNames.has(name)) continue;
-				if (term.metavar != null) names.value.add(name);
-				else names.flag.add(name);
-			}
-			return;
-		case "optional":
-		case "multiple":
-		case "sequence":
-			collectRootOptionNames(term.terms, names, rootLeadingNames);
-			return;
-		case "exclusive":
-			for (const branch of term.terms) collectRootOptionNames(branch, names, rootLeadingNames);
-			return;
-		case "argument":
-		case "command":
-		case "literal":
-		case "passthrough":
-		case "ellipsis": return;
-	}
-}
-function collectActiveOptionNames(usage, commandPath, names, fromExclusive, includeDirectAfterCommandOptions) {
-	if (commandPath.length === 0) {
-		collectOptionNamesAtCurrentCommandDepth(usage, names, false);
-		return;
-	}
-	const [commandName, ...rest] = commandPath;
-	for (let i = 0; i < usage.length; i++) {
-		const term = usage[i];
-		if (term.type === "command" && term.name === commandName) {
-			const remainingUsage = usage.slice(i + 1);
-			if (rest.length === 0) collectOptionNamesAtCurrentCommandDepth(remainingUsage, names, !fromExclusive && includeDirectAfterCommandOptions);
-			else collectActiveOptionNames(remainingUsage, rest, names, fromExclusive, includeDirectAfterCommandOptions);
-		} else if (term.type === "exclusive") for (const branch of term.terms) collectActiveOptionNames(branch, commandPath, names, true, includeDirectAfterCommandOptions);
-		else if (term.type === "optional" || term.type === "multiple" || term.type === "sequence") collectActiveOptionNames(term.terms, commandPath, names, fromExclusive, includeDirectAfterCommandOptions);
-	}
-}
 function isRootOptionToken(token, rootOptionSuggestions) {
 	return token != null && rootOptionSuggestions.some((suggestion) => token === suggestion.text || token.startsWith(`${suggestion.text}=`));
 }
-function collectOptionNamesAtCurrentCommandDepth(usage, names, afterMatchedCommand) {
-	for (const term of usage) if (collectOptionNamesAtCurrentCommandDepthFromTerm(term, names, afterMatchedCommand)) return;
-}
-function collectOptionNamesAtCurrentCommandDepthFromTerm(term, names, afterMatchedCommand) {
-	switch (term.type) {
-		case "command": return !afterMatchedCommand;
-		case "option":
-			if (term.metavar != null) for (const name of term.names) names.value.add(name);
-			else for (const name of term.names) names.flag.add(name);
-			return false;
-		case "optional":
-		case "multiple":
-		case "sequence":
-			collectOptionNamesAtCurrentCommandDepth(term.terms, names, afterMatchedCommand);
-			return false;
-		case "exclusive":
-			for (const branch of term.terms) collectOptionNamesAtCurrentCommandDepth(branch, names, false);
-			return false;
-		case "argument":
-		case "literal":
-		case "passthrough":
-		case "ellipsis": return false;
-	}
-}
 function getRootMetaOptionSuggestions(helpOptionConfig, helpOptionNames, versionOptionConfig, versionOptionNames) {
 	const suggestions = [];
 	if (helpOptionConfig != null && !require_usage.isSuggestionHidden(helpOptionConfig.hidden)) suggestions.push(...helpOptionNames.map((name) => ({