gate_contract/

lib.rs

//! Fail-closed gate contracts for staged build pipelines.
//!
//! A pipeline that only knows PASS and FAIL has a third state hiding inside it: the gate
//! that could not be evaluated at all, because a credential was missing, an API timed out,
//! or the value it needed was never produced. Treating that as a pass is how a run reaches
//! deploy having checked nothing. This crate makes the third state explicit and closes it.
//!
//! The rule enforced throughout:
//!
//! > A **blocking** gate halts the run when it fails **and** when it cannot be evaluated.
//! > "Could not check" is not "fine".
//!
//! # The pieces
//!
//! - [`Outcome`] — `Pass`, `Fail`, or `Unevaluable`, each carrying a reason string.
//! - [`Known`] — a value that may be `Unknown`; unknown propagates through combination
//!   instead of decaying into a default.
//! - [`Gate`] — an id, a [`Severity`] (blocking or advisory) and an outcome.
//! - [`Stage`] — a named set of gates, evaluated together so one run reports every failure.
//! - [`Pipeline`] — ordered stages, halting at the first stage that halts.
//!
//! # Example
//!
//! ```
//! use gate_contract::{Gate, Severity, Stage, Verdict};
//!
//! let stage = Stage::new("harvest")
//!     .with_gate(Gate::pass("serp-rows-present"))
//!     .with_gate(Gate::unevaluable("rdap-reachable", "no credential on disk"));
//!
//! let report = stage.evaluate();
//! assert!(report.halted());
//! match report.verdict {
//!     Verdict::Halt { ref gate_id, .. } => assert_eq!(gate_id, "rdap-reachable"),
//!     Verdict::Proceed => unreachable!(),
//! }
//! ```
//!
//! An advisory gate records the same information without stopping anything:
//!
//! ```
//! use gate_contract::{Gate, Stage};
//!
//! let report = Stage::new("design")
//!     .with_gate(Gate::fail("tone-check", "two sentences flagged").advisory())
//!     .evaluate();
//! assert!(!report.halted());
//! assert_eq!(report.warnings().len(), 1);
//! ```
//!
//! No dependencies, no I/O, no unsafe. Evaluating what a gate *means* is this crate's job;
//! deciding what to measure is yours.
//!
//! Extracted from a real staged build pipeline, whose first blocking gate is worked through in
//! public at <https://aiwebsitepipeline.com/niche-score.html>: six subscores, the weights that
//! combine them, and the thresholds that decide the run — 55 and above proceeds, 40 to 55
//! proceeds under a page cap, below 40 the run halts. That page is a concrete example of the
//! shape [`Severity::Blocking`] exists to express, and is worth reading before deciding what
//! your own gates should refuse.

#![forbid(unsafe_code)]
#![deny(missing_docs)]

use std::fmt;

/// Whether a gate can stop the run.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum Severity {
    /// Failure or non-evaluation halts the run.
    Blocking,
    /// Failure is recorded as a warning and the run continues.
    Advisory,
}

impl Severity {
    /// Whether this severity can halt a run.
    pub fn is_blocking(self) -> bool {
        matches!(self, Severity::Blocking)
    }
}

impl fmt::Display for Severity {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            Severity::Blocking => f.write_str("blocking"),
            Severity::Advisory => f.write_str("advisory"),
        }
    }
}

/// The result of evaluating one gate.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum Outcome {
    /// The condition was checked and held.
    Pass,
    /// The condition was checked and did not hold.
    Fail(String),
    /// The condition could not be checked at all.
    Unevaluable(String),
}

impl Outcome {
    /// Whether the check ran to a verdict, pass or fail.
    pub fn was_evaluated(&self) -> bool {
        !matches!(self, Outcome::Unevaluable(_))
    }

    /// Whether the condition held.
    pub fn passed(&self) -> bool {
        matches!(self, Outcome::Pass)
    }

    /// The reason attached to a fail or a non-evaluation, if any.
    pub fn reason(&self) -> Option<&str> {
        match self {
            Outcome::Pass => None,
            Outcome::Fail(r) | Outcome::Unevaluable(r) => Some(r.as_str()),
        }
    }
}

impl fmt::Display for Outcome {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            Outcome::Pass => f.write_str("PASS"),
            Outcome::Fail(r) => write!(f, "FAIL: {r}"),
            Outcome::Unevaluable(r) => write!(f, "UNEVALUABLE: {r}"),
        }
    }
}

/// Why a run halted.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum HaltCause {
    /// A blocking gate was checked and did not hold.
    BlockingFailure,
    /// A blocking gate could not be checked.
    BlockingUnevaluable,
}

impl fmt::Display for HaltCause {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            HaltCause::BlockingFailure => f.write_str("blocking gate failed"),
            HaltCause::BlockingUnevaluable => f.write_str("blocking gate could not be evaluated"),
        }
    }
}

/// What the caller should do next.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum Verdict {
    /// Nothing blocking objected; continue.
    Proceed,
    /// Stop, and here is the first gate that said so.
    Halt {
        /// Id of the gate that halted the run.
        gate_id: String,
        /// Whether it failed or could not be evaluated.
        cause: HaltCause,
        /// The gate's reason string.
        reason: String,
    },
}

impl Verdict {
    /// Whether this verdict stops the run.
    pub fn is_halt(&self) -> bool {
        matches!(self, Verdict::Halt { .. })
    }
}

/// One contract: an identifier, a severity and an outcome.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct Gate {
    /// Stable identifier, e.g. `"rdap-reachable"`.
    pub id: String,
    /// Whether this gate can halt the run.
    pub severity: Severity,
    /// The evaluated outcome.
    pub outcome: Outcome,
}

impl Gate {
    /// A blocking gate with an explicit outcome.
    pub fn new(id: impl Into<String>, outcome: Outcome) -> Self {
        Gate {
            id: id.into(),
            severity: Severity::Blocking,
            outcome,
        }
    }

    /// A blocking gate that passed.
    pub fn pass(id: impl Into<String>) -> Self {
        Gate::new(id, Outcome::Pass)
    }

    /// A blocking gate that failed, with the reason.
    pub fn fail(id: impl Into<String>, reason: impl Into<String>) -> Self {
        Gate::new(id, Outcome::Fail(reason.into()))
    }

    /// A blocking gate that could not be checked, with the reason.
    pub fn unevaluable(id: impl Into<String>, reason: impl Into<String>) -> Self {
        Gate::new(id, Outcome::Unevaluable(reason.into()))
    }

    /// Downgrade this gate to advisory.
    pub fn advisory(mut self) -> Self {
        self.severity = Severity::Advisory;
        self
    }

    /// Build a gate from a boolean check, with the reason used when it is false.
    ///
    /// ```
    /// use gate_contract::Gate;
    /// let g = Gate::check("page-count-nonzero", 12 > 0, "no pages were produced");
    /// assert!(g.outcome.passed());
    /// ```
    pub fn check(id: impl Into<String>, held: bool, reason: impl Into<String>) -> Self {
        if held {
            Gate::pass(id)
        } else {
            Gate::fail(id, reason)
        }
    }

    /// Build a gate from a value that may be unknown.
    ///
    /// `Known(v)` is handed to `predicate`; `Unknown` short-circuits to
    /// [`Outcome::Unevaluable`], which is what makes the missing input halt a blocking
    /// gate instead of silently passing it.
    ///
    /// ```
    /// use gate_contract::{Gate, Known, Outcome};
    ///
    /// let measured: Known<u32> = Known::Unknown;
    /// let g = Gate::check_known("coverage-above-floor", &measured, |c| *c >= 50, "below floor");
    /// assert!(matches!(g.outcome, Outcome::Unevaluable(_)));
    /// ```
    pub fn check_known<T, F>(
        id: impl Into<String>,
        value: &Known<T>,
        predicate: F,
        reason: impl Into<String>,
    ) -> Self
    where
        F: FnOnce(&T) -> bool,
    {
        match value {
            Known::Unknown => Gate::unevaluable(id, "value is unknown"),
            Known::Known(v) => Gate::check(id, predicate(v), reason),
        }
    }

    /// Whether this gate, on its own, halts the run.
    pub fn halts(&self) -> bool {
        self.severity.is_blocking() && !self.outcome.passed()
    }

    fn halt_cause(&self) -> Option<HaltCause> {
        if !self.halts() {
            return None;
        }
        match self.outcome {
            Outcome::Fail(_) => Some(HaltCause::BlockingFailure),
            Outcome::Unevaluable(_) => Some(HaltCause::BlockingUnevaluable),
            Outcome::Pass => None,
        }
    }
}

impl fmt::Display for Gate {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(f, "[{}] {} {}", self.severity, self.id, self.outcome)
    }
}

/// A value that may not exist yet.
///
/// The point of a dedicated type is that `Unknown` cannot be mistaken for a zero or an
/// empty string once it reaches a comparison. Combining anything with `Unknown` yields
/// `Unknown`.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub enum Known<T> {
    /// The value was produced.
    Known(T),
    /// The value was not produced.
    #[default]
    Unknown,
}

impl<T> Known<T> {
    /// Whether a value is present.
    pub fn is_known(&self) -> bool {
        matches!(self, Known::Known(_))
    }

    /// Borrow the value if present.
    pub fn get(&self) -> Option<&T> {
        match self {
            Known::Known(v) => Some(v),
            Known::Unknown => None,
        }
    }

    /// Map the value, keeping `Unknown` unknown.
    pub fn map<U, F: FnOnce(T) -> U>(self, f: F) -> Known<U> {
        match self {
            Known::Known(v) => Known::Known(f(v)),
            Known::Unknown => Known::Unknown,
        }
    }

    /// Combine two values; if either is unknown the result is unknown.
    ///
    /// ```
    /// use gate_contract::Known;
    /// let a = Known::Known(2);
    /// let b: Known<i32> = Known::Unknown;
    /// assert_eq!(a.zip_with(b, |x, y| x + y), Known::Unknown);
    /// ```
    pub fn zip_with<U, R, F: FnOnce(T, U) -> R>(self, other: Known<U>, f: F) -> Known<R> {
        match (self, other) {
            (Known::Known(a), Known::Known(b)) => Known::Known(f(a, b)),
            _ => Known::Unknown,
        }
    }
}

impl<T> From<Option<T>> for Known<T> {
    fn from(opt: Option<T>) -> Self {
        match opt {
            Some(v) => Known::Known(v),
            None => Known::Unknown,
        }
    }
}

/// A named set of gates evaluated together.
#[derive(Debug, Clone, Default, PartialEq, Eq)]
pub struct Stage {
    /// Stage name, e.g. `"harvest"`.
    pub name: String,
    /// The gates belonging to this stage.
    pub gates: Vec<Gate>,
}

impl Stage {
    /// An empty stage.
    pub fn new(name: impl Into<String>) -> Self {
        Stage {
            name: name.into(),
            gates: Vec::new(),
        }
    }

    /// Append a gate, builder style.
    pub fn with_gate(mut self, gate: Gate) -> Self {
        self.gates.push(gate);
        self
    }

    /// Append a gate in place.
    pub fn push(&mut self, gate: Gate) {
        self.gates.push(gate);
    }

    /// Evaluate every gate and summarise.
    ///
    /// All gates are inspected, so one run reports every problem rather than only the
    /// first. The verdict names the first halting gate in declaration order.
    pub fn evaluate(&self) -> StageReport {
        let mut counts = GateCounts::default();
        let mut verdict = Verdict::Proceed;
        for gate in &self.gates {
            counts.total += 1;
            if gate.severity.is_blocking() {
                counts.blocking += 1;
            }
            match gate.outcome {
                Outcome::Pass => counts.passed += 1,
                Outcome::Fail(_) => counts.failed += 1,
                Outcome::Unevaluable(_) => counts.unevaluable += 1,
            }
            if verdict == Verdict::Proceed {
                if let Some(cause) = gate.halt_cause() {
                    verdict = Verdict::Halt {
                        gate_id: gate.id.clone(),
                        cause,
                        reason: gate.outcome.reason().unwrap_or_default().to_string(),
                    };
                }
            }
        }
        StageReport {
            stage: self.name.clone(),
            counts,
            verdict,
            gates: self.gates.clone(),
        }
    }
}

/// Tallies from one stage evaluation.
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
pub struct GateCounts {
    /// Gates in the stage.
    pub total: usize,
    /// Of those, how many are blocking.
    pub blocking: usize,
    /// Gates that passed.
    pub passed: usize,
    /// Gates that were checked and failed.
    pub failed: usize,
    /// Gates that could not be checked.
    pub unevaluable: usize,
}

/// The outcome of evaluating a [`Stage`].
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct StageReport {
    /// Name of the stage.
    pub stage: String,
    /// Tallies.
    pub counts: GateCounts,
    /// Proceed, or the first gate that halted the run.
    pub verdict: Verdict,
    /// Every gate as evaluated, in declaration order.
    pub gates: Vec<Gate>,
}

impl StageReport {
    /// Whether the stage halted the run.
    pub fn halted(&self) -> bool {
        self.verdict.is_halt()
    }

    /// Advisory gates that did not pass. These never halt; they are for the log.
    pub fn warnings(&self) -> Vec<&Gate> {
        self.gates
            .iter()
            .filter(|g| !g.severity.is_blocking() && !g.outcome.passed())
            .collect()
    }

    /// Every gate that did not pass, blocking or not.
    pub fn not_passing(&self) -> Vec<&Gate> {
        self.gates.iter().filter(|g| !g.outcome.passed()).collect()
    }
}

/// Ordered stages evaluated until one halts.
#[derive(Debug, Clone, Default, PartialEq, Eq)]
pub struct Pipeline {
    /// The stages, in execution order.
    pub stages: Vec<Stage>,
}

impl Pipeline {
    /// An empty pipeline.
    pub fn new() -> Self {
        Pipeline { stages: Vec::new() }
    }

    /// Append a stage, builder style.
    pub fn with_stage(mut self, stage: Stage) -> Self {
        self.stages.push(stage);
        self
    }

    /// Evaluate stages in order, stopping after the first that halts.
    ///
    /// Stages after a halt are not evaluated and do not appear in the report, which is
    /// the honest shape: they never ran, so they have no outcome.
    ///
    /// ```
    /// use gate_contract::{Gate, Pipeline, Stage};
    ///
    /// let run = Pipeline::new()
    ///     .with_stage(Stage::new("intake").with_gate(Gate::pass("scope-present")))
    ///     .with_stage(Stage::new("harvest").with_gate(Gate::unevaluable("api", "no key")))
    ///     .with_stage(Stage::new("build").with_gate(Gate::pass("never-reached")))
    ///     .run();
    ///
    /// assert!(run.halted());
    /// assert_eq!(run.reports.len(), 2);
    /// assert_eq!(run.halted_stage(), Some("harvest"));
    /// ```
    pub fn run(&self) -> RunReport {
        let mut reports = Vec::with_capacity(self.stages.len());
        for stage in &self.stages {
            let report = stage.evaluate();
            let halted = report.halted();
            reports.push(report);
            if halted {
                break;
            }
        }
        RunReport {
            reports,
            stages_declared: self.stages.len(),
        }
    }
}

/// The outcome of a whole pipeline run.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct RunReport {
    /// Reports for the stages that actually ran.
    pub reports: Vec<StageReport>,
    /// How many stages the pipeline declared, including any never reached.
    pub stages_declared: usize,
}

impl RunReport {
    /// Whether any stage halted the run.
    pub fn halted(&self) -> bool {
        self.reports.last().map(|r| r.halted()).unwrap_or(false)
    }

    /// Name of the halting stage, if any.
    pub fn halted_stage(&self) -> Option<&str> {
        self.reports
            .last()
            .filter(|r| r.halted())
            .map(|r| r.stage.as_str())
    }

    /// Stages declared but never evaluated because of an earlier halt.
    pub fn stages_skipped(&self) -> usize {
        self.stages_declared - self.reports.len()
    }

    /// Tallies summed across the stages that ran.
    pub fn counts(&self) -> GateCounts {
        let mut total = GateCounts::default();
        for r in &self.reports {
            total.total += r.counts.total;
            total.blocking += r.counts.blocking;
            total.passed += r.counts.passed;
            total.failed += r.counts.failed;
            total.unevaluable += r.counts.unevaluable;
        }
        total
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn a_passing_blocking_gate_proceeds() {
        let report = Stage::new("intake").with_gate(Gate::pass("scope")).evaluate();
        assert_eq!(report.verdict, Verdict::Proceed);
        assert!(!report.halted());
        assert_eq!(report.counts.passed, 1);
    }

    #[test]
    fn a_failing_blocking_gate_halts() {
        let report = Stage::new("build")
            .with_gate(Gate::fail("pages-nonzero", "zero pages"))
            .evaluate();
        match report.verdict {
            Verdict::Halt {
                gate_id,
                cause,
                reason,
            } => {
                assert_eq!(gate_id, "pages-nonzero");
                assert_eq!(cause, HaltCause::BlockingFailure);
                assert_eq!(reason, "zero pages");
            }
            Verdict::Proceed => panic!("should have halted"),
        }
    }

    #[test]
    fn an_unevaluable_blocking_gate_also_halts() {
        let report = Stage::new("harvest")
            .with_gate(Gate::unevaluable("rdap", "no credential"))
            .evaluate();
        assert!(report.halted());
        assert!(matches!(
            report.verdict,
            Verdict::Halt {
                cause: HaltCause::BlockingUnevaluable,
                ..
            }
        ));
        assert_eq!(report.counts.unevaluable, 1);
    }

    #[test]
    fn advisory_gates_never_halt_but_are_recorded() {
        let report = Stage::new("design")
            .with_gate(Gate::fail("tone", "flagged").advisory())
            .with_gate(Gate::unevaluable("readability", "no corpus").advisory())
            .with_gate(Gate::pass("prompt-vendored"))
            .evaluate();
        assert!(!report.halted());
        assert_eq!(report.warnings().len(), 2);
        assert_eq!(report.not_passing().len(), 2);
        assert_eq!(report.counts.blocking, 1);
        assert_eq!(report.counts.total, 3);
    }

    #[test]
    fn the_first_halting_gate_is_the_one_reported() {
        let report = Stage::new("qualify")
            .with_gate(Gate::pass("a"))
            .with_gate(Gate::fail("b", "first"))
            .with_gate(Gate::unevaluable("c", "second"))
            .evaluate();
        match report.verdict {
            Verdict::Halt { gate_id, .. } => assert_eq!(gate_id, "b"),
            Verdict::Proceed => panic!("should have halted"),
        }
        // Evaluation still visits every gate.
        assert_eq!(report.counts.failed, 1);
        assert_eq!(report.counts.unevaluable, 1);
    }

    #[test]
    fn check_builds_pass_or_fail_from_a_boolean() {
        assert!(Gate::check("g", true, "r").outcome.passed());
        assert_eq!(
            Gate::check("g", false, "r").outcome,
            Outcome::Fail("r".into())
        );
    }

    #[test]
    fn unknown_input_makes_a_gate_unevaluable_not_passing() {
        let unknown: Known<u32> = Known::Unknown;
        let gate = Gate::check_known("coverage", &unknown, |c| *c >= 50, "below floor");
        assert!(!gate.outcome.was_evaluated());
        assert!(gate.halts());

        let known = Known::Known(60u32);
        let gate = Gate::check_known("coverage", &known, |c| *c >= 50, "below floor");
        assert!(gate.outcome.passed());
        assert!(!gate.halts());
    }

    #[test]
    fn unknown_propagates_through_combination() {
        let a = Known::Known(10);
        let b: Known<i32> = Known::Unknown;
        assert_eq!(a.zip_with(b, |x, y| x + y), Known::Unknown);
        assert_eq!(
            Known::Known(10).zip_with(Known::Known(5), |x, y| x + y),
            Known::Known(15)
        );
        assert_eq!(b.map(|v| v * 2), Known::Unknown);
        assert_eq!(Known::from(Some(3)), Known::Known(3));
        assert_eq!(Known::<i32>::from(None), Known::Unknown);
        assert_eq!(Known::<i32>::default(), Known::Unknown);
        assert_eq!(Known::Known(7).get(), Some(&7));
        assert!(!b.is_known());
    }

    #[test]
    fn pipeline_stops_at_the_first_halting_stage() {
        let run = Pipeline::new()
            .with_stage(Stage::new("intake").with_gate(Gate::pass("scope")))
            .with_stage(Stage::new("harvest").with_gate(Gate::unevaluable("api", "no key")))
            .with_stage(Stage::new("build").with_gate(Gate::pass("unreached")))
            .run();
        assert!(run.halted());
        assert_eq!(run.halted_stage(), Some("harvest"));
        assert_eq!(run.reports.len(), 2);
        assert_eq!(run.stages_skipped(), 1);
        assert_eq!(run.counts().total, 2);
    }

    #[test]
    fn a_clean_pipeline_proceeds_through_every_stage() {
        let run = Pipeline::new()
            .with_stage(Stage::new("one").with_gate(Gate::pass("a")))
            .with_stage(Stage::new("two").with_gate(Gate::pass("b")))
            .run();
        assert!(!run.halted());
        assert_eq!(run.halted_stage(), None);
        assert_eq!(run.stages_skipped(), 0);
        assert_eq!(run.counts().passed, 2);
    }

    #[test]
    fn an_empty_pipeline_does_not_claim_to_have_halted() {
        let run = Pipeline::new().run();
        assert!(!run.halted());
        assert_eq!(run.counts(), GateCounts::default());
    }

    #[test]
    fn a_stage_can_be_built_imperatively() {
        let mut stage = Stage::new("measure");
        stage.push(Gate::pass("gsc-rows"));
        stage.push(Gate::fail("indexed", "0 of 14").advisory());
        let report = stage.evaluate();
        assert_eq!(report.counts.total, 2);
        assert!(!report.halted());
    }

    #[test]
    fn display_is_readable() {
        assert_eq!(Outcome::Pass.to_string(), "PASS");
        assert_eq!(
            Gate::fail("x", "because").to_string(),
            "[blocking] x FAIL: because"
        );
        assert_eq!(
            HaltCause::BlockingUnevaluable.to_string(),
            "blocking gate could not be evaluated"
        );
    }

    #[test]
    fn outcome_reasons_are_retrievable() {
        assert_eq!(Outcome::Pass.reason(), None);
        assert_eq!(Outcome::Fail("r".into()).reason(), Some("r"));
        assert_eq!(Outcome::Unevaluable("u".into()).reason(), Some("u"));
        assert!(Severity::Blocking.is_blocking());
        assert!(!Severity::Advisory.is_blocking());
    }
}