@optique/core 1.1.0-dev.2086 → 1.1.0-dev.2096

package/dist/modifiers.js

@@ -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;
@@ -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 [{
@@ -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 [{
@@ -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, 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,
@@ -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,
@@ -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,7 +1221,8 @@ 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 dispatchIterableByMode(parser.mode, function* () {}, async function* () {});
 			const itemIndex = canExtendCurrent ? context.state.length - 1 : context.state.length;
@@ -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 = 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 ? [{

package/dist/primitives.cjs

@@ -23,6 +23,9 @@ function hasParsedOptionValue(state, valueParser) {
 	if (valueParser != null) return state != null && typeof state === "object" && "success" in state && typeof state.success === "boolean";
 	return state != null && "success" in state && state.success && state.value === true;
 }
+function isTerminalValueState(state) {
+	return state != null && typeof state === "object" && "success" in state && typeof state.success === "boolean";
+}
 /**
 * Helper function to create the stored state for an option or argument value.
 *
@@ -117,6 +120,9 @@ function constant(value) {
 		leadingNames: EMPTY_LEADING_NAMES,
 		acceptingAnyToken: false,
 		initialState: value,
+		canSkip() {
+			return true;
+		},
 		parse(context) {
 			return {
 				success: true,
@@ -174,6 +180,9 @@ function fail() {
 		leadingNames: EMPTY_LEADING_NAMES,
 		acceptingAnyToken: false,
 		initialState: void 0,
+		canSkip() {
+			return false;
+		},
 		parse(_context) {
 			return {
 				success: false,
@@ -431,6 +440,9 @@ function option(...args) {
 			success: true,
 			value: false
 		} : void 0,
+		canSkip(state) {
+			return valueParser == null || isTerminalValueState(state);
+		},
 		parse(context) {
 			if (context.optionsTerminated) return {
 				success: false,
@@ -782,6 +794,9 @@ function flag(...args) {
 		leadingNames: new Set(optionNames$1),
 		acceptingAnyToken: false,
 		initialState: void 0,
+		canSkip(state) {
+			return isTerminalValueState(state);
+		},
 		parse(context) {
 			if (context.optionsTerminated) return {
 				success: false,
@@ -1013,6 +1028,9 @@ function negatableFlag(names, options = {}) {
 		leadingNames: new Set(optionNames$1),
 		acceptingAnyToken: false,
 		initialState: void 0,
+		canSkip(state) {
+			return state != null;
+		},
 		parse(context) {
 			if (context.optionsTerminated) return {
 				success: false,
@@ -1177,6 +1195,9 @@ function argument(valueParser, options = {}) {
 		leadingNames: EMPTY_LEADING_NAMES,
 		acceptingAnyToken: true,
 		initialState: void 0,
+		canSkip(state) {
+			return isTerminalValueState(state);
+		},
 		parse(context) {
 			const localState = require_annotation_state.normalizeInjectedAnnotationState(context.state);
 			if (context.buffer.length < 1) return {
@@ -1433,6 +1454,12 @@ function command(name, parser, options = {}) {
 		leadingNames: new Set([name]),
 		acceptingAnyToken: false,
 		initialState: void 0,
+		canSkip(state, exec) {
+			const normalizedState = normalizeCommandState(state);
+			if (normalizedState === void 0) return false;
+			if (normalizedState[0] === "matched") return parser.canSkip?.(getCommandChildState(state, parser.initialState, parser), require_execution_context.withChildExecPath(exec, name)) === true;
+			return parser.canSkip?.(getCommandChildState(state, normalizedState[1], parser), require_execution_context.withChildExecPath(exec, name)) === true;
+		},
 		getSuggestRuntimeNodes(state, path) {
 			const normalizedState = normalizeCommandState(state);
 			if (normalizedState === void 0) return [];
@@ -1696,6 +1723,9 @@ function passThrough(options = {}) {
 		leadingNames: EMPTY_LEADING_NAMES,
 		acceptingAnyToken: false,
 		initialState: [],
+		canSkip() {
+			return true;
+		},
 		parse(context) {
 			if (context.buffer.length < 1) return {
 				success: false,

package/dist/primitives.js

@@ -23,6 +23,9 @@ function hasParsedOptionValue(state, valueParser) {
 	if (valueParser != null) return state != null && typeof state === "object" && "success" in state && typeof state.success === "boolean";
 	return state != null && "success" in state && state.success && state.value === true;
 }
+function isTerminalValueState(state) {
+	return state != null && typeof state === "object" && "success" in state && typeof state.success === "boolean";
+}
 /**
 * Helper function to create the stored state for an option or argument value.
 *
@@ -117,6 +120,9 @@ function constant(value) {
 		leadingNames: EMPTY_LEADING_NAMES,
 		acceptingAnyToken: false,
 		initialState: value,
+		canSkip() {
+			return true;
+		},
 		parse(context) {
 			return {
 				success: true,
@@ -174,6 +180,9 @@ function fail() {
 		leadingNames: EMPTY_LEADING_NAMES,
 		acceptingAnyToken: false,
 		initialState: void 0,
+		canSkip() {
+			return false;
+		},
 		parse(_context) {
 			return {
 				success: false,
@@ -431,6 +440,9 @@ function option(...args) {
 			success: true,
 			value: false
 		} : void 0,
+		canSkip(state) {
+			return valueParser == null || isTerminalValueState(state);
+		},
 		parse(context) {
 			if (context.optionsTerminated) return {
 				success: false,
@@ -782,6 +794,9 @@ function flag(...args) {
 		leadingNames: new Set(optionNames$1),
 		acceptingAnyToken: false,
 		initialState: void 0,
+		canSkip(state) {
+			return isTerminalValueState(state);
+		},
 		parse(context) {
 			if (context.optionsTerminated) return {
 				success: false,
@@ -1013,6 +1028,9 @@ function negatableFlag(names, options = {}) {
 		leadingNames: new Set(optionNames$1),
 		acceptingAnyToken: false,
 		initialState: void 0,
+		canSkip(state) {
+			return state != null;
+		},
 		parse(context) {
 			if (context.optionsTerminated) return {
 				success: false,
@@ -1177,6 +1195,9 @@ function argument(valueParser, options = {}) {
 		leadingNames: EMPTY_LEADING_NAMES,
 		acceptingAnyToken: true,
 		initialState: void 0,
+		canSkip(state) {
+			return isTerminalValueState(state);
+		},
 		parse(context) {
 			const localState = normalizeInjectedAnnotationState(context.state);
 			if (context.buffer.length < 1) return {
@@ -1433,6 +1454,12 @@ function command(name, parser, options = {}) {
 		leadingNames: new Set([name]),
 		acceptingAnyToken: false,
 		initialState: void 0,
+		canSkip(state, exec) {
+			const normalizedState = normalizeCommandState(state);
+			if (normalizedState === void 0) return false;
+			if (normalizedState[0] === "matched") return parser.canSkip?.(getCommandChildState(state, parser.initialState, parser), withChildExecPath(exec, name)) === true;
+			return parser.canSkip?.(getCommandChildState(state, normalizedState[1], parser), withChildExecPath(exec, name)) === true;
+		},
 		getSuggestRuntimeNodes(state, path) {
 			const normalizedState = normalizeCommandState(state);
 			if (normalizedState === void 0) return [];
@@ -1696,6 +1723,9 @@ function passThrough(options = {}) {
 		leadingNames: EMPTY_LEADING_NAMES,
 		acceptingAnyToken: false,
 		initialState: [],
+		canSkip() {
+			return true;
+		},
 		parse(context) {
 			if (context.buffer.length < 1) return {
 				success: false,

package/dist/usage-internals.cjs

@@ -16,31 +16,35 @@ const require_usage = require('./usage.cjs');
 * @returns `true` if every term in `terms` is skippable (i.e., the caller
 *          may continue scanning the next sibling term), `false` otherwise.
 */
-function collectLeadingCandidates(terms, optionNames, commandNames) {
+function collectLeadingCandidates(terms, optionNames, commandNames, includeHidden = false) {
 	if (!terms || !Array.isArray(terms)) return true;
 	for (const term of terms) {
 		if (term.type === "option") {
-			if (!require_usage.isSuggestionHidden(term.hidden)) for (const name of term.names) optionNames.add(name);
+			if (includeHidden || !require_usage.isSuggestionHidden(term.hidden)) for (const name of term.names) optionNames.add(name);
 			return false;
 		}
 		if (term.type === "command") {
-			if (!require_usage.isSuggestionHidden(term.hidden)) commandNames.add(term.name);
+			if (includeHidden || !require_usage.isSuggestionHidden(term.hidden)) commandNames.add(term.name);
 			return false;
 		}
 		if (term.type === "argument") return false;
 		if (term.type === "optional") {
-			collectLeadingCandidates(term.terms, optionNames, commandNames);
+			collectLeadingCandidates(term.terms, optionNames, commandNames, includeHidden);
 			continue;
 		}
 		if (term.type === "multiple") {
-			collectLeadingCandidates(term.terms, optionNames, commandNames);
+			collectLeadingCandidates(term.terms, optionNames, commandNames, includeHidden);
 			if (term.min === 0) continue;
 			return false;
 		}
+		if (term.type === "sequence") {
+			if (collectLeadingCandidates(term.terms, optionNames, commandNames, includeHidden)) continue;
+			return false;
+		}
 		if (term.type === "exclusive") {
 			let allSkippable = true;
 			for (const branch of term.terms) {
-				const branchSkippable = collectLeadingCandidates(branch, optionNames, commandNames);
+				const branchSkippable = collectLeadingCandidates(branch, optionNames, commandNames, includeHidden);
 				allSkippable = allSkippable && branchSkippable;
 			}
 			if (allSkippable) continue;

package/dist/usage-internals.js

@@ -16,31 +16,35 @@ import { isSuggestionHidden } from "./usage.js";
 * @returns `true` if every term in `terms` is skippable (i.e., the caller
 *          may continue scanning the next sibling term), `false` otherwise.
 */
-function collectLeadingCandidates(terms, optionNames, commandNames) {
+function collectLeadingCandidates(terms, optionNames, commandNames, includeHidden = false) {
 	if (!terms || !Array.isArray(terms)) return true;
 	for (const term of terms) {
 		if (term.type === "option") {
-			if (!isSuggestionHidden(term.hidden)) for (const name of term.names) optionNames.add(name);
+			if (includeHidden || !isSuggestionHidden(term.hidden)) for (const name of term.names) optionNames.add(name);
 			return false;
 		}
 		if (term.type === "command") {
-			if (!isSuggestionHidden(term.hidden)) commandNames.add(term.name);
+			if (includeHidden || !isSuggestionHidden(term.hidden)) commandNames.add(term.name);
 			return false;
 		}
 		if (term.type === "argument") return false;
 		if (term.type === "optional") {
-			collectLeadingCandidates(term.terms, optionNames, commandNames);
+			collectLeadingCandidates(term.terms, optionNames, commandNames, includeHidden);
 			continue;
 		}
 		if (term.type === "multiple") {
-			collectLeadingCandidates(term.terms, optionNames, commandNames);
+			collectLeadingCandidates(term.terms, optionNames, commandNames, includeHidden);
 			if (term.min === 0) continue;
 			return false;
 		}
+		if (term.type === "sequence") {
+			if (collectLeadingCandidates(term.terms, optionNames, commandNames, includeHidden)) continue;
+			return false;
+		}
 		if (term.type === "exclusive") {
 			let allSkippable = true;
 			for (const branch of term.terms) {
-				const branchSkippable = collectLeadingCandidates(branch, optionNames, commandNames);
+				const branchSkippable = collectLeadingCandidates(branch, optionNames, commandNames, includeHidden);
 				allSkippable = allSkippable && branchSkippable;
 			}
 			if (allSkippable) continue;

package/dist/usage.cjs

@@ -63,7 +63,7 @@ function extractOptionNames(usage, includeHidden) {
 		for (const term of terms) if (term.type === "option") {
 			if (!includeHidden && isSuggestionHidden(term.hidden)) continue;
 			for (const name of term.names) names.add(name);
-		} else if (term.type === "optional" || term.type === "multiple") traverseUsage(term.terms);
+		} else if (term.type === "optional" || term.type === "multiple" || term.type === "sequence") traverseUsage(term.terms);
 		else if (term.type === "exclusive") for (const exclusiveUsage of term.terms) traverseUsage(exclusiveUsage);
 	}
 	traverseUsage(usage);
@@ -98,7 +98,7 @@ function extractCommandNames(usage, includeHidden) {
 		for (const term of terms) if (term.type === "command") {
 			if (!includeHidden && isSuggestionHidden(term.hidden)) continue;
 			names.add(term.name);
-		} else if (term.type === "optional" || term.type === "multiple") traverseUsage(term.terms);
+		} else if (term.type === "optional" || term.type === "multiple" || term.type === "sequence") traverseUsage(term.terms);
 		else if (term.type === "exclusive") for (const exclusiveUsage of term.terms) traverseUsage(exclusiveUsage);
 	}
 	traverseUsage(usage);
@@ -121,7 +121,7 @@ function extractLiteralValues(usage) {
 	function traverseUsage(terms) {
 		if (!terms || !Array.isArray(terms)) return;
 		for (const term of terms) if (term.type === "literal") values.add(term.value);
-		else if (term.type === "optional" || term.type === "multiple") traverseUsage(term.terms);
+		else if (term.type === "optional" || term.type === "multiple" || term.type === "sequence") traverseUsage(term.terms);
 		else if (term.type === "exclusive") for (const branch of term.terms) traverseUsage(branch);
 	}
 	traverseUsage(usage);
@@ -155,7 +155,7 @@ function extractArgumentMetavars(usage) {
 		for (const term of terms) if (term.type === "argument") {
 			if (isSuggestionHidden(term.hidden)) continue;
 			metavars.add(term.metavar);
-		} else if (term.type === "optional" || term.type === "multiple") traverseUsage(term.terms);
+		} else if (term.type === "optional" || term.type === "multiple" || term.type === "sequence") traverseUsage(term.terms);
 		else if (term.type === "exclusive") for (const exclusiveUsage of term.terms) traverseUsage(exclusiveUsage);
 	}
 	traverseUsage(usage);
@@ -282,6 +282,10 @@ function normalizeUsageTerm(term) {
 		terms: normalizeUsage(term.terms),
 		min: term.min
 	};
+	else if (term.type === "sequence") return {
+		type: "sequence",
+		terms: term.terms.map(normalizeUsageTerm).filter(isNonDegenerateTerm)
+	};
 	else if (term.type === "exclusive") {
 		const terms = [];
 		for (const usage of term.terms) {
@@ -314,7 +318,7 @@ function isNonDegenerateTerm(term) {
 	if (term.type === "option") return term.names.length > 0;
 	if (term.type === "command") return term.name !== "";
 	if (term.type === "argument") return term.metavar.length > 0;
-	if (term.type === "optional" || term.type === "multiple" || term.type === "exclusive") return term.terms.length > 0;
+	if (term.type === "optional" || term.type === "multiple" || term.type === "exclusive" || term.type === "sequence") return term.terms.length > 0;
 	return true;
 }
 function containsMalformedLeaf(usage) {
@@ -322,7 +326,7 @@ function containsMalformedLeaf(usage) {
 		if (term.type === "option" && term.names.length === 0) return true;
 		if (term.type === "command" && term.name === "") return true;
 		if (term.type === "argument" && term.metavar.length === 0) return true;
-		if (term.type === "optional" || term.type === "multiple") {
+		if (term.type === "optional" || term.type === "multiple" || term.type === "sequence") {
 			if (containsMalformedLeaf(term.terms)) return true;
 		}
 		if (term.type === "exclusive") {
@@ -369,6 +373,10 @@ function cloneUsageTerm(term) {
 			type: "exclusive",
 			terms: term.terms.map((u) => u.map(cloneUsageTerm))
 		};
+		case "sequence": return {
+			type: "sequence",
+			terms: term.terms.map(cloneUsageTerm)
+		};
 		case "literal":
 		case "passthrough":
 		case "ellipsis": return { ...term };
@@ -421,6 +429,14 @@ function filterUsageForDisplay(usage, isHidden = isUsageHidden) {
 			});
 			continue;
 		}
+		if (term.type === "sequence") {
+			const filtered = filterUsageForDisplay(term.terms, isHidden);
+			if (filtered.length > 0) terms.push({
+				type: "sequence",
+				terms: filtered
+			});
+			continue;
+		}
 		terms.push(term);
 	}
 	return terms;
@@ -541,7 +557,8 @@ function* formatUsageTermInternal(term, options) {
 			text: options?.colors ? `\x1b[2m)\x1b[0m` : ")",
 			width: 1
 		};
-	} else if (term.type === "multiple") {
+	} else if (term.type === "sequence") yield* formatUsageTerms(term.terms, options);
+	else if (term.type === "multiple") {
 		if (term.min < 1) yield {
 			text: options?.colors ? `\x1b[2m[\x1b[0m` : "[",
 			width: 1

package/dist/usage.d.cts

@@ -164,6 +164,23 @@ type UsageTerm =
    */
   readonly terms: readonly Usage[];
 }
+/**
+ * A sequence term, which preserves the declaration order of its child
+ * terms through usage normalization.
+ *
+ * This is used by ordered parser combinators where argument/command/option
+ * order is part of the accepted grammar.
+ * @since 1.1.0
+ */ | {
+  /**
+   * The type of the term, which is always `"sequence"` for this term.
+   */
+  readonly type: "sequence";
+  /**
+   * Terms that must be displayed in the given order.
+   */
+  readonly terms: Usage;
+}
 /**
  * A literal term, which represents a fixed string value in the command-line
  * usage. Unlike metavars which are placeholders for user-provided values,

package/dist/usage.d.ts

@@ -164,6 +164,23 @@ type UsageTerm =
    */
   readonly terms: readonly Usage[];
 }
+/**
+ * A sequence term, which preserves the declaration order of its child
+ * terms through usage normalization.
+ *
+ * This is used by ordered parser combinators where argument/command/option
+ * order is part of the accepted grammar.
+ * @since 1.1.0
+ */ | {
+  /**
+   * The type of the term, which is always `"sequence"` for this term.
+   */
+  readonly type: "sequence";
+  /**
+   * Terms that must be displayed in the given order.
+   */
+  readonly terms: Usage;
+}
 /**
  * A literal term, which represents a fixed string value in the command-line
  * usage. Unlike metavars which are placeholders for user-provided values,

package/dist/usage.js

@@ -63,7 +63,7 @@ function extractOptionNames(usage, includeHidden) {
 		for (const term of terms) if (term.type === "option") {
 			if (!includeHidden && isSuggestionHidden(term.hidden)) continue;
 			for (const name of term.names) names.add(name);
-		} else if (term.type === "optional" || term.type === "multiple") traverseUsage(term.terms);
+		} else if (term.type === "optional" || term.type === "multiple" || term.type === "sequence") traverseUsage(term.terms);
 		else if (term.type === "exclusive") for (const exclusiveUsage of term.terms) traverseUsage(exclusiveUsage);
 	}
 	traverseUsage(usage);
@@ -98,7 +98,7 @@ function extractCommandNames(usage, includeHidden) {
 		for (const term of terms) if (term.type === "command") {
 			if (!includeHidden && isSuggestionHidden(term.hidden)) continue;
 			names.add(term.name);
-		} else if (term.type === "optional" || term.type === "multiple") traverseUsage(term.terms);
+		} else if (term.type === "optional" || term.type === "multiple" || term.type === "sequence") traverseUsage(term.terms);
 		else if (term.type === "exclusive") for (const exclusiveUsage of term.terms) traverseUsage(exclusiveUsage);
 	}
 	traverseUsage(usage);
@@ -121,7 +121,7 @@ function extractLiteralValues(usage) {
 	function traverseUsage(terms) {
 		if (!terms || !Array.isArray(terms)) return;
 		for (const term of terms) if (term.type === "literal") values.add(term.value);
-		else if (term.type === "optional" || term.type === "multiple") traverseUsage(term.terms);
+		else if (term.type === "optional" || term.type === "multiple" || term.type === "sequence") traverseUsage(term.terms);
 		else if (term.type === "exclusive") for (const branch of term.terms) traverseUsage(branch);
 	}
 	traverseUsage(usage);
@@ -155,7 +155,7 @@ function extractArgumentMetavars(usage) {
 		for (const term of terms) if (term.type === "argument") {
 			if (isSuggestionHidden(term.hidden)) continue;
 			metavars.add(term.metavar);
-		} else if (term.type === "optional" || term.type === "multiple") traverseUsage(term.terms);
+		} else if (term.type === "optional" || term.type === "multiple" || term.type === "sequence") traverseUsage(term.terms);
 		else if (term.type === "exclusive") for (const exclusiveUsage of term.terms) traverseUsage(exclusiveUsage);
 	}
 	traverseUsage(usage);
@@ -282,6 +282,10 @@ function normalizeUsageTerm(term) {
 		terms: normalizeUsage(term.terms),
 		min: term.min
 	};
+	else if (term.type === "sequence") return {
+		type: "sequence",
+		terms: term.terms.map(normalizeUsageTerm).filter(isNonDegenerateTerm)
+	};
 	else if (term.type === "exclusive") {
 		const terms = [];
 		for (const usage of term.terms) {
@@ -314,7 +318,7 @@ function isNonDegenerateTerm(term) {
 	if (term.type === "option") return term.names.length > 0;
 	if (term.type === "command") return term.name !== "";
 	if (term.type === "argument") return term.metavar.length > 0;
-	if (term.type === "optional" || term.type === "multiple" || term.type === "exclusive") return term.terms.length > 0;
+	if (term.type === "optional" || term.type === "multiple" || term.type === "exclusive" || term.type === "sequence") return term.terms.length > 0;
 	return true;
 }
 function containsMalformedLeaf(usage) {
@@ -322,7 +326,7 @@ function containsMalformedLeaf(usage) {
 		if (term.type === "option" && term.names.length === 0) return true;
 		if (term.type === "command" && term.name === "") return true;
 		if (term.type === "argument" && term.metavar.length === 0) return true;
-		if (term.type === "optional" || term.type === "multiple") {
+		if (term.type === "optional" || term.type === "multiple" || term.type === "sequence") {
 			if (containsMalformedLeaf(term.terms)) return true;
 		}
 		if (term.type === "exclusive") {
@@ -369,6 +373,10 @@ function cloneUsageTerm(term) {
 			type: "exclusive",
 			terms: term.terms.map((u) => u.map(cloneUsageTerm))
 		};
+		case "sequence": return {
+			type: "sequence",
+			terms: term.terms.map(cloneUsageTerm)
+		};
 		case "literal":
 		case "passthrough":
 		case "ellipsis": return { ...term };
@@ -421,6 +429,14 @@ function filterUsageForDisplay(usage, isHidden = isUsageHidden) {
 			});
 			continue;
 		}
+		if (term.type === "sequence") {
+			const filtered = filterUsageForDisplay(term.terms, isHidden);
+			if (filtered.length > 0) terms.push({
+				type: "sequence",
+				terms: filtered
+			});
+			continue;
+		}
 		terms.push(term);
 	}
 	return terms;
@@ -541,7 +557,8 @@ function* formatUsageTermInternal(term, options) {
 			text: options?.colors ? `\x1b[2m)\x1b[0m` : ")",
 			width: 1
 		};
-	} else if (term.type === "multiple") {
+	} else if (term.type === "sequence") yield* formatUsageTerms(term.terms, options);
+	else if (term.type === "multiple") {
 		if (term.min < 1) yield {
 			text: options?.colors ? `\x1b[2m[\x1b[0m` : "[",
 			width: 1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/core",
-  "version": "1.1.0-dev.2086",
+  "version": "1.1.0-dev.2096",
   "description": "Type-safe combinatorial command-line interface parser",
   "keywords": [
     "CLI",