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

package/dist/execution-context.cjs

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

package/dist/execution-context.js

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

package/dist/extension.cjs

@@ -2,6 +2,7 @@ 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
@@ -28,6 +29,19 @@ 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.
@@ -80,6 +94,7 @@ 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,6 +60,17 @@ 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.
  *
@@ -95,4 +106,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, injectAnnotations, isInjectedAnnotationState, mapModeValue, mapSourceMetadata, unwrapInjectedAnnotationState, withAnnotationView, wrapForMode };
+export { ParserSourceMetadata, ParserTraits, SuggestNode, defineTraits, delegateSuggestNodes, dispatchByMode, extractPhase2SeedKey, getTraits, inheritAnnotations, inheritOptionScope, injectAnnotations, isInjectedAnnotationState, mapModeValue, mapSourceMetadata, unwrapInjectedAnnotationState, withAnnotationView, wrapForMode };

package/dist/extension.d.ts

@@ -60,6 +60,17 @@ 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.
  *
@@ -95,4 +106,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, injectAnnotations, isInjectedAnnotationState, mapModeValue, mapSourceMetadata, unwrapInjectedAnnotationState, withAnnotationView, wrapForMode };
+export { ParserSourceMetadata, ParserTraits, SuggestNode, defineTraits, delegateSuggestNodes, dispatchByMode, extractPhase2SeedKey, getTraits, inheritAnnotations, inheritOptionScope, injectAnnotations, isInjectedAnnotationState, mapModeValue, mapSourceMetadata, unwrapInjectedAnnotationState, withAnnotationView, wrapForMode };

package/dist/extension.js

@@ -2,6 +2,7 @@ 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
@@ -28,6 +29,19 @@ 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.
@@ -74,4 +88,4 @@ function mapSourceMetadata(parser, mapSource) {
 }
 
 //#endregion
-export { defineTraits, delegateSuggestNodes, dispatchByMode, extractPhase2SeedKey, getTraits, inheritAnnotations, injectAnnotations, isInjectedAnnotationState, mapModeValue, mapSourceMetadata, unwrapInjectedAnnotationState, withAnnotationView, wrapForMode };
+export { defineTraits, delegateSuggestNodes, dispatchByMode, extractPhase2SeedKey, getTraits, inheritAnnotations, inheritOptionScope$1 as inheritOptionScope, injectAnnotations, isInjectedAnnotationState, mapModeValue, mapSourceMetadata, unwrapInjectedAnnotationState, withAnnotationView, wrapForMode };

package/dist/facade.cjs

@@ -12,6 +12,7 @@ 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');
@@ -750,83 +751,16 @@ function collectActiveValueOptionNames(usage, commandPath, includeDirectAfterCom
 		flag: /* @__PURE__ */ new Set()
 	};
 	if (commandPath.length === 0) {
-		collectRootOptionNames(usage, optionNames, rootLeadingNames);
+		require_usage_internals.collectRootOptionNames(usage, optionNames, rootLeadingNames);
 		return optionNames.value;
-	} else collectActiveOptionNames(usage, commandPath, optionNames, false, includeDirectAfterCommandOptions);
+	} else require_usage_internals.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) => ({
@@ -884,7 +818,7 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 		options = optionsParam ?? {};
 	}
 	require_validate.validateProgramName(programName);
-	const { colors, messageFormatter, theme: requestedTheme, maxWidth: requestedMaxWidth, termWidth, showDefault, showChoices, sectionOrder, helpSections, showUsage, usageLine, commandList = "recursive", aboveError = "usage", onError = () => {
+	const { colors, messageFormatter, theme: requestedTheme, maxWidth: requestedMaxWidth, termWidth, showDefault, showChoices, sectionOrder, 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;
@@ -916,7 +850,6 @@ 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");
@@ -1089,8 +1022,7 @@ 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 groupedDoc = applyHelpSections(augmentedDoc, helpSections);
-						const renderedDoc = isTopLevel && usageLine != null ? applyUsageLine(groupedDoc, usageLine) : groupedDoc;
+						const renderedDoc = isTopLevel && usageLine != null ? applyUsageLine(augmentedDoc, usageLine) : augmentedDoc;
 						stdout(require_doc.formatDocPage(programName, renderedDoc, formatOptions({
 							messageFormatter,
 							theme,
@@ -1166,8 +1098,7 @@ 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 groupedDoc = applyHelpSections(augmentedDoc, helpSections);
-						const renderedDoc = isTopLevel && usageLine != null ? applyUsageLine(groupedDoc, usageLine, defaultRootUsage) : groupedDoc;
+						const renderedDoc = isTopLevel && usageLine != null ? applyUsageLine(augmentedDoc, usageLine, defaultRootUsage) : augmentedDoc;
 						stderr(require_doc.formatDocPage(programName, renderedDoc, formatOptions({
 							messageFormatter,
 							theme,
@@ -1254,7 +1185,6 @@ 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) {
@@ -1277,7 +1207,6 @@ 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
 */
@@ -1292,66 +1221,6 @@ 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 {
@@ -1687,7 +1556,6 @@ 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.
@@ -1788,7 +1656,6 @@ 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.
@@ -1840,7 +1707,6 @@ 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,19 +20,6 @@ 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.
  *
@@ -197,16 +184,6 @@ 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.
@@ -405,9 +382,7 @@ 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 `+`). Also thrown if a
- *          `helpSections` label is empty, whitespace-only, or contains
- *          control characters.
+ *          valid prefix (`--`, `-`, `/`, or `+`).
  * @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.
@@ -436,7 +411,6 @@ 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>;
@@ -456,7 +430,6 @@ 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
  */
@@ -571,7 +544,6 @@ 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.
@@ -623,7 +595,6 @@ 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.
@@ -654,7 +625,6 @@ 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.
@@ -667,4 +637,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, HelpSectionsOptions, OptionSubConfig, type ParserValuePlaceholder, RunOptions, RunParserError, RunWithOptions, type SourceContext, type SourceContextRequest, SubstituteParserValue, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync };
+export { CommandListMode, CommandSubConfig, ContextOptionsParam, ExtractRequiredOptions, OptionSubConfig, type ParserValuePlaceholder, RunOptions, RunParserError, RunWithOptions, type SourceContext, type SourceContextRequest, SubstituteParserValue, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync };

package/dist/facade.d.ts

@@ -20,19 +20,6 @@ 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.
  *
@@ -197,16 +184,6 @@ 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.
@@ -405,9 +382,7 @@ 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 `+`). Also thrown if a
- *          `helpSections` label is empty, whitespace-only, or contains
- *          control characters.
+ *          valid prefix (`--`, `-`, `/`, or `+`).
  * @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.
@@ -436,7 +411,6 @@ 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>;
@@ -456,7 +430,6 @@ 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
  */
@@ -571,7 +544,6 @@ 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.
@@ -623,7 +595,6 @@ 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.
@@ -654,7 +625,6 @@ 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.
@@ -667,4 +637,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, HelpSectionsOptions, OptionSubConfig, type ParserValuePlaceholder, RunOptions, RunParserError, RunWithOptions, type SourceContext, type SourceContextRequest, SubstituteParserValue, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync };
+export { CommandListMode, CommandSubConfig, ContextOptionsParam, ExtractRequiredOptions, OptionSubConfig, type ParserValuePlaceholder, RunOptions, RunParserError, RunWithOptions, type SourceContext, type SourceContextRequest, SubstituteParserValue, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync };