@optique/core 1.1.8 → 1.1.10

package/dist/displaywidth.cjs

@@ -16,6 +16,17 @@ function getDisplayWidth(text) {
 	for (const { segment } of segmenter.segment(stripped)) width += graphemeWidth(segment);
 	return width;
 }
+/**
+* Removes ANSI escape sequences (CSI and OSC) from a string, leaving only
+* the text a terminal would print.
+*
+* @param text The string to strip.
+* @returns The string without ANSI escape sequences.
+* @internal
+*/
+function stripAnsi(text) {
+	return text.replace(ansiRegex, "");
+}
 const zeroWidthRegex = /^[\p{Cf}\p{Mn}\p{Me}]+$/u;
 const emojiPresentationRegex = /\p{Emoji_Presentation}/u;
 const emojiWithVS16Regex = /\p{Emoji}\uFE0F/u;
@@ -41,4 +52,5 @@ function isEastAsianWide(cp) {
 }
 
 //#endregion
-exports.getDisplayWidth = getDisplayWidth;
+exports.getDisplayWidth = getDisplayWidth;
+exports.stripAnsi = stripAnsi;

package/dist/displaywidth.d.cts

@@ -8,5 +8,14 @@
  * @internal
  */
 declare function getDisplayWidth(text: string): number;
+/**
+ * Removes ANSI escape sequences (CSI and OSC) from a string, leaving only
+ * the text a terminal would print.
+ *
+ * @param text The string to strip.
+ * @returns The string without ANSI escape sequences.
+ * @internal
+ */
+declare function stripAnsi(text: string): string;
 //#endregion
-export { getDisplayWidth };
+export { getDisplayWidth, stripAnsi };

package/dist/displaywidth.d.ts

@@ -8,5 +8,14 @@
  * @internal
  */
 declare function getDisplayWidth(text: string): number;
+/**
+ * Removes ANSI escape sequences (CSI and OSC) from a string, leaving only
+ * the text a terminal would print.
+ *
+ * @param text The string to strip.
+ * @returns The string without ANSI escape sequences.
+ * @internal
+ */
+declare function stripAnsi(text: string): string;
 //#endregion
-export { getDisplayWidth };
+export { getDisplayWidth, stripAnsi };

package/dist/displaywidth.js

@@ -15,6 +15,17 @@ function getDisplayWidth(text) {
 	for (const { segment } of segmenter.segment(stripped)) width += graphemeWidth(segment);
 	return width;
 }
+/**
+* Removes ANSI escape sequences (CSI and OSC) from a string, leaving only
+* the text a terminal would print.
+*
+* @param text The string to strip.
+* @returns The string without ANSI escape sequences.
+* @internal
+*/
+function stripAnsi(text) {
+	return text.replace(ansiRegex, "");
+}
 const zeroWidthRegex = /^[\p{Cf}\p{Mn}\p{Me}]+$/u;
 const emojiPresentationRegex = /\p{Emoji_Presentation}/u;
 const emojiWithVS16Regex = /\p{Emoji}\uFE0F/u;
@@ -40,4 +51,4 @@ function isEastAsianWide(cp) {
 }
 
 //#endregion
-export { getDisplayWidth };
+export { getDisplayWidth, stripAnsi };

package/dist/doc.cjs

@@ -341,13 +341,15 @@ function formatDocPage(programName, page, options = {}) {
 				const suffix = typeof options.showDefault === "object" ? options.showDefault.suffix ?? "]" : "]";
 				const prefixWidth = require_displaywidth.getDisplayWidth(prefix);
 				const suffixWidth = require_displaywidth.getDisplayWidth(suffix);
+				let defaultPrefix = prefix;
 				let defaultStartWidth;
 				if (descColumnWidth != null) {
 					const lastW = lastLineVisibleLength(description);
 					const effectiveLastW = lastW + currentExtraOffset();
 					if (effectiveLastW + prefixWidth >= descColumnWidth) {
 						description += "\n";
-						defaultStartWidth = prefixWidth;
+						defaultPrefix = prefix.trimStart();
+						defaultStartWidth = require_displaywidth.getDisplayWidth(defaultPrefix);
 					} else defaultStartWidth = effectiveLastW + prefixWidth;
 				}
 				const defaultFormatOptions = {
@@ -357,7 +359,7 @@ function formatDocPage(programName, page, options = {}) {
 					startWidth: defaultStartWidth
 				};
 				const defaultContent = require_message.formatMessage(entry.default, defaultFormatOptions);
-				const defaultText = `${prefix}${defaultContent}${suffix}`;
+				const defaultText = `${defaultPrefix}${defaultContent}${suffix}`;
 				const formattedDefault = options.colors ? `\x1b[2m${defaultText}\x1b[0m` : defaultText;
 				description += formattedDefault;
 			}
@@ -385,6 +387,7 @@ function formatDocPage(programName, page, options = {}) {
 				const choicesPrefixWidth = require_displaywidth.getDisplayWidth(prefix);
 				const choicesSuffixWidth = require_displaywidth.getDisplayWidth(suffix);
 				const choicesLabelWidth = require_displaywidth.getDisplayWidth(label);
+				let choicesHeading = `${prefix}${label}`;
 				let choicesStartWidth;
 				if (descColumnWidth != null) {
 					const lastW = lastLineVisibleLength(description);
@@ -392,7 +395,8 @@ function formatDocPage(programName, page, options = {}) {
 					const prefixLabelLen = choicesPrefixWidth + choicesLabelWidth;
 					if (effectiveLastW + prefixLabelLen >= descColumnWidth) {
 						description += "\n";
-						choicesStartWidth = prefixLabelLen;
+						choicesHeading = choicesHeading.trimStart();
+						choicesStartWidth = require_displaywidth.getDisplayWidth(choicesHeading);
 					} else choicesStartWidth = effectiveLastW + prefixLabelLen;
 				}
 				const choicesFormatOptions = {
@@ -402,7 +406,7 @@ function formatDocPage(programName, page, options = {}) {
 					startWidth: choicesStartWidth
 				};
 				const choicesDisplay = require_message.formatMessage(truncatedTerms, choicesFormatOptions);
-				const choicesText = `${prefix}${label}${choicesDisplay}${suffix}`;
+				const choicesText = `${choicesHeading}${choicesDisplay}${suffix}`;
 				const formattedChoices = options.colors ? `\x1b[2m${choicesText}\x1b[0m` : choicesText;
 				description += formattedChoices;
 			}

package/dist/doc.js

@@ -341,13 +341,15 @@ function formatDocPage(programName, page, options = {}) {
 				const suffix = typeof options.showDefault === "object" ? options.showDefault.suffix ?? "]" : "]";
 				const prefixWidth = getDisplayWidth(prefix);
 				const suffixWidth = getDisplayWidth(suffix);
+				let defaultPrefix = prefix;
 				let defaultStartWidth;
 				if (descColumnWidth != null) {
 					const lastW = lastLineVisibleLength(description);
 					const effectiveLastW = lastW + currentExtraOffset();
 					if (effectiveLastW + prefixWidth >= descColumnWidth) {
 						description += "\n";
-						defaultStartWidth = prefixWidth;
+						defaultPrefix = prefix.trimStart();
+						defaultStartWidth = getDisplayWidth(defaultPrefix);
 					} else defaultStartWidth = effectiveLastW + prefixWidth;
 				}
 				const defaultFormatOptions = {
@@ -357,7 +359,7 @@ function formatDocPage(programName, page, options = {}) {
 					startWidth: defaultStartWidth
 				};
 				const defaultContent = formatMessage(entry.default, defaultFormatOptions);
-				const defaultText = `${prefix}${defaultContent}${suffix}`;
+				const defaultText = `${defaultPrefix}${defaultContent}${suffix}`;
 				const formattedDefault = options.colors ? `\x1b[2m${defaultText}\x1b[0m` : defaultText;
 				description += formattedDefault;
 			}
@@ -385,6 +387,7 @@ function formatDocPage(programName, page, options = {}) {
 				const choicesPrefixWidth = getDisplayWidth(prefix);
 				const choicesSuffixWidth = getDisplayWidth(suffix);
 				const choicesLabelWidth = getDisplayWidth(label);
+				let choicesHeading = `${prefix}${label}`;
 				let choicesStartWidth;
 				if (descColumnWidth != null) {
 					const lastW = lastLineVisibleLength(description);
@@ -392,7 +395,8 @@ function formatDocPage(programName, page, options = {}) {
 					const prefixLabelLen = choicesPrefixWidth + choicesLabelWidth;
 					if (effectiveLastW + prefixLabelLen >= descColumnWidth) {
 						description += "\n";
-						choicesStartWidth = prefixLabelLen;
+						choicesHeading = choicesHeading.trimStart();
+						choicesStartWidth = getDisplayWidth(choicesHeading);
 					} else choicesStartWidth = effectiveLastW + prefixLabelLen;
 				}
 				const choicesFormatOptions = {
@@ -402,7 +406,7 @@ function formatDocPage(programName, page, options = {}) {
 					startWidth: choicesStartWidth
 				};
 				const choicesDisplay = formatMessage(truncatedTerms, choicesFormatOptions);
-				const choicesText = `${prefix}${label}${choicesDisplay}${suffix}`;
+				const choicesText = `${choicesHeading}${choicesDisplay}${suffix}`;
 				const formattedChoices = options.colors ? `\x1b[2m${choicesText}\x1b[0m` : choicesText;
 				description += formattedChoices;
 			}

package/dist/extension.cjs

@@ -2,6 +2,7 @@ const require_internal_annotations = require('./internal/annotations.cjs');
 const require_mode_dispatch = require('./internal/mode-dispatch.cjs');
 const require_internal_parser = require('./internal/parser.cjs');
 const require_annotation_state = require('./annotation-state.cjs');
+const require_passthrough = require('./internal/passthrough.cjs');
 
 //#region src/extension.ts
 const emptyTraits = Object.freeze({});
@@ -71,9 +72,25 @@ function delegateSuggestNodes(innerParser, outerParser, state, path, innerState,
 function mapSourceMetadata(parser, mapSource) {
 	return require_internal_parser.composeWrappedSourceMetadata(parser.dependencyMetadata, mapSource);
 }
+/**
+* Delegates CLI option matching and capture priority through a parser wrapper.
+* Use the same child-state projection as the wrapper's parse method. This
+* preserves selected command options without changing public leading names.
+*
+* @param wrapper The parser being constructed.
+* @param inner Its wrapped CLI parser.
+* @param getInnerState Projects the wrapper state to the CLI parser state.
+* @throws {TypeError} If metadata cannot be defined on the wrapper.
+* @since 1.0.11
+*/
+function delegateOptionParsing(wrapper, inner, getInnerState) {
+	require_passthrough.defineOptionMatch(wrapper, (state, token) => require_passthrough.getOptionMatch(inner, getInnerState(state), token));
+	require_passthrough.definePassThroughPriority(wrapper, [inner], (state, token) => require_passthrough.getPassThroughPriority(inner, getInnerState(state), token));
+}
 
 //#endregion
 exports.defineTraits = defineTraits;
+exports.delegateOptionParsing = delegateOptionParsing;
 exports.delegateSuggestNodes = delegateSuggestNodes;
 exports.dispatchByMode = require_mode_dispatch.dispatchByMode;
 exports.getTraits = getTraits;

package/dist/extension.d.cts

@@ -93,5 +93,17 @@ declare function delegateSuggestNodes<TInnerState>(innerParser: Parser<Mode, unk
  * @since 1.0.0
  */
 declare function mapSourceMetadata<M extends Mode, TValue, TState>(parser: Pick<Parser<M, TValue, TState>, "dependencyMetadata">, mapSource: (source: ParserSourceMetadata<M, TValue, TState>) => ParserSourceMetadata<M, TValue, TState>): Parser<M, TValue, TState>["dependencyMetadata"] | undefined;
+/**
+ * Delegates CLI option matching and capture priority through a parser wrapper.
+ * Use the same child-state projection as the wrapper's parse method. This
+ * preserves selected command options without changing public leading names.
+ *
+ * @param wrapper The parser being constructed.
+ * @param inner Its wrapped CLI parser.
+ * @param getInnerState Projects the wrapper state to the CLI parser state.
+ * @throws {TypeError} If metadata cannot be defined on the wrapper.
+ * @since 1.0.11
+ */
+declare function delegateOptionParsing<TOuterState, TInnerState>(wrapper: Parser<Mode, unknown, TOuterState>, inner: Parser<Mode, unknown, TInnerState>, getInnerState: (state: TOuterState) => TInnerState): void;
 //#endregion
-export { ParserSourceMetadata, ParserTraits, SuggestNode, defineTraits, delegateSuggestNodes, dispatchByMode, getTraits, inheritAnnotations, injectAnnotations, isInjectedAnnotationState, mapModeValue, mapSourceMetadata, unwrapInjectedAnnotationState, withAnnotationView, wrapForMode };
+export { ParserSourceMetadata, ParserTraits, SuggestNode, defineTraits, delegateOptionParsing, delegateSuggestNodes, dispatchByMode, getTraits, inheritAnnotations, injectAnnotations, isInjectedAnnotationState, mapModeValue, mapSourceMetadata, unwrapInjectedAnnotationState, withAnnotationView, wrapForMode };

package/dist/extension.d.ts

@@ -93,5 +93,17 @@ declare function delegateSuggestNodes<TInnerState>(innerParser: Parser<Mode, unk
  * @since 1.0.0
  */
 declare function mapSourceMetadata<M extends Mode, TValue, TState>(parser: Pick<Parser<M, TValue, TState>, "dependencyMetadata">, mapSource: (source: ParserSourceMetadata<M, TValue, TState>) => ParserSourceMetadata<M, TValue, TState>): Parser<M, TValue, TState>["dependencyMetadata"] | undefined;
+/**
+ * Delegates CLI option matching and capture priority through a parser wrapper.
+ * Use the same child-state projection as the wrapper's parse method. This
+ * preserves selected command options without changing public leading names.
+ *
+ * @param wrapper The parser being constructed.
+ * @param inner Its wrapped CLI parser.
+ * @param getInnerState Projects the wrapper state to the CLI parser state.
+ * @throws {TypeError} If metadata cannot be defined on the wrapper.
+ * @since 1.0.11
+ */
+declare function delegateOptionParsing<TOuterState, TInnerState>(wrapper: Parser<Mode, unknown, TOuterState>, inner: Parser<Mode, unknown, TInnerState>, getInnerState: (state: TOuterState) => TInnerState): void;
 //#endregion
-export { ParserSourceMetadata, ParserTraits, SuggestNode, defineTraits, delegateSuggestNodes, dispatchByMode, getTraits, inheritAnnotations, injectAnnotations, isInjectedAnnotationState, mapModeValue, mapSourceMetadata, unwrapInjectedAnnotationState, withAnnotationView, wrapForMode };
+export { ParserSourceMetadata, ParserTraits, SuggestNode, defineTraits, delegateOptionParsing, delegateSuggestNodes, dispatchByMode, getTraits, inheritAnnotations, injectAnnotations, isInjectedAnnotationState, mapModeValue, mapSourceMetadata, unwrapInjectedAnnotationState, withAnnotationView, wrapForMode };

package/dist/extension.js

@@ -2,6 +2,7 @@ import { inheritAnnotations, injectAnnotations, isInjectedAnnotationState, unwra
 import { dispatchByMode, mapModeValue, wrapForMode } from "./internal/mode-dispatch.js";
 import { annotationWrapperRequiresSourceBindingKey, composeWrappedSourceMetadata, defineInheritedAnnotationParser, getDelegatingSuggestRuntimeNodes, inheritParentAnnotationsKey, unmatchedNonCliDependencySourceStateMarker } from "./internal/parser.js";
 import { withAnnotationView } from "./annotation-state.js";
+import { defineOptionMatch, definePassThroughPriority, getOptionMatch, getPassThroughPriority } from "./internal/passthrough.js";
 
 //#region src/extension.ts
 const emptyTraits = Object.freeze({});
@@ -71,6 +72,21 @@ function delegateSuggestNodes(innerParser, outerParser, state, path, innerState,
 function mapSourceMetadata(parser, mapSource) {
 	return composeWrappedSourceMetadata(parser.dependencyMetadata, mapSource);
 }
+/**
+* Delegates CLI option matching and capture priority through a parser wrapper.
+* Use the same child-state projection as the wrapper's parse method. This
+* preserves selected command options without changing public leading names.
+*
+* @param wrapper The parser being constructed.
+* @param inner Its wrapped CLI parser.
+* @param getInnerState Projects the wrapper state to the CLI parser state.
+* @throws {TypeError} If metadata cannot be defined on the wrapper.
+* @since 1.0.11
+*/
+function delegateOptionParsing(wrapper, inner, getInnerState) {
+	defineOptionMatch(wrapper, (state, token) => getOptionMatch(inner, getInnerState(state), token));
+	definePassThroughPriority(wrapper, [inner], (state, token) => getPassThroughPriority(inner, getInnerState(state), token));
+}
 
 //#endregion
-export { defineTraits, delegateSuggestNodes, dispatchByMode, getTraits, inheritAnnotations, injectAnnotations, isInjectedAnnotationState, mapModeValue, mapSourceMetadata, unwrapInjectedAnnotationState, withAnnotationView, wrapForMode };
+export { defineTraits, delegateOptionParsing, delegateSuggestNodes, dispatchByMode, getTraits, inheritAnnotations, injectAnnotations, isInjectedAnnotationState, mapModeValue, mapSourceMetadata, unwrapInjectedAnnotationState, withAnnotationView, wrapForMode };

package/dist/internal/passthrough.cjs

@@ -0,0 +1,230 @@
+
+//#region src/internal/passthrough.ts
+/** Retains the deepest diagnostic and highest matching lane priority. @internal */
+function retainConsumingFailure(current, failure, priority) {
+	return {
+		failure: current != null && current.failure.consumed >= failure.consumed ? current.failure : failure,
+		priority: Math.max(current?.priority ?? -Infinity, priority)
+	};
+}
+const passThroughFailure = Symbol("passThroughFailure");
+/**
+* Gets the sibling failure that prevents pass-through capture at this cursor.
+* Stale hints inherited through a successful child do not block later input.
+* @param context The pass-through parser's context.
+* @returns The failure at this cursor, or undefined if capture is allowed.
+* @internal
+*/
+function getPassThroughFailure(context, capturePriority$1 = -Infinity) {
+	const hinted = context;
+	const hint = hinted[passThroughFailure];
+	return hint?.buffer === context.buffer && hint.optionsTerminated === context.optionsTerminated && hint.failure.priority >= capturePriority$1 ? hint.failure : void 0;
+}
+/**
+* Carries a sibling's consuming failure into a child parse call. Only
+* passThrough consults the hint; ordinary alternatives may still recover.
+* @param context The child context, without modifying the parent's context.
+* @param failure The deepest matching consuming failure at this input position.
+* @returns A context with a hint for active option-like input, or the original.
+* @internal
+*/
+function withPassThroughFailure(context, failure, capturePriority$1 = -Infinity) {
+	const token = context.buffer[0];
+	const existing = getPassThroughFailure(context);
+	if (existing != null && existing.priority < capturePriority$1) {
+		const hinted$1 = context;
+		const { [passThroughFailure]: _discarded,...rest } = hinted$1;
+		context = rest;
+	}
+	if (failure == null || failure.failure.consumed < 1 || failure.priority < capturePriority$1 || context.optionsTerminated || token == null || token === "--" || !/^[-/+]/.test(token)) return context;
+	const retained = getPassThroughFailure(context);
+	const combined = retainConsumingFailure(retained, failure.failure, failure.priority);
+	const hinted = {
+		...context,
+		[passThroughFailure]: {
+			buffer: context.buffer,
+			optionsTerminated: context.optionsTerminated,
+			failure: combined
+		}
+	};
+	return hinted;
+}
+/** Retains a child's rejected option failure only at the parent's cursor. @internal */
+function retainConsumingFailureHint(current, context, next) {
+	if (next.buffer !== context.buffer || next.optionsTerminated !== context.optionsTerminated) return current;
+	const hint = getPassThroughFailure(next);
+	return hint == null ? current : retainConsumingFailure(current, hint.failure, hint.priority);
+}
+const capturePriority = Symbol("capturePriority");
+/** Checks for capture through usage-preserving wrappers. @internal */
+function hasPassThroughUsage(usage) {
+	return usage.some((term) => term.type === "passthrough" || (term.type === "optional" || term.type === "multiple") && hasPassThroughUsage(term.terms) || term.type === "exclusive" && term.terms.some(hasPassThroughUsage));
+}
+/**
+* Gets the priority of reachable capture, respecting an explicit override.
+* @param parser The parser whose capture priority is needed.
+* @param state The current parser state.
+* @param token The current token, omitted for an unfiltered priority lookup.
+* @returns The capture priority, or undefined when capture is absent.
+* @internal
+*/
+function getPassThroughPriority(parser, state = parser.initialState, token) {
+	if (!hasPassThroughUsage(parser.usage)) return void 0;
+	const annotated = parser;
+	const hint = annotated[capturePriority];
+	if (hint == null) return parser.priority;
+	const priority = hint.getPriority == null ? hint.priority : hint.getPriority(state, token);
+	return priority == null ? void 0 : hint.ownerPriority === parser.priority ? priority : parser.priority;
+}
+/**
+* Records capture priority separately from unrelated children's priorities.
+* @param parser The newly constructed parser.
+* @param children Its transparent children.
+* @param getPriority Optional state-aware capture priority lookup.
+* @internal
+*/
+function definePassThroughPriority(parser, children, getPriority) {
+	const priorities = children.filter((child) => hasPassThroughUsage(child.usage)).map((child) => getPassThroughPriority(child) ?? child.priority);
+	if (priorities.length === 0) return;
+	Object.defineProperty(parser, capturePriority, {
+		value: {
+			ownerPriority: parser.priority,
+			priority: Math.max(...priorities),
+			getPriority
+		},
+		enumerable: true
+	});
+}
+/**
+* Copies only a cursor-valid hint when rebuilding a child context.
+* @param context The successful child's context.
+* @returns Private hint properties, or an empty object for stale hints.
+* @internal
+*/
+function getPassThroughFailureHint(context) {
+	const hinted = context;
+	const hint = hinted[passThroughFailure];
+	return hint != null && getPassThroughFailure(context) != null ? { [passThroughFailure]: hint } : {};
+}
+/** Finds a Boolean option through usage-preserving wrappers. */
+function hasFlagUsage(usage, name) {
+	return usage.some((term) => term.type === "option" && term.metavar == null && term.names.some((optionName) => optionName === name) || (term.type === "optional" || term.type === "multiple") && hasFlagUsage(term.terms, name) || term.type === "exclusive" && term.terms.some((terms) => hasFlagUsage(terms, name)));
+}
+/** Matches exact options, attached values, and leading bundled flags. */
+function matchesOptionToken(parser, token) {
+	if (token == null || token === "--" || !/^[-/+]/.test(token)) return false;
+	if (parser.leadingNames.has(token)) return true;
+	const slashOption = token.startsWith("/");
+	const separator = slashOption ? token.indexOf(":") : token.startsWith("-") ? token.indexOf("=") : -1;
+	if (separator > (slashOption ? 0 : 2) && parser.leadingNames.has(token.slice(0, separator))) return true;
+	const shortName = token.slice(0, 2);
+	return token.length > 2 && /^-[^-]$/.test(shortName) && parser.leadingNames.has(shortName) && hasFlagUsage(parser.usage, shortName);
+}
+const optionMatchKey = Symbol("optionMatch");
+/**
+* Records state-aware option matching without changing public leading names.
+* @param parser The newly constructed transparent parser.
+* @param match Finds a reachable known-option lane.
+* @internal
+*/
+function defineOptionMatch(parser, match) {
+	Object.defineProperty(parser, optionMatchKey, {
+		value: {
+			ownerPriority: parser.priority,
+			match
+		},
+		enumerable: true
+	});
+}
+/**
+* Finds a matching option's actual priority, including selected command children.
+* @param parser The parser to inspect.
+* @param state Its current state.
+* @param token The current token.
+* @returns A reachable option match, or undefined.
+* @internal
+*/
+function getOptionMatch(parser, state, token) {
+	if (token == null || token === "--" || !/^[-/+]/.test(token)) return void 0;
+	const annotated = parser;
+	const matcher = annotated[optionMatchKey];
+	if (matcher != null) {
+		const match = matcher.match(state, token);
+		return match == null || matcher.ownerPriority === parser.priority ? match : {
+			...match,
+			priority: parser.priority
+		};
+	}
+	return matchesOptionToken(parser, token) ? {
+		priority: parser.priority,
+		continuesCommand: false
+	} : void 0;
+}
+/**
+* Combines option matches while retaining active command continuation.
+* @param matches Matches from transparent children.
+* @returns Their highest priority and whether any matching command continues.
+* @internal
+*/
+function combineOptionMatches(matches) {
+	const found = matches.filter((match) => match != null);
+	return found.length === 0 ? void 0 : {
+		priority: Math.max(...found.map((match) => match.priority)),
+		continuesCommand: found.some((match) => match.continuesCommand)
+	};
+}
+const knownCompletionKey = Symbol("knownCompletion");
+/** Marks a completion value that can be inspected without running user code. @internal */
+function defineKnownCompletion(parser, value) {
+	defineKnownCompletionLookup(parser, (state) => ({ value: value(state) }));
+}
+/** Registers a known-value lookup that may decline unknown completion. @internal */
+function defineKnownCompletionLookup(parser, value) {
+	Object.defineProperty(parser, knownCompletionKey, {
+		value: {
+			complete: parser.complete,
+			value
+		},
+		enumerable: true
+	});
+}
+/** Looks up a known value only while the original completion is intact. @internal */
+function getKnownCompletion(parser, state) {
+	const annotated = parser;
+	const hint = annotated[knownCompletionKey];
+	return hint != null && hint.complete === parser.complete ? hint.value(state) : void 0;
+}
+/** Combines the priorities of currently reachable capture lanes. @internal */
+function combinePassThroughPriorities(priorities) {
+	const found = priorities.filter((priority) => priority != null);
+	return found.length === 0 ? void 0 : Math.max(...found);
+}
+/** Forwards known completion through a state-preserving wrapper. @internal */
+function delegateKnownCompletion(wrapper, inner) {
+	Object.defineProperty(wrapper, knownCompletionKey, {
+		value: {
+			complete: wrapper.complete,
+			value: (state) => getKnownCompletion(inner, state)
+		},
+		enumerable: true
+	});
+}
+
+//#endregion
+exports.combineOptionMatches = combineOptionMatches;
+exports.combinePassThroughPriorities = combinePassThroughPriorities;
+exports.defineKnownCompletion = defineKnownCompletion;
+exports.defineKnownCompletionLookup = defineKnownCompletionLookup;
+exports.defineOptionMatch = defineOptionMatch;
+exports.definePassThroughPriority = definePassThroughPriority;
+exports.delegateKnownCompletion = delegateKnownCompletion;
+exports.getKnownCompletion = getKnownCompletion;
+exports.getOptionMatch = getOptionMatch;
+exports.getPassThroughFailure = getPassThroughFailure;
+exports.getPassThroughFailureHint = getPassThroughFailureHint;
+exports.getPassThroughPriority = getPassThroughPriority;
+exports.hasPassThroughUsage = hasPassThroughUsage;
+exports.matchesOptionToken = matchesOptionToken;
+exports.retainConsumingFailure = retainConsumingFailure;
+exports.retainConsumingFailureHint = retainConsumingFailureHint;
+exports.withPassThroughFailure = withPassThroughFailure;