@optique/core 1.0.0-dev.401 → 1.0.0-dev.416

package/README.md

@@ -1,9 +1,6 @@
 @optique/core
 =============
 
-> [!WARNING]
-> The API is stabilizing, but may change before the 1.0 release.
-
 The core package of Optique which provides the shared types and parser
 combinators. It is designed to be used in universal JavaScript runtimes,
 including Node.js, Deno, Bun, edge functions, and web browsers—although

package/dist/constructs.cjs

@@ -3,50 +3,13 @@ const require_dependency = require('./dependency.cjs');
 const require_mode_dispatch = require('./mode-dispatch.cjs');
 const require_usage = require('./usage.cjs');
 const require_suggestion = require('./suggestion.cjs');
+const require_usage_internals = require('./usage-internals.cjs');
 
 //#region src/constructs.ts
-/**
-* Collects option names and command names that are valid at the current
-* parse position by walking the usage tree.  Only "leading" candidates
-* (those reachable before a required positional argument) are collected.
-*/
-function collectLeadingCandidates(terms, optionNames, commandNames) {
-	if (!terms || !Array.isArray(terms)) return true;
-	for (const term of terms) {
-		if (term.type === "option") {
-			for (const name of term.names) optionNames.add(name);
-			return false;
-		}
-		if (term.type === "command") {
-			commandNames.add(term.name);
-			return false;
-		}
-		if (term.type === "argument") return false;
-		if (term.type === "optional") {
-			collectLeadingCandidates(term.terms, optionNames, commandNames);
-			continue;
-		}
-		if (term.type === "multiple") {
-			collectLeadingCandidates(term.terms, optionNames, commandNames);
-			if (term.min === 0) continue;
-			return false;
-		}
-		if (term.type === "exclusive") {
-			let allAlternativesSkippable = true;
-			for (const exclusiveUsage of term.terms) {
-				const alternativeSkippable = collectLeadingCandidates(exclusiveUsage, optionNames, commandNames);
-				allAlternativesSkippable = allAlternativesSkippable && alternativeSkippable;
-			}
-			if (allAlternativesSkippable) continue;
-			return false;
-		}
-	}
-	return true;
-}
 function createUnexpectedInputErrorWithScopedSuggestions(baseError, invalidInput, parsers, customFormatter) {
 	const options = /* @__PURE__ */ new Set();
 	const commands = /* @__PURE__ */ new Set();
-	for (const parser of parsers) collectLeadingCandidates(parser.usage, options, commands);
+	for (const parser of parsers) require_usage_internals.collectLeadingCandidates(parser.usage, options, commands);
 	const candidates = new Set([...options, ...commands]);
 	const suggestions = require_suggestion.findSimilar(invalidInput, candidates, require_suggestion.DEFAULT_FIND_SIMILAR_OPTIONS);
 	const suggestionMsg = customFormatter ? customFormatter(suggestions) : require_suggestion.createSuggestionMessage(suggestions);
@@ -2006,7 +1969,7 @@ function group(label, parser) {
 		complete: (state) => parser.complete(state),
 		suggest: (context, prefix) => parser.suggest(context, prefix),
 		getDocFragments: (state, defaultValue) => {
-			const { description, fragments } = parser.getDocFragments(state, defaultValue);
+			const { brief, description, footer, fragments } = parser.getDocFragments(state, defaultValue);
 			const allEntries = [];
 			const titledSections = [];
 			for (const fragment of fragments) if (fragment.type === "entry") allEntries.push(fragment);
@@ -2016,15 +1979,22 @@ function group(label, parser) {
 				kind: "available",
 				state: parser.initialState
 			}, void 0);
-			const initialHasCommands = initialFragments.fragments.some((f) => f.type === "entry" && f.term.type === "command" || f.type === "section" && f.entries.some((e) => e.term.type === "command"));
-			const currentHasCommands = allEntries.some((e) => e.term.type === "command");
-			const applyLabel = !initialHasCommands || currentHasCommands;
+			const initialCommandNames = /* @__PURE__ */ new Set();
+			for (const f of initialFragments.fragments) if (f.type === "entry" && f.term.type === "command") initialCommandNames.add(f.term.name);
+			else if (f.type === "section") {
+				for (const e of f.entries) if (e.term.type === "command") initialCommandNames.add(e.term.name);
+			}
+			const initialHasCommands = initialCommandNames.size > 0;
+			const currentCommandsAreGroupOwn = allEntries.some((e) => e.term.type === "command" && initialCommandNames.has(e.term.name));
+			const applyLabel = !initialHasCommands || currentCommandsAreGroupOwn;
 			const labeledSection = applyLabel ? {
 				title: label,
 				entries: allEntries
 			} : { entries: allEntries };
 			return {
+				brief,
 				description,
+				footer,
 				fragments: [...titledSections.map((s) => ({
 					...s,
 					type: "section"

package/dist/constructs.js

@@ -3,46 +3,9 @@ import { DependencyRegistry, dependencyId, isDeferredParseState, isDependencySou
 import { dispatchByMode, dispatchIterableByMode } from "./mode-dispatch.js";
 import { extractArgumentMetavars, extractCommandNames, extractOptionNames } from "./usage.js";
 import { DEFAULT_FIND_SIMILAR_OPTIONS, createErrorWithSuggestions, createSuggestionMessage, deduplicateSuggestions, findSimilar } from "./suggestion.js";
+import { collectLeadingCandidates } from "./usage-internals.js";
 
 //#region src/constructs.ts
-/**
-* Collects option names and command names that are valid at the current
-* parse position by walking the usage tree.  Only "leading" candidates
-* (those reachable before a required positional argument) are collected.
-*/
-function collectLeadingCandidates(terms, optionNames, commandNames) {
-	if (!terms || !Array.isArray(terms)) return true;
-	for (const term of terms) {
-		if (term.type === "option") {
-			for (const name of term.names) optionNames.add(name);
-			return false;
-		}
-		if (term.type === "command") {
-			commandNames.add(term.name);
-			return false;
-		}
-		if (term.type === "argument") return false;
-		if (term.type === "optional") {
-			collectLeadingCandidates(term.terms, optionNames, commandNames);
-			continue;
-		}
-		if (term.type === "multiple") {
-			collectLeadingCandidates(term.terms, optionNames, commandNames);
-			if (term.min === 0) continue;
-			return false;
-		}
-		if (term.type === "exclusive") {
-			let allAlternativesSkippable = true;
-			for (const exclusiveUsage of term.terms) {
-				const alternativeSkippable = collectLeadingCandidates(exclusiveUsage, optionNames, commandNames);
-				allAlternativesSkippable = allAlternativesSkippable && alternativeSkippable;
-			}
-			if (allAlternativesSkippable) continue;
-			return false;
-		}
-	}
-	return true;
-}
 function createUnexpectedInputErrorWithScopedSuggestions(baseError, invalidInput, parsers, customFormatter) {
 	const options = /* @__PURE__ */ new Set();
 	const commands = /* @__PURE__ */ new Set();
@@ -2006,7 +1969,7 @@ function group(label, parser) {
 		complete: (state) => parser.complete(state),
 		suggest: (context, prefix) => parser.suggest(context, prefix),
 		getDocFragments: (state, defaultValue) => {
-			const { description, fragments } = parser.getDocFragments(state, defaultValue);
+			const { brief, description, footer, fragments } = parser.getDocFragments(state, defaultValue);
 			const allEntries = [];
 			const titledSections = [];
 			for (const fragment of fragments) if (fragment.type === "entry") allEntries.push(fragment);
@@ -2016,15 +1979,22 @@ function group(label, parser) {
 				kind: "available",
 				state: parser.initialState
 			}, void 0);
-			const initialHasCommands = initialFragments.fragments.some((f) => f.type === "entry" && f.term.type === "command" || f.type === "section" && f.entries.some((e) => e.term.type === "command"));
-			const currentHasCommands = allEntries.some((e) => e.term.type === "command");
-			const applyLabel = !initialHasCommands || currentHasCommands;
+			const initialCommandNames = /* @__PURE__ */ new Set();
+			for (const f of initialFragments.fragments) if (f.type === "entry" && f.term.type === "command") initialCommandNames.add(f.term.name);
+			else if (f.type === "section") {
+				for (const e of f.entries) if (e.term.type === "command") initialCommandNames.add(e.term.name);
+			}
+			const initialHasCommands = initialCommandNames.size > 0;
+			const currentCommandsAreGroupOwn = allEntries.some((e) => e.term.type === "command" && initialCommandNames.has(e.term.name));
+			const applyLabel = !initialHasCommands || currentCommandsAreGroupOwn;
 			const labeledSection = applyLabel ? {
 				title: label,
 				entries: allEntries
 			} : { entries: allEntries };
 			return {
+				brief,
 				description,
+				footer,
 				fragments: [...titledSections.map((s) => ({
 					...s,
 					type: "section"

package/dist/facade.cjs

@@ -626,8 +626,8 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 						const shouldOverride = !isMetaCommandHelp && !isSubcommandHelp;
 						const augmentedDoc = {
 							...doc,
-							brief: shouldOverride ? brief ?? doc.brief : doc.brief ?? brief,
-							description: shouldOverride ? description ?? doc.description : doc.description ?? description,
+							brief: shouldOverride ? brief ?? doc.brief : doc.brief,
+							description: shouldOverride ? description ?? doc.description : doc.description,
 							examples: isTopLevel && !isMetaCommandHelp ? examples ?? doc.examples : void 0,
 							author: isTopLevel && !isMetaCommandHelp ? author ?? doc.author : void 0,
 							bugs: isTopLevel && !isMetaCommandHelp ? bugs ?? doc.bugs : void 0,

package/dist/facade.js

@@ -626,8 +626,8 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 						const shouldOverride = !isMetaCommandHelp && !isSubcommandHelp;
 						const augmentedDoc = {
 							...doc,
-							brief: shouldOverride ? brief ?? doc.brief : doc.brief ?? brief,
-							description: shouldOverride ? description ?? doc.description : doc.description ?? description,
+							brief: shouldOverride ? brief ?? doc.brief : doc.brief,
+							description: shouldOverride ? description ?? doc.description : doc.description,
 							examples: isTopLevel && !isMetaCommandHelp ? examples ?? doc.examples : void 0,
 							author: isTopLevel && !isMetaCommandHelp ? author ?? doc.author : void 0,
 							bugs: isTopLevel && !isMetaCommandHelp ? bugs ?? doc.bugs : void 0,

package/dist/message.cjs

@@ -253,115 +253,127 @@ function formatMessage(msg, options = {}) {
 	const resetSequence = `\x1b[0m${resetSuffix}`;
 	function* stream() {
 		const wordPattern = /\s*\S+\s*/g;
-		for (const term of msg) if (term.type === "text") if (term.text.includes("\n\n")) {
-			const paragraphs = term.text.split(/\n\n+/);
-			for (let paragraphIndex = 0; paragraphIndex < paragraphs.length; paragraphIndex++) {
-				if (paragraphIndex > 0) yield {
-					text: "\n\n",
-					width: -1
-				};
-				const paragraph = paragraphs[paragraphIndex].replace(/\n/g, " ");
-				wordPattern.lastIndex = 0;
-				while (true) {
-					const match = wordPattern.exec(paragraph);
-					if (match == null) break;
-					yield {
-						text: match[0],
-						width: match[0].length
+		let prevWasLineBreak = false;
+		for (const term of msg) {
+			const isAfterLineBreak = prevWasLineBreak;
+			prevWasLineBreak = false;
+			if (term.type === "text") {
+				const rawText = isAfterLineBreak ? term.text.replace(/^\n(?!\n)/, "") : term.text;
+				if (rawText.includes("\n\n")) {
+					const paragraphs = rawText.split(/\n\n+/);
+					for (let paragraphIndex = 0; paragraphIndex < paragraphs.length; paragraphIndex++) {
+						if (paragraphIndex > 0) {
+							const breakText = isAfterLineBreak && paragraphIndex === 1 ? "\n" : "\n\n";
+							yield {
+								text: breakText,
+								width: -1
+							};
+						}
+						const paragraph = paragraphs[paragraphIndex].replace(/\n/g, " ");
+						wordPattern.lastIndex = 0;
+						while (true) {
+							const match = wordPattern.exec(paragraph);
+							if (match == null) break;
+							yield {
+								text: match[0],
+								width: match[0].length
+							};
+						}
+					}
+				} else {
+					const normalizedText = rawText.replace(/\n/g, " ");
+					if (normalizedText.trim() === "" && normalizedText.length > 0) yield {
+						text: " ",
+						width: 1
 					};
+					else {
+						wordPattern.lastIndex = 0;
+						while (true) {
+							const match = wordPattern.exec(normalizedText);
+							if (match == null) break;
+							yield {
+								text: match[0],
+								width: match[0].length
+							};
+						}
+					}
 				}
-			}
-		} else {
-			const normalizedText = term.text.replace(/\n/g, " ");
-			if (normalizedText.trim() === "" && normalizedText.length > 0) yield {
-				text: " ",
-				width: 1
-			};
-			else {
-				wordPattern.lastIndex = 0;
-				while (true) {
-					const match = wordPattern.exec(normalizedText);
-					if (match == null) break;
+			} else if (term.type === "optionName") {
+				const name = useQuotes ? `\`${term.optionName}\`` : term.optionName;
+				yield {
+					text: useColors ? `\x1b[3m${name}${resetSequence}` : name,
+					width: name.length
+				};
+			} else if (term.type === "optionNames") {
+				const names = term.optionNames.map((name) => useQuotes ? `\`${name}\`` : name);
+				let i = 0;
+				for (const name of names) {
+					if (i > 0) yield {
+						text: "/",
+						width: 1
+					};
 					yield {
-						text: match[0],
-						width: match[0].length
+						text: useColors ? `\x1b[3m${name}${resetSequence}` : name,
+						width: name.length
 					};
+					i++;
 				}
-			}
-		}
-		else if (term.type === "optionName") {
-			const name = useQuotes ? `\`${term.optionName}\`` : term.optionName;
-			yield {
-				text: useColors ? `\x1b[3m${name}${resetSequence}` : name,
-				width: name.length
-			};
-		} else if (term.type === "optionNames") {
-			const names = term.optionNames.map((name) => useQuotes ? `\`${name}\`` : name);
-			let i = 0;
-			for (const name of names) {
+			} else if (term.type === "metavar") {
+				const metavar$1 = useQuotes ? `\`${term.metavar}\`` : term.metavar;
+				yield {
+					text: useColors ? `\x1b[1m${metavar$1}${resetSequence}` : metavar$1,
+					width: metavar$1.length
+				};
+			} else if (term.type === "value") {
+				const value$1 = useQuotes ? `${JSON.stringify(term.value)}` : term.value;
+				yield {
+					text: useColors ? `\x1b[32m${value$1}${resetSequence}` : value$1,
+					width: value$1.length
+				};
+			} else if (term.type === "values") for (let i = 0; i < term.values.length; i++) {
 				if (i > 0) yield {
-					text: "/",
+					text: " ",
 					width: 1
 				};
+				const value$1 = useQuotes ? JSON.stringify(term.values[i]) : term.values[i];
 				yield {
-					text: useColors ? `\x1b[3m${name}${resetSequence}` : name,
-					width: name.length
+					text: useColors ? i <= 0 ? `\x1b[32m${value$1}` : i + 1 >= term.values.length ? `${value$1}${resetSequence}` : value$1 : value$1,
+					width: value$1.length
 				};
-				i++;
 			}
-		} else if (term.type === "metavar") {
-			const metavar$1 = useQuotes ? `\`${term.metavar}\`` : term.metavar;
-			yield {
-				text: useColors ? `\x1b[1m${metavar$1}${resetSequence}` : metavar$1,
-				width: metavar$1.length
-			};
-		} else if (term.type === "value") {
-			const value$1 = useQuotes ? `${JSON.stringify(term.value)}` : term.value;
-			yield {
-				text: useColors ? `\x1b[32m${value$1}${resetSequence}` : value$1,
-				width: value$1.length
-			};
-		} else if (term.type === "values") for (let i = 0; i < term.values.length; i++) {
-			if (i > 0) yield {
-				text: " ",
-				width: 1
-			};
-			const value$1 = useQuotes ? JSON.stringify(term.values[i]) : term.values[i];
-			yield {
-				text: useColors ? i <= 0 ? `\x1b[32m${value$1}` : i + 1 >= term.values.length ? `${value$1}${resetSequence}` : value$1 : value$1,
-				width: value$1.length
-			};
-		}
-		else if (term.type === "envVar") {
-			const envVar$1 = useQuotes ? `\`${term.envVar}\`` : term.envVar;
-			yield {
-				text: useColors ? `\x1b[1;4m${envVar$1}${resetSequence}` : envVar$1,
-				width: envVar$1.length
-			};
-		} else if (term.type === "commandLine") {
-			const cmd = useQuotes ? `\`${term.commandLine}\`` : term.commandLine;
-			yield {
-				text: useColors ? `\x1b[36m${cmd}${resetSequence}` : cmd,
-				width: cmd.length
-			};
-		} else if (term.type === "lineBreak") yield {
-			text: "\n",
-			width: -1
-		};
-		else if (term.type === "url") {
-			const urlString = term.url.href;
-			const displayText = useQuotes ? `<${urlString}>` : urlString;
-			if (useColors) {
-				const hyperlink = `\x1b]8;;${urlString}\x1b\\${displayText}\x1b]8;;\x1b\\${resetSuffix}`;
+			else if (term.type === "envVar") {
+				const envVar$1 = useQuotes ? `\`${term.envVar}\`` : term.envVar;
 				yield {
-					text: hyperlink,
+					text: useColors ? `\x1b[1;4m${envVar$1}${resetSequence}` : envVar$1,
+					width: envVar$1.length
+				};
+			} else if (term.type === "commandLine") {
+				const cmd = useQuotes ? `\`${term.commandLine}\`` : term.commandLine;
+				yield {
+					text: useColors ? `\x1b[36m${cmd}${resetSequence}` : cmd,
+					width: cmd.length
+				};
+			} else if (term.type === "lineBreak") {
+				yield {
+					text: "\n",
+					width: -1
+				};
+				prevWasLineBreak = true;
+			} else if (term.type === "url") {
+				const urlString = term.url.href;
+				const displayText = useQuotes ? `<${urlString}>` : urlString;
+				if (useColors) {
+					const hyperlink = `\x1b]8;;${urlString}\x1b\\${displayText}\x1b]8;;\x1b\\${resetSuffix}`;
+					yield {
+						text: hyperlink,
+						width: displayText.length
+					};
+				} else yield {
+					text: displayText,
 					width: displayText.length
 				};
-			} else yield {
-				text: displayText,
-				width: displayText.length
-			};
-		} else throw new TypeError(`Invalid MessageTerm type: ${term["type"]}.`);
+			} else throw new TypeError(`Invalid MessageTerm type: ${term["type"]}.`);
+		}
 	}
 	let output = "";
 	let totalWidth = 0;

package/dist/message.js

@@ -252,115 +252,127 @@ function formatMessage(msg, options = {}) {
 	const resetSequence = `\x1b[0m${resetSuffix}`;
 	function* stream() {
 		const wordPattern = /\s*\S+\s*/g;
-		for (const term of msg) if (term.type === "text") if (term.text.includes("\n\n")) {
-			const paragraphs = term.text.split(/\n\n+/);
-			for (let paragraphIndex = 0; paragraphIndex < paragraphs.length; paragraphIndex++) {
-				if (paragraphIndex > 0) yield {
-					text: "\n\n",
-					width: -1
-				};
-				const paragraph = paragraphs[paragraphIndex].replace(/\n/g, " ");
-				wordPattern.lastIndex = 0;
-				while (true) {
-					const match = wordPattern.exec(paragraph);
-					if (match == null) break;
-					yield {
-						text: match[0],
-						width: match[0].length
+		let prevWasLineBreak = false;
+		for (const term of msg) {
+			const isAfterLineBreak = prevWasLineBreak;
+			prevWasLineBreak = false;
+			if (term.type === "text") {
+				const rawText = isAfterLineBreak ? term.text.replace(/^\n(?!\n)/, "") : term.text;
+				if (rawText.includes("\n\n")) {
+					const paragraphs = rawText.split(/\n\n+/);
+					for (let paragraphIndex = 0; paragraphIndex < paragraphs.length; paragraphIndex++) {
+						if (paragraphIndex > 0) {
+							const breakText = isAfterLineBreak && paragraphIndex === 1 ? "\n" : "\n\n";
+							yield {
+								text: breakText,
+								width: -1
+							};
+						}
+						const paragraph = paragraphs[paragraphIndex].replace(/\n/g, " ");
+						wordPattern.lastIndex = 0;
+						while (true) {
+							const match = wordPattern.exec(paragraph);
+							if (match == null) break;
+							yield {
+								text: match[0],
+								width: match[0].length
+							};
+						}
+					}
+				} else {
+					const normalizedText = rawText.replace(/\n/g, " ");
+					if (normalizedText.trim() === "" && normalizedText.length > 0) yield {
+						text: " ",
+						width: 1
 					};
+					else {
+						wordPattern.lastIndex = 0;
+						while (true) {
+							const match = wordPattern.exec(normalizedText);
+							if (match == null) break;
+							yield {
+								text: match[0],
+								width: match[0].length
+							};
+						}
+					}
 				}
-			}
-		} else {
-			const normalizedText = term.text.replace(/\n/g, " ");
-			if (normalizedText.trim() === "" && normalizedText.length > 0) yield {
-				text: " ",
-				width: 1
-			};
-			else {
-				wordPattern.lastIndex = 0;
-				while (true) {
-					const match = wordPattern.exec(normalizedText);
-					if (match == null) break;
+			} else if (term.type === "optionName") {
+				const name = useQuotes ? `\`${term.optionName}\`` : term.optionName;
+				yield {
+					text: useColors ? `\x1b[3m${name}${resetSequence}` : name,
+					width: name.length
+				};
+			} else if (term.type === "optionNames") {
+				const names = term.optionNames.map((name) => useQuotes ? `\`${name}\`` : name);
+				let i = 0;
+				for (const name of names) {
+					if (i > 0) yield {
+						text: "/",
+						width: 1
+					};
 					yield {
-						text: match[0],
-						width: match[0].length
+						text: useColors ? `\x1b[3m${name}${resetSequence}` : name,
+						width: name.length
 					};
+					i++;
 				}
-			}
-		}
-		else if (term.type === "optionName") {
-			const name = useQuotes ? `\`${term.optionName}\`` : term.optionName;
-			yield {
-				text: useColors ? `\x1b[3m${name}${resetSequence}` : name,
-				width: name.length
-			};
-		} else if (term.type === "optionNames") {
-			const names = term.optionNames.map((name) => useQuotes ? `\`${name}\`` : name);
-			let i = 0;
-			for (const name of names) {
+			} else if (term.type === "metavar") {
+				const metavar$1 = useQuotes ? `\`${term.metavar}\`` : term.metavar;
+				yield {
+					text: useColors ? `\x1b[1m${metavar$1}${resetSequence}` : metavar$1,
+					width: metavar$1.length
+				};
+			} else if (term.type === "value") {
+				const value$1 = useQuotes ? `${JSON.stringify(term.value)}` : term.value;
+				yield {
+					text: useColors ? `\x1b[32m${value$1}${resetSequence}` : value$1,
+					width: value$1.length
+				};
+			} else if (term.type === "values") for (let i = 0; i < term.values.length; i++) {
 				if (i > 0) yield {
-					text: "/",
+					text: " ",
 					width: 1
 				};
+				const value$1 = useQuotes ? JSON.stringify(term.values[i]) : term.values[i];
 				yield {
-					text: useColors ? `\x1b[3m${name}${resetSequence}` : name,
-					width: name.length
+					text: useColors ? i <= 0 ? `\x1b[32m${value$1}` : i + 1 >= term.values.length ? `${value$1}${resetSequence}` : value$1 : value$1,
+					width: value$1.length
 				};
-				i++;
 			}
-		} else if (term.type === "metavar") {
-			const metavar$1 = useQuotes ? `\`${term.metavar}\`` : term.metavar;
-			yield {
-				text: useColors ? `\x1b[1m${metavar$1}${resetSequence}` : metavar$1,
-				width: metavar$1.length
-			};
-		} else if (term.type === "value") {
-			const value$1 = useQuotes ? `${JSON.stringify(term.value)}` : term.value;
-			yield {
-				text: useColors ? `\x1b[32m${value$1}${resetSequence}` : value$1,
-				width: value$1.length
-			};
-		} else if (term.type === "values") for (let i = 0; i < term.values.length; i++) {
-			if (i > 0) yield {
-				text: " ",
-				width: 1
-			};
-			const value$1 = useQuotes ? JSON.stringify(term.values[i]) : term.values[i];
-			yield {
-				text: useColors ? i <= 0 ? `\x1b[32m${value$1}` : i + 1 >= term.values.length ? `${value$1}${resetSequence}` : value$1 : value$1,
-				width: value$1.length
-			};
-		}
-		else if (term.type === "envVar") {
-			const envVar$1 = useQuotes ? `\`${term.envVar}\`` : term.envVar;
-			yield {
-				text: useColors ? `\x1b[1;4m${envVar$1}${resetSequence}` : envVar$1,
-				width: envVar$1.length
-			};
-		} else if (term.type === "commandLine") {
-			const cmd = useQuotes ? `\`${term.commandLine}\`` : term.commandLine;
-			yield {
-				text: useColors ? `\x1b[36m${cmd}${resetSequence}` : cmd,
-				width: cmd.length
-			};
-		} else if (term.type === "lineBreak") yield {
-			text: "\n",
-			width: -1
-		};
-		else if (term.type === "url") {
-			const urlString = term.url.href;
-			const displayText = useQuotes ? `<${urlString}>` : urlString;
-			if (useColors) {
-				const hyperlink = `\x1b]8;;${urlString}\x1b\\${displayText}\x1b]8;;\x1b\\${resetSuffix}`;
+			else if (term.type === "envVar") {
+				const envVar$1 = useQuotes ? `\`${term.envVar}\`` : term.envVar;
 				yield {
-					text: hyperlink,
+					text: useColors ? `\x1b[1;4m${envVar$1}${resetSequence}` : envVar$1,
+					width: envVar$1.length
+				};
+			} else if (term.type === "commandLine") {
+				const cmd = useQuotes ? `\`${term.commandLine}\`` : term.commandLine;
+				yield {
+					text: useColors ? `\x1b[36m${cmd}${resetSequence}` : cmd,
+					width: cmd.length
+				};
+			} else if (term.type === "lineBreak") {
+				yield {
+					text: "\n",
+					width: -1
+				};
+				prevWasLineBreak = true;
+			} else if (term.type === "url") {
+				const urlString = term.url.href;
+				const displayText = useQuotes ? `<${urlString}>` : urlString;
+				if (useColors) {
+					const hyperlink = `\x1b]8;;${urlString}\x1b\\${displayText}\x1b]8;;\x1b\\${resetSuffix}`;
+					yield {
+						text: hyperlink,
+						width: displayText.length
+					};
+				} else yield {
+					text: displayText,
 					width: displayText.length
 				};
-			} else yield {
-				text: displayText,
-				width: displayText.length
-			};
-		} else throw new TypeError(`Invalid MessageTerm type: ${term["type"]}.`);
+			} else throw new TypeError(`Invalid MessageTerm type: ${term["type"]}.`);
+		}
 	}
 	let output = "";
 	let totalWidth = 0;

package/dist/parser.cjs

@@ -350,11 +350,11 @@ function getDocPageSyncImpl(parser, args, options) {
 		state: initialState,
 		usage: parser.usage
 	};
-	do {
+	while (context.buffer.length > 0) {
 		const result = parser.parse(context);
 		if (!result.success) break;
 		context = result.next;
-	} while (context.buffer.length > 0);
+	}
 	return buildDocPage(parser, context, args);
 }
 /**
@@ -372,11 +372,11 @@ async function getDocPageAsyncImpl(parser, args, options) {
 		state: initialState,
 		usage: parser.usage
 	};
-	do {
+	while (context.buffer.length > 0) {
 		const result = await parser.parse(context);
 		if (!result.success) break;
 		context = result.next;
-	} while (context.buffer.length > 0);
+	}
 	return buildDocPage(parser, context, args);
 }
 /**

package/dist/parser.js

@@ -350,11 +350,11 @@ function getDocPageSyncImpl(parser, args, options) {
 		state: initialState,
 		usage: parser.usage
 	};
-	do {
+	while (context.buffer.length > 0) {
 		const result = parser.parse(context);
 		if (!result.success) break;
 		context = result.next;
-	} while (context.buffer.length > 0);
+	}
 	return buildDocPage(parser, context, args);
 }
 /**
@@ -372,11 +372,11 @@ async function getDocPageAsyncImpl(parser, args, options) {
 		state: initialState,
 		usage: parser.usage
 	};
-	do {
+	while (context.buffer.length > 0) {
 		const result = await parser.parse(context);
 		if (!result.success) break;
 		context = result.next;
-	} while (context.buffer.length > 0);
+	}
 	return buildDocPage(parser, context, args);
 }
 /**

package/dist/primitives.cjs

@@ -2,6 +2,7 @@ const require_message = require('./message.cjs');
 const require_dependency = require('./dependency.cjs');
 const require_usage = require('./usage.cjs');
 const require_suggestion = require('./suggestion.cjs');
+const require_usage_internals = require('./usage-internals.cjs');
 const require_valueparser = require('./valueparser.cjs');
 
 //#region src/primitives.ts
@@ -929,11 +930,10 @@ function command(name, parser, options = {}) {
 			if (context.state === void 0) {
 				if (context.buffer.length < 1 || context.buffer[0] !== name) {
 					const actual = context.buffer.length > 0 ? context.buffer[0] : null;
+					const leadingCmds = require_usage_internals.extractLeadingCommandNames(context.usage);
+					const suggestions = actual ? require_suggestion.findSimilar(actual, leadingCmds, require_suggestion.DEFAULT_FIND_SIMILAR_OPTIONS) : [];
 					if (options.errors?.notMatched) {
 						const errorMessage = options.errors.notMatched;
-						const candidates = /* @__PURE__ */ new Set();
-						for (const cmdName of require_usage.extractCommandNames(context.usage)) candidates.add(cmdName);
-						const suggestions = actual ? require_suggestion.findSimilar(actual, candidates, require_suggestion.DEFAULT_FIND_SIMILAR_OPTIONS) : [];
 						return {
 							success: false,
 							consumed: 0,
@@ -946,10 +946,15 @@ function command(name, parser, options = {}) {
 						error: require_message.message`Expected command ${require_message.optionName(name)}, but got end of input.`
 					};
 					const baseError = require_message.message`Expected command ${require_message.optionName(name)}, but got ${actual}.`;
+					const suggestionMsg = require_suggestion.createSuggestionMessage(suggestions);
 					return {
 						success: false,
 						consumed: 0,
-						error: require_suggestion.createErrorWithSuggestions(baseError, actual, context.usage, "command")
+						error: suggestionMsg.length > 0 ? [
+							...baseError,
+							require_message.text("\n\n"),
+							...suggestionMsg
+						] : baseError
 					};
 				}
 				return {

package/dist/primitives.js

@@ -1,7 +1,8 @@
-import { message, metavar, optionName, optionNames, valueSet } from "./message.js";
+import { message, metavar, optionName, optionNames, text, valueSet } from "./message.js";
 import { createDeferredParseState, createDependencySourceState, createPendingDependencySourceState, dependencyId, getDefaultValuesFunction, getDependencyIds, isDeferredParseState, isDependencySource, isDependencySourceState, isDerivedValueParser, isPendingDependencySourceState, suggestWithDependency } from "./dependency.js";
-import { extractCommandNames, extractOptionNames } from "./usage.js";
-import { DEFAULT_FIND_SIMILAR_OPTIONS, createErrorWithSuggestions, findSimilar } from "./suggestion.js";
+import { extractOptionNames } from "./usage.js";
+import { DEFAULT_FIND_SIMILAR_OPTIONS, createErrorWithSuggestions, createSuggestionMessage, findSimilar } from "./suggestion.js";
+import { extractLeadingCommandNames } from "./usage-internals.js";
 import { isValueParser } from "./valueparser.js";
 
 //#region src/primitives.ts
@@ -929,11 +930,10 @@ function command(name, parser, options = {}) {
 			if (context.state === void 0) {
 				if (context.buffer.length < 1 || context.buffer[0] !== name) {
 					const actual = context.buffer.length > 0 ? context.buffer[0] : null;
+					const leadingCmds = extractLeadingCommandNames(context.usage);
+					const suggestions = actual ? findSimilar(actual, leadingCmds, DEFAULT_FIND_SIMILAR_OPTIONS) : [];
 					if (options.errors?.notMatched) {
 						const errorMessage = options.errors.notMatched;
-						const candidates = /* @__PURE__ */ new Set();
-						for (const cmdName of extractCommandNames(context.usage)) candidates.add(cmdName);
-						const suggestions = actual ? findSimilar(actual, candidates, DEFAULT_FIND_SIMILAR_OPTIONS) : [];
 						return {
 							success: false,
 							consumed: 0,
@@ -946,10 +946,15 @@ function command(name, parser, options = {}) {
 						error: message`Expected command ${optionName(name)}, but got end of input.`
 					};
 					const baseError = message`Expected command ${optionName(name)}, but got ${actual}.`;
+					const suggestionMsg = createSuggestionMessage(suggestions);
 					return {
 						success: false,
 						consumed: 0,
-						error: createErrorWithSuggestions(baseError, actual, context.usage, "command")
+						error: suggestionMsg.length > 0 ? [
+							...baseError,
+							text("\n\n"),
+							...suggestionMsg
+						] : baseError
 					};
 				}
 				return {

package/dist/usage-internals.cjs

@@ -0,0 +1,73 @@
+
+//#region src/usage-internals.ts
+/**
+* Collects option names and command names that are valid as the *immediate*
+* next token at the current parse position ("leading candidates").
+*
+* Unlike the full-tree extractors in `usage.ts`, this function stops
+* descending into a branch as soon as it hits a required (blocking) term —
+* an option, a command, or a required argument.  Optional and zero-or-more
+* terms are traversed but do not block.
+*
+* @param terms  The usage terms to inspect.
+* @param optionNames  Accumulator for leading option names.
+* @param commandNames  Accumulator for leading command names.
+* @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) {
+	if (!terms || !Array.isArray(terms)) return true;
+	for (const term of terms) {
+		if (term.type === "option") {
+			for (const name of term.names) optionNames.add(name);
+			return false;
+		}
+		if (term.type === "command") {
+			commandNames.add(term.name);
+			return false;
+		}
+		if (term.type === "argument") return false;
+		if (term.type === "optional") {
+			collectLeadingCandidates(term.terms, optionNames, commandNames);
+			continue;
+		}
+		if (term.type === "multiple") {
+			collectLeadingCandidates(term.terms, optionNames, commandNames);
+			if (term.min === 0) continue;
+			return false;
+		}
+		if (term.type === "exclusive") {
+			let allSkippable = true;
+			for (const branch of term.terms) {
+				const branchSkippable = collectLeadingCandidates(branch, optionNames, commandNames);
+				allSkippable = allSkippable && branchSkippable;
+			}
+			if (allSkippable) continue;
+			return false;
+		}
+	}
+	return true;
+}
+/**
+* Returns the set of command names that are valid as the *immediate* next
+* token, derived from the leading candidates of `usage`.
+*
+* This is the command-only projection of {@link collectLeadingCandidates}
+* and is used to generate accurate "Did you mean?" suggestions in
+* `command()` error messages — suggestions are scoped to commands actually
+* reachable at the current parse position rather than all commands anywhere
+* in the usage tree.
+*
+* @param usage  The usage tree to inspect.
+* @returns A `Set` of command names valid as the next input token.
+*/
+function extractLeadingCommandNames(usage) {
+	const options = /* @__PURE__ */ new Set();
+	const commands = /* @__PURE__ */ new Set();
+	collectLeadingCandidates(usage, options, commands);
+	return commands;
+}
+
+//#endregion
+exports.collectLeadingCandidates = collectLeadingCandidates;
+exports.extractLeadingCommandNames = extractLeadingCommandNames;

package/dist/usage-internals.js

@@ -0,0 +1,71 @@
+//#region src/usage-internals.ts
+/**
+* Collects option names and command names that are valid as the *immediate*
+* next token at the current parse position ("leading candidates").
+*
+* Unlike the full-tree extractors in `usage.ts`, this function stops
+* descending into a branch as soon as it hits a required (blocking) term —
+* an option, a command, or a required argument.  Optional and zero-or-more
+* terms are traversed but do not block.
+*
+* @param terms  The usage terms to inspect.
+* @param optionNames  Accumulator for leading option names.
+* @param commandNames  Accumulator for leading command names.
+* @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) {
+	if (!terms || !Array.isArray(terms)) return true;
+	for (const term of terms) {
+		if (term.type === "option") {
+			for (const name of term.names) optionNames.add(name);
+			return false;
+		}
+		if (term.type === "command") {
+			commandNames.add(term.name);
+			return false;
+		}
+		if (term.type === "argument") return false;
+		if (term.type === "optional") {
+			collectLeadingCandidates(term.terms, optionNames, commandNames);
+			continue;
+		}
+		if (term.type === "multiple") {
+			collectLeadingCandidates(term.terms, optionNames, commandNames);
+			if (term.min === 0) continue;
+			return false;
+		}
+		if (term.type === "exclusive") {
+			let allSkippable = true;
+			for (const branch of term.terms) {
+				const branchSkippable = collectLeadingCandidates(branch, optionNames, commandNames);
+				allSkippable = allSkippable && branchSkippable;
+			}
+			if (allSkippable) continue;
+			return false;
+		}
+	}
+	return true;
+}
+/**
+* Returns the set of command names that are valid as the *immediate* next
+* token, derived from the leading candidates of `usage`.
+*
+* This is the command-only projection of {@link collectLeadingCandidates}
+* and is used to generate accurate "Did you mean?" suggestions in
+* `command()` error messages — suggestions are scoped to commands actually
+* reachable at the current parse position rather than all commands anywhere
+* in the usage tree.
+*
+* @param usage  The usage tree to inspect.
+* @returns A `Set` of command names valid as the next input token.
+*/
+function extractLeadingCommandNames(usage) {
+	const options = /* @__PURE__ */ new Set();
+	const commands = /* @__PURE__ */ new Set();
+	collectLeadingCandidates(usage, options, commands);
+	return commands;
+}
+
+//#endregion
+export { collectLeadingCandidates, extractLeadingCommandNames };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/core",
-  "version": "1.0.0-dev.401+5769648d",
+  "version": "1.0.0-dev.416+db8179aa",
   "description": "Type-safe combinatorial command-line interface parser",
   "keywords": [
     "CLI",