/**
 * Lexicon regen-validate pipeline.
 *
 * Given a lexicon root directory, this module:
 *   1. Runs the prepack chain (generate -> bundle -> validate -> build)
 *      by invoking `npm run <script>` in the lexicon directory.
 *   2. Runs `chant lint` on any examples found under `examples/`.
 *   3. Extracts the generated public API surface.
 *   4. Diffs the fresh surface against the committed per-lexicon baseline
 *      (`surface.snapshot.json` at the lexicon root).
 *   5. Returns { ok, changed, severity, delta, failures } — never throws.
 *
 * Supply-chain guarantee:
 *   All spec fetching happens through the lexicon's own `generate` script,
 *   which is pinned to the lexicon's existing fetch layer (cached, TTL-based).
 *   When `force` is true, the cache is bypassed and the spec is re-downloaded.
 *   This module never executes spec-provided content — it only reads the
 *   artifacts that the generate script produced.
 *
 * Never auto-fix:
 *   Any failure is captured into `failures` and returned. This module never
 *   rewrites examples, skips checks, or masks errors.
 */
import { type SurfaceDelta, type ChangeSeverity, type SurfaceSnapshot } from "./surface-snapshot.js";
export interface RegenFailure {
    /**
     * Which step failed:
     * "setup" | "digest-verify" | "generate" | "bundle" | "validate"
     * | "build" | "lint" | "examples" | "surface-extract" | "surface-diff"
     */
    step: string;
    /** Exit code from the subprocess, if applicable. */
    exitCode?: number;
    /** Combined stdout+stderr output captured from the subprocess. */
    output: string;
}
export interface RegenResult {
    /** True only when all steps passed and (if a baseline exists) the diff completed. */
    ok: boolean;
    /** True when the surface changed versus the baseline. */
    changed: boolean;
    /** Rolled-up severity of the surface delta. "none" when unchanged. */
    severity: ChangeSeverity;
    /** Structured delta: what was added, changed, or removed. */
    delta: SurfaceDelta;
    /** Human-readable delta text (empty string when no changes). */
    deltaText: string;
    /** Step failures captured during the run. */
    failures: RegenFailure[];
    /** Fresh surface snapshot — caller can write this as the new baseline. */
    freshSnapshot: SurfaceSnapshot | null;
}
export interface RegenOptions {
    /**
     * Root of the lexicon package (e.g. `/path/to/lexicons/aws`).
     * Must contain a `package.json` with `generate`, `bundle`, `validate`, `build` scripts.
     */
    lexiconDir: string;
    /**
     * When true, pass `CHANT_FORCE_FETCH=1` to the generate step so the spec is
     * re-downloaded from upstream even if the cache is fresh.
     */
    force?: boolean;
    /** Print subprocess output as it runs. Default: false. */
    verbose?: boolean;
    /**
     * Skip the `bundle` step. Useful when testing without a full dist build.
     * Default: false.
     */
    skipBundle?: boolean;
    /**
     * Skip the `build` (tsc) step. Useful in test contexts where tsc is not available.
     * Default: false.
     */
    skipBuild?: boolean;
    /**
     * Skip running `chant lint` on examples.
     * Default: false.
     */
    skipLint?: boolean;
    /**
     * Skip running example deploy harness (npm run deploy / npm run build in each example).
     * Default: true (examples require live cloud credentials; opt-in only).
     */
    skipExamples?: boolean;
    /**
     * Path to a SHA-256 digest file pinning the spec cache file.
     *
     * When provided, this module verifies the digest of the cached spec file
     * before invoking `generate`. This is the supply-chain choke point:
     * untrusted upstream content is verified here before any downstream processing.
     * The spec file is never executed — only checksummed and then passed to the
     * lexicon's own generator as data.
     *
     * File format (shasum -a 256 style):
     *   sha256:<64-hex-chars>  <relative-path-to-spec-file>
     */
    pinnedDigestPath?: string;
    /**
     * This run is about to rewrite the baseline snapshot (#1825).
     *
     * The `validate` step runs with {@link SNAPSHOT_UPDATE_ENV} set so its
     * `surface-matches-snapshot` check is skipped. A lexicon whose snapshot gate
     * runs in `"always"` mode (#1475) fails validate on a stale baseline, and a
     * stale baseline is exactly what a re-baseline starts from — without this
     * exemption the documented update flow deadlocks. Every other validate check
     * still gates the run, so a broken generate cannot be baselined.
     */
    updatingSnapshot?: boolean;
}
export declare const SNAPSHOT_FILENAME = "surface.snapshot.json";
/**
 * Run the full regen-validate pipeline for a lexicon and return the result.
 */
export declare function regenLexicon(opts: RegenOptions): Promise<RegenResult>;
/**
 * Write the fresh surface snapshot to the lexicon's committed baseline file.
 * Call this after a successful regen when the snapshot should be updated.
 */
export declare function writeSurfaceSnapshot(lexiconDir: string, snapshot: SurfaceSnapshot): void;
//# sourceMappingURL=lexicon-regen.d.ts.map