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

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 };

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

@@ -24,7 +24,11 @@ function collectLeadingCandidates(terms, optionNames, commandNames, includeHidde
 			return false;
 		}
 		if (term.type === "command") {
-			if (includeHidden || !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;

package/dist/usage-internals.js

@@ -24,7 +24,11 @@ function collectLeadingCandidates(terms, optionNames, commandNames, includeHidde
 			return false;
 		}
 		if (term.type === "command") {
-			if (includeHidden || !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;

package/dist/usage.cjs

@@ -98,6 +98,8 @@ function extractCommandNames(usage, includeHidden) {
 		for (const term of terms) if (term.type === "command") {
 			if (!includeHidden && isSuggestionHidden(term.hidden)) continue;
 			names.add(term.name);
+			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);
 	}
@@ -354,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)
 			};
 		}

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.

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.

package/dist/usage.js

@@ -98,6 +98,8 @@ function extractCommandNames(usage, includeHidden) {
 		for (const term of terms) if (term.type === "command") {
 			if (!includeHidden && isSuggestionHidden(term.hidden)) continue;
 			names.add(term.name);
+			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);
 	}
@@ -354,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)
 			};
 		}

package/dist/validate.cjs

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