boundgraph-check 0.1.0

//! Does it build?
//!
//! The check that makes coding agents usable. A model that has been told the
//! code compiles will say the code compiles; a compiler that has been run
//! either exits zero or does not. Everything else in this crate is machinery
//! around that difference.
//!
//! # Which compiler, and why the checker refuses to exist without knowing
//!
//! "It type-checks" is not a claim about a patch, it is a claim about a patch
//! *and a compiler*. The same file passes `tsc` 5.4 and fails 5.7; `mypy`
//! changes what it rejects with every minor release. Evidence that did not say
//! which tool produced it would be unfalsifiable six months later, which is the
//! opposite of what evidence is for.
//!
//! So [`CompileChecker::probe`] runs the tool's version command *first* and
//! records the answer in the checker's own [`CheckerId`], which the trait then
//! writes into every piece of evidence. A tool that cannot be identified yields
//! no checker, and therefore no verdicts — which is the right failure, because
//! a verdict from an unknown compiler would have been worthless anyway.
//!
//! # The verdict mapping
//!
//! | What happened | Verdict |
//! |---|---|
//! | exit 0 | `Pass` |
//! | non-zero exit | `Fail`, with the diagnostics |
//! | killed at the timeout | `Inconclusive` |
//! | the sandbox refused, or the tool would not start | `Inconclusive` |
//!
//! The last two rows are the ones worth stating. A build that timed out has not
//! shown the code to be broken, so calling it `Fail` would send a repair loop
//! chasing a bug that is not there — and calling it `Pass` would commit code
//! nobody compiled. `Inconclusive` is neither, and it does not commit.
//!
//! # Diagnostics are cut from the front
//!
//! A failing compiler's first error is usually the cause and the rest are
//! consequences of it, so what a repair loop needs is the head of the output.
//! That is the opposite of a test runner, which puts its summary at the end,
//! and the two checkers differ accordingly.

use std::path::{Path, PathBuf};
use std::time::Duration;

use async_trait::async_trait;
use boundgraph_core::{CheckerId, Condensate, Digest, GrantSet, WorkOrder};

use crate::checker::{Checker, Judgement};
use crate::sandbox::{Command, DEFAULT_TIMEOUT, Sandbox, SandboxError, workspace_grant};

/// How much of a compiler's output reaches the failure reason.
///
/// The reason is read by a model on the next repair attempt, so it competes for
/// the same context window everything else does. Enough for the first several
/// errors, and no more.
pub const MAX_REASON: usize = 4_000;

/// A tool to compile or type-check with.
///
/// The three constructors cover what US-0804 names. Anything else is
/// [`CompileConfig::new`].
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct CompileConfig {
    /// The program to run.
    pub program: String,
    /// The arguments that perform the check.
    pub args: Vec<String>,
    /// The arguments that make it print its version, e.g. `--version`.
    pub version_args: Vec<String>,
    /// The directory to run in, and the only one the checker may read.
    pub workspace: PathBuf,
    /// How long the check may run before it is killed.
    pub timeout: Duration,
}

impl CompileConfig {
    /// A tool invocation, with the default timeout and `--version` as the
    /// version command.
    pub fn new(
        program: impl Into<String>,
        args: impl IntoIterator<Item = impl Into<String>>,
        workspace: impl Into<PathBuf>,
    ) -> Self {
        Self {
            program: program.into(),
            args: args.into_iter().map(Into::into).collect(),
            version_args: vec!["--version".to_string()],
            workspace: workspace.into(),
            timeout: DEFAULT_TIMEOUT,
        }
    }

    /// `cargo check --all-targets`.
    ///
    /// `check` rather than `build`: it type-checks without linking, which is
    /// several times faster and is the whole of what this checker claims.
    pub fn cargo(workspace: impl Into<PathBuf>) -> Self {
        Self::new("cargo", ["check", "--all-targets", "--quiet"], workspace)
    }

    /// `tsc --noEmit`.
    ///
    /// `--noEmit` because a checker may not write to the workspace, and `tsc`
    /// writes JavaScript unless told not to.
    pub fn tsc(workspace: impl Into<PathBuf>) -> Self {
        Self::new("tsc", ["--noEmit"], workspace)
    }

    /// `mypy .`.
    pub fn mypy(workspace: impl Into<PathBuf>) -> Self {
        Self::new("mypy", ["."], workspace)
    }

    /// Ask for the version some other way than `--version`.
    #[must_use]
    pub fn versioned_by(mut self, args: impl IntoIterator<Item = impl Into<String>>) -> Self {
        self.version_args = args.into_iter().map(Into::into).collect();
        self
    }

    /// Kill the check after `timeout`.
    #[must_use]
    pub fn within(mut self, timeout: Duration) -> Self {
        self.timeout = timeout;
        self
    }

    /// The grant this configuration needs: read the workspace, execute the
    /// tool, nothing else.
    pub fn grant(&self) -> GrantSet {
        workspace_grant(&self.workspace, &self.program)
    }

    fn check_command(&self) -> Command {
        Command::new(&self.program, self.args.clone(), self.workspace.clone()).within(self.timeout)
    }

    fn version_command(&self) -> Command {
        Command::new(
            &self.program,
            self.version_args.clone(),
            self.workspace.clone(),
        )
        // A tool that cannot say its own version in half a minute is broken.
        .within(Duration::from_secs(30))
    }
}

/// The tool could not be identified, so no checker was built.
#[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)]
#[non_exhaustive]
pub enum ProbeError {
    /// The version command could not be run.
    #[error("could not run `{command}` to identify the tool: {source}")]
    Unrunnable {
        /// What was attempted.
        command: String,
        /// Why it failed.
        #[source]
        source: SandboxError,
    },

    /// The version command ran and failed, or printed nothing.
    #[error("`{command}` did not report a version: {detail}")]
    NoVersion {
        /// What was attempted.
        command: String,
        /// What happened instead.
        detail: String,
    },
}

/// Compiles or type-checks a workspace, and reports whether it built.
///
/// Built by [`probe`](Self::probe), which identifies the tool first. See the
/// module documentation for why that is not optional.
#[derive(Debug, Clone)]
pub struct CompileChecker {
    config: CompileConfig,
    tool: String,
    id: CheckerId,
}

impl CompileChecker {
    /// Identify the tool, then build a checker bound to that version.
    ///
    /// # Errors
    ///
    /// [`ProbeError`] if the tool could not be run or would not say what it is.
    /// There is deliberately no fallback to an unidentified checker.
    pub async fn probe(sandbox: &dyn Sandbox, config: CompileConfig) -> Result<Self, ProbeError> {
        let command = config.version_command();
        let outcome = sandbox
            .run(&command, &config.grant())
            .await
            .map_err(|source| ProbeError::Unrunnable {
                command: command.rendered(),
                source,
            })?;

        if !outcome.succeeded() {
            return Err(ProbeError::NoVersion {
                command: command.rendered(),
                detail: if outcome.timed_out {
                    "it did not finish".to_string()
                } else {
                    format!("exit {:?}: {}", outcome.exit, outcome.diagnostics())
                },
            });
        }

        // First line only. `cargo --version` is one line; `mypy --version` is
        // one line; `tsc --version` is one line. A tool that prints a banner
        // first would give a useless identity, and a wrong identity is worse
        // than a long one, so this is the line that names it.
        let tool = outcome
            .stdout
            .lines()
            .map(str::trim)
            .find(|line| !line.is_empty())
            .ok_or_else(|| ProbeError::NoVersion {
                command: command.rendered(),
                detail: "it printed nothing".to_string(),
            })?
            .to_string();

        Ok(Self::declaring(config, tool))
    }

    /// Build a checker for a tool whose version is already known.
    ///
    /// For a replayed run (US-1006) and for a test, where the tool identity
    /// comes from the recording rather than from running anything. Using it
    /// with a version the tool does not actually have produces evidence that
    /// says something false, so it is for reconstruction, not convenience.
    pub fn declaring(config: CompileConfig, tool: impl Into<String>) -> Self {
        let tool = tool.into();
        Self {
            // The tool identity travels in the checker's name because that is
            // the field a verifier reads. `Evidence` has one place to put it.
            id: CheckerId::new(format!("compile[{tool}]"), 1),
            tool,
            config,
        }
    }

    /// The tool this checker is bound to, as the tool reported itself.
    pub fn tool(&self) -> &str {
        &self.tool
    }

    /// The workspace being checked.
    pub fn workspace(&self) -> &Path {
        &self.config.workspace
    }
}

/// Keep the head of `text`, which is where a compiler's real error is.
///
/// Counting characters rather than bytes, so a multi-byte character is never
/// cut in half and the result is always printable.
pub fn head(text: &str, limit: usize) -> String {
    if text.chars().count() <= limit {
        return text.to_string();
    }
    let kept: String = text.chars().take(limit).collect();
    format!("{kept}\n… (output truncated)")
}

/// A checker built over a sandbox it does not own.
///
/// The sandbox is held rather than passed to `judge`, because [`Checker::judge`]
/// takes only the work order and the condensate — the checker's environment is
/// part of the checker.
#[derive(Debug)]
pub struct SandboxedCompile<S: Sandbox> {
    checker: CompileChecker,
    sandbox: S,
}

impl<S: Sandbox> SandboxedCompile<S> {
    /// Identify the tool through `sandbox`, then bind the checker to it.
    ///
    /// # Errors
    ///
    /// [`ProbeError`] if the tool could not be identified.
    pub async fn probe(sandbox: S, config: CompileConfig) -> Result<Self, ProbeError> {
        let checker = CompileChecker::probe(&sandbox, config).await?;
        Ok(Self { checker, sandbox })
    }

    /// Bind to a tool whose version is already known.
    pub fn declaring(sandbox: S, config: CompileConfig, tool: impl Into<String>) -> Self {
        Self {
            checker: CompileChecker::declaring(config, tool),
            sandbox,
        }
    }

    /// The tool this checker is bound to.
    pub fn tool(&self) -> &str {
        self.checker.tool()
    }
}

#[async_trait]
impl<S: Sandbox> Checker for SandboxedCompile<S> {
    fn id(&self) -> CheckerId {
        self.checker.id.clone()
    }

    fn grants(&self) -> GrantSet {
        self.checker.config.grant()
    }

    async fn judge(&self, _order: &WorkOrder, _condensate: &Condensate) -> Judgement {
        let config = &self.checker.config;
        let command = config.check_command();

        // The tool identity is bound into the evidence as well as named in the
        // checker id, so a verdict cannot be re-labelled with a different
        // compiler without breaking the signature.
        let tool = Digest::of(self.checker.tool.as_bytes());

        let outcome = match self.sandbox.run(&command, &config.grant()).await {
            Ok(outcome) => outcome,
            // The check did not happen. That is not the code's fault, so it is
            // not a failure of the code.
            Err(e) => {
                return Judgement::inconclusive(format!("the check could not be run: {e}"))
                    .covering(tool);
            }
        };

        if outcome.timed_out {
            return Judgement::inconclusive(format!(
                "`{}` did not finish within {:?}",
                command.rendered(),
                config.timeout
            ))
            .covering(tool);
        }

        let judgement = match outcome.exit {
            Some(0) => Judgement::pass(),
            Some(code) => {
                let diagnostics = outcome.diagnostics();
                let detail = if diagnostics.is_empty() {
                    "no diagnostics were produced".to_string()
                } else {
                    head(&diagnostics, MAX_REASON)
                };
                Judgement::fail(format!(
                    "`{}` exited {code} under {}:\n{detail}",
                    command.rendered(),
                    self.checker.tool
                ))
            }
            // Killed by a signal, or otherwise gone without a status. Nothing
            // was shown either way.
            None => Judgement::inconclusive(format!(
                "`{}` ended without an exit status",
                command.rendered()
            )),
        };

        judgement.covering(tool)
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::sandbox::Outcome;
    use crate::sign::LocalKey;
    use boundgraph_core::{CondensatePayload, Intent, ProposalOrigin, SchemaId, SlicerId, Verdict};
    use std::sync::Mutex;

    /// A sandbox that answers from a script rather than running anything.
    #[derive(Debug)]
    struct Scripted {
        version: Result<Outcome, SandboxError>,
        check: Result<Outcome, SandboxError>,
        seen: Mutex<Vec<String>>,
    }

    impl Scripted {
        fn new(version: Outcome, check: Result<Outcome, SandboxError>) -> Self {
            Self {
                version: Ok(version),
                check,
                seen: Mutex::new(Vec::new()),
            }
        }

        fn ran(&self) -> Vec<String> {
            self.seen.lock().unwrap().clone()
        }
    }

    #[async_trait]
    impl Sandbox for Scripted {
        async fn run(&self, command: &Command, _grant: &GrantSet) -> Result<Outcome, SandboxError> {
            self.seen.lock().unwrap().push(command.rendered());
            if command.args.iter().any(|a| a == "--version") {
                self.version.clone()
            } else {
                self.check.clone()
            }
        }
    }

    fn outcome(exit: Option<i32>, stdout: &str, stderr: &str) -> Outcome {
        Outcome {
            exit,
            stdout: stdout.to_string(),
            stderr: stderr.to_string(),
            timed_out: false,
            truncated: false,
            duration: Duration::from_millis(10),
        }
    }

    fn timed_out() -> Outcome {
        Outcome {
            exit: None,
            stdout: String::new(),
            stderr: String::new(),
            timed_out: true,
            truncated: false,
            duration: Duration::from_secs(300),
        }
    }

    fn version() -> Outcome {
        outcome(Some(0), "cargo 1.85.0 (1d8b05cdd 2026-01-20)\n", "")
    }

    fn config() -> CompileConfig {
        CompileConfig::cargo("/work/repo")
    }

    fn order() -> WorkOrder {
        WorkOrder::new(
            Intent::new("patch.apply", &"fix the borrow error").unwrap(),
            vec![],
            GrantSet::EMPTY,
            ProposalOrigin::new("claude-opus-5", [], Digest::of(b"prompt")),
        )
    }

    fn condensate() -> Condensate {
        Condensate::new(
            SchemaId::new("boundgraph.diff.v1", 1),
            CondensatePayload::inline(&"one file changed").unwrap(),
            Digest::of(b"the patch"),
            400,
            false,
            SlicerId::new("diff", 1),
        )
    }

    fn key() -> LocalKey {
        LocalKey::from_seed("host-key-1", [7u8; 32])
    }

    async fn verdict_for(check: Result<Outcome, SandboxError>) -> Verdict {
        let sandbox = Scripted::new(version(), check);
        let checker = SandboxedCompile::probe(sandbox, config()).await.unwrap();
        checker
            .check(&order(), &condensate(), &key())
            .await
            .unwrap()
            .verdict
    }

    // ── the verdict mapping ─────────────────────────────────────────────────

    /// The criterion: exit status maps to the verdict.
    #[tokio::test]
    async fn a_clean_build_passes() {
        assert_eq!(
            verdict_for(Ok(outcome(Some(0), "", ""))).await,
            Verdict::Pass
        );
    }

    /// The criterion: a non-zero exit is `Fail` with the diagnostics as the
    /// reason.
    #[tokio::test]
    async fn a_failed_build_fails_with_the_diagnostics() {
        let errors = "error[E0502]: cannot borrow `x` as mutable\n  --> src/main.rs:12:5\n";
        let verdict = verdict_for(Ok(outcome(Some(101), "", errors))).await;

        let Verdict::Fail(reason) = verdict else {
            panic!("expected Fail, got {verdict:?}");
        };
        assert!(reason.contains("E0502"), "{reason}");
        assert!(reason.contains("src/main.rs:12"), "{reason}");
        assert!(reason.contains("exited 101"), "{reason}");
    }

    /// The criterion: a timeout is `Inconclusive`, never `Pass`.
    #[tokio::test]
    async fn a_timeout_is_inconclusive_never_a_pass() {
        let verdict = verdict_for(Ok(timed_out())).await;

        assert!(matches!(verdict, Verdict::Inconclusive(_)), "{verdict:?}");
        assert!(!verdict.is_pass());
    }

    /// A build that timed out has not shown the code to be broken either, so
    /// sending a repair loop after it would be chasing a bug that is not there.
    #[tokio::test]
    async fn a_timeout_is_not_a_failure_either() {
        assert!(!matches!(
            verdict_for(Ok(timed_out())).await,
            Verdict::Fail(_)
        ));
    }

    #[tokio::test]
    async fn a_sandbox_that_refuses_leaves_the_verdict_undecided() {
        let refused = Err(SandboxError::Unenforceable {
            atom: "net:egress:**".into(),
            command: "cargo check".into(),
        });
        let verdict = verdict_for(refused).await;

        assert!(matches!(verdict, Verdict::Inconclusive(_)), "{verdict:?}");
    }

    #[tokio::test]
    async fn a_tool_killed_by_a_signal_is_inconclusive() {
        let verdict = verdict_for(Ok(outcome(None, "", ""))).await;
        assert!(matches!(verdict, Verdict::Inconclusive(_)), "{verdict:?}");
    }

    #[tokio::test]
    async fn a_failure_with_no_output_at_all_still_says_something_useful() {
        let verdict = verdict_for(Ok(outcome(Some(1), "", ""))).await;

        let Verdict::Fail(reason) = verdict else {
            panic!("expected Fail");
        };
        assert!(reason.contains("no diagnostics"), "{reason}");
    }

    #[tokio::test]
    async fn diagnostics_on_stdout_are_read_too() {
        let verdict = verdict_for(Ok(outcome(
            Some(2),
            "error: Type 'x' is not assignable",
            "",
        )))
        .await;
        assert!(verdict.reason().unwrap().contains("not assignable"));
    }

    // ── identifying the tool ────────────────────────────────────────────────

    /// The criterion: the tool version is recorded in the evidence.
    #[tokio::test]
    async fn the_tool_version_reaches_the_evidence() {
        let sandbox = Scripted::new(version(), Ok(outcome(Some(0), "", "")));
        let checker = SandboxedCompile::probe(sandbox, config()).await.unwrap();

        let evidence = checker
            .check(&order(), &condensate(), &key())
            .await
            .unwrap();

        assert!(
            evidence.checker.name.contains("cargo 1.85.0"),
            "an auditor must be able to read which compiler said so: {}",
            evidence.checker.name
        );
        assert!(
            evidence.covers(&Digest::of(b"cargo 1.85.0 (1d8b05cdd 2026-01-20)")),
            "and it must be bound by the signature, not merely printed"
        );
    }

    #[tokio::test]
    async fn two_versions_of_one_tool_are_different_checkers() {
        let a = SandboxedCompile::declaring(
            Scripted::new(version(), Ok(outcome(Some(0), "", ""))),
            config(),
            "tsc 5.4.2",
        );
        let b = SandboxedCompile::declaring(
            Scripted::new(version(), Ok(outcome(Some(0), "", ""))),
            config(),
            "tsc 5.7.0",
        );

        assert_ne!(a.id(), b.id());
    }

    /// A verdict from an unknown compiler would be worthless, so there is no
    /// fallback to an unidentified checker.
    #[tokio::test]
    async fn a_tool_that_will_not_say_what_it_is_yields_no_checker() {
        let silent = Scripted::new(outcome(Some(0), "", ""), Ok(outcome(Some(0), "", "")));
        let err = SandboxedCompile::probe(silent, config()).await.unwrap_err();
        assert!(matches!(err, ProbeError::NoVersion { .. }), "{err:?}");

        let missing = Scripted {
            version: Err(SandboxError::Spawn {
                command: "tsc --version".into(),
                detail: "not found".into(),
            }),
            check: Ok(outcome(Some(0), "", "")),
            seen: Mutex::new(Vec::new()),
        };
        let err = SandboxedCompile::probe(missing, config())
            .await
            .unwrap_err();
        assert!(matches!(err, ProbeError::Unrunnable { .. }), "{err:?}");
    }

    #[tokio::test]
    async fn a_version_command_that_fails_yields_no_checker() {
        let broken = Scripted::new(
            outcome(Some(127), "", "command not found"),
            Ok(outcome(Some(0), "", "")),
        );
        assert!(SandboxedCompile::probe(broken, config()).await.is_err());
    }

    #[tokio::test]
    async fn the_version_is_asked_for_before_the_check_is_run() {
        let sandbox = Scripted::new(version(), Ok(outcome(Some(0), "", "")));
        let checker = SandboxedCompile::probe(sandbox, config()).await.unwrap();
        checker
            .check(&order(), &condensate(), &key())
            .await
            .unwrap();

        let ran = checker.sandbox.ran();
        assert!(ran[0].contains("--version"), "{ran:?}");
        assert!(ran[1].contains("check"), "{ran:?}");
    }

    // ── authority ───────────────────────────────────────────────────────────

    /// The criterion: the grant is no wider than reading the workspace, plus
    /// the one program it has to execute.
    #[tokio::test]
    async fn the_grant_reads_the_workspace_and_nothing_else() {
        let checker = SandboxedCompile::declaring(
            Scripted::new(version(), Ok(outcome(Some(0), "", ""))),
            config(),
            "cargo 1.85.0",
        );
        let grant = checker.grants();

        assert!(grant.iter().all(|a| a.action != "write"), "{grant:?}");
        assert!(grant.iter().all(|a| a.domain != "net"), "{grant:?}");
        assert!(grant.iter().all(|a| a.domain != "secret"), "{grant:?}");
        assert!(
            grant
                .iter()
                .filter(|a| a.domain == "fs")
                .all(|a| a.resource.starts_with("/work/repo/")),
            "{grant:?}"
        );
        assert!(
            grant
                .iter()
                .any(|a| a.domain == "proc" && a.resource == "cargo")
        );
    }

    /// And the trait enforces it: a checker declaring more never runs.
    #[tokio::test]
    async fn the_grant_is_within_what_a_checker_may_hold() {
        use boundgraph_grant::{Tri, set_leq};
        assert_eq!(
            set_leq(&config().grant(), &crate::checker_ceiling()),
            Tri::Yes
        );
    }

    #[tokio::test]
    async fn tsc_is_told_not_to_emit_because_a_checker_may_not_write() {
        assert!(
            CompileConfig::tsc("/w")
                .args
                .iter()
                .any(|a| a == "--noEmit")
        );
    }

    // ── output handling ─────────────────────────────────────────────────────

    #[tokio::test]
    async fn a_huge_diagnostic_is_cut_from_the_front_where_the_real_error_is() {
        let noise = format!(
            "error[E0001]: the first and only real problem\n{}",
            "error: knock-on failure\n".repeat(5_000)
        );
        let verdict = verdict_for(Ok(outcome(Some(101), "", &noise))).await;
        let reason = verdict.reason().unwrap();

        assert!(reason.contains("E0001"), "the cause must survive");
        assert!(reason.contains("truncated"), "and say it was cut");
        assert!(reason.chars().count() < MAX_REASON + 500);
    }

    #[test]
    fn head_keeps_the_start_and_says_when_it_cut() {
        let text = "first\nmiddle\nlast";
        assert!(head(text, 6).starts_with("first"));
        assert!(head(text, 6).contains("truncated"));

        // Short input is untouched.
        assert_eq!(head(text, 100), text);
    }

    #[test]
    fn truncating_does_not_cut_a_character_in_half() {
        let text = "é".repeat(100);
        assert!(!head(&text, 10).contains('\u{fffd}'));
    }

    // ── determinism ─────────────────────────────────────────────────────────

    #[tokio::test]
    async fn the_same_build_result_always_gives_the_same_evidence() {
        let sandbox = Scripted::new(version(), Ok(outcome(Some(0), "", "")));
        let checker = SandboxedCompile::probe(sandbox, config()).await.unwrap();
        let (order, k, key) = (order(), condensate(), key());

        let first = checker.check(&order, &k, &key).await.unwrap();
        for _ in 0..4 {
            assert_eq!(checker.check(&order, &k, &key).await.unwrap(), first);
        }
    }
}