Module provenance 

What a run measured about its own checkout when it ended.

A recorder that stamps a report with the tree it sees vouches for a tree it did not see: CI records in a fresh checkout, and a local run may be recorded after its checkout changed. So the run measures and the recorder carries. stamp is the one measurement a runner takes at the end of its run: the commit, the tree through crate::git::working_tree_excluding (the evidence ledger ignored, the run’s own untracked outputs excluded, a tracked change never hidden), the producer, the toolchain, the recorder’s version, the report’s digest, the host and the CI run. The result is an EvidenceProvenance, which evidence record --provenance attaches to that report’s executions.

A stamp measures the checkout when it is taken, after the report was written, and not the tree while the run executed: a run on a dirty tree that is cleaned before the stamp reads clean.

A stamp, taken and read back

use majordomus_cli::evidence::{stamp, EvidenceProducer, EvidenceProvenance, StampRequest, TreeState};
use std::process::Command;

let root = tempfile::tempdir().unwrap();
let git = |args: &[&str]| {
    Command::new("git").arg("-C").arg(root.path()).args(args).output().unwrap()
};
git(&["init", "-q"]);
git(&["config", "user.email", "t@example.com"]);
git(&["config", "user.name", "t"]);
std::fs::write(root.path().join("a.md"), "a").unwrap();
git(&["add", "-A"]);
git(&["commit", "-qm", "init"]);

// the run wrote its report into the checkout: it is one of the run's own outputs
std::fs::write(root.path().join("suite.tsv"), "01_a\tok\t1\tparallel\n").unwrap();
let req = StampRequest {
    producer: Some(EvidenceProducer::Suite),
    report: Some(root.path().join("suite.tsv")),
    exclude: vec![],
    run: None,
};
let measured = stamp(root.path(), &req).unwrap();
assert_eq!(measured.working_tree, TreeState::Clean);
assert_eq!(measured.excluded, ["suite.tsv"]);
assert_eq!(measured.report.as_ref().unwrap().path, "suite.tsv");

let out = tempfile::tempdir().unwrap();
let file = out.path().join("p.json");
std::fs::write(&file, serde_json::to_string(&measured).unwrap()).unwrap();
assert_eq!(EvidenceProvenance::read(&file).unwrap(), measured);

Structs

EvidenceHost

The machine the run measured on.

EvidenceProvenance

What a run measured about its own checkout when it ended.

EvidenceReportArtifact

The report a measurement belongs to: where it was and what its bytes were.

EvidenceToolchain

The toolchain the run’s producer used.

StampRequest

What to measure: which producer’s run, its report, its own untracked outputs, its CI run.

Enums

EvidenceToolchainSource

How a toolchain’s version was known: asked of the executable, or read from the pin the repository declares.

Functions

stamp

Measure the checkout at root as the run req describes left it.