/**
 * CLI Error Formatter
 * Format enriched errors for human-readable, JSON, or compact output
 */
import type { SourceSpan, CallFrame } from '@rcrsr/rill';
import type { EnrichedError } from './cli-error-enrichment.js';
export type { CallFrame, EnrichedError };
export type TraceMode = 'auto' | 'always' | 'never';
/**
 * Format options for error output.
 *
 * `trace` controls when the trace block renders for halt-bearing errors:
 * - `auto`: render only when status carries >= 2 frames (default)
 * - `always`: render whenever a halt view is present
 * - `never`: omit the block entirely
 *
 * `atomOnly` (JSON only) emits `{atom, errorId}` headers for CI consumers.
 * `showRecovered` is a placeholder for the successful-result side path
 * (rendering `guard-caught` frames on a recovered invalid value).
 */
export interface FormatOptions {
    readonly format: 'human' | 'json' | 'compact';
    readonly verbose: boolean;
    readonly includeCallStack: boolean;
    readonly maxCallStackDepth: number;
    readonly trace?: TraceMode | undefined;
    readonly showRecovered?: boolean | undefined;
    readonly atomOnly?: boolean | undefined;
}
/**
 * Format enriched error for output.
 *
 * Constraints:
 * - Human format: multi-line with snippet and caret underline
 * - JSON format: LSP Diagnostic compatible
 * - Compact format: single line for CI output
 *
 * @param error - Enriched error with context
 * @param options - Format options
 * @returns Formatted error string
 * @throws {TypeError} Unknown format
 */
export declare function formatError(error: EnrichedError, options: FormatOptions): string;
/**
 * Render caret underline for error span.
 *
 * Constraints:
 * - Single-char: single ^
 * - Multi-char same line: ^^^^^ (length = span width)
 * - Multi-line: ^^^^^ (continues) on first line only
 *
 * @param span - Error span
 * @param lineContent - Content of the line
 * @returns Caret underline string
 * @throws {RangeError} Invalid span (start after end)
 */
export declare function renderCaretUnderline(span: SourceSpan, lineContent: string): string;