@optique/core 0.10.2 → 0.10.4-dev.408

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

@@ -625,8 +625,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

@@ -625,8 +625,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,124 @@ 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",
-					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) yield {
+							text: "\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
+							};
+						}
+					}
+				} 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: 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: hyperlink,
+					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,124 @@ 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",
-					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) yield {
+							text: "\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
+							};
+						}
+					}
+				} 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: 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: hyperlink,
+					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/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
@@ -881,11 +882,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,
@@ -898,10 +898,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
@@ -881,11 +882,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,
@@ -898,10 +898,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": "0.10.2",
+  "version": "0.10.4-dev.408+296f11c0",
   "description": "Type-safe combinatorial command-line interface parser",
   "keywords": [
     "CLI",