/** Shared endpoint name used by both dev pipelines and the agent-facing MCP tools. */
export declare const LAST_ERROR_PATH = "/__nifra/last-error";
/** One parsed stack frame. `file`/`line`/`column` are present only when the frame could be located. */
export interface DiagnosticFrame {
    readonly raw: string;
    readonly file?: string;
    readonly line?: number;
    readonly column?: number;
}
/** A source window around the offending line. `caret` marks the exact line the top frame points at. */
export interface Codeframe {
    readonly file: string;
    readonly line: number;
    readonly column?: number | undefined;
    readonly lines: ReadonlyArray<{
        readonly number: number;
        readonly text: string;
        readonly caret: boolean;
    }>;
}
/** The structured failure. Serialisable as-is to JSON for the agent surfaces. */
export interface Diagnostic {
    /** Stable, greppable identifier, e.g. `NIFRA_SERVER_ONLY_IN_CLIENT`. `NIFRA_UNHANDLED` when unrecognised. */
    readonly code: string;
    readonly name: string;
    readonly message: string;
    readonly request?: {
        readonly method: string;
        readonly url: string;
    } | undefined;
    readonly frames: readonly DiagnosticFrame[];
    readonly codeframe?: Codeframe | undefined;
    /** Plain-language "why this happened", when the failure is recognised. */
    readonly cause?: string | undefined;
    /** Plain-language "do this", when the failure is recognised. */
    readonly fix?: string | undefined;
    /** Docs section anchor for the code, e.g. `errors#server-only-in-client`. */
    readonly docsAnchor?: string | undefined;
}
/** Reads a source file's text, or returns undefined if it cannot (missing, binary, permission). */
export type SourceReader = (file: string) => string | undefined;
/**
 * Parse a V8/Node stack into structured frames. Handles the `at fn (path:line:col)`, bare
 * `at path:line:col`, and `at async fn (...)` shapes; a frame that doesn't match keeps its raw text
 * with no location (so nothing is silently dropped).
 */
export declare function parseFrames(stack: string): DiagnosticFrame[];
/** The first frame that points at the user's own source - what the codeframe should show. */
export declare function topUserFrame(frames: readonly DiagnosticFrame[], root: string | undefined): DiagnosticFrame | undefined;
/**
 * Build a source codeframe: `radius` lines either side of `line`, each tagged with its 1-based number
 * and whether it is the offending line. Returns undefined if the source can't be read or the line is
 * out of range - a diagnostic without a codeframe is still useful, so this never throws.
 */
export declare function buildCodeframe(file: string, line: number, column: number | undefined, read?: SourceReader, radius?: number): Codeframe | undefined;
/** A recognised failure shape: a stable code plus the plain-language cause/fix/anchor to attach. */
interface CatalogEntry {
    readonly code: string;
    readonly match: (name: string, message: string) => boolean;
    readonly cause: string;
    readonly fix: string;
    readonly docsAnchor: string;
}
/**
 * The recognised-failure catalog. Seeded with the highest-signal nifra failures; extend it as new
 * classes of error earn a stable code. Order matters only in that the first match wins.
 */
export declare const DIAGNOSTIC_CATALOG: readonly CatalogEntry[];
/** Classify an error name+message against the catalog; falls back to the generic unhandled code. */
export declare function classify(name: string, message: string): {
    code: string;
    cause?: string;
    fix?: string;
    docsAnchor?: string;
};
export interface BuildDiagnosticOptions {
    readonly request?: {
        readonly method: string;
        readonly url: string;
    };
    /** Project root; frames outside it are treated as non-user. Defaults to `process.cwd()`. */
    readonly root?: string;
    /** Injectable source reader (tests pass a fake; production reads the filesystem). */
    readonly read?: SourceReader;
}
/**
 * Resolve any thrown value into a `Diagnostic`: parse the (already source-mapped) stack, locate the top
 * user frame, attach a codeframe, and classify the failure for a cause/fix. The caller is responsible
 * for running Vite's `ssrFixStacktrace` first so the frames point at real source.
 */
export declare function buildDiagnostic(err: unknown, options?: BuildDiagnosticOptions): Diagnostic;
export {};
//# sourceMappingURL=diagnostic.d.ts.map