rto_exec/

lib.rs

//! The analyzer execution seam: one contract, interchangeable backends.
//!
//! Running an external analyzer (`cargo-audit`, `semgrep`, successors) can happen
//! in CI, on a developer's machine, or — later — locally inside a sandbox. This
//! crate exists so those stop being competing architectures: every backend
//! implements one [`AnalyzerRunner`] trait, takes one [`AnalysisRequest`], and
//! returns one [`AnalysisResponse`] of normalized findings plus run evidence. A
//! caller never learns which backend produced a result, so adding the sandboxed
//! and subprocess backends later changes no call site.
//!
//! Today there is exactly one implementation, [`IngestRunner`], which consumes a
//! normalized report produced elsewhere. It is the zero-install default, not a
//! fallback: it needs no container runtime and adds no isolation surface, and
//! what it produces is byte-for-byte the shape a sandboxed run will produce.
//!
//! # What this crate does not do
//!
//! It does not *always* produce something to store, either. [`lint`] runs a
//! linter and returns a report the caller prints: no [`AnalysisRun`], no layer,
//! no store. A lint name is a symbol in a compiler rather than an assigned
//! identifier, so it is an opinion about the code as it stands today rather than
//! a durable fact about the repository (ADR-0020 v1.1) — and everything below
//! about persistence simply does not apply to it.
//!
//! [`AnalysisRun`]: rto_graph::AnalysisRun
//! [`lint`]: crate::lint
//!
//! It does not decide how results are *stored*. Persistence lives in `rto-graph`,
//! which files findings in their own tables — never `nodes`/`edges`, never a
//! provenance class, never in the exported graph artifact (ADR-0012). Nothing
//! here can move the published `GraphArtifact` by a byte, and that is checked by
//! test rather than assumed.
//!
//! No analyzer is implemented here, and no sandbox dependency is pulled in; the
//! backends arrive behind their own features (ADR-0014).
//!
//! @rto:0014
//! @rto:0012
//!
//! # Example
//!
//! ```
//! use rto_exec::{AnalysisRequest, AnalyzerRunner, Consent, IngestRunner, Worktree};
//! use rto_graph::SourceIdentity;
//!
//! let report = br#"{
//!   "schema": "roteiro.findings/v1",
//!   "analyzer": "cargo-audit",
//!   "analyzer_version": "0.21.0",
//!   "started_at": "2026-08-15T09:00:00Z",
//!   "ended_at": "2026-08-15T09:00:04Z",
//!   "exit_status": 1,
//!   "findings": [{
//!     "identity": ["RUSTSEC-2024-0001", "openssl", "0.10.5", "lock123"],
//!     "rule": "RUSTSEC-2024-0001",
//!     "severity": "high",
//!     "title": "openssl is vulnerable",
//!     "message": "upgrade to 0.10.66"
//!   }]
//! }"#;
//!
//! let request = AnalysisRequest {
//!     analyzer: "cargo-audit".to_owned(),
//!     worktree: Worktree::read_only("/repo".as_ref()).expect("worktree"),
//!     network: rto_graph::NetworkPolicy::Deny,
//!     consent: Consent::Granted,
//!     source: SourceIdentity::default(),
//! };
//! let response = IngestRunner::new(report.to_vec()).run(&request).expect("ingest");
//! assert_eq!(response.findings.len(), 1);
//! assert_eq!(response.run.isolation, rto_graph::Isolation::Ingested);
//! ```

pub mod adapter;
/// Where the pinned-asset cache lives, and the precedence that decides it.
///
/// Its source carries no `//!` header because `build.rs` pulls the same file in
/// with `include!`, where an inner doc comment is a syntax error — so the module
/// documentation lives here instead. `build.rs` needs it to find the sandbox
/// runtime `roteiro security prefetch` installed, which is the same cache
/// [`asset_paths::asset_root`] names; read the file's own comments for why that
/// is shared rather than copied.
pub mod asset_paths;
// Asset provisioning is **always compiled**, behind no feature at all.
//
// It used to be `cfg(any(exec-subprocess, exec-boxlite))`, on the reading that
// provisioning belongs to whichever backend consumes the assets. That was the
// wrong shape and this module half-said so already: it is shared between the
// backends and owned by neither, and the note on `SANDBOX_RUNTIME_NOTICE` below
// records that an `exec-subprocess`-only build provisions *for a later
// `exec-boxlite` build* — provisioning already served a backend that was not
// compiled in.
//
// The bootstrap argument settles it. `AGENTS.md` tells a contributor to run
// `roteiro security prefetch --allow-download` *before* building
// `--features exec-boxlite`, because that build script requires the verified
// archive at compile time. If prefetch lived behind an execution feature, you
// would need a build with a *different* execution backend compiled in before you
// could provision the one you actually wanted. That is circular.
//
// Nothing here executes anything: it downloads, digests, pins and reports. Every
// `Command::new` in this crate is in `subprocess.rs` or `boxlite.rs`, and both
// stay behind their features. Provisioning is not execution.
pub mod assets;
#[cfg(feature = "exec-boxlite")]
pub mod boxlite;
/// What an analyzer's environment is — for **both** backends, in one place.
///
/// Private because it is a seam between this crate's backends rather than a
/// contract with a caller. It exists as its own module because it used to exist
/// as two: a `ChildEnv` in [`subprocess`] and a hand-rolled list in [`boxlite`],
/// which is how `CARGO_TARGET_DIR` came to be listed as a name to *inherit*
/// under a promise that it was *set*. Read the module for why a guest has no
/// `inherit` half at all.
#[cfg(any(feature = "exec-subprocess", feature = "exec-boxlite"))]
mod child_env;
mod clock;
pub mod crossref;
/// Emitting a `file://` URL for a local path, and reading one back.
///
/// Its source carries no `//!` header because `build.rs` pulls the same file in
/// with `include!`, where an inner doc comment is a syntax error — so the module
/// documentation lives here instead. `build.rs` is this crate's only emitter: it
/// prints the `BOXLITE_RUNTIME_URL=` recipe an operator pastes, and parses that
/// variable back when it is set. What reads the URL in between is `boxlite`'s
/// own `curl`, which percent-decodes and rejects an unencoded space outright —
/// read the file's own comments for the measurements, and for why the encoder
/// and the decoder have to be one file rather than two.
pub mod file_url;
/// How a refusal is written, so that a way forward stays one.
///
/// Ungated, like [`lint_grant`], and for the same kind of reason: what a refusal
/// owes its reader is not a property of which backends were compiled in. Read
/// the module for the failure it makes unrepresentable — three of this crate's
/// refusals leaked source indentation into shipped output at once, which says
/// the way they were written invited it.
pub mod guidance;
/// Whether an image reference is pinned by a digest — the one place that decides.
///
/// Ungated, like [`guidance`], and for a reason of the same shape: the rule is
/// about a string somebody wrote in a config file, not about which backends were
/// compiled in. `roteiro config` reports an unpinned reference in a build with no
/// sandbox at all, and a second copy of the check written for that purpose is how
/// one of the two ends up laxer than the other.
pub mod image_ref;
mod ingest;
/// Running a linter and **reporting** it, with no store anywhere in the path.
///
/// The other half of this crate produces artifacts; this module deliberately
/// does not (ADR-0020 v1.1). It has no [`AnalyzerRunner`] implementation, takes
/// no [`Consent`], and cannot reach [`rto_graph::Store`] — read its own
/// documentation for why a lint is not a finding, and why relaxing
/// [`check_request`] to fit a builder through the reader-class preflight is the
/// conversion ADR-0014 warns against rather than a refactor.
#[cfg(feature = "exec-subprocess")]
pub mod lint;
/// ADR-0020 §6's grant: may a linter run on **this host**?
///
/// Ungated, unlike [`lint`] itself. A policy that existed only where the
/// capability does would be the conversion ADR-0014 warns about, so the answer
/// is the same in a build that cannot run a linter as in one that can — see the
/// module's own documentation.
pub mod lint_grant;
/// ADR-0020 conditions 1-2: the **sandboxed builder** — `roteiro lint`'s default.
///
/// The boundary half of [`lint`]. It adds one writable mount to what
/// [`boxlite`] already does and removes nothing: the worktree stays read-only,
/// [`check_request`]'s preflight is untouched, and the package cache is a
/// read-only mount of this machine's own rather than a vendored copy. Read its
/// documentation for why the image is supplied rather than pinned here, and why
/// a `$CARGO_HOME` root is not what gets mounted.
///
/// Gated on **both** backends. The boundary does not imply the escape hatch —
/// `exec-boxlite` still does not enable `exec-subprocess`, and enabling one must
/// never switch on the other. This module needs both because it shares
/// [`lint`]'s report shape and its one host-side `cargo locate-project`, which
/// is how it learns what to mount.
#[cfg(all(feature = "exec-boxlite", feature = "exec-subprocess"))]
pub mod lint_sandbox;
mod runner;
/// The per-file digests of the extracted sandbox runtime — **generated**.
///
/// Derived from the archives in [`runtime_pins`] by
/// `scripts/derive-runtime-file-pins.py`, and verified by `build.rs` against
/// what `boxlite` actually extracted, since those files rather than the archive
/// are what `include_bytes!` puts in the binary. Same `include!` arrangement,
/// and so the same standalone constraint; its module documentation lives here
/// for the same reason [`runtime_pins`]'s does.
pub mod runtime_file_pins;
/// The pinned sandbox-runtime archives, and the host-platform selection.
///
/// Its source carries no `//!` header because `build.rs` pulls the same file in
/// with `include!`, where an inner doc comment is a syntax error — so the module
/// documentation lives here instead. Read the file's own comments for what is
/// pinned and why it has to be.
pub mod runtime_pins;
/// The **sandbox image store**: what it is holding, and dropping it safely.
///
/// Ungated, like [`assets`], and the argument is the same one that moved
/// provisioning off the backend features: reclaiming the bytes a previous build
/// cached must not require rebuilding with the backend that cached them. Nothing
/// here executes anything — it reads an index, measures files, and removes what
/// a pinned digest re-obtains (ADR-0014 v1.6).
pub mod sandbox_store;
pub mod snippet;
#[cfg(feature = "exec-subprocess")]
pub mod subprocess;
/// The **read-only documents** `security list` / `security status` return over a
/// model-facing tool surface.
///
/// Ungated, like [`guidance`] and [`lint_grant`], and for a related reason: what
/// a read owes its reader is not a property of which backends were compiled in.
/// It is also the one place either document is built — the CLI's `security
/// status` shares its coverage matrix and staleness rows from here, so
/// `possibly_stale` and `ready` are one computation rather than three. Read the
/// module for the two hazards it exists to remove: an empty listing that reads as
/// a clean one, and a status blob whose two halves have different scopes.
pub mod tool_security;

pub use adapter::{
    ADAPTERS, Adapter, AssetPaths, Invocation, LINT_ANALYZERS, NO_SNIPPET, NativeContext,
    UNKNOWN_VERSION, adapter_for, known_analyzers, snippet_hash, snippet_hash_at,
};
// The linter's adapter is re-exported like any other, and — unlike any other —
// is **not** in [`ADAPTERS`], so `ingest` cannot resolve it and nothing can file
// its output as a layer. See [`adapter::clippy`].
pub use adapter::clippy::{Clippy, FeatureSet};
pub use assets::{
    ASSETS, AssetKind, AssetSource, AssetSpec, AssetStatus, DownloadFile, Fetcher, InstalledAsset,
    MissingAsset, SANDBOX, asset, asset_path, asset_root, assets_for, provision, provision_with,
    resolve, status,
};
#[cfg(feature = "exec-boxlite")]
pub use boxlite::{BoxliteRunner, SandboxError, SandboxProbe, sandbox_probe};
pub use clock::{age_in_days, rfc3339_from_unix, rfc3339_utc, unix_from_rfc3339};
pub use crossref::{
    Correspondence, Report, across_analyzers as cross_reference_across_analyzers, cross_reference,
};
pub use guidance::{Guidance, Line as GuidanceLine};
pub use image_ref::{NotPinned, PinDefect, pinned_digest as image_pinned_digest};
pub use ingest::{
    IngestRunner, MAX_REPORT_FINDINGS, NormalizedReport, REPORT_SCHEMA, ReportFinding,
    normalize_native,
};
#[cfg(feature = "exec-subprocess")]
pub use lint::{LintError, LintOutcome, Toolchain, invocation as lint_invocation, run as run_lint};
// ADR-0020 §6's grant. Re-exported under `lint_`-prefixed names because the
// concepts have twins in `rto-remote` (ADR-0019 §3) and a reader who meets
// `ConfigGrant` in the binary must be able to see which of the two it is.
pub use lint_grant::{
    Backend as LintBackend, ConfigGrant as LintConfigGrant, Decision as LintDecision,
    Reason as LintReason, Requested as LintRequested, decide as decide_lint_host,
};
#[cfg(all(feature = "exec-boxlite", feature = "exec-subprocess"))]
pub use lint_sandbox::BuilderError as LintBuilderError;
pub use runner::{
    AnalysisRequest, AnalysisResponse, AnalyzerRunner, Consent, ExecError, Worktree,
    check_reported_path, check_request, worktree_id,
};
pub use runtime_file_pins::{
    PinnedFile, PinnedRuntimeFiles, RUNTIME_FILES, RUNTIME_FILES_VERSION, runtime_files_for,
};
pub use runtime_pins::{
    PinnedArchive, RUNTIME_ARCHIVES, RUNTIME_ASSET, RUNTIME_FILE, RUNTIME_VERSION, archive_for,
    runtime_target,
};
pub use sandbox_store::{
    Attribution, CachedImage, ClearReport, ImageBytes, Objects, Preserved, RemovedImage,
    SANDBOX_CLEAR_SCHEMA, SANDBOX_STATUS_SCHEMA, SANDBOX_STORE_DIR, SandboxStatus, Scope,
    StoreError, Unattributed, VerifiedImage, clear as sandbox_clear, plan as sandbox_plan,
    status as sandbox_status, store_root as sandbox_store_root,
};
pub use snippet::{NoSnippets, SnippetSource, WorktreeSnippets};
#[cfg(feature = "exec-subprocess")]
pub use subprocess::{SubprocessError, SubprocessRunner};
pub use tool_security::{
    AnalyzerCoverage, Coverage, CrossReference, CrossReferenceReport, LayerStaleness, MachineScope,
    Readiness, RepositoryScope, SecurityListReport, TOOL_SECURITY_LIST_SCHEMA,
    TOOL_SECURITY_STATUS_SCHEMA, ToolFindingsLayer, ToolSecurityList, ToolSecurityStatus,
    coverage_matrix, coverage_matrix_with, layer_staleness, security_list, security_status,
};

/// The licence notice for the third-party binaries an `exec-boxlite` build
/// embeds, compiled in so it cannot be separated from what it describes.
///
/// `roteiro security prefetch` prints it before installing the sandbox runtime,
/// which is the same disclose-then-consent shape `roteiro model pull` uses. It
/// is compiled into every build, because every build can provision the runtime —
/// including one with no execution backend at all, which prefetches it for a
/// later `exec-boxlite` build — so the obligations travel with the artifact
/// rather than living only in the repository.
pub const SANDBOX_RUNTIME_NOTICE: &str = include_str!("../NOTICE-boxlite-runtime.md");

/// Lowercase hex SHA-256 of `bytes`.
///
/// Used for the report digest that ties an `AnalysisRun` to the exact bytes it
/// was derived from, and for deriving an opaque worktree id from a path.
#[must_use]
pub fn sha256_hex(bytes: &[u8]) -> String {
    use sha2::{Digest, Sha256};
    let digest = Sha256::digest(bytes);
    let mut out = String::with_capacity(64);
    for byte in digest {
        use std::fmt::Write as _;
        let _ = write!(out, "{byte:02x}");
    }
    out
}

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

    #[test]
    fn hashes_the_known_vector() {
        assert_eq!(
            sha256_hex(b"abc"),
            "ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad"
        );
    }
}