/**
 * CLI Error Enrichment
 * Functions for extracting source snippets and suggesting similar names
 */
import type { SourceSpan, RillError, CallFrame } from '@rcrsr/rill';
import { type HaltView } from './cli-error-from-halt.js';
export interface SourceSnippet {
    readonly lines: SnippetLine[];
    readonly highlightSpan: SourceSpan;
}
export interface SnippetLine {
    readonly lineNumber: number;
    readonly content: string;
    readonly isErrorLine: boolean;
}
export interface ScopeInfo {
    readonly variableNames: string[];
    readonly functionNames: string[];
}
export interface EnrichedError {
    readonly errorId: string;
    readonly message: string;
    readonly span?: SourceSpan | undefined;
    readonly context?: Record<string, unknown> | undefined;
    readonly callStack?: CallFrame[] | undefined;
    readonly sourceSnippet?: SourceSnippet | undefined;
    readonly suggestions?: string[] | undefined;
    readonly helpUrl?: string | undefined;
    readonly halt?: HaltView | undefined;
    readonly filePath?: string | undefined;
    readonly source?: string | undefined;
}
export type { HaltView };
/**
 * Extract source lines around error location.
 *
 * Constraints:
 * - Context lines: 2 before, 2 after (configurable)
 * - Line numbers: 1-based
 * - Handles edge cases: line 1, last line
 *
 * @param source - Full source text
 * @param span - Error location span
 * @param contextLines - Number of context lines before/after (default: 2)
 * @returns Snippet with context lines
 * @throws {RangeError} When span exceeds source bounds
 */
export declare function extractSnippet(source: string, span: SourceSpan, contextLines?: number): SourceSnippet;
/**
 * Find similar names using fuzzy matching.
 *
 * Constraints:
 * - Edit distance threshold: <= 2
 * - Max suggestions: 3
 * - Sort: ascending by distance, then alphabetically
 *
 * @param target - Name to match against
 * @param candidates - Available names
 * @returns Up to 3 similar names, sorted by distance then alphabetically
 */
export declare function suggestSimilarNames(target: string, candidates: string[]): string[];
/**
 * Enrich RillError with source snippets and suggestions.
 *
 * Constraints:
 * - Source must be valid UTF-8
 * - Snippet extraction: 2 lines before, error line, 2 after
 * - Fuzzy matching: edit distance <= 2
 * - Max 3 suggestions
 *
 * @param error - RillError to enrich
 * @param source - Full source text
 * @param scope - Optional scope information for suggestions
 * @returns Enriched error with snippet and suggestions
 * @throws {TypeError} When source is not a string or error is null
 */
export declare function enrichError(error: RillError, source: string, scope?: ScopeInfo, filePath?: string): EnrichedError;