@optique/core 1.1.0-dev.2087 → 1.1.0-dev.2146

package/dist/suggestion.js

@@ -1,5 +1,5 @@
 import { message, optionName, text } from "./message.js";
-import { extractCommandNames, extractOptionNames } from "./usage.js";
+import { extractCommandNames, extractOptionNames, isSuggestionHidden } from "./usage.js";
 
 //#region src/suggestion.ts
 /**
@@ -141,6 +141,73 @@ function createSuggestionMessage(suggestions) {
 	return messageParts;
 }
 /**
+* Expands command alias suggestions so an alias typo can point at both the
+* canonical command and the alias that matched.
+*
+* @param usage Usage terms that define command aliases.
+* @param suggestions Candidate suggestions returned by {@link findSimilar}.
+* @returns Suggestions with alias hits expanded to canonical name + alias.
+* @internal
+*/
+function expandCommandAliasSuggestions(usage, suggestions) {
+	if (suggestions.length === 0) return suggestions;
+	const commandAliasTargets = collectCommandAliasTargets(usage);
+	const expanded = [];
+	const seen = /* @__PURE__ */ new Set();
+	for (const suggestion of suggestions) {
+		const targets = commandAliasTargets.get(suggestion) ?? [suggestion];
+		for (const target of targets) {
+			if (seen.has(target)) continue;
+			seen.add(target);
+			expanded.push(target);
+		}
+	}
+	return expanded;
+}
+function collectCommandAliasTargets(usage) {
+	const targets = /* @__PURE__ */ new Map();
+	function traverse(terms) {
+		if (!terms || !Array.isArray(terms)) return true;
+		for (const term of terms) {
+			if (term.type === "option") continue;
+			if (term.type === "argument") return false;
+			if (term.type === "command") {
+				if (isSuggestionHidden(term.hidden)) return false;
+				if (!targets.has(term.name)) targets.set(term.name, [term.name]);
+				for (const alias of term.aliases ?? []) if (!targets.has(alias)) targets.set(alias, [term.name, alias]);
+				for (const alias of term.hiddenAliases ?? []) if (!targets.has(alias)) targets.set(alias, [term.name]);
+				return false;
+			}
+			if (term.type === "optional") {
+				traverse(term.terms);
+				continue;
+			}
+			if (term.type === "multiple") {
+				const termsSkippable = traverse(term.terms);
+				if (term.min === 0 || termsSkippable) continue;
+				return false;
+			}
+			if (term.type === "sequence") {
+				if (traverse(term.terms)) continue;
+				return false;
+			}
+			if (term.type === "exclusive") {
+				let anySkippable = false;
+				for (const branch of term.terms) {
+					const branchSkippable = traverse(branch);
+					anySkippable = anySkippable || branchSkippable;
+				}
+				if (anySkippable) continue;
+				return false;
+			}
+			return false;
+		}
+		return true;
+	}
+	traverse(usage);
+	return targets;
+}
+/**
 * Creates an error message with suggestions for similar options or commands.
 *
 * This is a convenience function that combines the functionality of
@@ -175,7 +242,8 @@ function createErrorWithSuggestions(baseError, invalidInput, usage, type = "both
 	if (type === "option" || type === "both") for (const name of extractOptionNames(usage)) candidates.add(name);
 	if (type === "command" || type === "both") for (const name of extractCommandNames(usage)) candidates.add(name);
 	const suggestions = findSimilar(invalidInput, candidates, DEFAULT_FIND_SIMILAR_OPTIONS);
-	const suggestionMsg = customFormatter ? customFormatter(suggestions) : createSuggestionMessage(suggestions);
+	const displaySuggestions = type === "option" ? suggestions : expandCommandAliasSuggestions(usage, suggestions);
+	const suggestionMsg = customFormatter ? customFormatter(displaySuggestions) : createSuggestionMessage(displaySuggestions);
 	return suggestionMsg.length > 0 ? [
 		...baseError,
 		text("\n\n"),
@@ -244,4 +312,4 @@ function deduplicateSuggestions(suggestions) {
 }
 
 //#endregion
-export { DEFAULT_FIND_SIMILAR_OPTIONS, createErrorWithSuggestions, createSuggestionMessage, deduplicateSuggestions, findSimilar };
+export { DEFAULT_FIND_SIMILAR_OPTIONS, createErrorWithSuggestions, createSuggestionMessage, deduplicateSuggestions, expandCommandAliasSuggestions, findSimilar, levenshteinDistance };

package/dist/usage-internals.cjs

@@ -16,31 +16,39 @@ const require_usage = require('./usage.cjs');
 * @returns `true` if every term in `terms` is skippable (i.e., the caller
 *          may continue scanning the next sibling term), `false` otherwise.
 */
-function collectLeadingCandidates(terms, optionNames, commandNames) {
+function collectLeadingCandidates(terms, optionNames, commandNames, includeHidden = false) {
 	if (!terms || !Array.isArray(terms)) return true;
 	for (const term of terms) {
 		if (term.type === "option") {
-			if (!require_usage.isSuggestionHidden(term.hidden)) for (const name of term.names) optionNames.add(name);
+			if (includeHidden || !require_usage.isSuggestionHidden(term.hidden)) for (const name of term.names) optionNames.add(name);
 			return false;
 		}
 		if (term.type === "command") {
-			if (!require_usage.isSuggestionHidden(term.hidden)) commandNames.add(term.name);
+			if (includeHidden || !require_usage.isSuggestionHidden(term.hidden)) {
+				commandNames.add(term.name);
+				for (const alias of term.aliases ?? []) commandNames.add(alias);
+				for (const alias of term.hiddenAliases ?? []) commandNames.add(alias);
+			}
 			return false;
 		}
 		if (term.type === "argument") return false;
 		if (term.type === "optional") {
-			collectLeadingCandidates(term.terms, optionNames, commandNames);
+			collectLeadingCandidates(term.terms, optionNames, commandNames, includeHidden);
 			continue;
 		}
 		if (term.type === "multiple") {
-			collectLeadingCandidates(term.terms, optionNames, commandNames);
+			collectLeadingCandidates(term.terms, optionNames, commandNames, includeHidden);
 			if (term.min === 0) continue;
 			return false;
 		}
+		if (term.type === "sequence") {
+			if (collectLeadingCandidates(term.terms, optionNames, commandNames, includeHidden)) continue;
+			return false;
+		}
 		if (term.type === "exclusive") {
 			let allSkippable = true;
 			for (const branch of term.terms) {
-				const branchSkippable = collectLeadingCandidates(branch, optionNames, commandNames);
+				const branchSkippable = collectLeadingCandidates(branch, optionNames, commandNames, includeHidden);
 				allSkippable = allSkippable && branchSkippable;
 			}
 			if (allSkippable) continue;

package/dist/usage-internals.js

@@ -16,31 +16,39 @@ import { isSuggestionHidden } from "./usage.js";
 * @returns `true` if every term in `terms` is skippable (i.e., the caller
 *          may continue scanning the next sibling term), `false` otherwise.
 */
-function collectLeadingCandidates(terms, optionNames, commandNames) {
+function collectLeadingCandidates(terms, optionNames, commandNames, includeHidden = false) {
 	if (!terms || !Array.isArray(terms)) return true;
 	for (const term of terms) {
 		if (term.type === "option") {
-			if (!isSuggestionHidden(term.hidden)) for (const name of term.names) optionNames.add(name);
+			if (includeHidden || !isSuggestionHidden(term.hidden)) for (const name of term.names) optionNames.add(name);
 			return false;
 		}
 		if (term.type === "command") {
-			if (!isSuggestionHidden(term.hidden)) commandNames.add(term.name);
+			if (includeHidden || !isSuggestionHidden(term.hidden)) {
+				commandNames.add(term.name);
+				for (const alias of term.aliases ?? []) commandNames.add(alias);
+				for (const alias of term.hiddenAliases ?? []) commandNames.add(alias);
+			}
 			return false;
 		}
 		if (term.type === "argument") return false;
 		if (term.type === "optional") {
-			collectLeadingCandidates(term.terms, optionNames, commandNames);
+			collectLeadingCandidates(term.terms, optionNames, commandNames, includeHidden);
 			continue;
 		}
 		if (term.type === "multiple") {
-			collectLeadingCandidates(term.terms, optionNames, commandNames);
+			collectLeadingCandidates(term.terms, optionNames, commandNames, includeHidden);
 			if (term.min === 0) continue;
 			return false;
 		}
+		if (term.type === "sequence") {
+			if (collectLeadingCandidates(term.terms, optionNames, commandNames, includeHidden)) continue;
+			return false;
+		}
 		if (term.type === "exclusive") {
 			let allSkippable = true;
 			for (const branch of term.terms) {
-				const branchSkippable = collectLeadingCandidates(branch, optionNames, commandNames);
+				const branchSkippable = collectLeadingCandidates(branch, optionNames, commandNames, includeHidden);
 				allSkippable = allSkippable && branchSkippable;
 			}
 			if (allSkippable) continue;

package/dist/usage.cjs

@@ -63,7 +63,7 @@ function extractOptionNames(usage, includeHidden) {
 		for (const term of terms) if (term.type === "option") {
 			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 === "optional" || term.type === "multiple" || term.type === "sequence") traverseUsage(term.terms);
 		else if (term.type === "exclusive") for (const exclusiveUsage of term.terms) traverseUsage(exclusiveUsage);
 	}
 	traverseUsage(usage);
@@ -98,7 +98,9 @@ function extractCommandNames(usage, includeHidden) {
 		for (const term of terms) if (term.type === "command") {
 			if (!includeHidden && isSuggestionHidden(term.hidden)) continue;
 			names.add(term.name);
-		} else if (term.type === "optional" || term.type === "multiple") traverseUsage(term.terms);
+			for (const alias of term.aliases ?? []) names.add(alias);
+			if (includeHidden) for (const alias of term.hiddenAliases ?? []) names.add(alias);
+		} else if (term.type === "optional" || term.type === "multiple" || term.type === "sequence") traverseUsage(term.terms);
 		else if (term.type === "exclusive") for (const exclusiveUsage of term.terms) traverseUsage(exclusiveUsage);
 	}
 	traverseUsage(usage);
@@ -121,7 +123,7 @@ function extractLiteralValues(usage) {
 	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 === "optional" || term.type === "multiple" || term.type === "sequence") traverseUsage(term.terms);
 		else if (term.type === "exclusive") for (const branch of term.terms) traverseUsage(branch);
 	}
 	traverseUsage(usage);
@@ -155,7 +157,7 @@ function extractArgumentMetavars(usage) {
 		for (const term of terms) if (term.type === "argument") {
 			if (isSuggestionHidden(term.hidden)) continue;
 			metavars.add(term.metavar);
-		} else if (term.type === "optional" || term.type === "multiple") traverseUsage(term.terms);
+		} else if (term.type === "optional" || term.type === "multiple" || term.type === "sequence") traverseUsage(term.terms);
 		else if (term.type === "exclusive") for (const exclusiveUsage of term.terms) traverseUsage(exclusiveUsage);
 	}
 	traverseUsage(usage);
@@ -282,6 +284,10 @@ function normalizeUsageTerm(term) {
 		terms: normalizeUsage(term.terms),
 		min: term.min
 	};
+	else if (term.type === "sequence") return {
+		type: "sequence",
+		terms: term.terms.map(normalizeUsageTerm).filter(isNonDegenerateTerm)
+	};
 	else if (term.type === "exclusive") {
 		const terms = [];
 		for (const usage of term.terms) {
@@ -314,7 +320,7 @@ 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;
+	if (term.type === "optional" || term.type === "multiple" || term.type === "exclusive" || term.type === "sequence") return term.terms.length > 0;
 	return true;
 }
 function containsMalformedLeaf(usage) {
@@ -322,7 +328,7 @@ function containsMalformedLeaf(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 (term.type === "optional" || term.type === "multiple" || term.type === "sequence") {
 			if (containsMalformedLeaf(term.terms)) return true;
 		}
 		if (term.type === "exclusive") {
@@ -350,9 +356,15 @@ function cloneUsageTerm(term) {
 			names: [...term.names]
 		};
 		case "command": {
-			if (term.usageLine == null || typeof term.usageLine === "function") return { ...term };
+			if (term.usageLine == null || typeof term.usageLine === "function") return {
+				...term,
+				...term.aliases != null ? { aliases: [...term.aliases] } : {},
+				...term.hiddenAliases != null ? { hiddenAliases: [...term.hiddenAliases] } : {}
+			};
 			return {
 				...term,
+				...term.aliases != null ? { aliases: [...term.aliases] } : {},
+				...term.hiddenAliases != null ? { hiddenAliases: [...term.hiddenAliases] } : {},
 				usageLine: term.usageLine.map(cloneUsageTerm)
 			};
 		}
@@ -369,6 +381,10 @@ function cloneUsageTerm(term) {
 			type: "exclusive",
 			terms: term.terms.map((u) => u.map(cloneUsageTerm))
 		};
+		case "sequence": return {
+			type: "sequence",
+			terms: term.terms.map(cloneUsageTerm)
+		};
 		case "literal":
 		case "passthrough":
 		case "ellipsis": return { ...term };
@@ -421,6 +437,14 @@ function filterUsageForDisplay(usage, isHidden = isUsageHidden) {
 			});
 			continue;
 		}
+		if (term.type === "sequence") {
+			const filtered = filterUsageForDisplay(term.terms, isHidden);
+			if (filtered.length > 0) terms.push({
+				type: "sequence",
+				terms: filtered
+			});
+			continue;
+		}
 		terms.push(term);
 	}
 	return terms;
@@ -541,7 +565,8 @@ function* formatUsageTermInternal(term, options) {
 			text: options?.colors ? `\x1b[2m)\x1b[0m` : ")",
 			width: 1
 		};
-	} else if (term.type === "multiple") {
+	} else if (term.type === "sequence") yield* formatUsageTerms(term.terms, options);
+	else if (term.type === "multiple") {
 		if (term.min < 1) yield {
 			text: options?.colors ? `\x1b[2m[\x1b[0m` : "[",
 			width: 1

package/dist/usage.d.cts

@@ -104,6 +104,20 @@ type UsageTerm =
    * in the command-line usage.
    */
   readonly name: string;
+  /**
+   * Additional command names that invoke the same parser.
+   * These aliases participate in parsing, completion, and typo
+   * suggestions, but are not rendered in usage or documentation output.
+   * @since 1.1.0
+   */
+  readonly aliases?: readonly string[];
+  /**
+   * Additional command names that invoke the same parser but are not
+   * rendered or suggested.  They are still available to parsers and
+   * suggestion matchers so alias typos can resolve to the canonical command.
+   * @since 1.1.0
+   */
+  readonly hiddenAliases?: readonly string[];
   /**
    * Optional usage line override for this command's own help page.
    * This affects help/documentation rendering only.
@@ -164,6 +178,23 @@ type UsageTerm =
    */
   readonly terms: readonly Usage[];
 }
+/**
+ * A sequence term, which preserves the declaration order of its child
+ * terms through usage normalization.
+ *
+ * This is used by ordered parser combinators where argument/command/option
+ * order is part of the accepted grammar.
+ * @since 1.1.0
+ */ | {
+  /**
+   * The type of the term, which is always `"sequence"` for this term.
+   */
+  readonly type: "sequence";
+  /**
+   * Terms that must be displayed in the given order.
+   */
+  readonly terms: Usage;
+}
 /**
  * A literal term, which represents a fixed string value in the command-line
  * usage. Unlike metavars which are placeholders for user-provided values,

package/dist/usage.d.ts

@@ -104,6 +104,20 @@ type UsageTerm =
    * in the command-line usage.
    */
   readonly name: string;
+  /**
+   * Additional command names that invoke the same parser.
+   * These aliases participate in parsing, completion, and typo
+   * suggestions, but are not rendered in usage or documentation output.
+   * @since 1.1.0
+   */
+  readonly aliases?: readonly string[];
+  /**
+   * Additional command names that invoke the same parser but are not
+   * rendered or suggested.  They are still available to parsers and
+   * suggestion matchers so alias typos can resolve to the canonical command.
+   * @since 1.1.0
+   */
+  readonly hiddenAliases?: readonly string[];
   /**
    * Optional usage line override for this command's own help page.
    * This affects help/documentation rendering only.
@@ -164,6 +178,23 @@ type UsageTerm =
    */
   readonly terms: readonly Usage[];
 }
+/**
+ * A sequence term, which preserves the declaration order of its child
+ * terms through usage normalization.
+ *
+ * This is used by ordered parser combinators where argument/command/option
+ * order is part of the accepted grammar.
+ * @since 1.1.0
+ */ | {
+  /**
+   * The type of the term, which is always `"sequence"` for this term.
+   */
+  readonly type: "sequence";
+  /**
+   * Terms that must be displayed in the given order.
+   */
+  readonly terms: Usage;
+}
 /**
  * A literal term, which represents a fixed string value in the command-line
  * usage. Unlike metavars which are placeholders for user-provided values,

package/dist/usage.js

@@ -63,7 +63,7 @@ function extractOptionNames(usage, includeHidden) {
 		for (const term of terms) if (term.type === "option") {
 			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 === "optional" || term.type === "multiple" || term.type === "sequence") traverseUsage(term.terms);
 		else if (term.type === "exclusive") for (const exclusiveUsage of term.terms) traverseUsage(exclusiveUsage);
 	}
 	traverseUsage(usage);
@@ -98,7 +98,9 @@ function extractCommandNames(usage, includeHidden) {
 		for (const term of terms) if (term.type === "command") {
 			if (!includeHidden && isSuggestionHidden(term.hidden)) continue;
 			names.add(term.name);
-		} else if (term.type === "optional" || term.type === "multiple") traverseUsage(term.terms);
+			for (const alias of term.aliases ?? []) names.add(alias);
+			if (includeHidden) for (const alias of term.hiddenAliases ?? []) names.add(alias);
+		} else if (term.type === "optional" || term.type === "multiple" || term.type === "sequence") traverseUsage(term.terms);
 		else if (term.type === "exclusive") for (const exclusiveUsage of term.terms) traverseUsage(exclusiveUsage);
 	}
 	traverseUsage(usage);
@@ -121,7 +123,7 @@ function extractLiteralValues(usage) {
 	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 === "optional" || term.type === "multiple" || term.type === "sequence") traverseUsage(term.terms);
 		else if (term.type === "exclusive") for (const branch of term.terms) traverseUsage(branch);
 	}
 	traverseUsage(usage);
@@ -155,7 +157,7 @@ function extractArgumentMetavars(usage) {
 		for (const term of terms) if (term.type === "argument") {
 			if (isSuggestionHidden(term.hidden)) continue;
 			metavars.add(term.metavar);
-		} else if (term.type === "optional" || term.type === "multiple") traverseUsage(term.terms);
+		} else if (term.type === "optional" || term.type === "multiple" || term.type === "sequence") traverseUsage(term.terms);
 		else if (term.type === "exclusive") for (const exclusiveUsage of term.terms) traverseUsage(exclusiveUsage);
 	}
 	traverseUsage(usage);
@@ -282,6 +284,10 @@ function normalizeUsageTerm(term) {
 		terms: normalizeUsage(term.terms),
 		min: term.min
 	};
+	else if (term.type === "sequence") return {
+		type: "sequence",
+		terms: term.terms.map(normalizeUsageTerm).filter(isNonDegenerateTerm)
+	};
 	else if (term.type === "exclusive") {
 		const terms = [];
 		for (const usage of term.terms) {
@@ -314,7 +320,7 @@ 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;
+	if (term.type === "optional" || term.type === "multiple" || term.type === "exclusive" || term.type === "sequence") return term.terms.length > 0;
 	return true;
 }
 function containsMalformedLeaf(usage) {
@@ -322,7 +328,7 @@ function containsMalformedLeaf(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 (term.type === "optional" || term.type === "multiple" || term.type === "sequence") {
 			if (containsMalformedLeaf(term.terms)) return true;
 		}
 		if (term.type === "exclusive") {
@@ -350,9 +356,15 @@ function cloneUsageTerm(term) {
 			names: [...term.names]
 		};
 		case "command": {
-			if (term.usageLine == null || typeof term.usageLine === "function") return { ...term };
+			if (term.usageLine == null || typeof term.usageLine === "function") return {
+				...term,
+				...term.aliases != null ? { aliases: [...term.aliases] } : {},
+				...term.hiddenAliases != null ? { hiddenAliases: [...term.hiddenAliases] } : {}
+			};
 			return {
 				...term,
+				...term.aliases != null ? { aliases: [...term.aliases] } : {},
+				...term.hiddenAliases != null ? { hiddenAliases: [...term.hiddenAliases] } : {},
 				usageLine: term.usageLine.map(cloneUsageTerm)
 			};
 		}
@@ -369,6 +381,10 @@ function cloneUsageTerm(term) {
 			type: "exclusive",
 			terms: term.terms.map((u) => u.map(cloneUsageTerm))
 		};
+		case "sequence": return {
+			type: "sequence",
+			terms: term.terms.map(cloneUsageTerm)
+		};
 		case "literal":
 		case "passthrough":
 		case "ellipsis": return { ...term };
@@ -421,6 +437,14 @@ function filterUsageForDisplay(usage, isHidden = isUsageHidden) {
 			});
 			continue;
 		}
+		if (term.type === "sequence") {
+			const filtered = filterUsageForDisplay(term.terms, isHidden);
+			if (filtered.length > 0) terms.push({
+				type: "sequence",
+				terms: filtered
+			});
+			continue;
+		}
 		terms.push(term);
 	}
 	return terms;
@@ -541,7 +565,8 @@ function* formatUsageTermInternal(term, options) {
 			text: options?.colors ? `\x1b[2m)\x1b[0m` : ")",
 			width: 1
 		};
-	} else if (term.type === "multiple") {
+	} else if (term.type === "sequence") yield* formatUsageTerms(term.terms, options);
+	else if (term.type === "multiple") {
 		if (term.min < 1) yield {
 			text: options?.colors ? `\x1b[2m[\x1b[0m` : "[",
 			width: 1

package/dist/validate.cjs

@@ -162,6 +162,7 @@ function validateContextIds(contexts) {
 }
 
 //#endregion
+exports.escapeControlChars = escapeControlChars;
 exports.validateCommandNames = validateCommandNames;
 exports.validateContextIds = validateContextIds;
 exports.validateLabel = validateLabel;

package/dist/validate.d.cts

@@ -0,0 +1,99 @@
+//#region src/validate.d.ts
+/**
+ * Escapes control characters in a string for readable error messages.
+ *
+ * @param value The string to escape.
+ * @returns The escaped string with control characters replaced by escape
+ *          sequences.
+ */
+declare function escapeControlChars(value: string): string;
+/**
+ * Validates option names at runtime.
+ *
+ * @param names The option names to validate.
+ * @param label A human-readable label for error messages (e.g.,
+ *              `"Option"`, `"Flag"`, `"Help option"`).
+ * @throws {TypeError} If the names array is empty, or any name is empty,
+ *         lacks a valid prefix, or contains whitespace or control characters.
+ */
+declare function validateOptionNames(names: readonly string[], label: string): void;
+/**
+ * Validates command names at runtime.
+ *
+ * @param names The command names to validate.
+ * @param label A human-readable label for error messages (e.g.,
+ *              `"Help command"`).
+ * @throws {TypeError} If the names array is empty, or any name is empty,
+ *         whitespace-only, or contains whitespace or control characters.
+ */
+declare function validateCommandNames(names: readonly string[], label: string): void;
+/**
+ * A meta entry describes one active meta feature for collision checking.
+ *
+ * The tuple elements are:
+ *
+ * 1. `kind` — `"command"` if this meta feature matches at `args[0]` only,
+ *    or `"option"` if a lenient scanner matches the name anywhere in `argv`.
+ * 2. `label` — human-readable label for error messages (e.g., `"help option"`).
+ * 3. `names` — the configured name(s) for this meta feature.
+ * 4. `prefixMatch` — when `true`, the runtime also intercepts tokens
+ *    starting with `name=` (e.g., `--completion=bash`).  Only the
+ *    completion option uses this form; help/version use exact matching.
+ *
+ * @since 1.0.0
+ */
+type MetaEntry = readonly [kind: "command" | "option", label: string, names: readonly string[], prefixMatch?: boolean];
+/**
+ * Validates that there are no name collisions among active meta features
+ * (help, version, completion).
+ *
+ * User parser names are accepted even when they overlap with meta names.
+ * Runtime parsing resolves those cases parser-first so ordinary parser data
+ * can shadow built-in meta behavior.
+ *
+ * Meta-vs-meta collisions are always checked in a unified namespace,
+ * because a meta command named `"--help"` and a meta option named
+ * `"--help"` both compete for the same token.
+ *
+ * @param metaEntries Active meta feature entries annotated with their kind.
+ * @throws {TypeError} If any meta/meta collision or duplicate is detected.
+ * @since 1.0.0
+ */
+declare function validateMetaNameCollisions(metaEntries: readonly MetaEntry[]): void;
+/**
+ * Validates a program name at runtime.
+ *
+ * Program names may contain spaces (e.g., file paths), but must not be empty,
+ * whitespace-only, or contain control characters.
+ *
+ * @param programName The program name to validate.
+ * @throws {TypeError} If the value is not a string, is empty,
+ *         whitespace-only, or contains control characters.
+ */
+declare function validateProgramName(programName: string): void;
+/**
+ * Validates a label at runtime.
+ *
+ * Labels are used as section titles in documentation output.  They may contain
+ * spaces (e.g., "Connection options"), but must not be empty, whitespace-only,
+ * or contain control characters.
+ *
+ * @param label The label to validate.
+ * @throws {TypeError} If the label is not a string, is empty,
+ *         whitespace-only, or contains control characters.
+ * @since 1.0.0
+ */
+declare function validateLabel(label: string): void;
+/**
+ * Validates that all source contexts have unique
+ * {@link import("./context.ts").SourceContext.id | id} values.
+ *
+ * @param contexts The source contexts to validate.
+ * @throws {TypeError} If two or more contexts share the same id.
+ * @since 1.0.0
+ */
+declare function validateContextIds(contexts: readonly {
+  readonly id: symbol;
+}[]): void;
+//#endregion
+export { MetaEntry, escapeControlChars, validateCommandNames, validateContextIds, validateLabel, validateMetaNameCollisions, validateOptionNames, validateProgramName };