@optique/core 1.4.0-dev.2616 → 1.4.0-dev.2618

package/dist/execution-context.cjs

@@ -1,4 +1,3 @@
-const require_short_option = require('./short-option.cjs');
 
 //#region src/execution-context.ts
 /**
@@ -38,7 +37,7 @@ function withChildContext(context, segment, state, usage) {
 	const exec = withChildExecPath(context.exec, segment);
 	const dependencyRegistry = context.dependencyRegistry ?? exec?.dependencyRegistry;
 	return {
-		...require_short_option.withOptionScopeChild(context, segment),
+		...context,
 		state,
 		...usage != null ? { usage } : {},
 		...exec != null ? {

package/dist/execution-context.js

@@ -1,5 +1,3 @@
-import { withOptionScopeChild } from "./short-option.js";
-
 //#region src/execution-context.ts
 /**
 * Appends a child parser segment to the current execution path.
@@ -38,7 +36,7 @@ function withChildContext(context, segment, state, usage) {
 	const exec = withChildExecPath(context.exec, segment);
 	const dependencyRegistry = context.dependencyRegistry ?? exec?.dependencyRegistry;
 	return {
-		...withOptionScopeChild(context, segment),
+		...context,
 		state,
 		...usage != null ? { usage } : {},
 		...exec != null ? {

package/dist/extension.cjs

@@ -2,7 +2,6 @@ const require_internal_annotations = require('./internal/annotations.cjs');
 const require_mode_dispatch = require('./internal/mode-dispatch.cjs');
 const require_internal_parser = require('./internal/parser.cjs');
 const require_annotation_state = require('./annotation-state.cjs');
-const require_short_option = require('./short-option.cjs');
 const require_phase2_seed = require('./phase2-seed.cjs');
 
 //#region src/extension.ts
@@ -29,19 +28,6 @@ function defineTraits(parser, traits) {
 	});
 }
 /**
-* Preserves a wrapped parser's reachable option names in the same parse path.
-* Call this when a transparent wrapper constructs a fresh parser object instead
-* of copying the inner parser with object spread.
-*
-* @param parser The wrapper parser to annotate.
-* @param innerParser The parser that handles the wrapper's CLI input.
-* @throws {TypeError} If scope metadata cannot be defined on the wrapper.
-* @since 1.4.0
-*/
-function inheritOptionScope$1(parser, innerParser) {
-	require_short_option.inheritOptionScope(parser, innerParser);
-}
-/**
 * Reads the stable extension traits defined on a parser object.
 *
 * @param parser The parser object to inspect.
@@ -94,7 +80,6 @@ exports.dispatchByMode = require_mode_dispatch.dispatchByMode;
 exports.extractPhase2SeedKey = require_phase2_seed.extractPhase2SeedKey;
 exports.getTraits = getTraits;
 exports.inheritAnnotations = require_internal_annotations.inheritAnnotations;
-exports.inheritOptionScope = inheritOptionScope$1;
 exports.injectAnnotations = require_internal_annotations.injectAnnotations;
 exports.isInjectedAnnotationState = require_internal_annotations.isInjectedAnnotationState;
 exports.mapModeValue = require_mode_dispatch.mapModeValue;

package/dist/extension.d.cts

@@ -60,17 +60,6 @@ type ParserSourceMetadata<M extends Mode = Mode, TValue = unknown, TState = unkn
  * @since 1.0.0
  */
 declare function defineTraits(parser: object, traits: ParserTraits): void;
-/**
- * Preserves a wrapped parser's reachable option names in the same parse path.
- * Call this when a transparent wrapper constructs a fresh parser object instead
- * of copying the inner parser with object spread.
- *
- * @param parser The wrapper parser to annotate.
- * @param innerParser The parser that handles the wrapper's CLI input.
- * @throws {TypeError} If scope metadata cannot be defined on the wrapper.
- * @since 1.4.0
- */
-declare function inheritOptionScope(parser: object, innerParser: Parser<Mode, unknown, unknown>): void;
 /**
  * Reads the stable extension traits defined on a parser object.
  *
@@ -106,4 +95,4 @@ declare function delegateSuggestNodes<TInnerState>(innerParser: Parser<Mode, unk
  */
 declare function mapSourceMetadata<M extends Mode, TValue, TState>(parser: Pick<Parser<M, TValue, TState>, "dependencyMetadata">, mapSource: (source: ParserSourceMetadata<M, TValue, TState>) => ParserSourceMetadata<M, TValue, TState>): Parser<M, TValue, TState>["dependencyMetadata"] | undefined;
 //#endregion
-export { ParserSourceMetadata, ParserTraits, SuggestNode, defineTraits, delegateSuggestNodes, dispatchByMode, extractPhase2SeedKey, getTraits, inheritAnnotations, inheritOptionScope, injectAnnotations, isInjectedAnnotationState, mapModeValue, mapSourceMetadata, unwrapInjectedAnnotationState, withAnnotationView, wrapForMode };
+export { ParserSourceMetadata, ParserTraits, SuggestNode, defineTraits, delegateSuggestNodes, dispatchByMode, extractPhase2SeedKey, getTraits, inheritAnnotations, injectAnnotations, isInjectedAnnotationState, mapModeValue, mapSourceMetadata, unwrapInjectedAnnotationState, withAnnotationView, wrapForMode };

package/dist/extension.d.ts

@@ -60,17 +60,6 @@ type ParserSourceMetadata<M extends Mode = Mode, TValue = unknown, TState = unkn
  * @since 1.0.0
  */
 declare function defineTraits(parser: object, traits: ParserTraits): void;
-/**
- * Preserves a wrapped parser's reachable option names in the same parse path.
- * Call this when a transparent wrapper constructs a fresh parser object instead
- * of copying the inner parser with object spread.
- *
- * @param parser The wrapper parser to annotate.
- * @param innerParser The parser that handles the wrapper's CLI input.
- * @throws {TypeError} If scope metadata cannot be defined on the wrapper.
- * @since 1.4.0
- */
-declare function inheritOptionScope(parser: object, innerParser: Parser<Mode, unknown, unknown>): void;
 /**
  * Reads the stable extension traits defined on a parser object.
  *
@@ -106,4 +95,4 @@ declare function delegateSuggestNodes<TInnerState>(innerParser: Parser<Mode, unk
  */
 declare function mapSourceMetadata<M extends Mode, TValue, TState>(parser: Pick<Parser<M, TValue, TState>, "dependencyMetadata">, mapSource: (source: ParserSourceMetadata<M, TValue, TState>) => ParserSourceMetadata<M, TValue, TState>): Parser<M, TValue, TState>["dependencyMetadata"] | undefined;
 //#endregion
-export { ParserSourceMetadata, ParserTraits, SuggestNode, defineTraits, delegateSuggestNodes, dispatchByMode, extractPhase2SeedKey, getTraits, inheritAnnotations, inheritOptionScope, injectAnnotations, isInjectedAnnotationState, mapModeValue, mapSourceMetadata, unwrapInjectedAnnotationState, withAnnotationView, wrapForMode };
+export { ParserSourceMetadata, ParserTraits, SuggestNode, defineTraits, delegateSuggestNodes, dispatchByMode, extractPhase2SeedKey, getTraits, inheritAnnotations, injectAnnotations, isInjectedAnnotationState, mapModeValue, mapSourceMetadata, unwrapInjectedAnnotationState, withAnnotationView, wrapForMode };

package/dist/extension.js

@@ -2,7 +2,6 @@ import { inheritAnnotations, injectAnnotations, isInjectedAnnotationState, unwra
 import { dispatchByMode, mapModeValue, wrapForMode } from "./internal/mode-dispatch.js";
 import { annotationWrapperRequiresSourceBindingKey, composeWrappedSourceMetadata, defineInheritedAnnotationParser, getDelegatingSuggestRuntimeNodes, inheritParentAnnotationsKey, unmatchedNonCliDependencySourceStateMarker } from "./internal/parser.js";
 import { withAnnotationView } from "./annotation-state.js";
-import { inheritOptionScope } from "./short-option.js";
 import { extractPhase2SeedKey } from "./phase2-seed.js";
 
 //#region src/extension.ts
@@ -29,19 +28,6 @@ function defineTraits(parser, traits) {
 	});
 }
 /**
-* Preserves a wrapped parser's reachable option names in the same parse path.
-* Call this when a transparent wrapper constructs a fresh parser object instead
-* of copying the inner parser with object spread.
-*
-* @param parser The wrapper parser to annotate.
-* @param innerParser The parser that handles the wrapper's CLI input.
-* @throws {TypeError} If scope metadata cannot be defined on the wrapper.
-* @since 1.4.0
-*/
-function inheritOptionScope$1(parser, innerParser) {
-	inheritOptionScope(parser, innerParser);
-}
-/**
 * Reads the stable extension traits defined on a parser object.
 *
 * @param parser The parser object to inspect.
@@ -88,4 +74,4 @@ function mapSourceMetadata(parser, mapSource) {
 }
 
 //#endregion
-export { defineTraits, delegateSuggestNodes, dispatchByMode, extractPhase2SeedKey, getTraits, inheritAnnotations, inheritOptionScope$1 as inheritOptionScope, injectAnnotations, isInjectedAnnotationState, mapModeValue, mapSourceMetadata, unwrapInjectedAnnotationState, withAnnotationView, wrapForMode };
+export { defineTraits, delegateSuggestNodes, dispatchByMode, extractPhase2SeedKey, getTraits, inheritAnnotations, injectAnnotations, isInjectedAnnotationState, mapModeValue, mapSourceMetadata, unwrapInjectedAnnotationState, withAnnotationView, wrapForMode };

package/dist/facade.cjs

@@ -12,7 +12,6 @@ const require_dependency_runtime = require('./dependency-runtime.cjs');
 const require_input_trace = require('./input-trace.cjs');
 const require_internal_parser = require('./internal/parser.cjs');
 const require_completion = require('./completion.cjs');
-const require_usage_internals = require('./usage-internals.cjs');
 const require_command_alias = require('./internal/command-alias.cjs');
 const require_phase2_seed = require('./phase2-seed.cjs');
 const require_modifiers = require('./modifiers.cjs');
@@ -751,16 +750,83 @@ function collectActiveValueOptionNames(usage, commandPath, includeDirectAfterCom
 		flag: /* @__PURE__ */ new Set()
 	};
 	if (commandPath.length === 0) {
-		require_usage_internals.collectRootOptionNames(usage, optionNames, rootLeadingNames);
+		collectRootOptionNames(usage, optionNames, rootLeadingNames);
 		return optionNames.value;
-	} else require_usage_internals.collectActiveOptionNames(usage, commandPath, optionNames, false, includeDirectAfterCommandOptions);
+	} else collectActiveOptionNames(usage, commandPath, optionNames, false, includeDirectAfterCommandOptions);
 	const names = new Set(optionNames.value);
 	for (const name of optionNames.flag) names.delete(name);
 	return names;
 }
+function collectRootOptionNames(usage, names, rootLeadingNames) {
+	for (const term of usage) collectRootOptionNamesFromTerm(term, names, rootLeadingNames);
+}
+function collectRootOptionNamesFromTerm(term, names, rootLeadingNames) {
+	switch (term.type) {
+		case "option":
+			for (const name of term.names) {
+				if (!rootLeadingNames.has(name)) continue;
+				if (term.metavar != null) names.value.add(name);
+				else names.flag.add(name);
+			}
+			return;
+		case "optional":
+		case "multiple":
+		case "sequence":
+			collectRootOptionNames(term.terms, names, rootLeadingNames);
+			return;
+		case "exclusive":
+			for (const branch of term.terms) collectRootOptionNames(branch, names, rootLeadingNames);
+			return;
+		case "argument":
+		case "command":
+		case "literal":
+		case "passthrough":
+		case "ellipsis": return;
+	}
+}
+function collectActiveOptionNames(usage, commandPath, names, fromExclusive, includeDirectAfterCommandOptions) {
+	if (commandPath.length === 0) {
+		collectOptionNamesAtCurrentCommandDepth(usage, names, false);
+		return;
+	}
+	const [commandName, ...rest] = commandPath;
+	for (let i = 0; i < usage.length; i++) {
+		const term = usage[i];
+		if (term.type === "command" && term.name === commandName) {
+			const remainingUsage = usage.slice(i + 1);
+			if (rest.length === 0) collectOptionNamesAtCurrentCommandDepth(remainingUsage, names, !fromExclusive && includeDirectAfterCommandOptions);
+			else collectActiveOptionNames(remainingUsage, rest, names, fromExclusive, includeDirectAfterCommandOptions);
+		} else if (term.type === "exclusive") for (const branch of term.terms) collectActiveOptionNames(branch, commandPath, names, true, includeDirectAfterCommandOptions);
+		else if (term.type === "optional" || term.type === "multiple" || term.type === "sequence") collectActiveOptionNames(term.terms, commandPath, names, fromExclusive, includeDirectAfterCommandOptions);
+	}
+}
 function isRootOptionToken(token, rootOptionSuggestions) {
 	return token != null && rootOptionSuggestions.some((suggestion) => token === suggestion.text || token.startsWith(`${suggestion.text}=`));
 }
+function collectOptionNamesAtCurrentCommandDepth(usage, names, afterMatchedCommand) {
+	for (const term of usage) if (collectOptionNamesAtCurrentCommandDepthFromTerm(term, names, afterMatchedCommand)) return;
+}
+function collectOptionNamesAtCurrentCommandDepthFromTerm(term, names, afterMatchedCommand) {
+	switch (term.type) {
+		case "command": return !afterMatchedCommand;
+		case "option":
+			if (term.metavar != null) for (const name of term.names) names.value.add(name);
+			else for (const name of term.names) names.flag.add(name);
+			return false;
+		case "optional":
+		case "multiple":
+		case "sequence":
+			collectOptionNamesAtCurrentCommandDepth(term.terms, names, afterMatchedCommand);
+			return false;
+		case "exclusive":
+			for (const branch of term.terms) collectOptionNamesAtCurrentCommandDepth(branch, names, false);
+			return false;
+		case "argument":
+		case "literal":
+		case "passthrough":
+		case "ellipsis": return false;
+	}
+}
 function getRootMetaOptionSuggestions(helpOptionConfig, helpOptionNames, versionOptionConfig, versionOptionNames) {
 	const suggestions = [];
 	if (helpOptionConfig != null && !require_usage.isSuggestionHidden(helpOptionConfig.hidden)) suggestions.push(...helpOptionNames.map((name) => ({
@@ -818,7 +884,7 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 		options = optionsParam ?? {};
 	}
 	require_validate.validateProgramName(programName);
-	const { colors, messageFormatter, theme: requestedTheme, maxWidth: requestedMaxWidth, termWidth, showDefault, showChoices, sectionOrder, showUsage, usageLine, commandList = "recursive", aboveError = "usage", onError = () => {
+	const { colors, messageFormatter, theme: requestedTheme, maxWidth: requestedMaxWidth, termWidth, showDefault, showChoices, sectionOrder, helpSections, showUsage, usageLine, commandList = "recursive", 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;
 	let maxWidth = requestedMaxWidth;
@@ -850,6 +916,7 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 	const onCompletion = options.completion?.onShow ?? (() => ({}));
 	const onCompletionResult = (code) => onCompletion(code);
 	const onErrorResult = (code, error) => onError(code, error);
+	for (const label of [helpSections?.commands, helpSections?.options]) if (label !== void 0) require_validate.validateLabel(label);
 	if (helpOptionConfig?.names) require_validate.validateOptionNames(helpOptionConfig.names, "Help option");
 	if (helpCommandConfig?.names) require_validate.validateCommandNames(helpCommandConfig.names, "Help command");
 	if (versionOptionConfig?.names) require_validate.validateOptionNames(versionOptionConfig.names, "Version option");
@@ -1022,7 +1089,8 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 							bugs: isTopLevel && !isMetaCommandHelp ? bugs ?? doc.bugs : void 0,
 							footer: shouldOverride ? footer ?? doc.footer : doc.footer ?? footer
 						}, commandList, isTopLevel);
-						const renderedDoc = isTopLevel && usageLine != null ? applyUsageLine(augmentedDoc, usageLine) : augmentedDoc;
+						const groupedDoc = applyHelpSections(augmentedDoc, helpSections);
+						const renderedDoc = isTopLevel && usageLine != null ? applyUsageLine(groupedDoc, usageLine) : groupedDoc;
 						stdout(require_doc.formatDocPage(programName, renderedDoc, formatOptions({
 							messageFormatter,
 							theme,
@@ -1098,7 +1166,8 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 							footer: footer ?? doc.footer
 						}, commandList, isTopLevel);
 						const defaultRootUsage = typeof usageLine === "function" && (options.help || options.version || options.completion) ? require_usage.normalizeUsage(getRootHelpGeneratorParser().usage) : augmentedDoc.usage ?? [];
-						const renderedDoc = isTopLevel && usageLine != null ? applyUsageLine(augmentedDoc, usageLine, defaultRootUsage) : augmentedDoc;
+						const groupedDoc = applyHelpSections(augmentedDoc, helpSections);
+						const renderedDoc = isTopLevel && usageLine != null ? applyUsageLine(groupedDoc, usageLine, defaultRootUsage) : groupedDoc;
 						stderr(require_doc.formatDocPage(programName, renderedDoc, formatOptions({
 							messageFormatter,
 							theme,
@@ -1185,6 +1254,7 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 * @returns The parsed result if successful.
 * @throws {TypeError} If an async parser is passed at runtime.  Use
 * {@link runParser} or {@link runParserAsync} for async parsers.
+* @throws {TypeError} If a `helpSections` label is invalid.
 * @since 0.9.0
 */
 function runParserSync(parser, programName, args, options) {
@@ -1207,6 +1277,7 @@ function runParserSync(parser, programName, args, options) {
 * @param options Configuration options for customizing behavior.
 * @throws {RangeError} If rendering help or errors encounters an invalid theme
 * color, even when colors are disabled.
+* @throws {TypeError} If a `helpSections` label is invalid.
 * @returns A Promise of the parsed result if successful.
 * @since 0.9.0
 */
@@ -1221,6 +1292,66 @@ function applyUsageLine(doc, usageLine, defaultUsageLine = doc.usage ?? []) {
 		usage: require_usage.normalizeUsage(customUsageLine)
 	};
 }
+/** Prepares the runner's final page without changing parser documentation. */
+function applyHelpSections(doc, labels) {
+	if (labels == null || labels.commands == null && labels.options == null) return doc;
+	const visible = (entry) => !require_doc.isDocEntryHidden(entry) && require_usage.formatUsageTerm(entry.term, { context: "doc" }).trim() !== "";
+	if (!doc.sections.some((section) => section.entries.some((entry) => entry.term.type === "command" && visible(entry)))) return doc;
+	const existingTitles = new Set(doc.sections.flatMap((section) => section.title == null ? [] : [section.title]));
+	const additions = /* @__PURE__ */ new Map();
+	const residuals = /* @__PURE__ */ new Map();
+	const newSections = /* @__PURE__ */ new Map();
+	for (const section of doc.sections) {
+		if (section.title != null) continue;
+		const commands = [];
+		const options = [];
+		const remaining = [];
+		for (const entry of section.entries) if (entry.term.type === "command" && labels.commands != null && visible(entry)) commands.push(entry);
+		else if (entry.term.type === "option" && labels.options != null && visible(entry)) options.push(entry);
+		else remaining.push(entry);
+		if (commands.length === 0 && options.length === 0) continue;
+		residuals.set(section, remaining);
+		for (const [label, entries] of [[labels.commands, commands], [labels.options, options]]) {
+			if (label == null || entries.length === 0) continue;
+			const previous = additions.get(label);
+			if (previous != null) previous.push(...entries);
+			else {
+				additions.set(label, entries);
+				if (!existingTitles.has(label)) {
+					const titles = newSections.get(section) ?? [];
+					titles.push(label);
+					newSections.set(section, titles);
+				}
+			}
+		}
+	}
+	if (additions.size === 0) return doc;
+	const sections = [];
+	for (const section of doc.sections) {
+		if (section.title != null) {
+			const entries$1 = additions.get(section.title);
+			sections.push(entries$1 == null ? section : {
+				...section,
+				entries: [...section.entries, ...entries$1]
+			});
+			continue;
+		}
+		for (const title of newSections.get(section) ?? []) sections.push({
+			title,
+			entries: additions.get(title) ?? []
+		});
+		const entries = residuals.get(section);
+		if (entries == null) sections.push(section);
+		else if (entries.length > 0) sections.push({
+			...section,
+			entries
+		});
+	}
+	return {
+		...doc,
+		sections
+	};
+}
 function maybeCollapseCommandList(doc, commandList, isTopLevel) {
 	if (commandList !== "top-level" || !isTopLevel) return doc;
 	return {
@@ -1556,6 +1687,7 @@ async function runWithBody(parser, programName, contexts, args, options) {
 * @param programName Name of the program for help/error output.
 * @param contexts Source contexts to use (priority: earlier overrides later).
 * @param options Run options including args, help, version, etc.
+* @throws {TypeError} If a `helpSections` label is invalid.
 * @throws {RangeError} If rendering help or errors encounters an invalid theme
 * color, even when colors are disabled.
 * @returns Promise that resolves to the parsed result.
@@ -1656,6 +1788,7 @@ function runWithSyncBody(parser, programName, contexts, args, options) {
 * @param programName Name of the program for help/error output.
 * @param contexts Source contexts to use (priority: earlier overrides later).
 * @param options Run options including args, help, version, etc.
+* @throws {TypeError} If a `helpSections` label is invalid.
 * @throws {RangeError} If rendering help or errors encounters an invalid theme
 * color, even when colors are disabled.
 * @returns The parsed result.
@@ -1707,6 +1840,7 @@ function runWithSync(parser, programName, contexts, options) {
 * @param programName Name of the program for help/error output.
 * @param contexts Source contexts to use (priority: earlier overrides later).
 * @param options Run options including args, help, version, etc.
+* @throws {TypeError} If a `helpSections` label is invalid.
 * @throws {RangeError} If rendering help or errors encounters an invalid theme
 * color, even when colors are disabled.
 * @returns Promise that resolves to the parsed result.

package/dist/facade.d.cts

@@ -20,6 +20,19 @@ import { Program } from "./program.cjs";
  * @since 1.2.0
  */
 type CommandListMode = "recursive" | "top-level";
+/**
+ * Labels for automatically grouping untitled help entries on pages that
+ * contain visible commands. Explicitly titled sections keep their titles.
+ * Missing labels leave the corresponding entries untitled.
+ *
+ * @since 1.4.0
+ */
+interface HelpSectionsOptions {
+  /** Heading for untitled command entries. */
+  readonly commands?: string;
+  /** Heading for untitled option entries, including built-in meta options. */
+  readonly options?: string;
+}
 /**
  * Sub-configuration for a meta command's command form.
  *
@@ -184,6 +197,16 @@ interface RunOptions<THelp, TError> {
    * @since 1.0.0
    */
   readonly sectionOrder?: (a: DocSection, b: DocSection) => number;
+  /**
+   * Groups untitled command and option entries when the help page contains
+   * visible commands. Pages without commands receive no automatic headings.
+   * Existing titled sections are preserved; matching automatic entries are
+   * appended to them. Applies to help callbacks and help above errors too.
+   * Supplied labels must be nonempty and contain no control characters.
+   *
+   * @since 1.4.0
+   */
+  readonly helpSections?: HelpSectionsOptions;
   /**
    * Help configuration.  When provided, enables help functionality.
    * At least one of `command` or `option` must be specified.
@@ -382,7 +405,9 @@ interface RunOptions<THelp, TError> {
  *          non-empty string without ASCII control characters, or if any
  *          meta command/option name is empty, whitespace-only, contains
  *          whitespace or control characters, or (for option names) lacks a
- *          valid prefix (`--`, `-`, `/`, or `+`).
+ *          valid prefix (`--`, `-`, `/`, or `+`). Also thrown if a
+ *          `helpSections` label is empty, whitespace-only, or contains
+ *          control characters.
  * @throws {RunParserError} When parsing fails and no `onError` callback is
  *          provided, or if the requested help page cannot be generated.
  * @since 0.10.0 Added support for {@link Program} objects.
@@ -411,6 +436,7 @@ declare function runParser<TParser extends Parser<Mode, unknown, unknown>, THelp
  * @returns The parsed result if successful.
  * @throws {TypeError} If an async parser is passed at runtime.  Use
  * {@link runParser} or {@link runParserAsync} for async parsers.
+ * @throws {TypeError} If a `helpSections` label is invalid.
  * @since 0.9.0
  */
 declare function runParserSync<TParser extends Parser<"sync", unknown, unknown>, THelp = void, TError = never>(parser: TParser, programName: string, args: readonly string[], options?: RunOptions<THelp, TError>): InferValue<TParser>;
@@ -430,6 +456,7 @@ declare function runParserSync<TParser extends Parser<"sync", unknown, unknown>,
  * @param options Configuration options for customizing behavior.
  * @throws {RangeError} If rendering help or errors encounters an invalid theme
  * color, even when colors are disabled.
+ * @throws {TypeError} If a `helpSections` label is invalid.
  * @returns A Promise of the parsed result if successful.
  * @since 0.9.0
  */
@@ -544,6 +571,7 @@ type ContextOptionsParam<TContexts extends readonly SourceContext<unknown>[], TV
  * @param programName Name of the program for help/error output.
  * @param contexts Source contexts to use (priority: earlier overrides later).
  * @param options Run options including args, help, version, etc.
+ * @throws {TypeError} If a `helpSections` label is invalid.
  * @throws {RangeError} If rendering help or errors encounters an invalid theme
  * color, even when colors are disabled.
  * @returns Promise that resolves to the parsed result.
@@ -595,6 +623,7 @@ declare function runWith<TParser extends Parser<Mode, unknown, unknown>, TContex
  * @param programName Name of the program for help/error output.
  * @param contexts Source contexts to use (priority: earlier overrides later).
  * @param options Run options including args, help, version, etc.
+ * @throws {TypeError} If a `helpSections` label is invalid.
  * @throws {RangeError} If rendering help or errors encounters an invalid theme
  * color, even when colors are disabled.
  * @returns The parsed result.
@@ -625,6 +654,7 @@ declare function runWithSync<TParser extends Parser<"sync", unknown, unknown>, T
  * @param programName Name of the program for help/error output.
  * @param contexts Source contexts to use (priority: earlier overrides later).
  * @param options Run options including args, help, version, etc.
+ * @throws {TypeError} If a `helpSections` label is invalid.
  * @throws {RangeError} If rendering help or errors encounters an invalid theme
  * color, even when colors are disabled.
  * @returns Promise that resolves to the parsed result.
@@ -637,4 +667,4 @@ declare function runWithSync<TParser extends Parser<"sync", unknown, unknown>, T
  */
 declare function runWithAsync<TParser extends Parser<Mode, unknown, unknown>, TContexts extends readonly SourceContext<unknown>[], THelp = void, TError = never>(parser: TParser, programName: string, contexts: TContexts, options: RunWithOptions<THelp, TError> & ContextOptionsParam<TContexts, InferValue<TParser>>): Promise<InferValue<TParser>>;
 //#endregion
-export { CommandListMode, CommandSubConfig, ContextOptionsParam, ExtractRequiredOptions, OptionSubConfig, type ParserValuePlaceholder, RunOptions, RunParserError, RunWithOptions, type SourceContext, type SourceContextRequest, SubstituteParserValue, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync };
+export { CommandListMode, CommandSubConfig, ContextOptionsParam, ExtractRequiredOptions, HelpSectionsOptions, OptionSubConfig, type ParserValuePlaceholder, RunOptions, RunParserError, RunWithOptions, type SourceContext, type SourceContextRequest, SubstituteParserValue, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync };

package/dist/facade.d.ts

@@ -20,6 +20,19 @@ import { Program } from "./program.js";
  * @since 1.2.0
  */
 type CommandListMode = "recursive" | "top-level";
+/**
+ * Labels for automatically grouping untitled help entries on pages that
+ * contain visible commands. Explicitly titled sections keep their titles.
+ * Missing labels leave the corresponding entries untitled.
+ *
+ * @since 1.4.0
+ */
+interface HelpSectionsOptions {
+  /** Heading for untitled command entries. */
+  readonly commands?: string;
+  /** Heading for untitled option entries, including built-in meta options. */
+  readonly options?: string;
+}
 /**
  * Sub-configuration for a meta command's command form.
  *
@@ -184,6 +197,16 @@ interface RunOptions<THelp, TError> {
    * @since 1.0.0
    */
   readonly sectionOrder?: (a: DocSection, b: DocSection) => number;
+  /**
+   * Groups untitled command and option entries when the help page contains
+   * visible commands. Pages without commands receive no automatic headings.
+   * Existing titled sections are preserved; matching automatic entries are
+   * appended to them. Applies to help callbacks and help above errors too.
+   * Supplied labels must be nonempty and contain no control characters.
+   *
+   * @since 1.4.0
+   */
+  readonly helpSections?: HelpSectionsOptions;
   /**
    * Help configuration.  When provided, enables help functionality.
    * At least one of `command` or `option` must be specified.
@@ -382,7 +405,9 @@ interface RunOptions<THelp, TError> {
  *          non-empty string without ASCII control characters, or if any
  *          meta command/option name is empty, whitespace-only, contains
  *          whitespace or control characters, or (for option names) lacks a
- *          valid prefix (`--`, `-`, `/`, or `+`).
+ *          valid prefix (`--`, `-`, `/`, or `+`). Also thrown if a
+ *          `helpSections` label is empty, whitespace-only, or contains
+ *          control characters.
  * @throws {RunParserError} When parsing fails and no `onError` callback is
  *          provided, or if the requested help page cannot be generated.
  * @since 0.10.0 Added support for {@link Program} objects.
@@ -411,6 +436,7 @@ declare function runParser<TParser extends Parser<Mode, unknown, unknown>, THelp
  * @returns The parsed result if successful.
  * @throws {TypeError} If an async parser is passed at runtime.  Use
  * {@link runParser} or {@link runParserAsync} for async parsers.
+ * @throws {TypeError} If a `helpSections` label is invalid.
  * @since 0.9.0
  */
 declare function runParserSync<TParser extends Parser<"sync", unknown, unknown>, THelp = void, TError = never>(parser: TParser, programName: string, args: readonly string[], options?: RunOptions<THelp, TError>): InferValue<TParser>;
@@ -430,6 +456,7 @@ declare function runParserSync<TParser extends Parser<"sync", unknown, unknown>,
  * @param options Configuration options for customizing behavior.
  * @throws {RangeError} If rendering help or errors encounters an invalid theme
  * color, even when colors are disabled.
+ * @throws {TypeError} If a `helpSections` label is invalid.
  * @returns A Promise of the parsed result if successful.
  * @since 0.9.0
  */
@@ -544,6 +571,7 @@ type ContextOptionsParam<TContexts extends readonly SourceContext<unknown>[], TV
  * @param programName Name of the program for help/error output.
  * @param contexts Source contexts to use (priority: earlier overrides later).
  * @param options Run options including args, help, version, etc.
+ * @throws {TypeError} If a `helpSections` label is invalid.
  * @throws {RangeError} If rendering help or errors encounters an invalid theme
  * color, even when colors are disabled.
  * @returns Promise that resolves to the parsed result.
@@ -595,6 +623,7 @@ declare function runWith<TParser extends Parser<Mode, unknown, unknown>, TContex
  * @param programName Name of the program for help/error output.
  * @param contexts Source contexts to use (priority: earlier overrides later).
  * @param options Run options including args, help, version, etc.
+ * @throws {TypeError} If a `helpSections` label is invalid.
  * @throws {RangeError} If rendering help or errors encounters an invalid theme
  * color, even when colors are disabled.
  * @returns The parsed result.
@@ -625,6 +654,7 @@ declare function runWithSync<TParser extends Parser<"sync", unknown, unknown>, T
  * @param programName Name of the program for help/error output.
  * @param contexts Source contexts to use (priority: earlier overrides later).
  * @param options Run options including args, help, version, etc.
+ * @throws {TypeError} If a `helpSections` label is invalid.
  * @throws {RangeError} If rendering help or errors encounters an invalid theme
  * color, even when colors are disabled.
  * @returns Promise that resolves to the parsed result.
@@ -637,4 +667,4 @@ declare function runWithSync<TParser extends Parser<"sync", unknown, unknown>, T
  */
 declare function runWithAsync<TParser extends Parser<Mode, unknown, unknown>, TContexts extends readonly SourceContext<unknown>[], THelp = void, TError = never>(parser: TParser, programName: string, contexts: TContexts, options: RunWithOptions<THelp, TError> & ContextOptionsParam<TContexts, InferValue<TParser>>): Promise<InferValue<TParser>>;
 //#endregion
-export { CommandListMode, CommandSubConfig, ContextOptionsParam, ExtractRequiredOptions, OptionSubConfig, type ParserValuePlaceholder, RunOptions, RunParserError, RunWithOptions, type SourceContext, type SourceContextRequest, SubstituteParserValue, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync };
+export { CommandListMode, CommandSubConfig, ContextOptionsParam, ExtractRequiredOptions, HelpSectionsOptions, OptionSubConfig, type ParserValuePlaceholder, RunOptions, RunParserError, RunWithOptions, type SourceContext, type SourceContextRequest, SubstituteParserValue, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync };