@optique/core 1.1.0-dev.2087 → 1.1.0-dev.2146

package/dist/internal/parser.js

@@ -123,6 +123,7 @@ function parseSync(parser, args, options) {
 		phase: "complete",
 		dependencyRuntime: runtime,
 		dependencyRegistry: runtime.registry,
+		commandPath: context.exec?.commandPath ?? exec.commandPath,
 		trace: context.exec?.trace ?? context.trace ?? exec.trace
 	};
 	const endResult = parser.complete(context.state, completeExec);
@@ -195,6 +196,7 @@ async function parseAsync(parser, args, options) {
 		phase: "complete",
 		dependencyRuntime: runtime,
 		dependencyRegistry: runtime.registry,
+		commandPath: context.exec?.commandPath ?? exec.commandPath,
 		trace: context.exec?.trace ?? context.trace ?? exec.trace
 	};
 	const endResult = await parser.complete(context.state, completeExec);
@@ -501,14 +503,83 @@ function findCommandInExclusive(term, commandName) {
 	if (term.type !== "exclusive") return null;
 	for (const termGroup of term.terms) {
 		const firstTerm = termGroup[0];
-		if (firstTerm?.type === "command" && firstTerm.name === commandName) return termGroup;
-		if (firstTerm?.type === "exclusive") {
-			const found = findCommandInExclusive(firstTerm, commandName);
-			if (found) return [...found, ...termGroup.slice(1)];
-		}
+		if (firstTerm == null) continue;
+		const found = findCommandInCurrentUsageTerm(firstTerm, commandName, termGroup.slice(1));
+		if (found) return found;
+	}
+	return null;
+}
+/**
+* Searches for a command inside an ordered usage sequence and returns the
+* usage from the matched command onward.  This lets contextual command
+* documentation enter sequence terms while dropping sequence prefixes that
+* were skipped by parsing, such as optional positionals before a subcommand.
+*
+* @param usage The usage terms to search.
+* @param commandName The command name to find.
+* @returns The contextual usage terms if found, null otherwise.
+*/
+function findCommandInUsageSequence(usage, commandName) {
+	for (let index = 0; index < usage.length; index++) {
+		const found = findCommandInCurrentUsageTerm(usage[index], commandName, usage.slice(index + 1));
+		if (found) return found;
+	}
+	return null;
+}
+/**
+* Searches the current usage term for a command and appends the trailing
+* usage terms that remain valid after that current term.
+*
+* @param term The current usage term to search.
+* @param commandName The command name to find.
+* @param trailingUsage Usage terms that follow the current term.
+* @returns The contextual usage terms if found, null otherwise.
+*/
+function findCommandInCurrentUsageTerm(term, commandName, trailingUsage) {
+	if (term.type === "command" && commandTermMatches(term, commandName)) return [term, ...trailingUsage];
+	if (term.type === "exclusive") {
+		const found = findCommandInExclusive(term, commandName);
+		if (found) return [...found, ...trailingUsage];
+	} else if (term.type === "sequence") {
+		const found = findCommandInUsageSequence(term.terms, commandName);
+		if (found) return [...found, ...trailingUsage];
 	}
 	return null;
 }
+function commandTermMatches(term, commandName) {
+	return term?.type === "command" && (term.name === commandName || term.aliases?.includes(commandName) === true || term.hiddenAliases?.includes(commandName) === true);
+}
+function collectCommandInputNames(usage, commandName, names) {
+	for (const term of usage) if (term.type === "command") {
+		if (commandTermMatches(term, commandName)) {
+			names.add(term.name);
+			for (const alias of term.aliases ?? []) names.add(alias);
+			for (const alias of term.hiddenAliases ?? []) names.add(alias);
+		}
+	} else if (term.type === "exclusive") for (const branch of term.terms) collectCommandInputNames(branch, commandName, names);
+	else if (term.type === "sequence") collectCommandInputNames(term.terms, commandName, names);
+	else if (term.type === "optional" || term.type === "multiple") collectCommandInputNames(term.terms, commandName, names);
+}
+function findLastCommandInputIndex(consumed, commandName, usage, searchEnd) {
+	const names = new Set([commandName]);
+	collectCommandInputNames(usage, commandName, names);
+	for (let index = searchEnd - 1; index >= 0; index--) if (names.has(consumed[index])) return index;
+	return -1;
+}
+function recordMatchedCommandArgIndices(usage, consumed, previousCommandPath, nextCommandPath, consumedOffset, indices) {
+	const previousLength = previousCommandPath?.length ?? 0;
+	const next = nextCommandPath ?? [];
+	if (next.length <= previousLength || consumed.length < 1) return;
+	let searchEnd = consumed.length;
+	for (let index = next.length - 1; index >= previousLength; index--) {
+		if (searchEnd <= 0) break;
+		const commandName = next[index];
+		const localIndex = findLastCommandInputIndex(consumed, commandName, usage, searchEnd);
+		if (localIndex < 0) continue;
+		indices.add(consumedOffset + localIndex);
+		searchEnd = localIndex;
+	}
+}
 /**
 * Generates a documentation page for a synchronous parser.
 *
@@ -579,14 +650,18 @@ function getDocPageSyncImpl(parser, args, options) {
 		state: initialState,
 		optionsTerminated: false
 	}, exec);
+	const matchedCommandArgIndices = /* @__PURE__ */ new Set();
 	while (context.buffer.length > 0) {
 		const result = parser.parse(context);
 		if (!result.success) break;
+		const previousCommandPath = context.exec?.commandPath;
 		const previousBuffer = context.buffer;
 		context = result.next;
+		const consumedCount = previousBuffer.length - context.buffer.length;
+		recordMatchedCommandArgIndices(parser.usage, previousBuffer.slice(0, consumedCount), previousCommandPath, context.exec?.commandPath, args.length - previousBuffer.length, matchedCommandArgIndices);
 		if (isBufferUnchanged(previousBuffer, context.buffer)) break;
 	}
-	return buildDocPage(parser, context, args);
+	return buildDocPage(parser, context, args, matchedCommandArgIndices);
 }
 /**
 * Internal async implementation of getDocPage.
@@ -604,20 +679,24 @@ async function getDocPageAsyncImpl(parser, args, options) {
 		state: initialState,
 		optionsTerminated: false
 	}, exec);
+	const matchedCommandArgIndices = /* @__PURE__ */ new Set();
 	while (context.buffer.length > 0) {
 		const result = await parser.parse(context);
 		if (!result.success) break;
+		const previousCommandPath = context.exec?.commandPath;
 		const previousBuffer = context.buffer;
 		context = result.next;
+		const consumedCount = previousBuffer.length - context.buffer.length;
+		recordMatchedCommandArgIndices(parser.usage, previousBuffer.slice(0, consumedCount), previousCommandPath, context.exec?.commandPath, args.length - previousBuffer.length, matchedCommandArgIndices);
 		if (isBufferUnchanged(previousBuffer, context.buffer)) break;
 	}
-	return buildDocPage(parser, context, args);
+	return buildDocPage(parser, context, args, matchedCommandArgIndices);
 }
 /**
 * Builds a DocPage from the parser and context.
 * Shared by both sync and async implementations.
 */
-function buildDocPage(parser, context, args) {
+function buildDocPage(parser, context, args, matchedCommandArgIndices) {
 	let effectiveArgs = args;
 	let { brief, description, fragments, footer } = parser.getDocFragments({
 		kind: "available",
@@ -668,26 +747,32 @@ function buildDocPage(parser, context, args) {
 	const sections = buildingSections;
 	const usage = [...normalizeUsage(parser.usage)];
 	const maybeApplyCommandUsageLine = (term, arg, isLastArg, usageIndex) => {
-		if (term?.type !== "command" || term.name !== arg || !isLastArg || term.usageLine == null) return;
+		if (term?.type !== "command" || !commandTermMatches(term, arg) || !isLastArg || term.usageLine == null) return;
 		const defaultUsageLine = cloneUsage(usage.slice(usageIndex + 1));
 		const customUsageLine = typeof term.usageLine === "function" ? term.usageLine(defaultUsageLine) : term.usageLine;
 		const normalizedCustomUsageLine = normalizeUsage(customUsageLine);
 		usage.splice(usageIndex + 1, usage.length - (usageIndex + 1), ...normalizedCustomUsageLine);
 	};
 	let i = 0;
+	const consumedArgsCount = Math.max(0, effectiveArgs.length - context.buffer.length);
+	const commandArgIndices = args.length > 0 ? matchedCommandArgIndices : null;
 	for (let argIndex = 0; argIndex < effectiveArgs.length; argIndex++) {
 		const arg = effectiveArgs[argIndex];
 		if (i >= usage.length) break;
 		let term = usage[i];
-		if (term.type === "exclusive") {
-			const found = findCommandInExclusive(term, arg);
-			if (found) {
-				usage.splice(i, 1, ...found);
-				term = usage[i];
-			}
+		const canSearchCommand = commandArgIndices == null || commandArgIndices.has(argIndex);
+		if (!canSearchCommand) continue;
+		let found = null;
+		for (let searchIndex = i; searchIndex < usage.length; searchIndex++) {
+			found = findCommandInCurrentUsageTerm(usage[searchIndex], arg, usage.slice(searchIndex + 1));
+			if (found != null) break;
+		}
+		if (found) {
+			usage.splice(i, usage.length - i, ...found);
+			term = usage[i];
 		}
 		maybeApplyCommandUsageLine(term, arg, argIndex === effectiveArgs.length - 1, i);
-		i++;
+		if (found != null || term.type !== "sequence" || argIndex >= consumedArgsCount) i++;
 	}
 	if (effectiveArgs.length === 0 && usage.length > 0) {
 		const first = usage[0];

package/dist/modifiers.cjs

@@ -1,7 +1,7 @@
-const require_annotations = require('./internal/annotations.cjs');
+const require_internal_annotations = require('./internal/annotations.cjs');
 const require_message = require('./message.cjs');
 const require_mode_dispatch = require('./internal/mode-dispatch.cjs');
-const require_parser = require('./internal/parser.cjs');
+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_phase2_seed = require('./phase2-seed.cjs');
@@ -12,6 +12,11 @@ function isTerminalMultipleItemState(state) {
 	const unwrapped = unwrapMultipleItemState(state).value;
 	return unwrapped != null && typeof unwrapped === "object" && Object.hasOwn(unwrapped, "success") && typeof unwrapped.success === "boolean";
 }
+function isMatchedCommandParserState(parser, state) {
+	if (Reflect.get(parser, Symbol.for("@optique/core/commandParser")) !== true) return false;
+	const unwrapped = unwrapMultipleItemState(state).value;
+	return Array.isArray(unwrapped) && unwrapped.length === 2 && unwrapped[0] === "matched" && typeof unwrapped[1] === "string";
+}
 function isUnstartedMultipleItemState(state, originalState) {
 	const unwrappedState = unwrapMultipleItemState(state);
 	if (unwrappedState.value == null) return true;
@@ -26,8 +31,8 @@ function unwrapMultipleItemState(state) {
 	let unwrapped = state;
 	let viaBoundCliWrapper = false;
 	while (true) {
-		if (require_annotations.isInjectedAnnotationWrapper(unwrapped)) {
-			unwrapped = require_annotations.unwrapInjectedAnnotationWrapper(unwrapped);
+		if (require_internal_annotations.isInjectedAnnotationWrapper(unwrapped)) {
+			unwrapped = require_internal_annotations.unwrapInjectedAnnotationWrapper(unwrapped);
 			continue;
 		}
 		if (Array.isArray(unwrapped) && unwrapped.length === 1) {
@@ -55,7 +60,7 @@ function normalizeOptionalLikeCompleteResult(result, shouldNormalize) {
 	} : result;
 }
 function shouldRetryOptionalLikeCompatibilityError(error, state) {
-	return error instanceof TypeError && state != null && typeof state === "object" && require_annotations.isInjectedAnnotationWrapper(state);
+	return error instanceof TypeError && state != null && typeof state === "object" && require_internal_annotations.isInjectedAnnotationWrapper(state);
 }
 function completeOptionalLikeSync(parser, state, exec) {
 	const hasCarrier = require_annotation_state.hasDelegatedAnnotationCarrier(state);
@@ -156,12 +161,12 @@ function extractOptionalLikePhase2Seed(parser, state, exec) {
 function deriveOptionalInnerParseState(outerState, parser) {
 	if (Array.isArray(outerState)) {
 		const innerState = outerState[0];
-		if (require_annotations.getAnnotations(outerState) != null && innerState != null && typeof innerState === "object") return require_annotation_state.getDelegatedAnnotationState(outerState, innerState);
+		if (require_internal_annotations.getAnnotations(outerState) != null && innerState != null && typeof innerState === "object") return require_annotation_state.getDelegatedAnnotationState(outerState, innerState);
 		return innerState;
 	}
 	const initial = parser.initialState;
 	if (initial != null && typeof initial !== "object") return initial;
-	return initial != null && typeof initial === "object" ? require_annotation_state.getDelegatedAnnotationState(outerState, initial) : require_annotations.inheritAnnotations(outerState, initial);
+	return initial != null && typeof initial === "object" ? require_annotation_state.getDelegatedAnnotationState(outerState, initial) : require_internal_annotations.inheritAnnotations(outerState, initial);
 }
 /**
 * Internal helper for optional-style parsing logic shared by optional()
@@ -257,9 +262,9 @@ function adaptShouldDeferCompletion(innerCheck, parser) {
 	};
 }
 function isAnnotationOnlyObjectState(state) {
-	if (state == null || typeof state !== "object" || Array.isArray(state) || require_annotations.isInjectedAnnotationWrapper(state)) return false;
+	if (state == null || typeof state !== "object" || Array.isArray(state) || require_internal_annotations.isInjectedAnnotationWrapper(state)) return false;
 	const keys = Reflect.ownKeys(state);
-	return require_annotations.getAnnotations(state) != null && keys.length === 1 && keys[0] === require_annotations.annotationKey;
+	return require_internal_annotations.getAnnotations(state) != null && keys.length === 1 && keys[0] === require_internal_annotations.annotationKey;
 }
 function normalizeOptionalLikeInnerState(state, initialState, parser) {
 	if (Array.isArray(state)) return require_annotation_state.getDelegatedAnnotationState(state, state[0]);
@@ -310,7 +315,7 @@ function optional(parser) {
 		mode: parser.mode,
 		$valueType: [],
 		$stateType: [],
-		...parser[require_parser.unmatchedNonCliDependencySourceStateMarker] === true ? { [require_parser.unmatchedNonCliDependencySourceStateMarker]: true } : {},
+		...parser[require_internal_parser.unmatchedNonCliDependencySourceStateMarker] === true ? { [require_internal_parser.unmatchedNonCliDependencySourceStateMarker]: true } : {},
 		placeholder: void 0,
 		priority: parser.priority,
 		usage: [{
@@ -320,6 +325,11 @@ function optional(parser) {
 		leadingNames: parser.leadingNames,
 		acceptingAnyToken: false,
 		initialState: void 0,
+		canSkip(state, exec) {
+			if (!Array.isArray(state)) return true;
+			const innerState = normalizeOptionalLikeInnerState(state, parser.initialState, parser);
+			return parser.canSkip?.(innerState, exec) === true;
+		},
 		...typeof parser.shouldDeferCompletion === "function" ? { shouldDeferCompletion: adaptShouldDeferCompletion(parser.shouldDeferCompletion.bind(parser), parser) } : {},
 		getSuggestRuntimeNodes(state, path) {
 			if (optionalParser.dependencyMetadata?.source != null) return [{
@@ -358,7 +368,7 @@ function optional(parser) {
 					const delegatedState = normalizeOptionalLikeInnerState(state, parser.initialState, parser);
 					return require_mode_dispatch.dispatchByMode(parser.mode, () => completeOptionalLikeSync(syncParser, delegatedState, exec), async () => await completeOptionalLikeAsync(parser, delegatedState, exec));
 				}
-				if (parser[require_parser.unmatchedNonCliDependencySourceStateMarker] === true && state != null && typeof state === "object") {
+				if (parser[require_internal_parser.unmatchedNonCliDependencySourceStateMarker] === true && state != null && typeof state === "object") {
 					const innerState = normalizeOptionalLikeInnerState(state, parser.initialState, parser);
 					return delegateToInner(innerState);
 				}
@@ -410,8 +420,8 @@ function optional(parser) {
 		const composed = require_dependency_metadata.composeDependencyMetadata(parser.dependencyMetadata, "optional");
 		if (composed != null) optionalParser.dependencyMetadata = composed;
 	}
-	require_parser.defineInheritedAnnotationParser(optionalParser);
-	require_parser.defineSourceBindingOnlyAnnotationCompletionParser(optionalParser);
+	require_internal_parser.defineInheritedAnnotationParser(optionalParser);
+	require_internal_parser.defineSourceBindingOnlyAnnotationCompletionParser(optionalParser);
 	return optionalParser;
 }
 /**
@@ -479,7 +489,7 @@ function withDefault(parser, defaultValue, options) {
 		mode: parser.mode,
 		$valueType: [],
 		$stateType: [],
-		...parser[require_parser.unmatchedNonCliDependencySourceStateMarker] === true ? { [require_parser.unmatchedNonCliDependencySourceStateMarker]: true } : {},
+		...parser[require_internal_parser.unmatchedNonCliDependencySourceStateMarker] === true ? { [require_internal_parser.unmatchedNonCliDependencySourceStateMarker]: true } : {},
 		priority: parser.priority,
 		usage: [{
 			type: "optional",
@@ -488,6 +498,11 @@ function withDefault(parser, defaultValue, options) {
 		leadingNames: parser.leadingNames,
 		acceptingAnyToken: false,
 		initialState: void 0,
+		canSkip(state, exec) {
+			if (!Array.isArray(state)) return true;
+			const innerState = normalizeOptionalLikeInnerState(state, parser.initialState, parser);
+			return parser.canSkip?.(innerState, exec) === true;
+		},
 		...typeof parser.shouldDeferCompletion === "function" ? { shouldDeferCompletion: adaptShouldDeferCompletion(parser.shouldDeferCompletion.bind(parser), parser) } : {},
 		getSuggestRuntimeNodes(state, path) {
 			if (withDefaultParser.dependencyMetadata?.source != null) return [{
@@ -522,7 +537,7 @@ function withDefault(parser, defaultValue, options) {
 					const innerResult = require_mode_dispatch.dispatchByMode(parser.mode, () => completeOptionalLikeSync(syncParser, innerState, exec), async () => await completeOptionalLikeAsync(parser, innerState, exec));
 					return innerResult;
 				}
-				if (parser[require_parser.unmatchedNonCliDependencySourceStateMarker] === true && state != null && typeof state === "object") {
+				if (parser[require_internal_parser.unmatchedNonCliDependencySourceStateMarker] === true && state != null && typeof state === "object") {
 					const innerState = normalizeOptionalLikeInnerState(state, parser.initialState, parser);
 					const innerResult = require_mode_dispatch.dispatchByMode(parser.mode, () => completeOptionalLikeSync(syncParser, innerState, exec), async () => await completeOptionalLikeAsync(parser, innerState, exec));
 					const handleInnerResult = (result) => {
@@ -639,8 +654,8 @@ function withDefault(parser, defaultValue, options) {
 		} });
 		if (composed != null) withDefaultParser.dependencyMetadata = composed;
 	}
-	require_parser.defineInheritedAnnotationParser(withDefaultParser);
-	require_parser.defineSourceBindingOnlyAnnotationCompletionParser(withDefaultParser);
+	require_internal_parser.defineInheritedAnnotationParser(withDefaultParser);
+	require_internal_parser.defineSourceBindingOnlyAnnotationCompletionParser(withDefaultParser);
 	return withDefaultParser;
 }
 /**
@@ -848,27 +863,27 @@ function map(parser, transform) {
 function multiple(parser, options = {}) {
 	const syncParser = parser;
 	const { min = 0, max = Infinity } = options;
-	const unwrapInjectedWrapper = require_annotations.unwrapInjectedAnnotationWrapper;
+	const unwrapInjectedWrapper = require_internal_annotations.unwrapInjectedAnnotationWrapper;
 	const completeSyncWithUnwrappedFallback = (state, exec) => {
 		try {
 			const result = syncParser.complete(state, exec);
-			if (!result.success && require_annotations.isInjectedAnnotationWrapper(state)) return syncParser.complete(unwrapInjectedWrapper(state), exec);
+			if (!result.success && require_internal_annotations.isInjectedAnnotationWrapper(state)) return syncParser.complete(unwrapInjectedWrapper(state), exec);
 			return result;
 		} catch (error) {
-			if (!require_annotations.isInjectedAnnotationWrapper(state)) throw error;
+			if (!require_internal_annotations.isInjectedAnnotationWrapper(state)) throw error;
 			return syncParser.complete(unwrapInjectedWrapper(state), exec);
 		}
 	};
 	const parseSyncWithUnwrappedFallback = (context) => {
 		try {
 			const result = syncParser.parse(context);
-			if (result.success || result.consumed !== 0 || !require_annotations.isInjectedAnnotationWrapper(context.state)) return result;
+			if (result.success || result.consumed !== 0 || !require_internal_annotations.isInjectedAnnotationWrapper(context.state)) return result;
 			return syncParser.parse({
 				...context,
 				state: unwrapInjectedWrapper(context.state)
 			});
 		} catch (error) {
-			if (!require_annotations.isInjectedAnnotationWrapper(context.state)) throw error;
+			if (!require_internal_annotations.isInjectedAnnotationWrapper(context.state)) throw error;
 			return syncParser.parse({
 				...context,
 				state: unwrapInjectedWrapper(context.state)
@@ -878,23 +893,23 @@ function multiple(parser, options = {}) {
 	const completeAsyncWithUnwrappedFallback = async (state, exec) => {
 		try {
 			const result = await parser.complete(state, exec);
-			if (!result.success && require_annotations.isInjectedAnnotationWrapper(state)) return await parser.complete(unwrapInjectedWrapper(state), exec);
+			if (!result.success && require_internal_annotations.isInjectedAnnotationWrapper(state)) return await parser.complete(unwrapInjectedWrapper(state), exec);
 			return result;
 		} catch (error) {
-			if (!require_annotations.isInjectedAnnotationWrapper(state)) throw error;
+			if (!require_internal_annotations.isInjectedAnnotationWrapper(state)) throw error;
 			return await parser.complete(unwrapInjectedWrapper(state), exec);
 		}
 	};
 	const parseAsyncWithUnwrappedFallback = async (context) => {
 		try {
 			const result = await parser.parse(context);
-			if (result.success || result.consumed !== 0 || !require_annotations.isInjectedAnnotationWrapper(context.state)) return result;
+			if (result.success || result.consumed !== 0 || !require_internal_annotations.isInjectedAnnotationWrapper(context.state)) return result;
 			return await parser.parse({
 				...context,
 				state: unwrapInjectedWrapper(context.state)
 			});
 		} catch (error) {
-			if (!require_annotations.isInjectedAnnotationWrapper(context.state)) throw error;
+			if (!require_internal_annotations.isInjectedAnnotationWrapper(context.state)) throw error;
 			return await parser.parse({
 				...context,
 				state: unwrapInjectedWrapper(context.state)
@@ -904,20 +919,20 @@ function multiple(parser, options = {}) {
 	const extractPhase2SeedSyncWithUnwrappedFallback = (state, exec) => {
 		try {
 			const seed = require_phase2_seed.completeOrExtractPhase2Seed(syncParser, state, exec);
-			if (seed == null && require_annotations.isInjectedAnnotationWrapper(state)) return require_phase2_seed.completeOrExtractPhase2Seed(syncParser, unwrapInjectedWrapper(state), exec);
+			if (seed == null && require_internal_annotations.isInjectedAnnotationWrapper(state)) return require_phase2_seed.completeOrExtractPhase2Seed(syncParser, unwrapInjectedWrapper(state), exec);
 			return seed;
 		} catch (error) {
-			if (!require_annotations.isInjectedAnnotationWrapper(state)) throw error;
+			if (!require_internal_annotations.isInjectedAnnotationWrapper(state)) throw error;
 			return require_phase2_seed.completeOrExtractPhase2Seed(syncParser, unwrapInjectedWrapper(state), exec);
 		}
 	};
 	const extractPhase2SeedAsyncWithUnwrappedFallback = async (state, exec) => {
 		try {
 			const seed = await require_phase2_seed.completeOrExtractPhase2Seed(parser, state, exec);
-			if (seed == null && require_annotations.isInjectedAnnotationWrapper(state)) return await require_phase2_seed.completeOrExtractPhase2Seed(parser, unwrapInjectedWrapper(state), exec);
+			if (seed == null && require_internal_annotations.isInjectedAnnotationWrapper(state)) return await require_phase2_seed.completeOrExtractPhase2Seed(parser, unwrapInjectedWrapper(state), exec);
 			return seed;
 		} catch (error) {
-			if (!require_annotations.isInjectedAnnotationWrapper(state)) throw error;
+			if (!require_internal_annotations.isInjectedAnnotationWrapper(state)) throw error;
 			return await require_phase2_seed.completeOrExtractPhase2Seed(parser, unwrapInjectedWrapper(state), exec);
 		}
 	};
@@ -926,9 +941,11 @@ function multiple(parser, options = {}) {
 		parser,
 		state
 	}] : []);
+	const canExtendMultipleItem = (state, itemIndex, exec) => state != null && !isTerminalMultipleItemState(state) && (isMatchedCommandParserState(parser, state) || parser.canSkip?.(state, require_execution_context.withChildExecPath(exec, itemIndex)) !== true);
 	const parseSync = (context) => {
 		const currentItemState = context.state.at(-1);
-		const canExtendCurrent = currentItemState != null && !isTerminalMultipleItemState(currentItemState);
+		const currentItemIndex = context.state.length - 1;
+		const canExtendCurrent = canExtendMultipleItem(currentItemState, currentItemIndex, context.exec);
 		const canOpenFreshItem = context.state.length < max;
 		if (!canExtendCurrent && !canOpenFreshItem) return {
 			success: true,
@@ -937,12 +954,12 @@ function multiple(parser, options = {}) {
 		};
 		let added = !canExtendCurrent;
 		let itemIndex = canExtendCurrent ? context.state.length - 1 : context.state.length;
-		const currentItemStateWithAnnotations = canExtendCurrent ? currentItemState : require_annotations.inheritAnnotations(context.state, syncParser.initialState);
+		const currentItemStateWithAnnotations = canExtendCurrent ? currentItemState : require_internal_annotations.inheritAnnotations(context.state, syncParser.initialState);
 		let result = parseSyncWithUnwrappedFallback(require_execution_context.withChildContext(context, itemIndex, currentItemStateWithAnnotations));
 		if (!result.success) {
 			if (result.consumed !== 0) return result;
 			if (!added && canOpenFreshItem) {
-				const nextInitialState = require_annotations.inheritAnnotations(context.state, syncParser.initialState);
+				const nextInitialState = require_internal_annotations.inheritAnnotations(context.state, syncParser.initialState);
 				itemIndex = context.state.length;
 				result = parseSyncWithUnwrappedFallback(require_execution_context.withChildContext(context, itemIndex, nextInitialState));
 				if (!result.success) {
@@ -990,13 +1007,13 @@ function multiple(parser, options = {}) {
 			},
 			consumed: result.consumed
 		};
-		const nextItemState = require_annotations.inheritAnnotations(itemAnnotationSource, result.next.state);
+		const nextItemState = require_internal_annotations.inheritAnnotations(itemAnnotationSource, result.next.state);
 		return {
 			success: true,
 			...result.provisional ? { provisional: true } : {},
 			next: {
 				...result.next,
-				state: require_annotations.annotateFreshArray(context.state, [...added ? context.state : context.state.slice(0, -1), nextItemState]),
+				state: require_internal_annotations.annotateFreshArray(context.state, [...added ? context.state : context.state.slice(0, -1), nextItemState]),
 				...mergedExec != null ? {
 					trace: mergedExec.trace,
 					exec: mergedExec,
@@ -1008,7 +1025,8 @@ function multiple(parser, options = {}) {
 	};
 	const parseAsync = async (context) => {
 		const currentItemState = context.state.at(-1);
-		const canExtendCurrent = currentItemState != null && !isTerminalMultipleItemState(currentItemState);
+		const currentItemIndex = context.state.length - 1;
+		const canExtendCurrent = canExtendMultipleItem(currentItemState, currentItemIndex, context.exec);
 		const canOpenFreshItem = context.state.length < max;
 		if (!canExtendCurrent && !canOpenFreshItem) return {
 			success: true,
@@ -1017,12 +1035,12 @@ function multiple(parser, options = {}) {
 		};
 		let added = !canExtendCurrent;
 		let itemIndex = canExtendCurrent ? context.state.length - 1 : context.state.length;
-		const currentItemStateWithAnnotations = canExtendCurrent ? currentItemState : require_annotations.inheritAnnotations(context.state, parser.initialState);
+		const currentItemStateWithAnnotations = canExtendCurrent ? currentItemState : require_internal_annotations.inheritAnnotations(context.state, parser.initialState);
 		let result = await parseAsyncWithUnwrappedFallback(require_execution_context.withChildContext(context, itemIndex, currentItemStateWithAnnotations));
 		if (!result.success) {
 			if (result.consumed !== 0) return result;
 			if (!added && canOpenFreshItem) {
-				const nextInitialState = require_annotations.inheritAnnotations(context.state, parser.initialState);
+				const nextInitialState = require_internal_annotations.inheritAnnotations(context.state, parser.initialState);
 				itemIndex = context.state.length;
 				result = await parseAsyncWithUnwrappedFallback(require_execution_context.withChildContext(context, itemIndex, nextInitialState));
 				if (!result.success) {
@@ -1070,13 +1088,13 @@ function multiple(parser, options = {}) {
 			},
 			consumed: result.consumed
 		};
-		const nextItemState = require_annotations.inheritAnnotations(itemAnnotationSource, result.next.state);
+		const nextItemState = require_internal_annotations.inheritAnnotations(itemAnnotationSource, result.next.state);
 		return {
 			success: true,
 			...result.provisional ? { provisional: true } : {},
 			next: {
 				...result.next,
-				state: require_annotations.annotateFreshArray(context.state, [...added ? context.state : context.state.slice(0, -1), nextItemState]),
+				state: require_internal_annotations.annotateFreshArray(context.state, [...added ? context.state : context.state.slice(0, -1), nextItemState]),
 				...mergedExec != null ? {
 					trace: mergedExec.trace,
 					exec: mergedExec,
@@ -1099,6 +1117,11 @@ function multiple(parser, options = {}) {
 		leadingNames: parser.leadingNames,
 		acceptingAnyToken: min > 0 && (parser.acceptingAnyToken ?? false),
 		initialState: [],
+		canSkip(state, exec) {
+			if (state.length < min) return false;
+			const currentItemState = state.at(-1);
+			return !canExtendMultipleItem(currentItemState, state.length - 1, exec);
+		},
 		getSuggestRuntimeNodes(state, path) {
 			const innerNodes = state.flatMap((item, i) => [...getInnerSuggestRuntimeNodes(item, [...path, i])]);
 			return resultParser.dependencyMetadata?.source != null ? [{
@@ -1198,11 +1221,12 @@ function multiple(parser, options = {}) {
 		},
 		suggest(context, prefix) {
 			const currentItemState = context.state.at(-1);
-			const canExtendCurrent = currentItemState != null && !isTerminalMultipleItemState(currentItemState);
+			const currentItemIndex = context.state.length - 1;
+			const canExtendCurrent = canExtendMultipleItem(currentItemState, currentItemIndex, context.exec);
 			const canOpenNew = context.state.length < max;
 			if (!canExtendCurrent && !canOpenNew) return require_mode_dispatch.dispatchIterableByMode(parser.mode, function* () {}, async function* () {});
 			const itemIndex = canExtendCurrent ? context.state.length - 1 : context.state.length;
-			const suggestInitialState = canExtendCurrent ? currentItemState : require_annotations.inheritAnnotations(context.state, parser.initialState);
+			const suggestInitialState = canExtendCurrent ? currentItemState : require_internal_annotations.inheritAnnotations(context.state, parser.initialState);
 			const suggestFallbackState = unwrapInjectedWrapper(suggestInitialState);
 			const hasSuggestFallbackState = suggestFallbackState !== suggestInitialState;
 			const collectSelectedValuesSync = () => {
@@ -1287,7 +1311,7 @@ function multiple(parser, options = {}) {
 		},
 		getDocFragments(state, defaultValue) {
 			const latestState = state.kind === "available" && state.state.length > 0 ? state.state.at(-1) : void 0;
-			const latestInnerState = latestState != null && require_annotations.isInjectedAnnotationWrapper(latestState) ? unwrapInjectedWrapper(latestState) : latestState;
+			const latestInnerState = latestState != null && require_internal_annotations.isInjectedAnnotationWrapper(latestState) ? unwrapInjectedWrapper(latestState) : latestState;
 			const innerState = state.kind === "unavailable" ? { kind: "unavailable" } : latestInnerState !== void 0 ? {
 				kind: "available",
 				state: latestInnerState
@@ -1484,6 +1508,7 @@ function multiple(parser, options = {}) {
 */
 function nonEmpty(parser) {
 	const syncParser = parser;
+	const initialState = parser.initialState;
 	const processNonEmptyResult = (result) => {
 		if (!result.success) return result;
 		if (result.consumed.length === 0) return {
@@ -1509,7 +1534,12 @@ function nonEmpty(parser) {
 		usage: parser.usage,
 		leadingNames: parser.leadingNames,
 		acceptingAnyToken: parser.acceptingAnyToken,
-		initialState: parser.initialState,
+		initialState,
+		...typeof parser.canSkip === "function" ? { canSkip(state, exec) {
+			const unwrappedState = require_internal_annotations.unwrapInjectedAnnotationWrapper(state);
+			if (unwrappedState === initialState) return false;
+			return parser.canSkip?.(unwrappedState, exec) === true;
+		} } : {},
 		...typeof parser.shouldDeferCompletion === "function" ? { shouldDeferCompletion: parser.shouldDeferCompletion.bind(parser) } : {},
 		getSuggestRuntimeNodes(state, path) {
 			return parser.getSuggestRuntimeNodes?.(state, path) ?? (parser.dependencyMetadata?.source != null ? [{