@optique/core 1.0.0-dev.416 → 1.0.0-dev.428

package/dist/constructs.cjs

@@ -19,6 +19,60 @@ function createUnexpectedInputErrorWithScopedSuggestions(baseError, invalidInput
 		...suggestionMsg
 	] : baseError;
 }
+function applyHiddenToUsageTerm(term, hidden) {
+	if (hidden == null) return term;
+	if (term.type === "optional") return {
+		type: "optional",
+		terms: applyHiddenToUsage(term.terms, hidden)
+	};
+	if (term.type === "multiple") return {
+		type: "multiple",
+		terms: applyHiddenToUsage(term.terms, hidden),
+		min: term.min
+	};
+	if (term.type === "exclusive") return {
+		type: "exclusive",
+		terms: term.terms.map((u) => applyHiddenToUsage(u, hidden))
+	};
+	if (term.type === "argument" || term.type === "option" || term.type === "command" || term.type === "passthrough") return {
+		...term,
+		hidden: require_usage.mergeHidden(term.hidden, hidden)
+	};
+	return term;
+}
+function applyHiddenToUsage(usage, hidden) {
+	if (hidden == null) return usage;
+	return usage.map((term) => applyHiddenToUsageTerm(term, hidden));
+}
+function applyHiddenToDocEntry(entry, hidden) {
+	const mergedTerm = applyHiddenToUsageTerm(entry.term, hidden);
+	if ((mergedTerm.type === "argument" || mergedTerm.type === "option" || mergedTerm.type === "command" || mergedTerm.type === "passthrough") && require_usage.isDocHidden(mergedTerm.hidden)) return void 0;
+	return {
+		...entry,
+		term: mergedTerm
+	};
+}
+function applyHiddenToDocFragments(fragments, hidden) {
+	if (hidden == null) return fragments;
+	const result = [];
+	for (const fragment of fragments) {
+		if (fragment.type === "entry") {
+			const entry = applyHiddenToDocEntry(fragment, hidden);
+			if (entry != null) result.push({
+				...entry,
+				type: "entry"
+			});
+			continue;
+		}
+		const entries = fragment.entries.map((entry) => applyHiddenToDocEntry(entry, hidden)).filter((entry) => entry != null);
+		result.push({
+			type: "section",
+			title: fragment.title,
+			entries
+		});
+	}
+	return result;
+}
 /**
 * Checks if the given token is an option name that requires a value
 * (i.e., has a metavar) within the given usage terms.
@@ -919,7 +973,7 @@ function object(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 		$valueType: [],
 		$stateType: [],
 		priority: Math.max(...parserKeys.map((k) => parsers[k].priority)),
-		usage: parserPairs.flatMap(([_, p]) => p.usage),
+		usage: applyHiddenToUsage(parserPairs.flatMap(([_, p]) => p.usage), options.hidden),
 		initialState,
 		parse(context) {
 			return require_mode_dispatch.dispatchByMode(combinedMode, () => parseSync(context), () => parseAsync(context));
@@ -1028,6 +1082,7 @@ function object(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 			});
 		},
 		suggest(context, prefix) {
+			if (options.hidden === true) return require_mode_dispatch.dispatchIterableByMode(combinedMode, function* () {}, async function* () {});
 			return require_mode_dispatch.dispatchIterableByMode(combinedMode, () => {
 				const syncParserPairs = parserPairs;
 				return suggestObjectSync(context, prefix, syncParserPairs);
@@ -1041,9 +1096,10 @@ function object(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 				};
 				return p.getDocFragments(fieldState, defaultValue?.[field]).fragments;
 			});
-			const entries = fragments.filter((d) => d.type === "entry");
+			const hiddenAwareFragments = applyHiddenToDocFragments(fragments, options.hidden);
+			const entries = hiddenAwareFragments.filter((d) => d.type === "entry");
 			const sections = [];
-			for (const fragment of fragments) {
+			for (const fragment of hiddenAwareFragments) {
 				if (fragment.type !== "section") continue;
 				if (fragment.title == null) entries.push(...fragment.entries);
 				else sections.push(fragment);
@@ -1518,7 +1574,7 @@ function merge(...args) {
 		$valueType: [],
 		$stateType: [],
 		priority: Math.max(...parsers.map((p) => p.priority)),
-		usage: parsers.flatMap((p) => p.usage),
+		usage: applyHiddenToUsage(parsers.flatMap((p) => p.usage), options.hidden),
 		initialState,
 		parse(context) {
 			if (isAsync) return parseAsync(context);
@@ -1572,6 +1628,7 @@ function merge(...args) {
 			})();
 		},
 		suggest(context, prefix) {
+			if (options.hidden === true) return require_mode_dispatch.dispatchIterableByMode(combinedMode, function* () {}, async function* () {});
 			const extractState = (p, i) => {
 				if (p.initialState === void 0) {
 					const key = `__parser_${i}`;
@@ -1638,9 +1695,10 @@ function merge(...args) {
 				footer ??= docFragments.footer;
 				return docFragments.fragments;
 			});
-			const entries = fragments.filter((f) => f.type === "entry");
+			const hiddenAwareFragments = applyHiddenToDocFragments(fragments, options.hidden);
+			const entries = hiddenAwareFragments.filter((f) => f.type === "entry");
 			const sections = [];
-			for (const fragment of fragments) {
+			for (const fragment of hiddenAwareFragments) {
 				if (fragment.type !== "section") continue;
 				if (fragment.title == null) entries.push(...fragment.entries);
 				else sections.push(fragment);
@@ -1915,64 +1973,26 @@ function concat(...parsers) {
 		}
 	};
 }
-/**
-* Wraps a parser with a group label for documentation purposes.
-*
-* The `group()` function is a documentation-only wrapper that applies a label
-* to any parser for help text organization. This allows you to use clean code
-* structure with combinators like {@link merge} while maintaining well-organized
-* help text through group labeling.
-*
-* The wrapped parser has identical parsing behavior but generates documentation
-* fragments wrapped in a labeled section. This is particularly useful when
-* combining parsers using {@link merge}—you can wrap the merged result with
-* `group()` to add a section header in help output.
-*
-* @example
-* ```typescript
-* const apiOptions = merge(
-*   object({ endpoint: option("--endpoint", string()) }),
-*   object({ timeout: option("--timeout", integer()) })
-* );
-*
-* const groupedApiOptions = group("API Options", apiOptions);
-* // Now produces a labeled "API Options" section in help text
-* ```
-*
-* @example
-* ```typescript
-* // Can be used with any parser, not just merge()
-* const verboseGroup = group("Verbosity", object({
-*   verbose: option("-v", "--verbose"),
-*   quiet: option("-q", "--quiet")
-* }));
-* ```
-*
-* @template TValue The value type of the wrapped parser.
-* @template TState The state type of the wrapped parser.
-* @param label A descriptive label for this parser group, used for
-*              documentation and help text organization.
-* @param parser The parser to wrap with a group label.
-* @returns A new parser that behaves identically to the input parser
-*          but generates documentation within a labeled section.
-* @since 0.4.0
-*/
-function group(label, parser) {
+function group(label, parser, options = {}) {
 	return {
 		$mode: parser.$mode,
 		$valueType: parser.$valueType,
 		$stateType: parser.$stateType,
 		priority: parser.priority,
-		usage: parser.usage,
+		usage: applyHiddenToUsage(parser.usage, options.hidden),
 		initialState: parser.initialState,
 		parse: (context) => parser.parse(context),
 		complete: (state) => parser.complete(state),
-		suggest: (context, prefix) => parser.suggest(context, prefix),
+		suggest: (context, prefix) => {
+			if (options.hidden === true) return require_mode_dispatch.dispatchIterableByMode(parser.$mode, function* () {}, async function* () {});
+			return parser.suggest(context, prefix);
+		},
 		getDocFragments: (state, defaultValue) => {
 			const { brief, description, footer, fragments } = parser.getDocFragments(state, defaultValue);
+			const hiddenAwareFragments = applyHiddenToDocFragments(fragments, options.hidden);
 			const allEntries = [];
 			const titledSections = [];
-			for (const fragment of fragments) if (fragment.type === "entry") allEntries.push(fragment);
+			for (const fragment of hiddenAwareFragments) if (fragment.type === "entry") allEntries.push(fragment);
 			else if (fragment.type === "section") if (fragment.title) titledSections.push(fragment);
 			else allEntries.push(...fragment.entries);
 			const initialFragments = parser.getDocFragments({

package/dist/constructs.d.cts

@@ -1,4 +1,5 @@
 import { Message } from "./message.cjs";
+import { HiddenVisibility } from "./usage.cjs";
 import { CombineModes, InferValue, Mode, Parser, ParserResult } from "./parser.cjs";
 
 //#region src/constructs.d.ts
@@ -626,6 +627,11 @@ interface ObjectOptions {
    * @since 0.7.0
    */
   readonly allowDuplicates?: boolean;
+  /**
+   * Controls visibility of all terms emitted by this object parser.
+   * @since 1.0.0
+   */
+  readonly hidden?: HiddenVisibility;
 }
 /**
  * Options for customizing error messages in the {@link object} parser.
@@ -799,6 +805,11 @@ interface MergeOptions {
    * @since 0.7.0
    */
   readonly allowDuplicates?: boolean;
+  /**
+   * Controls visibility of all terms emitted by this merged parser.
+   * @since 1.0.0
+   */
+  readonly hidden?: HiddenVisibility;
 }
 /**
  * Merges multiple {@link object} parsers into a single {@link object} parser.
@@ -1387,11 +1398,22 @@ declare function concat<MA extends Mode, MB extends Mode, MC extends Mode, MD ex
  * @param label A descriptive label for this parser group, used for
  *              documentation and help text organization.
  * @param parser The parser to wrap with a group label.
+ * @param options Optional visibility controls for the wrapped parser terms.
  * @returns A new parser that behaves identically to the input parser
  *          but generates documentation within a labeled section.
  * @since 0.4.0
  */
-declare function group<M extends Mode, TValue, TState>(label: string, parser: Parser<M, TValue, TState>): Parser<M, TValue, TState>;
+/**
+ * Options for the {@link group} parser wrapper.
+ * @since 1.0.0
+ */
+interface GroupOptions {
+  /**
+   * Controls visibility of all terms emitted by this group.
+   */
+  readonly hidden?: HiddenVisibility;
+}
+declare function group<M extends Mode, TValue, TState>(label: string, parser: Parser<M, TValue, TState>, options?: GroupOptions): Parser<M, TValue, TState>;
 /**
  * Tagged union type representing which branch is selected.
  * Uses tagged union to avoid collision with discriminator values.
@@ -1476,4 +1498,4 @@ declare function conditional<TDiscriminator extends string, TBranches extends {
  */
 declare function conditional<TDiscriminator extends string, TBranches extends { [K in TDiscriminator]: Parser<Mode, unknown, unknown> }, TDefault extends Parser<Mode, unknown, unknown>, TD extends Parser<Mode, TDiscriminator, unknown>>(discriminator: TD, branches: TBranches, defaultBranch: TDefault, options?: ConditionalOptions): Parser<CombineModes<readonly [ExtractMode<TD>, ExtractMode<TDefault>, ...{ [K in keyof TBranches]: ExtractMode<TBranches[K]> }[keyof TBranches][]]>, ConditionalResultWithDefault<TDiscriminator, TBranches, TDefault>, ConditionalState<TDiscriminator>>;
 //#endregion
-export { ConditionalErrorOptions, ConditionalOptions, DuplicateOptionError, LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, NoMatchContext, ObjectErrorOptions, ObjectOptions, OrErrorOptions, OrOptions, TupleOptions, concat, conditional, group, longestMatch, merge, object, or, tuple };
+export { ConditionalErrorOptions, ConditionalOptions, DuplicateOptionError, GroupOptions, LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, NoMatchContext, ObjectErrorOptions, ObjectOptions, OrErrorOptions, OrOptions, TupleOptions, concat, conditional, group, longestMatch, merge, object, or, tuple };

package/dist/constructs.d.ts

@@ -1,4 +1,5 @@
 import { Message } from "./message.js";
+import { HiddenVisibility } from "./usage.js";
 import { CombineModes, InferValue, Mode, Parser, ParserResult } from "./parser.js";
 
 //#region src/constructs.d.ts
@@ -626,6 +627,11 @@ interface ObjectOptions {
    * @since 0.7.0
    */
   readonly allowDuplicates?: boolean;
+  /**
+   * Controls visibility of all terms emitted by this object parser.
+   * @since 1.0.0
+   */
+  readonly hidden?: HiddenVisibility;
 }
 /**
  * Options for customizing error messages in the {@link object} parser.
@@ -799,6 +805,11 @@ interface MergeOptions {
    * @since 0.7.0
    */
   readonly allowDuplicates?: boolean;
+  /**
+   * Controls visibility of all terms emitted by this merged parser.
+   * @since 1.0.0
+   */
+  readonly hidden?: HiddenVisibility;
 }
 /**
  * Merges multiple {@link object} parsers into a single {@link object} parser.
@@ -1387,11 +1398,22 @@ declare function concat<MA extends Mode, MB extends Mode, MC extends Mode, MD ex
  * @param label A descriptive label for this parser group, used for
  *              documentation and help text organization.
  * @param parser The parser to wrap with a group label.
+ * @param options Optional visibility controls for the wrapped parser terms.
  * @returns A new parser that behaves identically to the input parser
  *          but generates documentation within a labeled section.
  * @since 0.4.0
  */
-declare function group<M extends Mode, TValue, TState>(label: string, parser: Parser<M, TValue, TState>): Parser<M, TValue, TState>;
+/**
+ * Options for the {@link group} parser wrapper.
+ * @since 1.0.0
+ */
+interface GroupOptions {
+  /**
+   * Controls visibility of all terms emitted by this group.
+   */
+  readonly hidden?: HiddenVisibility;
+}
+declare function group<M extends Mode, TValue, TState>(label: string, parser: Parser<M, TValue, TState>, options?: GroupOptions): Parser<M, TValue, TState>;
 /**
  * Tagged union type representing which branch is selected.
  * Uses tagged union to avoid collision with discriminator values.
@@ -1476,4 +1498,4 @@ declare function conditional<TDiscriminator extends string, TBranches extends {
  */
 declare function conditional<TDiscriminator extends string, TBranches extends { [K in TDiscriminator]: Parser<Mode, unknown, unknown> }, TDefault extends Parser<Mode, unknown, unknown>, TD extends Parser<Mode, TDiscriminator, unknown>>(discriminator: TD, branches: TBranches, defaultBranch: TDefault, options?: ConditionalOptions): Parser<CombineModes<readonly [ExtractMode<TD>, ExtractMode<TDefault>, ...{ [K in keyof TBranches]: ExtractMode<TBranches[K]> }[keyof TBranches][]]>, ConditionalResultWithDefault<TDiscriminator, TBranches, TDefault>, ConditionalState<TDiscriminator>>;
 //#endregion
-export { ConditionalErrorOptions, ConditionalOptions, DuplicateOptionError, LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, NoMatchContext, ObjectErrorOptions, ObjectOptions, OrErrorOptions, OrOptions, TupleOptions, concat, conditional, group, longestMatch, merge, object, or, tuple };
+export { ConditionalErrorOptions, ConditionalOptions, DuplicateOptionError, GroupOptions, LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, NoMatchContext, ObjectErrorOptions, ObjectOptions, OrErrorOptions, OrOptions, TupleOptions, concat, conditional, group, longestMatch, merge, object, or, tuple };

package/dist/constructs.js

@@ -1,7 +1,7 @@
 import { message, optionName, text, values } from "./message.js";
 import { DependencyRegistry, dependencyId, isDeferredParseState, isDependencySourceState, isPendingDependencySourceState, isWrappedDependencySource, parseWithDependency, wrappedDependencySourceMarker } from "./dependency.js";
 import { dispatchByMode, dispatchIterableByMode } from "./mode-dispatch.js";
-import { extractArgumentMetavars, extractCommandNames, extractOptionNames } from "./usage.js";
+import { extractArgumentMetavars, extractCommandNames, extractOptionNames, isDocHidden, mergeHidden } from "./usage.js";
 import { DEFAULT_FIND_SIMILAR_OPTIONS, createErrorWithSuggestions, createSuggestionMessage, deduplicateSuggestions, findSimilar } from "./suggestion.js";
 import { collectLeadingCandidates } from "./usage-internals.js";
 
@@ -19,6 +19,60 @@ function createUnexpectedInputErrorWithScopedSuggestions(baseError, invalidInput
 		...suggestionMsg
 	] : baseError;
 }
+function applyHiddenToUsageTerm(term, hidden) {
+	if (hidden == null) return term;
+	if (term.type === "optional") return {
+		type: "optional",
+		terms: applyHiddenToUsage(term.terms, hidden)
+	};
+	if (term.type === "multiple") return {
+		type: "multiple",
+		terms: applyHiddenToUsage(term.terms, hidden),
+		min: term.min
+	};
+	if (term.type === "exclusive") return {
+		type: "exclusive",
+		terms: term.terms.map((u) => applyHiddenToUsage(u, hidden))
+	};
+	if (term.type === "argument" || term.type === "option" || term.type === "command" || term.type === "passthrough") return {
+		...term,
+		hidden: mergeHidden(term.hidden, hidden)
+	};
+	return term;
+}
+function applyHiddenToUsage(usage, hidden) {
+	if (hidden == null) return usage;
+	return usage.map((term) => applyHiddenToUsageTerm(term, hidden));
+}
+function applyHiddenToDocEntry(entry, hidden) {
+	const mergedTerm = applyHiddenToUsageTerm(entry.term, hidden);
+	if ((mergedTerm.type === "argument" || mergedTerm.type === "option" || mergedTerm.type === "command" || mergedTerm.type === "passthrough") && isDocHidden(mergedTerm.hidden)) return void 0;
+	return {
+		...entry,
+		term: mergedTerm
+	};
+}
+function applyHiddenToDocFragments(fragments, hidden) {
+	if (hidden == null) return fragments;
+	const result = [];
+	for (const fragment of fragments) {
+		if (fragment.type === "entry") {
+			const entry = applyHiddenToDocEntry(fragment, hidden);
+			if (entry != null) result.push({
+				...entry,
+				type: "entry"
+			});
+			continue;
+		}
+		const entries = fragment.entries.map((entry) => applyHiddenToDocEntry(entry, hidden)).filter((entry) => entry != null);
+		result.push({
+			type: "section",
+			title: fragment.title,
+			entries
+		});
+	}
+	return result;
+}
 /**
 * Checks if the given token is an option name that requires a value
 * (i.e., has a metavar) within the given usage terms.
@@ -919,7 +973,7 @@ function object(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 		$valueType: [],
 		$stateType: [],
 		priority: Math.max(...parserKeys.map((k) => parsers[k].priority)),
-		usage: parserPairs.flatMap(([_, p]) => p.usage),
+		usage: applyHiddenToUsage(parserPairs.flatMap(([_, p]) => p.usage), options.hidden),
 		initialState,
 		parse(context) {
 			return dispatchByMode(combinedMode, () => parseSync(context), () => parseAsync(context));
@@ -1028,6 +1082,7 @@ function object(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 			});
 		},
 		suggest(context, prefix) {
+			if (options.hidden === true) return dispatchIterableByMode(combinedMode, function* () {}, async function* () {});
 			return dispatchIterableByMode(combinedMode, () => {
 				const syncParserPairs = parserPairs;
 				return suggestObjectSync(context, prefix, syncParserPairs);
@@ -1041,9 +1096,10 @@ function object(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 				};
 				return p.getDocFragments(fieldState, defaultValue?.[field]).fragments;
 			});
-			const entries = fragments.filter((d) => d.type === "entry");
+			const hiddenAwareFragments = applyHiddenToDocFragments(fragments, options.hidden);
+			const entries = hiddenAwareFragments.filter((d) => d.type === "entry");
 			const sections = [];
-			for (const fragment of fragments) {
+			for (const fragment of hiddenAwareFragments) {
 				if (fragment.type !== "section") continue;
 				if (fragment.title == null) entries.push(...fragment.entries);
 				else sections.push(fragment);
@@ -1518,7 +1574,7 @@ function merge(...args) {
 		$valueType: [],
 		$stateType: [],
 		priority: Math.max(...parsers.map((p) => p.priority)),
-		usage: parsers.flatMap((p) => p.usage),
+		usage: applyHiddenToUsage(parsers.flatMap((p) => p.usage), options.hidden),
 		initialState,
 		parse(context) {
 			if (isAsync) return parseAsync(context);
@@ -1572,6 +1628,7 @@ function merge(...args) {
 			})();
 		},
 		suggest(context, prefix) {
+			if (options.hidden === true) return dispatchIterableByMode(combinedMode, function* () {}, async function* () {});
 			const extractState = (p, i) => {
 				if (p.initialState === void 0) {
 					const key = `__parser_${i}`;
@@ -1638,9 +1695,10 @@ function merge(...args) {
 				footer ??= docFragments.footer;
 				return docFragments.fragments;
 			});
-			const entries = fragments.filter((f) => f.type === "entry");
+			const hiddenAwareFragments = applyHiddenToDocFragments(fragments, options.hidden);
+			const entries = hiddenAwareFragments.filter((f) => f.type === "entry");
 			const sections = [];
-			for (const fragment of fragments) {
+			for (const fragment of hiddenAwareFragments) {
 				if (fragment.type !== "section") continue;
 				if (fragment.title == null) entries.push(...fragment.entries);
 				else sections.push(fragment);
@@ -1915,64 +1973,26 @@ function concat(...parsers) {
 		}
 	};
 }
-/**
-* Wraps a parser with a group label for documentation purposes.
-*
-* The `group()` function is a documentation-only wrapper that applies a label
-* to any parser for help text organization. This allows you to use clean code
-* structure with combinators like {@link merge} while maintaining well-organized
-* help text through group labeling.
-*
-* The wrapped parser has identical parsing behavior but generates documentation
-* fragments wrapped in a labeled section. This is particularly useful when
-* combining parsers using {@link merge}—you can wrap the merged result with
-* `group()` to add a section header in help output.
-*
-* @example
-* ```typescript
-* const apiOptions = merge(
-*   object({ endpoint: option("--endpoint", string()) }),
-*   object({ timeout: option("--timeout", integer()) })
-* );
-*
-* const groupedApiOptions = group("API Options", apiOptions);
-* // Now produces a labeled "API Options" section in help text
-* ```
-*
-* @example
-* ```typescript
-* // Can be used with any parser, not just merge()
-* const verboseGroup = group("Verbosity", object({
-*   verbose: option("-v", "--verbose"),
-*   quiet: option("-q", "--quiet")
-* }));
-* ```
-*
-* @template TValue The value type of the wrapped parser.
-* @template TState The state type of the wrapped parser.
-* @param label A descriptive label for this parser group, used for
-*              documentation and help text organization.
-* @param parser The parser to wrap with a group label.
-* @returns A new parser that behaves identically to the input parser
-*          but generates documentation within a labeled section.
-* @since 0.4.0
-*/
-function group(label, parser) {
+function group(label, parser, options = {}) {
 	return {
 		$mode: parser.$mode,
 		$valueType: parser.$valueType,
 		$stateType: parser.$stateType,
 		priority: parser.priority,
-		usage: parser.usage,
+		usage: applyHiddenToUsage(parser.usage, options.hidden),
 		initialState: parser.initialState,
 		parse: (context) => parser.parse(context),
 		complete: (state) => parser.complete(state),
-		suggest: (context, prefix) => parser.suggest(context, prefix),
+		suggest: (context, prefix) => {
+			if (options.hidden === true) return dispatchIterableByMode(parser.$mode, function* () {}, async function* () {});
+			return parser.suggest(context, prefix);
+		},
 		getDocFragments: (state, defaultValue) => {
 			const { brief, description, footer, fragments } = parser.getDocFragments(state, defaultValue);
+			const hiddenAwareFragments = applyHiddenToDocFragments(fragments, options.hidden);
 			const allEntries = [];
 			const titledSections = [];
-			for (const fragment of fragments) if (fragment.type === "entry") allEntries.push(fragment);
+			for (const fragment of hiddenAwareFragments) if (fragment.type === "entry") allEntries.push(fragment);
 			else if (fragment.type === "section") if (fragment.title) titledSections.push(fragment);
 			else allEntries.push(...fragment.entries);
 			const initialFragments = parser.getDocFragments({

package/dist/doc.cjs

@@ -17,12 +17,22 @@ function classifySection(section) {
 	return 2;
 }
 /**
+* Scores a section for the default smart sort.  Untitled sections receive
+* a bonus of `-1` so that the main (untitled) section appears before titled
+* sections of a similar classification.
+*/
+function scoreSection(section) {
+	return classifySection(section) + (section.title == null ? -1 : 0);
+}
+/**
 * The default section comparator: command-only sections come first, then
-* mixed sections, then option/argument-only sections.  Sections with the
+* mixed sections, then option/argument-only sections.  Untitled sections
+* receive a slight priority boost so the main (untitled) section appears
+* before titled sections of a similar classification.  Sections with the
 * same score preserve their original relative order (stable sort).
 */
 function defaultSectionOrder(a, b) {
-	return classifySection(a) - classifySection(b);
+	return scoreSection(a) - scoreSection(b);
 }
 /**
 * Formats a documentation page into a human-readable string.
@@ -109,18 +119,37 @@ function formatDocPage(programName, page, options = {}) {
 				optionsSeparator: ", ",
 				maxWidth: options.maxWidth == null ? void 0 : options.maxWidth - termIndent
 			});
-			let description = entry.description == null ? "" : require_message.formatMessage(entry.description, {
+			const descColumnWidth = options.maxWidth == null ? void 0 : options.maxWidth - termIndent - termWidth - 2;
+			const termVisibleWidth = lastLineVisibleLength(term);
+			const extraTermOffset = descColumnWidth != null ? Math.max(0, termVisibleWidth - termWidth) : 0;
+			const currentExtraOffset = () => description.includes("\n") ? 0 : extraTermOffset;
+			const descFormatOptions = {
 				colors: options.colors,
 				quotes: !options.colors,
-				maxWidth: options.maxWidth == null ? void 0 : options.maxWidth - termIndent - termWidth - 2
-			});
+				maxWidth: descColumnWidth,
+				startWidth: extraTermOffset > 0 ? extraTermOffset : void 0
+			};
+			let description = entry.description == null ? "" : require_message.formatMessage(entry.description, descFormatOptions);
 			if (options.showDefault && entry.default != null) {
 				const prefix = typeof options.showDefault === "object" ? options.showDefault.prefix ?? " [" : " [";
 				const suffix = typeof options.showDefault === "object" ? options.showDefault.suffix ?? "]" : "]";
-				const defaultText = `${prefix}${require_message.formatMessage(entry.default, {
+				let defaultStartWidth;
+				if (descColumnWidth != null) {
+					const lastW = lastLineVisibleLength(description);
+					const effectiveLastW = lastW + currentExtraOffset();
+					if (effectiveLastW + prefix.length >= descColumnWidth) {
+						description += "\n";
+						defaultStartWidth = prefix.length;
+					} else defaultStartWidth = effectiveLastW + prefix.length;
+				}
+				const defaultFormatOptions = {
 					colors: options.colors ? { resetSuffix: "\x1B[2m" } : false,
-					quotes: !options.colors
-				})}${suffix}`;
+					quotes: !options.colors,
+					maxWidth: descColumnWidth == null ? void 0 : descColumnWidth - suffix.length,
+					startWidth: defaultStartWidth
+				};
+				const defaultContent = require_message.formatMessage(entry.default, defaultFormatOptions);
+				const defaultText = `${prefix}${defaultContent}${suffix}`;
 				const formattedDefault = options.colors ? `\x1b[2m${defaultText}\x1b[0m` : defaultText;
 				description += formattedDefault;
 			}
@@ -145,10 +174,23 @@ function formatDocPage(programName, page, options = {}) {
 					}
 					if (truncated) truncatedTerms = [...terms.slice(0, cutIndex), require_message.text(", ...")];
 				}
-				const choicesDisplay = require_message.formatMessage(truncatedTerms, {
+				let choicesStartWidth;
+				if (descColumnWidth != null) {
+					const lastW = lastLineVisibleLength(description);
+					const effectiveLastW = lastW + currentExtraOffset();
+					const prefixLabelLen = prefix.length + label.length;
+					if (effectiveLastW + prefixLabelLen >= descColumnWidth) {
+						description += "\n";
+						choicesStartWidth = prefixLabelLen;
+					} else choicesStartWidth = effectiveLastW + prefixLabelLen;
+				}
+				const choicesFormatOptions = {
 					colors: options.colors ? { resetSuffix: "\x1B[2m" } : false,
-					quotes: false
-				});
+					quotes: false,
+					maxWidth: descColumnWidth == null ? void 0 : descColumnWidth - suffix.length,
+					startWidth: choicesStartWidth
+				};
+				const choicesDisplay = require_message.formatMessage(truncatedTerms, choicesFormatOptions);
 				const choicesText = `${prefix}${label}${choicesDisplay}${suffix}`;
 				const formattedChoices = options.colors ? `\x1b[2m${choicesText}\x1b[0m` : choicesText;
 				description += formattedChoices;
@@ -205,12 +247,17 @@ function formatDocPage(programName, page, options = {}) {
 function indentLines(text$1, indent) {
 	return text$1.split("\n").join("\n" + " ".repeat(indent));
 }
+const ansiEscapeCodeRegex = /\x1B\[[0-9;]*[a-zA-Z]/g;
 function ansiAwareRightPad(text$1, length, char = " ") {
-	const ansiEscapeCodeRegex = /\x1B\[[0-9;]*[a-zA-Z]/g;
 	const strippedText = text$1.replace(ansiEscapeCodeRegex, "");
 	if (strippedText.length >= length) return text$1;
 	return text$1 + char.repeat(length - strippedText.length);
 }
+function lastLineVisibleLength(text$1) {
+	const lastNewline = text$1.lastIndexOf("\n");
+	const lastLine = lastNewline === -1 ? text$1 : text$1.slice(lastNewline + 1);
+	return lastLine.replace(ansiEscapeCodeRegex, "").length;
+}
 
 //#endregion
 exports.formatDocPage = formatDocPage;