@optique/core 0.9.7 → 0.9.9

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);
@@ -1300,6 +1263,9 @@ function merge(...args) {
 			}();
 		},
 		getDocFragments(state, _defaultValue) {
+			let brief;
+			let description;
+			let footer;
 			const fragments = parsers.flatMap((p, i) => {
 				let parserState;
 				if (p.initialState === void 0) {
@@ -1313,7 +1279,11 @@ function merge(...args) {
 					kind: "available",
 					state: state.state
 				};
-				return p.getDocFragments(parserState, void 0).fragments;
+				const docFragments = p.getDocFragments(parserState, void 0);
+				brief ??= docFragments.brief;
+				description ??= docFragments.description;
+				footer ??= docFragments.footer;
+				return docFragments.fragments;
 			});
 			const entries = fragments.filter((f) => f.type === "entry");
 			const sections = [];
@@ -1328,18 +1298,28 @@ function merge(...args) {
 					entries
 				};
 				sections.push(labeledSection);
-				return { fragments: sections.map((s) => ({
+				return {
+					brief,
+					description,
+					footer,
+					fragments: sections.map((s) => ({
+						...s,
+						type: "section"
+					}))
+				};
+			}
+			return {
+				brief,
+				description,
+				footer,
+				fragments: [...sections.map((s) => ({
 					...s,
 					type: "section"
-				})) };
-			}
-			return { fragments: [...sections.map((s) => ({
-				...s,
-				type: "section"
-			})), {
-				type: "section",
-				entries
-			}] };
+				})), {
+					type: "section",
+					entries
+				}]
+			};
 		}
 	};
 }
@@ -1630,18 +1610,32 @@ 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);
 			else if (fragment.type === "section") if (fragment.title) titledSections.push(fragment);
 			else allEntries.push(...fragment.entries);
-			const labeledSection = {
+			const initialFragments = parser.getDocFragments({
+				kind: "available",
+				state: parser.initialState
+			}, void 0);
+			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();
@@ -1300,6 +1263,9 @@ function merge(...args) {
 			}();
 		},
 		getDocFragments(state, _defaultValue) {
+			let brief;
+			let description;
+			let footer;
 			const fragments = parsers.flatMap((p, i) => {
 				let parserState;
 				if (p.initialState === void 0) {
@@ -1313,7 +1279,11 @@ function merge(...args) {
 					kind: "available",
 					state: state.state
 				};
-				return p.getDocFragments(parserState, void 0).fragments;
+				const docFragments = p.getDocFragments(parserState, void 0);
+				brief ??= docFragments.brief;
+				description ??= docFragments.description;
+				footer ??= docFragments.footer;
+				return docFragments.fragments;
 			});
 			const entries = fragments.filter((f) => f.type === "entry");
 			const sections = [];
@@ -1328,18 +1298,28 @@ function merge(...args) {
 					entries
 				};
 				sections.push(labeledSection);
-				return { fragments: sections.map((s) => ({
+				return {
+					brief,
+					description,
+					footer,
+					fragments: sections.map((s) => ({
+						...s,
+						type: "section"
+					}))
+				};
+			}
+			return {
+				brief,
+				description,
+				footer,
+				fragments: [...sections.map((s) => ({
 					...s,
 					type: "section"
-				})) };
-			}
-			return { fragments: [...sections.map((s) => ({
-				...s,
-				type: "section"
-			})), {
-				type: "section",
-				entries
-			}] };
+				})), {
+					type: "section",
+					entries
+				}]
+			};
 		}
 	};
 }
@@ -1630,18 +1610,32 @@ 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);
 			else if (fragment.type === "section") if (fragment.title) titledSections.push(fragment);
 			else allEntries.push(...fragment.entries);
-			const labeledSection = {
+			const initialFragments = parser.getDocFragments({
+				kind: "available",
+				state: parser.initialState
+			}, void 0);
+			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/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.7",
+  "version": "0.9.9",
   "description": "Type-safe combinatorial command-line interface parser",
   "keywords": [
     "CLI",