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

package/dist/primitives.js

@@ -6,9 +6,10 @@ import { dispatchByMode, dispatchIterableByMode, wrapForMode } from "./internal/
 import { getDefaultValuesFunction, getDependencyIds, getSnapshottedDefaultDependencyValues, isDerivedValueParser, suggestWithDependency } from "./internal/dependency.js";
 import { replayDerivedParser, replayDerivedParserAsync } from "./dependency-runtime.js";
 import { getWrappedChildParseState, getWrappedChildState, isAnnotationWrappedInitialState, normalizeInjectedAnnotationState } from "./annotation-state.js";
+import { hiddenCommandAliasesKey } from "./internal/command-alias.js";
 import { mergeChildExec, withChildContext, withChildExecPath } from "./execution-context.js";
 import { completeOrExtractPhase2Seed, extractPhase2SeedKey } from "./phase2-seed.js";
-import { DEFAULT_FIND_SIMILAR_OPTIONS, createErrorWithSuggestions, createSuggestionMessage, findSimilar } from "./suggestion.js";
+import { DEFAULT_FIND_SIMILAR_OPTIONS, createErrorWithSuggestions, createSuggestionMessage, expandCommandAliasSuggestions, findSimilar } from "./suggestion.js";
 import { extractLeadingCommandNames } from "./usage-internals.js";
 import { extractDependencyMetadata } from "./dependency-metadata.js";
 import { isValueParser } from "./valueparser.js";
@@ -23,6 +24,9 @@ function hasParsedOptionValue(state, valueParser) {
 	if (valueParser != null) return state != null && typeof state === "object" && "success" in state && typeof state.success === "boolean";
 	return state != null && "success" in state && state.success && state.value === true;
 }
+function isTerminalValueState(state) {
+	return state != null && typeof state === "object" && "success" in state && typeof state.success === "boolean";
+}
 /**
 * Helper function to create the stored state for an option or argument value.
 *
@@ -117,6 +121,9 @@ function constant(value) {
 		leadingNames: EMPTY_LEADING_NAMES,
 		acceptingAnyToken: false,
 		initialState: value,
+		canSkip() {
+			return true;
+		},
 		parse(context) {
 			return {
 				success: true,
@@ -174,6 +181,9 @@ function fail() {
 		leadingNames: EMPTY_LEADING_NAMES,
 		acceptingAnyToken: false,
 		initialState: void 0,
+		canSkip() {
+			return false;
+		},
 		parse(_context) {
 			return {
 				success: false,
@@ -431,6 +441,9 @@ function option(...args) {
 			success: true,
 			value: false
 		} : void 0,
+		canSkip(state) {
+			return valueParser == null || isTerminalValueState(state);
+		},
 		parse(context) {
 			if (context.optionsTerminated) return {
 				success: false,
@@ -686,6 +699,7 @@ function option(...args) {
 		};
 		Object.defineProperty(result, "validateValue", {
 			value(v) {
+				if (typeof vp.validate === "function") return wrapForMode(mode, wrapParseResult(vp.validate(v)));
 				let stringified;
 				try {
 					stringified = vp.format(v);
@@ -782,6 +796,9 @@ function flag(...args) {
 		leadingNames: new Set(optionNames$1),
 		acceptingAnyToken: false,
 		initialState: void 0,
+		canSkip(state) {
+			return isTerminalValueState(state);
+		},
 		parse(context) {
 			if (context.optionsTerminated) return {
 				success: false,
@@ -1013,6 +1030,9 @@ function negatableFlag(names, options = {}) {
 		leadingNames: new Set(optionNames$1),
 		acceptingAnyToken: false,
 		initialState: void 0,
+		canSkip(state) {
+			return state != null;
+		},
 		parse(context) {
 			if (context.optionsTerminated) return {
 				success: false,
@@ -1177,6 +1197,9 @@ function argument(valueParser, options = {}) {
 		leadingNames: EMPTY_LEADING_NAMES,
 		acceptingAnyToken: true,
 		initialState: void 0,
+		canSkip(state) {
+			return isTerminalValueState(state);
+		},
 		parse(context) {
 			const localState = normalizeInjectedAnnotationState(context.state);
 			if (context.buffer.length < 1) return {
@@ -1312,6 +1335,7 @@ function argument(valueParser, options = {}) {
 		};
 		Object.defineProperty(result, "validateValue", {
 			value(v) {
+				if (typeof vp.validate === "function") return wrapForMode(vpMode, wrapParseResult(vp.validate(v)));
 				let stringified;
 				try {
 					stringified = vp.format(v);
@@ -1368,25 +1392,56 @@ function appendCommandPath(exec, name) {
 		commandPath: [...exec.commandPath ?? [], name]
 	};
 }
-function* suggestCommandSync(context, prefix, name, parser, options) {
+function getCommandNames(name, options) {
+	return [
+		name,
+		...getVisibleCommandAliases(options),
+		...getHiddenCommandAliases(options)
+	];
+}
+function getVisibleCommandAliases(options) {
+	const aliases = options.aliases;
+	if (aliases == null) return [];
+	if (!isNonEmptyStringArray(aliases)) throw new TypeError("Command aliases must be a non-empty array of strings.");
+	return aliases;
+}
+function getHiddenCommandAliases(options) {
+	const hiddenAliases = options[hiddenCommandAliasesKey];
+	if (hiddenAliases == null) return [];
+	if (!isNonEmptyStringArray(hiddenAliases)) throw new TypeError("Hidden command aliases must be a non-empty array of strings.");
+	return hiddenAliases;
+}
+function isNonEmptyStringArray(value) {
+	if (!Array.isArray(value) || value.length === 0) return false;
+	for (let i = 0; i < value.length; i++) if (typeof value[i] !== "string") return false;
+	return true;
+}
+function validateUniqueCommandNames(names) {
+	const seen = /* @__PURE__ */ new Set();
+	for (const name of names) {
+		if (seen.has(name)) throw new TypeError(`Command has a duplicate name: "${name}".`);
+		seen.add(name);
+	}
+}
+function* suggestCommandSync(context, prefix, name, aliases, parser, options) {
 	if (isSuggestionHidden(options.hidden)) return;
 	const state = normalizeCommandState(context.state);
 	if (state === void 0) {
-		if (name.startsWith(prefix)) yield {
+		for (const commandName of [name, ...aliases]) if (commandName.startsWith(prefix)) yield {
 			kind: "literal",
-			text: name,
+			text: commandName,
 			...options.description && { description: options.description }
 		};
 	} else if (state[0] === "matched") yield* parser.suggest(withChildContext(context, name, getCommandChildState(context.state, parser.initialState, parser), parser.usage), prefix);
 	else if (state[0] === "parsing") yield* parser.suggest(withChildContext(context, name, getCommandChildState(context.state, state[1], parser), parser.usage), prefix);
 }
-async function* suggestCommandAsync(context, prefix, name, parser, options) {
+async function* suggestCommandAsync(context, prefix, name, aliases, parser, options) {
 	if (isSuggestionHidden(options.hidden)) return;
 	const state = normalizeCommandState(context.state);
 	if (state === void 0) {
-		if (name.startsWith(prefix)) yield {
+		for (const commandName of [name, ...aliases]) if (commandName.startsWith(prefix)) yield {
 			kind: "literal",
-			text: name,
+			text: commandName,
 			...options.description && { description: options.description }
 		};
 	} else if (state[0] === "matched") {
@@ -1414,7 +1469,11 @@ async function* suggestCommandAsync(context, prefix, name, parser, options) {
 *         embedded whitespace, or contains control characters.
 */
 function command(name, parser, options = {}) {
-	validateCommandNames([name], "Command");
+	const commandNames = getCommandNames(name, options);
+	const aliases = getVisibleCommandAliases(options);
+	const hiddenAliases = getHiddenCommandAliases(options);
+	validateCommandNames(commandNames, "Command");
+	validateUniqueCommandNames(commandNames);
 	const isAsync = parser.mode === "async";
 	const syncInnerParser = parser;
 	const asyncInnerParser = parser;
@@ -1427,12 +1486,20 @@ function command(name, parser, options = {}) {
 		usage: [{
 			type: "command",
 			name,
+			...aliases.length > 0 && { aliases },
+			...hiddenAliases.length > 0 && { hiddenAliases },
 			...options.usageLine != null && { usageLine: options.usageLine },
 			...options.hidden != null && { hidden: options.hidden }
 		}, ...parser.usage],
-		leadingNames: new Set([name]),
+		leadingNames: new Set(commandNames),
 		acceptingAnyToken: false,
 		initialState: void 0,
+		canSkip(state, exec) {
+			const normalizedState = normalizeCommandState(state);
+			if (normalizedState === void 0) return false;
+			if (normalizedState[0] === "matched") return parser.canSkip?.(getCommandChildState(state, parser.initialState, parser), withChildExecPath(exec, name)) === true;
+			return parser.canSkip?.(getCommandChildState(state, normalizedState[1], parser), withChildExecPath(exec, name)) === true;
+		},
 		getSuggestRuntimeNodes(state, path) {
 			const normalizedState = normalizeCommandState(state);
 			if (normalizedState === void 0) return [];
@@ -1447,10 +1514,11 @@ function command(name, parser, options = {}) {
 		parse(context) {
 			const state = normalizeCommandState(context.state);
 			if (state === void 0) {
-				if (context.buffer.length < 1 || context.buffer[0] !== name) {
+				if (context.buffer.length < 1 || !commandNames.includes(context.buffer[0])) {
 					const actual = context.buffer.length > 0 ? context.buffer[0] : null;
 					const leadingCmds = extractLeadingCommandNames(context.usage);
-					const suggestions = actual ? findSimilar(actual, leadingCmds, DEFAULT_FIND_SIMILAR_OPTIONS) : [];
+					const rawSuggestions = actual ? findSimilar(actual, leadingCmds, DEFAULT_FIND_SIMILAR_OPTIONS) : [];
+					const suggestions = expandCommandAliasSuggestions(context.usage, rawSuggestions);
 					if (options.errors?.notMatched) {
 						const errorMessage = options.errors.notMatched;
 						return {
@@ -1581,8 +1649,8 @@ function command(name, parser, options = {}) {
 			return wrapForMode(parser.mode, null);
 		},
 		suggest(context, prefix) {
-			if (isAsync) return suggestCommandAsync(context, prefix, name, parser, options);
-			return suggestCommandSync(context, prefix, name, parser, options);
+			if (isAsync) return suggestCommandAsync(context, prefix, name, aliases, parser, options);
+			return suggestCommandSync(context, prefix, name, aliases, parser, options);
 		},
 		getDocFragments(state, defaultValue) {
 			const commandState = state.kind === "available" ? normalizeCommandState(state.state) : void 0;
@@ -1696,6 +1764,9 @@ function passThrough(options = {}) {
 		leadingNames: EMPTY_LEADING_NAMES,
 		acceptingAnyToken: false,
 		initialState: [],
+		canSkip() {
+			return true;
+		},
 		parse(context) {
 			if (context.buffer.length < 1) return {
 				success: false,

package/dist/suggestion.cjs

@@ -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 (require_usage.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 require_usage.extractOptionNames(usage)) candidates.add(name);
 	if (type === "command" || type === "both") for (const name of require_usage.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,
 		require_message.text("\n\n"),
@@ -248,4 +316,6 @@ exports.DEFAULT_FIND_SIMILAR_OPTIONS = DEFAULT_FIND_SIMILAR_OPTIONS;
 exports.createErrorWithSuggestions = createErrorWithSuggestions;
 exports.createSuggestionMessage = createSuggestionMessage;
 exports.deduplicateSuggestions = deduplicateSuggestions;
-exports.findSimilar = findSimilar;
+exports.expandCommandAliasSuggestions = expandCommandAliasSuggestions;
+exports.findSimilar = findSimilar;
+exports.levenshteinDistance = levenshteinDistance;

package/dist/suggestion.d.cts

@@ -0,0 +1,188 @@
+import { Message } from "./message.cjs";
+import { Usage } from "./usage.cjs";
+import { Suggestion } from "./internal/parser.cjs";
+
+//#region src/suggestion.d.ts
+
+/**
+ * Calculates the Levenshtein distance between two strings.
+ *
+ * The Levenshtein distance is the minimum number of single-character edits
+ * (insertions, deletions, or substitutions) required to transform one string
+ * into another.
+ *
+ * @param source The source string
+ * @param target The target string
+ * @returns The edit distance (number of insertions, deletions, substitutions)
+ *
+ * @example
+ * ```typescript
+ * levenshteinDistance("kitten", "sitting"); // returns 3
+ * levenshteinDistance("--verbos", "--verbose"); // returns 1
+ * levenshteinDistance("hello", "hello"); // returns 0
+ * ```
+ */
+declare function levenshteinDistance(source: string, target: string): number;
+/**
+ * Options for finding similar strings.
+ */
+interface FindSimilarOptions {
+  /**
+   * Maximum edit distance to consider a match.
+   * Strings with a distance greater than this value will not be suggested.
+   * @default 3
+   */
+  readonly maxDistance?: number;
+  /**
+   * Maximum distance ratio (distance / input length).
+   * Prevents suggesting long strings for very short inputs.
+   * For example, with maxDistanceRatio=0.5, an input of length 2
+   * will only suggest strings within distance 1.
+   * @default 0.5
+   */
+  readonly maxDistanceRatio?: number;
+  /**
+   * Maximum number of suggestions to return.
+   * @default 3
+   */
+  readonly maxSuggestions?: number;
+  /**
+   * Case-sensitive comparison.
+   * If false, strings are compared case-insensitively.
+   * @default false
+   */
+  readonly caseSensitive?: boolean;
+}
+/**
+ * Default options for finding similar strings.
+ * These values are optimized for command-line option/command name suggestions.
+ *
+ * @since 0.7.0
+ */
+declare const DEFAULT_FIND_SIMILAR_OPTIONS: Required<FindSimilarOptions>;
+/**
+ * Finds similar strings from a list of candidates.
+ *
+ * This function uses Levenshtein distance to find strings that are similar
+ * to the input string. Results are sorted by similarity (most similar first).
+ *
+ * @param input The input string to find matches for
+ * @param candidates List of candidate strings to compare against
+ * @param options Configuration options
+ * @returns Array of similar strings, sorted by similarity (most similar first)
+ *
+ * @example
+ * ```typescript
+ * const candidates = ["--verbose", "--version", "--verify", "--help"];
+ * findSimilar("--verbos", candidates);
+ * // returns ["--verbose"]
+ *
+ * findSimilar("--ver", candidates, { maxDistance: 5 });
+ * // returns ["--verify", "--version", "--verbose"]
+ *
+ * findSimilar("--xyz", candidates);
+ * // returns [] (no similar matches)
+ * ```
+ */
+declare function findSimilar(input: string, candidates: Iterable<string>, options?: FindSimilarOptions): string[];
+/**
+ * Creates a suggestion message for a mismatched option/command.
+ *
+ * This function formats suggestions in a user-friendly way:
+ * - No suggestions: returns empty message
+ * - One suggestion: "Did you mean `option`?"
+ * - Multiple suggestions: "Did you mean one of these?\n  option1\n  option2"
+ *
+ * @param suggestions List of similar valid options/commands
+ * @returns A Message array with suggestion text
+ *
+ * @example
+ * ```typescript
+ * createSuggestionMessage(["--verbose", "--version"]);
+ * // returns message parts for:
+ * // "Did you mean one of these?
+ * //   --verbose
+ * //   --version"
+ *
+ * createSuggestionMessage(["--verbose"]);
+ * // returns message parts for:
+ * // "Did you mean `--verbose`?"
+ *
+ * createSuggestionMessage([]);
+ * // returns []
+ * ```
+ */
+declare function createSuggestionMessage(suggestions: readonly string[]): Message;
+/**
+ * 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
+ */
+declare function expandCommandAliasSuggestions(usage: Usage, suggestions: readonly string[]): readonly string[];
+/**
+ * Creates an error message with suggestions for similar options or commands.
+ *
+ * This is a convenience function that combines the functionality of
+ * `findSimilar()` and `createSuggestionMessage()` to generate user-friendly
+ * error messages with "Did you mean?" suggestions.
+ *
+ * @param baseError The base error message to display
+ * @param invalidInput The invalid option or command name that the user typed
+ * @param usage The usage information to extract available options/commands from
+ * @param type What type of names to suggest ("option", "command", or "both")
+ * @param customFormatter Optional custom function to format suggestions instead
+ *                        of using the default "Did you mean?" formatting
+ * @returns A message combining the base error with suggestions, or just the
+ *          base error if no similar names are found
+ *
+ * @example
+ * ```typescript
+ * const baseError = message`No matched option for ${optionName("--verbos")}.`;
+ * const error = createErrorWithSuggestions(
+ *   baseError,
+ *   "--verbos",
+ *   context.usage,
+ *   "option"
+ * );
+ * // Returns: "No matched option for `--verbos`.\nDid you mean `--verbose`?"
+ * ```
+ *
+ * @since 0.7.0
+ */
+declare function createErrorWithSuggestions(baseError: Message, invalidInput: string, usage: Usage, type?: "option" | "command" | "both", customFormatter?: (suggestions: readonly string[]) => Message): Message;
+/**
+ * Removes duplicate suggestions from an array while preserving order.
+ *
+ * Suggestions are considered duplicates if they have the same key:
+ * - Literal suggestions: same text
+ * - File suggestions: same type, extensions, and pattern
+ *
+ * The first occurrence of each unique suggestion is kept.  For file
+ * suggestions, `includeHidden` is merged across duplicates: if any
+ * duplicate has `includeHidden: true`, the kept suggestion is upgraded
+ * to `includeHidden: true` because it is a superset of the non-hidden
+ * variant.
+ *
+ * @param suggestions Array of suggestions that may contain duplicates
+ * @returns A new array with duplicates removed, preserving order of first occurrences
+ *
+ * @example
+ * ```typescript
+ * const suggestions = [
+ *   { kind: "literal", text: "--verbose" },
+ *   { kind: "literal", text: "--help" },
+ *   { kind: "literal", text: "--verbose" }, // duplicate
+ * ];
+ * deduplicateSuggestions(suggestions);
+ * // returns [{ kind: "literal", text: "--verbose" }, { kind: "literal", text: "--help" }]
+ * ```
+ *
+ * @since 0.9.0
+ */
+declare function deduplicateSuggestions(suggestions: readonly Suggestion[]): Suggestion[];
+//#endregion
+export { DEFAULT_FIND_SIMILAR_OPTIONS, FindSimilarOptions, createErrorWithSuggestions, createSuggestionMessage, deduplicateSuggestions, expandCommandAliasSuggestions, findSimilar, levenshteinDistance };

package/dist/suggestion.d.ts

@@ -0,0 +1,188 @@
+import { Message } from "./message.js";
+import { Usage } from "./usage.js";
+import { Suggestion } from "./internal/parser.js";
+
+//#region src/suggestion.d.ts
+
+/**
+ * Calculates the Levenshtein distance between two strings.
+ *
+ * The Levenshtein distance is the minimum number of single-character edits
+ * (insertions, deletions, or substitutions) required to transform one string
+ * into another.
+ *
+ * @param source The source string
+ * @param target The target string
+ * @returns The edit distance (number of insertions, deletions, substitutions)
+ *
+ * @example
+ * ```typescript
+ * levenshteinDistance("kitten", "sitting"); // returns 3
+ * levenshteinDistance("--verbos", "--verbose"); // returns 1
+ * levenshteinDistance("hello", "hello"); // returns 0
+ * ```
+ */
+declare function levenshteinDistance(source: string, target: string): number;
+/**
+ * Options for finding similar strings.
+ */
+interface FindSimilarOptions {
+  /**
+   * Maximum edit distance to consider a match.
+   * Strings with a distance greater than this value will not be suggested.
+   * @default 3
+   */
+  readonly maxDistance?: number;
+  /**
+   * Maximum distance ratio (distance / input length).
+   * Prevents suggesting long strings for very short inputs.
+   * For example, with maxDistanceRatio=0.5, an input of length 2
+   * will only suggest strings within distance 1.
+   * @default 0.5
+   */
+  readonly maxDistanceRatio?: number;
+  /**
+   * Maximum number of suggestions to return.
+   * @default 3
+   */
+  readonly maxSuggestions?: number;
+  /**
+   * Case-sensitive comparison.
+   * If false, strings are compared case-insensitively.
+   * @default false
+   */
+  readonly caseSensitive?: boolean;
+}
+/**
+ * Default options for finding similar strings.
+ * These values are optimized for command-line option/command name suggestions.
+ *
+ * @since 0.7.0
+ */
+declare const DEFAULT_FIND_SIMILAR_OPTIONS: Required<FindSimilarOptions>;
+/**
+ * Finds similar strings from a list of candidates.
+ *
+ * This function uses Levenshtein distance to find strings that are similar
+ * to the input string. Results are sorted by similarity (most similar first).
+ *
+ * @param input The input string to find matches for
+ * @param candidates List of candidate strings to compare against
+ * @param options Configuration options
+ * @returns Array of similar strings, sorted by similarity (most similar first)
+ *
+ * @example
+ * ```typescript
+ * const candidates = ["--verbose", "--version", "--verify", "--help"];
+ * findSimilar("--verbos", candidates);
+ * // returns ["--verbose"]
+ *
+ * findSimilar("--ver", candidates, { maxDistance: 5 });
+ * // returns ["--verify", "--version", "--verbose"]
+ *
+ * findSimilar("--xyz", candidates);
+ * // returns [] (no similar matches)
+ * ```
+ */
+declare function findSimilar(input: string, candidates: Iterable<string>, options?: FindSimilarOptions): string[];
+/**
+ * Creates a suggestion message for a mismatched option/command.
+ *
+ * This function formats suggestions in a user-friendly way:
+ * - No suggestions: returns empty message
+ * - One suggestion: "Did you mean `option`?"
+ * - Multiple suggestions: "Did you mean one of these?\n  option1\n  option2"
+ *
+ * @param suggestions List of similar valid options/commands
+ * @returns A Message array with suggestion text
+ *
+ * @example
+ * ```typescript
+ * createSuggestionMessage(["--verbose", "--version"]);
+ * // returns message parts for:
+ * // "Did you mean one of these?
+ * //   --verbose
+ * //   --version"
+ *
+ * createSuggestionMessage(["--verbose"]);
+ * // returns message parts for:
+ * // "Did you mean `--verbose`?"
+ *
+ * createSuggestionMessage([]);
+ * // returns []
+ * ```
+ */
+declare function createSuggestionMessage(suggestions: readonly string[]): Message;
+/**
+ * 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
+ */
+declare function expandCommandAliasSuggestions(usage: Usage, suggestions: readonly string[]): readonly string[];
+/**
+ * Creates an error message with suggestions for similar options or commands.
+ *
+ * This is a convenience function that combines the functionality of
+ * `findSimilar()` and `createSuggestionMessage()` to generate user-friendly
+ * error messages with "Did you mean?" suggestions.
+ *
+ * @param baseError The base error message to display
+ * @param invalidInput The invalid option or command name that the user typed
+ * @param usage The usage information to extract available options/commands from
+ * @param type What type of names to suggest ("option", "command", or "both")
+ * @param customFormatter Optional custom function to format suggestions instead
+ *                        of using the default "Did you mean?" formatting
+ * @returns A message combining the base error with suggestions, or just the
+ *          base error if no similar names are found
+ *
+ * @example
+ * ```typescript
+ * const baseError = message`No matched option for ${optionName("--verbos")}.`;
+ * const error = createErrorWithSuggestions(
+ *   baseError,
+ *   "--verbos",
+ *   context.usage,
+ *   "option"
+ * );
+ * // Returns: "No matched option for `--verbos`.\nDid you mean `--verbose`?"
+ * ```
+ *
+ * @since 0.7.0
+ */
+declare function createErrorWithSuggestions(baseError: Message, invalidInput: string, usage: Usage, type?: "option" | "command" | "both", customFormatter?: (suggestions: readonly string[]) => Message): Message;
+/**
+ * Removes duplicate suggestions from an array while preserving order.
+ *
+ * Suggestions are considered duplicates if they have the same key:
+ * - Literal suggestions: same text
+ * - File suggestions: same type, extensions, and pattern
+ *
+ * The first occurrence of each unique suggestion is kept.  For file
+ * suggestions, `includeHidden` is merged across duplicates: if any
+ * duplicate has `includeHidden: true`, the kept suggestion is upgraded
+ * to `includeHidden: true` because it is a superset of the non-hidden
+ * variant.
+ *
+ * @param suggestions Array of suggestions that may contain duplicates
+ * @returns A new array with duplicates removed, preserving order of first occurrences
+ *
+ * @example
+ * ```typescript
+ * const suggestions = [
+ *   { kind: "literal", text: "--verbose" },
+ *   { kind: "literal", text: "--help" },
+ *   { kind: "literal", text: "--verbose" }, // duplicate
+ * ];
+ * deduplicateSuggestions(suggestions);
+ * // returns [{ kind: "literal", text: "--verbose" }, { kind: "literal", text: "--help" }]
+ * ```
+ *
+ * @since 0.9.0
+ */
+declare function deduplicateSuggestions(suggestions: readonly Suggestion[]): Suggestion[];
+//#endregion
+export { DEFAULT_FIND_SIMILAR_OPTIONS, FindSimilarOptions, createErrorWithSuggestions, createSuggestionMessage, deduplicateSuggestions, expandCommandAliasSuggestions, findSimilar, levenshteinDistance };