/**
 * Post-emit verification framework — generic interface.
 *
 * SpecVerse realize emits one or more LLM-authored source files per
 * owner (e.g. `backend/src/behaviors/<Owner>.ai.ts` for the TypeScript
 * stack). LLM emissions sometimes carry compile errors / lint issues
 * that don't show up at per-rule validation time (the realize-rules
 * manifest catches forbidden APIs, missing `.js` extensions, etc., but
 * not type mismatches or runtime semantics).
 *
 * A `PostEmitVerifier` runs AFTER all owners have emitted, on the
 * fully-realized output tree. It produces structured errors that the
 * feedback runner uses to drive a per-file re-emit pass.
 *
 * The interface is intentionally language-agnostic. The first
 * implementation is `tsc` for TypeScript stacks; future verifiers can
 * target Python (`mypy`/`ruff`), Go (`go vet`), Java (`mvn compile`),
 * Rust (`cargo check`), etc. Each verifier knows whether it `applies`
 * given the realized target (the manifest's stack tells you).
 *
 * Empirical motivation: 2026-05-13 idle-meta realize at engines 6.50.1
 * produced 48 backend tsc errors. Two hand-crafted feedback prompts
 * (AuthController.ai.ts + FormatNumberService.ai.ts) reduced this to
 * 37 errors with zero regressions. Extrapolation: a full feedback
 * sweep brings idle-meta from ~48 → ~5-10 errors per realize.
 */
/**
 * Single error reported by a verifier. Position-optional (some
 * verifiers — Go vet, formatters — emit errors without precise
 * line/col).
 */
export interface VerifyError {
    /** Path to the source file, relative to the realized output dir. */
    file: string;
    line?: number;
    col?: number;
    /** Verifier-specific code, e.g. "TS2554", "py:E501", "go:S1000". */
    code: string;
    /** Human-readable description, suitable for inclusion in a feedback
     *  prompt. Verifier-specific; the framework doesn't interpret it. */
    message: string;
    severity: 'error' | 'warning';
}
/**
 * Result of running a single verifier on the realized output.
 */
export interface VerifyResult {
    /** Verifier id (matches `PostEmitVerifier.id`). */
    verifierId: string;
    /** Wall-time. Useful for tuning verifier order + budget. */
    durationMs: number;
    /** Whether the verifier ran successfully. False indicates a tool-level
     *  failure (tsc not installed, npm install needed first, etc.) — the
     *  feedback runner SKIPS the verifier when not ok, not when errors > 0. */
    ok: boolean;
    errors: VerifyError[];
    /** Non-fatal warnings from the verifier itself (separate from
     *  per-error severity), e.g. "tsc emitted 200 errors but we truncated
     *  to 100". */
    notes: string[];
}
/**
 * Context passed to verifiers — describes the realize target so each
 * verifier can decide whether it `applies`.
 *
 * Minimal for now; extends as new verifiers need additional signal.
 */
export interface VerifyContext {
    /** Absolute path to the realized output root (the dir that contains
     *  e.g. `backend/`, `frontend/`, `tests/`). */
    outputDir: string;
    /** Realize target tag, e.g. 'typescript', 'python', 'go'. Set by the
     *  realize pipeline based on the manifest's primary stack. */
    targetLanguage?: string;
    /** Optional: explicit subpath within outputDir to verify. tsc would
     *  typically scope to `backend/`. Defaults to outputDir itself. */
    subpath?: string;
    /**
     * When true (the default), verifiers MAY run dependency installation
     * (`npm install` / `pip install` / etc.) before running their actual
     * checks. Required for the in-pipeline `spv realize` invocation:
     * realize emits a scaffolded project but doesn't install deps, so
     * tsc/mypy/etc. wouldn't otherwise be available.
     *
     * Set to false in test harnesses or when the caller has already
     * installed deps. Each verifier decides whether to honour the hint —
     * a stub-only verifier might ignore it.
     */
    autoInstall?: boolean;
}
/**
 * A verifier runs a quality check on the realized output. Each
 * verifier is independent — the framework collects results from
 * applicable verifiers, then the feedback runner decides what to do.
 *
 * Implementations must NOT throw on tool-level failures; return
 * `{ ok: false, errors: [], notes: ['…'] }` instead. The framework
 * surfaces notes to the user; throws crash the realize pipeline.
 */
export interface PostEmitVerifier {
    /** Stable identifier — kebab-case. e.g. 'tsc', 'mypy', 'go-vet'. */
    id: string;
    /** Human-readable name for logs and audit. */
    name: string;
    /**
     * Whether this verifier runs unless explicitly disabled. Mature
     * stable verifiers ship `enabledByDefault: true` (tsc); experimental
     * or third-party verifiers ship `false` to require an opt-in via
     * `SPECVERSE_REALIZE_POST_VERIFY_ENABLE=<id>,<id>` env (future).
     *
     * Optional for backwards compatibility — missing field is treated
     * as `true` (the original behavior).
     */
    enabledByDefault?: boolean;
    /** Predicate: does this verifier apply to the given context? */
    applies: (ctx: VerifyContext) => boolean;
    /** Run the verifier. MUST NOT throw on tool failure (return ok:false). */
    verify: (ctx: VerifyContext) => Promise<VerifyResult>;
}
/**
 * After all verifiers have run, the feedback runner needs to map
 * each errored file to its owning spec entity (e.g.
 * `backend/src/behaviors/AuthController.ai.ts` → ownerName=AuthController).
 *
 * Each verifier MAY contribute a mapping hint via `mapFileToOwner`,
 * but the framework falls back to a generic regex
 * (`behaviors/(.+)\\.ai\\.ts$` for TypeScript). Verifiers for other
 * stacks would override the mapping.
 */
export interface OwnerMapping {
    /** Source file path (relative to outputDir). */
    file: string;
    /** Inferred owner name. null if the file can't be mapped (e.g.
     *  shared infrastructure files generated by the framework, not by
     *  per-owner LLM emit — those should NOT receive feedback re-emits). */
    ownerName: string | null;
}
/**
 * Per-error fix strategy. Phase 2 of
 * 2026-05-13-VERIFIER-DIAGNOSTIC-TREATMENT-SPLIT — different verifier
 * errors need different fix strategies, not a single "always reemit"
 * path:
 *
 *   - `auto-reemit`: include this error in the file's reemit prompt;
 *     the LLM should try to fix it. Right for tsc errors (unambiguous
 *     fix) + γ-fallback / trivial-return / empty-body stubs (LLM never
 *     produced real output the first time; a second try with focused
 *     context is high-success).
 *
 *   - `surface-spec-gap`: do NOT reemit; surface the error to the user
 *     via the `realize-quality.json` sidecar (`specGaps` field).
 *     Right for STUB002 (LLM-throw stubs) where the LLM already
 *     signaled a context gap on the original emit — re-prompting
 *     either no-ops or hallucinates cross-file regressions (measured
 *     on idle-meta 2026-05-13 at engines 6.54.0).
 *
 *   - `skip`: ignore entirely. Right for unmappable errors (already
 *     filtered) and for future categories the framework doesn't know
 *     how to treat.
 */
export type TreatmentStrategy = 'auto-reemit' | 'surface-spec-gap' | 'skip';
/**
 * Decides how each verifier error should be treated. The default
 * selector lives in `feedback-runner.ts::defaultTreatmentSelector`;
 * callers may override for advanced cases (testing, custom verifiers,
 * different LLM tolerance profiles).
 */
export type TreatmentSelector = (error: VerifyError) => TreatmentStrategy;
/**
 * A single spec-level gap surfaced from a verifier error that the
 * framework chose NOT to auto-fix. Goes into the realize-quality.json
 * sidecar's `specGaps` array; users read it and decide whether to
 * adjust the spec/manifest, switch providers, or hand-edit.
 */
export interface SpecGapEntry {
    /** Owner name (e.g. "AuthController"). null when unmappable. */
    ownerName: string | null;
    /** Source file path, relative to outputDir. */
    file: string;
    line?: number;
    col?: number;
    /** Verifier code (e.g. "STUB002"). */
    code: string;
    /** Verifier-formatted message — directly suitable for user reading. */
    message: string;
}
//# sourceMappingURL=types.d.ts.map