/**
 * Static semantic analysis over a parsed `Program`. Detects problems that
 * are syntactically valid but semantically wrong — undefined variable
 * references, duplicate bindings, unreachable code — *without* evaluating
 * the program. Designed for editor integrations (Monaco / VSCode markers)
 * and pre-flight checks.
 *
 * Two tiers:
 *
 * - **Tier 1** (always on): zero-false-positive checks based on scope and
 *   AST structure only. `undefined-variable`, `duplicate-binding`,
 *   `unreachable-match-arm`, `unreachable-if-branch`.
 *
 * - **Tier 2** (opt-in via `{ deep: true }`): adds `type-mismatch` (from
 *   the bidirectional inference pass in `./semantic-types`) and
 *   `never-fires-match-arm` (from running `ProgramStats.analyze` on the
 *   match scrutinee when its value support is computable exactly).
 */
import { type Program } from './program';
import type { SourceSpan } from './source-span';
export type DiagnosticSeverity = 'error' | 'warning' | 'info';
export interface DiagnosticRelatedInformation {
    span: SourceSpan;
    message: string;
}
export interface SemanticDiagnostic {
    severity: DiagnosticSeverity;
    /** Stable identifier suitable for filtering / per-code suppression. */
    code: string;
    message: string;
    /** Region the diagnostic applies to. Always present for parser-built ASTs;
     *  consumers analysing hand-built ASTs without `loc` may see a zero span. */
    span: SourceSpan;
    related?: readonly DiagnosticRelatedInformation[];
}
export interface AnalyzeProgramOptions {
    /** Include Tier 2 checks (type-mismatch, never-fires match arm).
     *  Defaults to `false`. Tier 2 is more expensive and may run additional
     *  analysis passes; not recommended for keystroke-level use without
     *  debouncing. */
    deep?: boolean;
}
export declare function analyzeProgram(program: Program, options?: AnalyzeProgramOptions): SemanticDiagnostic[];