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