/**
 * pipeline/plan.ts
 *
 * Execution plan assembly for the `--explain` CLI flag.
 *
 * Computes a detailed preview of what a command will do without executing
 * anything. Calls existing pure functions (task expansion, model loading,
 * cache hashing, pricing) and composes them into an `ExecutionPlan`.
 *
 * @see docs/archive/exec-plans/execution-preview.md
 */
import type { DebugOptions, EvalMode } from "./types.js";
import { LiteracyVariant } from "./normalize-mode.js";
/** Comparison plan for --compare flag. */
export interface ComparisonPlan {
    /** Age of the baseline in human-readable form */
    baselineAge?: string;
    /** Path to the baseline file */
    baselinePath: string;
    /** Whether the baseline file exists */
    exists: boolean;
    /** Noise threshold for comparison */
    threshold: number;
}
/** Cost estimate for the evaluation run. */
export interface CostEstimate {
    /** Grading cost estimate (min/max) */
    grading: {
        max: number;
        min: number;
    };
    /** Number of grading calls (rubric evaluations) */
    gradingCalls: number;
    /** Per-model evaluation cost breakdown */
    perModel: {
        cost: {
            max: number;
            min: number;
        };
        label: string;
        modelName: string;
    }[];
    /** Total API calls for evaluation (tests × models) */
    totalApiCalls: number;
    /** Total estimated cost (min/max) */
    totalCost: {
        max: number;
        min: number;
    };
}
/** Debug filtering plan. */
export interface DebugPlan {
    /** Description of the debug filter applied */
    filterDescription: string;
    /** How many tests survive debug filtering */
    filteredCount: number;
    /** Total tests before debug filtering */
    totalCount: number;
}
/** The complete execution plan for any command. */
export interface ExecutionPlan {
    /** Cache prediction per step */
    cacheStatus: Record<string, "hit" | "miss" | "skipped" | "unknown">;
    /** Command name (e.g., "run", "compare", "validate") */
    command: string;
    /** Comparison plan (when --compare is set) */
    comparison?: ComparisonPlan;
    /** Estimated cost */
    costEstimate?: CostEstimate;
    /** Debug filter plan */
    debug?: DebugPlan;
    /** Human-readable description of what the command does */
    description: string;
    /** Validation errors (would prevent execution) */
    errors: string[];
    /** Files that will be created or updated */
    filesCreated: string[];
    /** Files that will be read as input */
    filesRead: string[];
    /** Evaluation mode */
    mode?: EvalMode;
    /** Model plan */
    models?: ModelPlan[];
    /** Documentation source */
    source?: string;
    /** Step-by-step plan */
    steps: StepPlan[];
    /** Task plan */
    tasks?: TaskPlan[];
    /** Total estimated time savings from cache hits */
    totalCacheSavingsMs: number;
    /** Total number of tests to run */
    totalTests?: number;
    /** Number of tests from repo-based tasks (included in totalTests) */
    repoTaskCount?: number;
    /** Validation warnings */
    warnings: string[];
}
/** A model that will be evaluated. */
export interface ModelPlan {
    /** Provider ID (e.g., "openai:chat:gpt-5.2") */
    id: string;
    /** Human-readable label */
    label: string;
    /** Raw model name for pricing lookup */
    modelName: string;
}
/** Description of a single pipeline step in the execution plan. */
export interface StepPlan {
    /** Cache prediction: hit (will skip), miss (will execute), skipped (flag), or unknown */
    cacheStatus: "hit" | "miss" | "skipped" | "unknown";
    /** Estimated duration in ms from cached data (if cache hit predicted) */
    estimatedSavedMs?: number;
    /** Human-readable name */
    name: string;
    /** Short description of what happens */
    reason: string;
    /** Whether this step will execute */
    willRun: boolean;
}
/** A task that will be included in the evaluation. */
export interface TaskPlan {
    /** Test description */
    description: string;
    /** Whether this is a gold (with docs) or standard/baseline (without docs) variant */
    variant: typeof LiteracyVariant.STANDARD | "gold";
}
/** Minimal options shape needed to build a pipeline execution plan. */
export interface PlanOptions {
    areaOption?: string;
    beforeOption?: string;
    compareBaseline?: string;
    compareEnabled: boolean;
    compareThreshold?: number;
    concurrency?: number;
    debug?: DebugOptions;
    dryRun: boolean;
    gapAnalysisEnabled: boolean;
    graderReplications?: number;
    mode: EvalMode;
    /** Literacy variant when mode is "literacy" (baseline, agentic, observed, full) */
    variant?: string;
    noCache: boolean;
    publishEnabled: boolean;
    repoTasksPath?: string;
    skipEval: boolean;
    skipFetch: boolean;
    source?: string;
    tagOption?: string[];
    taskOption?: string;
}
/**
 * Build a complete execution plan for the `run` command.
 *
 * This is a read-only operation — it computes the plan by calling existing
 * pure functions (task expansion, model loading, cache lookup, pricing)
 * without executing any pipeline steps or writing to process.env.
 */
export declare function buildPipelinePlan(opts: PlanOptions, rootDir: string): Promise<ExecutionPlan>;
/**
 * Build a minimal plan for commands that don't have complex step graphs.
 * Used by compare, validate, fetch-docs, baseline, etc.
 */
export declare function buildSimpleCommandPlan(opts: {
    command: string;
    description: string;
    filesCreated?: string[];
    filesRead?: string[];
    rootDir: string;
    steps?: StepPlan[];
}): ExecutionPlan;
