Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions .pre-commit-config.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -141,6 +141,11 @@ repos:
# cargo clippy -p e2e-cucumber --test e2e -- -D warnings
# cargo test --workspace --all-targets --exclude e2e-cucumber
# and `cargo xtask pre-push-check <step> --base <ref>` runs one by hand.
# A step that already passed on the same tree (same cargo command, toolchain
# and environment, clean working tree) is skipped and says so; a green run
# records the pass under the git directory. `ROCM_PRE_PUSH_RERUN=1` (or
# `--rerun` by hand) ignores recorded passes, and `SKIP=<hook id>` still
# skips a hook.
- id: cargo-clippy
name: cargo clippy
entry: cargo xtask pre-push-check clippy
Expand Down
2 changes: 1 addition & 1 deletion CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -48,7 +48,7 @@ prek install -t pre-push # heavier checks on push (clippy + tests of the crat

`prek` runs the same checks locally that CI enforces: `cargo fmt`, `clippy`, `cargo test`, `ruff` (Python), `shellcheck` (shell), PowerShell syntax, license headers (`hawkeye`), markdown links (`lychee`), and the generated manifests (`MANIFEST.md`, `THIRD_PARTY_NOTICES.txt`).

The pre-push hooks (`cargo clippy`, the e2e harness clippy and `cargo test`) check only the crates your push affects: the crates whose files changed plus every crate that depends on them, selected the way CI's `cargo xtask affected` does. They check the whole workspace when a change cannot be confined to specific crates (the lockfile, the root manifest, the toolchain file, workflow files, a doc an xtask test reads, or a path no crate owns), and when the affected crates cannot be determined at all, for example because the remote branch tip is not fetched locally or the pushed range lists no changed files. They also add the crates whose tests read files from outside their own crate: any Rust file adds `xtask`, whose contract tests scan every source file, and `README.md`, `docs/` and `skills/` add `rocm` and `xtask`. Each step prints the scope it chose and why. A push that changes no Rust file runs none of the cargo steps, whatever else it changes (a lockfile-only push included). A green hook is an early warning and not the gate: on pull requests CI lints the whole workspace, but its Linux test job runs only the affected crates, and the whole workspace's tests run in the Windows debug job, in the merge queue and on `main`. To see what a push would check without compiling anything, run `cargo xtask pre-push-check test --dry-run --base origin/main` (the steps are `clippy`, `clippy-e2e` and `test`).
The pre-push hooks (`cargo clippy`, the e2e harness clippy and `cargo test`) check only the crates your push affects: the crates whose files changed plus every crate that depends on them, selected the way CI's `cargo xtask affected` does. They check the whole workspace when a change cannot be confined to specific crates (the lockfile, the root manifest, the toolchain file, workflow files, a doc an xtask test reads, or a path no crate owns), and when the affected crates cannot be determined at all, for example because the remote branch tip is not fetched locally or the pushed range lists no changed files. They also add the crates whose tests read files from outside their own crate: any Rust file adds `xtask`, whose contract tests scan every source file, and `README.md`, `docs/` and `skills/` add `rocm` and `xtask`. Each step prints the scope it chose and why. A step that already passed on this exact content is skipped, and says so: after a green run it records a stamp keyed on the git tree hash of `HEAD`, the exact cargo command (so a pass for a narrow selection never covers a wider one), the toolchain and the `CARGO_*` and `RUST*` environment, under the clone's `.git` directory where every worktree shares it, so a retried push, a manual run before the push or an amend that only rewords the message does not pay for the same checks twice. Stamps are only used and written when the working tree is clean (cargo checks the working tree, not the pushed commit, and an untracked file can hide a missing `git add`), expire after seven days, and do not cover your user-level cargo configuration, installed tools, files git ignores or flaky tests. A skip shows that this tree passed those checks earlier, not that they ran during this push; the `cargo test --workspace` and `cargo clippy --workspace` commands you run by hand are unaffected, and `--rerun` gives a fresh run when you want proof the checks ran for this push. `cargo xtask pre-push-check <step> --rerun`, or `ROCM_PRE_PUSH_RERUN=1` for the hook, ignores them, drops this step's earlier pass so a failed rerun cannot leave it to skip the next run, and records a fresh pass when the step succeeds; `SKIP=<hook id>` still skips a hook outright, and the commit-signature hook runs on every push. A push that changes no Rust file runs none of the cargo steps, whatever else it changes (a lockfile-only push included). A green hook is an early warning and not the gate: on pull requests CI lints the whole workspace, but its Linux test job runs only the affected crates, and the whole workspace's tests run in the Windows debug job, in the merge queue and on `main`. To see what a push would check without compiling anything, run `cargo xtask pre-push-check test --dry-run --base origin/main` (the steps are `clippy`, `clippy-e2e` and `test`).

The manifest hooks only run when you change the dependency graph. They *rewrite* the generated file instead of only reporting that it is stale. When that happens, the commit stops so you can re-stage the refreshed file.

Expand Down
51 changes: 49 additions & 2 deletions docs/testing.md
Original file line number Diff line number Diff line change
Expand Up @@ -448,14 +448,61 @@ Known limits, unchanged by the narrowing: the steps check the working tree rathe
commit; under prek 0.4.5 a push of several refs, a tag or a deletion runs no hooks; and `-p`
builds can resolve Cargo features differently from `--workspace` ones.

Preview what a push would check without compiling:
### Pass stamps

A step that already passed on this exact content is skipped. After a step's cargo command exits 0,
[prepush_stamp.rs](../xtask/src/prepush_stamp.rs) records a stamp, and the next run of the same step
looks for it first. The stamp stands for:

- the step and its exact cargo arguments, so a pass recorded for `-p xtask` never lets a later run
over `--workspace` skip (the selection is part of the key, not a separate check);
- the git *tree* hash of `HEAD`, not the commit hash, so an amend that only rewords the message, or
the same content pushed to a second remote, still hits;
- the compiler and cargo identity (`rustc -vV`, `cargo -vV`) and a digest of the `CARGO_*` and
`RUST*` environment (never the values), minus a short list of per-run variables such as
`CARGO_TARGET_DIR` and `CARGO_TERM_COLOR`. The environment is read as raw bytes, so a variable
whose value is not valid Unicode never stops the hook: an unrelated one is ignored and a
relevant one is hashed as the bytes it is.

The working tree has to be clean for a stamp to be used or written, because cargo checks the working
tree, not the pushed commit: with uncommitted changes the step runs and says why, and an untracked
file counts because it can hide a missing `git add`. The tree is probed again after the step, and
nothing is recorded if cargo changed it (a rewritten `Cargo.lock`, for example). A pass is only
written after cargo succeeded, per step, so a failed `test` does not erase the `clippy` pass that
the retry then skips.

Stamps live in `rocm-cli-prepush-passes` under the git common directory, so every worktree of a
clone shares them, nothing lands in the work tree and `cargo clean` does not erase them. Each write
drops stamps older than seven days and keeps at most 64. A write goes through a scratch file and a
rename, and removes the scratch file itself when the rename fails; a process killed mid-write
leaves its scratch file behind until a later write prunes it, once it is more than an hour old (a
younger one may belong to a concurrent writer). Any error locating, reading or verifying a
stamp means the step runs (git is run for an explicit directory with `GIT_DIR` and the other
repository-selecting variables removed, which git and prek export to a hook run from a linked
worktree); a stamp that does not match its key exactly, is dated in the future or is
unreadable is ignored (the step names it); a failed write is reported and never fails the hook.

The skip message says what a stamp does not cover: user-level cargo configuration, installed
tools, files git ignores (the one thing a clean `git status` cannot see) and flaky tests. Force
a run with `--rerun` or `ROCM_PRE_PUSH_RERUN=1` (the hook has no flags, so use the variable
there), or delete the directory the message names. `SKIP=<hook id>` still skips a hook outright,
and `verify-commits` is a separate hook that checks commit signatures on every push. A skip
proves that this tree passed these checks earlier, not that they ran during this push; for a
fresh run before relying on the result, use `--rerun`. A rerun replaces the recorded pass: it
drops this step's earlier pass before running, so if the rerun fails the next ordinary run runs
the step instead of skipping on the pass it was meant to double-check, and a successful rerun
records a fresh one. Other steps' and other selections' passes are left alone, and `--dry-run`
never touches a stamp.

Preview what a push would check without compiling (a dry run also says when a real run would skip):

```bash
cargo xtask pre-push-check test --dry-run --base origin/main
```

`--base` replaces the range's base; `clippy` and `clippy-e2e` take the same flags. The selection
logic is unit-tested in [prepush.rs](../xtask/src/prepush.rs); as dev tooling, with no change to
logic and the stamps are unit-tested in [prepush.rs](../xtask/src/prepush.rs) and
[prepush_stamp.rs](../xtask/src/prepush_stamp.rs); as dev tooling, with no change to
what the `rocm` binary does, it has no Gherkin scenario.

The smoke path is the cross-platform local no-fallback acceptance surface. It
Expand Down
100 changes: 94 additions & 6 deletions xtask/src/main.rs
Original file line number Diff line number Diff line change
Expand Up @@ -29,6 +29,7 @@ mod package;
mod paths;
mod powershell;
mod prepush;
mod prepush_stamp;
mod release_readiness;
mod report_mailbox;
mod report_rollup;
Expand All @@ -42,7 +43,7 @@ mod workflow_contract;
use std::path::PathBuf;
use std::process::ExitCode;

use anyhow::Result;
use anyhow::{Result, bail};
use clap::{Parser, Subcommand};

#[derive(Parser)]
Expand Down Expand Up @@ -118,6 +119,10 @@ pub(crate) enum Command {
/// cannot be determined, and prints why. It is skipped only when the
/// selection is known and has nothing for the step to check. CI always
/// checks the whole workspace.
///
/// A step that already passed on this exact tree (same cargo command,
/// toolchain and environment, clean working tree) is skipped, and a pass is
/// recorded after a green run; see `xtask/src/prepush_stamp.rs`.
PrePushCheck {
/// Which step to run.
#[arg(value_enum)]
Expand All @@ -129,6 +134,10 @@ pub(crate) enum Command {
/// Print the scope and the cargo command without running it.
#[arg(long)]
dry_run: bool,
/// Run the step even when this tree already passed it, and record the
/// new result. `ROCM_PRE_PUSH_RERUN=1` does the same, for the hook.
#[arg(long)]
rerun: bool,
},
/// Fail if any first-party crate has gained a normal/build dependency
/// edge outside the allowlist pinned in `xtask/src/crate_edges.rs`.
Expand Down Expand Up @@ -402,11 +411,7 @@ fn run() -> Result<()> {
} => signing::verify(public_key.as_deref(), &input, &signature)?,
Command::VerifyPinnedKeys => verify_pinned_keys::run()?,
Command::Affected { base } => affected::run(base)?,
Command::PrePushCheck {
check,
base,
dry_run,
} => prepush::run(check, base, dry_run)?,
command @ Command::PrePushCheck { .. } => run_pre_push_check(command, prepush::run)?,
Command::CheckCrateEdges => crate_edges::run()?,
Command::CheckModuleSize => module_size::run()?,
Command::CheckModuleSizeAdvisory => module_size::run_advisory()?,
Expand Down Expand Up @@ -487,6 +492,25 @@ fn run() -> Result<()> {
Ok(())
}

/// The `pre-push-check` arm of [`run`]: hand each argument to `run` as parsed.
/// `run` is a parameter so a test sees exactly what arrives, in particular that
/// `--rerun` is not dropped on the way to the stamp logic.
fn run_pre_push_check(
command: Command,
run: impl FnOnce(prepush::Check, Option<String>, bool, bool) -> Result<()>,
) -> Result<()> {
let Command::PrePushCheck {
check,
base,
dry_run,
rerun,
} = command
else {
bail!("not a pre-push-check command");
};
run(check, base, dry_run, rerun)
}

fn main() -> ExitCode {
match run() {
Ok(()) => ExitCode::SUCCESS,
Expand All @@ -496,3 +520,67 @@ fn main() -> ExitCode {
}
}
}

#[cfg(test)]
mod tests {
use clap::Parser;

use super::{Cli, Command};

fn rerun(args: &[&str]) -> bool {
let cli = Cli::try_parse_from(args).expect("the arguments parse");
let Command::PrePushCheck { rerun, .. } = cli.command else {
panic!("expected pre-push-check");
};
rerun
}

/// What the dispatch hands to `prepush::run` for these arguments: the real
/// clap parse, then the `pre-push-check` arm, with `run` recording its input.
fn handed_to_run(args: &[&str]) -> (String, Option<String>, bool, bool) {
let cli = Cli::try_parse_from(args).expect("the arguments parse");
let mut seen = None;
super::run_pre_push_check(cli.command, |check, base, dry_run, rerun| {
seen = Some((format!("{check:?}"), base, dry_run, rerun));
Ok(())
})
.expect("the dispatch succeeds");
seen.expect("the arm calls run")
}

#[test]
fn the_dispatch_hands_every_flag_to_run_unchanged() {
assert_eq!(
handed_to_run(&["xtask", "pre-push-check", "test"]),
("Test".to_string(), None, false, false)
);
assert_eq!(
handed_to_run(&[
"xtask",
"pre-push-check",
"clippy",
"--base",
"origin/main",
"--dry-run",
"--rerun",
]),
(
"Clippy".to_string(),
Some("origin/main".to_string()),
true,
true
)
);
// `--rerun` alone, and `--dry-run` alone, are not mixed up with each other.
assert!(handed_to_run(&["xtask", "pre-push-check", "test", "--rerun"]).3);
assert!(!handed_to_run(&["xtask", "pre-push-check", "test", "--rerun"]).2);
assert!(handed_to_run(&["xtask", "pre-push-check", "test", "--dry-run"]).2);
assert!(!handed_to_run(&["xtask", "pre-push-check", "test", "--dry-run"]).3);
}

#[test]
fn pre_push_check_takes_rerun_and_defaults_to_off() {
assert!(rerun(&["xtask", "pre-push-check", "test", "--rerun"]));
assert!(!rerun(&["xtask", "pre-push-check", "test"]));
}
}
Loading
Loading