@optique/core 0.9.8 → 0.9.10

package/dist/constructs.cjs

@@ -1,50 +1,13 @@
 const require_message = require('./message.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);
@@ -1647,7 +1610,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);
@@ -1657,15 +1620,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

@@ -1,46 +1,9 @@
 import { message, optionName, text, values } from "./message.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();
@@ -1647,7 +1610,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);
@@ -1657,15 +1620,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

@@ -577,8 +577,8 @@ function runParser(parser, programName, args, options = {}) {
 						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,
 							footer: shouldOverride ? footer ?? doc.footer : doc.footer ?? footer
 						};
 						stdout(require_doc.formatDocPage(programName, augmentedDoc, {

package/dist/facade.js

@@ -577,8 +577,8 @@ function runParser(parser, programName, args, options = {}) {
 						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,
 							footer: shouldOverride ? footer ?? doc.footer : doc.footer ?? footer
 						};
 						stdout(formatDocPage(programName, augmentedDoc, {

package/dist/parser.cjs

@@ -308,11 +308,11 @@ function getDocPageSyncImpl(parser, args) {
 		state: parser.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);
 }
 /**
@@ -325,11 +325,11 @@ async function getDocPageAsyncImpl(parser, args) {
 		state: parser.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

@@ -308,11 +308,11 @@ function getDocPageSyncImpl(parser, args) {
 		state: parser.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);
 }
 /**
@@ -325,11 +325,11 @@ async function getDocPageAsyncImpl(parser, args) {
 		state: parser.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

@@ -1,6 +1,7 @@
 const require_message = require('./message.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
@@ -752,11 +753,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,
@@ -769,10 +769,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,6 +1,7 @@
-import { message, metavar, optionName, optionNames } from "./message.js";
-import { extractCommandNames, extractOptionNames } from "./usage.js";
-import { DEFAULT_FIND_SIMILAR_OPTIONS, createErrorWithSuggestions, findSimilar } from "./suggestion.js";
+import { message, metavar, optionName, optionNames, text } from "./message.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
@@ -752,11 +753,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,
@@ -769,10 +769,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.9.8",
+  "version": "0.9.10",
   "description": "Type-safe combinatorial command-line interface parser",
   "keywords": [
     "CLI",