@optique/core 1.4.0-dev.2636 → 1.4.0-dev.2661

package/dist/extension.cjs

@@ -3,6 +3,7 @@ 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_short_option = require('./short-option.cjs');
+const require_passthrough = require('./internal/passthrough.cjs');
 const require_phase2_seed = require('./phase2-seed.cjs');
 
 //#region src/extension.ts
@@ -86,9 +87,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.extractPhase2SeedKey = require_phase2_seed.extractPhase2SeedKey;

package/dist/extension.d.cts

@@ -105,5 +105,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, extractPhase2SeedKey, getTraits, inheritAnnotations, inheritOptionScope, injectAnnotations, isInjectedAnnotationState, mapModeValue, mapSourceMetadata, unwrapInjectedAnnotationState, withAnnotationView, wrapForMode };
+export { ParserSourceMetadata, ParserTraits, SuggestNode, defineTraits, delegateOptionParsing, delegateSuggestNodes, dispatchByMode, extractPhase2SeedKey, getTraits, inheritAnnotations, inheritOptionScope, injectAnnotations, isInjectedAnnotationState, mapModeValue, mapSourceMetadata, unwrapInjectedAnnotationState, withAnnotationView, wrapForMode };

package/dist/extension.d.ts

@@ -105,5 +105,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, extractPhase2SeedKey, getTraits, inheritAnnotations, inheritOptionScope, injectAnnotations, isInjectedAnnotationState, mapModeValue, mapSourceMetadata, unwrapInjectedAnnotationState, withAnnotationView, wrapForMode };
+export { ParserSourceMetadata, ParserTraits, SuggestNode, defineTraits, delegateOptionParsing, delegateSuggestNodes, dispatchByMode, extractPhase2SeedKey, getTraits, inheritAnnotations, inheritOptionScope, injectAnnotations, isInjectedAnnotationState, mapModeValue, mapSourceMetadata, unwrapInjectedAnnotationState, withAnnotationView, wrapForMode };

package/dist/extension.js

@@ -3,6 +3,7 @@ import { dispatchByMode, mapModeValue, wrapForMode } from "./internal/mode-dispa
 import { annotationWrapperRequiresSourceBindingKey, composeWrappedSourceMetadata, defineInheritedAnnotationParser, getDelegatingSuggestRuntimeNodes, inheritParentAnnotationsKey, unmatchedNonCliDependencySourceStateMarker } from "./internal/parser.js";
 import { withAnnotationView } from "./annotation-state.js";
 import { inheritOptionScope } from "./short-option.js";
+import { defineOptionMatch, definePassThroughPriority, getOptionMatch, getPassThroughPriority } from "./internal/passthrough.js";
 import { extractPhase2SeedKey } from "./phase2-seed.js";
 
 //#region src/extension.ts
@@ -86,6 +87,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, extractPhase2SeedKey, getTraits, inheritAnnotations, inheritOptionScope$1 as inheritOptionScope, injectAnnotations, isInjectedAnnotationState, mapModeValue, mapSourceMetadata, unwrapInjectedAnnotationState, withAnnotationView, wrapForMode };
+export { defineTraits, delegateOptionParsing, delegateSuggestNodes, dispatchByMode, extractPhase2SeedKey, getTraits, inheritAnnotations, inheritOptionScope$1 as inheritOptionScope, 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;

package/dist/internal/passthrough.js

@@ -0,0 +1,213 @@
+//#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
+export { combineOptionMatches, combinePassThroughPriorities, defineKnownCompletion, defineKnownCompletionLookup, defineOptionMatch, definePassThroughPriority, delegateKnownCompletion, getKnownCompletion, getOptionMatch, getPassThroughFailure, getPassThroughFailureHint, getPassThroughPriority, hasPassThroughUsage, matchesOptionToken, retainConsumingFailure, retainConsumingFailureHint, withPassThroughFailure };

package/dist/modifiers.cjs

@@ -6,6 +6,7 @@ const require_internal_parser = require('./internal/parser.cjs');
 const require_annotation_state = require('./annotation-state.cjs');
 const require_execution_context = require('./execution-context.cjs');
 const require_short_option = require('./short-option.cjs');
+const require_passthrough = require('./internal/passthrough.cjs');
 const require_phase2_seed = require('./phase2-seed.cjs');
 const require_dependency_metadata = require('./dependency-metadata.cjs');
 
@@ -479,6 +480,9 @@ function optional(parser) {
 	require_internal_parser.defineParseLanes(optionalParser, adaptOptionalStyleParseLanes(parser));
 	require_internal_parser.defineInheritedAnnotationParser(optionalParser);
 	require_internal_parser.defineSourceBindingOnlyAnnotationCompletionParser(optionalParser);
+	require_passthrough.defineOptionMatch(optionalParser, (state, token) => require_passthrough.getOptionMatch(parser, normalizeOptionalLikeSuggestState(state, parser.initialState, parser), token));
+	require_passthrough.definePassThroughPriority(optionalParser, [parser], (state, token) => require_passthrough.getPassThroughPriority(parser, normalizeOptionalLikeSuggestState(state, parser.initialState, parser), token));
+	require_passthrough.defineKnownCompletionLookup(optionalParser, (state) => require_passthrough.getKnownCompletion(parser, deriveOptionalInnerParseState(state, parser)));
 	return fluent(require_short_option.scopeParser(optionalParser, require_short_option.combinedOptionScope([parser])));
 }
 /**
@@ -730,6 +734,9 @@ function withDefault(parser, defaultValue, options) {
 	require_internal_parser.defineParseLanes(withDefaultParser, adaptOptionalStyleParseLanes(parser));
 	require_internal_parser.defineInheritedAnnotationParser(withDefaultParser);
 	require_internal_parser.defineSourceBindingOnlyAnnotationCompletionParser(withDefaultParser);
+	require_passthrough.defineOptionMatch(withDefaultParser, (state, token) => require_passthrough.getOptionMatch(parser, normalizeOptionalLikeSuggestState(state, parser.initialState, parser), token));
+	require_passthrough.definePassThroughPriority(withDefaultParser, [parser], (state, token) => require_passthrough.getPassThroughPriority(parser, normalizeOptionalLikeSuggestState(state, parser.initialState, parser), token));
+	require_passthrough.defineKnownCompletionLookup(withDefaultParser, (state) => require_passthrough.getKnownCompletion(parser, deriveOptionalInnerParseState(state, parser)));
 	return fluent(require_short_option.scopeParser(withDefaultParser, require_short_option.combinedOptionScope([parser])));
 }
 /**
@@ -1715,6 +1722,19 @@ function multiple(parser, options = {}) {
 			enumerable: false
 		});
 	}
+	const matchingItem = (state) => {
+		const current = state.at(-1);
+		if (current != null && !isTerminalMultipleItemState(current)) return { state: unwrapInjectedWrapper(current) };
+		return state.length < max ? { state: parser.initialState } : void 0;
+	};
+	require_passthrough.defineOptionMatch(resultParser, (state, token) => {
+		const item = matchingItem(state);
+		return item == null ? void 0 : require_passthrough.getOptionMatch(parser, item.state, token);
+	});
+	require_passthrough.definePassThroughPriority(resultParser, [parser], (state, token) => {
+		const item = matchingItem(state);
+		return item == null ? void 0 : require_passthrough.getPassThroughPriority(parser, item.state, token);
+	});
 	return fluent(require_short_option.scopeParser(resultParser, require_short_option.repeatedOptionScope(parser)));
 }
 /**
@@ -1851,6 +1871,8 @@ function nonEmpty(parser) {
 		enumerable: false
 	});
 	require_dependency_runtime.defineForwardedEffectfulSchedulingNodes(nonEmptyParser, parser);
+	require_passthrough.defineOptionMatch(nonEmptyParser, (state, token) => require_passthrough.getOptionMatch(parser, state, token));
+	require_passthrough.definePassThroughPriority(nonEmptyParser, [parser], (state, token) => require_passthrough.getPassThroughPriority(parser, state, token));
 	return fluent(require_short_option.scopeParser(nonEmptyParser, require_short_option.combinedOptionScope([parser])));
 }
 const fluentParserMarker = Symbol.for("@optique/core/fluent");

package/dist/modifiers.js

@@ -6,6 +6,7 @@ import { defineInheritedAnnotationParser, defineParseLanes, defineSourceBindingO
 import { getDelegatedAnnotationState, hasDelegatedAnnotationCarrier, isAnnotationWrappedInitialState, normalizeDelegatedAnnotationState, normalizeNestedDelegatedAnnotationState } from "./annotation-state.js";
 import { mergeChildExec, withChildContext, withChildExecPath } from "./execution-context.js";
 import { combinedOptionScope, repeatedOptionScope, scopeParser } from "./short-option.js";
+import { defineKnownCompletionLookup, defineOptionMatch, definePassThroughPriority, getKnownCompletion, getOptionMatch, getPassThroughPriority } from "./internal/passthrough.js";
 import { completeOrExtractPhase2Seed, extractPhase2Seed, extractPhase2SeedKey, phase2SeedFromValueResult } from "./phase2-seed.js";
 import { composeDependencyMetadata } from "./dependency-metadata.js";
 
@@ -479,6 +480,9 @@ function optional(parser) {
 	defineParseLanes(optionalParser, adaptOptionalStyleParseLanes(parser));
 	defineInheritedAnnotationParser(optionalParser);
 	defineSourceBindingOnlyAnnotationCompletionParser(optionalParser);
+	defineOptionMatch(optionalParser, (state, token) => getOptionMatch(parser, normalizeOptionalLikeSuggestState(state, parser.initialState, parser), token));
+	definePassThroughPriority(optionalParser, [parser], (state, token) => getPassThroughPriority(parser, normalizeOptionalLikeSuggestState(state, parser.initialState, parser), token));
+	defineKnownCompletionLookup(optionalParser, (state) => getKnownCompletion(parser, deriveOptionalInnerParseState(state, parser)));
 	return fluent(scopeParser(optionalParser, combinedOptionScope([parser])));
 }
 /**
@@ -730,6 +734,9 @@ function withDefault(parser, defaultValue, options) {
 	defineParseLanes(withDefaultParser, adaptOptionalStyleParseLanes(parser));
 	defineInheritedAnnotationParser(withDefaultParser);
 	defineSourceBindingOnlyAnnotationCompletionParser(withDefaultParser);
+	defineOptionMatch(withDefaultParser, (state, token) => getOptionMatch(parser, normalizeOptionalLikeSuggestState(state, parser.initialState, parser), token));
+	definePassThroughPriority(withDefaultParser, [parser], (state, token) => getPassThroughPriority(parser, normalizeOptionalLikeSuggestState(state, parser.initialState, parser), token));
+	defineKnownCompletionLookup(withDefaultParser, (state) => getKnownCompletion(parser, deriveOptionalInnerParseState(state, parser)));
 	return fluent(scopeParser(withDefaultParser, combinedOptionScope([parser])));
 }
 /**
@@ -1715,6 +1722,19 @@ function multiple(parser, options = {}) {
 			enumerable: false
 		});
 	}
+	const matchingItem = (state) => {
+		const current = state.at(-1);
+		if (current != null && !isTerminalMultipleItemState(current)) return { state: unwrapInjectedWrapper(current) };
+		return state.length < max ? { state: parser.initialState } : void 0;
+	};
+	defineOptionMatch(resultParser, (state, token) => {
+		const item = matchingItem(state);
+		return item == null ? void 0 : getOptionMatch(parser, item.state, token);
+	});
+	definePassThroughPriority(resultParser, [parser], (state, token) => {
+		const item = matchingItem(state);
+		return item == null ? void 0 : getPassThroughPriority(parser, item.state, token);
+	});
 	return fluent(scopeParser(resultParser, repeatedOptionScope(parser)));
 }
 /**
@@ -1851,6 +1871,8 @@ function nonEmpty(parser) {
 		enumerable: false
 	});
 	defineForwardedEffectfulSchedulingNodes(nonEmptyParser, parser);
+	defineOptionMatch(nonEmptyParser, (state, token) => getOptionMatch(parser, state, token));
+	definePassThroughPriority(nonEmptyParser, [parser], (state, token) => getPassThroughPriority(parser, state, token));
 	return fluent(scopeParser(nonEmptyParser, combinedOptionScope([parser])));
 }
 const fluentParserMarker = Symbol.for("@optique/core/fluent");