@optique/core 1.0.0-dev.908 → 1.0.0

package/dist/usage.cjs

@@ -1,3 +1,5 @@
+const require_displaywidth = require('./displaywidth.cjs');
+const require_validate = require('./validate.cjs');
 
 //#region src/usage.ts
 /**
@@ -40,6 +42,8 @@ function mergeHidden(a, b) {
 * multiple, and exclusive terms.
 *
 * @param usage The usage description to extract option names from.
+* @param includeHidden Whether to include fully hidden options (`hidden: true`)
+*   in the result.  Defaults to `false`.
 * @returns A set containing all option names found in the usage description.
 *
 * @example
@@ -52,12 +56,12 @@ function mergeHidden(a, b) {
 * // names = Set(["--verbose", "-v", "--quiet", "-q"])
 * ```
 */
-function extractOptionNames(usage) {
+function extractOptionNames(usage, includeHidden) {
 	const names = /* @__PURE__ */ new Set();
 	function traverseUsage(terms) {
 		if (!terms || !Array.isArray(terms)) return;
 		for (const term of terms) if (term.type === "option") {
-			if (isSuggestionHidden(term.hidden)) continue;
+			if (!includeHidden && isSuggestionHidden(term.hidden)) continue;
 			for (const name of term.names) names.add(name);
 		} else if (term.type === "optional" || term.type === "multiple") traverseUsage(term.terms);
 		else if (term.type === "exclusive") for (const exclusiveUsage of term.terms) traverseUsage(exclusiveUsage);
@@ -71,8 +75,10 @@ function extractOptionNames(usage) {
 * This function recursively traverses the usage structure and collects
 * all command names, similar to {@link extractOptionNames}.
 *
-* @param usage The usage structure to extract command names from
-* @returns A Set of all command names found in the usage structure
+* @param usage The usage structure to extract command names from.
+* @param includeHidden Whether to include fully hidden commands
+*   (`hidden: true`) in the result.  Defaults to `false`.
+* @returns A set of all command names found in the usage structure.
 *
 * @example
 * ```typescript
@@ -85,12 +91,12 @@ function extractOptionNames(usage) {
 * ```
 * @since 0.7.0
 */
-function extractCommandNames(usage) {
+function extractCommandNames(usage, includeHidden) {
 	const names = /* @__PURE__ */ new Set();
 	function traverseUsage(terms) {
 		if (!terms || !Array.isArray(terms)) return;
 		for (const term of terms) if (term.type === "command") {
-			if (isSuggestionHidden(term.hidden)) continue;
+			if (!includeHidden && isSuggestionHidden(term.hidden)) continue;
 			names.add(term.name);
 		} else if (term.type === "optional" || term.type === "multiple") traverseUsage(term.terms);
 		else if (term.type === "exclusive") for (const exclusiveUsage of term.terms) traverseUsage(exclusiveUsage);
@@ -99,6 +105,29 @@ function extractCommandNames(usage) {
 	return names;
 }
 /**
+* Extracts all literal values from a usage description.
+*
+* This function recursively traverses the usage tree and collects all
+* `literal` term values.  Literal values represent fixed strings that
+* the user must type (e.g., conditional discriminator values like
+* `"server"` in `conditional(option("--mode", string()), { server: ... })`).
+*
+* @param usage The usage description to extract literal values from.
+* @returns A set of all literal values found in the usage description.
+* @since 1.0.0
+*/
+function extractLiteralValues(usage) {
+	const values = /* @__PURE__ */ new Set();
+	function traverseUsage(terms) {
+		if (!terms || !Array.isArray(terms)) return;
+		for (const term of terms) if (term.type === "literal") values.add(term.value);
+		else if (term.type === "optional" || term.type === "multiple") traverseUsage(term.terms);
+		else if (term.type === "exclusive") for (const branch of term.terms) traverseUsage(branch);
+	}
+	traverseUsage(usage);
+	return values;
+}
+/**
 * Extracts all argument metavars from a Usage array.
 *
 * This function recursively traverses the usage structure and collects
@@ -147,8 +176,11 @@ function extractArgumentMetavars(usage) {
 * @param options Optional formatting options to customize the output.
 *                See {@link UsageFormatOptions} for available options.
 * @returns A formatted string representation of the usage description.
+* @throws {TypeError} If `programName` is not a string, is empty,
+*         whitespace-only, or contains control characters.
 */
 function formatUsage(programName, usage, options = {}) {
+	require_validate.validateProgramName(programName);
 	usage = normalizeUsage(filterUsageForDisplay(usage));
 	if (options.expandCommands) {
 		const lastTerm = usage.at(-1);
@@ -160,13 +192,24 @@ function formatUsage(programName, usage, options = {}) {
 				if (usage.length > 1) command = [...usage.slice(0, -1), ...command];
 				lines.push(formatUsage(programName, command, options));
 			}
-			return lines.join("\n");
+			if (lines.length > 0) return lines.join("\n");
 		}
 	}
-	let output = options.colors ? `\x1b[1m${programName}\x1b[0m ` : `${programName} `;
-	let lineWidth = programName.length + 1;
+	let output = options.colors ? `\x1b[1m${programName}\x1b[0m` : programName;
+	let lineWidth = require_displaywidth.getDisplayWidth(programName);
+	let first = true;
 	for (const { text, width } of formatUsageTerms(usage, options)) {
-		if (options.maxWidth != null && lineWidth + width > options.maxWidth) {
+		if (first) {
+			first = false;
+			if (options.maxWidth != null && lineWidth + 1 + width > options.maxWidth) {
+				output += "\n";
+				lineWidth = 0;
+			} else {
+				output += " ";
+				lineWidth += 1;
+			}
+		} else if (options.maxWidth != null && lineWidth > 0 && lineWidth + width > options.maxWidth) {
+			if (output.endsWith(" ")) output = output.slice(0, -1);
 			output += "\n";
 			lineWidth = 0;
 			if (text === " ") continue;
@@ -181,14 +224,27 @@ function formatUsage(programName, usage, options = {}) {
 * sorting terms for better readability, and ensuring consistent structure
 * throughout the usage tree.
 *
-* This function performs two main operations:
+* This function performs three main operations:
+*
+* 1. *Stripping*: Removes degenerate terms that would render as empty or
+*    malformed output, such as options with no names, commands with empty
+*    names, arguments with empty metavars, and container terms (`optional`,
+*    `multiple`, `exclusive`) whose top-level terms array is empty after
+*    recursive normalization.  Exclusive branches representing valid
+*    zero-token alternatives (e.g., `conditional()` default branches or
+*    `optional(constant(...))`) and empty-value literals are preserved.
+*    Only branches that become empty because all their content was
+*    malformed are removed.
 *
-* 1. *Flattening*: Recursively processes all usage terms and merges any
+* 2. *Flattening*: Recursively processes all usage terms and merges any
 *    nested exclusive terms into their parent exclusive term to avoid
 *    redundant nesting. For example, an exclusive term containing another
 *    exclusive term will have its nested terms flattened into the parent.
+*    Similarly, nested optional terms are collapsed:
+*    `optional(optional(X))` becomes `optional(X)` when the outer optional
+*    contains only a single inner optional term.
 *
-* 2. *Sorting*: Reorders terms to improve readability by placing:
+* 3. *Sorting*: Reorders terms to improve readability by placing:
 *    - Commands (subcommands) first
 *    - Options and other terms in the middle
 *    - Positional arguments last (including optional/multiple wrappers around
@@ -198,11 +254,12 @@ function formatUsage(programName, usage, options = {}) {
 * positional arguments and treats them as arguments for sorting purposes.
 *
 * @param usage The usage description to normalize.
-* @returns A normalized usage description with flattened exclusive terms
-*          and terms sorted for optimal readability.
+* @returns A normalized usage description with degenerate terms removed,
+*          nested exclusive and optional terms flattened, and remaining
+*          terms sorted for optimal readability.
 */
 function normalizeUsage(usage) {
-	const terms = usage.map(normalizeUsageTerm);
+	const terms = usage.map(normalizeUsageTerm).filter(isNonDegenerateTerm);
 	terms.sort((a, b) => {
 		const aCmd = a.type === "command";
 		const bCmd = b.type === "command";
@@ -213,11 +270,14 @@ function normalizeUsage(usage) {
 	return terms;
 }
 function normalizeUsageTerm(term) {
-	if (term.type === "optional") return {
-		type: "optional",
-		terms: normalizeUsage(term.terms)
-	};
-	else if (term.type === "multiple") return {
+	if (term.type === "optional") {
+		const normalized = normalizeUsage(term.terms);
+		if (normalized.length === 1 && normalized[0].type === "optional") return normalized[0];
+		return {
+			type: "optional",
+			terms: normalized
+		};
+	} else if (term.type === "multiple") return {
 		type: "multiple",
 		terms: normalizeUsage(term.terms),
 		min: term.min
@@ -229,20 +289,111 @@ function normalizeUsageTerm(term) {
 			if (normalized.length >= 1 && normalized[0].type === "exclusive") {
 				const rest = normalized.slice(1);
 				for (const subUsage of normalized[0].terms) terms.push([...subUsage, ...rest]);
-			} else terms.push(normalized);
+			} else if (normalized.length > 0 || !containsMalformedLeaf(usage)) terms.push(normalized);
 		}
 		return {
 			type: "exclusive",
 			terms
 		};
-	} else return term;
+	} else {
+		if (term.type === "option") return {
+			...term,
+			names: [...term.names]
+		};
+		else if (term.type === "command") {
+			if (term.usageLine == null || typeof term.usageLine === "function") return { ...term };
+			return {
+				...term,
+				usageLine: cloneUsage(term.usageLine)
+			};
+		}
+		return { ...term };
+	}
+}
+function isNonDegenerateTerm(term) {
+	if (term.type === "option") return term.names.length > 0;
+	if (term.type === "command") return term.name !== "";
+	if (term.type === "argument") return term.metavar.length > 0;
+	if (term.type === "optional" || term.type === "multiple" || term.type === "exclusive") return term.terms.length > 0;
+	return true;
+}
+function containsMalformedLeaf(usage) {
+	for (const term of usage) {
+		if (term.type === "option" && term.names.length === 0) return true;
+		if (term.type === "command" && term.name === "") return true;
+		if (term.type === "argument" && term.metavar.length === 0) return true;
+		if (term.type === "optional" || term.type === "multiple") {
+			if (containsMalformedLeaf(term.terms)) return true;
+		}
+		if (term.type === "exclusive") {
+			for (const branch of term.terms) if (containsMalformedLeaf(branch)) return true;
+		}
+	}
+	return false;
+}
+/**
+* Creates a deep clone of a single {@link UsageTerm}.  Recursive term
+* variants (`optional`, `multiple`, `exclusive`) are cloned recursively.
+* For `command` terms, a function-valued `usageLine` is preserved by
+* reference (functions are stateless callbacks), while an array-valued
+* `usageLine` is deep-cloned.
+*
+* @param term The usage term to clone.
+* @returns A structurally equal but referentially distinct copy.
+* @since 1.0.0
+*/
+function cloneUsageTerm(term) {
+	switch (term.type) {
+		case "argument": return { ...term };
+		case "option": return {
+			...term,
+			names: [...term.names]
+		};
+		case "command": {
+			if (term.usageLine == null || typeof term.usageLine === "function") return { ...term };
+			return {
+				...term,
+				usageLine: term.usageLine.map(cloneUsageTerm)
+			};
+		}
+		case "optional": return {
+			type: "optional",
+			terms: term.terms.map(cloneUsageTerm)
+		};
+		case "multiple": return {
+			type: "multiple",
+			terms: term.terms.map(cloneUsageTerm),
+			min: term.min
+		};
+		case "exclusive": return {
+			type: "exclusive",
+			terms: term.terms.map((u) => u.map(cloneUsageTerm))
+		};
+		case "literal":
+		case "passthrough":
+		case "ellipsis": return { ...term };
+	}
+}
+/**
+* Creates a deep clone of a {@link Usage} array and all of its terms.
+*
+* @param usage The usage array to clone.
+* @returns A mutable array of deeply cloned usage terms.
+* @since 1.0.0
+*/
+function cloneUsage(usage) {
+	return usage.map(cloneUsageTerm);
 }
-function filterUsageForDisplay(usage) {
+function filterUsageForDisplay(usage, isHidden = isUsageHidden) {
 	const terms = [];
 	for (const term of usage) {
-		if ((term.type === "argument" || term.type === "option" || term.type === "command" || term.type === "passthrough") && isUsageHidden(term.hidden)) continue;
+		if ((term.type === "argument" || term.type === "option" || term.type === "command" || term.type === "passthrough") && isHidden(term.hidden)) continue;
+		if (term.type === "option" && term.names.length === 0) continue;
+		if (term.type === "command" && term.name === "") continue;
+		if (term.type === "argument" && term.metavar.length === 0) continue;
+		if (term.type === "literal" && term.value === "") continue;
 		if (term.type === "optional") {
-			const filtered = filterUsageForDisplay(term.terms);
+			const filtered = filterUsageForDisplay(term.terms, isHidden);
 			if (filtered.length > 0) terms.push({
 				type: "optional",
 				terms: filtered
@@ -250,7 +401,7 @@ function filterUsageForDisplay(usage) {
 			continue;
 		}
 		if (term.type === "multiple") {
-			const filtered = filterUsageForDisplay(term.terms);
+			const filtered = filterUsageForDisplay(term.terms, isHidden);
 			if (filtered.length > 0) terms.push({
 				type: "multiple",
 				terms: filtered,
@@ -261,8 +412,8 @@ function filterUsageForDisplay(usage) {
 		if (term.type === "exclusive") {
 			const filteredBranches = term.terms.map((branch) => {
 				const first = branch[0];
-				if (first?.type === "command" && isUsageHidden(first.hidden)) return [];
-				return filterUsageForDisplay(branch);
+				if (first?.type === "command" && isHidden(first.hidden)) return [];
+				return filterUsageForDisplay(branch, isHidden);
 			}).filter((branch) => branch.length > 0);
 			if (filteredBranches.length > 0) terms.push({
 				type: "exclusive",
@@ -277,7 +428,6 @@ function filterUsageForDisplay(usage) {
 function* formatUsageTerms(terms, options) {
 	let i = 0;
 	for (const t of terms) {
-		if ("hidden" in t && (t.type === "argument" || t.type === "option" || t.type === "command" || t.type === "passthrough") && isUsageHidden(t.hidden)) continue;
 		if (i > 0) yield {
 			text: " ",
 			width: 1
@@ -296,12 +446,14 @@ function* formatUsageTerms(terms, options) {
 * @returns A formatted string representation of the usage term.
 */
 function formatUsageTerm(term, options = {}) {
-	const visibleTerms = filterUsageForDisplay([term]);
+	const hiddenCheck = options.context === "doc" ? isDocHidden : isUsageHidden;
+	const visibleTerms = filterUsageForDisplay([term], hiddenCheck);
 	if (visibleTerms.length < 1) return "";
 	let lineWidth = 0;
 	let output = "";
 	for (const { text, width } of formatUsageTermInternal(visibleTerms[0], options)) {
-		if (options.maxWidth != null && lineWidth + width > options.maxWidth) {
+		if (options.maxWidth != null && lineWidth > 0 && lineWidth + width > options.maxWidth) {
+			if (output.endsWith(" ")) output = output.slice(0, -1);
 			output += "\n";
 			lineWidth = 0;
 			if (text === " ") continue;
@@ -315,24 +467,24 @@ function* formatUsageTermInternal(term, options) {
 	const optionsSeparator = options.optionsSeparator ?? "/";
 	if (term.type === "argument") yield {
 		text: options?.colors ? `\x1b[4m${term.metavar}\x1b[0m` : term.metavar,
-		width: term.metavar.length
+		width: require_displaywidth.getDisplayWidth(term.metavar)
 	};
 	else if (term.type === "option") if (options?.onlyShortestOptions) {
-		const shortestName = term.names.reduce((a, b) => a.length <= b.length ? a : b);
+		const shortestName = term.names.reduce((a, b) => require_displaywidth.getDisplayWidth(a) <= require_displaywidth.getDisplayWidth(b) ? a : b);
 		yield {
 			text: options?.colors ? `\x1b[3m${shortestName}\x1b[0m` : shortestName,
-			width: shortestName.length
+			width: require_displaywidth.getDisplayWidth(shortestName)
 		};
 	} else {
 		let i = 0;
 		for (const optionName of term.names) {
 			if (i > 0) yield {
 				text: options?.colors ? `\x1b[2m${optionsSeparator}\x1b[0m` : optionsSeparator,
-				width: optionsSeparator.length
+				width: require_displaywidth.getDisplayWidth(optionsSeparator)
 			};
 			yield {
 				text: options?.colors ? `\x1b[3m${optionName}\x1b[0m` : optionName,
-				width: optionName.length
+				width: require_displaywidth.getDisplayWidth(optionName)
 			};
 			i++;
 		}
@@ -343,13 +495,13 @@ function* formatUsageTermInternal(term, options) {
 			};
 			yield {
 				text: options?.colors ? `\x1b[4m\x1b[2m${term.metavar}\x1b[0m` : term.metavar,
-				width: term.metavar.length
+				width: require_displaywidth.getDisplayWidth(term.metavar)
 			};
 		}
 	}
 	else if (term.type === "command") yield {
 		text: options?.colors ? `\x1b[1m${term.name}\x1b[0m` : term.name,
-		width: term.name.length
+		width: require_displaywidth.getDisplayWidth(term.name)
 	};
 	else if (term.type === "optional") {
 		yield {
@@ -411,7 +563,7 @@ function* formatUsageTermInternal(term, options) {
 		};
 	} else if (term.type === "literal") yield {
 		text: term.value,
-		width: term.value.length
+		width: require_displaywidth.getDisplayWidth(term.value)
 	};
 	else if (term.type === "passthrough") {
 		const text = "[...]";
@@ -429,8 +581,11 @@ function* formatUsageTermInternal(term, options) {
 }
 
 //#endregion
+exports.cloneUsage = cloneUsage;
+exports.cloneUsageTerm = cloneUsageTerm;
 exports.extractArgumentMetavars = extractArgumentMetavars;
 exports.extractCommandNames = extractCommandNames;
+exports.extractLiteralValues = extractLiteralValues;
 exports.extractOptionNames = extractOptionNames;
 exports.formatUsage = formatUsage;
 exports.formatUsageTerm = formatUsageTerm;

package/dist/usage.d.cts

@@ -10,8 +10,14 @@ import { NonEmptyString } from "./nonempty.cjs";
  * - POSIX-style short options (`-o`) or Java-style options (`-option`)
  * - MS-DOS-style options (`/o`, `/option`)
  * - Plus-prefixed options (`+o`)
+ *
+ * Each prefix must be followed by at least one character, so bare prefixes
+ * like `"-"`, `"/"`, or `"+"` are rejected at compile time.  Due to
+ * TypeScript template literal limitations, `"--"` still matches the
+ * `-${NonEmptyString}` branch and is only rejected at runtime by the
+ * `option()` and `flag()` validators.
  */
-type OptionName = `--${string}` | `-${string}` | `/${string}` | `+${string}`;
+type OptionName = `--${NonEmptyString}` | `-${NonEmptyString}` | `/${NonEmptyString}` | `+${NonEmptyString}`;
 /**
  * Visibility control for parser terms.
  *
@@ -172,6 +178,18 @@ type UsageTerm =
    * The literal value that must be provided exactly as written.
    */
   readonly value: string;
+  /**
+   * When `true`, this literal was derived from an option's metavar by
+   * `appendLiteralToUsage()` in `conditional()` and represents an option
+   * value, not a standalone positional token.
+   * {@link extractLeadingLiteralValues} and the `skipOptionValueLiterals`
+   * mode of `branchConsumesToken()` use this to distinguish option values
+   * from real positional literals.  {@link extractLeadingOptionNames} and
+   * {@link extractLeadingCommandNames} intentionally still treat these
+   * literals as positional gates.
+   * @since 1.0.0
+   */
+  readonly optionValue?: boolean;
 }
 /**
  * A pass-through term, which represents unrecognized options that are
@@ -214,6 +232,8 @@ type Usage = readonly UsageTerm[];
  * multiple, and exclusive terms.
  *
  * @param usage The usage description to extract option names from.
+ * @param includeHidden Whether to include fully hidden options (`hidden: true`)
+ *   in the result.  Defaults to `false`.
  * @returns A set containing all option names found in the usage description.
  *
  * @example
@@ -226,15 +246,17 @@ type Usage = readonly UsageTerm[];
  * // names = Set(["--verbose", "-v", "--quiet", "-q"])
  * ```
  */
-declare function extractOptionNames(usage: Usage): Set<string>;
+declare function extractOptionNames(usage: Usage, includeHidden?: boolean): Set<string>;
 /**
  * Extracts all command names from a Usage array.
  *
  * This function recursively traverses the usage structure and collects
  * all command names, similar to {@link extractOptionNames}.
  *
- * @param usage The usage structure to extract command names from
- * @returns A Set of all command names found in the usage structure
+ * @param usage The usage structure to extract command names from.
+ * @param includeHidden Whether to include fully hidden commands
+ *   (`hidden: true`) in the result.  Defaults to `false`.
+ * @returns A set of all command names found in the usage structure.
  *
  * @example
  * ```typescript
@@ -247,7 +269,20 @@ declare function extractOptionNames(usage: Usage): Set<string>;
  * ```
  * @since 0.7.0
  */
-declare function extractCommandNames(usage: Usage): Set<string>;
+declare function extractCommandNames(usage: Usage, includeHidden?: boolean): Set<string>;
+/**
+ * Extracts all literal values from a usage description.
+ *
+ * This function recursively traverses the usage tree and collects all
+ * `literal` term values.  Literal values represent fixed strings that
+ * the user must type (e.g., conditional discriminator values like
+ * `"server"` in `conditional(option("--mode", string()), { server: ... })`).
+ *
+ * @param usage The usage description to extract literal values from.
+ * @returns A set of all literal values found in the usage description.
+ * @since 1.0.0
+ */
+declare function extractLiteralValues(usage: Usage): Set<string>;
 /**
  * Extracts all argument metavars from a Usage array.
  *
@@ -319,6 +354,8 @@ interface UsageFormatOptions {
  * @param options Optional formatting options to customize the output.
  *                See {@link UsageFormatOptions} for available options.
  * @returns A formatted string representation of the usage description.
+ * @throws {TypeError} If `programName` is not a string, is empty,
+ *         whitespace-only, or contains control characters.
  */
 declare function formatUsage(programName: string, usage: Usage, options?: UsageFormatOptions): string;
 /**
@@ -326,14 +363,27 @@ declare function formatUsage(programName: string, usage: Usage, options?: UsageF
  * sorting terms for better readability, and ensuring consistent structure
  * throughout the usage tree.
  *
- * This function performs two main operations:
+ * This function performs three main operations:
  *
- * 1. *Flattening*: Recursively processes all usage terms and merges any
+ * 1. *Stripping*: Removes degenerate terms that would render as empty or
+ *    malformed output, such as options with no names, commands with empty
+ *    names, arguments with empty metavars, and container terms (`optional`,
+ *    `multiple`, `exclusive`) whose top-level terms array is empty after
+ *    recursive normalization.  Exclusive branches representing valid
+ *    zero-token alternatives (e.g., `conditional()` default branches or
+ *    `optional(constant(...))`) and empty-value literals are preserved.
+ *    Only branches that become empty because all their content was
+ *    malformed are removed.
+ *
+ * 2. *Flattening*: Recursively processes all usage terms and merges any
  *    nested exclusive terms into their parent exclusive term to avoid
  *    redundant nesting. For example, an exclusive term containing another
  *    exclusive term will have its nested terms flattened into the parent.
+ *    Similarly, nested optional terms are collapsed:
+ *    `optional(optional(X))` becomes `optional(X)` when the outer optional
+ *    contains only a single inner optional term.
  *
- * 2. *Sorting*: Reorders terms to improve readability by placing:
+ * 3. *Sorting*: Reorders terms to improve readability by placing:
  *    - Commands (subcommands) first
  *    - Options and other terms in the middle
  *    - Positional arguments last (including optional/multiple wrappers around
@@ -343,10 +393,31 @@ declare function formatUsage(programName: string, usage: Usage, options?: UsageF
  * positional arguments and treats them as arguments for sorting purposes.
  *
  * @param usage The usage description to normalize.
- * @returns A normalized usage description with flattened exclusive terms
- *          and terms sorted for optimal readability.
+ * @returns A normalized usage description with degenerate terms removed,
+ *          nested exclusive and optional terms flattened, and remaining
+ *          terms sorted for optimal readability.
  */
 declare function normalizeUsage(usage: Usage): Usage;
+/**
+ * Creates a deep clone of a single {@link UsageTerm}.  Recursive term
+ * variants (`optional`, `multiple`, `exclusive`) are cloned recursively.
+ * For `command` terms, a function-valued `usageLine` is preserved by
+ * reference (functions are stateless callbacks), while an array-valued
+ * `usageLine` is deep-cloned.
+ *
+ * @param term The usage term to clone.
+ * @returns A structurally equal but referentially distinct copy.
+ * @since 1.0.0
+ */
+declare function cloneUsageTerm(term: UsageTerm): UsageTerm;
+/**
+ * Creates a deep clone of a {@link Usage} array and all of its terms.
+ *
+ * @param usage The usage array to clone.
+ * @returns A mutable array of deeply cloned usage terms.
+ * @since 1.0.0
+ */
+declare function cloneUsage(usage: Usage): UsageTerm[];
 /**
  * Options for formatting a single {@link UsageTerm}.
  */
@@ -356,6 +427,16 @@ interface UsageTermFormatOptions extends UsageFormatOptions {
    * @default `"/"`
    */
   readonly optionsSeparator?: string;
+  /**
+   * The rendering context, which determines which hidden visibility values
+   * cause terms to be filtered out.
+   *
+   * - `"usage"` (default): filters terms hidden from usage output
+   * - `"doc"`: filters terms hidden from documentation output
+   * @default `"usage"`
+   * @since 1.0.0
+   */
+  readonly context?: "usage" | "doc";
 }
 /**
  * Formats a single {@link UsageTerm} into a string representation
@@ -368,4 +449,4 @@ interface UsageTermFormatOptions extends UsageFormatOptions {
  */
 declare function formatUsageTerm(term: UsageTerm, options?: UsageTermFormatOptions): string;
 //#endregion
-export { HiddenVisibility, OptionName, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, extractArgumentMetavars, extractCommandNames, extractOptionNames, formatUsage, formatUsageTerm, isDocHidden, isSuggestionHidden, isUsageHidden, mergeHidden, normalizeUsage };
+export { HiddenVisibility, OptionName, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, cloneUsage, cloneUsageTerm, extractArgumentMetavars, extractCommandNames, extractLiteralValues, extractOptionNames, formatUsage, formatUsageTerm, isDocHidden, isSuggestionHidden, isUsageHidden, mergeHidden, normalizeUsage };