import type { SourceText, Span } from "./source.ts";
/**
 * D38 §48: the mechanical rewrite a diagnostic already knows. A fix is
 * registered only where the diagnostic names one correct replacement and no
 * judgment is involved, so applying it is a spelling change and never a guess
 * about intent. `velar fix` applies these, and an editor offers each one as a
 * quick fix; every other diagnostic stays advice the author acts on.
 */
export interface DiagnosticEdit {
    /** The replaced range. It may be wider than the diagnostic span (surrounding whitespace a deletion should take with it), and empty to insert. */
    readonly span: Span;
    /** The exact replacement text; the empty string deletes the range. */
    readonly text: string;
}
export interface DiagnosticFix {
    /** The edits of one rewrite; they never overlap and are applied together or not at all. */
    readonly edits: readonly DiagnosticEdit[];
    /** Imperative editor title, e.g. "Use VelarScript strict equality '=='". */
    readonly title: string;
}
export interface Diagnostic {
    readonly code: string;
    readonly message: string;
    readonly span: Span;
    /**
     * Marks a guidance diagnostic whose compile stage internally recovered as
     * the guided spelling, so later stages still run and can report their own
     * guidance in the same compile. Compilation still fails: recovered
     * diagnostics count toward the zero-diagnostics gate for code generation.
     */
    readonly recovered?: boolean;
    /** The mechanical rewrite this diagnostic names, when it names exactly one. */
    readonly fix?: DiagnosticFix;
}
export declare function diagnostic(code: string, message: string, span: Span, fix?: DiagnosticFix): Diagnostic;
export declare function recoveredDiagnostic(code: string, message: string, span: Span, fix?: DiagnosticFix): Diagnostic;
/**
 * D89: the second diagnostic channel. An advisory names a spelling VelarScript
 * accepts with a different meaning than the Python or JavaScript reflex that
 * wrote it, so it can be neither silenced nor rejected. It never blocks code
 * generation: `index.ts` gates emission on `diagnostics.length === 0`, and an
 * advisory is physically incapable of reaching that expression.
 *
 * This is a separate type rather than a `severity` field on `Diagnostic`
 * because the analyzer reads `this.diagnostics.length` as a cursor:
 * `analyzer.ts:3496` and `:3549` hand the length to `reanalyzeLoopBackEdge` as
 * the first diagnostic of a loop body, `:6964`/`:6967` compare two lengths to
 * decide `calleeAlreadyDiagnosed` (which suppresses three reports at `:7058`),
 * `:12573` pairs with `deduplicateDiagnostics`, and `web/analyzer.ts:1063`
 * rewrites message text by index over the same range. Every one of those reads
 * the array's length or index, never the items, so a severity field cannot
 * keep an interleaved advisory from being mistaken for a diagnostic and
 * deleting the real error behind it. Separate arrays make that impossible.
 *
 * The `tier` discriminant is required so TypeScript rejects an advisory passed
 * into any `readonly Diagnostic[]` in the repository, which is what keeps the
 * two channels from merging by accident.
 */
export interface Advisory {
    readonly tier: "advisory";
    /** The advisory roster id, e.g. "A1". Deliberately not the VELxxxx family. */
    readonly code: string;
    readonly message: string;
    readonly span: Span;
    /** The mechanical rewrite this advisory names, when it names exactly one. */
    readonly fix?: DiagnosticFix;
}
export declare function advisory(code: string, message: string, span: Span, fix?: DiagnosticFix): Advisory;
/** Builds the one-edit mechanical rewrite of `span` to `text`. */
export declare function mechanicalFix(span: Span, text: string, title: string): DiagnosticFix;
/** Builds a mechanical rewrite whose one spelling change needs more than one edit. */
export declare function mechanicalEdits(edits: readonly DiagnosticEdit[], title: string): DiagnosticFix;
export declare function formatDiagnostic(source: SourceText, item: Diagnostic): string;
/** The diagnostic block with `advisory` where the label reads `error`. */
export declare function formatAdvisory(source: SourceText, item: Advisory): string;
//# sourceMappingURL=diagnostic.d.ts.map