@optique/core 1.0.2 → 1.0.5

package/dist/constructs.cjs

@@ -516,6 +516,35 @@ function createExclusiveState(parentState, index, parser, result) {
 	return require_annotations.annotateFreshArray(parentState, [index, annotatedResult]);
 }
 /**
+* Detects a branch result that handled only the global options terminator.
+* Such a result advances the shared parser context, but does not identify
+* which exclusive branch matched.
+* @internal
+*/
+function isOptionsTerminatorOnlyResult(context, result) {
+	return !context.optionsTerminated && context.buffer[0] === "--" && result.success && result.next.optionsTerminated && result.consumed.length === 1 && result.consumed[0] === "--";
+}
+function isUnselectedBooleanOptionState(state) {
+	return state != null && typeof state === "object" && "success" in state && state.success === true && "value" in state && state.value === false;
+}
+function preserveExclusiveStateAfterOptionsTerminator(context, result) {
+	const mergedExec = require_execution_context.mergeChildExec(context.exec, result.next.exec);
+	return {
+		success: true,
+		next: {
+			...context,
+			buffer: result.next.buffer,
+			optionsTerminated: true,
+			state: context.state,
+			...mergedExec != null ? {
+				exec: mergedExec,
+				dependencyRegistry: mergedExec.dependencyRegistry
+			} : {}
+		},
+		consumed: result.consumed
+	};
+}
+/**
 * Creates a complete() method shared by or() and longestMatch().
 * @internal
 */
@@ -752,9 +781,15 @@ function or(...args) {
 		let zeroConsumedBranch = null;
 		let zeroConsumedCount = 0;
 		let provisionalConsuming = null;
+		let optionsTerminatorResult = null;
 		let provisionalAmbiguous = false;
 		for (const [parser, i] of orderedParsers) {
 			const result = parser.parse(withChildContext$1(context, i, activeState == null || activeState[0] !== i || !activeState[1].success ? parser.initialState : activeState[1].next.state, parser));
+			if (isOptionsTerminatorOnlyResult(context, result)) {
+				if (activeState?.[0] === i && activeState[1].success && activeState[1].consumed.length > 0 && result.next.buffer.length < 1) return preserveExclusiveStateAfterOptionsTerminator(context, result);
+				optionsTerminatorResult ??= result;
+				continue;
+			}
 			if (result.success && result.consumed.length > 0) {
 				if (result.provisional) {
 					const activeBranchLocked = activeState != null && activeState[1].success && activeState[1].consumed.length > 0;
@@ -935,6 +970,7 @@ function or(...args) {
 				}
 			}
 		}
+		if (optionsTerminatorResult != null) return preserveExclusiveStateAfterOptionsTerminator(context, optionsTerminatorResult);
 		return {
 			...error,
 			success: false
@@ -948,10 +984,16 @@ function or(...args) {
 		let zeroConsumedBranch = null;
 		let zeroConsumedCount = 0;
 		let provisionalConsuming = null;
+		let optionsTerminatorResult = null;
 		let provisionalAmbiguous = false;
 		for (const [parser, i] of orderedParsers) {
 			const resultOrPromise = parser.parse(withChildContext$1(context, i, activeState == null || activeState[0] !== i || !activeState[1].success ? parser.initialState : activeState[1].next.state, parser));
 			const result = await resultOrPromise;
+			if (isOptionsTerminatorOnlyResult(context, result)) {
+				if (activeState?.[0] === i && activeState[1].success && activeState[1].consumed.length > 0 && result.next.buffer.length < 1) return preserveExclusiveStateAfterOptionsTerminator(context, result);
+				optionsTerminatorResult ??= result;
+				continue;
+			}
 			if (result.success && result.consumed.length > 0) {
 				if (result.provisional) {
 					const activeBranchLocked = activeState != null && activeState[1].success && activeState[1].consumed.length > 0;
@@ -1134,6 +1176,7 @@ function or(...args) {
 				}
 			}
 		}
+		if (optionsTerminatorResult != null) return preserveExclusiveStateAfterOptionsTerminator(context, optionsTerminatorResult);
 		return {
 			...error,
 			success: false
@@ -1221,82 +1264,122 @@ function longestMatch(...args) {
 			return createUnexpectedInputErrorWithScopedSuggestions(defaultMsg, token, parsers, options?.errors?.suggestions);
 		})()
 	});
-	const parseSync = (context) => {
+	const commitLongestMatch = (context, match, optionsTerminatorResult) => {
+		const selectedResult = optionsTerminatorResult == null ? match.result : {
+			...match.result,
+			next: {
+				...match.result.next,
+				buffer: optionsTerminatorResult.next.buffer,
+				optionsTerminated: true
+			},
+			consumed: [...optionsTerminatorResult.consumed, ...match.result.consumed]
+		};
+		const parser = parsers[match.index];
+		const mergedExec = require_execution_context.mergeChildExec(context.exec, selectedResult.next.exec);
+		return {
+			success: true,
+			next: {
+				...context,
+				buffer: selectedResult.next.buffer,
+				optionsTerminated: selectedResult.next.optionsTerminated,
+				state: createExclusiveState(context.state, match.index, parser, selectedResult),
+				...mergedExec != null ? {
+					exec: mergedExec,
+					dependencyRegistry: mergedExec.dependencyRegistry
+				} : {}
+			},
+			consumed: selectedResult.consumed
+		};
+	};
+	const resolveLongestMatchOptionsTerminator = (context, bestMatch, optionsTerminatorMatches) => {
+		if (optionsTerminatorMatches.length < 1) return null;
+		if (bestMatch != null && bestMatch.consumed > 0) return null;
+		const activeState = normalizeExclusiveState(context.state);
+		if (activeState != null && activeState[1].success && activeState[1].consumed.length > 0) return preserveExclusiveStateAfterOptionsTerminator(context, optionsTerminatorMatches[0].result);
+		let selected = bestMatch == null ? null : {
+			match: bestMatch,
+			fromTerminator: false
+		};
+		for (const match of optionsTerminatorMatches) {
+			if (!match.selectedAfterTerminator && (extractRequiredUsage(parsers[match.index].usage).length > 0 || isUnselectedBooleanOptionState(match.result.next.state))) continue;
+			const selectedIsProvisional = selected != null && !!selected.match.result.provisional;
+			const matchIsProvisional = !!match.result.provisional;
+			if (selected == null || selectedIsProvisional && !matchIsProvisional || selectedIsProvisional === matchIsProvisional && match.index < selected.match.index) selected = {
+				match,
+				fromTerminator: true
+			};
+		}
+		if (selected != null) return commitLongestMatch(context, selected.match, selected.fromTerminator ? void 0 : optionsTerminatorMatches[0].result);
+		return preserveExclusiveStateAfterOptionsTerminator(context, optionsTerminatorMatches[0].result);
+	};
+	const parseSyncBranches = (context) => {
 		let bestMatch = null;
+		const optionsTerminatorMatches = [];
 		let error = getInitialError(context);
 		const activeState = normalizeExclusiveState(context.state);
 		for (let i = 0; i < syncParsers.length; i++) {
 			const parser = syncParsers[i];
-			const result = parser.parse(withChildContext$1(context, i, activeState == null || activeState[0] !== i || !activeState[1].success ? parser.initialState : activeState[1].next.state, parser));
+			const childContext = withChildContext$1(context, i, activeState == null || activeState[0] !== i || !activeState[1].success ? parser.initialState : activeState[1].next.state, parser);
+			const result = parser.parse(childContext);
+			if (isOptionsTerminatorOnlyResult(context, result)) {
+				optionsTerminatorMatches.push({
+					index: i,
+					result,
+					consumed: 1,
+					...normalizeExclusiveState(result.next.state) != null ? { selectedAfterTerminator: true } : {}
+				});
+				continue;
+			}
 			if (result.success) {
 				const consumed = context.buffer.length - result.next.buffer.length;
 				const bestIsProvisional = bestMatch != null && bestMatch.result.success && !!bestMatch.result.provisional;
 				if (bestMatch === null || consumed > bestMatch.consumed || consumed === bestMatch.consumed && bestIsProvisional && !result.provisional) bestMatch = {
 					index: i,
-					parser,
 					result,
 					consumed
 				};
 			} else if (error.consumed < result.consumed) error = result;
 		}
-		if (bestMatch && bestMatch.result.success) {
-			const mergedExec = require_execution_context.mergeChildExec(context.exec, bestMatch.result.next.exec);
-			return {
-				success: true,
-				next: {
-					...context,
-					buffer: bestMatch.result.next.buffer,
-					optionsTerminated: bestMatch.result.next.optionsTerminated,
-					state: createExclusiveState(context.state, bestMatch.index, bestMatch.parser, bestMatch.result),
-					...mergedExec != null ? {
-						exec: mergedExec,
-						dependencyRegistry: mergedExec.dependencyRegistry
-					} : {}
-				},
-				consumed: bestMatch.result.consumed
-			};
-		}
+		const optionsTerminatorResolution = resolveLongestMatchOptionsTerminator(context, bestMatch, optionsTerminatorMatches);
+		if (optionsTerminatorResolution != null) return optionsTerminatorResolution;
+		if (bestMatch != null) return commitLongestMatch(context, bestMatch);
 		return {
 			...error,
 			success: false
 		};
 	};
-	const parseAsync = async (context) => {
+	const parseAsyncBranches = async (context) => {
 		let bestMatch = null;
+		const optionsTerminatorMatches = [];
 		let error = getInitialError(context);
 		const activeState = normalizeExclusiveState(context.state);
 		for (let i = 0; i < parsers.length; i++) {
 			const parser = parsers[i];
-			const resultOrPromise = parser.parse(withChildContext$1(context, i, activeState == null || activeState[0] !== i || !activeState[1].success ? parser.initialState : activeState[1].next.state, parser));
+			const childContext = withChildContext$1(context, i, activeState == null || activeState[0] !== i || !activeState[1].success ? parser.initialState : activeState[1].next.state, parser);
+			const resultOrPromise = parser.parse(childContext);
 			const result = await resultOrPromise;
+			if (isOptionsTerminatorOnlyResult(context, result)) {
+				optionsTerminatorMatches.push({
+					index: i,
+					result,
+					consumed: 1,
+					...normalizeExclusiveState(result.next.state) != null ? { selectedAfterTerminator: true } : {}
+				});
+				continue;
+			}
 			if (result.success) {
 				const consumed = context.buffer.length - result.next.buffer.length;
 				const bestIsProvisional = bestMatch != null && bestMatch.result.success && !!bestMatch.result.provisional;
 				if (bestMatch === null || consumed > bestMatch.consumed || consumed === bestMatch.consumed && bestIsProvisional && !result.provisional) bestMatch = {
 					index: i,
-					parser,
 					result,
 					consumed
 				};
 			} else if (error.consumed < result.consumed) error = result;
 		}
-		if (bestMatch && bestMatch.result.success) {
-			const mergedExec = require_execution_context.mergeChildExec(context.exec, bestMatch.result.next.exec);
-			return {
-				success: true,
-				next: {
-					...context,
-					buffer: bestMatch.result.next.buffer,
-					optionsTerminated: bestMatch.result.next.optionsTerminated,
-					state: createExclusiveState(context.state, bestMatch.index, bestMatch.parser, bestMatch.result),
-					...mergedExec != null ? {
-						exec: mergedExec,
-						dependencyRegistry: mergedExec.dependencyRegistry
-					} : {}
-				},
-				consumed: bestMatch.result.consumed
-			};
-		}
+		const optionsTerminatorResolution = resolveLongestMatchOptionsTerminator(context, bestMatch, optionsTerminatorMatches);
+		if (optionsTerminatorResolution != null) return optionsTerminatorResolution;
+		if (bestMatch != null) return commitLongestMatch(context, bestMatch);
 		return {
 			...error,
 			success: false
@@ -1319,7 +1402,7 @@ function longestMatch(...args) {
 			return extractExclusivePhase2Seed(parsers, state, exec, combinedMode);
 		},
 		parse(context) {
-			return require_mode_dispatch.dispatchByMode(combinedMode, () => parseSync(context), () => parseAsync(context));
+			return require_mode_dispatch.dispatchByMode(combinedMode, () => parseSyncBranches(context), () => parseAsyncBranches(context));
 		},
 		getSuggestRuntimeNodes(state, path) {
 			return getExclusiveSuggestRuntimeNodes(parsers, state, path);

package/dist/constructs.js

@@ -516,6 +516,35 @@ function createExclusiveState(parentState, index, parser, result) {
 	return annotateFreshArray(parentState, [index, annotatedResult]);
 }
 /**
+* Detects a branch result that handled only the global options terminator.
+* Such a result advances the shared parser context, but does not identify
+* which exclusive branch matched.
+* @internal
+*/
+function isOptionsTerminatorOnlyResult(context, result) {
+	return !context.optionsTerminated && context.buffer[0] === "--" && result.success && result.next.optionsTerminated && result.consumed.length === 1 && result.consumed[0] === "--";
+}
+function isUnselectedBooleanOptionState(state) {
+	return state != null && typeof state === "object" && "success" in state && state.success === true && "value" in state && state.value === false;
+}
+function preserveExclusiveStateAfterOptionsTerminator(context, result) {
+	const mergedExec = mergeChildExec(context.exec, result.next.exec);
+	return {
+		success: true,
+		next: {
+			...context,
+			buffer: result.next.buffer,
+			optionsTerminated: true,
+			state: context.state,
+			...mergedExec != null ? {
+				exec: mergedExec,
+				dependencyRegistry: mergedExec.dependencyRegistry
+			} : {}
+		},
+		consumed: result.consumed
+	};
+}
+/**
 * Creates a complete() method shared by or() and longestMatch().
 * @internal
 */
@@ -752,9 +781,15 @@ function or(...args) {
 		let zeroConsumedBranch = null;
 		let zeroConsumedCount = 0;
 		let provisionalConsuming = null;
+		let optionsTerminatorResult = null;
 		let provisionalAmbiguous = false;
 		for (const [parser, i] of orderedParsers) {
 			const result = parser.parse(withChildContext$1(context, i, activeState == null || activeState[0] !== i || !activeState[1].success ? parser.initialState : activeState[1].next.state, parser));
+			if (isOptionsTerminatorOnlyResult(context, result)) {
+				if (activeState?.[0] === i && activeState[1].success && activeState[1].consumed.length > 0 && result.next.buffer.length < 1) return preserveExclusiveStateAfterOptionsTerminator(context, result);
+				optionsTerminatorResult ??= result;
+				continue;
+			}
 			if (result.success && result.consumed.length > 0) {
 				if (result.provisional) {
 					const activeBranchLocked = activeState != null && activeState[1].success && activeState[1].consumed.length > 0;
@@ -935,6 +970,7 @@ function or(...args) {
 				}
 			}
 		}
+		if (optionsTerminatorResult != null) return preserveExclusiveStateAfterOptionsTerminator(context, optionsTerminatorResult);
 		return {
 			...error,
 			success: false
@@ -948,10 +984,16 @@ function or(...args) {
 		let zeroConsumedBranch = null;
 		let zeroConsumedCount = 0;
 		let provisionalConsuming = null;
+		let optionsTerminatorResult = null;
 		let provisionalAmbiguous = false;
 		for (const [parser, i] of orderedParsers) {
 			const resultOrPromise = parser.parse(withChildContext$1(context, i, activeState == null || activeState[0] !== i || !activeState[1].success ? parser.initialState : activeState[1].next.state, parser));
 			const result = await resultOrPromise;
+			if (isOptionsTerminatorOnlyResult(context, result)) {
+				if (activeState?.[0] === i && activeState[1].success && activeState[1].consumed.length > 0 && result.next.buffer.length < 1) return preserveExclusiveStateAfterOptionsTerminator(context, result);
+				optionsTerminatorResult ??= result;
+				continue;
+			}
 			if (result.success && result.consumed.length > 0) {
 				if (result.provisional) {
 					const activeBranchLocked = activeState != null && activeState[1].success && activeState[1].consumed.length > 0;
@@ -1134,6 +1176,7 @@ function or(...args) {
 				}
 			}
 		}
+		if (optionsTerminatorResult != null) return preserveExclusiveStateAfterOptionsTerminator(context, optionsTerminatorResult);
 		return {
 			...error,
 			success: false
@@ -1221,82 +1264,122 @@ function longestMatch(...args) {
 			return createUnexpectedInputErrorWithScopedSuggestions(defaultMsg, token, parsers, options?.errors?.suggestions);
 		})()
 	});
-	const parseSync = (context) => {
+	const commitLongestMatch = (context, match, optionsTerminatorResult) => {
+		const selectedResult = optionsTerminatorResult == null ? match.result : {
+			...match.result,
+			next: {
+				...match.result.next,
+				buffer: optionsTerminatorResult.next.buffer,
+				optionsTerminated: true
+			},
+			consumed: [...optionsTerminatorResult.consumed, ...match.result.consumed]
+		};
+		const parser = parsers[match.index];
+		const mergedExec = mergeChildExec(context.exec, selectedResult.next.exec);
+		return {
+			success: true,
+			next: {
+				...context,
+				buffer: selectedResult.next.buffer,
+				optionsTerminated: selectedResult.next.optionsTerminated,
+				state: createExclusiveState(context.state, match.index, parser, selectedResult),
+				...mergedExec != null ? {
+					exec: mergedExec,
+					dependencyRegistry: mergedExec.dependencyRegistry
+				} : {}
+			},
+			consumed: selectedResult.consumed
+		};
+	};
+	const resolveLongestMatchOptionsTerminator = (context, bestMatch, optionsTerminatorMatches) => {
+		if (optionsTerminatorMatches.length < 1) return null;
+		if (bestMatch != null && bestMatch.consumed > 0) return null;
+		const activeState = normalizeExclusiveState(context.state);
+		if (activeState != null && activeState[1].success && activeState[1].consumed.length > 0) return preserveExclusiveStateAfterOptionsTerminator(context, optionsTerminatorMatches[0].result);
+		let selected = bestMatch == null ? null : {
+			match: bestMatch,
+			fromTerminator: false
+		};
+		for (const match of optionsTerminatorMatches) {
+			if (!match.selectedAfterTerminator && (extractRequiredUsage(parsers[match.index].usage).length > 0 || isUnselectedBooleanOptionState(match.result.next.state))) continue;
+			const selectedIsProvisional = selected != null && !!selected.match.result.provisional;
+			const matchIsProvisional = !!match.result.provisional;
+			if (selected == null || selectedIsProvisional && !matchIsProvisional || selectedIsProvisional === matchIsProvisional && match.index < selected.match.index) selected = {
+				match,
+				fromTerminator: true
+			};
+		}
+		if (selected != null) return commitLongestMatch(context, selected.match, selected.fromTerminator ? void 0 : optionsTerminatorMatches[0].result);
+		return preserveExclusiveStateAfterOptionsTerminator(context, optionsTerminatorMatches[0].result);
+	};
+	const parseSyncBranches = (context) => {
 		let bestMatch = null;
+		const optionsTerminatorMatches = [];
 		let error = getInitialError(context);
 		const activeState = normalizeExclusiveState(context.state);
 		for (let i = 0; i < syncParsers.length; i++) {
 			const parser = syncParsers[i];
-			const result = parser.parse(withChildContext$1(context, i, activeState == null || activeState[0] !== i || !activeState[1].success ? parser.initialState : activeState[1].next.state, parser));
+			const childContext = withChildContext$1(context, i, activeState == null || activeState[0] !== i || !activeState[1].success ? parser.initialState : activeState[1].next.state, parser);
+			const result = parser.parse(childContext);
+			if (isOptionsTerminatorOnlyResult(context, result)) {
+				optionsTerminatorMatches.push({
+					index: i,
+					result,
+					consumed: 1,
+					...normalizeExclusiveState(result.next.state) != null ? { selectedAfterTerminator: true } : {}
+				});
+				continue;
+			}
 			if (result.success) {
 				const consumed = context.buffer.length - result.next.buffer.length;
 				const bestIsProvisional = bestMatch != null && bestMatch.result.success && !!bestMatch.result.provisional;
 				if (bestMatch === null || consumed > bestMatch.consumed || consumed === bestMatch.consumed && bestIsProvisional && !result.provisional) bestMatch = {
 					index: i,
-					parser,
 					result,
 					consumed
 				};
 			} else if (error.consumed < result.consumed) error = result;
 		}
-		if (bestMatch && bestMatch.result.success) {
-			const mergedExec = mergeChildExec(context.exec, bestMatch.result.next.exec);
-			return {
-				success: true,
-				next: {
-					...context,
-					buffer: bestMatch.result.next.buffer,
-					optionsTerminated: bestMatch.result.next.optionsTerminated,
-					state: createExclusiveState(context.state, bestMatch.index, bestMatch.parser, bestMatch.result),
-					...mergedExec != null ? {
-						exec: mergedExec,
-						dependencyRegistry: mergedExec.dependencyRegistry
-					} : {}
-				},
-				consumed: bestMatch.result.consumed
-			};
-		}
+		const optionsTerminatorResolution = resolveLongestMatchOptionsTerminator(context, bestMatch, optionsTerminatorMatches);
+		if (optionsTerminatorResolution != null) return optionsTerminatorResolution;
+		if (bestMatch != null) return commitLongestMatch(context, bestMatch);
 		return {
 			...error,
 			success: false
 		};
 	};
-	const parseAsync = async (context) => {
+	const parseAsyncBranches = async (context) => {
 		let bestMatch = null;
+		const optionsTerminatorMatches = [];
 		let error = getInitialError(context);
 		const activeState = normalizeExclusiveState(context.state);
 		for (let i = 0; i < parsers.length; i++) {
 			const parser = parsers[i];
-			const resultOrPromise = parser.parse(withChildContext$1(context, i, activeState == null || activeState[0] !== i || !activeState[1].success ? parser.initialState : activeState[1].next.state, parser));
+			const childContext = withChildContext$1(context, i, activeState == null || activeState[0] !== i || !activeState[1].success ? parser.initialState : activeState[1].next.state, parser);
+			const resultOrPromise = parser.parse(childContext);
 			const result = await resultOrPromise;
+			if (isOptionsTerminatorOnlyResult(context, result)) {
+				optionsTerminatorMatches.push({
+					index: i,
+					result,
+					consumed: 1,
+					...normalizeExclusiveState(result.next.state) != null ? { selectedAfterTerminator: true } : {}
+				});
+				continue;
+			}
 			if (result.success) {
 				const consumed = context.buffer.length - result.next.buffer.length;
 				const bestIsProvisional = bestMatch != null && bestMatch.result.success && !!bestMatch.result.provisional;
 				if (bestMatch === null || consumed > bestMatch.consumed || consumed === bestMatch.consumed && bestIsProvisional && !result.provisional) bestMatch = {
 					index: i,
-					parser,
 					result,
 					consumed
 				};
 			} else if (error.consumed < result.consumed) error = result;
 		}
-		if (bestMatch && bestMatch.result.success) {
-			const mergedExec = mergeChildExec(context.exec, bestMatch.result.next.exec);
-			return {
-				success: true,
-				next: {
-					...context,
-					buffer: bestMatch.result.next.buffer,
-					optionsTerminated: bestMatch.result.next.optionsTerminated,
-					state: createExclusiveState(context.state, bestMatch.index, bestMatch.parser, bestMatch.result),
-					...mergedExec != null ? {
-						exec: mergedExec,
-						dependencyRegistry: mergedExec.dependencyRegistry
-					} : {}
-				},
-				consumed: bestMatch.result.consumed
-			};
-		}
+		const optionsTerminatorResolution = resolveLongestMatchOptionsTerminator(context, bestMatch, optionsTerminatorMatches);
+		if (optionsTerminatorResolution != null) return optionsTerminatorResolution;
+		if (bestMatch != null) return commitLongestMatch(context, bestMatch);
 		return {
 			...error,
 			success: false
@@ -1319,7 +1402,7 @@ function longestMatch(...args) {
 			return extractExclusivePhase2Seed(parsers, state, exec, combinedMode);
 		},
 		parse(context) {
-			return dispatchByMode(combinedMode, () => parseSync(context), () => parseAsync(context));
+			return dispatchByMode(combinedMode, () => parseSyncBranches(context), () => parseAsyncBranches(context));
 		},
 		getSuggestRuntimeNodes(state, path) {
 			return getExclusiveSuggestRuntimeNodes(parsers, state, path);

package/dist/primitives.cjs

@@ -237,7 +237,7 @@ function* getSuggestionsWithDependency(valueParser, prefix, dependencyRegistry,
 * Internal sync helper for option suggest functionality.
 * @internal
 */
-function* suggestOptionSync(optionNames$1, valueParser, hidden, context, prefix) {
+function* suggestOptionSync(optionNames$1, valueParser, hidden, description, context, prefix) {
 	if (hidden) return;
 	const equalsIndex = prefix.indexOf("=");
 	if (equalsIndex >= 0) {
@@ -265,7 +265,8 @@ function* suggestOptionSync(optionNames$1, valueParser, hidden, context, prefix)
 				if (prefix === "-" && optionName$1.length !== 2) continue;
 				yield {
 					kind: "literal",
-					text: optionName$1
+					text: optionName$1,
+					...description && { description }
 				};
 			}
 		}
@@ -321,7 +322,7 @@ async function* getSuggestionsWithDependencyAsync(valueParser, prefix, dependenc
 * Internal async helper for option suggest functionality.
 * @internal
 */
-async function* suggestOptionAsync(optionNames$1, valueParser, hidden, context, prefix) {
+async function* suggestOptionAsync(optionNames$1, valueParser, hidden, description, context, prefix) {
 	if (hidden) return;
 	const equalsIndex = prefix.indexOf("=");
 	if (equalsIndex >= 0) {
@@ -349,7 +350,8 @@ async function* suggestOptionAsync(optionNames$1, valueParser, hidden, context,
 				if (prefix === "-" && optionName$1.length !== 2) continue;
 				yield {
 					kind: "literal",
-					text: optionName$1
+					text: optionName$1,
+					...description && { description }
 				};
 			}
 		}
@@ -615,8 +617,8 @@ function option(...args) {
 			return require_mode_dispatch.dispatchByMode(mode, completeSync, completeAsync);
 		},
 		suggest(context, prefix) {
-			if (isAsync) return suggestOptionAsync(optionNames$1, valueParser, require_usage.isSuggestionHidden(options.hidden), context, prefix);
-			return suggestOptionSync(optionNames$1, valueParser, require_usage.isSuggestionHidden(options.hidden), context, prefix);
+			if (isAsync) return suggestOptionAsync(optionNames$1, valueParser, require_usage.isSuggestionHidden(options.hidden), options.description, context, prefix);
+			return suggestOptionSync(optionNames$1, valueParser, require_usage.isSuggestionHidden(options.hidden), options.description, context, prefix);
 		},
 		getDocFragments(_state, defaultValue) {
 			if (require_usage.isDocHidden(options.hidden)) return {
@@ -893,7 +895,8 @@ function flag(...args) {
 					if (prefix === "-" && optionName$1.length !== 2) continue;
 					suggestions.push({
 						kind: "literal",
-						text: optionName$1
+						text: optionName$1,
+						...options.description && { description: options.description }
 					});
 				}
 			}
@@ -1157,11 +1160,14 @@ function* suggestCommandSync(context, prefix, name, parser, options) {
 	if (require_usage.isSuggestionHidden(options.hidden)) return;
 	const state = normalizeCommandState(context.state);
 	if (state === void 0) {
-		if (name.startsWith(prefix)) yield {
-			kind: "literal",
-			text: name,
-			...options.description && { description: options.description }
-		};
+		if (name.startsWith(prefix)) {
+			const description = options.brief ?? options.description;
+			yield {
+				kind: "literal",
+				text: name,
+				...description && { description }
+			};
+		}
 	} else if (state[0] === "matched") yield* parser.suggest(require_execution_context.withChildContext(context, name, getCommandChildState(context.state, parser.initialState, parser), parser.usage), prefix);
 	else if (state[0] === "parsing") yield* parser.suggest(require_execution_context.withChildContext(context, name, getCommandChildState(context.state, state[1], parser), parser.usage), prefix);
 }
@@ -1169,11 +1175,14 @@ async function* suggestCommandAsync(context, prefix, name, parser, options) {
 	if (require_usage.isSuggestionHidden(options.hidden)) return;
 	const state = normalizeCommandState(context.state);
 	if (state === void 0) {
-		if (name.startsWith(prefix)) yield {
-			kind: "literal",
-			text: name,
-			...options.description && { description: options.description }
-		};
+		if (name.startsWith(prefix)) {
+			const description = options.brief ?? options.description;
+			yield {
+				kind: "literal",
+				text: name,
+				...description && { description }
+			};
+		}
 	} else if (state[0] === "matched") {
 		const suggestions = parser.suggest(require_execution_context.withChildContext(context, name, getCommandChildState(context.state, parser.initialState, parser), parser.usage), prefix);
 		for await (const s of suggestions) yield s;

package/dist/primitives.js

@@ -237,7 +237,7 @@ function* getSuggestionsWithDependency(valueParser, prefix, dependencyRegistry,
 * Internal sync helper for option suggest functionality.
 * @internal
 */
-function* suggestOptionSync(optionNames$1, valueParser, hidden, context, prefix) {
+function* suggestOptionSync(optionNames$1, valueParser, hidden, description, context, prefix) {
 	if (hidden) return;
 	const equalsIndex = prefix.indexOf("=");
 	if (equalsIndex >= 0) {
@@ -265,7 +265,8 @@ function* suggestOptionSync(optionNames$1, valueParser, hidden, context, prefix)
 				if (prefix === "-" && optionName$1.length !== 2) continue;
 				yield {
 					kind: "literal",
-					text: optionName$1
+					text: optionName$1,
+					...description && { description }
 				};
 			}
 		}
@@ -321,7 +322,7 @@ async function* getSuggestionsWithDependencyAsync(valueParser, prefix, dependenc
 * Internal async helper for option suggest functionality.
 * @internal
 */
-async function* suggestOptionAsync(optionNames$1, valueParser, hidden, context, prefix) {
+async function* suggestOptionAsync(optionNames$1, valueParser, hidden, description, context, prefix) {
 	if (hidden) return;
 	const equalsIndex = prefix.indexOf("=");
 	if (equalsIndex >= 0) {
@@ -349,7 +350,8 @@ async function* suggestOptionAsync(optionNames$1, valueParser, hidden, context,
 				if (prefix === "-" && optionName$1.length !== 2) continue;
 				yield {
 					kind: "literal",
-					text: optionName$1
+					text: optionName$1,
+					...description && { description }
 				};
 			}
 		}
@@ -615,8 +617,8 @@ function option(...args) {
 			return dispatchByMode(mode, completeSync, completeAsync);
 		},
 		suggest(context, prefix) {
-			if (isAsync) return suggestOptionAsync(optionNames$1, valueParser, isSuggestionHidden(options.hidden), context, prefix);
-			return suggestOptionSync(optionNames$1, valueParser, isSuggestionHidden(options.hidden), context, prefix);
+			if (isAsync) return suggestOptionAsync(optionNames$1, valueParser, isSuggestionHidden(options.hidden), options.description, context, prefix);
+			return suggestOptionSync(optionNames$1, valueParser, isSuggestionHidden(options.hidden), options.description, context, prefix);
 		},
 		getDocFragments(_state, defaultValue) {
 			if (isDocHidden(options.hidden)) return {
@@ -893,7 +895,8 @@ function flag(...args) {
 					if (prefix === "-" && optionName$1.length !== 2) continue;
 					suggestions.push({
 						kind: "literal",
-						text: optionName$1
+						text: optionName$1,
+						...options.description && { description: options.description }
 					});
 				}
 			}
@@ -1157,11 +1160,14 @@ function* suggestCommandSync(context, prefix, name, parser, options) {
 	if (isSuggestionHidden(options.hidden)) return;
 	const state = normalizeCommandState(context.state);
 	if (state === void 0) {
-		if (name.startsWith(prefix)) yield {
-			kind: "literal",
-			text: name,
-			...options.description && { description: options.description }
-		};
+		if (name.startsWith(prefix)) {
+			const description = options.brief ?? options.description;
+			yield {
+				kind: "literal",
+				text: name,
+				...description && { description }
+			};
+		}
 	} else if (state[0] === "matched") yield* parser.suggest(withChildContext(context, name, getCommandChildState(context.state, parser.initialState, parser), parser.usage), prefix);
 	else if (state[0] === "parsing") yield* parser.suggest(withChildContext(context, name, getCommandChildState(context.state, state[1], parser), parser.usage), prefix);
 }
@@ -1169,11 +1175,14 @@ async function* suggestCommandAsync(context, prefix, name, parser, options) {
 	if (isSuggestionHidden(options.hidden)) return;
 	const state = normalizeCommandState(context.state);
 	if (state === void 0) {
-		if (name.startsWith(prefix)) yield {
-			kind: "literal",
-			text: name,
-			...options.description && { description: options.description }
-		};
+		if (name.startsWith(prefix)) {
+			const description = options.brief ?? options.description;
+			yield {
+				kind: "literal",
+				text: name,
+				...description && { description }
+			};
+		}
 	} else if (state[0] === "matched") {
 		const suggestions = parser.suggest(withChildContext(context, name, getCommandChildState(context.state, parser.initialState, parser), parser.usage), prefix);
 		for await (const s of suggestions) yield s;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/core",
-  "version": "1.0.2",
+  "version": "1.0.5",
   "description": "Type-safe combinatorial command-line interface parser",
   "keywords": [
     "CLI",