/**
 * Diagnostic layer — runs stub-completeness (and future observe-only
 * verifiers) on the realized output and writes a `realize-quality.json`
 * sidecar. Runs independently of the feedback runner.
 *
 * Why this exists (Phase 1 of 2026-05-13-VERIFIER-DIAGNOSTIC-TREATMENT-SPLIT):
 *   The realize pipeline used to print `✅ All code generated` and the
 *   user would only discover stub bodies at runtime. The post-emit-verify
 *   framework can detect stubs but only fires opt-in via
 *   `SPECVERSE_REALIZE_POST_VERIFY_ENABLE=stub-completeness`, and even
 *   then the findings are buried in pass logs. This module promotes the
 *   diagnostic to a first-class artifact: a sidecar JSON + a CLI summary
 *   line at end of realize.
 *
 * The diagnostic layer:
 *   - Runs ALWAYS when there are emitted `.ai.ts` files
 *   - Calls stub-completeness directly (bypasses the manifest's
 *     enabledByDefault gate — diagnostic should run regardless of whether
 *     the verifier is wired into the auto-fix loop)
 *   - Writes `<outputDir>/realize-quality.json`
 *   - Returns a summary suitable for CLI display
 *
 * Costs: regex-only scan of `.ai.ts` files. Milliseconds. No LLM calls.
 * Disabled via `SPECVERSE_REALIZE_NO_DIAGNOSTICS=1` for users who really
 * don't want the sidecar.
 */
import type { SpecGapEntry, VerifyContext } from './types.js';
export interface RealizeQualitySidecar {
    schemaVersion: '1.0';
    ranAt: string;
    ctx: {
        outputDir: string;
        targetLanguage?: string;
        subpath?: string;
    };
    totals: {
        stubs: number;
        stubsByCode: Record<string, number>;
        ownersWithStubs: number;
        specGaps?: number;
    };
    byOwner: Record<string, OwnerQualityEntry>;
    /** Errors classified `surface-spec-gap` by the feedback runner's
     *  treatment selector. The framework chose NOT to auto-fix these;
     *  the user reads them and decides whether to adjust the spec,
     *  manifest, or provider. Populated by `appendSpecGaps()` after the
     *  feedback runner completes. */
    specGaps?: SpecGapEntry[];
    notes: string[];
}
export interface OwnerQualityEntry {
    ownerName: string;
    stubs: OwnerStubIssue[];
}
export interface OwnerStubIssue {
    code: string;
    file: string;
    line?: number;
    col?: number;
    message: string;
}
export interface RealizeQualitySummary {
    totalStubs: number;
    ownersWithStubs: number;
    sidecarPath: string;
}
/**
 * Run the diagnostic verifiers on the realized output, write the
 * sidecar, return a summary for the CLI.
 *
 * Returns null when there's nothing to report (e.g. no `.ai.ts` files
 * at all — typical for backend-only validate-only specs). Caller
 * suppresses CLI output in that case.
 */
export declare function runDiagnostics(ctx: VerifyContext): Promise<RealizeQualitySummary | null>;
/**
 * Format the one-line CLI summary for `spv realize` output.
 *
 *   ⚠ realize-quality: 5 stubs across 3 owners (see realize-quality.json)
 *
 * Returns null when there's nothing to flag — caller should not print
 * anything in that case (no false-positive noise on clean realizes).
 */
export declare function formatSummaryLine(summary: RealizeQualitySummary | null): string | null;
/**
 * Read the existing `realize-quality.json` sidecar, attach the
 * feedback runner's `specGaps`, and rewrite. Idempotent — safe to call
 * multiple times. Skips silently when the sidecar doesn't exist
 * (diagnostics never ran or wrote it).
 *
 * Phase 2 of 2026-05-13-VERIFIER-DIAGNOSTIC-TREATMENT-SPLIT: the
 * feedback runner returns specGaps; realize's index.ts calls this to
 * merge them into the sidecar so users have one place to inspect
 * realize quality.
 */
export declare function appendSpecGaps(outputDir: string, specGaps: SpecGapEntry[]): void;
/**
 * Format the spec-gap one-liner for `spv realize` output. Distinct from
 * the stub summary because spec gaps indicate the user needs to act
 * (adjust spec/manifest/provider), not just inspect.
 *
 *   ⚠ realize-quality: 3 spec gap(s) surfaced; review realize-quality.json::specGaps
 *
 * Returns null when there are no gaps.
 */
export declare function formatSpecGapLine(specGapCount: number): string | null;
//# sourceMappingURL=diagnostics.d.ts.map