/**
 * Port: A single step in the evaluation pipeline.
 *
 * Steps are composable, independently testable, and uniformly executed
 * by the StepRunner. Each step declares its preconditions, execution
 * logic, and cache inputs.
 */
import type { PipelineState, StepResult, ValidationIssue } from "../types/index.js";
import type { AppContext } from "./context.js";
export interface PipelineStep {
    /** Human-readable step name for logging and diagnostics */
    readonly name: string;
    /**
     * Precondition check — validates that required files, config, and
     * environment are in place before execution.
     *
     * @returns Array of validation issues (empty = all clear)
     */
    check(ctx: AppContext): ValidationIssue[];
    /**
     * Execute the step. May read from filesystem, call APIs, spawn
     * processes, or delegate to domain services.
     *
     * @param ctx — Immutable application context (config, adapters, logger)
     * @param state — Mutable state bag for inter-step data flow. Producer
     *   steps write values (e.g., `state.reportId`); consumer steps read
     *   them. Steps that don't participate in inter-step data flow can
     *   ignore this parameter.
     *
     * @returns Step result with status, duration, and summary/error
     */
    execute(ctx: AppContext, state: PipelineState): Promise<StepResult>;
    /**
     * Cache key inputs — file paths or content identifiers that determine
     * whether this step's output is still valid.
     *
     * When undefined, the step is never cached (always executes).
     * When defined, the StepRunner computes a hash and checks the cache.
     */
    cacheInputs?(ctx: AppContext): string[];
    /**
     * Cache context strings — non-file state that participates in cache key
     * computation (e.g., mode, variant, area/task/tag filters).
     *
     * Without these, two runs with different CLI flags but identical config
     * files would share a cache entry, causing cross-mode or cross-area
     * contamination.
     *
     * When undefined, only file content determines the cache key.
     */
    cacheContext?(ctx: AppContext): string[];
    /**
     * Whether this step is optional — a failure in an optional step
     * does not stop the pipeline.
     */
    readonly optional?: boolean;
}
