From f9c841e8151cc174079d3ed749655430d5e93ac1 Mon Sep 17 00:00:00 2001 From: VirtualMachinist Date: Thu, 19 Nov 2026 20:53:47 -0500 Subject: [PATCH 1/4] Mutation base: --base, gates.base_ref, then origin/HEAD The mutation diff no longer assumes origin/main. The base is the --base flag, else gates.base_ref, else the remote default branch (origin/HEAD). A named base that is not a commit fails the layer and names the ref. With no base the layer fails under CI, naming fetch-depth: 0 and --base, and is vacuous otherwise, listing each source tried. The report names the base and its source on the mutation row. Both workflows pass --base. The schema, its copy, PROTOCOL.md 8.3 and the init goldens follow. The laws_gate fixtures leave origin/HEAD as a clone does and run without CI set. Co-Authored-By: Claude Sonnet 5.5 --- .github/workflows/rust-tops.yml | 5 +- PROTOCOL.md | 12 +- config/drop-in/rust-tops.yml | 7 +- crates/cargo-tops/src/config.rs | 4 + crates/cargo-tops/src/gate/execute.rs | 116 +++- crates/cargo-tops/src/gate/mod.rs | 31 +- crates/cargo-tops/src/gate/plan.rs | 34 +- crates/cargo-tops/src/gate/report.rs | 38 ++ crates/cargo-tops/src/main.rs | 13 +- crates/cargo-tops/src/steps.rs | 254 +++++++- .../templates/drop-in/rust-tops.yml | 7 +- .../templates/rust-tops.schema.json | 5 + crates/cargo-tops/tests/gate_base.rs | 613 ++++++++++++++++++ .../.github/workflows/rust-tops.yml | 7 +- .../.github/workflows/rust-tops.yml | 7 +- .../.github/workflows/rust-tops.yml | 7 +- .../.github/workflows/rust-tops.yml | 7 +- .../.github/workflows/rust-tops.yml | 7 +- .../.github/workflows/rust-tops.yml | 7 +- .../.github/workflows/rust-tops.yml | 7 +- .../.github/workflows/rust-tops.yml | 7 +- crates/cargo-tops/tests/laws_gate.rs | 23 +- schema/rust-tops.schema.json | 5 + 23 files changed, 1111 insertions(+), 112 deletions(-) create mode 100644 crates/cargo-tops/tests/gate_base.rs diff --git a/.github/workflows/rust-tops.yml b/.github/workflows/rust-tops.yml index f1a06a5..c3ba44d 100644 --- a/.github/workflows/rust-tops.yml +++ b/.github/workflows/rust-tops.yml @@ -351,7 +351,8 @@ jobs: # Runs this repository's own gate: every enabled layer at tier <= 1 in # rust-tops.yaml, laws included. Not a --dry-run. fetch-depth: 0 because - # the mutation layer diffs against origin/main. cargo-tops is built from + # the mutation layer diffs against the base branch, which --base names + # (a gate with no base fails under CI). cargo-tops is built from # this checkout, so the gate under test is the one on this commit. Bend is # not preinstalled: the laws layer fetches it by laws/bend.lock, as it # does on an adopter. @@ -384,7 +385,7 @@ jobs: with: tool: cargo-mutants@27.1.0 - run: cargo install --path crates/cargo-tops --locked - - run: cargo tops gate --max-tier 1 + - run: cargo tops gate --max-tier 1 --base "origin/${{ github.base_ref || github.event.repository.default_branch }}" # mutants-diff: class overlay. Diff-scoped; no --baseline skip; default # features usually need no FFI sysdeps. Do not mark required until one diff --git a/PROTOCOL.md b/PROTOCOL.md index e4842c5..b2f3b70 100644 --- a/PROTOCOL.md +++ b/PROTOCOL.md @@ -479,10 +479,20 @@ Coverage says a line ran. A survivor says no test *cared*. On every PR that touches `src/`: ```bash -git diff origin/main...HEAD --unified=0 > /tmp/pr.diff +git diff "$(git merge-base "$BASE" HEAD)" HEAD --unified=0 > /tmp/pr.diff cargo mutants --in-diff /tmp/pr.diff -j 2 -- --skip ignored ``` +`$BASE` is the PR's base ref, such as `origin/main`. `cargo tops gate` takes it, in this order: + +1. `--base `. +2. `gates.base_ref` in `rust-tops.yaml`. +3. `origin/HEAD`, the remote's default branch. + +The first source that is set wins. A ref that is named by the flag or the key and does not name a commit fails the layer, and the failure names the ref. The diff is from `git merge-base HEAD` to `HEAD`. The report names the base and its source (`flag`, `key` or `origin/HEAD`). + +When no source gives a base, the layer is `fail` if the `CI` environment variable is set and is not empty, `false` or `0`. The detail names `fetch-depth: 0` and `--base`: a checkout that never fetched the base must not read as a clean diff. When `CI` is unset, `false` or `0`, the layer is `vacuous`, and the detail lists each source tried. CI workflows pass `--base "origin/${{ github.base_ref || github.event.repository.default_branch }}"` from a checkout with `fetch-depth: 0`, because `actions/checkout` may not create `origin/HEAD`. + Pass criteria: - baseline green diff --git a/config/drop-in/rust-tops.yml b/config/drop-in/rust-tops.yml index 2fa8292..0088f14 100644 --- a/config/drop-in/rust-tops.yml +++ b/config/drop-in/rust-tops.yml @@ -174,8 +174,9 @@ jobs: # Runs the gate rust-tops.yaml declares: every enabled layer at tier <= 1, # laws included when they are on. Not a --dry-run. fetch-depth: 0 because - # the mutation layer diffs against origin/main, which a depth-1 checkout - # does not have. cargo-tops builds with Rust 1.99.1 (its rust-version), + # the mutation layer diffs against the base branch, which a depth-1 checkout + # does not have. --base names that branch: actions/checkout may not create + # origin/HEAD, and a gate with no base fails under CI. cargo-tops builds with Rust 1.99.1 (its rust-version), # which can be newer than crate.msrv; the layers run on the pinned channel. # The cargo-tops version is pinned; bump it when the kit publishes. # Since 0.4.0 the gate enforces the coverage floors and the CRAP threshold @@ -220,7 +221,7 @@ jobs: with: tool: cargo-mutants@27.1.0 fallback: none - - run: cargo tops gate --max-tier 1 + - run: cargo tops gate --max-tier 1 --base "origin/${{ github.base_ref || github.event.repository.default_branch }}" # mutants-diff: class overlay. Diff-scoped; no --baseline skip; default # features usually need no FFI sysdeps. Do not mark required until one diff --git a/crates/cargo-tops/src/config.rs b/crates/cargo-tops/src/config.rs index e5114ac..ad2bafc 100644 --- a/crates/cargo-tops/src/config.rs +++ b/crates/cargo-tops/src/config.rs @@ -40,6 +40,10 @@ pub(crate) struct Gates { pub coverage: CoverageGate, pub crap: CrapGate, pub mutation: MutationGate, + /// The ref the mutation diff starts from, when `--base` is not given. + /// Absent means the remote's default branch (`origin/HEAD`). + #[serde(skip_serializing_if = "Option::is_none")] + pub base_ref: Option, } #[derive(Debug, Deserialize, Serialize, PartialEq)] diff --git a/crates/cargo-tops/src/gate/execute.rs b/crates/cargo-tops/src/gate/execute.rs index 0bf8dbd..d4cc6c3 100644 --- a/crates/cargo-tops/src/gate/execute.rs +++ b/crates/cargo-tops/src/gate/execute.rs @@ -11,7 +11,7 @@ use super::plan::{GatePlan, Unit, What, CRAP_VERSION}; use super::{Fault, Mode}; use crate::config::Layer; use crate::facts::{Outcome, Run}; -use crate::steps::{self, Kind, MutationPlan, Step}; +use crate::steps::{self, Base, Kind, MutationPlan, Step}; use crate::{laws, TOOL_LOCK}; /// What the laws layer needs before any work starts. @@ -360,8 +360,11 @@ pub(crate) fn run_pinned_crap(dir: &Path, layer: &str, chain: &[Step], pin: &str } /// `cargo-mutants` is looked up before the diff, so an empty diff cannot -/// hide a missing tool. A failed diff is `Failed`; nothing waives it. An -/// empty one is `Vacuous` and `cargo mutants` does not run. +/// hide a missing tool. A base that was named and is not a commit fails the +/// layer, naming it. A failed diff is `Failed`; nothing waives it. An empty +/// one is `Vacuous` and `cargo mutants` does not run, except that no base at +/// all is `Failed` when `CI` is set: a base that was never fetched must not +/// read as a clean diff. pub(crate) fn run_mutation(dir: &Path, layer: &str, plan: &MutationPlan) -> Result { if let Err(missing) = steps::check_tool(&plan.mutants.argv) { println!("{missing}"); @@ -372,43 +375,58 @@ pub(crate) fn run_mutation(dir: &Path, layer: &str, plan: &MutationPlan) -> Resu )); } let mut ran = vec![plan.diff.display()]; + if let Base::Unresolved { source, name } = &plan.base { + println!( + "Failed: {} names `{name}`, which is not a commit; the mutation diff cannot start there", + source.label() + ); + return Ok(finish(layer, &ran, Outcome::Failed)); + } let diff_ok = run_step(dir, &plan.diff)? == Outcome::Passed; let diff = steps::judge_diff(diff_ok, &plan.diff_path); let Some(mutants) = plan.after_diff(diff) else { - if diff == Outcome::Vacuous && has_origin_main(dir) { - println!( - "Vacuous: the diff from `git merge-base origin/main HEAD` is empty; \ - cargo mutants did not run and no law counts this layer" - ); - } else if diff == Outcome::Vacuous { - println!( - "Vacuous: no origin/main; the mutation diff is empty; \ - cargo mutants did not run and no law counts this layer" - ); - } else { - println!("Failed: the mutation diff did not succeed; a failed diff is never waived"); - } - return Ok(finish(layer, &ran, diff)); + let ci = std::env::var("CI").ok(); + let outcome = stopped_diff(&plan.base, diff, ci.as_deref()); + return Ok(finish(layer, &ran, outcome)); }; ran.push(mutants.display()); let outcome = run_step(dir, mutants)?; Ok(finish(layer, &ran, outcome)) } -/// Whether `refs/remotes/origin/main` exists, for the Vacuous wording only. -pub(crate) fn has_origin_main(dir: &Path) -> bool { - Command::new("git") - .args([ - "rev-parse", - "--verify", - "--quiet", - "refs/remotes/origin/main", - ]) - .current_dir(dir) - .stdout(std::process::Stdio::null()) - .stderr(std::process::Stdio::null()) - .status() - .is_ok_and(|status| status.success()) +/// Say why the diff stopped the layer, and give its outcome: a failed diff +/// stays failed, no base under CI (the value of `CI`) fails, and any other +/// empty diff is vacuous. +fn stopped_diff(base: &Base, diff: Outcome, ci: Option<&str>) -> Outcome { + match (diff, base) { + (Outcome::Vacuous, Base::Missing { tried }) => { + let sources = tried.join("; "); + if steps::ci_active(ci) { + println!( + "Failed: no mutation base ({sources}); under CI that is never a clean diff. \ + Check out with `fetch-depth: 0` and pass `--base `, or set `gates.base_ref`" + ); + Outcome::Failed + } else { + println!( + "Vacuous: no mutation base ({sources}); the mutation diff is empty; \ + cargo mutants did not run and no law counts this layer" + ); + Outcome::Vacuous + } + } + (Outcome::Vacuous, Base::Found { name, .. } | Base::Unresolved { name, .. }) => { + println!( + "Vacuous: the diff from `git merge-base {name} HEAD` is empty; \ + cargo mutants did not run and no law counts this layer" + ); + Outcome::Vacuous + } + (other, _) => { + println!("Failed: the mutation diff did not succeed; a failed diff is never waived"); + other + } + } } pub(crate) fn run_step(dir: &Path, step: &Step) -> Result { @@ -447,9 +465,9 @@ pub(crate) fn run_step(dir: &Path, step: &Step) -> Result { #[cfg(test)] mod tests { - use super::{run_step, version_ask, Executed, Timing}; + use super::{run_step, stopped_diff, version_ask, Executed, Timing}; use crate::facts::Outcome; - use crate::steps::Step; + use crate::steps::{Base, BaseSource, Step}; use std::fs; use std::path::Path; use std::time::SystemTime; @@ -517,4 +535,36 @@ mod tests { assert!(format!("{err:#}").contains("spawn"), "{err:#}"); fs::remove_dir_all(&dir).ok(); } + + #[test] + fn an_empty_diff_is_vacuous_unless_no_base_was_found_under_ci() { + let missing = Base::Missing { + tried: vec!["origin/HEAD: not set".to_string()], + }; + let found = Base::Found { + source: BaseSource::Flag, + name: "origin/main".to_string(), + }; + let vacuous = Outcome::Vacuous; + assert_eq!(stopped_diff(&missing, vacuous, None), Outcome::Vacuous); + assert_eq!( + stopped_diff(&missing, vacuous, Some("false")), + Outcome::Vacuous + ); + assert_eq!( + stopped_diff(&missing, vacuous, Some("true")), + Outcome::Failed + ); + // A named base that gave an empty diff is vacuous even under CI. + assert_eq!( + stopped_diff(&found, vacuous, Some("true")), + Outcome::Vacuous + ); + // A failed diff stays failed, whatever the base and CI. + for base in [&missing, &found] { + for ci in [None, Some("true")] { + assert_eq!(stopped_diff(base, Outcome::Failed, ci), Outcome::Failed); + } + } + } } diff --git a/crates/cargo-tops/src/gate/mod.rs b/crates/cargo-tops/src/gate/mod.rs index 079d4d2..6321ce5 100644 --- a/crates/cargo-tops/src/gate/mod.rs +++ b/crates/cargo-tops/src/gate/mod.rs @@ -82,10 +82,16 @@ impl Fault { } /// Run the gate for `cfg` under `dir`: always writes `report.json`. -pub(crate) fn run(dir: &Path, cfg: &TopsConfig, opts: Options) -> ExitCode { +/// `base_flag` is `--base`, the first source of the mutation base. +pub(crate) fn run( + dir: &Path, + cfg: &TopsConfig, + opts: Options, + base_flag: Option<&str>, +) -> ExitCode { // A gate resolves `cargo metadata` afresh, once per project. laws::begin_gate(); - let plan = match plan::build(dir, cfg, opts.max_tier) { + let plan = match plan::build(dir, cfg, opts.max_tier, base_flag) { Ok(plan) => plan, Err(fault) => return report::fault(dir, Some(cfg), opts, None, &fault), }; @@ -123,7 +129,7 @@ mod tests { use super::judge::{command_count, ran_commands}; use super::plan::{plan_for, Plan, TestCommands}; use crate::facts::{Outcome, Run}; - use crate::steps::{self, Kind, Step}; + use crate::steps::{self, Base, Kind, Step}; use crate::{config, credit}; use std::fs; use std::path::Path; @@ -136,7 +142,7 @@ mod tests { } fn chains(id: &str) -> Vec> { - match plan_for(&layer(id), Path::new("/r")) { + match plan_for(&layer(id), Path::new("/r"), &Base::unused()) { Some(Plan::Chains(chains)) => chains, _ => panic!("{id} has no chains"), } @@ -152,7 +158,7 @@ mod tests { #[test] fn the_g0_strings_name_the_tool_they_run() { let coverage = "mkdir -p target/coverage && cargo llvm-cov nextest --workspace --all-features --profile ci --lcov --output-path target/coverage/lcov.info && test -s target/coverage/lcov.info"; - let mutation = "sh -c 'git diff origin/main...HEAD --unified=0 > /tmp/rust-tops.diff; cargo mutants --in-diff /tmp/rust-tops.diff -j 2'"; + let mutation = "sh -c 'git diff base...HEAD --unified=0 > /tmp/rust-tops.diff; cargo mutants --in-diff /tmp/rust-tops.diff -j 2'"; assert_eq!( steps::tool_binary(&[coverage.to_string()]).as_deref(), Some("cargo-llvm-cov") @@ -391,16 +397,20 @@ mod tests { #[test] fn the_mutation_diff_uses_merge_base_and_the_report_dir() { let report = Path::new("/work/target/rust-tops"); - let Some(Plan::Mutation(plan)) = plan_for(&layer("mutation"), report) else { + let base = Base::Found { + source: steps::BaseSource::Flag, + name: "origin/trunk".to_string(), + }; + let Some(Plan::Mutation(plan)) = plan_for(&layer("mutation"), report, &base) else { panic!("mutation has no plan"); }; assert_eq!(plan.diff_path, report.join("rust-tops.diff")); let script = plan.diff.argv.join(" "); assert!( - script.contains("git merge-base origin/main HEAD"), + script.contains("git merge-base 'origin/trunk' HEAD"), "{script}" ); - assert!(script.contains("refs/remotes/origin/main"), "{script}"); + assert!(!script.contains("origin/main"), "{script}"); assert!(script.contains("&& git diff"), "{script}"); assert!(!script.contains("mutants"), "{script}"); assert!(!script.contains("/tmp"), "{script}"); @@ -446,7 +456,10 @@ mod tests { "density-audit", "laws", ] { - assert!(plan_for(&layer(id), Path::new("/r")).is_none(), "{id}"); + assert!( + plan_for(&layer(id), Path::new("/r"), &Base::unused()).is_none(), + "{id}" + ); } } diff --git a/crates/cargo-tops/src/gate/plan.rs b/crates/cargo-tops/src/gate/plan.rs index 0c26b6a..8153f99 100644 --- a/crates/cargo-tops/src/gate/plan.rs +++ b/crates/cargo-tops/src/gate/plan.rs @@ -10,7 +10,7 @@ use crate::facts::{Outcome, Run}; use crate::{credit, laws, steps, TOOL_LOCK}; use anyhow::{Context, Result}; use std::fs; -use steps::{Kind, MutationPlan, Step}; +use steps::{Base, Kind, MutationPlan, Step}; /// The command whose first line must name the pinned cargo-crap. pub(crate) const CRAP_VERSION: [&str; 3] = ["cargo", "crap", "--version"]; @@ -40,7 +40,7 @@ impl TestCommands { enabled .iter() .find(|layer| layer.id == id) - .and_then(|layer| plan_for(layer, report)) + .and_then(|layer| tool_plan(layer, report)) .and_then(|plan| match plan { Plan::Chains(chains) => chains .into_iter() @@ -214,11 +214,20 @@ fn crap_steps(report: &Path) -> Vec { } /// `report` is [`laws::artifact_dir`]: the coverage LCOV, the CRAP report -/// and the mutation diff are written there. -pub(crate) fn plan_for(layer: &config::Layer, report: &Path) -> Option { +/// and the mutation diff are written there. `base` is where the mutation +/// diff starts. +pub(crate) fn plan_for(layer: &config::Layer, report: &Path, base: &Base) -> Option { + if layer.id == "mutation" { + Some(Plan::Mutation(MutationPlan::new(report, base.clone()))) + } else { + tool_plan(layer, report) + } +} + +/// The plan of every layer but `mutation`, which also needs a base. +fn tool_plan(layer: &config::Layer, report: &Path) -> Option { let id = layer.id.as_str(); match id { - "mutation" => Some(Plan::Mutation(MutationPlan::new(report))), "coverage" => Some(Plan::Chains(vec![steps::coverage_steps(report)])), "crap" => Some(Plan::Chains(vec![crap_steps(report)])), _ => TOOL_LAYERS @@ -326,13 +335,14 @@ fn units_of<'a>( enabled: &[&'a config::Layer], tests: &TestCommands, report: &Path, + base: &Base, ) -> Vec> { enabled .iter() .copied() .filter(|layer| layer.id != "laws") .map(|layer| { - let what = match (tests.shared_from(&layer.id), plan_for(layer, report)) { + let what = match (tests.shared_from(&layer.id), plan_for(layer, report, base)) { (Some(from), _) => What::Shared(from), (None, Some(Plan::Chains(chains))) => What::Chains(chains), (None, Some(Plan::Mutation(plan))) => What::Mutation(plan), @@ -343,13 +353,16 @@ fn units_of<'a>( .collect() } -/// The plan for `cfg` at `max_tier`. A config the gate cannot plan from is +/// The plan for `cfg` at `max_tier`. `base` is the `--base` flag; with a +/// mutation layer in range it and `gates.base_ref` decide where the diff +/// starts. A config the gate cannot plan from is /// a [`Fault::config`]; a project whose Cargo metadata cannot be read, or /// whose report directory cannot be resolved, is a [`Fault::env`]. pub(crate) fn build<'a>( dir: &Path, cfg: &'a TopsConfig, max_tier: u8, + base_flag: Option<&str>, ) -> Result, Fault> { let enabled = in_range(cfg, max_tier); if enabled.is_empty() { @@ -359,6 +372,11 @@ pub(crate) fn build<'a>( } let report = report_dir(dir)?; let tests = TestCommands::new(&enabled, &report); + let base = if enabled.iter().any(|layer| layer.id == "mutation") { + steps::resolve_base(dir, base_flag, cfg.gates.base_ref.as_deref()) + } else { + Base::unused() + }; let crap_pin = if enabled.iter().any(|layer| layer.id == "crap") { tool_pin(dir, "cargo-crap").map_err(Fault::config)? } else { @@ -372,7 +390,7 @@ pub(crate) fn build<'a>( above: ids(cfg, |l| l.enabled && crate::tiers::tier_for(l) > max_tier), // A layer turned off still shows in the run: it is not run, not omitted. disabled: ids(cfg, |l| !l.enabled), - units: units_of(&enabled, &tests, &report), + units: units_of(&enabled, &tests, &report, &base), enabled, report, tests, diff --git a/crates/cargo-tops/src/gate/report.rs b/crates/cargo-tops/src/gate/report.rs index 8611590..9a4a8e7 100644 --- a/crates/cargo-tops/src/gate/report.rs +++ b/crates/cargo-tops/src/gate/report.rs @@ -16,6 +16,7 @@ use super::{Fault, Mode, Options}; use crate::config::TopsConfig; use crate::facts::{Outcome, Run}; use crate::floors::{CoverageNumbers, CrapNumbers}; +use crate::steps::Base; use crate::{laws, PROTOCOL_VERSION}; /// The file name under the gate's report directory. @@ -419,9 +420,46 @@ fn unit_row(parts: &Parts<'_>, id: &str, tier: u8) -> Map { if let Some(numbers) = numbers { entry.insert("judged".into(), numbers); } + if id == "mutation" { + name_the_base(plan, &mut entry); + } entry } +/// The mutation row names the base the diff started from and where it came +/// from (`flag`, `key` or `origin/HEAD`), under `judged.base`. A base that +/// was named and is not a commit, or none at all, also says so in `detail`. +fn name_the_base(plan: &GatePlan<'_>, entry: &mut Map) { + let Some(What::Mutation(mutation)) = plan + .units + .iter() + .find(|unit| unit.layer.id == "mutation") + .map(|unit| &unit.what) + else { + return; + }; + let (base, detail) = match &mutation.base { + Base::Found { source, name } => { + (json!({ "ref": name, "source": source.report_name() }), None) + } + Base::Unresolved { source, name } => ( + json!({ "ref": name, "source": source.report_name(), "resolved": false }), + Some(format!( + "{} names `{name}`, which is not a commit", + source.label() + )), + ), + Base::Missing { tried } => ( + json!({ "ref": null, "source": null, "tried": tried }), + Some(format!("no mutation base: {}", tried.join("; "))), + ), + }; + entry.insert("judged".into(), json!({ "base": base })); + if let Some(detail) = detail { + entry.insert("detail".into(), json!(detail)); + } +} + fn laws_row(parts: &Parts<'_>, tier: u8) -> Map { let argv = vec![vec![ "bend".to_string(), diff --git a/crates/cargo-tops/src/main.rs b/crates/cargo-tops/src/main.rs index 5e261bd..cda1415 100644 --- a/crates/cargo-tops/src/main.rs +++ b/crates/cargo-tops/src/main.rs @@ -103,6 +103,11 @@ Where more than one applies, 2 wins over 3, and 3 over 1.")] /// Print commands without running them #[arg(long)] dry_run: bool, + /// Ref the mutation diff starts from, over `gates.base_ref` and the + /// remote's default branch (`origin/HEAD`). In CI pass + /// `origin/` from a checkout with `fetch-depth: 0` + #[arg(long, value_name = "REF")] + base: Option, }, /// Record the last gate's CRAP report as the baseline the crap ratchet reads CrapBaseline { @@ -159,7 +164,7 @@ fn main() -> ExitCode { } } -/// The argv clap parses. `cargo tops …` execs this binary with argv[1] == +/// The argv clap parses. `cargo tops …` execs this binary with `argv[1]` == /// "tops"; `cargo-tops …` does not. Drop that one word so both forms parse. fn subcommand_argv(mut args: Vec) -> Vec { if args.get(1).and_then(|arg| arg.to_str()) == Some("tops") { @@ -188,12 +193,14 @@ fn run() -> Result { path, max_tier, dry_run, + base, } => Ok(run_gate( &path, gate::Options { max_tier, mode: dry_run.into(), }, + base.as_deref(), )), Commands::CrapBaseline { path } => { let cfg = load_config(&path)?; @@ -209,9 +216,9 @@ fn run() -> Result { /// `cargo tops gate`: a config that does not load, or fails `check`, is exit /// 2 with a report; anything else is the gate's own verdict. -fn run_gate(path: &Path, opts: gate::Options) -> ExitCode { +fn run_gate(path: &Path, opts: gate::Options, base: Option<&str>) -> ExitCode { match load_config(path).and_then(|cfg| check(&cfg).map(|()| cfg)) { - Ok(cfg) => gate::run(path, &cfg, opts), + Ok(cfg) => gate::run(path, &cfg, opts, base), Err(err) => gate::config_error(path, &err, opts), } } diff --git a/crates/cargo-tops/src/steps.rs b/crates/cargo-tops/src/steps.rs index 4dd592a..8f636de 100644 --- a/crates/cargo-tops/src/steps.rs +++ b/crates/cargo-tops/src/steps.rs @@ -17,6 +17,7 @@ use std::fmt; use std::fs; use std::path::{Path, PathBuf}; +use std::process::{Command, Stdio}; const DIFF_NAME: &str = "rust-tops.diff"; @@ -344,11 +345,148 @@ pub(crate) fn judge_diff(command_ok: bool, diff_path: &Path) -> Outcome { } } +/// Where the mutation base came from. +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +pub(crate) enum BaseSource { + /// `--base `. + Flag, + /// `gates.base_ref` in `rust-tops.yaml`. + Key, + /// The remote's default branch, `refs/remotes/origin/HEAD`. + OriginHead, +} + +impl BaseSource { + /// How a message names the source. + pub(crate) fn label(self) -> &'static str { + match self { + Self::Flag => "--base", + Self::Key => "gates.base_ref", + Self::OriginHead => "origin/HEAD", + } + } + + /// How `report.json` names the source. + pub(crate) fn report_name(self) -> &'static str { + match self { + Self::Flag => "flag", + Self::Key => "key", + Self::OriginHead => "origin/HEAD", + } + } +} + +/// The ref the mutation diff starts from, and what became of looking for it. +#[derive(Clone, Debug, PartialEq, Eq)] +pub(crate) enum Base { + /// A ref that names a commit. + Found { source: BaseSource, name: String }, + /// A ref a flag or the config named that is not a commit: the layer + /// fails, naming it. + Unresolved { source: BaseSource, name: String }, + /// Nothing named a base and the remote has no default branch. `tried` + /// has one line per source. + Missing { tried: Vec }, +} + +impl Base { + /// A base nothing was asked for: the layer that would use it is off. + pub(crate) fn unused() -> Self { + Self::Missing { tried: Vec::new() } + } +} + +/// The base for the mutation diff: `flag`, else `key`, else the remote's +/// default branch (`origin/HEAD`). A named base is never replaced by a later +/// source, so one that does not resolve is [`Base::Unresolved`]. +pub(crate) fn resolve_base(dir: &Path, flag: Option<&str>, key: Option<&str>) -> Base { + let named = flag + .map(|name| (BaseSource::Flag, name)) + .or_else(|| key.map(|name| (BaseSource::Key, name))); + match named { + Some((source, name)) => { + let name = name.to_string(); + if names_a_commit(dir, &name) { + Base::Found { source, name } + } else { + Base::Unresolved { source, name } + } + } + None => origin_head(dir), + } +} + +fn origin_head(dir: &Path) -> Base { + let note = match git_line( + dir, + &[ + "symbolic-ref", + "--quiet", + "--short", + "refs/remotes/origin/HEAD", + ], + ) { + None => "origin/HEAD: not set".to_string(), + Some(name) if names_a_commit(dir, &name) => { + return Base::Found { + source: BaseSource::OriginHead, + name, + } + } + Some(name) => format!("origin/HEAD: points at {name}, which is not a commit"), + }; + Base::Missing { + tried: vec![ + "--base: not given".to_string(), + "gates.base_ref: not set".to_string(), + note, + ], + } +} + +/// The first line git prints for `args`, when it succeeds with one. +fn git_line(dir: &Path, args: &[&str]) -> Option { + let out = Command::new("git") + .args(args) + .current_dir(dir) + .stderr(Stdio::null()) + .output() + .ok()?; + let text = String::from_utf8_lossy(&out.stdout); + let line = text.lines().next().unwrap_or_default().trim(); + (out.status.success() && !line.is_empty()).then(|| line.to_string()) +} + +/// Whether `name` is a ref that names a commit. A name that starts with `-` +/// is never one: it would be read as an option. +fn names_a_commit(dir: &Path, name: &str) -> bool { + !name.is_empty() + && !name.starts_with('-') + && git_line( + dir, + &[ + "rev-parse", + "--verify", + "--quiet", + &format!("{name}^{{commit}}"), + ], + ) + .is_some() +} + +/// Whether `CI` says this is a CI run: set, not empty, and not `false` or +/// `0` in any case. +pub(crate) fn ci_active(value: Option<&str>) -> bool { + value + .map(str::trim) + .is_some_and(|text| !text.is_empty() && text != "0" && !text.eq_ignore_ascii_case("false")) +} + /// Mutation diff command, then the `cargo mutants` tool step. /// -/// The diff command uses `git merge-base` and `&&`, and writes -/// `/rust-tops.diff`. Run it with the project as the working -/// directory. [`MutationPlan::after_diff`] runs mutants only after a +/// The diff command writes `/rust-tops.diff`: the changes from +/// `git merge-base HEAD` to `HEAD`. Run it with the project as the +/// working directory. [`MutationPlan::after_diff`] runs mutants only after a /// non-empty diff; a failed diff is not waived, and an empty diff is not /// handed to `cargo mutants`. #[derive(Clone, Debug, PartialEq, Eq)] @@ -356,14 +494,19 @@ pub(crate) struct MutationPlan { pub diff: Step, pub diff_path: PathBuf, pub mutants: Step, + pub base: Base, } impl MutationPlan { #[must_use] - pub(crate) fn new(report_dir: &Path) -> Self { + pub(crate) fn new(report_dir: &Path, base: Base) -> Self { let diff_path = report_dir.join(DIFF_NAME); let diff_arg = diff_path.display().to_string(); - let script = mutation_diff_script(report_dir, &diff_path); + let from = match &base { + Base::Found { name, .. } | Base::Unresolved { name, .. } => Some(name.as_str()), + Base::Missing { .. } => None, + }; + let script = mutation_diff_script(report_dir, &diff_path, from); let diff = Step::command(["sh", "-c", script.as_str()]); let mutants = Step::tool([ "cargo", @@ -377,6 +520,7 @@ impl MutationPlan { diff, diff_path, mutants, + base, } } @@ -387,24 +531,25 @@ impl MutationPlan { } } -/// Not a git work tree, or no commit: the command fails. No `origin/main`: -/// it writes an empty diff, so the layer is Vacuous. `origin/main` with no -/// merge-base: it fails. Otherwise the diff from the merge-base to `HEAD`. -fn mutation_diff_script(report_dir: &Path, diff_path: &Path) -> String { - let dir = shell_quote(report_dir); - let file = shell_quote(diff_path); - format!( - "mkdir -p {dir} && git rev-parse --verify --quiet HEAD >/dev/null \ - && if git rev-parse --verify --quiet refs/remotes/origin/main >/dev/null; \ - then base=\"$(git merge-base origin/main HEAD)\" \ - && git diff \"$base\" HEAD --unified=0 > {file}; \ - else : > {file}; fi" - ) +/// Not a git work tree, or no commit: the command fails. With a base: the +/// diff from `git merge-base HEAD` to `HEAD`, and no merge-base is a +/// failure. With none: an empty diff, so the layer is Vacuous. +fn mutation_diff_script(report_dir: &Path, diff_path: &Path, base: Option<&str>) -> String { + let dir = shell_quote(&report_dir.display().to_string()); + let file = shell_quote(&diff_path.display().to_string()); + let head = format!("mkdir -p {dir} && git rev-parse --verify --quiet HEAD >/dev/null"); + match base { + Some(name) => format!( + "{head} && base=\"$(git merge-base {} HEAD)\" \ + && git diff \"$base\" HEAD --unified=0 > {file}", + shell_quote(name) + ), + None => format!("{head} && : > {file}"), + } } -fn shell_quote(path: &Path) -> String { - let text = path.display().to_string().replace('\'', "'\\''"); - format!("'{text}'") +fn shell_quote(text: &str) -> String { + format!("'{}'", text.replace('\'', "'\\''")) } fn one_layer(layer: &str) -> bool { @@ -746,3 +891,70 @@ mod expiry { assert!(Exemption::new("mutation", "not-a-date").is_err()); } } + +#[cfg(test)] +mod base { + use super::{ci_active, mutation_diff_script, shell_quote, Base, BaseSource, MutationPlan}; + use std::path::Path; + + #[test] + fn ci_is_a_value_that_is_neither_empty_false_nor_zero() { + for on in ["true", "1", "yes", "TRUE", " true "] { + assert!(ci_active(Some(on)), "{on}"); + } + for off in ["", " ", "false", "False", "FALSE", "0", " 0 "] { + assert!(!ci_active(Some(off)), "{off:?}"); + } + assert!(!ci_active(None)); + } + + #[test] + fn each_source_has_a_label_and_a_report_name() { + assert_eq!(BaseSource::Flag.label(), "--base"); + assert_eq!(BaseSource::Key.label(), "gates.base_ref"); + assert_eq!(BaseSource::OriginHead.label(), "origin/HEAD"); + assert_eq!(BaseSource::Flag.report_name(), "flag"); + assert_eq!(BaseSource::Key.report_name(), "key"); + assert_eq!(BaseSource::OriginHead.report_name(), "origin/HEAD"); + } + + #[test] + fn a_name_is_quoted_for_the_shell() { + assert_eq!(shell_quote("origin/main"), "'origin/main'"); + assert_eq!(shell_quote("a'b"), "'a'\\''b'"); + assert_eq!(shell_quote("$(x)"), "'$(x)'"); + } + + #[test] + fn the_script_diffs_from_the_merge_base_or_writes_an_empty_file() { + let report = Path::new("/r"); + let file = Path::new("/r/rust-tops.diff"); + let with = mutation_diff_script(report, file, Some("origin/dev")); + assert_eq!( + with, + "mkdir -p '/r' && git rev-parse --verify --quiet HEAD >/dev/null \ + && base=\"$(git merge-base 'origin/dev' HEAD)\" \ + && git diff \"$base\" HEAD --unified=0 > '/r/rust-tops.diff'" + ); + let without = mutation_diff_script(report, file, None); + assert_eq!( + without, + "mkdir -p '/r' && git rev-parse --verify --quiet HEAD >/dev/null \ + && : > '/r/rust-tops.diff'" + ); + } + + #[test] + fn the_plan_keeps_its_base_and_an_unused_base_names_no_source() { + let found = Base::Found { + source: BaseSource::Key, + name: "origin/dev".to_string(), + }; + let plan = MutationPlan::new(Path::new("/r"), found.clone()); + assert_eq!(plan.base, found); + assert!(plan.diff.argv.join(" ").contains("merge-base 'origin/dev'")); + let none = MutationPlan::new(Path::new("/r"), Base::unused()); + assert_eq!(none.base, Base::Missing { tried: Vec::new() }); + assert!(!none.diff.argv.join(" ").contains("merge-base")); + } +} diff --git a/crates/cargo-tops/templates/drop-in/rust-tops.yml b/crates/cargo-tops/templates/drop-in/rust-tops.yml index 2fa8292..0088f14 100644 --- a/crates/cargo-tops/templates/drop-in/rust-tops.yml +++ b/crates/cargo-tops/templates/drop-in/rust-tops.yml @@ -174,8 +174,9 @@ jobs: # Runs the gate rust-tops.yaml declares: every enabled layer at tier <= 1, # laws included when they are on. Not a --dry-run. fetch-depth: 0 because - # the mutation layer diffs against origin/main, which a depth-1 checkout - # does not have. cargo-tops builds with Rust 1.99.1 (its rust-version), + # the mutation layer diffs against the base branch, which a depth-1 checkout + # does not have. --base names that branch: actions/checkout may not create + # origin/HEAD, and a gate with no base fails under CI. cargo-tops builds with Rust 1.99.1 (its rust-version), # which can be newer than crate.msrv; the layers run on the pinned channel. # The cargo-tops version is pinned; bump it when the kit publishes. # Since 0.4.0 the gate enforces the coverage floors and the CRAP threshold @@ -220,7 +221,7 @@ jobs: with: tool: cargo-mutants@27.1.0 fallback: none - - run: cargo tops gate --max-tier 1 + - run: cargo tops gate --max-tier 1 --base "origin/${{ github.base_ref || github.event.repository.default_branch }}" # mutants-diff: class overlay. Diff-scoped; no --baseline skip; default # features usually need no FFI sysdeps. Do not mark required until one diff --git a/crates/cargo-tops/templates/rust-tops.schema.json b/crates/cargo-tops/templates/rust-tops.schema.json index f261112..d70f0d0 100644 --- a/crates/cargo-tops/templates/rust-tops.schema.json +++ b/crates/cargo-tops/templates/rust-tops.schema.json @@ -137,6 +137,11 @@ "additionalProperties": false, "required": ["unit", "coverage", "crap", "mutation", "lint"], "properties": { + "base_ref": { + "description": "The ref the mutation diff starts from when --base is not given: a branch, tag or commit that resolves in the checkout, such as origin/main. Absent means the remote's default branch (origin/HEAD).", + "type": "string", + "minLength": 1 + }, "lint": { "type": "object", "properties": { diff --git a/crates/cargo-tops/tests/gate_base.rs b/crates/cargo-tops/tests/gate_base.rs new file mode 100644 index 0000000..cb02a4a --- /dev/null +++ b/crates/cargo-tops/tests/gate_base.rs @@ -0,0 +1,613 @@ +//! The mutation layer diffs from a named base: `--base `, then +//! `gates.base_ref`, then `origin/HEAD`. A base that is named and does not +//! resolve fails and names the ref. With no base at all the layer is `fail` +//! under `CI` (naming `fetch-depth: 0` and `--base`) and `vacuous` +//! otherwise, listing each source tried. The report names the base and +//! where it came from. +//! +//! Each case is a real git repository. Cargo and its plugins are stubs that +//! log what they are asked, so a test sees whether `cargo mutants` ran and +//! on which diff. Every report is validated against the schema. +use std::fs; +use std::path::{Path, PathBuf}; +use std::process::{Command, Output}; + +use serde_json::{json, Value}; + +/// The validator `cargo tops check` uses, and the schema it reads. +#[path = "../src/schema.rs"] +mod schema; + +mod profiles { + pub(crate) const SCHEMA_JSON: &str = include_str!("../templates/rust-tops.schema.json"); +} + +const REPORT_SCHEMA: &str = include_str!("../../../schema/gate-report.schema.json"); + +/// Logs its argv when `$CARGO_STUB_LOG` is set; answers every `--version`; +/// passes everything else. +const CARGO_STUB: &str = r#"#!/bin/sh +if [ -n "${CARGO_STUB_LOG:-}" ]; then echo "$*" >> "$CARGO_STUB_LOG"; fi +if [ "$1 $2" = "crap --version" ]; then echo "cargo-crap 0.9.0"; exit 0; fi +case "$*" in *--version) echo "stub-tool 1.2.3"; exit 0 ;; esac +exit 0 +"#; + +struct Fixture { + root: PathBuf, + repo: PathBuf, + bin: PathBuf, + home: PathBuf, +} + +impl Drop for Fixture { + fn drop(&mut self) { + fs::remove_dir_all(&self.root).ok(); + } +} + +fn at<'v>(value: &'v Value, pointer: &str) -> &'v Value { + static NULL: Value = Value::Null; + value.pointer(pointer).unwrap_or(&NULL) +} + +fn stub(bin: &Path, name: &str, body: &str) { + let path = bin.join(name); + fs::write(&path, body).expect("write stub"); + #[cfg(unix)] + { + use std::os::unix::fs::PermissionsExt; + fs::set_permissions(&path, fs::Permissions::from_mode(0o755)).expect("chmod stub"); + } +} + +fn git(fixture: &Fixture, dir: &Path, args: &[&str]) -> String { + let out = Command::new("git") + .args(["-c", "commit.gpgsign=false"]) + .args(args) + .current_dir(dir) + .env("HOME", &fixture.home) + .env("GIT_CONFIG_NOSYSTEM", "1") + .env("GIT_AUTHOR_NAME", "fixture") + .env("GIT_AUTHOR_EMAIL", "fixture@example.invalid") + .env("GIT_COMMITTER_NAME", "fixture") + .env("GIT_COMMITTER_EMAIL", "fixture@example.invalid") + .output() + .expect("spawn git"); + assert!( + out.status.success(), + "git {args:?}: {}", + String::from_utf8_lossy(&out.stderr) + ); + String::from_utf8_lossy(&out.stdout).trim().to_string() +} + +fn set(doc: &mut Value, key: &str, value: Value) { + doc.as_object_mut() + .expect("an object") + .insert(key.to_string(), value); +} + +fn edit(fixture: &Fixture, change: impl FnOnce(&mut Value)) { + let path = fixture.repo.join("rust-tops.yaml"); + let mut doc: Value = + serde_saphyr::from_str(&fs::read_to_string(&path).expect("read")).expect("yaml"); + change(&mut doc); + fs::write(&path, serde_json::to_string_pretty(&doc).expect("json")).expect("write yaml"); +} + +/// A library-core instance named `fixture`, in a directory of its own with +/// a `Cargo.toml`, one source file and stub tools, not yet a git repository. +fn scaffold(name: &str) -> Fixture { + let root = std::env::temp_dir().join(format!("cargo-tops-base-{name}-{}", std::process::id())); + fs::remove_dir_all(&root).ok(); + let fixture = Fixture { + repo: root.join("repo"), + bin: root.join("bin"), + home: root.join("home"), + root, + }; + fs::create_dir_all(&fixture.bin).expect("mkdir bin"); + fs::create_dir_all(&fixture.home).expect("mkdir home"); + let init = Command::new(env!("CARGO_BIN_EXE_cargo-tops")) + .args([ + "init", + "--class", + "library-core", + "--name", + "fixture", + "--path", + ]) + .arg(&fixture.repo) + .output() + .expect("spawn init"); + assert!(init.status.success(), "init failed"); + fs::write( + fixture.repo.join("Cargo.toml"), + "[package]\nname = \"fixture\"\nversion = \"0.1.0\"\n", + ) + .expect("write Cargo.toml"); + fs::create_dir_all(fixture.repo.join("src")).expect("mkdir src"); + fs::write(fixture.repo.join("src/a.rs"), "pub fn a() {}\n").expect("write a.rs"); + fs::write(fixture.repo.join(".gitignore"), "/target\n").expect("write .gitignore"); + stub(&fixture.bin, "cargo", CARGO_STUB); + for tool in ["cargo-deny", "cargo-nextest", "cargo-mutants"] { + stub(&fixture.bin, tool, "#!/bin/sh\nexit 0\n"); + } + fixture +} + +/// The scaffold with `static-lint`, `security-advisory`, `property` and +/// `mutation` on, in a git repository whose one branch is `branch` and whose +/// one commit is everything `init` wrote. There is no remote. +fn fixture(name: &str, branch: &str) -> Fixture { + let fixture = scaffold(name); + edit(&fixture, |doc| { + let layers = doc.pointer_mut("/layers").and_then(Value::as_array_mut); + for layer in layers.expect("layers") { + let id = layer.get("id").and_then(Value::as_str).unwrap_or_default(); + let on = matches!( + id, + "static-lint" | "security-advisory" | "property" | "mutation" + ); + set(layer, "enabled", Value::Bool(on)); + } + }); + git(&fixture, &fixture.repo, &["init", "-q", "-b", branch]); + git(&fixture, &fixture.repo, &["add", "-A"]); + git(&fixture, &fixture.repo, &["commit", "-q", "-m", "adopt"]); + fixture +} + +/// A commit that adds `file` under `src/`. +fn commit_file(fixture: &Fixture, file: &str) -> String { + fs::write(fixture.repo.join("src").join(file), format!("// {file}\n")).expect("write"); + git(fixture, &fixture.repo, &["add", "-A"]); + git(fixture, &fixture.repo, &["commit", "-q", "-m", file]); + git(fixture, &fixture.repo, &["rev-parse", "HEAD"]) +} + +/// What a clone leaves: a remote `origin` holding `branch`, with +/// `refs/remotes/origin/HEAD` pointing at it. +fn clone_shape(fixture: &Fixture, branch: &str) { + let bare = fixture.root.join("origin.git"); + git( + fixture, + &fixture.root, + &["init", "-q", "--bare", "origin.git"], + ); + let url = bare.to_string_lossy().into_owned(); + git(fixture, &fixture.repo, &["remote", "add", "origin", &url]); + git(fixture, &fixture.repo, &["push", "-q", "origin", branch]); + git( + fixture, + &fixture.repo, + &["remote", "set-head", "origin", branch], + ); +} + +/// `refs/remotes/origin/` at `commit`. +fn remote_ref(fixture: &Fixture, name: &str, commit: &str) { + let full = format!("refs/remotes/origin/{name}"); + git(fixture, &fixture.repo, &["update-ref", &full, commit]); +} + +fn set_base_ref(fixture: &Fixture, base: &str) { + edit(fixture, |doc| { + let gates = doc.pointer_mut("/gates").expect("gates"); + set(gates, "base_ref", json!(base)); + }); +} + +fn gate(fixture: &Fixture, args: &[&str], ci: Option<&str>) -> (Output, String) { + let mut cmd = Command::new(env!("CARGO_BIN_EXE_cargo-tops")); + cmd.arg("gate") + .args(args) + .arg("--path") + .arg(&fixture.repo) + .env( + "PATH", + std::env::join_paths([ + fixture.bin.as_path(), + Path::new("/usr/bin"), + Path::new("/bin"), + ]) + .expect("PATH"), + ) + .env("HOME", &fixture.home) + .env("GIT_CONFIG_NOSYSTEM", "1") + .env("CARGO_STUB_LOG", fixture.root.join("cargo.log")) + .env_remove("CARGO_TARGET_DIR") + .env_remove("CI"); + if let Some(value) = ci { + cmd.env("CI", value); + } + let out = cmd.output().expect("spawn cargo-tops gate"); + let text = format!( + "{}{}", + String::from_utf8_lossy(&out.stdout), + String::from_utf8_lossy(&out.stderr) + ); + (out, text) +} + +fn report(fixture: &Fixture) -> Value { + let raw = fs::read_to_string(fixture.repo.join("target/rust-tops/report.json")) + .expect("report.json was written"); + let doc: Value = serde_json::from_str(&raw).expect("report.json is JSON"); + let schema: Value = serde_json::from_str(REPORT_SCHEMA).expect("schema is JSON"); + let errors = schema::validate(&schema, &doc); + assert!( + errors.is_empty(), + "report.json breaks the schema: {errors:?}\n{raw}" + ); + doc +} + +fn mutation(report: &Value) -> &Value { + at(report, "/layers") + .as_array() + .and_then(|layers| layers.iter().find(|row| at(row, "/id") == "mutation")) + .unwrap_or_else(|| at(report, "/missing")) +} + +fn cargo_log(fixture: &Fixture) -> String { + fs::read_to_string(fixture.root.join("cargo.log")).unwrap_or_default() +} + +/// Whether `cargo mutants` ran. +fn mutants_ran(fixture: &Fixture) -> bool { + cargo_log(fixture) + .lines() + .any(|line| line.starts_with("mutants --in-diff ")) +} + +fn diff_text(fixture: &Fixture) -> String { + fs::read_to_string(fixture.repo.join("target/rust-tops/rust-tops.diff")).unwrap_or_default() +} + +/// A branch `feature` two commits ahead of `base`: `src/b.rs`, then +/// `src/c.rs`. Returns the commits `(base, after_b, after_c)`. +fn feature_branch(fixture: &Fixture) -> (String, String, String) { + let base = git(fixture, &fixture.repo, &["rev-parse", "HEAD"]); + git(fixture, &fixture.repo, &["checkout", "-q", "-b", "feature"]); + let after_b = commit_file(fixture, "b.rs"); + let after_c = commit_file(fixture, "c.rs"); + (base, after_b, after_c) +} + +#[test] +fn a_default_branch_called_trunk_runs_mutants() { + let fixture = fixture("trunk", "trunk"); + clone_shape(&fixture, "trunk"); + feature_branch(&fixture); + let (out, text) = gate(&fixture, &[], None); + assert_eq!(out.status.code(), Some(0), "{text}"); + assert!(mutants_ran(&fixture), "{}", cargo_log(&fixture)); + let diff = diff_text(&fixture); + assert!( + diff.contains("src/b.rs") && diff.contains("src/c.rs"), + "{diff}" + ); + let report = report(&fixture); + let row = mutation(&report); + assert_eq!(at(row, "/verdict"), "pass", "{row}"); + assert_eq!( + at(row, "/judged/base"), + &json!({ "ref": "origin/trunk", "source": "origin/HEAD" }), + "{row}" + ); + assert!(at(row, "/detail").is_null(), "{row}"); + assert!(!text.contains("origin/main"), "{text}"); +} + +/// Three remote refs on one history: `origin/main` before the two commits, +/// `origin/one` after the first, `origin/two` at `HEAD`. `origin/HEAD` is +/// `origin/main`. +fn three_bases(name: &str) -> Fixture { + let fixture = fixture(name, "main"); + clone_shape(&fixture, "main"); + let (_, after_b, after_c) = feature_branch(&fixture); + remote_ref(&fixture, "one", &after_b); + remote_ref(&fixture, "two", &after_c); + fixture +} + +fn touched(diff: &str) -> (bool, bool) { + (diff.contains("src/b.rs"), diff.contains("src/c.rs")) +} + +#[test] +fn origin_head_is_the_base_when_nothing_else_names_one() { + let fixture = three_bases("from-head"); + let (out, text) = gate(&fixture, &[], None); + assert_eq!(out.status.code(), Some(0), "{text}"); + assert_eq!(touched(&diff_text(&fixture)), (true, true)); + let report = report(&fixture); + assert_eq!( + at(mutation(&report), "/judged/base"), + &json!({ "ref": "origin/main", "source": "origin/HEAD" }) + ); +} + +#[test] +fn the_key_beats_origin_head() { + let fixture = three_bases("key-over-head"); + set_base_ref(&fixture, "origin/one"); + let (out, text) = gate(&fixture, &[], None); + assert_eq!(out.status.code(), Some(0), "{text}"); + assert_eq!(touched(&diff_text(&fixture)), (false, true), "{text}"); + let report = report(&fixture); + assert_eq!( + at(mutation(&report), "/judged/base"), + &json!({ "ref": "origin/one", "source": "key" }) + ); +} + +#[test] +fn the_flag_beats_the_key_and_origin_head() { + let fixture = three_bases("flag-over-key"); + // The key alone would leave an empty diff; the flag gives a real one. + set_base_ref(&fixture, "origin/two"); + let (out, text) = gate(&fixture, &["--base", "origin/one"], None); + assert_eq!(out.status.code(), Some(0), "{text}"); + assert!(mutants_ran(&fixture), "{}", cargo_log(&fixture)); + assert_eq!(touched(&diff_text(&fixture)), (false, true), "{text}"); + let report = report(&fixture); + assert_eq!( + at(mutation(&report), "/judged/base"), + &json!({ "ref": "origin/one", "source": "flag" }) + ); +} + +#[test] +fn a_base_at_head_is_an_empty_diff_and_vacuous() { + let fixture = three_bases("empty"); + let (out, text) = gate(&fixture, &["--base", "origin/two"], None); + assert_eq!(out.status.code(), Some(0), "{text}"); + assert!( + text.contains("Vacuous: the diff from `git merge-base origin/two HEAD` is empty"), + "{text}" + ); + assert!(!mutants_ran(&fixture)); + let report = report(&fixture); + assert_eq!(at(mutation(&report), "/verdict"), "vacuous"); +} + +#[test] +fn a_tag_or_a_commit_is_a_base() { + let fixture = three_bases("tag-and-sha"); + let one = git(&fixture, &fixture.repo, &["rev-parse", "origin/one"]); + git(&fixture, &fixture.repo, &["tag", "v0", &one]); + for named in ["v0", one.as_str()] { + let (out, text) = gate(&fixture, &["--base", named], None); + assert_eq!(out.status.code(), Some(0), "{named}: {text}"); + assert_eq!(touched(&diff_text(&fixture)), (false, true), "{named}"); + let report = report(&fixture); + assert_eq!(at(mutation(&report), "/judged/base/ref"), named); + } +} + +fn expect_unresolved(fixture: &Fixture, text: &str, out: &Output, name: &str, source: &str) { + assert_eq!(out.status.code(), Some(1), "{text}"); + assert!(text.contains(name), "{text}"); + assert!( + text.lines() + .any(|line| line.starts_with("Failed:") && line.contains(name)), + "{text}" + ); + assert!(!mutants_ran(fixture), "{}", cargo_log(fixture)); + let report = report(fixture); + let row = mutation(&report); + assert_eq!(at(row, "/verdict"), "fail", "{row}"); + assert!( + at(row, "/detail") + .as_str() + .is_some_and(|d| d.contains(name)), + "{row}" + ); + assert_eq!( + at(row, "/judged/base"), + &json!({ "ref": name, "source": source, "resolved": false }), + "{row}" + ); +} + +#[test] +fn a_named_base_that_does_not_resolve_fails_naming_it() { + let fixture = three_bases("nope-flag"); + let (out, text) = gate(&fixture, &["--base", "nope"], None); + expect_unresolved(&fixture, &text, &out, "nope", "flag"); + assert!(text.contains("--base names `nope`"), "{text}"); +} + +#[test] +fn a_named_key_that_does_not_resolve_fails_naming_it() { + let fixture = three_bases("nope-key"); + set_base_ref(&fixture, "origin/gone"); + let (out, text) = gate(&fixture, &[], None); + expect_unresolved(&fixture, &text, &out, "origin/gone", "key"); + assert!( + text.contains("gates.base_ref names `origin/gone`"), + "{text}" + ); +} + +#[test] +fn a_named_base_is_never_replaced_by_a_later_source() { + // The key and `origin/HEAD` would both resolve. The flag does not. + let fixture = three_bases("nope-over-key"); + set_base_ref(&fixture, "origin/one"); + let (out, text) = gate(&fixture, &["--base", "nope"], None); + expect_unresolved(&fixture, &text, &out, "nope", "flag"); +} + +#[test] +fn a_base_that_starts_with_a_dash_is_not_a_ref() { + let fixture = three_bases("dash"); + let (out, text) = gate(&fixture, &["--base=-x"], None); + expect_unresolved(&fixture, &text, &out, "-x", "flag"); + let (out, text) = gate(&fixture, &["--base="], None); + assert_eq!(out.status.code(), Some(1), "{text}"); + assert!(text.contains("--base names ``"), "{text}"); +} + +#[test] +fn no_base_under_ci_fails_naming_fetch_depth_and_the_flag() { + for ci in ["true", "1", "yes", "TRUE"] { + let fixture = fixture("ci-none", "main"); + let (out, text) = gate(&fixture, &[], Some(ci)); + assert_eq!(out.status.code(), Some(1), "CI={ci}: {text}"); + assert!( + text.lines().any(|line| line.starts_with("Failed:") + && line.contains("fetch-depth: 0") + && line.contains("--base")), + "CI={ci}: {text}" + ); + assert!(!text.contains("Vacuous"), "CI={ci}: {text}"); + assert!(!mutants_ran(&fixture)); + let report = report(&fixture); + let row = mutation(&report); + assert_eq!(at(row, "/verdict"), "fail", "{row}"); + assert_eq!(at(&report, "/ok"), &json!(false)); + } +} + +#[test] +fn no_base_without_ci_is_vacuous_and_lists_every_source_tried() { + // Unset, empty, `false`, `0` and any case of `false` are not CI. + for ci in [None, Some(""), Some("false"), Some("False"), Some("0")] { + let fixture = fixture("ci-off", "main"); + let (out, text) = gate(&fixture, &[], ci); + assert_eq!(out.status.code(), Some(0), "CI={ci:?}: {text}"); + for source in [ + "--base: not given", + "gates.base_ref: not set", + "origin/HEAD: not set", + ] { + assert!(text.contains(source), "CI={ci:?}: {source}: {text}"); + } + assert!(text.contains("Vacuous: no mutation base"), "{text}"); + assert!(!mutants_ran(&fixture)); + let report = report(&fixture); + let row = mutation(&report); + assert_eq!(at(row, "/verdict"), "vacuous", "{row}"); + let detail = at(row, "/detail").as_str().unwrap_or_default(); + for source in [ + "--base: not given", + "gates.base_ref: not set", + "origin/HEAD: not set", + ] { + assert!(detail.contains(source), "{row}"); + } + assert_eq!( + at(row, "/judged/base"), + &json!({ + "ref": null, + "source": null, + "tried": [ + "--base: not given", + "gates.base_ref: not set", + "origin/HEAD: not set" + ] + }), + "{row}" + ); + } +} + +#[test] +fn an_origin_head_that_points_nowhere_is_no_base() { + let fixture = fixture("dangling", "main"); + git( + &fixture, + &fixture.repo, + &[ + "symbolic-ref", + "refs/remotes/origin/HEAD", + "refs/remotes/origin/gone", + ], + ); + let (out, text) = gate(&fixture, &[], None); + assert_eq!(out.status.code(), Some(0), "{text}"); + assert!( + text.contains("origin/HEAD: points at origin/gone, which is not a commit"), + "{text}" + ); + let (out, text) = gate(&fixture, &[], Some("true")); + assert_eq!(out.status.code(), Some(1), "{text}"); + assert!(text.contains("fetch-depth: 0"), "{text}"); +} + +#[test] +fn a_flag_or_key_is_a_base_under_ci_too() { + let fixture = three_bases("ci-named"); + let (out, text) = gate(&fixture, &["--base", "origin/one"], Some("true")); + assert_eq!(out.status.code(), Some(0), "{text}"); + assert!(mutants_ran(&fixture)); +} + +#[test] +fn a_failed_diff_is_failed_whatever_the_ci_setting() { + // Not a git work tree: the diff command fails, with or without CI. + let fixture = fixture("not-git", "main"); + fs::remove_dir_all(fixture.repo.join(".git")).expect("remove .git"); + for ci in [None, Some("true")] { + let (out, text) = gate(&fixture, &[], ci); + assert_eq!(out.status.code(), Some(1), "CI={ci:?}: {text}"); + assert!(text.contains("a failed diff is never waived"), "{text}"); + assert!(!text.contains("fetch-depth"), "{text}"); + assert!(!mutants_ran(&fixture)); + } +} + +#[test] +fn a_dry_run_lists_the_diff_from_the_named_base() { + let fixture = three_bases("dry"); + let (out, text) = gate(&fixture, &["--dry-run", "--base", "origin/one"], None); + assert_eq!(out.status.code(), Some(1), "{text}"); + assert!(text.contains("git merge-base 'origin/one' HEAD"), "{text}"); + assert!(!mutants_ran(&fixture)); + let report = report(&fixture); + assert_eq!( + at(mutation(&report), "/judged/base"), + &json!({ "ref": "origin/one", "source": "flag" }) + ); +} + +fn check(fixture: &Fixture) -> (Output, String) { + let out = Command::new(env!("CARGO_BIN_EXE_cargo-tops")) + .args(["check", "--path"]) + .arg(&fixture.repo) + .output() + .expect("spawn check"); + let text = format!( + "{}{}", + String::from_utf8_lossy(&out.stdout), + String::from_utf8_lossy(&out.stderr) + ); + (out, text) +} + +#[test] +fn the_schema_accepts_a_base_ref_and_refuses_an_empty_one() { + let fixture = fixture("schema", "main"); + set_base_ref(&fixture, "origin/main"); + let (out, text) = check(&fixture); + assert_eq!(out.status.code(), Some(0), "{text}"); + set_base_ref(&fixture, ""); + let (out, text) = check(&fixture); + assert_ne!(out.status.code(), Some(0), "{text}"); + assert!(text.contains("base_ref"), "{text}"); +} + +#[test] +fn the_flag_is_in_the_gate_help() { + let out = Command::new(env!("CARGO_BIN_EXE_cargo-tops")) + .args(["gate", "--help"]) + .output() + .expect("spawn help"); + let text = String::from_utf8_lossy(&out.stdout); + assert!(text.contains("--base "), "{text}"); + assert!(text.contains("fetch-depth: 0"), "{text}"); +} diff --git a/crates/cargo-tops/tests/golden/init/binary-cli/.github/workflows/rust-tops.yml b/crates/cargo-tops/tests/golden/init/binary-cli/.github/workflows/rust-tops.yml index 2fa8292..0088f14 100644 --- a/crates/cargo-tops/tests/golden/init/binary-cli/.github/workflows/rust-tops.yml +++ b/crates/cargo-tops/tests/golden/init/binary-cli/.github/workflows/rust-tops.yml @@ -174,8 +174,9 @@ jobs: # Runs the gate rust-tops.yaml declares: every enabled layer at tier <= 1, # laws included when they are on. Not a --dry-run. fetch-depth: 0 because - # the mutation layer diffs against origin/main, which a depth-1 checkout - # does not have. cargo-tops builds with Rust 1.99.1 (its rust-version), + # the mutation layer diffs against the base branch, which a depth-1 checkout + # does not have. --base names that branch: actions/checkout may not create + # origin/HEAD, and a gate with no base fails under CI. cargo-tops builds with Rust 1.99.1 (its rust-version), # which can be newer than crate.msrv; the layers run on the pinned channel. # The cargo-tops version is pinned; bump it when the kit publishes. # Since 0.4.0 the gate enforces the coverage floors and the CRAP threshold @@ -220,7 +221,7 @@ jobs: with: tool: cargo-mutants@27.1.0 fallback: none - - run: cargo tops gate --max-tier 1 + - run: cargo tops gate --max-tier 1 --base "origin/${{ github.base_ref || github.event.repository.default_branch }}" # mutants-diff: class overlay. Diff-scoped; no --baseline skip; default # features usually need no FFI sysdeps. Do not mark required until one diff --git a/crates/cargo-tops/tests/golden/init/ffi-bridge/.github/workflows/rust-tops.yml b/crates/cargo-tops/tests/golden/init/ffi-bridge/.github/workflows/rust-tops.yml index 08a2f9e..c2d18d4 100644 --- a/crates/cargo-tops/tests/golden/init/ffi-bridge/.github/workflows/rust-tops.yml +++ b/crates/cargo-tops/tests/golden/init/ffi-bridge/.github/workflows/rust-tops.yml @@ -174,8 +174,9 @@ jobs: # Runs the gate rust-tops.yaml declares: every enabled layer at tier <= 1, # laws included when they are on. Not a --dry-run. fetch-depth: 0 because - # the mutation layer diffs against origin/main, which a depth-1 checkout - # does not have. cargo-tops builds with Rust 1.99.1 (its rust-version), + # the mutation layer diffs against the base branch, which a depth-1 checkout + # does not have. --base names that branch: actions/checkout may not create + # origin/HEAD, and a gate with no base fails under CI. cargo-tops builds with Rust 1.99.1 (its rust-version), # which can be newer than crate.msrv; the layers run on the pinned channel. # The cargo-tops version is pinned; bump it when the kit publishes. # Since 0.4.0 the gate enforces the coverage floors and the CRAP threshold @@ -220,7 +221,7 @@ jobs: with: tool: cargo-mutants@27.1.0 fallback: none - - run: cargo tops gate --max-tier 1 + - run: cargo tops gate --max-tier 1 --base "origin/${{ github.base_ref || github.event.repository.default_branch }}" # mutants-diff: class overlay. Diff-scoped; no --baseline skip; default # features usually need no FFI sysdeps. Do not mark required until one diff --git a/crates/cargo-tops/tests/golden/init/library-core/.github/workflows/rust-tops.yml b/crates/cargo-tops/tests/golden/init/library-core/.github/workflows/rust-tops.yml index 2fa8292..0088f14 100644 --- a/crates/cargo-tops/tests/golden/init/library-core/.github/workflows/rust-tops.yml +++ b/crates/cargo-tops/tests/golden/init/library-core/.github/workflows/rust-tops.yml @@ -174,8 +174,9 @@ jobs: # Runs the gate rust-tops.yaml declares: every enabled layer at tier <= 1, # laws included when they are on. Not a --dry-run. fetch-depth: 0 because - # the mutation layer diffs against origin/main, which a depth-1 checkout - # does not have. cargo-tops builds with Rust 1.99.1 (its rust-version), + # the mutation layer diffs against the base branch, which a depth-1 checkout + # does not have. --base names that branch: actions/checkout may not create + # origin/HEAD, and a gate with no base fails under CI. cargo-tops builds with Rust 1.99.1 (its rust-version), # which can be newer than crate.msrv; the layers run on the pinned channel. # The cargo-tops version is pinned; bump it when the kit publishes. # Since 0.4.0 the gate enforces the coverage floors and the CRAP threshold @@ -220,7 +221,7 @@ jobs: with: tool: cargo-mutants@27.1.0 fallback: none - - run: cargo tops gate --max-tier 1 + - run: cargo tops gate --max-tier 1 --base "origin/${{ github.base_ref || github.event.repository.default_branch }}" # mutants-diff: class overlay. Diff-scoped; no --baseline skip; default # features usually need no FFI sysdeps. Do not mark required until one diff --git a/crates/cargo-tops/tests/golden/init/library-util/.github/workflows/rust-tops.yml b/crates/cargo-tops/tests/golden/init/library-util/.github/workflows/rust-tops.yml index 2fa8292..0088f14 100644 --- a/crates/cargo-tops/tests/golden/init/library-util/.github/workflows/rust-tops.yml +++ b/crates/cargo-tops/tests/golden/init/library-util/.github/workflows/rust-tops.yml @@ -174,8 +174,9 @@ jobs: # Runs the gate rust-tops.yaml declares: every enabled layer at tier <= 1, # laws included when they are on. Not a --dry-run. fetch-depth: 0 because - # the mutation layer diffs against origin/main, which a depth-1 checkout - # does not have. cargo-tops builds with Rust 1.99.1 (its rust-version), + # the mutation layer diffs against the base branch, which a depth-1 checkout + # does not have. --base names that branch: actions/checkout may not create + # origin/HEAD, and a gate with no base fails under CI. cargo-tops builds with Rust 1.99.1 (its rust-version), # which can be newer than crate.msrv; the layers run on the pinned channel. # The cargo-tops version is pinned; bump it when the kit publishes. # Since 0.4.0 the gate enforces the coverage floors and the CRAP threshold @@ -220,7 +221,7 @@ jobs: with: tool: cargo-mutants@27.1.0 fallback: none - - run: cargo tops gate --max-tier 1 + - run: cargo tops gate --max-tier 1 --base "origin/${{ github.base_ref || github.event.repository.default_branch }}" # mutants-diff: class overlay. Diff-scoped; no --baseline skip; default # features usually need no FFI sysdeps. Do not mark required until one diff --git a/crates/cargo-tops/tests/golden/init/no-std-embedded/.github/workflows/rust-tops.yml b/crates/cargo-tops/tests/golden/init/no-std-embedded/.github/workflows/rust-tops.yml index 6735f2c..ec2b6f2 100644 --- a/crates/cargo-tops/tests/golden/init/no-std-embedded/.github/workflows/rust-tops.yml +++ b/crates/cargo-tops/tests/golden/init/no-std-embedded/.github/workflows/rust-tops.yml @@ -174,8 +174,9 @@ jobs: # Runs the gate rust-tops.yaml declares: every enabled layer at tier <= 1, # laws included when they are on. Not a --dry-run. fetch-depth: 0 because - # the mutation layer diffs against origin/main, which a depth-1 checkout - # does not have. cargo-tops builds with Rust 1.99.1 (its rust-version), + # the mutation layer diffs against the base branch, which a depth-1 checkout + # does not have. --base names that branch: actions/checkout may not create + # origin/HEAD, and a gate with no base fails under CI. cargo-tops builds with Rust 1.99.1 (its rust-version), # which can be newer than crate.msrv; the layers run on the pinned channel. # The cargo-tops version is pinned; bump it when the kit publishes. # Since 0.4.0 the gate enforces the coverage floors and the CRAP threshold @@ -220,7 +221,7 @@ jobs: with: tool: cargo-mutants@27.1.0 fallback: none - - run: cargo tops gate --max-tier 1 + - run: cargo tops gate --max-tier 1 --base "origin/${{ github.base_ref || github.event.repository.default_branch }}" # mutants-diff: class overlay. Diff-scoped; no --baseline skip; default # features usually need no FFI sysdeps. Do not mark required until one diff --git a/crates/cargo-tops/tests/golden/init/parser-codec/.github/workflows/rust-tops.yml b/crates/cargo-tops/tests/golden/init/parser-codec/.github/workflows/rust-tops.yml index c1aabd0..c4b6146 100644 --- a/crates/cargo-tops/tests/golden/init/parser-codec/.github/workflows/rust-tops.yml +++ b/crates/cargo-tops/tests/golden/init/parser-codec/.github/workflows/rust-tops.yml @@ -174,8 +174,9 @@ jobs: # Runs the gate rust-tops.yaml declares: every enabled layer at tier <= 1, # laws included when they are on. Not a --dry-run. fetch-depth: 0 because - # the mutation layer diffs against origin/main, which a depth-1 checkout - # does not have. cargo-tops builds with Rust 1.99.1 (its rust-version), + # the mutation layer diffs against the base branch, which a depth-1 checkout + # does not have. --base names that branch: actions/checkout may not create + # origin/HEAD, and a gate with no base fails under CI. cargo-tops builds with Rust 1.99.1 (its rust-version), # which can be newer than crate.msrv; the layers run on the pinned channel. # The cargo-tops version is pinned; bump it when the kit publishes. # Since 0.4.0 the gate enforces the coverage floors and the CRAP threshold @@ -220,7 +221,7 @@ jobs: with: tool: cargo-mutants@27.1.0 fallback: none - - run: cargo tops gate --max-tier 1 + - run: cargo tops gate --max-tier 1 --base "origin/${{ github.base_ref || github.event.repository.default_branch }}" # mutants-diff: class overlay. Diff-scoped; no --baseline skip; default # features usually need no FFI sysdeps. Do not mark required until one diff --git a/crates/cargo-tops/tests/golden/init/unsafe-kernel/.github/workflows/rust-tops.yml b/crates/cargo-tops/tests/golden/init/unsafe-kernel/.github/workflows/rust-tops.yml index a73b1e3..eadedb1 100644 --- a/crates/cargo-tops/tests/golden/init/unsafe-kernel/.github/workflows/rust-tops.yml +++ b/crates/cargo-tops/tests/golden/init/unsafe-kernel/.github/workflows/rust-tops.yml @@ -174,8 +174,9 @@ jobs: # Runs the gate rust-tops.yaml declares: every enabled layer at tier <= 1, # laws included when they are on. Not a --dry-run. fetch-depth: 0 because - # the mutation layer diffs against origin/main, which a depth-1 checkout - # does not have. cargo-tops builds with Rust 1.99.1 (its rust-version), + # the mutation layer diffs against the base branch, which a depth-1 checkout + # does not have. --base names that branch: actions/checkout may not create + # origin/HEAD, and a gate with no base fails under CI. cargo-tops builds with Rust 1.99.1 (its rust-version), # which can be newer than crate.msrv; the layers run on the pinned channel. # The cargo-tops version is pinned; bump it when the kit publishes. # Since 0.4.0 the gate enforces the coverage floors and the CRAP threshold @@ -220,7 +221,7 @@ jobs: with: tool: cargo-mutants@27.1.0 fallback: none - - run: cargo tops gate --max-tier 1 + - run: cargo tops gate --max-tier 1 --base "origin/${{ github.base_ref || github.event.repository.default_branch }}" # mutants-diff: class overlay. Diff-scoped; no --baseline skip; default # features usually need no FFI sysdeps. Do not mark required until one diff --git a/crates/cargo-tops/tests/golden/init/workspace-root/.github/workflows/rust-tops.yml b/crates/cargo-tops/tests/golden/init/workspace-root/.github/workflows/rust-tops.yml index 2fa8292..0088f14 100644 --- a/crates/cargo-tops/tests/golden/init/workspace-root/.github/workflows/rust-tops.yml +++ b/crates/cargo-tops/tests/golden/init/workspace-root/.github/workflows/rust-tops.yml @@ -174,8 +174,9 @@ jobs: # Runs the gate rust-tops.yaml declares: every enabled layer at tier <= 1, # laws included when they are on. Not a --dry-run. fetch-depth: 0 because - # the mutation layer diffs against origin/main, which a depth-1 checkout - # does not have. cargo-tops builds with Rust 1.99.1 (its rust-version), + # the mutation layer diffs against the base branch, which a depth-1 checkout + # does not have. --base names that branch: actions/checkout may not create + # origin/HEAD, and a gate with no base fails under CI. cargo-tops builds with Rust 1.99.1 (its rust-version), # which can be newer than crate.msrv; the layers run on the pinned channel. # The cargo-tops version is pinned; bump it when the kit publishes. # Since 0.4.0 the gate enforces the coverage floors and the CRAP threshold @@ -220,7 +221,7 @@ jobs: with: tool: cargo-mutants@27.1.0 fallback: none - - run: cargo tops gate --max-tier 1 + - run: cargo tops gate --max-tier 1 --base "origin/${{ github.base_ref || github.event.repository.default_branch }}" # mutants-diff: class overlay. Diff-scoped; no --baseline skip; default # features usually need no FFI sysdeps. Do not mark required until one diff --git a/crates/cargo-tops/tests/laws_gate.rs b/crates/cargo-tops/tests/laws_gate.rs index 0c28bec..921b4a9 100644 --- a/crates/cargo-tops/tests/laws_gate.rs +++ b/crates/cargo-tops/tests/laws_gate.rs @@ -364,6 +364,8 @@ fn adopt(fixture: &Fixture, origin: Origin) { let url = bare.to_string_lossy().into_owned(); git(fixture, repo, &["remote", "add", "origin", &url]); git(fixture, repo, &["push", "-q", "origin", "main"]); + // A clone leaves `origin/HEAD` at the default branch. + git(fixture, repo, &["remote", "set-head", "origin", "main"]); } } @@ -397,6 +399,15 @@ fn unrelated_origin(fixture: &Fixture) { &fixture.repo, &["update-ref", "refs/remotes/origin/main", &orphan], ); + git( + fixture, + &fixture.repo, + &[ + "symbolic-ref", + "refs/remotes/origin/HEAD", + "refs/remotes/origin/main", + ], + ); } /// Plant a non-empty diff where a failed run must not read it. @@ -607,7 +618,9 @@ fn gate_command(fixture: &Fixture, path: OsString, cargo_target: Option<&Path>) .env("CARGO_TOPS_BEND_PATH", "1") .env("BEND_STUB_LOG", fixture.root.join("bend.log")) .env("CARGO_STUB_LOG", fixture.root.join("cargo.log")) - .env_remove("RUST_TOPS_ROOT"); + .env_remove("RUST_TOPS_ROOT") + // A gate with no mutation base fails under CI; these runs are not CI. + .env_remove("CI"); match cargo_target { Some(dir) => { cmd.env("CARGO_TARGET_DIR", dir); @@ -652,7 +665,7 @@ fn law<'v>(cases: &'v serde_json::Value, name: &str) -> &'v serde_json::Value { /// What every fresh-init gate run says, laws on or off: nothing NotRun, /// `acceptance` listed as off and never run, nothing above tier 1 run, the -/// mutation layer `Vacuous` with no `origin/main`, and a count that is not +/// mutation layer `Vacuous` with no mutation base, and a count that is not /// short. fn expect_fresh_init_outcomes(class: &str, fixture: &Fixture, text: &str) { assert!(!text.contains("NotRun"), "{class}: {text}"); @@ -666,7 +679,7 @@ fn expect_fresh_init_outcomes(class: &str, fixture: &Fixture, text: &str) { "{class}: cargo kani ran at --max-tier 1" ); assert!( - text.contains("Vacuous: no origin/main; the mutation diff is empty"), + text.contains("Vacuous: no mutation base (--base: not given; gates.base_ref: not set; origin/HEAD: not set); the mutation diff is empty"), "{class}: {text}" ); assert!(!text.contains("Vacuous: the diff from"), "{class}: {text}"); @@ -1763,7 +1776,7 @@ fn a_failed_diff_is_failed_with_no_escape() { } #[test] -fn no_origin_main_is_an_empty_diff_and_vacuous() { +fn no_base_is_an_empty_diff_and_vacuous() { // `git init` plus one commit and no remote. A stale diff is replaced by // the empty one, not read. let fixture = fixture_with("diff-no-origin", &["static-lint", "mutation", "laws"]); @@ -1773,7 +1786,7 @@ fn no_origin_main_is_an_empty_diff_and_vacuous() { let (out, text) = gate(&fixture, path_without_bend(&fixture.bin)); assert_eq!(out.status.code(), Some(0), "{text}"); assert!( - text.contains("Vacuous: no origin/main; the mutation diff is empty"), + text.contains("Vacuous: no mutation base (--base: not given; gates.base_ref: not set; origin/HEAD: not set); the mutation diff is empty"), "{text}" ); assert!(!text.contains("Vacuous: the diff from"), "{text}"); diff --git a/schema/rust-tops.schema.json b/schema/rust-tops.schema.json index f261112..d70f0d0 100644 --- a/schema/rust-tops.schema.json +++ b/schema/rust-tops.schema.json @@ -137,6 +137,11 @@ "additionalProperties": false, "required": ["unit", "coverage", "crap", "mutation", "lint"], "properties": { + "base_ref": { + "description": "The ref the mutation diff starts from when --base is not given: a branch, tag or commit that resolves in the checkout, such as origin/main. Absent means the remote's default branch (origin/HEAD).", + "type": "string", + "minLength": 1 + }, "lint": { "type": "object", "properties": { From e5b8bd947da89ec2d2b22dcaa7ad2f19a681dc07 Mon Sep 17 00:00:00 2001 From: VirtualMachinist Date: Thu, 19 Nov 2026 21:13:02 -0500 Subject: [PATCH 2/4] Test the git line and the base lookup Two mutants survived: git_line accepted a failed run or an empty line, and the base was looked up for any layer but mutation. The lookup is now base_for, and each has a test. Co-Authored-By: Claude Sonnet 5.5 --- crates/cargo-tops/src/gate/plan.rs | 59 +++++++++++++++++++++++++++--- crates/cargo-tops/src/steps.rs | 36 +++++++++++++++++- 2 files changed, 88 insertions(+), 7 deletions(-) diff --git a/crates/cargo-tops/src/gate/plan.rs b/crates/cargo-tops/src/gate/plan.rs index 8153f99..6a74081 100644 --- a/crates/cargo-tops/src/gate/plan.rs +++ b/crates/cargo-tops/src/gate/plan.rs @@ -330,6 +330,15 @@ fn report_dir(dir: &Path) -> Result { Ok(report) } +/// The mutation base, looked up only when a mutation layer is in range. +fn base_for(enabled: &[&config::Layer], dir: &Path, flag: Option<&str>, key: Option<&str>) -> Base { + if enabled.iter().any(|layer| layer.id == "mutation") { + steps::resolve_base(dir, flag, key) + } else { + Base::unused() + } +} + /// What each enabled layer other than `laws` does. fn units_of<'a>( enabled: &[&'a config::Layer], @@ -372,11 +381,7 @@ pub(crate) fn build<'a>( } let report = report_dir(dir)?; let tests = TestCommands::new(&enabled, &report); - let base = if enabled.iter().any(|layer| layer.id == "mutation") { - steps::resolve_base(dir, base_flag, cfg.gates.base_ref.as_deref()) - } else { - Base::unused() - }; + let base = base_for(&enabled, dir, base_flag, cfg.gates.base_ref.as_deref()); let crap_pin = if enabled.iter().any(|layer| layer.id == "crap") { tool_pin(dir, "cargo-crap").map_err(Fault::config)? } else { @@ -400,8 +405,50 @@ pub(crate) fn build<'a>( #[cfg(test)] mod tests { - use super::{GatePlan, TestCommands}; + use super::{base_for, GatePlan, TestCommands}; + use crate::config::Layer; + use crate::steps::{Base, BaseSource}; use std::path::PathBuf; + use std::process::Command; + + fn layer(id: &str) -> Layer { + serde_saphyr::from_str(&format!( + "{{ id: {id}, enabled: true, tier: 0, runner: x }}" + )) + .expect("layer") + } + + #[test] + fn the_base_is_looked_up_only_with_a_mutation_layer_in_range() { + let dir = std::env::temp_dir().join(format!("cargo-tops-base-for-{}", std::process::id())); + std::fs::remove_dir_all(&dir).ok(); + std::fs::create_dir_all(&dir).expect("mkdir"); + let git = |args: &[&str]| { + let out = Command::new("git") + .args(["-c", "user.name=t", "-c", "user.email=t@example.invalid"]) + .args(args) + .current_dir(&dir) + .output() + .expect("spawn git"); + assert!(out.status.success(), "git {args:?}"); + }; + git(&["init", "-q"]); + git(&["commit", "-q", "--allow-empty", "-m", "one"]); + let mutation = layer("mutation"); + let unit = layer("unit"); + let found = Base::Found { + source: BaseSource::Flag, + name: "HEAD".to_string(), + }; + assert_eq!(base_for(&[&mutation], &dir, Some("HEAD"), None), found); + assert_eq!( + base_for(&[&unit, &mutation], &dir, Some("HEAD"), None), + found + ); + assert_eq!(base_for(&[&unit], &dir, Some("HEAD"), None), Base::unused()); + assert_eq!(base_for(&[], &dir, Some("HEAD"), None), Base::unused()); + std::fs::remove_dir_all(&dir).ok(); + } #[test] fn a_layer_with_no_unit_in_the_plan_has_no_commands() { diff --git a/crates/cargo-tops/src/steps.rs b/crates/cargo-tops/src/steps.rs index 8f636de..530eabc 100644 --- a/crates/cargo-tops/src/steps.rs +++ b/crates/cargo-tops/src/steps.rs @@ -894,7 +894,9 @@ mod expiry { #[cfg(test)] mod base { - use super::{ci_active, mutation_diff_script, shell_quote, Base, BaseSource, MutationPlan}; + use super::{ + ci_active, git_line, mutation_diff_script, shell_quote, Base, BaseSource, MutationPlan, + }; use std::path::Path; #[test] @@ -957,4 +959,36 @@ mod base { assert_eq!(none.base, Base::Missing { tried: Vec::new() }); assert!(!none.diff.argv.join(" ").contains("merge-base")); } + + #[test] + fn a_line_is_what_a_successful_git_prints_and_nothing_else() { + let dir = std::env::temp_dir().join(format!("cargo-tops-git-line-{}", std::process::id())); + std::fs::remove_dir_all(&dir).ok(); + std::fs::create_dir_all(&dir).expect("mkdir"); + let git = |args: &[&str]| { + git_line(&dir, args); + }; + git(&["init", "-q"]); + assert_eq!( + git_line(&dir, &["rev-parse", "--git-dir"]).as_deref(), + Some(".git") + ); + // Success with no output is no line. + assert_eq!(git_line(&dir, &["status", "--porcelain"]), None); + // Failure with output is no line either: `diff --exit-code` prints + // the change and exits 1. + std::fs::write(dir.join("f"), "one\n").expect("write"); + let add = std::process::Command::new("git") + .args(["add", "-N", "f"]) + .current_dir(&dir) + .status() + .expect("spawn git"); + assert!(add.success()); + assert_eq!(git_line(&dir, &["diff", "--exit-code"]), None); + assert_eq!( + git_line(&dir, &["status", "--porcelain"]).as_deref(), + Some("A f") + ); + std::fs::remove_dir_all(&dir).ok(); + } } From 0033abadf536ac99c199b069a9ff1a770d3d1c38 Mon Sep 17 00:00:00 2001 From: VirtualMachinist Date: Thu, 19 Nov 2026 22:02:15 -0500 Subject: [PATCH 3/4] Say the same thing about the mutation base everywhere The no-base words had two owners: stdout knew about CI and the report did not, so a CI failure showed the vacuous detail and a problem line about a diff command that had not failed. steps::stop_note now words every stop once. The run keeps it, and stdout, the row detail and the problem line all print it. - No base under CI: detail and problem name fetch-depth: 0 and --base. - An unresolved base runs no git and counts no command; the problem names the ref. - A direct origin/HEAD that names a commit is a base, not "not set". - A base with no common history, as in a shallow checkout, gets the fetch-depth: 0 hint and a detail. - The row keeps other judged keys when it adds the base. - PROTOCOL.md states the CI rule evenly and the cookbook drops origin/main...HEAD. Co-Authored-By: Claude Sonnet 5.5 --- PROTOCOL.md | 4 +- crates/cargo-tops/src/facts.rs | 24 +++ crates/cargo-tops/src/gate/execute.rs | 107 ++++---------- crates/cargo-tops/src/gate/judge.rs | 9 +- crates/cargo-tops/src/gate/mod.rs | 1 + crates/cargo-tops/src/gate/plan.rs | 1 + crates/cargo-tops/src/gate/report.rs | 68 ++++++--- crates/cargo-tops/src/steps.rs | 204 +++++++++++++++++++++++--- crates/cargo-tops/tests/gate_base.rs | 129 ++++++++++++++++ 9 files changed, 416 insertions(+), 131 deletions(-) diff --git a/PROTOCOL.md b/PROTOCOL.md index b2f3b70..a9d57f7 100644 --- a/PROTOCOL.md +++ b/PROTOCOL.md @@ -491,7 +491,7 @@ cargo mutants --in-diff /tmp/pr.diff -j 2 -- --skip ignored The first source that is set wins. A ref that is named by the flag or the key and does not name a commit fails the layer, and the failure names the ref. The diff is from `git merge-base HEAD` to `HEAD`. The report names the base and its source (`flag`, `key` or `origin/HEAD`). -When no source gives a base, the layer is `fail` if the `CI` environment variable is set and is not empty, `false` or `0`. The detail names `fetch-depth: 0` and `--base`: a checkout that never fetched the base must not read as a clean diff. When `CI` is unset, `false` or `0`, the layer is `vacuous`, and the detail lists each source tried. CI workflows pass `--base "origin/${{ github.base_ref || github.event.repository.default_branch }}"` from a checkout with `fetch-depth: 0`, because `actions/checkout` may not create `origin/HEAD`. +`CI` counts as set when it is not empty and is not `0` or `false` (in any case). When no source gives a base, the layer is `fail` if `CI` is set. The report's `detail` and the gate's problem line name `fetch-depth: 0` and `--base`: a checkout that never fetched the base must not read as a clean diff. When `CI` is not set, the layer is `vacuous`, and the detail lists each source tried. A base that resolves but shares no history with `HEAD`, as in a shallow checkout, fails the diff and names `fetch-depth: 0` too. CI workflows pass `--base "origin/${{ github.base_ref || github.event.repository.default_branch }}"` from a checkout with `fetch-depth: 0`, because `actions/checkout` may not create `origin/HEAD`. Pass criteria: @@ -1021,7 +1021,7 @@ cargo test --doc --workspace cargo llvm-cov nextest --workspace --all-features \ --lcov --output-path target/coverage/lcov.info --fail-under-lines 90 cargo crap -git diff origin/main...HEAD --unified=0 > /tmp/pr.diff +git diff "$(git merge-base "$BASE" HEAD)" HEAD --unified=0 > /tmp/pr.diff # BASE: section 8.3 cargo mutants --in-diff /tmp/pr.diff # extra by class diff --git a/crates/cargo-tops/src/facts.rs b/crates/cargo-tops/src/facts.rs index c46b3ec..1b5e546 100644 --- a/crates/cargo-tops/src/facts.rs +++ b/crates/cargo-tops/src/facts.rs @@ -29,6 +29,18 @@ pub(crate) struct Run { /// The last step that ran: the one that decided `outcome`. pub step: String, pub outcome: Outcome, + /// Why the layer stopped, when it stopped on something no command + /// reported: the mutation base. The report prints it as the layer's + /// detail and its problem, in place of "`step` failed". + pub note: Option, +} + +impl Run { + /// Whether a command ran. A layer that stopped on its note before any + /// command has an empty `cmd` and a note. + pub(crate) fn ran(&self) -> bool { + !self.cmd.is_empty() || self.note.is_none() + } } /// A run some law may count: `Passed`, `Failed` or `ToolMissing`, never @@ -1047,9 +1059,21 @@ mod tests { cmd: cmd.into(), step: cmd.into(), outcome, + note: None, } } + #[test] + fn a_run_with_a_note_and_no_command_ran_nothing() { + let mut stopped = run("mutation", "", Outcome::Failed); + assert!(stopped.ran()); + stopped.note = Some("why".to_string()); + assert!(!stopped.ran()); + stopped.cmd = "git x".to_string(); + assert!(stopped.ran()); + assert!(run("unit", "cargo nextest", Outcome::Passed).ran()); + } + fn ctx_with<'a>(cfg: &'a TopsConfig, runs: &'a [Run]) -> Ctx<'a> { Ctx { dir: Path::new("."), diff --git a/crates/cargo-tops/src/gate/execute.rs b/crates/cargo-tops/src/gate/execute.rs index d4cc6c3..b57cf56 100644 --- a/crates/cargo-tops/src/gate/execute.rs +++ b/crates/cargo-tops/src/gate/execute.rs @@ -313,6 +313,7 @@ pub(crate) fn finish(layer: &str, ran: &[String], outcome: Outcome) -> Run { cmd: ran.join(" && "), step: ran.last().cloned().unwrap_or_default(), outcome, + note: None, } } @@ -361,10 +362,10 @@ pub(crate) fn run_pinned_crap(dir: &Path, layer: &str, chain: &[Step], pin: &str /// `cargo-mutants` is looked up before the diff, so an empty diff cannot /// hide a missing tool. A base that was named and is not a commit fails the -/// layer, naming it. A failed diff is `Failed`; nothing waives it. An empty -/// one is `Vacuous` and `cargo mutants` does not run, except that no base at -/// all is `Failed` when `CI` is set: a base that was never fetched must not -/// read as a clean diff. +/// layer before any command runs. A failed diff is `Failed`; nothing waives +/// it. An empty one is `Vacuous` and `cargo mutants` does not run, except +/// that no base at all fails under CI. [`steps::stop_note`] words every one +/// of these stops. pub(crate) fn run_mutation(dir: &Path, layer: &str, plan: &MutationPlan) -> Result { if let Err(missing) = steps::check_tool(&plan.mutants.argv) { println!("{missing}"); @@ -374,58 +375,36 @@ pub(crate) fn run_mutation(dir: &Path, layer: &str, plan: &MutationPlan) -> Resu Outcome::ToolMissing, )); } - let mut ran = vec![plan.diff.display()]; - if let Base::Unresolved { source, name } = &plan.base { - println!( - "Failed: {} names `{name}`, which is not a commit; the mutation diff cannot start there", - source.label() - ); - return Ok(finish(layer, &ran, Outcome::Failed)); + if matches!(plan.base, Base::Unresolved { .. }) { + return Ok(stopped(layer, &[], &plan.base, Outcome::Failed)); } + let mut ran = vec![plan.diff.display()]; let diff_ok = run_step(dir, &plan.diff)? == Outcome::Passed; let diff = steps::judge_diff(diff_ok, &plan.diff_path); let Some(mutants) = plan.after_diff(diff) else { - let ci = std::env::var("CI").ok(); - let outcome = stopped_diff(&plan.base, diff, ci.as_deref()); - return Ok(finish(layer, &ran, outcome)); + return Ok(stopped(layer, &ran, &plan.base, diff)); }; ran.push(mutants.display()); let outcome = run_step(dir, mutants)?; Ok(finish(layer, &ran, outcome)) } -/// Say why the diff stopped the layer, and give its outcome: a failed diff -/// stays failed, no base under CI (the value of `CI`) fails, and any other -/// empty diff is vacuous. -fn stopped_diff(base: &Base, diff: Outcome, ci: Option<&str>) -> Outcome { - match (diff, base) { - (Outcome::Vacuous, Base::Missing { tried }) => { - let sources = tried.join("; "); - if steps::ci_active(ci) { - println!( - "Failed: no mutation base ({sources}); under CI that is never a clean diff. \ - Check out with `fetch-depth: 0` and pass `--base `, or set `gates.base_ref`" - ); - Outcome::Failed - } else { - println!( - "Vacuous: no mutation base ({sources}); the mutation diff is empty; \ - cargo mutants did not run and no law counts this layer" - ); - Outcome::Vacuous - } - } - (Outcome::Vacuous, Base::Found { name, .. } | Base::Unresolved { name, .. }) => { - println!( - "Vacuous: the diff from `git merge-base {name} HEAD` is empty; \ - cargo mutants did not run and no law counts this layer" - ); - Outcome::Vacuous - } - (other, _) => { - println!("Failed: the mutation diff did not succeed; a failed diff is never waived"); - other - } +/// The run of a layer that stopped on its base or its diff: prints the +/// note and keeps it with the run, so the report says the same. A diff +/// command that ran and failed is named in the kept note, since it did fail; +/// a base that was never tried, or an empty diff, names no command. +fn stopped(layer: &str, ran: &[String], base: &Base, diff: Outcome) -> Run { + let (outcome, note) = steps::stop_note(base, diff) + .unwrap_or_else(|| (diff, format!("the mutation diff ended as {diff}"))); + println!("{outcome}: {note}"); + let command_failed = diff == Outcome::Failed && !matches!(base, Base::Unresolved { .. }); + let kept = match ran.last() { + Some(step) if command_failed => format!("`{step}` failed: {note}"), + _ => note, + }; + Run { + note: Some(kept), + ..finish(layer, ran, outcome) } } @@ -465,9 +444,9 @@ pub(crate) fn run_step(dir: &Path, step: &Step) -> Result { #[cfg(test)] mod tests { - use super::{run_step, stopped_diff, version_ask, Executed, Timing}; + use super::{run_step, version_ask, Executed, Timing}; use crate::facts::Outcome; - use crate::steps::{Base, BaseSource, Step}; + use crate::steps::Step; use std::fs; use std::path::Path; use std::time::SystemTime; @@ -535,36 +514,4 @@ mod tests { assert!(format!("{err:#}").contains("spawn"), "{err:#}"); fs::remove_dir_all(&dir).ok(); } - - #[test] - fn an_empty_diff_is_vacuous_unless_no_base_was_found_under_ci() { - let missing = Base::Missing { - tried: vec!["origin/HEAD: not set".to_string()], - }; - let found = Base::Found { - source: BaseSource::Flag, - name: "origin/main".to_string(), - }; - let vacuous = Outcome::Vacuous; - assert_eq!(stopped_diff(&missing, vacuous, None), Outcome::Vacuous); - assert_eq!( - stopped_diff(&missing, vacuous, Some("false")), - Outcome::Vacuous - ); - assert_eq!( - stopped_diff(&missing, vacuous, Some("true")), - Outcome::Failed - ); - // A named base that gave an empty diff is vacuous even under CI. - assert_eq!( - stopped_diff(&found, vacuous, Some("true")), - Outcome::Vacuous - ); - // A failed diff stays failed, whatever the base and CI. - for base in [&missing, &found] { - for ci in [None, Some("true")] { - assert_eq!(stopped_diff(base, Outcome::Failed, ci), Outcome::Failed); - } - } - } } diff --git a/crates/cargo-tops/src/gate/judge.rs b/crates/cargo-tops/src/gate/judge.rs index 20d0387..78e8161 100644 --- a/crates/cargo-tops/src/gate/judge.rs +++ b/crates/cargo-tops/src/gate/judge.rs @@ -243,7 +243,7 @@ fn judge_laws( /// judged the laws layer. A layer that took another layer's run ran none. pub(crate) fn ran_commands(runs: &[Run], bend_ran: bool, shared: &[(&str, &str)]) -> usize { runs.iter() - .filter(|run| run.outcome != Outcome::ToolMissing) + .filter(|run| run.outcome != Outcome::ToolMissing && run.ran()) .filter(|run| !shared.iter().any(|(layer, _)| *layer == run.layer)) .count() + usize::from(bend_ran) @@ -272,7 +272,7 @@ pub(crate) fn command_count( "laws" => !bend_ran, _ => !runs .iter() - .any(|run| run.layer == *id && run.outcome != Outcome::ToolMissing), + .any(|run| run.layer == *id && run.outcome != Outcome::ToolMissing && run.ran()), }) .collect(); let mut line = format!( @@ -320,7 +320,10 @@ pub(crate) fn laws_evaluated(cases: &Path) -> Option<(usize, usize)> { pub(crate) fn run_failure(run: &Run) -> Option { match run.outcome { Outcome::Passed | Outcome::Vacuous => None, - Outcome::Failed => Some(format!("{}: `{}` failed", run.layer, run.step)), + Outcome::Failed => Some(match &run.note { + Some(note) => format!("{}: {note}", run.layer), + None => format!("{}: `{}` failed", run.layer, run.step), + }), Outcome::ToolMissing => { let missing = steps::MissingTool { binary: steps::tool_binary(std::slice::from_ref(&run.step)) diff --git a/crates/cargo-tops/src/gate/mod.rs b/crates/cargo-tops/src/gate/mod.rs index 6321ce5..cb52d3a 100644 --- a/crates/cargo-tops/src/gate/mod.rs +++ b/crates/cargo-tops/src/gate/mod.rs @@ -269,6 +269,7 @@ mod tests { cmd: format!("{layer} cmd"), step: format!("{layer} step"), outcome, + note: None, } } diff --git a/crates/cargo-tops/src/gate/plan.rs b/crates/cargo-tops/src/gate/plan.rs index 6a74081..df0fba8 100644 --- a/crates/cargo-tops/src/gate/plan.rs +++ b/crates/cargo-tops/src/gate/plan.rs @@ -109,6 +109,7 @@ impl TestCommands { cmd: source.map(|run| run.cmd.clone()).unwrap_or_default(), step: source.map(|run| run.step.clone()).unwrap_or_default(), outcome, + note: None, } } } diff --git a/crates/cargo-tops/src/gate/report.rs b/crates/cargo-tops/src/gate/report.rs index 9a4a8e7..5397d9c 100644 --- a/crates/cargo-tops/src/gate/report.rs +++ b/crates/cargo-tops/src/gate/report.rs @@ -16,7 +16,7 @@ use super::{Fault, Mode, Options}; use crate::config::TopsConfig; use crate::facts::{Outcome, Run}; use crate::floors::{CoverageNumbers, CrapNumbers}; -use crate::steps::Base; +use crate::steps::{self, Base}; use crate::{laws, PROTOCOL_VERSION}; /// The file name under the gate's report directory. @@ -421,15 +421,17 @@ fn unit_row(parts: &Parts<'_>, id: &str, tier: u8) -> Map { entry.insert("judged".into(), numbers); } if id == "mutation" { - name_the_base(plan, &mut entry); + name_the_base(plan, done, &mut entry); } entry } /// The mutation row names the base the diff started from and where it came -/// from (`flag`, `key` or `origin/HEAD`), under `judged.base`. A base that -/// was named and is not a commit, or none at all, also says so in `detail`. -fn name_the_base(plan: &GatePlan<'_>, entry: &mut Map) { +/// from (`flag`, `key` or `origin/HEAD`), under `judged.base`. When the +/// layer stopped before `cargo mutants`, `detail` says why, in the words the +/// run printed. A dry run has no run, so a base that is missing or not a +/// commit is worded by [`steps::stop_note`] from the plan alone. +fn name_the_base(plan: &GatePlan<'_>, done: &Executed<'_>, entry: &mut Map) { let Some(What::Mutation(mutation)) = plan .units .iter() @@ -438,28 +440,37 @@ fn name_the_base(plan: &GatePlan<'_>, entry: &mut Map) { else { return; }; - let (base, detail) = match &mutation.base { - Base::Found { source, name } => { - (json!({ "ref": name, "source": source.report_name() }), None) + let base = match &mutation.base { + Base::Found { source, name } => json!({ "ref": name, "source": source.report_name() }), + Base::Unresolved { source, name } => { + json!({ "ref": name, "source": source.report_name(), "resolved": false }) } - Base::Unresolved { source, name } => ( - json!({ "ref": name, "source": source.report_name(), "resolved": false }), - Some(format!( - "{} names `{name}`, which is not a commit", - source.label() - )), - ), - Base::Missing { tried } => ( - json!({ "ref": null, "source": null, "tried": tried }), - Some(format!("no mutation base: {}", tried.join("; "))), - ), + Base::Missing { tried, .. } => json!({ "ref": null, "source": null, "tried": tried }), }; - entry.insert("judged".into(), json!({ "base": base })); - if let Some(detail) = detail { + put_judged(entry, "base", base); + let ran = done + .runs + .iter() + .find(|run| run.layer == "mutation") + .and_then(|run| run.note.clone()); + let planned = (!matches!(mutation.base, Base::Found { .. })) + .then(|| steps::stop_note(&mutation.base, Outcome::Vacuous).map(|(_, note)| note)) + .flatten(); + if let Some(detail) = ran.or(planned) { entry.insert("detail".into(), json!(detail)); } } +/// Set `key` in the row's `judged` object, keeping what else is there. +fn put_judged(entry: &mut Map, key: &str, value: Value) { + let judged = entry + .entry("judged".to_string()) + .or_insert_with(|| json!({})); + if let Some(map) = judged.as_object_mut() { + map.insert(key.to_string(), value); + } +} + fn laws_row(parts: &Parts<'_>, tier: u8) -> Map { let argv = vec![vec![ "bend".to_string(), @@ -512,7 +523,8 @@ fn law_rows(parts: &Parts<'_>) -> (Vec, usize, Option) { #[cfg(test)] mod tests { - use super::{clear, REPORT}; + use super::{clear, put_judged, REPORT}; + use serde_json::{json, Map}; use std::fs; #[test] @@ -525,4 +537,16 @@ mod tests { assert!(!dir.join(REPORT).exists()); fs::remove_dir_all(&dir).ok(); } + + #[test] + fn a_judged_key_is_added_beside_the_ones_already_there() { + let mut row = Map::new(); + put_judged(&mut row, "base", json!({ "ref": "x" })); + assert_eq!(row.get("judged"), Some(&json!({ "base": { "ref": "x" } }))); + put_judged(&mut row, "caught", json!(3)); + assert_eq!( + row.get("judged"), + Some(&json!({ "base": { "ref": "x" }, "caught": 3 })) + ); + } } diff --git a/crates/cargo-tops/src/steps.rs b/crates/cargo-tops/src/steps.rs index 530eabc..6ee5cd9 100644 --- a/crates/cargo-tops/src/steps.rs +++ b/crates/cargo-tops/src/steps.rs @@ -385,14 +385,18 @@ pub(crate) enum Base { /// fails, naming it. Unresolved { source: BaseSource, name: String }, /// Nothing named a base and the remote has no default branch. `tried` - /// has one line per source. - Missing { tried: Vec }, + /// has one line per source; `ci` is whether `CI` was set when the plan + /// was made, which decides whether the layer fails or is vacuous. + Missing { tried: Vec, ci: bool }, } impl Base { /// A base nothing was asked for: the layer that would use it is off. pub(crate) fn unused() -> Self { - Self::Missing { tried: Vec::new() } + Self::Missing { + tried: Vec::new(), + ci: false, + } } } @@ -412,12 +416,26 @@ pub(crate) fn resolve_base(dir: &Path, flag: Option<&str>, key: Option<&str>) -> Base::Unresolved { source, name } } } - None => origin_head(dir), + None => match origin_head(dir) { + Ok(name) => Base::Found { + source: BaseSource::OriginHead, + name, + }, + Err(note) => Base::Missing { + tried: vec![ + "--base: not given".to_string(), + "gates.base_ref: not set".to_string(), + note, + ], + ci: ci_active(std::env::var("CI").ok().as_deref()), + }, + }, } } -fn origin_head(dir: &Path) -> Base { - let note = match git_line( +/// The remote's default branch as a ref, or why there is none. +fn origin_head(dir: &Path) -> Result { + let named = git_line( dir, &[ "symbolic-ref", @@ -425,25 +443,81 @@ fn origin_head(dir: &Path) -> Base { "--short", "refs/remotes/origin/HEAD", ], - ) { - None => "origin/HEAD: not set".to_string(), - Some(name) if names_a_commit(dir, &name) => { - return Base::Found { - source: BaseSource::OriginHead, - name, - } - } - Some(name) => format!("origin/HEAD: points at {name}, which is not a commit"), - }; - Base::Missing { - tried: vec![ - "--base: not given".to_string(), - "gates.base_ref: not set".to_string(), - note, - ], + ); + match named { + Some(name) if names_a_commit(dir, &name) => Ok(name), + Some(name) => Err(format!( + "origin/HEAD: points at {name}, which is not a commit" + )), + // Not a symbolic ref. A direct ref that names a commit is a base. + None if names_a_commit(dir, "origin/HEAD") => Ok("origin/HEAD".to_string()), + None => Err("origin/HEAD: not set".to_string()), + } +} + +/// Why the mutation layer stopped before `cargo mutants`, and its outcome. +/// This is the one place the words live: stdout, the report's `detail` and +/// its `problems` all print what this returns. `diff` is the outcome of the +/// diff command, or `Failed` for a base that was never tried. `None` means +/// the diff passed and mutants runs. +pub(crate) fn stop_note(base: &Base, diff: Outcome) -> Option<(Outcome, String)> { + match (base, diff) { + (Base::Unresolved { source, name }, _) => Some(( + Outcome::Failed, + format!( + "{} names `{name}`, which is not a commit; the mutation diff cannot start there", + source.label() + ), + )), + (Base::Missing { tried, ci: true }, Outcome::Vacuous) => Some(no_base_in_ci(tried)), + (Base::Missing { tried, ci: false }, Outcome::Vacuous) => Some(no_base_outside_ci(tried)), + (Base::Found { name, .. }, Outcome::Vacuous) => Some(( + Outcome::Vacuous, + format!( + "the diff from `git merge-base {name} HEAD` is empty; \ + cargo mutants did not run and no law counts this layer" + ), + )), + (Base::Found { name, .. }, Outcome::Failed) => Some(( + Outcome::Failed, + format!( + "the mutation diff did not succeed: `{name}` and HEAD share no history, \ + as in a shallow checkout (use `fetch-depth: 0`); a failed diff is never waived" + ), + )), + (Base::Missing { .. }, Outcome::Failed) => Some(( + Outcome::Failed, + "the mutation diff did not succeed; a failed diff is never waived".to_string(), + )), + _ => None, } } +/// No source gave a base under CI: a base that was never fetched must not +/// read as a clean diff. +fn no_base_in_ci(tried: &[String]) -> (Outcome, String) { + ( + Outcome::Failed, + format!( + "no mutation base ({}); under CI that is never a clean diff. \ + Check out with `fetch-depth: 0` and pass `--base `, or set `gates.base_ref`", + tried.join("; ") + ), + ) +} + +/// No source gave a base outside CI: the diff is empty and the layer vacuous. +fn no_base_outside_ci(tried: &[String]) -> (Outcome, String) { + ( + Outcome::Vacuous, + format!( + "no mutation base ({}); the mutation diff is empty; \ + cargo mutants did not run and no law counts this layer", + tried.join("; ") + ), + ) +} + /// The first line git prints for `args`, when it succeeds with one. fn git_line(dir: &Path, args: &[&str]) -> Option { let out = Command::new("git") @@ -895,7 +969,8 @@ mod expiry { #[cfg(test)] mod base { use super::{ - ci_active, git_line, mutation_diff_script, shell_quote, Base, BaseSource, MutationPlan, + ci_active, git_line, mutation_diff_script, shell_quote, stop_note, Base, BaseSource, + MutationPlan, Outcome, }; use std::path::Path; @@ -956,7 +1031,7 @@ mod base { assert_eq!(plan.base, found); assert!(plan.diff.argv.join(" ").contains("merge-base 'origin/dev'")); let none = MutationPlan::new(Path::new("/r"), Base::unused()); - assert_eq!(none.base, Base::Missing { tried: Vec::new() }); + assert_eq!(none.base, Base::unused()); assert!(!none.diff.argv.join(" ").contains("merge-base")); } @@ -991,4 +1066,85 @@ mod base { ); std::fs::remove_dir_all(&dir).ok(); } + + fn tried() -> Vec { + vec!["a".to_string(), "b".to_string()] + } + + fn missing_in_ci() -> Base { + Base::Missing { + tried: tried(), + ci: true, + } + } + + fn missing_outside_ci() -> Base { + Base::Missing { + tried: tried(), + ci: false, + } + } + + fn found() -> Base { + Base::Found { + source: BaseSource::Flag, + name: "origin/dev".to_string(), + } + } + + #[test] + fn no_base_fails_under_ci_naming_the_remedy_and_is_vacuous_otherwise() { + let (outcome, note) = stop_note(&missing_in_ci(), Outcome::Vacuous).expect("a stop"); + assert_eq!(outcome, Outcome::Failed); + assert!(note.contains("(a; b)"), "{note}"); + assert!( + note.contains("`fetch-depth: 0`") && note.contains("`--base `"), + "{note}" + ); + let (outcome, note) = stop_note(&missing_outside_ci(), Outcome::Vacuous).expect("a stop"); + assert_eq!(outcome, Outcome::Vacuous); + assert!( + note.contains("(a; b)") && !note.contains("fetch-depth"), + "{note}" + ); + } + + #[test] + fn each_other_stop_has_its_outcome_and_words() { + let unresolved = Base::Unresolved { + source: BaseSource::Key, + name: "nope".to_string(), + }; + // A base that was never tried fails whatever the diff says. + for diff in [Outcome::Passed, Outcome::Failed, Outcome::Vacuous] { + let (outcome, note) = stop_note(&unresolved, diff).expect("a stop"); + assert_eq!(outcome, Outcome::Failed); + assert!(note.starts_with("gates.base_ref names `nope`"), "{note}"); + } + let (outcome, note) = stop_note(&found(), Outcome::Vacuous).expect("a stop"); + assert_eq!(outcome, Outcome::Vacuous); + assert!( + note.starts_with("the diff from `git merge-base origin/dev HEAD` is empty"), + "{note}" + ); + let (outcome, note) = stop_note(&found(), Outcome::Failed).expect("a stop"); + assert_eq!(outcome, Outcome::Failed); + assert!( + note.contains("`origin/dev`") && note.contains("fetch-depth: 0"), + "{note}" + ); + let (outcome, note) = stop_note(&missing_in_ci(), Outcome::Failed).expect("a stop"); + assert_eq!(outcome, Outcome::Failed); + assert!( + note.contains("never waived") && !note.contains("fetch-depth"), + "{note}" + ); + } + + #[test] + fn a_passed_diff_does_not_stop_the_layer() { + for base in [found(), missing_in_ci(), missing_outside_ci()] { + assert_eq!(stop_note(&base, Outcome::Passed), None); + } + } } diff --git a/crates/cargo-tops/tests/gate_base.rs b/crates/cargo-tops/tests/gate_base.rs index cb02a4a..3707ded 100644 --- a/crates/cargo-tops/tests/gate_base.rs +++ b/crates/cargo-tops/tests/gate_base.rs @@ -251,6 +251,18 @@ fn mutation(report: &Value) -> &Value { .unwrap_or_else(|| at(report, "/missing")) } +/// The entries of `problems` that start with `mutation:`. +fn mutation_problems(report: &Value) -> Vec { + at(report, "/problems") + .as_array() + .into_iter() + .flatten() + .filter_map(Value::as_str) + .filter(|problem| problem.starts_with("mutation:")) + .map(str::to_string) + .collect() +} + fn cargo_log(fixture: &Fixture) -> String { fs::read_to_string(fixture.root.join("cargo.log")).unwrap_or_default() } @@ -411,6 +423,22 @@ fn expect_unresolved(fixture: &Fixture, text: &str, out: &Output, name: &str, so &json!({ "ref": name, "source": source, "resolved": false }), "{row}" ); + // Git never ran: the problem says what happened, and no command is + // reported as failed or counted as run. + let problems = mutation_problems(&report); + assert_eq!(problems.len(), 1, "{problems:?}"); + assert!( + problems + .iter() + .all(|p| p.contains(name) && !p.contains("failed") && !p.contains("merge-base")), + "{problems:?}" + ); + assert!( + at(&report, "/count") + .as_str() + .is_some_and(|c| c.contains("none ran for: mutation")), + "{report}" + ); } #[test] @@ -470,6 +498,21 @@ fn no_base_under_ci_fails_naming_fetch_depth_and_the_flag() { let row = mutation(&report); assert_eq!(at(row, "/verdict"), "fail", "{row}"); assert_eq!(at(&report, "/ok"), &json!(false)); + // The report says what stdout says: the remedy, and no command that + // failed, because none did. + let detail = at(row, "/detail").as_str().unwrap_or_default(); + assert!( + detail.contains("fetch-depth: 0") && detail.contains("--base"), + "{row}" + ); + let problems = mutation_problems(&report); + assert_eq!(problems.len(), 1, "{problems:?}"); + assert!( + problems.iter().all(|p| p.contains("fetch-depth: 0") + && p.contains("--base") + && !p.contains("failed")), + "{problems:?}" + ); } } @@ -611,3 +654,89 @@ fn the_flag_is_in_the_gate_help() { assert!(text.contains("--base "), "{text}"); assert!(text.contains("fetch-depth: 0"), "{text}"); } + +#[test] +fn a_dry_run_with_no_base_gives_the_same_remedy_in_the_report() { + let fixture = fixture("dry-ci", "main"); + let (out, text) = gate(&fixture, &["--dry-run"], Some("true")); + assert_eq!(out.status.code(), Some(1), "{text}"); + let doc = report(&fixture); + let detail = at(mutation(&doc), "/detail").as_str().unwrap_or_default(); + assert!( + detail.contains("fetch-depth: 0") && detail.contains("--base"), + "{detail}" + ); + let (_, _) = gate(&fixture, &["--dry-run"], None); + let doc = report(&fixture); + let detail = at(mutation(&doc), "/detail").as_str().unwrap_or_default(); + assert!( + detail.contains("no mutation base") && !detail.contains("fetch-depth"), + "{detail}" + ); +} + +#[test] +fn an_origin_head_that_is_not_a_symbolic_ref_is_still_a_base() { + let fixture = fixture("direct-head", "main"); + let base = git(&fixture, &fixture.repo, &["rev-parse", "HEAD"]); + commit_file(&fixture, "b.rs"); + git( + &fixture, + &fixture.repo, + &[ + "update-ref", + "--no-deref", + "refs/remotes/origin/HEAD", + &base, + ], + ); + let (out, text) = gate(&fixture, &[], Some("true")); + assert_eq!(out.status.code(), Some(0), "{text}"); + assert!(mutants_ran(&fixture), "{}", cargo_log(&fixture)); + assert!(!text.contains("not set"), "{text}"); + let report = report(&fixture); + assert_eq!( + at(mutation(&report), "/judged/base"), + &json!({ "ref": "origin/HEAD", "source": "origin/HEAD" }) + ); +} + +#[test] +fn a_base_with_no_common_history_says_why_and_names_fetch_depth() { + // What a shallow checkout leaves: the base is a commit, and + // `git merge-base` finds nothing in common with HEAD. + let fixture = fixture("no-merge-base", "main"); + let orphan = git( + &fixture, + &fixture.repo, + &[ + "commit-tree", + "4b825dc642cb6eb9a060e54bf8d69288fbee4904", + "-m", + "unrelated", + ], + ); + remote_ref(&fixture, "orph", &orphan); + let (out, text) = gate(&fixture, &["--base", "origin/orph"], None); + assert_eq!(out.status.code(), Some(1), "{text}"); + assert!(text.contains("a failed diff is never waived"), "{text}"); + assert!( + text.contains("fetch-depth: 0") && text.contains("origin/orph"), + "{text}" + ); + assert!(!mutants_ran(&fixture)); + let report = report(&fixture); + let detail = at(mutation(&report), "/detail") + .as_str() + .unwrap_or_default(); + assert!( + detail.contains("fetch-depth: 0") && detail.contains("origin/orph"), + "{detail}" + ); + let problems = mutation_problems(&report); + assert_eq!(problems.len(), 1, "{problems:?}"); + assert!( + problems.iter().all(|p| p.contains("fetch-depth: 0")), + "{problems:?}" + ); +} From b9ca42cc656d1fe774274784823cd7d6e1e94601 Mon Sep 17 00:00:00 2001 From: VirtualMachinist Date: Thu, 19 Nov 2026 22:08:32 -0500 Subject: [PATCH 4/4] Word each base kind's stop in its own function stop_note matched every base and diff pair in one function, which put its CRAP over the new-code threshold. Each base kind now has its own small function; the words and outcomes are unchanged. Co-Authored-By: Claude Sonnet 5.5 --- crates/cargo-tops/src/steps.rs | 36 ++++++++++++++++++++++++---------- 1 file changed, 26 insertions(+), 10 deletions(-) diff --git a/crates/cargo-tops/src/steps.rs b/crates/cargo-tops/src/steps.rs index 6ee5cd9..c27c90e 100644 --- a/crates/cargo-tops/src/steps.rs +++ b/crates/cargo-tops/src/steps.rs @@ -461,34 +461,50 @@ fn origin_head(dir: &Path) -> Result { /// diff command, or `Failed` for a base that was never tried. `None` means /// the diff passed and mutants runs. pub(crate) fn stop_note(base: &Base, diff: Outcome) -> Option<(Outcome, String)> { - match (base, diff) { - (Base::Unresolved { source, name }, _) => Some(( + match base { + Base::Unresolved { source, name } => Some(( Outcome::Failed, format!( "{} names `{name}`, which is not a commit; the mutation diff cannot start there", source.label() ), )), - (Base::Missing { tried, ci: true }, Outcome::Vacuous) => Some(no_base_in_ci(tried)), - (Base::Missing { tried, ci: false }, Outcome::Vacuous) => Some(no_base_outside_ci(tried)), - (Base::Found { name, .. }, Outcome::Vacuous) => Some(( + Base::Missing { tried, ci: true } => missing_stop(diff, no_base_in_ci(tried)), + Base::Missing { tried, ci: false } => missing_stop(diff, no_base_outside_ci(tried)), + Base::Found { name, .. } => found_stop(name, diff), + } +} + +/// A stop with no base: the empty diff gives `empty`, a failed one is never +/// waived. +fn missing_stop(diff: Outcome, empty: (Outcome, String)) -> Option<(Outcome, String)> { + match diff { + Outcome::Vacuous => Some(empty), + Outcome::Failed => Some(( + Outcome::Failed, + "the mutation diff did not succeed; a failed diff is never waived".to_string(), + )), + _ => None, + } +} + +/// A stop with a base that is a commit: an empty diff, or no merge-base. +fn found_stop(name: &str, diff: Outcome) -> Option<(Outcome, String)> { + match diff { + Outcome::Vacuous => Some(( Outcome::Vacuous, format!( "the diff from `git merge-base {name} HEAD` is empty; \ cargo mutants did not run and no law counts this layer" ), )), - (Base::Found { name, .. }, Outcome::Failed) => Some(( + Outcome::Failed => Some(( Outcome::Failed, format!( "the mutation diff did not succeed: `{name}` and HEAD share no history, \ as in a shallow checkout (use `fetch-depth: 0`); a failed diff is never waived" ), )), - (Base::Missing { .. }, Outcome::Failed) => Some(( - Outcome::Failed, - "the mutation diff did not succeed; a failed diff is never waived".to_string(), - )), _ => None, } }