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

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);
 				}
 			}
 		}
@@ -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);
 				}
 			}
 		}
@@ -636,7 +637,8 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 							colors,
 							maxWidth,
 							showDefault,
-							showChoices
+							showChoices,
+							sectionOrder
 						}));
 					}
 					try {

package/package.json

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