@optique/core 1.0.0-dev.1323 → 1.0.0-dev.1335

package/dist/constructs.cjs

@@ -3,6 +3,7 @@ const require_message = require('./message.cjs');
 const require_dependency = require('./dependency.cjs');
 const require_mode_dispatch = require('./mode-dispatch.cjs');
 const require_usage = require('./usage.cjs');
+const require_doc = require('./doc.cjs');
 const require_suggestion = require('./suggestion.cjs');
 const require_usage_internals = require('./usage-internals.cjs');
 
@@ -471,24 +472,12 @@ function or(...args) {
 				footer = docFragments.footer;
 				fragments = docFragments.fragments;
 			}
-			const entries = fragments.filter((f) => f.type === "entry");
-			const sections = [];
-			for (const fragment of fragments) {
-				if (fragment.type !== "section") continue;
-				if (fragment.title == null) entries.push(...fragment.entries);
-				else sections.push(fragment);
-			}
+			if (state.kind === "unavailable" || state.state == null) fragments = require_doc.deduplicateDocFragments(fragments);
 			return {
 				brief,
 				description,
 				footer,
-				fragments: [...sections.map((s) => ({
-					...s,
-					type: "section"
-				})), {
-					type: "section",
-					entries
-				}]
+				fragments
 			};
 		}
 	};
@@ -606,8 +595,11 @@ function longestMatch(...args) {
 			let description;
 			let footer;
 			let fragments;
-			if (state.kind === "unavailable" || state.state == null) fragments = parsers.flatMap((p) => p.getDocFragments({ kind: "unavailable" }).fragments);
-			else {
+			let shouldDeduplicate;
+			if (state.kind === "unavailable" || state.state == null) {
+				fragments = parsers.flatMap((p) => p.getDocFragments({ kind: "unavailable" }).fragments);
+				shouldDeduplicate = true;
+			} else {
 				const [i, result] = state.state;
 				if (result.success) {
 					const docResult = parsers[i].getDocFragments({
@@ -618,12 +610,16 @@ function longestMatch(...args) {
 					description = docResult.description;
 					footer = docResult.footer;
 					fragments = docResult.fragments;
-				} else fragments = parsers.flatMap((p) => p.getDocFragments({ kind: "unavailable" }).fragments);
+					shouldDeduplicate = false;
+				} else {
+					fragments = parsers.flatMap((p) => p.getDocFragments({ kind: "unavailable" }).fragments);
+					shouldDeduplicate = true;
+				}
 			}
 			return {
 				brief,
 				description,
-				fragments,
+				fragments: shouldDeduplicate ? require_doc.deduplicateDocFragments(fragments) : fragments,
 				footer
 			};
 		}

package/dist/constructs.js

@@ -3,6 +3,7 @@ import { message, optionName, text, values } from "./message.js";
 import { DependencyRegistry, createDependencySourceState, dependencyId, isDeferredParseState, isDependencySourceState, isPendingDependencySourceState, isWrappedDependencySource, parseWithDependency, wrappedDependencySourceMarker } from "./dependency.js";
 import { dispatchByMode, dispatchIterableByMode } from "./mode-dispatch.js";
 import { extractArgumentMetavars, extractCommandNames, extractOptionNames, isDocHidden, mergeHidden } from "./usage.js";
+import { deduplicateDocFragments } from "./doc.js";
 import { DEFAULT_FIND_SIMILAR_OPTIONS, createErrorWithSuggestions, createSuggestionMessage, deduplicateSuggestions, findSimilar } from "./suggestion.js";
 import { collectLeadingCandidates } from "./usage-internals.js";
 
@@ -471,24 +472,12 @@ function or(...args) {
 				footer = docFragments.footer;
 				fragments = docFragments.fragments;
 			}
-			const entries = fragments.filter((f) => f.type === "entry");
-			const sections = [];
-			for (const fragment of fragments) {
-				if (fragment.type !== "section") continue;
-				if (fragment.title == null) entries.push(...fragment.entries);
-				else sections.push(fragment);
-			}
+			if (state.kind === "unavailable" || state.state == null) fragments = deduplicateDocFragments(fragments);
 			return {
 				brief,
 				description,
 				footer,
-				fragments: [...sections.map((s) => ({
-					...s,
-					type: "section"
-				})), {
-					type: "section",
-					entries
-				}]
+				fragments
 			};
 		}
 	};
@@ -606,8 +595,11 @@ function longestMatch(...args) {
 			let description;
 			let footer;
 			let fragments;
-			if (state.kind === "unavailable" || state.state == null) fragments = parsers.flatMap((p) => p.getDocFragments({ kind: "unavailable" }).fragments);
-			else {
+			let shouldDeduplicate;
+			if (state.kind === "unavailable" || state.state == null) {
+				fragments = parsers.flatMap((p) => p.getDocFragments({ kind: "unavailable" }).fragments);
+				shouldDeduplicate = true;
+			} else {
 				const [i, result] = state.state;
 				if (result.success) {
 					const docResult = parsers[i].getDocFragments({
@@ -618,12 +610,16 @@ function longestMatch(...args) {
 					description = docResult.description;
 					footer = docResult.footer;
 					fragments = docResult.fragments;
-				} else fragments = parsers.flatMap((p) => p.getDocFragments({ kind: "unavailable" }).fragments);
+					shouldDeduplicate = false;
+				} else {
+					fragments = parsers.flatMap((p) => p.getDocFragments({ kind: "unavailable" }).fragments);
+					shouldDeduplicate = true;
+				}
 			}
 			return {
 				brief,
 				description,
-				fragments,
+				fragments: shouldDeduplicate ? deduplicateDocFragments(fragments) : fragments,
 				footer
 			};
 		}

package/dist/doc.cjs

@@ -2,6 +2,118 @@ const require_message = require('./message.cjs');
 const require_usage = require('./usage.cjs');
 
 //#region src/doc.ts
+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).  When duplicates exist,
+* the first occurrence is kept and later ones 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 duplicates removed, preserving insertion order.
+* @since 1.0.0
+*/
+function deduplicateDocEntries(entries) {
+	const seen = /* @__PURE__ */ new Set();
+	const result = [];
+	for (const entry of entries) {
+		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 slots = [];
+	for (const fragment of fragments) if (fragment.type === "entry") 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 (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, []);
+			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.
@@ -327,4 +439,7 @@ function lastLineVisibleLength(text$1) {
 }
 
 //#endregion
+exports.cloneDocEntry = cloneDocEntry;
+exports.deduplicateDocEntries = deduplicateDocEntries;
+exports.deduplicateDocFragments = deduplicateDocFragments;
 exports.formatDocPage = formatDocPage;

package/dist/doc.d.cts

@@ -103,6 +103,40 @@ interface DocFragments {
    */
   readonly footer?: Message;
 }
+/**
+ * Removes duplicate {@link DocEntry} values that share the same surface
+ * syntax (same term type and identifying names).  When duplicates exist,
+ * the first occurrence is kept and later ones 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 duplicates removed, preserving insertion order.
+ * @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.
  *
@@ -291,4 +325,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 };

package/dist/doc.d.ts

@@ -103,6 +103,40 @@ interface DocFragments {
    */
   readonly footer?: Message;
 }
+/**
+ * Removes duplicate {@link DocEntry} values that share the same surface
+ * syntax (same term type and identifying names).  When duplicates exist,
+ * the first occurrence is kept and later ones 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 duplicates removed, preserving insertion order.
+ * @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.
  *
@@ -291,4 +325,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 };

package/dist/doc.js

@@ -1,7 +1,119 @@
-import { formatMessage, text } from "./message.js";
-import { formatUsage, formatUsageTerm } from "./usage.js";
+import { cloneMessage, formatMessage, text } from "./message.js";
+import { cloneUsageTerm, formatUsage, formatUsageTerm } from "./usage.js";
 
 //#region src/doc.ts
+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).  When duplicates exist,
+* the first occurrence is kept and later ones 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 duplicates removed, preserving insertion order.
+* @since 1.0.0
+*/
+function deduplicateDocEntries(entries) {
+	const seen = /* @__PURE__ */ new Set();
+	const result = [];
+	for (const entry of entries) {
+		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 slots = [];
+	for (const fragment of fragments) if (fragment.type === "entry") 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 (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, []);
+			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: cloneUsageTerm(entry.term),
+		...entry.description != null && { description: cloneMessage(entry.description) },
+		...entry.default != null && { default: cloneMessage(entry.default) },
+		...entry.choices != null && { choices: cloneMessage(entry.choices) }
+	};
+}
 /**
 * Classifies a {@link DocSection} by its content type for use in the
 * default smart sort.
@@ -327,4 +439,4 @@ function lastLineVisibleLength(text$1) {
 }
 
 //#endregion
-export { formatDocPage };
+export { cloneDocEntry, deduplicateDocEntries, deduplicateDocFragments, formatDocPage };

package/dist/facade.cjs

@@ -3,9 +3,9 @@ const require_message = require('./message.cjs');
 const require_completion = require('./completion.cjs');
 const require_mode_dispatch = require('./mode-dispatch.cjs');
 const require_usage = require('./usage.cjs');
+const require_doc = require('./doc.cjs');
 const require_constructs = require('./constructs.cjs');
 const require_context = require('./context.cjs');
-const require_doc = require('./doc.cjs');
 const require_modifiers = require('./modifiers.cjs');
 const require_valueparser = require('./valueparser.cjs');
 const require_primitives = require('./primitives.cjs');

package/dist/facade.js

@@ -3,9 +3,9 @@ import { commandLine, formatMessage, lineBreak, message, optionName, text, value
 import { bash, fish, nu, pwsh, zsh } from "./completion.js";
 import { dispatchByMode } from "./mode-dispatch.js";
 import { formatUsage } from "./usage.js";
+import { formatDocPage } from "./doc.js";
 import { group, longestMatch, object } from "./constructs.js";
 import { isPlaceholderValue } from "./context.js";
-import { formatDocPage } from "./doc.js";
 import { multiple, optional, withDefault } from "./modifiers.js";
 import { string } from "./valueparser.js";
 import { argument, command, constant, flag, option } from "./primitives.js";

package/dist/index.cjs

@@ -3,8 +3,8 @@ const require_message = require('./message.cjs');
 const require_completion = require('./completion.cjs');
 const require_dependency = require('./dependency.cjs');
 const require_usage = require('./usage.cjs');
-const require_constructs = require('./constructs.cjs');
 const require_doc = require('./doc.cjs');
+const require_constructs = require('./constructs.cjs');
 const require_modifiers = require('./modifiers.cjs');
 const require_nonempty = require('./nonempty.cjs');
 const require_valueparser = require('./valueparser.cjs');
@@ -23,6 +23,9 @@ exports.checkBooleanOption = require_valueparser.checkBooleanOption;
 exports.checkEnumOption = require_valueparser.checkEnumOption;
 exports.choice = require_valueparser.choice;
 exports.cidr = require_valueparser.cidr;
+exports.cloneDocEntry = require_doc.cloneDocEntry;
+exports.cloneUsage = require_usage.cloneUsage;
+exports.cloneUsageTerm = require_usage.cloneUsageTerm;
 exports.command = require_primitives.command;
 exports.commandLine = require_message.commandLine;
 exports.concat = require_constructs.concat;
@@ -31,6 +34,8 @@ exports.constant = require_primitives.constant;
 exports.createDeferredParseState = require_dependency.createDeferredParseState;
 exports.createDependencySourceState = require_dependency.createDependencySourceState;
 exports.createPendingDependencySourceState = require_dependency.createPendingDependencySourceState;
+exports.deduplicateDocEntries = require_doc.deduplicateDocEntries;
+exports.deduplicateDocFragments = require_doc.deduplicateDocFragments;
 exports.defaultValues = require_dependency.defaultValues;
 exports.deferredParseMarker = require_dependency.deferredParseMarker;
 exports.dependency = require_dependency.dependency;

package/dist/index.d.cts

@@ -1,8 +1,8 @@
 import { Annotations, ParseOptions, annotationKey, getAnnotations } from "./annotations.cjs";
 import { NonEmptyString, ensureNonEmptyString, isNonEmptyString } from "./nonempty.cjs";
 import { Message, MessageFormatOptions, MessageTerm, ValueSetOptions, commandLine, envVar, formatMessage, lineBreak, link, message, metavar, optionName, optionNames, text, value, valueSet, values } from "./message.cjs";
-import { HiddenVisibility, OptionName, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, extractArgumentMetavars, extractCommandNames, extractOptionNames, formatUsage, formatUsageTerm, isDocHidden, isSuggestionHidden, isUsageHidden, mergeHidden, normalizeUsage } from "./usage.cjs";
-import { DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, ShowChoicesOptions, ShowDefaultOptions, formatDocPage } from "./doc.cjs";
+import { HiddenVisibility, OptionName, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, cloneUsage, cloneUsageTerm, extractArgumentMetavars, extractCommandNames, extractOptionNames, formatUsage, formatUsageTerm, isDocHidden, isSuggestionHidden, isUsageHidden, mergeHidden, normalizeUsage } from "./usage.cjs";
+import { DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, ShowChoicesOptions, ShowDefaultOptions, cloneDocEntry, deduplicateDocEntries, deduplicateDocFragments, formatDocPage } from "./doc.cjs";
 import { ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, DomainOptions, EmailOptions, FloatOptions, HostnameOptions, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, LocaleOptions, MacAddressOptions, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, SocketAddressOptions, SocketAddressValue, StringOptions, UrlOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, checkBooleanOption, checkEnumOption, choice, cidr, domain, email, float, hostname, integer, ip, ipv4, ipv6, isValueParser, locale, macAddress, port, portRange, socketAddress, string, url, uuid } from "./valueparser.cjs";
 import { ConditionalErrorOptions, ConditionalOptions, DuplicateOptionError, GroupOptions, LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, NoMatchContext, ObjectErrorOptions, ObjectOptions, OrErrorOptions, OrOptions, TupleOptions, concat, conditional, group, longestMatch, merge, object, or, tuple } from "./constructs.cjs";
 import { MultipleErrorOptions, MultipleOptions, WithDefaultError, WithDefaultOptions, map, multiple, nonEmpty, optional, withDefault } from "./modifiers.cjs";
@@ -12,4 +12,4 @@ import { CombineModes, DocState, InferMode, InferValue, Mode, ModeIterable, Mode
 import { ShellCompletion, bash, fish, nu, pwsh, zsh } from "./completion.cjs";
 import { ParserValuePlaceholder, SourceContext } from "./context.cjs";
 import { CommandSubConfig, ContextOptionsParam, ExtractRequiredOptions, OptionSubConfig, RunOptions, RunParserError, RunWithOptions, SubstituteParserValue, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync } from "./facade.cjs";
-export { type Annotations, AnyDependencySource, ArgumentErrorOptions, ArgumentOptions, ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, CombineMode, CombineModes, CombinedDependencyMode, CommandErrorOptions, CommandOptions, CommandSubConfig, ConditionalErrorOptions, ConditionalOptions, ContextOptionsParam, DeferredParseState, DependencyError, DependencyMode, DependencyRegistry, DependencySource, DependencySourceState, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, DocState, DomainOptions, DuplicateOptionError, EmailOptions, ExtractRequiredOptions, FlagErrorOptions, FlagOptions, FloatOptions, GroupOptions, HiddenVisibility, HostnameOptions, InferMode, InferValue, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, LocaleOptions, LongestMatchErrorOptions, LongestMatchOptions, MacAddressOptions, MergeOptions, type Message, type MessageFormatOptions, type MessageTerm, Mode, ModeIterable, ModeValue, MultipleErrorOptions, MultipleOptions, NoMatchContext, NonEmptyString, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionName, OptionOptions, OptionState, OptionSubConfig, OrErrorOptions, OrOptions, type ParseOptions, Parser, ParserContext, ParserResult, ParserValuePlaceholder, PassThroughFormat, PassThroughOptions, PendingDependencySourceState, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, ResolvedDependency, Result, RunOptions, RunParserError, RunWithOptions, ShellCompletion, ShowChoicesOptions, ShowDefaultOptions, SocketAddressOptions, SocketAddressValue, SourceContext, StringOptions, SubstituteParserValue, Suggestion, TupleOptions, UrlOptions, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, type ValueSetOptions, WithDefaultError, WithDefaultOptions, annotationKey, argument, bash, checkBooleanOption, checkEnumOption, choice, cidr, command, commandLine, concat, conditional, constant, createDeferredParseState, createDependencySourceState, createPendingDependencySourceState, defaultValues, deferredParseMarker, dependency, dependencyId, dependencyIds, dependencySourceMarker, dependencySourceStateMarker, deriveFrom, deriveFromAsync, deriveFromSync, derivedValueParserMarker, domain, email, ensureNonEmptyString, envVar, extractArgumentMetavars, extractCommandNames, extractOptionNames, fail, fish, flag, float, formatDependencyError, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getAnnotations, getDefaultValuesFunction, getDependencyIds, getDocPage, getDocPageAsync, getDocPageSync, group, hostname, integer, ip, ipv4, ipv6, isDeferredParseState, isDependencySource, isDependencySourceState, isDerivedValueParser, isDocHidden, isNonEmptyString, isPendingDependencySourceState, isSuggestionHidden, isUsageHidden, isValueParser, isWrappedDependencySource, lineBreak, link, locale, longestMatch, macAddress, map, merge, mergeHidden, message, metavar, multiple, nonEmpty, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, parse, parseAsync, parseSync, parseWithDependency, passThrough, pendingDependencySourceStateMarker, port, portRange, pwsh, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync, socketAddress, string, suggest, suggestAsync, suggestSync, suggestWithDependency, text, transformsDependencyValue, transformsDependencyValueMarker, tuple, url, uuid, value, valueSet, values, withDefault, wrappedDependencySourceMarker, zsh };
+export { type Annotations, AnyDependencySource, ArgumentErrorOptions, ArgumentOptions, ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, CombineMode, CombineModes, CombinedDependencyMode, CommandErrorOptions, CommandOptions, CommandSubConfig, ConditionalErrorOptions, ConditionalOptions, ContextOptionsParam, DeferredParseState, DependencyError, DependencyMode, DependencyRegistry, DependencySource, DependencySourceState, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, DocState, DomainOptions, DuplicateOptionError, EmailOptions, ExtractRequiredOptions, FlagErrorOptions, FlagOptions, FloatOptions, GroupOptions, HiddenVisibility, HostnameOptions, InferMode, InferValue, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, LocaleOptions, LongestMatchErrorOptions, LongestMatchOptions, MacAddressOptions, MergeOptions, type Message, type MessageFormatOptions, type MessageTerm, Mode, ModeIterable, ModeValue, MultipleErrorOptions, MultipleOptions, NoMatchContext, NonEmptyString, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionName, OptionOptions, OptionState, OptionSubConfig, OrErrorOptions, OrOptions, type ParseOptions, Parser, ParserContext, ParserResult, ParserValuePlaceholder, PassThroughFormat, PassThroughOptions, PendingDependencySourceState, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, ResolvedDependency, Result, RunOptions, RunParserError, RunWithOptions, ShellCompletion, ShowChoicesOptions, ShowDefaultOptions, SocketAddressOptions, SocketAddressValue, SourceContext, StringOptions, SubstituteParserValue, Suggestion, TupleOptions, UrlOptions, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, type ValueSetOptions, WithDefaultError, WithDefaultOptions, annotationKey, argument, bash, checkBooleanOption, checkEnumOption, choice, cidr, cloneDocEntry, cloneUsage, cloneUsageTerm, command, commandLine, concat, conditional, constant, createDeferredParseState, createDependencySourceState, createPendingDependencySourceState, deduplicateDocEntries, deduplicateDocFragments, defaultValues, deferredParseMarker, dependency, dependencyId, dependencyIds, dependencySourceMarker, dependencySourceStateMarker, deriveFrom, deriveFromAsync, deriveFromSync, derivedValueParserMarker, domain, email, ensureNonEmptyString, envVar, extractArgumentMetavars, extractCommandNames, extractOptionNames, fail, fish, flag, float, formatDependencyError, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getAnnotations, getDefaultValuesFunction, getDependencyIds, getDocPage, getDocPageAsync, getDocPageSync, group, hostname, integer, ip, ipv4, ipv6, isDeferredParseState, isDependencySource, isDependencySourceState, isDerivedValueParser, isDocHidden, isNonEmptyString, isPendingDependencySourceState, isSuggestionHidden, isUsageHidden, isValueParser, isWrappedDependencySource, lineBreak, link, locale, longestMatch, macAddress, map, merge, mergeHidden, message, metavar, multiple, nonEmpty, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, parse, parseAsync, parseSync, parseWithDependency, passThrough, pendingDependencySourceStateMarker, port, portRange, pwsh, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync, socketAddress, string, suggest, suggestAsync, suggestSync, suggestWithDependency, text, transformsDependencyValue, transformsDependencyValueMarker, tuple, url, uuid, value, valueSet, values, withDefault, wrappedDependencySourceMarker, zsh };

package/dist/index.d.ts

@@ -1,8 +1,8 @@
 import { Annotations, ParseOptions, annotationKey, getAnnotations } from "./annotations.js";
 import { NonEmptyString, ensureNonEmptyString, isNonEmptyString } from "./nonempty.js";
 import { Message, MessageFormatOptions, MessageTerm, ValueSetOptions, commandLine, envVar, formatMessage, lineBreak, link, message, metavar, optionName, optionNames, text, value, valueSet, values } from "./message.js";
-import { HiddenVisibility, OptionName, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, extractArgumentMetavars, extractCommandNames, extractOptionNames, formatUsage, formatUsageTerm, isDocHidden, isSuggestionHidden, isUsageHidden, mergeHidden, normalizeUsage } from "./usage.js";
-import { DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, ShowChoicesOptions, ShowDefaultOptions, formatDocPage } from "./doc.js";
+import { HiddenVisibility, OptionName, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, cloneUsage, cloneUsageTerm, extractArgumentMetavars, extractCommandNames, extractOptionNames, formatUsage, formatUsageTerm, isDocHidden, isSuggestionHidden, isUsageHidden, mergeHidden, normalizeUsage } from "./usage.js";
+import { DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, ShowChoicesOptions, ShowDefaultOptions, cloneDocEntry, deduplicateDocEntries, deduplicateDocFragments, formatDocPage } from "./doc.js";
 import { ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, DomainOptions, EmailOptions, FloatOptions, HostnameOptions, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, LocaleOptions, MacAddressOptions, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, SocketAddressOptions, SocketAddressValue, StringOptions, UrlOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, checkBooleanOption, checkEnumOption, choice, cidr, domain, email, float, hostname, integer, ip, ipv4, ipv6, isValueParser, locale, macAddress, port, portRange, socketAddress, string, url, uuid } from "./valueparser.js";
 import { ConditionalErrorOptions, ConditionalOptions, DuplicateOptionError, GroupOptions, LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, NoMatchContext, ObjectErrorOptions, ObjectOptions, OrErrorOptions, OrOptions, TupleOptions, concat, conditional, group, longestMatch, merge, object, or, tuple } from "./constructs.js";
 import { MultipleErrorOptions, MultipleOptions, WithDefaultError, WithDefaultOptions, map, multiple, nonEmpty, optional, withDefault } from "./modifiers.js";
@@ -12,4 +12,4 @@ import { CombineModes, DocState, InferMode, InferValue, Mode, ModeIterable, Mode
 import { ShellCompletion, bash, fish, nu, pwsh, zsh } from "./completion.js";
 import { ParserValuePlaceholder, SourceContext } from "./context.js";
 import { CommandSubConfig, ContextOptionsParam, ExtractRequiredOptions, OptionSubConfig, RunOptions, RunParserError, RunWithOptions, SubstituteParserValue, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync } from "./facade.js";
-export { type Annotations, AnyDependencySource, ArgumentErrorOptions, ArgumentOptions, ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, CombineMode, CombineModes, CombinedDependencyMode, CommandErrorOptions, CommandOptions, CommandSubConfig, ConditionalErrorOptions, ConditionalOptions, ContextOptionsParam, DeferredParseState, DependencyError, DependencyMode, DependencyRegistry, DependencySource, DependencySourceState, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, DocState, DomainOptions, DuplicateOptionError, EmailOptions, ExtractRequiredOptions, FlagErrorOptions, FlagOptions, FloatOptions, GroupOptions, HiddenVisibility, HostnameOptions, InferMode, InferValue, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, LocaleOptions, LongestMatchErrorOptions, LongestMatchOptions, MacAddressOptions, MergeOptions, type Message, type MessageFormatOptions, type MessageTerm, Mode, ModeIterable, ModeValue, MultipleErrorOptions, MultipleOptions, NoMatchContext, NonEmptyString, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionName, OptionOptions, OptionState, OptionSubConfig, OrErrorOptions, OrOptions, type ParseOptions, Parser, ParserContext, ParserResult, ParserValuePlaceholder, PassThroughFormat, PassThroughOptions, PendingDependencySourceState, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, ResolvedDependency, Result, RunOptions, RunParserError, RunWithOptions, ShellCompletion, ShowChoicesOptions, ShowDefaultOptions, SocketAddressOptions, SocketAddressValue, SourceContext, StringOptions, SubstituteParserValue, Suggestion, TupleOptions, UrlOptions, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, type ValueSetOptions, WithDefaultError, WithDefaultOptions, annotationKey, argument, bash, checkBooleanOption, checkEnumOption, choice, cidr, command, commandLine, concat, conditional, constant, createDeferredParseState, createDependencySourceState, createPendingDependencySourceState, defaultValues, deferredParseMarker, dependency, dependencyId, dependencyIds, dependencySourceMarker, dependencySourceStateMarker, deriveFrom, deriveFromAsync, deriveFromSync, derivedValueParserMarker, domain, email, ensureNonEmptyString, envVar, extractArgumentMetavars, extractCommandNames, extractOptionNames, fail, fish, flag, float, formatDependencyError, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getAnnotations, getDefaultValuesFunction, getDependencyIds, getDocPage, getDocPageAsync, getDocPageSync, group, hostname, integer, ip, ipv4, ipv6, isDeferredParseState, isDependencySource, isDependencySourceState, isDerivedValueParser, isDocHidden, isNonEmptyString, isPendingDependencySourceState, isSuggestionHidden, isUsageHidden, isValueParser, isWrappedDependencySource, lineBreak, link, locale, longestMatch, macAddress, map, merge, mergeHidden, message, metavar, multiple, nonEmpty, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, parse, parseAsync, parseSync, parseWithDependency, passThrough, pendingDependencySourceStateMarker, port, portRange, pwsh, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync, socketAddress, string, suggest, suggestAsync, suggestSync, suggestWithDependency, text, transformsDependencyValue, transformsDependencyValueMarker, tuple, url, uuid, value, valueSet, values, withDefault, wrappedDependencySourceMarker, zsh };
+export { type Annotations, AnyDependencySource, ArgumentErrorOptions, ArgumentOptions, ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, CombineMode, CombineModes, CombinedDependencyMode, CommandErrorOptions, CommandOptions, CommandSubConfig, ConditionalErrorOptions, ConditionalOptions, ContextOptionsParam, DeferredParseState, DependencyError, DependencyMode, DependencyRegistry, DependencySource, DependencySourceState, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, DocState, DomainOptions, DuplicateOptionError, EmailOptions, ExtractRequiredOptions, FlagErrorOptions, FlagOptions, FloatOptions, GroupOptions, HiddenVisibility, HostnameOptions, InferMode, InferValue, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, LocaleOptions, LongestMatchErrorOptions, LongestMatchOptions, MacAddressOptions, MergeOptions, type Message, type MessageFormatOptions, type MessageTerm, Mode, ModeIterable, ModeValue, MultipleErrorOptions, MultipleOptions, NoMatchContext, NonEmptyString, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionName, OptionOptions, OptionState, OptionSubConfig, OrErrorOptions, OrOptions, type ParseOptions, Parser, ParserContext, ParserResult, ParserValuePlaceholder, PassThroughFormat, PassThroughOptions, PendingDependencySourceState, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, ResolvedDependency, Result, RunOptions, RunParserError, RunWithOptions, ShellCompletion, ShowChoicesOptions, ShowDefaultOptions, SocketAddressOptions, SocketAddressValue, SourceContext, StringOptions, SubstituteParserValue, Suggestion, TupleOptions, UrlOptions, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, type ValueSetOptions, WithDefaultError, WithDefaultOptions, annotationKey, argument, bash, checkBooleanOption, checkEnumOption, choice, cidr, cloneDocEntry, cloneUsage, cloneUsageTerm, command, commandLine, concat, conditional, constant, createDeferredParseState, createDependencySourceState, createPendingDependencySourceState, deduplicateDocEntries, deduplicateDocFragments, defaultValues, deferredParseMarker, dependency, dependencyId, dependencyIds, dependencySourceMarker, dependencySourceStateMarker, deriveFrom, deriveFromAsync, deriveFromSync, derivedValueParserMarker, domain, email, ensureNonEmptyString, envVar, extractArgumentMetavars, extractCommandNames, extractOptionNames, fail, fish, flag, float, formatDependencyError, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getAnnotations, getDefaultValuesFunction, getDependencyIds, getDocPage, getDocPageAsync, getDocPageSync, group, hostname, integer, ip, ipv4, ipv6, isDeferredParseState, isDependencySource, isDependencySourceState, isDerivedValueParser, isDocHidden, isNonEmptyString, isPendingDependencySourceState, isSuggestionHidden, isUsageHidden, isValueParser, isWrappedDependencySource, lineBreak, link, locale, longestMatch, macAddress, map, merge, mergeHidden, message, metavar, multiple, nonEmpty, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, parse, parseAsync, parseSync, parseWithDependency, passThrough, pendingDependencySourceStateMarker, port, portRange, pwsh, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync, socketAddress, string, suggest, suggestAsync, suggestSync, suggestWithDependency, text, transformsDependencyValue, transformsDependencyValueMarker, tuple, url, uuid, value, valueSet, values, withDefault, wrappedDependencySourceMarker, zsh };

package/dist/index.js

@@ -2,9 +2,9 @@ import { annotationKey, getAnnotations } from "./annotations.js";
 import { commandLine, envVar, formatMessage, lineBreak, link, message, metavar, optionName, optionNames, text, value, valueSet, values } from "./message.js";
 import { bash, fish, nu, pwsh, zsh } from "./completion.js";
 import { DependencyRegistry, createDeferredParseState, createDependencySourceState, createPendingDependencySourceState, defaultValues, deferredParseMarker, dependency, dependencyId, dependencyIds, dependencySourceMarker, dependencySourceStateMarker, deriveFrom, deriveFromAsync, deriveFromSync, derivedValueParserMarker, formatDependencyError, getDefaultValuesFunction, getDependencyIds, isDeferredParseState, isDependencySource, isDependencySourceState, isDerivedValueParser, isPendingDependencySourceState, isWrappedDependencySource, parseWithDependency, pendingDependencySourceStateMarker, suggestWithDependency, transformsDependencyValue, transformsDependencyValueMarker, wrappedDependencySourceMarker } from "./dependency.js";
-import { extractArgumentMetavars, extractCommandNames, extractOptionNames, formatUsage, formatUsageTerm, isDocHidden, isSuggestionHidden, isUsageHidden, mergeHidden, normalizeUsage } from "./usage.js";
+import { cloneUsage, cloneUsageTerm, extractArgumentMetavars, extractCommandNames, extractOptionNames, formatUsage, formatUsageTerm, isDocHidden, isSuggestionHidden, isUsageHidden, mergeHidden, normalizeUsage } from "./usage.js";
+import { cloneDocEntry, deduplicateDocEntries, deduplicateDocFragments, formatDocPage } from "./doc.js";
 import { DuplicateOptionError, concat, conditional, group, longestMatch, merge, object, or, tuple } from "./constructs.js";
-import { formatDocPage } from "./doc.js";
 import { WithDefaultError, map, multiple, nonEmpty, optional, withDefault } from "./modifiers.js";
 import { ensureNonEmptyString, isNonEmptyString } from "./nonempty.js";
 import { checkBooleanOption, checkEnumOption, choice, cidr, domain, email, float, hostname, integer, ip, ipv4, ipv6, isValueParser, locale, macAddress, port, portRange, socketAddress, string, url, uuid } from "./valueparser.js";
@@ -12,4 +12,4 @@ import { argument, command, constant, fail, flag, option, passThrough } from "./
 import { getDocPage, getDocPageAsync, getDocPageSync, parse, parseAsync, parseSync, suggest, suggestAsync, suggestSync } from "./parser.js";
 import { RunParserError, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync } from "./facade.js";
 
-export { DependencyRegistry, DuplicateOptionError, RunParserError, WithDefaultError, annotationKey, argument, bash, checkBooleanOption, checkEnumOption, choice, cidr, command, commandLine, concat, conditional, constant, createDeferredParseState, createDependencySourceState, createPendingDependencySourceState, defaultValues, deferredParseMarker, dependency, dependencyId, dependencyIds, dependencySourceMarker, dependencySourceStateMarker, deriveFrom, deriveFromAsync, deriveFromSync, derivedValueParserMarker, domain, email, ensureNonEmptyString, envVar, extractArgumentMetavars, extractCommandNames, extractOptionNames, fail, fish, flag, float, formatDependencyError, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getAnnotations, getDefaultValuesFunction, getDependencyIds, getDocPage, getDocPageAsync, getDocPageSync, group, hostname, integer, ip, ipv4, ipv6, isDeferredParseState, isDependencySource, isDependencySourceState, isDerivedValueParser, isDocHidden, isNonEmptyString, isPendingDependencySourceState, isSuggestionHidden, isUsageHidden, isValueParser, isWrappedDependencySource, lineBreak, link, locale, longestMatch, macAddress, map, merge, mergeHidden, message, metavar, multiple, nonEmpty, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, parse, parseAsync, parseSync, parseWithDependency, passThrough, pendingDependencySourceStateMarker, port, portRange, pwsh, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync, socketAddress, string, suggest, suggestAsync, suggestSync, suggestWithDependency, text, transformsDependencyValue, transformsDependencyValueMarker, tuple, url, uuid, value, valueSet, values, withDefault, wrappedDependencySourceMarker, zsh };
+export { DependencyRegistry, DuplicateOptionError, RunParserError, WithDefaultError, annotationKey, argument, bash, checkBooleanOption, checkEnumOption, choice, cidr, cloneDocEntry, cloneUsage, cloneUsageTerm, command, commandLine, concat, conditional, constant, createDeferredParseState, createDependencySourceState, createPendingDependencySourceState, deduplicateDocEntries, deduplicateDocFragments, defaultValues, deferredParseMarker, dependency, dependencyId, dependencyIds, dependencySourceMarker, dependencySourceStateMarker, deriveFrom, deriveFromAsync, deriveFromSync, derivedValueParserMarker, domain, email, ensureNonEmptyString, envVar, extractArgumentMetavars, extractCommandNames, extractOptionNames, fail, fish, flag, float, formatDependencyError, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getAnnotations, getDefaultValuesFunction, getDependencyIds, getDocPage, getDocPageAsync, getDocPageSync, group, hostname, integer, ip, ipv4, ipv6, isDeferredParseState, isDependencySource, isDependencySourceState, isDerivedValueParser, isDocHidden, isNonEmptyString, isPendingDependencySourceState, isSuggestionHidden, isUsageHidden, isValueParser, isWrappedDependencySource, lineBreak, link, locale, longestMatch, macAddress, map, merge, mergeHidden, message, metavar, multiple, nonEmpty, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, parse, parseAsync, parseSync, parseWithDependency, passThrough, pendingDependencySourceStateMarker, port, portRange, pwsh, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync, socketAddress, string, suggest, suggestAsync, suggestSync, suggestWithDependency, text, transformsDependencyValue, transformsDependencyValueMarker, tuple, url, uuid, value, valueSet, values, withDefault, wrappedDependencySourceMarker, zsh };

package/dist/message.cjs

@@ -1,6 +1,44 @@
 
 //#region src/message.ts
 /**
+* Creates a deep clone of a {@link MessageTerm}.  Most variants contain only
+* primitive fields and are cloned via object spread.  The `url` variant
+* receives a new `URL` object (since `structuredClone` cannot handle `URL`
+* on Node.js), and array-valued fields (`optionNames`, `values`) are
+* shallow-copied.
+*
+* @param term The message term to clone.
+* @returns A structurally equal but referentially distinct copy.
+* @since 1.0.0
+*/
+function cloneMessageTerm(term) {
+	switch (term.type) {
+		case "optionNames": return {
+			...term,
+			optionNames: [...term.optionNames]
+		};
+		case "values": return {
+			...term,
+			values: [...term.values]
+		};
+		case "url": return {
+			type: "url",
+			url: new URL(term.url.href)
+		};
+		default: return { ...term };
+	}
+}
+/**
+* Creates a deep clone of a {@link Message} array and all of its terms.
+*
+* @param msg The message to clone.
+* @returns A structurally equal but referentially distinct copy.
+* @since 1.0.0
+*/
+function cloneMessage(msg) {
+	return msg.map(cloneMessageTerm);
+}
+/**
 * Creates a structured message with template strings and values.
 *
 * This function allows creating messages where specific values can be
@@ -386,6 +424,8 @@ function formatMessage(msg, options = {}) {
 }
 
 //#endregion
+exports.cloneMessage = cloneMessage;
+exports.cloneMessageTerm = cloneMessageTerm;
 exports.commandLine = commandLine;
 exports.envVar = envVar;
 exports.formatMessage = formatMessage;

package/dist/message.d.cts

@@ -151,6 +151,26 @@ type MessageTerm =
  * displayed to the user with specific formatting.
  */
 type Message = readonly MessageTerm[];
+/**
+ * Creates a deep clone of a {@link MessageTerm}.  Most variants contain only
+ * primitive fields and are cloned via object spread.  The `url` variant
+ * receives a new `URL` object (since `structuredClone` cannot handle `URL`
+ * on Node.js), and array-valued fields (`optionNames`, `values`) are
+ * shallow-copied.
+ *
+ * @param term The message term to clone.
+ * @returns A structurally equal but referentially distinct copy.
+ * @since 1.0.0
+ */
+declare function cloneMessageTerm(term: MessageTerm): MessageTerm;
+/**
+ * Creates a deep clone of a {@link Message} array and all of its terms.
+ *
+ * @param msg The message to clone.
+ * @returns A structurally equal but referentially distinct copy.
+ * @since 1.0.0
+ */
+declare function cloneMessage(msg: Message): Message;
 /**
  * Creates a structured message with template strings and values.
  *
@@ -380,4 +400,4 @@ interface MessageFormatOptions {
  */
 declare function formatMessage(msg: Message, options?: MessageFormatOptions): string;
 //#endregion
-export { Message, MessageFormatOptions, MessageTerm, ValueSetOptions, commandLine, envVar, formatMessage, lineBreak, link, message, metavar, optionName, optionNames, text, url, value, valueSet, values };
+export { Message, MessageFormatOptions, MessageTerm, ValueSetOptions, cloneMessage, cloneMessageTerm, commandLine, envVar, formatMessage, lineBreak, link, message, metavar, optionName, optionNames, text, url, value, valueSet, values };

package/dist/message.d.ts

@@ -151,6 +151,26 @@ type MessageTerm =
  * displayed to the user with specific formatting.
  */
 type Message = readonly MessageTerm[];
+/**
+ * Creates a deep clone of a {@link MessageTerm}.  Most variants contain only
+ * primitive fields and are cloned via object spread.  The `url` variant
+ * receives a new `URL` object (since `structuredClone` cannot handle `URL`
+ * on Node.js), and array-valued fields (`optionNames`, `values`) are
+ * shallow-copied.
+ *
+ * @param term The message term to clone.
+ * @returns A structurally equal but referentially distinct copy.
+ * @since 1.0.0
+ */
+declare function cloneMessageTerm(term: MessageTerm): MessageTerm;
+/**
+ * Creates a deep clone of a {@link Message} array and all of its terms.
+ *
+ * @param msg The message to clone.
+ * @returns A structurally equal but referentially distinct copy.
+ * @since 1.0.0
+ */
+declare function cloneMessage(msg: Message): Message;
 /**
  * Creates a structured message with template strings and values.
  *
@@ -380,4 +400,4 @@ interface MessageFormatOptions {
  */
 declare function formatMessage(msg: Message, options?: MessageFormatOptions): string;
 //#endregion
-export { Message, MessageFormatOptions, MessageTerm, ValueSetOptions, commandLine, envVar, formatMessage, lineBreak, link, message, metavar, optionName, optionNames, text, url, value, valueSet, values };
+export { Message, MessageFormatOptions, MessageTerm, ValueSetOptions, cloneMessage, cloneMessageTerm, commandLine, envVar, formatMessage, lineBreak, link, message, metavar, optionName, optionNames, text, url, value, valueSet, values };

package/dist/message.js

@@ -1,5 +1,43 @@
 //#region src/message.ts
 /**
+* Creates a deep clone of a {@link MessageTerm}.  Most variants contain only
+* primitive fields and are cloned via object spread.  The `url` variant
+* receives a new `URL` object (since `structuredClone` cannot handle `URL`
+* on Node.js), and array-valued fields (`optionNames`, `values`) are
+* shallow-copied.
+*
+* @param term The message term to clone.
+* @returns A structurally equal but referentially distinct copy.
+* @since 1.0.0
+*/
+function cloneMessageTerm(term) {
+	switch (term.type) {
+		case "optionNames": return {
+			...term,
+			optionNames: [...term.optionNames]
+		};
+		case "values": return {
+			...term,
+			values: [...term.values]
+		};
+		case "url": return {
+			type: "url",
+			url: new URL(term.url.href)
+		};
+		default: return { ...term };
+	}
+}
+/**
+* Creates a deep clone of a {@link Message} array and all of its terms.
+*
+* @param msg The message to clone.
+* @returns A structurally equal but referentially distinct copy.
+* @since 1.0.0
+*/
+function cloneMessage(msg) {
+	return msg.map(cloneMessageTerm);
+}
+/**
 * Creates a structured message with template strings and values.
 *
 * This function allows creating messages where specific values can be
@@ -385,4 +423,4 @@ function formatMessage(msg, options = {}) {
 }
 
 //#endregion
-export { commandLine, envVar, formatMessage, lineBreak, link, message, metavar, optionName, optionNames, text, url, value, valueSet, values };
+export { cloneMessage, cloneMessageTerm, commandLine, envVar, formatMessage, lineBreak, link, message, metavar, optionName, optionNames, text, url, value, valueSet, values };

package/dist/parser.cjs

@@ -2,6 +2,7 @@ const require_annotations = require('./annotations.cjs');
 const require_message = require('./message.cjs');
 const require_mode_dispatch = require('./mode-dispatch.cjs');
 const require_usage = require('./usage.cjs');
+const require_doc = require('./doc.cjs');
 const require_constructs = require('./constructs.cjs');
 const require_modifiers = require('./modifiers.cjs');
 const require_primitives = require('./primitives.cjs');
@@ -388,13 +389,13 @@ function buildDocPage(parser, context, args) {
 			untitledSection = { entries: [] };
 			buildingSections.push(untitledSection);
 		}
-		untitledSection.entries.push(fragment);
+		untitledSection.entries.push(require_doc.cloneDocEntry(fragment));
 	} else if (fragment.type === "section") if (fragment.title == null) {
 		if (untitledSection == null) {
 			untitledSection = { entries: [] };
 			buildingSections.push(untitledSection);
 		}
-		untitledSection.entries.push(...fragment.entries);
+		untitledSection.entries.push(...fragment.entries.map(require_doc.cloneDocEntry));
 	} else {
 		let section = titledSectionMap.get(fragment.title);
 		if (section == null) {
@@ -405,15 +406,15 @@ function buildDocPage(parser, context, args) {
 			titledSectionMap.set(fragment.title, section);
 			buildingSections.push(section);
 		}
-		section.entries.push(...fragment.entries);
+		section.entries.push(...fragment.entries.map(require_doc.cloneDocEntry));
 	}
 	const sections = buildingSections;
-	const usage = [...require_usage.normalizeUsage(parser.usage)];
+	const usage = require_usage.cloneUsage(require_usage.normalizeUsage(parser.usage));
 	const maybeApplyCommandUsageLine = (term, arg, isLastArg, usageIndex) => {
 		if (term?.type !== "command" || term.name !== arg || !isLastArg || term.usageLine == null) return;
-		const defaultUsageLine = usage.slice(usageIndex + 1);
+		const defaultUsageLine = require_usage.cloneUsage(usage.slice(usageIndex + 1));
 		const customUsageLine = typeof term.usageLine === "function" ? term.usageLine(defaultUsageLine) : term.usageLine;
-		const normalizedCustomUsageLine = require_usage.normalizeUsage(customUsageLine);
+		const normalizedCustomUsageLine = require_usage.cloneUsage(require_usage.normalizeUsage(customUsageLine));
 		usage.splice(usageIndex + 1, usage.length - (usageIndex + 1), ...normalizedCustomUsageLine);
 	};
 	let i = 0;
@@ -434,17 +435,18 @@ function buildDocPage(parser, context, args) {
 	if (effectiveArgs.length === 0 && usage.length > 0) {
 		const first = usage[0];
 		if (first.type === "command" && first.usageLine != null) {
-			const defaultUsageLine = usage.slice(1);
+			const defaultUsageLine = require_usage.cloneUsage(usage.slice(1));
 			const customUsageLine = typeof first.usageLine === "function" ? first.usageLine(defaultUsageLine) : first.usageLine;
-			usage.splice(1, usage.length - 1, ...require_usage.normalizeUsage(customUsageLine));
+			const normalizedCustomUsageLine = require_usage.cloneUsage(require_usage.normalizeUsage(customUsageLine));
+			usage.splice(1, usage.length - 1, ...normalizedCustomUsageLine);
 		}
 	}
 	return {
 		usage,
 		sections,
-		...brief != null && { brief },
-		...description != null && { description },
-		...footer != null && { footer }
+		...brief != null && { brief: require_message.cloneMessage(brief) },
+		...description != null && { description: require_message.cloneMessage(description) },
+		...footer != null && { footer: require_message.cloneMessage(footer) }
 	};
 }
 

package/dist/parser.js

@@ -1,7 +1,8 @@
 import { injectAnnotations, isInjectedAnnotationWrapper, unwrapInjectedAnnotationWrapper } from "./annotations.js";
-import { message } from "./message.js";
+import { cloneMessage, message } from "./message.js";
 import { dispatchByMode } from "./mode-dispatch.js";
-import { normalizeUsage } from "./usage.js";
+import { cloneUsage, normalizeUsage } from "./usage.js";
+import { cloneDocEntry } from "./doc.js";
 import { DuplicateOptionError, concat, conditional, group, longestMatch, merge, object, or, tuple } from "./constructs.js";
 import { WithDefaultError, map, multiple, nonEmpty, optional, withDefault } from "./modifiers.js";
 import { argument, command, constant, fail, flag, option, passThrough } from "./primitives.js";
@@ -388,13 +389,13 @@ function buildDocPage(parser, context, args) {
 			untitledSection = { entries: [] };
 			buildingSections.push(untitledSection);
 		}
-		untitledSection.entries.push(fragment);
+		untitledSection.entries.push(cloneDocEntry(fragment));
 	} else if (fragment.type === "section") if (fragment.title == null) {
 		if (untitledSection == null) {
 			untitledSection = { entries: [] };
 			buildingSections.push(untitledSection);
 		}
-		untitledSection.entries.push(...fragment.entries);
+		untitledSection.entries.push(...fragment.entries.map(cloneDocEntry));
 	} else {
 		let section = titledSectionMap.get(fragment.title);
 		if (section == null) {
@@ -405,15 +406,15 @@ function buildDocPage(parser, context, args) {
 			titledSectionMap.set(fragment.title, section);
 			buildingSections.push(section);
 		}
-		section.entries.push(...fragment.entries);
+		section.entries.push(...fragment.entries.map(cloneDocEntry));
 	}
 	const sections = buildingSections;
-	const usage = [...normalizeUsage(parser.usage)];
+	const usage = cloneUsage(normalizeUsage(parser.usage));
 	const maybeApplyCommandUsageLine = (term, arg, isLastArg, usageIndex) => {
 		if (term?.type !== "command" || term.name !== arg || !isLastArg || term.usageLine == null) return;
-		const defaultUsageLine = usage.slice(usageIndex + 1);
+		const defaultUsageLine = cloneUsage(usage.slice(usageIndex + 1));
 		const customUsageLine = typeof term.usageLine === "function" ? term.usageLine(defaultUsageLine) : term.usageLine;
-		const normalizedCustomUsageLine = normalizeUsage(customUsageLine);
+		const normalizedCustomUsageLine = cloneUsage(normalizeUsage(customUsageLine));
 		usage.splice(usageIndex + 1, usage.length - (usageIndex + 1), ...normalizedCustomUsageLine);
 	};
 	let i = 0;
@@ -434,17 +435,18 @@ function buildDocPage(parser, context, args) {
 	if (effectiveArgs.length === 0 && usage.length > 0) {
 		const first = usage[0];
 		if (first.type === "command" && first.usageLine != null) {
-			const defaultUsageLine = usage.slice(1);
+			const defaultUsageLine = cloneUsage(usage.slice(1));
 			const customUsageLine = typeof first.usageLine === "function" ? first.usageLine(defaultUsageLine) : first.usageLine;
-			usage.splice(1, usage.length - 1, ...normalizeUsage(customUsageLine));
+			const normalizedCustomUsageLine = cloneUsage(normalizeUsage(customUsageLine));
+			usage.splice(1, usage.length - 1, ...normalizedCustomUsageLine);
 		}
 	}
 	return {
 		usage,
 		sections,
-		...brief != null && { brief },
-		...description != null && { description },
-		...footer != null && { footer }
+		...brief != null && { brief: cloneMessage(brief) },
+		...description != null && { description: cloneMessage(description) },
+		...footer != null && { footer: cloneMessage(footer) }
 	};
 }
 

package/dist/usage.cjs

@@ -237,6 +237,59 @@ function normalizeUsageTerm(term) {
 		};
 	} else return term;
 }
+/**
+* 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, isHidden = isUsageHidden) {
 	const terms = [];
 	for (const term of usage) {
@@ -433,6 +486,8 @@ function* formatUsageTermInternal(term, options) {
 }
 
 //#endregion
+exports.cloneUsage = cloneUsage;
+exports.cloneUsageTerm = cloneUsageTerm;
 exports.extractArgumentMetavars = extractArgumentMetavars;
 exports.extractCommandNames = extractCommandNames;
 exports.extractOptionNames = extractOptionNames;

package/dist/usage.d.cts

@@ -347,6 +347,26 @@ declare function formatUsage(programName: string, usage: Usage, options?: UsageF
  *          and 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}.
  */
@@ -378,4 +398,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, extractOptionNames, formatUsage, formatUsageTerm, isDocHidden, isSuggestionHidden, isUsageHidden, mergeHidden, normalizeUsage };

package/dist/usage.d.ts

@@ -347,6 +347,26 @@ declare function formatUsage(programName: string, usage: Usage, options?: UsageF
  *          and 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}.
  */
@@ -378,4 +398,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, extractOptionNames, formatUsage, formatUsageTerm, isDocHidden, isSuggestionHidden, isUsageHidden, mergeHidden, normalizeUsage };

package/dist/usage.js

@@ -236,6 +236,59 @@ function normalizeUsageTerm(term) {
 		};
 	} else return term;
 }
+/**
+* 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, isHidden = isUsageHidden) {
 	const terms = [];
 	for (const term of usage) {
@@ -432,4 +485,4 @@ function* formatUsageTermInternal(term, options) {
 }
 
 //#endregion
-export { extractArgumentMetavars, extractCommandNames, extractOptionNames, formatUsage, formatUsageTerm, isDocHidden, isSuggestionHidden, isUsageHidden, mergeHidden, normalizeUsage };
+export { cloneUsage, cloneUsageTerm, extractArgumentMetavars, extractCommandNames, extractOptionNames, formatUsage, formatUsageTerm, isDocHidden, isSuggestionHidden, isUsageHidden, mergeHidden, normalizeUsage };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/core",
-  "version": "1.0.0-dev.1323+0653ad71",
+  "version": "1.0.0-dev.1335+e6f8ec57",
   "description": "Type-safe combinatorial command-line interface parser",
   "keywords": [
     "CLI",