@optique/core 1.0.0-dev.908 → 1.0.0

package/dist/displaywidth.cjs

@@ -0,0 +1,44 @@
+
+//#region src/displaywidth.ts
+const ansiRegex = /\x1B(?:\[[0-9;:]*[@-~]|\][^\x1B\x07]*(?:\x1B\\|\x07))/g;
+const segmenter = new Intl.Segmenter(void 0, { granularity: "grapheme" });
+/**
+* Computes the terminal display width of a string, accounting for
+* East Asian wide characters, combining marks, emoji, and ANSI escapes.
+*
+* @param text The string to measure.
+* @returns The number of terminal columns the string occupies.
+* @internal
+*/
+function getDisplayWidth(text) {
+	const stripped = text.replace(ansiRegex, "");
+	let width = 0;
+	for (const { segment } of segmenter.segment(stripped)) width += graphemeWidth(segment);
+	return width;
+}
+const zeroWidthRegex = /^[\p{Cf}\p{Mn}\p{Me}]+$/u;
+const emojiPresentationRegex = /\p{Emoji_Presentation}/u;
+const emojiWithVS16Regex = /\p{Emoji}\uFE0F/u;
+const keycapEmojiRegex = /^[#*0-9]\uFE0F?\u20E3$/u;
+const textPresentationRegex = /\uFE0E/u;
+const regionalIndicatorRegex = /[\u{1F1E6}-\u{1F1FF}]/u;
+function graphemeWidth(grapheme) {
+	const cp = grapheme.codePointAt(0);
+	if (cp == null) return 0;
+	if (cp === 9) return 1;
+	if (cp < 32 || cp >= 127 && cp < 160) return 0;
+	if (zeroWidthRegex.test(grapheme)) return 0;
+	if (keycapEmojiRegex.test(grapheme) || !textPresentationRegex.test(grapheme) && (emojiPresentationRegex.test(grapheme) || emojiWithVS16Regex.test(grapheme) || regionalIndicatorRegex.test(grapheme))) return 2;
+	let width = isEastAsianWide(cp) ? 2 : 1;
+	for (let i = cp > 65535 ? 2 : 1; i < grapheme.length; i++) {
+		const c = grapheme.charCodeAt(i);
+		if (c === 65438 || c === 65439) width += 1;
+	}
+	return width;
+}
+function isEastAsianWide(cp) {
+	return cp >= 4352 && cp <= 4447 || cp >= 9001 && cp <= 9002 || cp >= 9776 && cp <= 9783 || cp >= 9866 && cp <= 9871 || cp >= 11904 && cp <= 12255 || cp >= 12272 && cp <= 12350 || cp >= 12353 && cp <= 40959 || cp >= 40960 && cp <= 42191 || cp >= 43360 && cp <= 43391 || cp >= 44032 && cp <= 55215 || cp >= 63744 && cp <= 64255 || cp >= 65040 && cp <= 65049 || cp >= 65072 && cp <= 65135 || cp >= 65281 && cp <= 65376 || cp >= 65504 && cp <= 65510 || cp >= 94176 && cp <= 101759 || cp >= 110576 && cp <= 111359 || cp >= 127488 && cp <= 127490 || cp >= 127504 && cp <= 127547 || cp >= 127552 && cp <= 127560 || cp >= 127568 && cp <= 127569 || cp >= 127584 && cp <= 127589 || cp >= 131072 && cp <= 196605 || cp >= 196608 && cp <= 262141;
+}
+
+//#endregion
+exports.getDisplayWidth = getDisplayWidth;

package/dist/displaywidth.js

@@ -0,0 +1,43 @@
+//#region src/displaywidth.ts
+const ansiRegex = /\x1B(?:\[[0-9;:]*[@-~]|\][^\x1B\x07]*(?:\x1B\\|\x07))/g;
+const segmenter = new Intl.Segmenter(void 0, { granularity: "grapheme" });
+/**
+* Computes the terminal display width of a string, accounting for
+* East Asian wide characters, combining marks, emoji, and ANSI escapes.
+*
+* @param text The string to measure.
+* @returns The number of terminal columns the string occupies.
+* @internal
+*/
+function getDisplayWidth(text) {
+	const stripped = text.replace(ansiRegex, "");
+	let width = 0;
+	for (const { segment } of segmenter.segment(stripped)) width += graphemeWidth(segment);
+	return width;
+}
+const zeroWidthRegex = /^[\p{Cf}\p{Mn}\p{Me}]+$/u;
+const emojiPresentationRegex = /\p{Emoji_Presentation}/u;
+const emojiWithVS16Regex = /\p{Emoji}\uFE0F/u;
+const keycapEmojiRegex = /^[#*0-9]\uFE0F?\u20E3$/u;
+const textPresentationRegex = /\uFE0E/u;
+const regionalIndicatorRegex = /[\u{1F1E6}-\u{1F1FF}]/u;
+function graphemeWidth(grapheme) {
+	const cp = grapheme.codePointAt(0);
+	if (cp == null) return 0;
+	if (cp === 9) return 1;
+	if (cp < 32 || cp >= 127 && cp < 160) return 0;
+	if (zeroWidthRegex.test(grapheme)) return 0;
+	if (keycapEmojiRegex.test(grapheme) || !textPresentationRegex.test(grapheme) && (emojiPresentationRegex.test(grapheme) || emojiWithVS16Regex.test(grapheme) || regionalIndicatorRegex.test(grapheme))) return 2;
+	let width = isEastAsianWide(cp) ? 2 : 1;
+	for (let i = cp > 65535 ? 2 : 1; i < grapheme.length; i++) {
+		const c = grapheme.charCodeAt(i);
+		if (c === 65438 || c === 65439) width += 1;
+	}
+	return width;
+}
+function isEastAsianWide(cp) {
+	return cp >= 4352 && cp <= 4447 || cp >= 9001 && cp <= 9002 || cp >= 9776 && cp <= 9783 || cp >= 9866 && cp <= 9871 || cp >= 11904 && cp <= 12255 || cp >= 12272 && cp <= 12350 || cp >= 12353 && cp <= 40959 || cp >= 40960 && cp <= 42191 || cp >= 43360 && cp <= 43391 || cp >= 44032 && cp <= 55215 || cp >= 63744 && cp <= 64255 || cp >= 65040 && cp <= 65049 || cp >= 65072 && cp <= 65135 || cp >= 65281 && cp <= 65376 || cp >= 65504 && cp <= 65510 || cp >= 94176 && cp <= 101759 || cp >= 110576 && cp <= 111359 || cp >= 127488 && cp <= 127490 || cp >= 127504 && cp <= 127547 || cp >= 127552 && cp <= 127560 || cp >= 127568 && cp <= 127569 || cp >= 127584 && cp <= 127589 || cp >= 131072 && cp <= 196605 || cp >= 196608 && cp <= 262141;
+}
+
+//#endregion
+export { getDisplayWidth };

package/dist/doc.cjs

@@ -1,8 +1,145 @@
+const require_displaywidth = require('./displaywidth.cjs');
 const require_message = require('./message.cjs');
+const require_validate = require('./validate.cjs');
 const require_usage = require('./usage.cjs');
 
 //#region src/doc.ts
 /**
+* Returns whether a doc entry's term is hidden from documentation.
+* Only term types with a `hidden` field (argument, option, command,
+* passthrough) are checked; other types always return `false`.
+*
+* @param entry The doc entry to check.
+* @returns `true` if the entry should be hidden from documentation.
+* @since 1.0.0
+*/
+function isDocEntryHidden(entry) {
+	const term = entry.term;
+	if (term.type === "argument" || term.type === "option" || term.type === "command" || term.type === "passthrough") return require_usage.isDocHidden(term.hidden);
+	return false;
+}
+function getDocEntryKey(entry) {
+	const term = entry.term;
+	switch (term.type) {
+		case "command": return `command:${term.name}`;
+		case "option": return `option:${[...term.names].sort().join(",")}:${term.metavar ?? ""}`;
+		case "argument": return `argument:${term.metavar}`;
+		default: return JSON.stringify(term);
+	}
+}
+/**
+* Removes duplicate {@link DocEntry} values that share the same surface
+* syntax (same term type and identifying names).  Doc-hidden entries are
+* filtered out first so they cannot influence the ordering of visible
+* entries.  Among the remaining visible entries, the first occurrence is
+* kept and later duplicates are discarded.
+*
+* Positional argument entries are never deduplicated because they are
+* distinguished by position, not by metavar, and {@link DocEntry} does
+* not carry position information.
+*
+* @param entries The entries to deduplicate.
+* @returns A new array with hidden entries removed and duplicates
+*   collapsed, preserving insertion order of visible entries.
+* @since 1.0.0
+*/
+function deduplicateDocEntries(entries) {
+	const seen = /* @__PURE__ */ new Set();
+	const result = [];
+	for (const entry of entries) {
+		if (isDocEntryHidden(entry)) continue;
+		if (entry.term.type === "argument") {
+			result.push(entry);
+			continue;
+		}
+		const key = getDocEntryKey(entry);
+		if (!seen.has(key)) {
+			seen.add(key);
+			result.push(entry);
+		}
+	}
+	return result;
+}
+/**
+* Removes duplicate entries from a list of {@link DocFragment} values.
+* Entry-type fragments are deduplicated by their surface syntax key.
+* Section-type fragments have their entries deduplicated internally.
+*
+* @param fragments The fragments to deduplicate.
+* @returns A new array with duplicate entries removed.
+* @since 1.0.0
+*/
+function deduplicateDocFragments(fragments) {
+	const untitledSeen = /* @__PURE__ */ new Set();
+	const titledSectionMap = /* @__PURE__ */ new Map();
+	const titledSectionPositioned = /* @__PURE__ */ new Set();
+	const slots = [];
+	for (const fragment of fragments) if (fragment.type === "entry") {
+		if (isDocEntryHidden(fragment)) continue;
+		if (fragment.term.type === "argument") slots.push(fragment);
+		else {
+			const key = getDocEntryKey(fragment);
+			if (!untitledSeen.has(key)) {
+				untitledSeen.add(key);
+				slots.push(fragment);
+			}
+		}
+	} else if (fragment.title == null) {
+		const dedupedEntries = [];
+		for (const entry of fragment.entries) {
+			if (isDocEntryHidden(entry)) continue;
+			if (entry.term.type === "argument") {
+				dedupedEntries.push(entry);
+				continue;
+			}
+			const key = getDocEntryKey(entry);
+			if (!untitledSeen.has(key)) {
+				untitledSeen.add(key);
+				dedupedEntries.push(entry);
+			}
+		}
+		if (dedupedEntries.length > 0) slots.push({
+			...fragment,
+			type: "section",
+			entries: dedupedEntries
+		});
+	} else {
+		if (!titledSectionMap.has(fragment.title)) titledSectionMap.set(fragment.title, []);
+		if (!titledSectionPositioned.has(fragment.title) && fragment.entries.some((e) => !isDocEntryHidden(e))) {
+			titledSectionPositioned.add(fragment.title);
+			slots.push(fragment.title);
+		}
+		titledSectionMap.get(fragment.title).push(...fragment.entries);
+	}
+	const result = [];
+	for (const slot of slots) if (typeof slot === "string") {
+		const entries = deduplicateDocEntries(titledSectionMap.get(slot));
+		if (entries.length > 0) result.push({
+			type: "section",
+			title: slot,
+			entries
+		});
+	} else result.push(slot);
+	return result;
+}
+/**
+* Creates a deep clone of a {@link DocEntry}.  The `term` is cloned via
+* {@link cloneUsageTerm}, and `description`, `default`, and `choices`
+* messages are cloned via {@link cloneMessage}.
+*
+* @param entry The documentation entry to clone.
+* @returns A structurally equal but referentially distinct copy.
+* @since 1.0.0
+*/
+function cloneDocEntry(entry) {
+	return {
+		term: require_usage.cloneUsageTerm(entry.term),
+		...entry.description != null && { description: require_message.cloneMessage(entry.description) },
+		...entry.default != null && { default: require_message.cloneMessage(entry.default) },
+		...entry.choices != null && { choices: require_message.cloneMessage(entry.choices) }
+	};
+}
+/**
 * Classifies a {@link DocSection} by its content type for use in the
 * default smart sort.
 *
@@ -47,6 +184,13 @@ function defaultSectionOrder(a, b) {
 * @param page The documentation page to format
 * @param options Formatting options to customize the output
 * @returns A formatted string representation of the documentation page
+* @throws {TypeError} If `programName` is not a string, is empty,
+* whitespace-only, or contains control characters, if any non-empty
+* section's title is not a string, is empty, whitespace-only, or contains
+* control characters, or if `maxWidth` is not a finite integer.
+* @throws {RangeError} If any entry needs a description column and `maxWidth`
+* is too small to fit the minimum layout (less than `termIndent + 4`), or if
+* `showChoices.maxItems` is less than `1`.
 *
 * @example
 * ```typescript
@@ -67,10 +211,70 @@ function defaultSectionOrder(a, b) {
 * ```
 */
 function formatDocPage(programName, page, options = {}) {
+	require_validate.validateProgramName(programName);
 	const termIndent = options.termIndent ?? 2;
 	const termWidth = options.termWidth ?? 26;
+	if (options.maxWidth != null && (!Number.isFinite(options.maxWidth) || !Number.isInteger(options.maxWidth))) throw new TypeError(`maxWidth must be a finite integer, got ${options.maxWidth}.`);
+	const filteredSections = page.sections.map((s) => ({
+		...s,
+		entries: s.entries.filter((e) => {
+			const rendered = require_usage.formatUsageTerm(e.term, { context: "doc" });
+			return rendered.trim() !== "";
+		})
+	}));
+	page = {
+		...page,
+		sections: filteredSections
+	};
+	if (typeof options.showChoices === "object" && options.showChoices.maxItems != null) {
+		const maxItems = options.showChoices.maxItems;
+		if (maxItems < 1) throw new RangeError(`showChoices.maxItems must be at least 1, but got ${maxItems}.`);
+	}
+	const hasContent = (msg) => Array.isArray(msg) && msg.length > 0;
+	if (options.maxWidth != null) {
+		const hasEntries = page.sections.some((s) => s.entries.length > 0);
+		const needsDescColumn = hasEntries && page.sections.some((s) => s.entries.some((e) => hasContent(e.description) || options.showDefault && hasContent(e.default) || options.showChoices && hasContent(e.choices)));
+		let minDescWidth = 1;
+		if (needsDescColumn) {
+			if (options.showDefault && page.sections.some((s) => s.entries.some((e) => hasContent(e.default)))) {
+				const prefix = typeof options.showDefault === "object" ? options.showDefault.prefix ?? " [" : " [";
+				minDescWidth = Math.max(minDescWidth, require_displaywidth.getDisplayWidth(prefix));
+			}
+			if (options.showChoices && page.sections.some((s) => s.entries.some((e) => hasContent(e.choices)))) {
+				const prefix = typeof options.showChoices === "object" ? options.showChoices.prefix ?? " (" : " (";
+				const label = typeof options.showChoices === "object" ? options.showChoices.label ?? "choices: " : "choices: ";
+				minDescWidth = Math.max(minDescWidth, require_displaywidth.getDisplayWidth(prefix) + require_displaywidth.getDisplayWidth(label));
+			}
+		}
+		const splitEntryMin = termIndent + 2 + Math.max(2, 2 * minDescWidth - 1);
+		const fixedEntryMin = termIndent + 2 + termWidth + minDescWidth;
+		const entryMin = needsDescColumn ? Math.min(splitEntryMin, fixedEntryMin) : hasEntries ? termIndent + 1 : 1;
+		const programNameWidth = require_displaywidth.getDisplayWidth(programName);
+		const usageMin = page.usage != null ? 7 + Math.max(programNameWidth, Math.min(maxVisibleAtomicWidth(page.usage), programNameWidth + 7)) : 1;
+		let sectionMin = 1;
+		if (hasContent(page.examples)) sectionMin = Math.max(sectionMin, 9);
+		if (hasContent(page.author)) sectionMin = Math.max(sectionMin, 7);
+		if (hasContent(page.bugs)) sectionMin = Math.max(sectionMin, 5);
+		const minWidth = Math.max(entryMin, usageMin, sectionMin);
+		if (options.maxWidth < minWidth) throw new RangeError(`maxWidth must be at least ${minWidth}, got ${options.maxWidth}.`);
+		if (needsDescColumn && minDescWidth > 1) {
+			const avail = options.maxWidth - termIndent - 2;
+			const effTW = avail >= termWidth + 1 ? termWidth : Math.max(1, Math.floor(avail / 2));
+			const descW = avail - effTW;
+			if (descW < minDescWidth) {
+				const needed = termIndent + termWidth + 2 + minDescWidth;
+				throw new RangeError(`maxWidth must be at least ${needed}, got ${options.maxWidth}.`);
+			}
+		}
+	}
+	let effectiveTermWidth;
+	if (options.maxWidth == null) effectiveTermWidth = termWidth;
+	else {
+		const availableForColumns = options.maxWidth - termIndent - 2;
+		effectiveTermWidth = availableForColumns >= termWidth + 1 ? termWidth : Math.max(1, Math.floor(availableForColumns / 2));
+	}
 	let output = "";
-	if (page.brief != null) {
+	if (hasContent(page.brief)) {
 		output += require_message.formatMessage(page.brief, {
 			colors: options.colors,
 			maxWidth: options.maxWidth,
@@ -88,7 +292,7 @@ function formatDocPage(programName, page, options = {}) {
 		}), 7);
 		output += "\n";
 	}
-	if (page.description != null) {
+	if (hasContent(page.description)) {
 		output += "\n";
 		output += require_message.formatMessage(page.description, {
 			colors: options.colors,
@@ -110,6 +314,7 @@ function formatDocPage(programName, page, options = {}) {
 		if (section.entries.length < 1) continue;
 		output += "\n";
 		if (section.title != null) {
+			require_validate.validateLabel(section.title);
 			const sectionLabel = options.colors ? `\x1b[1;2m${section.title}:\x1b[0m\n` : `${section.title}:\n`;
 			output += sectionLabel;
 		}
@@ -117,11 +322,12 @@ function formatDocPage(programName, page, options = {}) {
 			const term = require_usage.formatUsageTerm(entry.term, {
 				colors: options.colors,
 				optionsSeparator: ", ",
+				context: "doc",
 				maxWidth: options.maxWidth == null ? void 0 : options.maxWidth - termIndent
 			});
-			const descColumnWidth = options.maxWidth == null ? void 0 : options.maxWidth - termIndent - termWidth - 2;
+			const descColumnWidth = options.maxWidth == null ? void 0 : options.maxWidth - termIndent - effectiveTermWidth - 2;
 			const termVisibleWidth = lastLineVisibleLength(term);
-			const extraTermOffset = descColumnWidth != null ? Math.max(0, termVisibleWidth - termWidth) : 0;
+			const extraTermOffset = descColumnWidth != null ? Math.max(0, termVisibleWidth - effectiveTermWidth) : 0;
 			const currentExtraOffset = () => description.includes("\n") ? 0 : extraTermOffset;
 			const descFormatOptions = {
 				colors: options.colors,
@@ -130,22 +336,24 @@ function formatDocPage(programName, page, options = {}) {
 				startWidth: extraTermOffset > 0 ? extraTermOffset : void 0
 			};
 			let description = entry.description == null ? "" : require_message.formatMessage(entry.description, descFormatOptions);
-			if (options.showDefault && entry.default != null) {
+			if (options.showDefault && hasContent(entry.default)) {
 				const prefix = typeof options.showDefault === "object" ? options.showDefault.prefix ?? " [" : " [";
 				const suffix = typeof options.showDefault === "object" ? options.showDefault.suffix ?? "]" : "]";
+				const prefixWidth = require_displaywidth.getDisplayWidth(prefix);
+				const suffixWidth = require_displaywidth.getDisplayWidth(suffix);
 				let defaultStartWidth;
 				if (descColumnWidth != null) {
 					const lastW = lastLineVisibleLength(description);
 					const effectiveLastW = lastW + currentExtraOffset();
-					if (effectiveLastW + prefix.length >= descColumnWidth) {
+					if (effectiveLastW + prefixWidth >= descColumnWidth) {
 						description += "\n";
-						defaultStartWidth = prefix.length;
-					} else defaultStartWidth = effectiveLastW + prefix.length;
+						defaultStartWidth = prefixWidth;
+					} else defaultStartWidth = effectiveLastW + prefixWidth;
 				}
 				const defaultFormatOptions = {
 					colors: options.colors ? { resetSuffix: "\x1B[2m" } : false,
 					quotes: !options.colors,
-					maxWidth: descColumnWidth == null ? void 0 : descColumnWidth - suffix.length,
+					maxWidth: descColumnWidth == null ? void 0 : descColumnWidth - suffixWidth,
 					startWidth: defaultStartWidth
 				};
 				const defaultContent = require_message.formatMessage(entry.default, defaultFormatOptions);
@@ -153,7 +361,7 @@ function formatDocPage(programName, page, options = {}) {
 				const formattedDefault = options.colors ? `\x1b[2m${defaultText}\x1b[0m` : defaultText;
 				description += formattedDefault;
 			}
-			if (options.showChoices && entry.choices != null) {
+			if (options.showChoices && hasContent(entry.choices)) {
 				const prefix = typeof options.showChoices === "object" ? options.showChoices.prefix ?? " (" : " (";
 				const suffix = typeof options.showChoices === "object" ? options.showChoices.suffix ?? ")" : ")";
 				const label = typeof options.showChoices === "object" ? options.showChoices.label ?? "choices: " : "choices: ";
@@ -174,11 +382,14 @@ function formatDocPage(programName, page, options = {}) {
 					}
 					if (truncated) truncatedTerms = [...terms.slice(0, cutIndex), require_message.text(", ...")];
 				}
+				const choicesPrefixWidth = require_displaywidth.getDisplayWidth(prefix);
+				const choicesSuffixWidth = require_displaywidth.getDisplayWidth(suffix);
+				const choicesLabelWidth = require_displaywidth.getDisplayWidth(label);
 				let choicesStartWidth;
 				if (descColumnWidth != null) {
 					const lastW = lastLineVisibleLength(description);
 					const effectiveLastW = lastW + currentExtraOffset();
-					const prefixLabelLen = prefix.length + label.length;
+					const prefixLabelLen = choicesPrefixWidth + choicesLabelWidth;
 					if (effectiveLastW + prefixLabelLen >= descColumnWidth) {
 						description += "\n";
 						choicesStartWidth = prefixLabelLen;
@@ -187,7 +398,7 @@ function formatDocPage(programName, page, options = {}) {
 				const choicesFormatOptions = {
 					colors: options.colors ? { resetSuffix: "\x1B[2m" } : false,
 					quotes: false,
-					maxWidth: descColumnWidth == null ? void 0 : descColumnWidth - suffix.length,
+					maxWidth: descColumnWidth == null ? void 0 : descColumnWidth - choicesSuffixWidth,
 					startWidth: choicesStartWidth
 				};
 				const choicesDisplay = require_message.formatMessage(truncatedTerms, choicesFormatOptions);
@@ -195,10 +406,10 @@ function formatDocPage(programName, page, options = {}) {
 				const formattedChoices = options.colors ? `\x1b[2m${choicesText}\x1b[0m` : choicesText;
 				description += formattedChoices;
 			}
-			output += `${" ".repeat(termIndent)}${ansiAwareRightPad(term, termWidth)}  ${description === "" ? "" : indentLines(description, termIndent + termWidth + 2)}\n`;
+			output += `${" ".repeat(termIndent)}${ansiAwareRightPad(term, effectiveTermWidth)}${description === "" ? "" : `  ${indentLines(description, termIndent + effectiveTermWidth + 2)}`}\n`;
 		}
 	}
-	if (page.examples != null) {
+	if (hasContent(page.examples)) {
 		output += "\n";
 		const examplesLabel = options.colors ? "\x1B[1;2mExamples:\x1B[0m\n" : "Examples:\n";
 		output += examplesLabel;
@@ -210,7 +421,7 @@ function formatDocPage(programName, page, options = {}) {
 		output += "  " + indentLines(examplesContent, 2);
 		output += "\n";
 	}
-	if (page.author != null) {
+	if (hasContent(page.author)) {
 		output += "\n";
 		const authorLabel = options.colors ? "\x1B[1;2mAuthor:\x1B[0m\n" : "Author:\n";
 		output += authorLabel;
@@ -222,7 +433,7 @@ function formatDocPage(programName, page, options = {}) {
 		output += "  " + indentLines(authorContent, 2);
 		output += "\n";
 	}
-	if (page.bugs != null) {
+	if (hasContent(page.bugs)) {
 		output += "\n";
 		const bugsLabel = options.colors ? "\x1B[1;2mBugs:\x1B[0m\n" : "Bugs:\n";
 		output += bugsLabel;
@@ -234,7 +445,7 @@ function formatDocPage(programName, page, options = {}) {
 		output += "  " + indentLines(bugsContent, 2);
 		output += "\n";
 	}
-	if (page.footer != null) {
+	if (hasContent(page.footer)) {
 		output += "\n";
 		output += require_message.formatMessage(page.footer, {
 			colors: options.colors,
@@ -247,17 +458,68 @@ 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;
+/**
+* Returns the width of the widest non-breakable segment among visible
+* (non-usage-hidden) terms in a usage tree.  Hidden terms are excluded
+* because they are filtered out before rendering, so they do not
+* contribute to the rendered width.
+*/
+function maxVisibleAtomicWidth(usage) {
+	let max = 0;
+	for (const term of usage) switch (term.type) {
+		case "argument":
+			if (!require_usage.isUsageHidden(term.hidden)) max = Math.max(max, require_displaywidth.getDisplayWidth(term.metavar));
+			break;
+		case "option":
+			if (!require_usage.isUsageHidden(term.hidden) && term.names.length > 0) {
+				for (const name of term.names) max = Math.max(max, require_displaywidth.getDisplayWidth(name));
+				if (term.metavar != null) max = Math.max(max, require_displaywidth.getDisplayWidth(term.metavar));
+			}
+			break;
+		case "command":
+			if (!require_usage.isUsageHidden(term.hidden)) max = Math.max(max, require_displaywidth.getDisplayWidth(term.name));
+			break;
+		case "passthrough":
+			if (!require_usage.isUsageHidden(term.hidden)) max = Math.max(max, 5);
+			break;
+		case "optional":
+			max = Math.max(max, maxVisibleAtomicWidth(term.terms));
+			break;
+		case "multiple": {
+			const innerMax = maxVisibleAtomicWidth(term.terms);
+			if (innerMax > 0) max = Math.max(max, 3, innerMax);
+			break;
+		}
+		case "exclusive":
+			for (const branch of term.terms) {
+				const first = branch[0];
+				if (first?.type === "command" && require_usage.isUsageHidden(first.hidden)) continue;
+				max = Math.max(max, maxVisibleAtomicWidth(branch));
+			}
+			break;
+		case "literal":
+			if (term.value !== "") max = Math.max(max, require_displaywidth.getDisplayWidth(term.value));
+			break;
+		case "ellipsis":
+			max = Math.max(max, 3);
+			break;
+	}
+	return max;
+}
 function ansiAwareRightPad(text$1, length, char = " ") {
-	const strippedText = text$1.replace(ansiEscapeCodeRegex, "");
-	if (strippedText.length >= length) return text$1;
-	return text$1 + char.repeat(length - strippedText.length);
+	const visibleWidth = lastLineVisibleLength(text$1);
+	if (visibleWidth >= length) return text$1;
+	return text$1 + char.repeat(length - visibleWidth);
 }
 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;
+	return require_displaywidth.getDisplayWidth(lastLine);
 }
 
 //#endregion
-exports.formatDocPage = formatDocPage;
+exports.cloneDocEntry = cloneDocEntry;
+exports.deduplicateDocEntries = deduplicateDocEntries;
+exports.deduplicateDocFragments = deduplicateDocFragments;
+exports.formatDocPage = formatDocPage;
+exports.isDocEntryHidden = isDocEntryHidden;

package/dist/doc.d.cts

@@ -103,6 +103,53 @@ interface DocFragments {
    */
   readonly footer?: Message;
 }
+/**
+ * Returns whether a doc entry's term is hidden from documentation.
+ * Only term types with a `hidden` field (argument, option, command,
+ * passthrough) are checked; other types always return `false`.
+ *
+ * @param entry The doc entry to check.
+ * @returns `true` if the entry should be hidden from documentation.
+ * @since 1.0.0
+ */
+declare function isDocEntryHidden(entry: DocEntry): boolean;
+/**
+ * Removes duplicate {@link DocEntry} values that share the same surface
+ * syntax (same term type and identifying names).  Doc-hidden entries are
+ * filtered out first so they cannot influence the ordering of visible
+ * entries.  Among the remaining visible entries, the first occurrence is
+ * kept and later duplicates are discarded.
+ *
+ * Positional argument entries are never deduplicated because they are
+ * distinguished by position, not by metavar, and {@link DocEntry} does
+ * not carry position information.
+ *
+ * @param entries The entries to deduplicate.
+ * @returns A new array with hidden entries removed and duplicates
+ *   collapsed, preserving insertion order of visible entries.
+ * @since 1.0.0
+ */
+declare function deduplicateDocEntries(entries: readonly DocEntry[]): DocEntry[];
+/**
+ * Removes duplicate entries from a list of {@link DocFragment} values.
+ * Entry-type fragments are deduplicated by their surface syntax key.
+ * Section-type fragments have their entries deduplicated internally.
+ *
+ * @param fragments The fragments to deduplicate.
+ * @returns A new array with duplicate entries removed.
+ * @since 1.0.0
+ */
+declare function deduplicateDocFragments(fragments: readonly DocFragment[]): DocFragment[];
+/**
+ * Creates a deep clone of a {@link DocEntry}.  The `term` is cloned via
+ * {@link cloneUsageTerm}, and `description`, `default`, and `choices`
+ * messages are cloned via {@link cloneMessage}.
+ *
+ * @param entry The documentation entry to clone.
+ * @returns A structurally equal but referentially distinct copy.
+ * @since 1.0.0
+ */
+declare function cloneDocEntry(entry: DocEntry): DocEntry;
 /**
  * Configuration for customizing default value display formatting.
  *
@@ -148,9 +195,10 @@ interface ShowChoicesOptions {
   readonly label?: string;
   /**
    * Maximum number of choice values to display before truncating with
-   * `...`.  Set to `Infinity` to show all choices.
+   * `...`.  Must be at least `1`.  Set to `Infinity` to show all choices.
    *
    * @default `8`
+   * @throws {RangeError} If the value is less than `1`.
    */
   readonly maxItems?: number;
 }
@@ -263,6 +311,13 @@ interface DocPageFormatOptions {
  * @param page The documentation page to format
  * @param options Formatting options to customize the output
  * @returns A formatted string representation of the documentation page
+ * @throws {TypeError} If `programName` is not a string, is empty,
+ * whitespace-only, or contains control characters, if any non-empty
+ * section's title is not a string, is empty, whitespace-only, or contains
+ * control characters, or if `maxWidth` is not a finite integer.
+ * @throws {RangeError} If any entry needs a description column and `maxWidth`
+ * is too small to fit the minimum layout (less than `termIndent + 4`), or if
+ * `showChoices.maxItems` is less than `1`.
  *
  * @example
  * ```typescript
@@ -284,4 +339,4 @@ interface DocPageFormatOptions {
  */
 declare function formatDocPage(programName: string, page: DocPage, options?: DocPageFormatOptions): string;
 //#endregion
-export { DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, ShowChoicesOptions, ShowDefaultOptions, formatDocPage };
+export { DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, ShowChoicesOptions, ShowDefaultOptions, cloneDocEntry, deduplicateDocEntries, deduplicateDocFragments, formatDocPage, isDocEntryHidden };