@optique/core 1.0.0-dev.400 → 1.0.0-dev.407

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/doc.cjs

@@ -3,6 +3,28 @@ const require_usage = require('./usage.cjs');
 
 //#region src/doc.ts
 /**
+* Classifies a {@link DocSection} by its content type for use in the
+* default smart sort.
+*
+* @returns `0` for command-only sections, `1` for mixed sections, `2` for
+*   option/argument/passthrough-only sections.
+*/
+function classifySection(section) {
+	const hasCommand = section.entries.some((e) => e.term.type === "command");
+	const hasNonCommand = section.entries.some((e) => e.term.type !== "command");
+	if (hasCommand && !hasNonCommand) return 0;
+	if (hasCommand && hasNonCommand) return 1;
+	return 2;
+}
+/**
+* The default section comparator: command-only sections come first, then
+* mixed sections, then option/argument-only sections.  Sections with the
+* same score preserve their original relative order (stable sort).
+*/
+function defaultSectionOrder(a, b) {
+	return classifySection(a) - classifySection(b);
+}
+/**
 * Formats a documentation page into a human-readable string.
 *
 * This function takes a structured {@link DocPage} and converts it into
@@ -64,7 +86,16 @@ function formatDocPage(programName, page, options = {}) {
 		});
 		output += "\n";
 	}
-	const sections = page.sections.toSorted((a, b) => a.title == null && b.title == null ? 0 : a.title == null ? -1 : 1);
+	const comparator = options.sectionOrder ?? defaultSectionOrder;
+	const sections = page.sections.map((s, i) => ({
+		section: s,
+		index: i
+	})).toSorted((a, b) => {
+		const cmp = comparator(a.section, b.section);
+		if (cmp !== 0) return cmp;
+		const titleCmp = (a.section.title == null ? 0 : 1) - (b.section.title == null ? 0 : 1);
+		return titleCmp !== 0 ? titleCmp : a.index - b.index;
+	}).map(({ section }) => section);
 	for (const section of sections) {
 		if (section.entries.length < 1) continue;
 		output += "\n";

package/dist/doc.d.cts

@@ -228,6 +228,28 @@ interface DocPageFormatOptions {
    * ```
    */
   showChoices?: boolean | ShowChoicesOptions;
+  /**
+   * A custom comparator function to control the order of sections in the
+   * help output.  When provided, it is used instead of the default smart
+   * sort (command-only sections first, then mixed, then option/argument-only
+   * sections).  Sections that compare equal (return `0`) preserve their
+   * original relative order (stable sort).
+   *
+   * @param a The first section to compare.
+   * @param b The second section to compare.
+   * @returns A negative number if `a` should appear before `b`, a positive
+   *   number if `a` should appear after `b`, or `0` if they are equal.
+   * @since 1.0.0
+   *
+   * @example
+   * ```typescript
+   * // Sort sections alphabetically by title
+   * {
+   *   sectionOrder: (a, b) => (a.title ?? "").localeCompare(b.title ?? "")
+   * }
+   * ```
+   */
+  sectionOrder?: (a: DocSection, b: DocSection) => number;
 }
 /**
  * Formats a documentation page into a human-readable string.

package/dist/doc.d.ts

@@ -228,6 +228,28 @@ interface DocPageFormatOptions {
    * ```
    */
   showChoices?: boolean | ShowChoicesOptions;
+  /**
+   * A custom comparator function to control the order of sections in the
+   * help output.  When provided, it is used instead of the default smart
+   * sort (command-only sections first, then mixed, then option/argument-only
+   * sections).  Sections that compare equal (return `0`) preserve their
+   * original relative order (stable sort).
+   *
+   * @param a The first section to compare.
+   * @param b The second section to compare.
+   * @returns A negative number if `a` should appear before `b`, a positive
+   *   number if `a` should appear after `b`, or `0` if they are equal.
+   * @since 1.0.0
+   *
+   * @example
+   * ```typescript
+   * // Sort sections alphabetically by title
+   * {
+   *   sectionOrder: (a, b) => (a.title ?? "").localeCompare(b.title ?? "")
+   * }
+   * ```
+   */
+  sectionOrder?: (a: DocSection, b: DocSection) => number;
 }
 /**
  * Formats a documentation page into a human-readable string.

package/dist/doc.js

@@ -3,6 +3,28 @@ import { formatUsage, formatUsageTerm } from "./usage.js";
 
 //#region src/doc.ts
 /**
+* Classifies a {@link DocSection} by its content type for use in the
+* default smart sort.
+*
+* @returns `0` for command-only sections, `1` for mixed sections, `2` for
+*   option/argument/passthrough-only sections.
+*/
+function classifySection(section) {
+	const hasCommand = section.entries.some((e) => e.term.type === "command");
+	const hasNonCommand = section.entries.some((e) => e.term.type !== "command");
+	if (hasCommand && !hasNonCommand) return 0;
+	if (hasCommand && hasNonCommand) return 1;
+	return 2;
+}
+/**
+* The default section comparator: command-only sections come first, then
+* mixed sections, then option/argument-only sections.  Sections with the
+* same score preserve their original relative order (stable sort).
+*/
+function defaultSectionOrder(a, b) {
+	return classifySection(a) - classifySection(b);
+}
+/**
 * Formats a documentation page into a human-readable string.
 *
 * This function takes a structured {@link DocPage} and converts it into
@@ -64,7 +86,16 @@ function formatDocPage(programName, page, options = {}) {
 		});
 		output += "\n";
 	}
-	const sections = page.sections.toSorted((a, b) => a.title == null && b.title == null ? 0 : a.title == null ? -1 : 1);
+	const comparator = options.sectionOrder ?? defaultSectionOrder;
+	const sections = page.sections.map((s, i) => ({
+		section: s,
+		index: i
+	})).toSorted((a, b) => {
+		const cmp = comparator(a.section, b.section);
+		if (cmp !== 0) return cmp;
+		const titleCmp = (a.section.title == null ? 0 : 1) - (b.section.title == null ? 0 : 1);
+		return titleCmp !== 0 ? titleCmp : a.index - b.index;
+	}).map(({ section }) => section);
 	for (const section of sections) {
 		if (section.entries.length < 1) continue;
 		output += "\n";

package/dist/facade.cjs

@@ -369,7 +369,7 @@ function classifyResult(result, args) {
 * Handles shell completion requests.
 * @since 0.6.0
 */
-function handleCompletion(completionArgs, programName, parser, completionParser, stdout, stderr, onCompletion, onError, availableShells, colors, maxWidth, completionMode, completionName) {
+function handleCompletion(completionArgs, programName, parser, completionParser, stdout, stderr, onCompletion, onError, availableShells, colors, maxWidth, completionMode, completionName, sectionOrder) {
 	const shellName = completionArgs[0] || "";
 	const args = completionArgs.slice(1);
 	const callOnError = (code) => {
@@ -392,7 +392,8 @@ function handleCompletion(completionArgs, programName, parser, completionParser,
 			const doc = require_parser.getDocPage(completionParser, ["completion"]);
 			if (doc) stderr(require_doc.formatDocPage(programName, doc, {
 				colors,
-				maxWidth
+				maxWidth,
+				sectionOrder
 			}));
 		}
 		if (parser.$mode === "async") return Promise.resolve(callOnError(1));
@@ -457,7 +458,7 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 		args = argsOrOptions;
 		options = optionsParam ?? {};
 	}
-	const { colors, maxWidth, showDefault, showChoices, aboveError = "usage", onError = () => {
+	const { colors, maxWidth, showDefault, showChoices, sectionOrder, aboveError = "usage", onError = () => {
 		throw new RunParserError("Failed to parse command line arguments.");
 	}, stderr = console.error, stdout = console.log, brief, description, examples, author, bugs, footer } = options;
 	const helpMode = options.help?.mode ?? "option";
@@ -500,7 +501,7 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 	} : createCompletionParser(completion, programName, availableShells, completionName, completionHelpVisibility);
 	if (options.completion) {
 		const hasHelpOption = args.includes("--help");
-		if ((completionMode === "command" || completionMode === "both") && args.length >= 1 && ((completionName === "singular" || completionName === "both" ? args[0] === "completion" : false) || (completionName === "plural" || completionName === "both" ? args[0] === "completions" : false)) && !hasHelpOption) return handleCompletion(args.slice(1), programName, parser, completionParsers.completionCommand, stdout, stderr, onCompletion, onError, availableShells, colors, maxWidth, completionMode, completionName);
+		if ((completionMode === "command" || completionMode === "both") && args.length >= 1 && ((completionName === "singular" || completionName === "both" ? args[0] === "completion" : false) || (completionName === "plural" || completionName === "both" ? args[0] === "completions" : false)) && !hasHelpOption) return handleCompletion(args.slice(1), programName, parser, completionParsers.completionCommand, stdout, stderr, onCompletion, onError, availableShells, colors, maxWidth, completionMode, completionName, sectionOrder);
 		if (completionMode === "option" || completionMode === "both") for (let i = 0; i < args.length; i++) {
 			const arg = args[i];
 			const singularMatch = completionName === "singular" || completionName === "both" ? arg.startsWith("--completion=") : false;
@@ -508,14 +509,14 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 			if (singularMatch || pluralMatch) {
 				const shell = arg.slice(arg.indexOf("=") + 1);
 				const completionArgs = args.slice(i + 1);
-				return handleCompletion([shell, ...completionArgs], programName, parser, completionParsers.completionCommand, stdout, stderr, onCompletion, onError, availableShells, colors, maxWidth, completionMode, completionName);
+				return handleCompletion([shell, ...completionArgs], programName, parser, completionParsers.completionCommand, stdout, stderr, onCompletion, onError, availableShells, colors, maxWidth, completionMode, completionName, sectionOrder);
 			} else {
 				const singularMatchExact = completionName === "singular" || completionName === "both" ? arg === "--completion" : false;
 				const pluralMatchExact = completionName === "plural" || completionName === "both" ? arg === "--completions" : false;
 				if (singularMatchExact || pluralMatchExact) {
 					const shell = i + 1 < args.length ? args[i + 1] : "";
 					const completionArgs = i + 1 < args.length ? args.slice(i + 2) : [];
-					return handleCompletion([shell, ...completionArgs], programName, parser, completionParsers.completionCommand, stdout, stderr, onCompletion, onError, availableShells, colors, maxWidth, completionMode, completionName);
+					return handleCompletion([shell, ...completionArgs], programName, parser, completionParsers.completionCommand, stdout, stderr, onCompletion, onError, availableShells, colors, maxWidth, completionMode, completionName, sectionOrder);
 				}
 			}
 		}
@@ -625,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,
@@ -636,7 +637,8 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 							colors,
 							maxWidth,
 							showDefault,
-							showChoices
+							showChoices,
+							sectionOrder
 						}));
 					}
 					try {

package/dist/facade.d.cts

@@ -1,5 +1,5 @@
 import { Message } from "./message.cjs";
-import { ShowChoicesOptions, ShowDefaultOptions } from "./doc.cjs";
+import { DocSection, ShowChoicesOptions, ShowDefaultOptions } from "./doc.cjs";
 import { InferMode, InferValue, Mode, ModeValue, Parser } from "./parser.cjs";
 import { ShellCompletion } from "./completion.cjs";
 import { ParserValuePlaceholder, SourceContext } from "./context.cjs";
@@ -148,6 +148,20 @@ interface RunOptions<THelp, TError> {
    * @since 0.10.0
    */
   readonly showChoices?: boolean | ShowChoicesOptions;
+  /**
+   * A custom comparator function to control the order of sections in the
+   * help output.  When provided, it is used instead of the default smart
+   * sort (command-only sections first, then mixed, then option/argument-only
+   * sections).  Sections that compare equal (return `0`) preserve their
+   * original relative order.
+   *
+   * @param a The first section to compare.
+   * @param b The second section to compare.
+   * @returns A negative number if `a` should appear before `b`, a positive
+   *   number if `a` should appear after `b`, or `0` if they are equal.
+   * @since 1.0.0
+   */
+  readonly sectionOrder?: (a: DocSection, b: DocSection) => number;
   /**
    * Help configuration. When provided, enables help functionality.
    */

package/dist/facade.d.ts

@@ -1,5 +1,5 @@
 import { Message } from "./message.js";
-import { ShowChoicesOptions, ShowDefaultOptions } from "./doc.js";
+import { DocSection, ShowChoicesOptions, ShowDefaultOptions } from "./doc.js";
 import { InferMode, InferValue, Mode, ModeValue, Parser } from "./parser.js";
 import { ShellCompletion } from "./completion.js";
 import { ParserValuePlaceholder, SourceContext } from "./context.js";
@@ -148,6 +148,20 @@ interface RunOptions<THelp, TError> {
    * @since 0.10.0
    */
   readonly showChoices?: boolean | ShowChoicesOptions;
+  /**
+   * A custom comparator function to control the order of sections in the
+   * help output.  When provided, it is used instead of the default smart
+   * sort (command-only sections first, then mixed, then option/argument-only
+   * sections).  Sections that compare equal (return `0`) preserve their
+   * original relative order.
+   *
+   * @param a The first section to compare.
+   * @param b The second section to compare.
+   * @returns A negative number if `a` should appear before `b`, a positive
+   *   number if `a` should appear after `b`, or `0` if they are equal.
+   * @since 1.0.0
+   */
+  readonly sectionOrder?: (a: DocSection, b: DocSection) => number;
   /**
    * Help configuration. When provided, enables help functionality.
    */

package/dist/facade.js

@@ -369,7 +369,7 @@ function classifyResult(result, args) {
 * Handles shell completion requests.
 * @since 0.6.0
 */
-function handleCompletion(completionArgs, programName, parser, completionParser, stdout, stderr, onCompletion, onError, availableShells, colors, maxWidth, completionMode, completionName) {
+function handleCompletion(completionArgs, programName, parser, completionParser, stdout, stderr, onCompletion, onError, availableShells, colors, maxWidth, completionMode, completionName, sectionOrder) {
 	const shellName = completionArgs[0] || "";
 	const args = completionArgs.slice(1);
 	const callOnError = (code) => {
@@ -392,7 +392,8 @@ function handleCompletion(completionArgs, programName, parser, completionParser,
 			const doc = getDocPage(completionParser, ["completion"]);
 			if (doc) stderr(formatDocPage(programName, doc, {
 				colors,
-				maxWidth
+				maxWidth,
+				sectionOrder
 			}));
 		}
 		if (parser.$mode === "async") return Promise.resolve(callOnError(1));
@@ -457,7 +458,7 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 		args = argsOrOptions;
 		options = optionsParam ?? {};
 	}
-	const { colors, maxWidth, showDefault, showChoices, aboveError = "usage", onError = () => {
+	const { colors, maxWidth, showDefault, showChoices, sectionOrder, aboveError = "usage", onError = () => {
 		throw new RunParserError("Failed to parse command line arguments.");
 	}, stderr = console.error, stdout = console.log, brief, description, examples, author, bugs, footer } = options;
 	const helpMode = options.help?.mode ?? "option";
@@ -500,7 +501,7 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 	} : createCompletionParser(completion, programName, availableShells, completionName, completionHelpVisibility);
 	if (options.completion) {
 		const hasHelpOption = args.includes("--help");
-		if ((completionMode === "command" || completionMode === "both") && args.length >= 1 && ((completionName === "singular" || completionName === "both" ? args[0] === "completion" : false) || (completionName === "plural" || completionName === "both" ? args[0] === "completions" : false)) && !hasHelpOption) return handleCompletion(args.slice(1), programName, parser, completionParsers.completionCommand, stdout, stderr, onCompletion, onError, availableShells, colors, maxWidth, completionMode, completionName);
+		if ((completionMode === "command" || completionMode === "both") && args.length >= 1 && ((completionName === "singular" || completionName === "both" ? args[0] === "completion" : false) || (completionName === "plural" || completionName === "both" ? args[0] === "completions" : false)) && !hasHelpOption) return handleCompletion(args.slice(1), programName, parser, completionParsers.completionCommand, stdout, stderr, onCompletion, onError, availableShells, colors, maxWidth, completionMode, completionName, sectionOrder);
 		if (completionMode === "option" || completionMode === "both") for (let i = 0; i < args.length; i++) {
 			const arg = args[i];
 			const singularMatch = completionName === "singular" || completionName === "both" ? arg.startsWith("--completion=") : false;
@@ -508,14 +509,14 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 			if (singularMatch || pluralMatch) {
 				const shell = arg.slice(arg.indexOf("=") + 1);
 				const completionArgs = args.slice(i + 1);
-				return handleCompletion([shell, ...completionArgs], programName, parser, completionParsers.completionCommand, stdout, stderr, onCompletion, onError, availableShells, colors, maxWidth, completionMode, completionName);
+				return handleCompletion([shell, ...completionArgs], programName, parser, completionParsers.completionCommand, stdout, stderr, onCompletion, onError, availableShells, colors, maxWidth, completionMode, completionName, sectionOrder);
 			} else {
 				const singularMatchExact = completionName === "singular" || completionName === "both" ? arg === "--completion" : false;
 				const pluralMatchExact = completionName === "plural" || completionName === "both" ? arg === "--completions" : false;
 				if (singularMatchExact || pluralMatchExact) {
 					const shell = i + 1 < args.length ? args[i + 1] : "";
 					const completionArgs = i + 1 < args.length ? args.slice(i + 2) : [];
-					return handleCompletion([shell, ...completionArgs], programName, parser, completionParsers.completionCommand, stdout, stderr, onCompletion, onError, availableShells, colors, maxWidth, completionMode, completionName);
+					return handleCompletion([shell, ...completionArgs], programName, parser, completionParsers.completionCommand, stdout, stderr, onCompletion, onError, availableShells, colors, maxWidth, completionMode, completionName, sectionOrder);
 				}
 			}
 		}
@@ -625,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,
@@ -636,7 +637,8 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 							colors,
 							maxWidth,
 							showDefault,
-							showChoices
+							showChoices,
+							sectionOrder
 						}));
 					}
 					try {

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.400+a38bcb54",
+  "version": "1.0.0-dev.407+21363ee4",
   "description": "Type-safe combinatorial command-line interface parser",
   "keywords": [
     "CLI",