@optique/core 1.4.0-dev.2622 → 1.4.0-dev.2623

package/dist/primitives.d.cts

@@ -104,7 +104,7 @@ interface OptionErrorOptions {
 /**
  * Creates a parser for various styles of command-line options that take an
  * argument value, such as `--option=value`, `-option=value`, `-o value`,
- * or `/option:value`.
+ * `-ovalue`, or `/option:value`.
  * @template M The execution mode of the parser.
  * @template T The type of value this parser produces.
  * @param args The {@link OptionName}s to parse, followed by
@@ -118,7 +118,7 @@ declare function option<M extends Mode, T>(...args: readonly [OptionName, ...rea
 /**
  * Creates a parser for various styles of command-line options that take an
  * argument value, such as `--option=value`, `-option=value`, `-o value`,
- * or `/option:value`.
+ * `-ovalue`, or `/option:value`.
  * @template M The execution mode of the parser.
  * @template T The type of value this parser produces.
  * @param args The {@link OptionName}s to parse, followed by
@@ -140,7 +140,7 @@ declare function option(...optionNames: readonly [OptionName, ...readonly Option
 /**
  * Creates a parser for various styles of command-line options that take an
  * argument value, such as `--option=value`, `-option=value`, `-o value`,
- * or `/option:value`.
+ * `-ovalue`, or `/option:value`.
  * @param args The {@link OptionName}s to parse, followed by
  *             an optional {@link OptionOptions} object that allows you to
  *             specify a description or other metadata.

package/dist/primitives.d.ts

@@ -104,7 +104,7 @@ interface OptionErrorOptions {
 /**
  * Creates a parser for various styles of command-line options that take an
  * argument value, such as `--option=value`, `-option=value`, `-o value`,
- * or `/option:value`.
+ * `-ovalue`, or `/option:value`.
  * @template M The execution mode of the parser.
  * @template T The type of value this parser produces.
  * @param args The {@link OptionName}s to parse, followed by
@@ -118,7 +118,7 @@ declare function option<M extends Mode, T>(...args: readonly [OptionName, ...rea
 /**
  * Creates a parser for various styles of command-line options that take an
  * argument value, such as `--option=value`, `-option=value`, `-o value`,
- * or `/option:value`.
+ * `-ovalue`, or `/option:value`.
  * @template M The execution mode of the parser.
  * @template T The type of value this parser produces.
  * @param args The {@link OptionName}s to parse, followed by
@@ -140,7 +140,7 @@ declare function option(...optionNames: readonly [OptionName, ...readonly Option
 /**
  * Creates a parser for various styles of command-line options that take an
  * argument value, such as `--option=value`, `-option=value`, `-o value`,
- * or `/option:value`.
+ * `-ovalue`, or `/option:value`.
  * @param args The {@link OptionName}s to parse, followed by
  *             an optional {@link OptionOptions} object that allows you to
  *             specify a description or other metadata.

package/dist/primitives.js

@@ -6,13 +6,14 @@ import { dispatchByMode, dispatchIterableByMode, wrapForMode } from "./internal/
 import { getDefaultValuesFunction, getDependencyIds, getSnapshottedDefaultDependencyValues, isDerivedValueParser, suggestWithDependency } from "./internal/dependency.js";
 import { effectfulSchedulingNodesKey, exclusiveSourceScopeKey, includeSourceFailureChain, recordDerivedRawInput, replayDerivedParser, replayDerivedParserAsync, sourceCollectionExpansionKey } from "./dependency-runtime.js";
 import { getWrappedChildParseState, getWrappedChildState, isAnnotationWrappedInitialState, normalizeInjectedAnnotationState } from "./annotation-state.js";
-import { hiddenCommandAliasesKey } from "./internal/command-alias.js";
 import { mergeChildExec, withChildContext, withChildExecPath } from "./execution-context.js";
+import { extractLeadingCommandNames } from "./usage-internals.js";
+import { attachedValuePrefix, combinedOptionScope, fullNameOwnsToken, prefixSuggestion, scopeParser, selectableOptionScope } from "./short-option.js";
+import { hiddenCommandAliasesKey } from "./internal/command-alias.js";
 import { completeOrExtractPhase2Seed, extractPhase2SeedKey } from "./phase2-seed.js";
 import { extractDependencyMetadata } from "./dependency-metadata.js";
 import { fluent } from "./modifiers.js";
 import { DEFAULT_FIND_SIMILAR_OPTIONS, createErrorWithSuggestions, createSuggestionMessage, expandCommandAliasSuggestions, findSimilar } from "./suggestion.js";
-import { extractLeadingCommandNames } from "./usage-internals.js";
 import { isValueParser } from "./valueparser.js";
 
 //#region src/primitives.ts
@@ -256,11 +257,25 @@ function* getSuggestionsWithDependency(valueParser, prefix, dependencyRegistry,
 */
 function* suggestOptionSync(optionNames$1, valueParser, hidden, description, context, prefix) {
 	if (hidden) return;
+	if (context.optionsTerminated) return;
+	const waitingForValue = context.buffer.length > 0 && optionNames$1.includes(context.buffer[context.buffer.length - 1]);
+	if (valueParser != null && !waitingForValue && !isTerminalValueState(context.state)) {
+		const attached = attachedValuePrefix(context, prefix, optionNames$1);
+		if (attached != null) {
+			if (attached.value.length === 0 && optionNames$1.includes(prefix)) yield {
+				kind: "literal",
+				text: prefix,
+				...description != null ? { description } : {}
+			};
+			if (valueParser.suggest != null) for (const suggestion of getSuggestionsWithDependency(valueParser, attached.value, context.dependencyRegistry, context.exec)) yield prefixSuggestion(attached.head, suggestion);
+			return;
+		}
+	}
 	const equalsIndex = prefix.indexOf("=");
-	if (equalsIndex >= 0) {
+	if (equalsIndex >= 0 && !waitingForValue) {
 		const optionPart = prefix.slice(0, equalsIndex);
 		const valuePart = prefix.slice(equalsIndex + 1);
-		if (optionNames$1.includes(optionPart)) {
+		if (optionNames$1.includes(optionPart) && !/^-[^-]$/u.test(optionPart)) {
 			if (valueParser && valueParser.suggest) {
 				const valueSuggestions = getSuggestionsWithDependency(valueParser, valuePart, context.dependencyRegistry, context.exec);
 				for (const suggestion of valueSuggestions) if (suggestion.kind === "literal") yield {
@@ -279,7 +294,7 @@ function* suggestOptionSync(optionNames$1, valueParser, hidden, description, con
 		const expectingValue = context.buffer.length > 0 && optionNames$1.includes(context.buffer[context.buffer.length - 1]);
 		if (!expectingValue && (prefix.startsWith("--") || prefix.startsWith("-") || prefix.startsWith("/") || prefix.startsWith("+"))) {
 			for (const optionName$1 of optionNames$1) if (optionName$1.startsWith(prefix)) {
-				if (prefix === "-" && optionName$1.length !== 2) continue;
+				if (prefix === "-" && !/^-[^-]$/u.test(optionName$1)) continue;
 				yield {
 					kind: "literal",
 					text: optionName$1,
@@ -341,11 +356,25 @@ async function* getSuggestionsWithDependencyAsync(valueParser, prefix, dependenc
 */
 async function* suggestOptionAsync(optionNames$1, valueParser, hidden, description, context, prefix) {
 	if (hidden) return;
+	if (context.optionsTerminated) return;
+	const waitingForValue = context.buffer.length > 0 && optionNames$1.includes(context.buffer[context.buffer.length - 1]);
+	if (valueParser != null && !waitingForValue && !isTerminalValueState(context.state)) {
+		const attached = attachedValuePrefix(context, prefix, optionNames$1);
+		if (attached != null) {
+			if (attached.value.length === 0 && optionNames$1.includes(prefix)) yield {
+				kind: "literal",
+				text: prefix,
+				...description != null ? { description } : {}
+			};
+			if (valueParser.suggest != null) for await (const suggestion of getSuggestionsWithDependencyAsync(valueParser, attached.value, context.dependencyRegistry, context.exec)) yield prefixSuggestion(attached.head, suggestion);
+			return;
+		}
+	}
 	const equalsIndex = prefix.indexOf("=");
-	if (equalsIndex >= 0) {
+	if (equalsIndex >= 0 && !waitingForValue) {
 		const optionPart = prefix.slice(0, equalsIndex);
 		const valuePart = prefix.slice(equalsIndex + 1);
-		if (optionNames$1.includes(optionPart)) {
+		if (optionNames$1.includes(optionPart) && !/^-[^-]$/u.test(optionPart)) {
 			if (valueParser && valueParser.suggest) {
 				const valueSuggestions = getSuggestionsWithDependencyAsync(valueParser, valuePart, context.dependencyRegistry, context.exec);
 				for await (const suggestion of valueSuggestions) if (suggestion.kind === "literal") yield {
@@ -364,7 +393,7 @@ async function* suggestOptionAsync(optionNames$1, valueParser, hidden, descripti
 		const expectingValue = context.buffer.length > 0 && optionNames$1.includes(context.buffer[context.buffer.length - 1]);
 		if (!expectingValue && (prefix.startsWith("--") || prefix.startsWith("-") || prefix.startsWith("/") || prefix.startsWith("+"))) {
 			for (const optionName$1 of optionNames$1) if (optionName$1.startsWith(prefix)) {
-				if (prefix === "-" && optionName$1.length !== 2) continue;
+				if (prefix === "-" && !/^-[^-]$/u.test(optionName$1)) continue;
 				yield {
 					kind: "literal",
 					text: optionName$1,
@@ -524,10 +553,18 @@ function option(...args) {
 					};
 				});
 			}
-			const prefixes = optionNames$1.filter((name) => name.startsWith("--") || name.startsWith("/") || name.startsWith("-") && name.length > 2).map((name) => name.startsWith("/") ? `${name}:` : `${name}=`);
-			for (const prefix of prefixes) {
+			const prefixes = optionNames$1.filter((name) => name.startsWith("--") || name.startsWith("/") || name.startsWith("-") && name.length > 2 && !/^-[^-]$/u.test(name)).map((name) => ({
+				optionName: name,
+				prefix: name.startsWith("/") ? `${name}:` : `${name}=`
+			}));
+			if (valueParser != null && optionNames$1.some((name) => /^-[^-]$/u.test(name) && context.buffer[0].startsWith(name)) && !fullNameOwnsToken(context, context.buffer[0])) {
+				for (const name of optionNames$1) if (/^-[^-]$/u.test(name)) prefixes.push({
+					optionName: name,
+					prefix: name
+				});
+			}
+			for (const { prefix, optionName: optionName$1 } of prefixes) {
 				if (!context.buffer[0].startsWith(prefix)) continue;
-				const optionName$1 = prefix.slice(0, -1);
 				if (hasParsedOptionValue(context.state, valueParser)) return {
 					success: false,
 					consumed: 1,
@@ -566,9 +603,9 @@ function option(...args) {
 				});
 			}
 			if (valueParser == null) {
-				const shortOptions = optionNames$1.filter((name) => name.match(/^-[^-]$/));
+				const shortOptions = optionNames$1.filter((name) => name.match(/^-[^-]$/u));
 				for (const shortOption of shortOptions) {
-					if (!context.buffer[0].startsWith(shortOption)) continue;
+					if (!context.buffer[0].startsWith(shortOption) || fullNameOwnsToken(context, context.buffer[0])) continue;
 					if (hasParsedOptionValue(context.state, valueParser)) return {
 						success: false,
 						consumed: 1,
@@ -582,9 +619,9 @@ function option(...args) {
 								success: true,
 								value: true
 							},
-							buffer: [`-${context.buffer[0].slice(2)}`, ...context.buffer.slice(1)]
+							buffer: [`-${context.buffer[0].slice(shortOption.length)}`, ...context.buffer.slice(1)]
 						},
-						consumed: [context.buffer[0].slice(0, 2)]
+						consumed: [context.buffer[0].slice(0, shortOption.length)]
 					};
 				}
 			}
@@ -846,7 +883,7 @@ function flag(...args) {
 					consumed: context.buffer.slice(0, 1)
 				};
 			}
-			const prefixes = optionNames$1.filter((name) => name.startsWith("--") || name.startsWith("/") || name.startsWith("-") && name.length > 2).map((name) => name.startsWith("/") ? `${name}:` : `${name}=`);
+			const prefixes = optionNames$1.filter((name) => name.startsWith("--") || name.startsWith("/") || name.startsWith("-") && name.length > 2 && !/^-[^-]$/u.test(name)).map((name) => name.startsWith("/") ? `${name}:` : `${name}=`);
 			for (const prefix of prefixes) if (context.buffer[0].startsWith(prefix)) {
 				const value = context.buffer[0].slice(prefix.length);
 				return {
@@ -855,9 +892,9 @@ function flag(...args) {
 					error: message`Flag ${optionName(prefix.slice(0, -1))} does not accept a value, but got: ${value}.`
 				};
 			}
-			const shortOptions = optionNames$1.filter((name) => name.match(/^-[^-]$/));
+			const shortOptions = optionNames$1.filter((name) => name.match(/^-[^-]$/u));
 			for (const shortOption of shortOptions) {
-				if (!context.buffer[0].startsWith(shortOption)) continue;
+				if (!context.buffer[0].startsWith(shortOption) || fullNameOwnsToken(context, context.buffer[0])) continue;
 				if (context.state?.success) return {
 					success: false,
 					consumed: 1,
@@ -871,9 +908,9 @@ function flag(...args) {
 							success: true,
 							value: true
 						},
-						buffer: [`-${context.buffer[0].slice(2)}`, ...context.buffer.slice(1)]
+						buffer: [`-${context.buffer[0].slice(shortOption.length)}`, ...context.buffer.slice(1)]
 					},
-					consumed: [context.buffer[0].slice(0, 2)]
+					consumed: [context.buffer[0].slice(0, shortOption.length)]
 				};
 			}
 			const invalidOption = context.buffer[0];
@@ -914,7 +951,7 @@ function flag(...args) {
 			const suggestions = [];
 			if (prefix.startsWith("--") || prefix.startsWith("-") || prefix.startsWith("/") || prefix.startsWith("+")) {
 				for (const optionName$1 of optionNames$1) if (optionName$1.startsWith(prefix)) {
-					if (prefix === "-" && optionName$1.length !== 2) continue;
+					if (prefix === "-" && !/^-[^-]$/u.test(optionName$1)) continue;
 					suggestions.push({
 						kind: "literal",
 						text: optionName$1,
@@ -1065,7 +1102,7 @@ function negatableFlag(names, options = {}) {
 			const directValue = valueByName.get(context.buffer[0]);
 			if (directValue != null) return parseMatchedNegatableFlag(context, context.buffer[0], directValue, context.buffer.slice(0, 1), 1, context.buffer.slice(1), options);
 			for (const name of optionNames$1) {
-				if (!name.startsWith("--") && !name.startsWith("/") && !name.startsWith("+") && !(name.startsWith("-") && name.length > 2)) continue;
+				if (!name.startsWith("--") && !name.startsWith("/") && !name.startsWith("+") && !(name.startsWith("-") && name.length > 2 && !/^-[^-]$/u.test(name))) continue;
 				const prefix = name.startsWith("/") ? `${name}:` : `${name}=`;
 				if (context.buffer[0].startsWith(prefix)) {
 					const value = context.buffer[0].slice(prefix.length);
@@ -1077,9 +1114,9 @@ function negatableFlag(names, options = {}) {
 				}
 			}
 			for (const shortOption of optionNames$1) {
-				if (!shortOption.match(/^-[^-]$/)) continue;
-				if (!context.buffer[0].startsWith(shortOption)) continue;
-				return parseMatchedNegatableFlag(context, shortOption, valueByName.get(shortOption), [context.buffer[0].slice(0, 2)], 1, [`-${context.buffer[0].slice(2)}`, ...context.buffer.slice(1)], options);
+				if (!shortOption.match(/^-[^-]$/u)) continue;
+				if (!context.buffer[0].startsWith(shortOption) || fullNameOwnsToken(context, context.buffer[0])) continue;
+				return parseMatchedNegatableFlag(context, shortOption, valueByName.get(shortOption), [context.buffer[0].slice(0, shortOption.length)], 1, [`-${context.buffer[0].slice(shortOption.length)}`, ...context.buffer.slice(1)], options);
 			}
 			const invalidOption = context.buffer[0];
 			if (options.errors?.noMatch) {
@@ -1114,7 +1151,7 @@ function negatableFlag(names, options = {}) {
 			const suggestions = [];
 			if (prefix.startsWith("--") || prefix.startsWith("-") || prefix.startsWith("/") || prefix.startsWith("+")) {
 				for (const optionName$1 of optionNames$1) if (optionName$1.startsWith(prefix)) {
-					if (prefix === "-" && optionName$1.length !== 2) continue;
+					if (prefix === "-" && !/^-[^-]$/u.test(optionName$1)) continue;
 					suggestions.push({
 						kind: "literal",
 						text: optionName$1
@@ -1487,6 +1524,8 @@ function command(name, parser, options = {}) {
 	const isAsync = parser.mode === "async";
 	const syncInnerParser = parser;
 	const asyncInnerParser = parser;
+	const commandScope = selectableOptionScope(() => new Set(commandNames));
+	const enteredScope = combinedOptionScope([parser], [name]);
 	const result = {
 		[Symbol.for("@optique/core/commandParser")]: true,
 		mode: parser.mode,
@@ -1554,6 +1593,7 @@ function command(name, parser, options = {}) {
 						] : baseError
 					};
 				}
+				commandScope.select(context, enteredScope);
 				return {
 					success: true,
 					next: {
@@ -1734,7 +1774,9 @@ function command(name, parser, options = {}) {
 		configurable: true,
 		enumerable: false
 	});
-	return fluent(result);
+	return fluent(scopeParser(result, commandScope.source, (context) => {
+		if (normalizeCommandState(context.state) != null) commandScope.select(context, enteredScope);
+	}));
 }
 /**
 * Creates a parser that collects unrecognized options and passes them through.

package/dist/short-option.cjs

@@ -0,0 +1,311 @@
+const require_internal_annotations = require('./internal/annotations.cjs');
+const require_usage = require('./usage.cjs');
+const require_mode_dispatch = require('./internal/mode-dispatch.cjs');
+const require_execution_context = require('./execution-context.cjs');
+const require_usage_internals = require('./usage-internals.cjs');
+
+//#region src/short-option.ts
+const optionScopeKey = Symbol("optionScope");
+const optionPathKey = Symbol("optionScopePath");
+const scopeSourceKey = Symbol("optionScopeSource");
+const scopeLocations = /* @__PURE__ */ new WeakMap();
+const scopeBindings = /* @__PURE__ */ new WeakMap();
+function getScopeBindings(selections) {
+	let bindings = scopeBindings.get(selections);
+	if (bindings == null) {
+		bindings = /* @__PURE__ */ new WeakMap();
+		scopeBindings.set(selections, bindings);
+	}
+	return bindings;
+}
+function bindScope(source, path, selections) {
+	const boundScopes = getScopeBindings(selections);
+	let node = boundScopes.get(source);
+	if (node == null) {
+		node = {
+			children: /* @__PURE__ */ new Map(),
+			bound: (selections$1, arities, context) => source(selections$1, arities, context, [])
+		};
+		boundScopes.set(source, node);
+		scopeLocations.set(node.bound, []);
+	}
+	for (let i = 0; i < path.length; i++) {
+		let child = node.children.get(path[i]);
+		if (child == null) {
+			const occurrence = path.slice(0, i + 1);
+			child = {
+				children: /* @__PURE__ */ new Map(),
+				bound: (selections$1, arities, context) => source(selections$1, arities, context, occurrence)
+			};
+			node.children.set(path[i], child);
+			scopeLocations.set(child.bound, occurrence);
+		}
+		node = child;
+	}
+	return node.bound;
+}
+function scopePath(context) {
+	return context.exec?.path ?? context[optionPathKey] ?? [];
+}
+/** Tracks child occurrences even for contexts without execution metadata. @internal */
+function withOptionScopeChild(context, segment) {
+	return {
+		...context,
+		[optionPathKey]: [...scopePath(context), segment]
+	};
+}
+const primitiveScopes = /* @__PURE__ */ new WeakMap();
+function parserScope(parser) {
+	const declared = parser[scopeSourceKey];
+	if (declared != null) return declared;
+	let source = primitiveScopes.get(parser);
+	if (source == null) {
+		source = (_selections, arities) => {
+			if (arities != null) require_usage_internals.collectOptionNamesAtCurrentCommandDepth(parser.usage, arities, false);
+			return parser.leadingNames;
+		};
+		primitiveScopes.set(parser, source);
+	}
+	return source;
+}
+/** Preserves dynamic option ownership through a transparent wrapper. @internal */
+function inheritOptionScope(target, inner) {
+	Object.defineProperty(target, scopeSourceKey, {
+		value: parserScope(inner),
+		enumerable: true,
+		configurable: true
+	});
+}
+/** Combines declarations without flattening conditional ownership. @internal */
+function combinedOptionScope(parsers, segments) {
+	return (selections, arities, context, path = []) => new Set(parsers.flatMap((parser, index) => [...parserScope(parser)(selections, arities, context, segments == null ? path : [...path, segments[index]])]));
+}
+/** Evaluates repeated declarations at their actual item occurrences. @internal */
+function repeatedOptionScope(parser) {
+	return (selections, arities, context, path = []) => {
+		const indices = /* @__PURE__ */ new Set();
+		const collect = (location) => {
+			if (location != null && path.every((segment, index) => location[index] === segment)) {
+				const index = location[path.length];
+				if (typeof index === "number") indices.add(index);
+			}
+		};
+		for (const selected of selections.keys()) collect(scopeLocations.get(selected));
+		if (context != null) collect(scopePath(context));
+		if (indices.size === 0) indices.add(0);
+		return new Set([...indices].flatMap((index) => [...parserScope(parser)(selections, arities, context, [...path, index])]));
+	};
+}
+/** Tracks declarations after a command or discriminator routes input. @internal */
+function selectableOptionScope(initial) {
+	const source = (selections, arities, context, path = []) => (selections.get(bindScope(source, path, selections)) ?? initial)(selections, arities, context, path);
+	return {
+		source,
+		select(context, selected) {
+			const selections = context[optionScopeKey]?.selections;
+			if (selections == null) return;
+			selections.set(bindScope(source, scopePath(context), selections), selected);
+		}
+	};
+}
+/** Keeps selected conditional names distinct from sibling declarations. @internal */
+function conditionalOptionScope(discriminator, fallback, candidates = []) {
+	const scope = selectableOptionScope((selections, arities, context, path) => {
+		const canSkip = discriminator.canSkip?.(context == null ? discriminator.initialState : require_internal_annotations.inheritAnnotations(context.state, discriminator.initialState), context?.exec == null ? void 0 : require_execution_context.withChildExecPath({
+			...context.exec,
+			path: path ?? scopePath(context)
+		}, "_discriminator")) === true;
+		return combinedOptionScope([
+			discriminator,
+			...canSkip ? candidates : [],
+			...fallback == null ? [] : [fallback]
+		], [
+			"_discriminator",
+			...canSkip ? candidates.map(() => "_branch") : [],
+			...fallback == null ? [] : ["_branch"]
+		])(selections, arities, context, path);
+	});
+	return {
+		source: scope.source,
+		select(context, branch) {
+			scope.select(context, combinedOptionScope([discriminator, branch], ["_discriminator", "_branch"]));
+		}
+	};
+}
+/** Returns the names reachable in this parse scope. @internal */
+function getOptionScope(context) {
+	const scoped = context[optionScopeKey];
+	const names = scoped == null ? require_usage.extractOptionNames(context.usage, true) : new Set([...scoped.names, ...[...scoped.sources].flatMap((source) => [...source(scoped.selections, void 0, context)])]);
+	return names;
+}
+/** Adds reachable names without consulting the flattened help tree. @internal */
+function withOptionScope(context, names) {
+	const inherited = context[optionScopeKey];
+	return {
+		...context,
+		[optionScopeKey]: {
+			names: new Set([...inherited?.names ?? [], ...names]),
+			sources: inherited?.sources ?? /* @__PURE__ */ new Set(),
+			selections: inherited?.selections ?? /* @__PURE__ */ new Map()
+		}
+	};
+}
+/** Adds a parser's owned declarations, retaining modifier metadata. @internal */
+function withParserOptionScope(context, parser, segment) {
+	const inherited = context[optionScopeKey];
+	const selections = inherited?.selections ?? /* @__PURE__ */ new Map();
+	return {
+		...context,
+		[optionScopeKey]: {
+			names: inherited?.names ?? /* @__PURE__ */ new Set(),
+			sources: new Set([...inherited?.sources ?? [], bindScope(parserScope(parser), segment == null ? scopePath(context) : [...scopePath(context), segment], selections)]),
+			selections
+		}
+	};
+}
+/** Isolates route selections while probing a competing branch. @internal */
+function forkOptionScope(context) {
+	const scoped = context[optionScopeKey];
+	if (scoped == null) return context;
+	const selections = new Map(scoped.selections);
+	scopeBindings.set(selections, getScopeBindings(scoped.selections));
+	return {
+		...context,
+		[optionScopeKey]: {
+			...scoped,
+			selections
+		}
+	};
+}
+/** Publishes winning routes without persisting temporary candidate names. @internal */
+function adoptOptionScope(context, next) {
+	const own = context[optionScopeKey];
+	const child = next[optionScopeKey];
+	if (own != null && child != null) for (const [source, selected] of child.selections) own.selections.set(source, selected);
+	return context;
+}
+/** Removes names reserved only for a speculative probe. @internal */
+function restoreOptionScope(next, parent) {
+	adoptOptionScope(parent, next);
+	const own = parent[optionScopeKey];
+	const child = next[optionScopeKey];
+	return own == null || child == null ? next : {
+		...next,
+		[optionScopeKey]: {
+			...child,
+			names: own.names,
+			selections: own.selections
+		}
+	};
+}
+/** Decorates construct entry points while retaining internal metadata. @internal */
+function scopeParser(parser, source = () => parser.leadingNames, prepare, isolate = false) {
+	const parse = parser.parse;
+	const suggest = parser.suggest;
+	Object.defineProperties(parser, {
+		[scopeSourceKey]: {
+			value: source,
+			enumerable: true
+		},
+		parse: {
+			enumerable: true,
+			configurable: true,
+			writable: true,
+			value: (context) => {
+				const scoped = withParserOptionScope(isolate ? forkOptionScope(context) : context, parser);
+				prepare?.(scoped);
+				return require_mode_dispatch.mapModeValue(parser.mode, parse.call(parser, scoped), (result) => {
+					if (!result.success) return result;
+					let next = result.next;
+					if (isolate) {
+						adoptOptionScope(context, next);
+						const parent = context[optionScopeKey];
+						const child = next[optionScopeKey];
+						if (parent != null && child != null) next = {
+							...next,
+							[optionScopeKey]: {
+								...child,
+								selections: parent.selections
+							}
+						};
+					}
+					return {
+						...result,
+						next: {
+							...next,
+							[optionPathKey]: scopePath(context)
+						}
+					};
+				});
+			}
+		},
+		suggest: {
+			enumerable: true,
+			configurable: true,
+			writable: true,
+			value: (context, prefix) => {
+				const scoped = withParserOptionScope(context, parser);
+				prepare?.(scoped);
+				return suggest.call(parser, scoped, prefix);
+			}
+		}
+	});
+	return parser;
+}
+/** Tests full-name ownership before splitting a short prefix. @internal */
+function fullNameOwnsToken(context, token) {
+	if (!/^-[^-]/.test(token)) return false;
+	for (const name of getOptionScope(context)) if (name.startsWith("-") && !name.startsWith("--") && name.length > 2 && !/^-[^-]$/u.test(name) && (token === name || token.startsWith(`${name}=`))) return true;
+	return false;
+}
+/** Finds the value part of an attached short-option completion. @internal */
+function attachedValuePrefix(context, prefix, optionNames) {
+	if (!/^-[^-]/.test(prefix)) return void 0;
+	const scope = getOptionScope(context);
+	const names = {
+		value: /* @__PURE__ */ new Set(),
+		flag: /* @__PURE__ */ new Set()
+	};
+	const scoped = context[optionScopeKey];
+	if (scoped == null) require_usage_internals.collectOptionNamesAtCurrentCommandDepth(context.usage, names, false);
+	else for (const source of scoped.sources) source(scoped.selections, names, context);
+	for (let index = 1; index < prefix.length;) {
+		const character = String.fromCodePoint(prefix.codePointAt(index));
+		const nextIndex = index + character.length;
+		const remainder = `-${prefix.slice(index)}`;
+		for (const name of scope) if (name.startsWith("-") && !name.startsWith("--") && name.length > 2 && !/^-[^-]$/u.test(name) && (name.startsWith(remainder) || remainder.startsWith(`${name}=`))) return void 0;
+		const short = `-${character}`;
+		if (optionNames.includes(short)) return {
+			head: prefix.slice(0, nextIndex),
+			value: prefix.slice(nextIndex)
+		};
+		if (!scope.has(short) || !names.flag.has(short) || names.value.has(short)) return void 0;
+		index = nextIndex;
+	}
+	return void 0;
+}
+/** Preserves the prefix when embedding value suggestions in one token. @internal */
+function prefixSuggestion(head, suggestion) {
+	return {
+		kind: "literal",
+		text: head + (suggestion.kind === "literal" ? suggestion.text : suggestion.pattern ?? ""),
+		...suggestion.description != null ? { description: suggestion.description } : {}
+	};
+}
+
+//#endregion
+exports.adoptOptionScope = adoptOptionScope;
+exports.attachedValuePrefix = attachedValuePrefix;
+exports.combinedOptionScope = combinedOptionScope;
+exports.conditionalOptionScope = conditionalOptionScope;
+exports.forkOptionScope = forkOptionScope;
+exports.fullNameOwnsToken = fullNameOwnsToken;
+exports.inheritOptionScope = inheritOptionScope;
+exports.prefixSuggestion = prefixSuggestion;
+exports.repeatedOptionScope = repeatedOptionScope;
+exports.restoreOptionScope = restoreOptionScope;
+exports.scopeParser = scopeParser;
+exports.selectableOptionScope = selectableOptionScope;
+exports.withOptionScope = withOptionScope;
+exports.withOptionScopeChild = withOptionScopeChild;
+exports.withParserOptionScope = withParserOptionScope;