From a7f859d03a9d91312bcfebc389b49623805a7be6 Mon Sep 17 00:00:00 2001 From: Roman Inflianskas Date: Wed, 2 Sep 2026 12:16:08 +0000 Subject: [PATCH 01/16] test(core): stop env-mutating tests racing on a shared process global Two tests in `fix.rs` both set the process-global `ROCM_PATH`, called `newest_rocm_install_dir()`, then restored it. Interleaved, each read the other's value: the one expecting a planted install got `""`, and the one expecting `""` got the planted install. This only ever failed on `windows-build-and-test` because that lane runs `cargo test` (all tests as threads in one process) while the Linux lanes run `cargo nextest` (a process per test, so the mutation cannot escape). Nothing about it is Windows-specific -- it is a property of the runner -- and it turned a required check red on branches that never touched the crate. Rather than serialize the mutation, remove it: `newest_rocm_install_dir` gets the same explicit-override seam the resolver already exposes as `discover_rocm_installs_in`, so the tests pass `$ROCM_PATH` in as an argument and never touch the environment. `engine_envs_dir` gets the same treatment -- it was not failing, since nothing else reads that key concurrently, but it was the identical unguarded pattern one added test away from the same flake. A new xtask contract test scans the workspace for unguarded env mutation in test code and fails the build with the offending file:line. It permits the two mechanisms already in the tree (`ScopedTestEnv`, `PROCESS_ENV_TEST_LOCK`), which is how the rest of the workspace had already handled this hazard. Verified: reverting the source fix makes the guard fail naming exactly the three sites; 40 stress runs of `RUST_TEST_THREADS=16 cargo test -p rocm-core --lib` are clean, where the race previously reproduced by run 8. Signed-off-by: Roman Inflianskas --- crates/rocm-core/src/fix.rs | 53 +++--- crates/rocm-core/src/lib.rs | 87 ++++++--- xtask/src/env_mutation_contract.rs | 271 +++++++++++++++++++++++++++++ xtask/src/main.rs | 1 + 4 files changed, 367 insertions(+), 45 deletions(-) create mode 100644 xtask/src/env_mutation_contract.rs diff --git a/crates/rocm-core/src/fix.rs b/crates/rocm-core/src/fix.rs index ce46bd2b8a..581b92a57e 100644 --- a/crates/rocm-core/src/fix.rs +++ b/crates/rocm-core/src/fix.rs @@ -1357,13 +1357,32 @@ fn ps_env_scope(var: &str, scope: &str) -> String { /// It now asks the same resolver as `examine`, which also means `$ROCM_PATH` is /// honoured here for the first time. fn newest_rocm_install_dir() -> String { - crate::discover_rocm_installs() + first_install_path(crate::discover_rocm_installs()) +} + +/// The best install's path, or empty when there is none. +fn first_install_path(installs: Vec) -> String { + installs .into_iter() .next() .map(|install| install.path.to_string_lossy().into_owned()) .unwrap_or_default() } +/// [`newest_rocm_install_dir`] against a caller-supplied `$ROCM_PATH` and +/// search roots, so a test can drive it without touching the process +/// environment. Same seam as [`crate::discover_rocm_installs_in`]. +#[cfg(test)] +fn newest_rocm_install_dir_in( + search_dirs: &[std::path::PathBuf], + env_override: Option<&std::path::Path>, +) -> String { + first_install_path(crate::discover_rocm_installs_on_host_in( + search_dirs, + env_override, + )) +} + #[cfg(test)] mod tests { use super::*; @@ -1402,7 +1421,6 @@ mod tests { } #[test] - #[allow(unsafe_code)] // std::env::set_var is unsafe in edition 2024 fn the_path_fix_finds_the_install_the_rest_of_the_cli_found() { // Discriminating on purpose: the scanner this replaces looked only in // two hardcoded `C:\Program Files` directories and ignored $ROCM_PATH @@ -1420,17 +1438,12 @@ mod tests { let install = root.join("rocm-6.10.0"); plant_install(&install); - let previous = std::env::var_os("ROCM_PATH"); - unsafe { - std::env::set_var("ROCM_PATH", &install); - } - let found = newest_rocm_install_dir(); - unsafe { - match previous { - Some(value) => std::env::set_var("ROCM_PATH", value), - None => std::env::remove_var("ROCM_PATH"), - } - } + // The override goes in as an argument rather than through + // `std::env::set_var`: the environment is process-global, so a sibling + // test mutating $ROCM_PATH between this set and its read used to make + // this assertion fail on whichever test lost the race. + let found = newest_rocm_install_dir_in(&[], Some(&install)); + std::fs::remove_dir_all(&root).ok(); assert_eq!( @@ -1441,7 +1454,6 @@ mod tests { } #[test] - #[allow(unsafe_code)] // std::env::set_var is unsafe in edition 2024 fn the_path_fix_reports_nothing_rather_than_a_directory_with_no_install_in_it() { // The old scan accepted any directory whose name started with a digit, // so an empty leftover could be put on PATH. The resolver requires a @@ -1457,17 +1469,8 @@ mod tests { let empty = root.join("6.10"); std::fs::create_dir_all(&empty).expect("create empty dir"); - let previous = std::env::var_os("ROCM_PATH"); - unsafe { - std::env::set_var("ROCM_PATH", &empty); - } - let found = newest_rocm_install_dir(); - unsafe { - match previous { - Some(value) => std::env::set_var("ROCM_PATH", value), - None => std::env::remove_var("ROCM_PATH"), - } - } + let found = newest_rocm_install_dir_in(&[], Some(&empty)); + std::fs::remove_dir_all(&root).ok(); assert!( diff --git a/crates/rocm-core/src/lib.rs b/crates/rocm-core/src/lib.rs index 19ee9b6a78..dc489193a7 100644 --- a/crates/rocm-core/src/lib.rs +++ b/crates/rocm-core/src/lib.rs @@ -1804,9 +1804,18 @@ impl AppPaths { } pub fn engine_envs_root(&self) -> PathBuf { - env_path_override("ROCM_CLI_ENGINE_ENVS_ROOT").map_or_else( + self.engine_envs_root_from(env_path_override("ROCM_CLI_ENGINE_ENVS_ROOT").as_deref()) + } + + /// [`Self::engine_envs_root`] against a caller-supplied override. + /// + /// Lets a test drive the override without `std::env::set_var`, which is + /// process-global and races other tests under a threaded runner. Same seam + /// as [`discover_rocm_installs_in_layout`]. + fn engine_envs_root_from(&self, override_root: Option<&Path>) -> PathBuf { + override_root.map_or_else( || self.data_dir.join("engines"), - |root| normalize_runtime_path_for_host(&root), + normalize_runtime_path_for_host, ) } @@ -1814,6 +1823,14 @@ impl AppPaths { self.engine_envs_root().join(engine).join("envs") } + /// [`Self::engine_envs_dir`] against a caller-supplied override. + #[cfg(test)] + fn engine_envs_dir_from(&self, engine: &str, override_root: Option<&Path>) -> PathBuf { + self.engine_envs_root_from(override_root) + .join(engine) + .join("envs") + } + pub fn engine_locks_dir(&self, engine: &str) -> PathBuf { self.engine_dir(engine).join("locks") } @@ -2840,21 +2857,44 @@ pub(crate) struct RocmInstall { pub(crate) version: Option, } +/// The search roots and layout this host's installs use. +fn host_rocm_search() -> (Vec, RocmLayout) { + let (dirs, layout) = if runtime_is_windows() { + (WINDOWS_ROCM_SEARCH_DIRS, RocmLayout::Children) + } else { + (LINUX_ROCM_SEARCH_DIRS, RocmLayout::Siblings) + }; + (dirs.iter().map(PathBuf::from).collect(), layout) +} + /// Every unmanaged ROCm install on this host, best candidate first. /// /// Supplies the platform's search roots, layout, and `$ROCM_PATH` to /// [`discover_rocm_installs_in_layout`]. pub(crate) fn discover_rocm_installs() -> Vec { let env_override = std::env::var_os("ROCM_PATH").map(PathBuf::from); - let (dirs, layout) = if runtime_is_windows() { - (WINDOWS_ROCM_SEARCH_DIRS, RocmLayout::Children) - } else { - (LINUX_ROCM_SEARCH_DIRS, RocmLayout::Siblings) - }; - let search_dirs: Vec = dirs.iter().map(PathBuf::from).collect(); + let (search_dirs, layout) = host_rocm_search(); discover_rocm_installs_in_layout(&search_dirs, env_override.as_deref(), layout) } +/// [`discover_rocm_installs`] with the host's `$ROCM_PATH` and search roots +/// supplied by the caller instead of read from the process. +/// +/// Reading `$ROCM_PATH` inside [`discover_rocm_installs`] is what forced its +/// callers' tests to mutate the process environment, and two of them racing on +/// that global is what made the Windows lane flake — that lane runs `cargo test` +/// (threads in one process) where the Linux lanes run `cargo nextest` (a process +/// per test), so only Windows could ever observe it. Passing the override in +/// keeps those tests hermetic. Same seam as [`discover_rocm_installs_in`], but +/// keeps the host's layout so the caller under test is the real one. +#[cfg(test)] +pub(crate) fn discover_rocm_installs_on_host_in( + search_dirs: &[PathBuf], + env_override: Option<&Path>, +) -> Vec { + discover_rocm_installs_in_layout(search_dirs, env_override, host_rocm_search().1) +} + /// [`discover_rocm_installs_in_layout`] for the Linux sibling layout. /// /// Production callers go through [`discover_rocm_installs`], which picks the @@ -12351,28 +12391,35 @@ Class Name: Display } #[test] - #[allow(unsafe_code)] // std::env::set_var is unsafe in edition 2024 fn engine_envs_dir_honors_dedicated_root_override() { let (root, paths) = temp_app_paths("engine-envs-root-override"); let override_root = root.join("runtime").join("engines"); - let previous = std::env::var_os("ROCM_CLI_ENGINE_ENVS_ROOT"); - unsafe { - std::env::set_var("ROCM_CLI_ENGINE_ENVS_ROOT", &override_root); - } + // Passed in rather than set via `std::env::set_var`: the environment is + // process-global, so mutating it here would race any concurrent test + // that reads the same key under a threaded runner. assert_eq!( - paths.engine_envs_dir("vllm"), + paths.engine_envs_dir_from("vllm", Some(&override_root)), normalize_runtime_path_for_host(&override_root) .join("vllm") .join("envs") ); - unsafe { - match previous { - Some(value) => std::env::set_var("ROCM_CLI_ENGINE_ENVS_ROOT", value), - None => std::env::remove_var("ROCM_CLI_ENGINE_ENVS_ROOT"), - } - } + fs::remove_dir_all(root).ok(); + } + + #[test] + fn engine_envs_dir_falls_back_to_the_data_dir_without_an_override() { + // The other half of the override contract: with nothing supplied the + // root is the data dir, which is what the unset-environment production + // path resolves to. + let (root, paths) = temp_app_paths("engine-envs-root-default"); + + assert_eq!( + paths.engine_envs_dir_from("vllm", None), + paths.data_dir.join("engines").join("vllm").join("envs") + ); + fs::remove_dir_all(root).ok(); } diff --git a/xtask/src/env_mutation_contract.rs b/xtask/src/env_mutation_contract.rs new file mode 100644 index 0000000000..31759b7b54 --- /dev/null +++ b/xtask/src/env_mutation_contract.rs @@ -0,0 +1,271 @@ +// Copyright © Advanced Micro Devices, Inc., or its affiliates. +// +// SPDX-License-Identifier: MIT + +//! Static contract test: a test that mutates the process environment must +//! serialize itself. +//! +//! Regression guard for EAI-8397. `std::env::set_var`/`remove_var` change state +//! shared by every thread in the process, so two tests touching the same key +//! race — one reads the other's value and fails an assertion that has nothing +//! to do with what it is testing. +//! +//! This is invisible on most of CI. `ci.yml` runs the Linux lanes under +//! `cargo nextest` (a process per test, so the mutation cannot escape), but +//! `windows-build-and-test` runs `cargo test --workspace --all-targets` — all +//! tests as threads in ONE process. So the Windows lane, a required check, was +//! the only place the race could fire, and it read as "your change broke +//! Windows" on branches that never touched the crate. Nothing about the bug is +//! Windows-specific; it is a property of the runner. +//! +//! The repo already had two ways of handling this — `ScopedTestEnv` in +//! `apps/rocm/src/main.rs` and `PROCESS_ENV_TEST_LOCK` in +//! `apps/rocm/src/therock.rs`, both of which take a process-wide lock — and the +//! `fix.rs` tests that flaked were simply the ones that skipped the discipline. +//! This guard makes the omission a build failure rather than an intermittent +//! red on a required check. +//! +//! Best is to not touch the environment at all: pass the value in through a +//! test seam, as `discover_rocm_installs_on_host_in` and +//! `newest_rocm_install_dir_in` do. Where a test must exercise the real +//! env-reading path, holding one of the shared locks above is the accepted +//! alternative and satisfies this guard. + +#[cfg(test)] +mod tests { + use std::path::{Path, PathBuf}; + + fn repo_root() -> PathBuf { + // CARGO_MANIFEST_DIR is the xtask/ crate dir; its parent is the repo + // root (same idiom as workflow_contract::repo_root). + Path::new(env!("CARGO_MANIFEST_DIR")) + .parent() + .expect("xtask crate has a parent directory") + .to_path_buf() + } + + /// Every `.rs` file in the repository. + /// + /// A whole-tree walk rather than a list of source directories, so a crate + /// added under a new top-level directory is covered without anyone + /// remembering to extend this. Two kinds of directory are skipped: + /// `target/`, which holds generated and vendored code we do not own, and + /// dot-directories, which include the `.claude/worktrees` checkouts of + /// other branches — scanning either would make the guard's verdict depend + /// on state outside the commit under test. + fn workspace_rust_sources() -> Vec { + let mut found = Vec::new(); + collect_rust_files(&repo_root(), &mut found); + assert!( + !found.is_empty(), + "found no Rust sources to scan -- the walk is broken, not the tree" + ); + found.sort(); + found + } + + fn collect_rust_files(dir: &Path, found: &mut Vec) { + let Ok(entries) = std::fs::read_dir(dir) else { + return; + }; + for entry in entries.flatten() { + let path = entry.path(); + if path.is_dir() { + let skip = path + .file_name() + .and_then(|name| name.to_str()) + .is_none_or(|name| name == "target" || name.starts_with('.')); + if skip { + continue; + } + collect_rust_files(&path, found); + } else if path.extension().is_some_and(|ext| ext == "rs") { + found.push(path); + } + } + } + + /// The mutating calls that need serializing. + const MUTATIONS: [&str; 2] = ["env::set_var", "env::remove_var"]; + + /// Markers that show a file already serializes its env mutations behind a + /// process-wide lock. Both are existing repo mechanisms; a file using + /// either has opted into the discipline this guard enforces. + const SERIALIZERS: [&str; 2] = ["ScopedTestEnv", "PROCESS_ENV_TEST_LOCK"]; + + /// Line numbers (1-based) inside a `#[cfg(test)]` module or a `#[test]` + /// function that call one of [`MUTATIONS`]. + /// + /// Brace-depth tracking rather than a whole-file substring match: production + /// code in the same file may legitimately set an environment variable (it + /// owns the process), and a file-level match could not tell the two apart. + fn env_mutations_in_test_code(text: &str) -> Vec<(usize, String)> { + let mut hits = Vec::new(); + let mut depth: usize = 0; + // Depth at which the enclosing test block opened, if we are inside one. + let mut test_block: Option = None; + let mut pending_test_attr = false; + + for (index, raw) in text.lines().enumerate() { + let line = raw.trim(); + let code = line.split("//").next().unwrap_or(line); + + if test_block.is_none() && (line.contains("#[cfg(test)]") || line.contains("#[test]")) { + pending_test_attr = true; + } + + if test_block.is_some() + && let Some(found) = MUTATIONS.iter().find(|needle| code.contains(*needle)) + { + hits.push((index + 1, (*found).to_owned())); + } + + let opens = code.matches('{').count(); + let closes = code.matches('}').count(); + if pending_test_attr { + if opens > 0 { + test_block.get_or_insert(depth); + pending_test_attr = false; + } else if code.trim_end().ends_with(';') { + // The attribute belonged to a braceless item -- a + // `#[cfg(test)] use ...;` import, say. Disarm, or the next + // brace anywhere in the file would be mistaken for the + // start of a test block and production code below it would + // be scanned as test code. + pending_test_attr = false; + } + } + // Saturating: a brace inside a string or macro can make a line look + // unbalanced, and the scan should degrade rather than panic. + depth = (depth + opens).saturating_sub(closes); + if let Some(open_depth) = test_block + && depth <= open_depth + { + test_block = None; + } + } + hits + } + + /// Whether `text` serializes its env mutations behind a process-wide lock. + /// + /// File-level on purpose: both existing mechanisms declare the lock once and + /// take it in each test that needs it, so the guard asks whether the file + /// has opted in rather than trying to prove each call site is covered. + fn serializes_env_mutations(text: &str) -> bool { + SERIALIZERS.iter().any(|marker| text.contains(marker)) + } + + #[test] + fn a_test_mutating_the_environment_serializes_itself() { + let root = repo_root(); + let mut offenders: Vec = Vec::new(); + + for path in workspace_rust_sources() { + let text = std::fs::read_to_string(&path) + .unwrap_or_else(|e| panic!("reading {}: {e}", path.display())); + if serializes_env_mutations(&text) { + continue; + } + let relative = path.strip_prefix(&root).unwrap_or(&path).display(); + for (line, call) in env_mutations_in_test_code(&text) { + offenders.push(format!("{relative}:{line}: {call}")); + } + } + + assert!( + offenders.is_empty(), + "a test that mutates the process environment must serialize itself \ + -- env is shared by every thread, so an unguarded mutation races \ + any test reading the same key and fails only under a threaded \ + runner (the Windows lane, a required check). Prefer passing the \ + value in through a seam (see `newest_rocm_install_dir_in`); \ + otherwise hold `ScopedTestEnv` or `PROCESS_ENV_TEST_LOCK`. \ + Offenders:\n{}", + offenders.join("\n") + ); + } + + /// A mutating call, assembled at runtime. + /// + /// Spelling `env::set_var` literally in a fixture below would make this + /// file's own test code match the scan it defines, so the fixtures build + /// the needle instead of containing it. + fn mutation_call(kind: &str) -> String { + format!("unsafe {{ std::env::{kind}(\"KEY\", \"value\") }}") + } + + #[test] + fn the_scanner_sees_a_mutation_inside_a_test_module() { + let call = mutation_call("set_var"); + let source = format!( + "fn production() {{\n {call}\n}}\n\ + #[cfg(test)]\nmod tests {{\n #[test]\n fn t() {{\n {call}\n }}\n}}\n" + ); + let hits = env_mutations_in_test_code(&source); + assert_eq!(hits.len(), 1, "expected exactly the in-test hit: {hits:?}"); + assert_eq!(hits[0].0, 8, "should flag the line inside the test module"); + } + + #[test] + fn the_scanner_ignores_production_mutations() { + // Production code owns the process and may legitimately set a variable; + // the hazard is specific to tests sharing one process under `cargo test`. + let source = format!("fn production() {{\n {}\n}}\n", mutation_call("set_var")); + assert!( + env_mutations_in_test_code(&source).is_empty(), + "a mutation outside test code is not an offense" + ); + } + + #[test] + fn the_scanner_stops_flagging_after_the_test_module_closes() { + let source = format!( + "#[cfg(test)]\nmod tests {{\n #[test]\n fn t() {{\n let _ = 1;\n }}\n}}\n\ + fn later_production() {{\n {}\n}}\n", + mutation_call("remove_var") + ); + assert!( + env_mutations_in_test_code(&source).is_empty(), + "the test module ended; the later mutation is production code" + ); + } + + #[test] + fn the_scanner_ignores_a_cfg_test_attribute_on_a_braceless_item() { + // `#[cfg(test)] use ...;` gates an import, not a block. Treating it as + // the opening of a test block would make every brace after it -- the + // whole rest of the file -- read as test code. Several files in this + // repo (crates/rocm-dash-tui/src/ui/dock.rs, apps/rocmd/src/lib.rs) do + // exactly this above production code that sets an env var. + let source = format!( + "#[cfg(test)]\nuse foo::Bar;\n\nfn production() {{\n {}\n}}\n", + mutation_call("set_var") + ); + assert!( + env_mutations_in_test_code(&source).is_empty(), + "the attribute gated an import; nothing below it is test code" + ); + } + + #[test] + fn a_serialized_file_is_exempt_but_an_unguarded_one_is_not() { + let unguarded = format!( + "#[cfg(test)]\nmod tests {{\n #[test]\n fn t() {{\n {}\n }}\n}}\n", + mutation_call("set_var") + ); + assert!( + !serializes_env_mutations(&unguarded), + "nothing in this source takes a process-wide lock" + ); + + let guarded = unguarded.replace( + " #[test]", + " static PROCESS_ENV_TEST_LOCK: Mutex<()> = Mutex::new(());\n #[test]", + ); + assert!( + serializes_env_mutations(&guarded), + "declaring the shared lock opts the file into the discipline" + ); + } +} diff --git a/xtask/src/main.rs b/xtask/src/main.rs index 5b5fbeb647..47483d6f79 100644 --- a/xtask/src/main.rs +++ b/xtask/src/main.rs @@ -16,6 +16,7 @@ mod demos; mod e2e; mod e2e_prewarm; mod e2e_report; +mod env_mutation_contract; mod manifest; mod package; mod paths; From 97406e310f0ea2051150aec0e2356e0b6b239e0d Mon Sep 17 00:00:00 2001 From: Roman Inflianskas Date: Thu, 17 Sep 2026 13:46:00 +0000 Subject: [PATCH 02/16] test(core): restore the env-read coverage the seam removed Deleting both production lookups -- `std::env::var_os("ROCM_PATH")` and `env_path_override("ROCM_CLI_ENGINE_ENVS_ROOT")` -- left the whole rocm-core suite green at 394 passed, 0 failed. The seam tests drive `newest_rocm_install_dir_in` and `engine_envs_dir_from`, which is what makes them hermetic, and is also why they cannot see the wiring they bypass. The regression `the_path_fix_finds_the_install_the_rest_of_the_cli_found` exists to prevent was reachable again. Keeps the seams, and adds one lock-serialized test per key that drives the real entry point against a real variable -- the escape hatch the guard's own module doc advertises for exactly this case. With them, that same mutation fails both. `fix.rs` reaches this from the other side: `main` fixed the original race with `PROCESS_ENV_TEST_LOCK` while this branch was open, so the merged tests held a lock they no longer needed. The seam tests drop it; the new one takes it, which is what it is for. `lib.rs` had no lock, so it gains `ENGINE_ENVS_ENV_TEST_LOCK`, named for the suffix rule rather than added to a list. Also says on `engine_envs_root` that it is the read side of a write-only contract, so the next reader does not take `pub` as evidence of a caller -- `unreachable_pub` is off workspace-wide, so nothing warns. Signed-off-by: Roman Inflianskas --- crates/rocm-core/src/fix.rs | 46 ++- crates/rocm-core/src/lib.rs | 51 +++ xtask/src/env_mutation_contract.rs | 498 ++++++++++++++++++++++++----- 3 files changed, 510 insertions(+), 85 deletions(-) diff --git a/crates/rocm-core/src/fix.rs b/crates/rocm-core/src/fix.rs index 581b92a57e..69bb14e5a7 100644 --- a/crates/rocm-core/src/fix.rs +++ b/crates/rocm-core/src/fix.rs @@ -1427,9 +1427,6 @@ mod tests { // outright, so it returned nothing here no matter what was planted. // Going through the shared resolver is what makes this pass -- and is // what stops fix-6-path putting 6.2 on PATH when 6.10 is installed. - let _guard = PROCESS_ENV_TEST_LOCK - .lock() - .unwrap_or_else(std::sync::PoisonError::into_inner); let root = std::env::temp_dir().join(format!( "rocm-fix-path-resolver-{}-{:?}", std::process::id(), @@ -1453,14 +1450,51 @@ mod tests { ); } + /// The seam tests above deliberately bypass `$ROCM_PATH`, so on their own + /// the production read could be deleted and the suite would stay green. + /// This one drives the real entry point against a real variable. + /// + /// It takes the lock rather than a seam because exercising the env read IS + /// the point — the escape hatch the contract guard advertises for exactly + /// this case. + #[allow(unsafe_code)] // std::env::set_var is unsafe in edition 2024 + #[test] + fn the_path_fix_reads_rocm_path_from_the_environment() { + let _guard = PROCESS_ENV_TEST_LOCK + .lock() + .unwrap_or_else(std::sync::PoisonError::into_inner); + let root = std::env::temp_dir().join(format!( + "rocm-fix-path-env-{}-{:?}", + std::process::id(), + std::thread::current().id() + )); + let install = root.join("rocm-6.10.0"); + plant_install(&install); + + let previous = std::env::var_os("ROCM_PATH"); + // SAFETY: the lock above serializes every test in this process that + // touches this key, and the value is restored before it is released. + unsafe { std::env::set_var("ROCM_PATH", &install) }; + let found = newest_rocm_install_dir(); + match &previous { + Some(value) => unsafe { std::env::set_var("ROCM_PATH", value) }, + None => unsafe { std::env::remove_var("ROCM_PATH") }, + } + + std::fs::remove_dir_all(&root).ok(); + + assert_eq!( + found, + install.to_string_lossy(), + "fix-6-path must reach $ROCM_PATH through the shared resolver" + ); + } + #[test] fn the_path_fix_reports_nothing_rather_than_a_directory_with_no_install_in_it() { // The old scan accepted any directory whose name started with a digit, // so an empty leftover could be put on PATH. The resolver requires a // marker. - let _guard = PROCESS_ENV_TEST_LOCK - .lock() - .unwrap_or_else(std::sync::PoisonError::into_inner); let root = std::env::temp_dir().join(format!( "rocm-fix-path-empty-{}-{:?}", std::process::id(), diff --git a/crates/rocm-core/src/lib.rs b/crates/rocm-core/src/lib.rs index dc489193a7..c934b0c0d7 100644 --- a/crates/rocm-core/src/lib.rs +++ b/crates/rocm-core/src/lib.rs @@ -1803,6 +1803,17 @@ impl AppPaths { self.engine_dir(engine).join("logs") } + /// Where engine virtualenvs live, honouring `ROCM_CLI_ENGINE_ENVS_ROOT`. + /// + /// Read-side of a write-only contract at present: `apps/rocm` exports this + /// key into the children it spawns, and this is the only code that reads it + /// back, so no in-tree production path reaches here today. That predates + /// the seam below and is deliberate — the key exists for an engine process + /// to honour. Being `pub` says nothing either way: `unreachable_pub` is + /// switched off workspace-wide (see the root `Cargo.toml`), so nothing warns + /// about an unused one. Delete this and the key together if the contract is + /// dropped; `engine_envs_dir_reads_its_root_from_the_environment` is what + /// keeps the lookup honest meanwhile. pub fn engine_envs_root(&self) -> PathBuf { self.engine_envs_root_from(env_path_override("ROCM_CLI_ENGINE_ENVS_ROOT").as_deref()) } @@ -12408,6 +12419,46 @@ Class Name: Display fs::remove_dir_all(root).ok(); } + /// Serializes tests that replace a process-global env var while they run. + /// + /// Named `*_TEST_LOCK` so the env-mutation contract guard recognises the + /// discipline by suffix rather than by a hardcoded list of lock names. + static ENGINE_ENVS_ENV_TEST_LOCK: std::sync::Mutex<()> = std::sync::Mutex::new(()); + + /// The two tests around this one drive the seam, which deliberately does + /// not read the environment — so on their own the production lookup, and + /// the key it names, could both be deleted without failing anything. This + /// drives `engine_envs_dir` itself against a real variable. + #[allow(unsafe_code)] // std::env::set_var is unsafe in edition 2024 + #[test] + fn engine_envs_dir_reads_its_root_from_the_environment() { + let _guard = ENGINE_ENVS_ENV_TEST_LOCK + .lock() + .unwrap_or_else(std::sync::PoisonError::into_inner); + let (root, paths) = temp_app_paths("engine-envs-root-env"); + let override_root = root.join("runtime").join("engines"); + + let previous = std::env::var_os("ROCM_CLI_ENGINE_ENVS_ROOT"); + // SAFETY: the lock above serializes every test in this process that + // touches this key, and the value is restored before it is released. + unsafe { std::env::set_var("ROCM_CLI_ENGINE_ENVS_ROOT", &override_root) }; + let resolved = paths.engine_envs_dir("vllm"); + match &previous { + Some(value) => unsafe { std::env::set_var("ROCM_CLI_ENGINE_ENVS_ROOT", value) }, + None => unsafe { std::env::remove_var("ROCM_CLI_ENGINE_ENVS_ROOT") }, + } + + assert_eq!( + resolved, + normalize_runtime_path_for_host(&override_root) + .join("vllm") + .join("envs"), + "engine_envs_dir must reach $ROCM_CLI_ENGINE_ENVS_ROOT" + ); + + fs::remove_dir_all(root).ok(); + } + #[test] fn engine_envs_dir_falls_back_to_the_data_dir_without_an_override() { // The other half of the override contract: with nothing supplied the diff --git a/xtask/src/env_mutation_contract.rs b/xtask/src/env_mutation_contract.rs index 31759b7b54..89da0361f3 100644 --- a/xtask/src/env_mutation_contract.rs +++ b/xtask/src/env_mutation_contract.rs @@ -88,72 +88,286 @@ mod tests { /// The mutating calls that need serializing. const MUTATIONS: [&str; 2] = ["env::set_var", "env::remove_var"]; - /// Markers that show a file already serializes its env mutations behind a - /// process-wide lock. Both are existing repo mechanisms; a file using - /// either has opted into the discipline this guard enforces. - const SERIALIZERS: [&str; 2] = ["ScopedTestEnv", "PROCESS_ENV_TEST_LOCK"]; + /// Named helpers that serialize env mutation for their whole scope. + /// + /// Anything ending `_TEST_LOCK` counts too, and is matched by suffix rather + /// than listed — see [`serializes`]. A fixed list of lock NAMES went stale + /// within days of this guard being written: `main` added + /// `UPDATE_CHECK_ENV_TEST_LOCK` and the guard then flagged correctly + /// disciplined code and told its author to rename the lock. + const NAMED_SERIALIZERS: [&str; 2] = ["ScopedTestEnv", "ScopedEnvVar"]; + + /// Whether `text` takes one of the process-wide serializers. + /// + /// The suffix rule recognises the DISCIPLINE rather than a specific lock, so + /// a new `*_TEST_LOCK` is covered the day it is declared. + fn serializes(text: &str) -> bool { + NAMED_SERIALIZERS.iter().any(|name| text.contains(name)) + || text + .split(|c: char| !(c.is_ascii_alphanumeric() || c == '_')) + .any(|word| word.ends_with("_TEST_LOCK")) + } - /// Line numbers (1-based) inside a `#[cfg(test)]` module or a `#[test]` - /// function that call one of [`MUTATIONS`]. + /// Replace the CONTENTS of string literals, char literals and comments with + /// spaces, preserving line structure and everything outside them. + /// + /// The scan below counts braces and looks for call text, and both are + /// wrong if a literal can contribute either. Two real files in this repo + /// break the naive version: + /// + /// * `engines/lemonade/src/lib.rs` contains + /// `ensure_cached_archive("test://archive", ..., |_, destination| {`. + /// Truncating the line at `//` throws away the closure's opening brace, + /// so the enclosing test module reads as closed hundreds of lines early + /// and every mutation after it becomes invisible. + /// * `tests/e2e-cucumber/src/mock_server.rs` contains format strings such + /// as `vllm:num_requests_running{{model=...}}`. Those braces inflate the + /// depth, which drags PRODUCTION code into the scanned region and makes + /// the guard fail a build for a mutation it should not be watching. /// - /// Brace-depth tracking rather than a whole-file substring match: production - /// code in the same file may legitimately set an environment variable (it - /// owns the process), and a file-level match could not tell the two apart. - fn env_mutations_in_test_code(text: &str) -> Vec<(usize, String)> { - let mut hits = Vec::new(); + /// Both directions are silent, which is the one failure mode a permanent + /// guard must not have, so literals are tokenized rather than approximated. + fn strip_literals_and_comments(text: &str) -> String { + #[derive(Clone, Copy)] + enum State { + Code, + LineComment, + BlockComment(usize), + Str, + RawStr(usize), + Char, + } + + let mut out = String::with_capacity(text.len()); + let mut state = State::Code; + let chars: Vec = text.chars().collect(); + let mut i = 0; + while i < chars.len() { + let c = chars[i]; + let next = chars.get(i + 1).copied(); + match state { + State::Code => { + // A raw string opener: `r"`, `r#"`, `br##"` and so on. Checked + // before the plain-string case so the hashes are counted. + if (c == 'r' || c == 'b') + && let Some((hashes, consumed)) = raw_string_opener(&chars, i) + { + out.extend(std::iter::repeat_n(' ', consumed)); + state = State::RawStr(hashes); + i += consumed; + continue; + } + if c == '/' && next == Some('/') { + state = State::LineComment; + out.push_str(" "); + i += 2; + continue; + } + if c == '/' && next == Some('*') { + state = State::BlockComment(1); + out.push_str(" "); + i += 2; + continue; + } + if c == '"' { + state = State::Str; + out.push(' '); + i += 1; + continue; + } + // A lifetime (`'a`) is not a char literal. A char literal is + // `'x'` or `'\n'`, so require a closing quote nearby. + if c == '\'' && is_char_literal(&chars, i) { + state = State::Char; + out.push(' '); + i += 1; + continue; + } + out.push(c); + i += 1; + } + State::LineComment => { + if c == '\n' { + state = State::Code; + out.push('\n'); + } else { + out.push(' '); + } + i += 1; + } + State::BlockComment(depth) => { + if c == '*' && next == Some('/') { + state = if depth == 1 { + State::Code + } else { + State::BlockComment(depth - 1) + }; + out.push_str(" "); + i += 2; + continue; + } + if c == '/' && next == Some('*') { + state = State::BlockComment(depth + 1); + out.push_str(" "); + i += 2; + continue; + } + out.push(if c == '\n' { '\n' } else { ' ' }); + i += 1; + } + State::Str => { + if c == '\\' { + out.push_str(" "); + i += 2; + continue; + } + if c == '"' { + state = State::Code; + } + out.push(if c == '\n' { '\n' } else { ' ' }); + i += 1; + } + State::RawStr(hashes) => { + if c == '"' && closing_hashes(&chars, i + 1) >= hashes { + state = State::Code; + out.extend(std::iter::repeat_n(' ', hashes + 1)); + i += hashes + 1; + continue; + } + out.push(if c == '\n' { '\n' } else { ' ' }); + i += 1; + } + State::Char => { + if c == '\\' { + out.push_str(" "); + i += 2; + continue; + } + if c == '\'' { + state = State::Code; + } + out.push(' '); + i += 1; + } + } + } + out + } + + /// `Some((hash_count, chars_consumed))` when a raw-string literal opens at + /// `i` (`r"`, `r#"`, `br##"`, ...). + fn raw_string_opener(chars: &[char], i: usize) -> Option<(usize, usize)> { + let mut j = i; + if chars.get(j) == Some(&'b') { + j += 1; + } + if chars.get(j) != Some(&'r') { + return None; + } + j += 1; + let hash_start = j; + while chars.get(j) == Some(&'#') { + j += 1; + } + if chars.get(j) == Some(&'"') { + Some((j - hash_start, j - i + 1)) + } else { + None + } + } + + fn closing_hashes(chars: &[char], mut i: usize) -> usize { + let start = i; + while chars.get(i) == Some(&'#') { + i += 1; + } + i - start + } + + /// Distinguish `'x'` from a lifetime such as `'a` in `&'a str`. + fn is_char_literal(chars: &[char], i: usize) -> bool { + match chars.get(i + 1) { + // `'\n'`, `'\''`, `'\\'` -- always a literal. + Some('\\') => true, + Some(_) => chars.get(i + 2) == Some(&'\''), + None => false, + } + } + + /// A `#[test]` function that mutates the environment. + #[derive(Debug, PartialEq, Eq)] + struct Offense { + line: usize, + call: String, + } + + /// Mutations inside a `#[test]` function that does not serialize itself. + /// + /// Scoped to the test FUNCTION, not the file. The file-level rule this + /// replaces asked only whether a marker appeared anywhere in the text, so a + /// comment reading "maybe migrate this to ScopedTestEnv one day" exempted + /// every test in the file — and `apps/rocm/src/main.rs` (379 tests) and + /// `apps/rocm/src/therock.rs` (73) were both wholly exempt for that reason, + /// which is precisely where the next unguarded test is most likely to land. + /// + /// Known limit: a `#[test]` that delegates its mutation to an unguarded + /// helper is not caught, because the helper's body is a different scope. + /// Mutations outside `#[test]` functions are deliberately not flagged — + /// that is production code, and test-support types such as `ScopedTestEnv` + /// whose whole job is to perform the mutation on a test's behalf. + fn env_mutations_in_unserialized_tests(text: &str) -> Vec { + let stripped = strip_literals_and_comments(text); + let mut offenses = Vec::new(); let mut depth: usize = 0; - // Depth at which the enclosing test block opened, if we are inside one. - let mut test_block: Option = None; let mut pending_test_attr = false; + // (depth at which the test fn body opened, body text so far, hits so far) + let mut current: Option<(usize, String, Vec)> = None; - for (index, raw) in text.lines().enumerate() { - let line = raw.trim(); - let code = line.split("//").next().unwrap_or(line); + for (index, line) in stripped.lines().enumerate() { + let code = line.trim(); - if test_block.is_none() && (line.contains("#[cfg(test)]") || line.contains("#[test]")) { + if current.is_none() && code.contains("#[test]") { pending_test_attr = true; } - if test_block.is_some() - && let Some(found) = MUTATIONS.iter().find(|needle| code.contains(*needle)) - { - hits.push((index + 1, (*found).to_owned())); + if let Some((_, body, hits)) = current.as_mut() { + body.push_str(line); + body.push('\n'); + if let Some(found) = MUTATIONS.iter().find(|needle| code.contains(*needle)) { + hits.push(Offense { + line: index + 1, + call: (*found).to_owned(), + }); + } } let opens = code.matches('{').count(); let closes = code.matches('}').count(); - if pending_test_attr { - if opens > 0 { - test_block.get_or_insert(depth); - pending_test_attr = false; - } else if code.trim_end().ends_with(';') { - // The attribute belonged to a braceless item -- a - // `#[cfg(test)] use ...;` import, say. Disarm, or the next - // brace anywhere in the file would be mistaken for the - // start of a test block and production code below it would - // be scanned as test code. - pending_test_attr = false; - } + + if pending_test_attr && opens > 0 { + pending_test_attr = false; + current = Some((depth, String::new(), Vec::new())); + } else if pending_test_attr && code.ends_with(';') { + // The attribute gated a braceless item; disarm so the next brace + // anywhere in the file is not mistaken for a test body. + pending_test_attr = false; } - // Saturating: a brace inside a string or macro can make a line look - // unbalanced, and the scan should degrade rather than panic. + depth = (depth + opens).saturating_sub(closes); - if let Some(open_depth) = test_block - && depth <= open_depth + + if let Some((open_depth, body, hits)) = current.as_ref() + && depth <= *open_depth { - test_block = None; + if !serializes(body) { + offenses.extend(hits.iter().map(|hit| Offense { + line: hit.line, + call: hit.call.clone(), + })); + } + current = None; } } - hits - } - - /// Whether `text` serializes its env mutations behind a process-wide lock. - /// - /// File-level on purpose: both existing mechanisms declare the lock once and - /// take it in each test that needs it, so the guard asks whether the file - /// has opted in rather than trying to prove each call site is covered. - fn serializes_env_mutations(text: &str) -> bool { - SERIALIZERS.iter().any(|marker| text.contains(marker)) + offenses } #[test] @@ -164,12 +378,9 @@ mod tests { for path in workspace_rust_sources() { let text = std::fs::read_to_string(&path) .unwrap_or_else(|e| panic!("reading {}: {e}", path.display())); - if serializes_env_mutations(&text) { - continue; - } let relative = path.strip_prefix(&root).unwrap_or(&path).display(); - for (line, call) in env_mutations_in_test_code(&text) { - offenders.push(format!("{relative}:{line}: {call}")); + for offense in env_mutations_in_unserialized_tests(&text) { + offenders.push(format!("{relative}:{}: {}", offense.line, offense.call)); } } @@ -180,31 +391,39 @@ mod tests { any test reading the same key and fails only under a threaded \ runner (the Windows lane, a required check). Prefer passing the \ value in through a seam (see `newest_rocm_install_dir_in`); \ - otherwise hold `ScopedTestEnv` or `PROCESS_ENV_TEST_LOCK`. \ - Offenders:\n{}", + otherwise take `ScopedTestEnv` or any `*_TEST_LOCK` in the test \ + body. Offenders:\n{}", offenders.join("\n") ); } /// A mutating call, assembled at runtime. /// - /// Spelling `env::set_var` literally in a fixture below would make this - /// file's own test code match the scan it defines, so the fixtures build - /// the needle instead of containing it. + /// Spelling `env::set_var` literally in a fixture would make this file's own + /// test code match the scan it defines, so the fixtures build the needle + /// instead of containing it. The `MUTATIONS` const above still spells them + /// literally; that is fine now the exemption is per-test-function rather + /// than per-file, because the const is not inside a `#[test]` body. fn mutation_call(kind: &str) -> String { format!("unsafe {{ std::env::{kind}(\"KEY\", \"value\") }}") } + fn unguarded_test(body: &str) -> String { + format!( + "#[cfg(test)]\nmod tests {{\n #[test]\n fn t() {{\n {body}\n }}\n}}\n" + ) + } + #[test] - fn the_scanner_sees_a_mutation_inside_a_test_module() { + fn the_scanner_sees_a_mutation_inside_a_test() { let call = mutation_call("set_var"); let source = format!( "fn production() {{\n {call}\n}}\n\ #[cfg(test)]\nmod tests {{\n #[test]\n fn t() {{\n {call}\n }}\n}}\n" ); - let hits = env_mutations_in_test_code(&source); + let hits = env_mutations_in_unserialized_tests(&source); assert_eq!(hits.len(), 1, "expected exactly the in-test hit: {hits:?}"); - assert_eq!(hits[0].0, 8, "should flag the line inside the test module"); + assert_eq!(hits[0].line, 8, "should flag the line inside the test"); } #[test] @@ -213,21 +432,21 @@ mod tests { // the hazard is specific to tests sharing one process under `cargo test`. let source = format!("fn production() {{\n {}\n}}\n", mutation_call("set_var")); assert!( - env_mutations_in_test_code(&source).is_empty(), + env_mutations_in_unserialized_tests(&source).is_empty(), "a mutation outside test code is not an offense" ); } #[test] - fn the_scanner_stops_flagging_after_the_test_module_closes() { + fn the_scanner_stops_flagging_after_the_test_closes() { let source = format!( "#[cfg(test)]\nmod tests {{\n #[test]\n fn t() {{\n let _ = 1;\n }}\n}}\n\ fn later_production() {{\n {}\n}}\n", mutation_call("remove_var") ); assert!( - env_mutations_in_test_code(&source).is_empty(), - "the test module ended; the later mutation is production code" + env_mutations_in_unserialized_tests(&source).is_empty(), + "the test ended; the later mutation is production code" ); } @@ -235,37 +454,158 @@ mod tests { fn the_scanner_ignores_a_cfg_test_attribute_on_a_braceless_item() { // `#[cfg(test)] use ...;` gates an import, not a block. Treating it as // the opening of a test block would make every brace after it -- the - // whole rest of the file -- read as test code. Several files in this - // repo (crates/rocm-dash-tui/src/ui/dock.rs, apps/rocmd/src/lib.rs) do - // exactly this above production code that sets an env var. + // whole rest of the file -- read as test code. let source = format!( "#[cfg(test)]\nuse foo::Bar;\n\nfn production() {{\n {}\n}}\n", mutation_call("set_var") ); assert!( - env_mutations_in_test_code(&source).is_empty(), + env_mutations_in_unserialized_tests(&source).is_empty(), "the attribute gated an import; nothing below it is test code" ); } #[test] - fn a_serialized_file_is_exempt_but_an_unguarded_one_is_not() { - let unguarded = format!( - "#[cfg(test)]\nmod tests {{\n #[test]\n fn t() {{\n {}\n }}\n}}\n", + fn a_serialized_test_is_exempt_but_an_unguarded_one_is_not() { + let unguarded = unguarded_test(&mutation_call("set_var")); + assert_eq!( + env_mutations_in_unserialized_tests(&unguarded).len(), + 1, + "nothing in this test takes a process-wide lock" + ); + + for marker in [ + "let _env = ScopedTestEnv::new();", + "let _env = ScopedEnvVar::new(\"K\");", + "let _guard = PROCESS_ENV_TEST_LOCK.lock().unwrap();", + // The suffix rule: a lock this guard has never heard of. + "let _guard = SOME_BRAND_NEW_TEST_LOCK.lock().unwrap();", + ] { + let guarded = + unguarded_test(&format!("{marker}\n {}", mutation_call("set_var"))); + assert!( + env_mutations_in_unserialized_tests(&guarded).is_empty(), + "taking {marker} should satisfy the guard" + ); + } + } + + /// The exemption must not be file-wide. + /// + /// Under the previous rule this whole file was exempt because SOME test in + /// it took a lock -- or merely because a comment named one. That is how + /// `apps/rocm/src/main.rs` (379 tests) and `apps/rocm/src/therock.rs` (73) + /// ended up with no line-level enforcement at all. + #[test] + fn one_serialized_test_does_not_exempt_its_neighbour() { + let call = mutation_call("set_var"); + let source = format!( + "#[cfg(test)]\nmod tests {{\n\ + \x20 #[test]\n fn guarded() {{\n let _env = ScopedTestEnv::new();\n {call}\n }}\n\ + \x20 #[test]\n fn unguarded() {{\n {call}\n }}\n}}\n" + ); + let hits = env_mutations_in_unserialized_tests(&source); + assert_eq!( + hits.len(), + 1, + "only the unguarded test is an offense: {hits:?}" + ); + assert_eq!(hits[0].line, 10); + } + + #[test] + fn a_comment_naming_a_serializer_does_not_exempt_anything() { + let source = unguarded_test(&format!( + "// TODO: maybe migrate this to ScopedTestEnv one day\n {}", + mutation_call("set_var") + )); + assert_eq!( + env_mutations_in_unserialized_tests(&source).len(), + 1, + "a comment is not a lock" + ); + } + + /// A `}}` inside a string literal used to close the enclosing test early, + /// making every later mutation invisible. Real instance: + /// `tests/e2e-cucumber/src/mock_server.rs` builds Prometheus format strings + /// containing `{{...}}`. + #[test] + fn a_brace_inside_a_string_literal_does_not_close_the_test() { + let source = unguarded_test(&format!( + "let _s = \"}}}}\";\n {}", + mutation_call("set_var") + )); + assert_eq!( + env_mutations_in_unserialized_tests(&source).len(), + 1, + "a brace inside a literal must not end the test block" + ); + } + + /// A `//` inside a string literal used to truncate the line, discarding any + /// brace after it. Real instance: `engines/lemonade/src/lib.rs` passes + /// `"test://archive"` on a line that also opens a closure. + #[test] + fn a_double_slash_inside_a_string_literal_does_not_truncate_the_line() { + let call = mutation_call("set_var"); + let source = format!( + "#[cfg(test)]\nmod tests {{\n #[test]\n fn t() {{\n\ + \x20 helper(\"test://archive\", |_| {{\n let _ = 1;\n }});\n\ + \x20 {call}\n }}\n}}\n" + ); + let hits = env_mutations_in_unserialized_tests(&source); + assert_eq!( + hits.len(), + 1, + "the closure's brace was inside a literal-bearing line: {hits:?}" + ); + } + + /// The mirror failure: an unbalanced `{{` in a literal inflates the depth and + /// keeps the scan inside a test long after it ended, so PRODUCTION code + /// downstream gets flagged and the build fails for nothing. + #[test] + fn an_opening_brace_in_a_literal_does_not_drag_in_production_code() { + let source = format!( + "#[cfg(test)]\nmod tests {{\n #[test]\n fn t() {{\n let _s = \"{{\";\n }}\n}}\n\ + fn later_production() {{\n {}\n}}\n", mutation_call("set_var") ); assert!( - !serializes_env_mutations(&unguarded), - "nothing in this source takes a process-wide lock" + env_mutations_in_unserialized_tests(&source).is_empty(), + "an opening brace inside a literal must not extend the test block" ); + } - let guarded = unguarded.replace( - " #[test]", - " static PROCESS_ENV_TEST_LOCK: Mutex<()> = Mutex::new(());\n #[test]", + #[test] + fn literals_and_comments_are_stripped_but_line_numbers_survive() { + let source = + "let a = \"}}}}\"; // }}\nlet b = r#\"raw } {\"#;\n/* block } */\nlet c = 1;\n"; + let stripped = strip_literals_and_comments(source); + assert_eq!( + stripped.lines().count(), + source.lines().count(), + "line structure must survive: {stripped:?}" + ); + assert!( + !stripped.contains('}') && !stripped.contains('{'), + "every brace here is inside a literal or comment: {stripped:?}" ); assert!( - serializes_env_mutations(&guarded), - "declaring the shared lock opts the file into the discipline" + stripped.contains("let c = 1;"), + "code must survive: {stripped:?}" + ); + } + + #[test] + fn a_lifetime_is_not_mistaken_for_a_char_literal() { + // `'a` opens no literal; treating it as one would swallow the rest of + // the line, including any brace or call on it. + let stripped = strip_literals_and_comments("fn f<'a>(x: &'a str) -> &'a str { x }\n"); + assert!( + stripped.contains('{') && stripped.contains('}'), + "{stripped:?}" ); } } From 0e243138394b851c0907ea9047dd13f41f3fe68a Mon Sep 17 00:00:00 2001 From: Roman Inflianskas Date: Thu, 17 Sep 2026 13:52:41 +0000 Subject: [PATCH 03/16] docs(testing): write down the env-mutation rule the build enforces Grepping docs/, AGENTS.md, CONTRIBUTING.md and README.md for `set_var`, `ScopedTestEnv` or `PROCESS_ENV_TEST_LOCK` returned nothing, so someone who trips this guard got a build failure citing a convention stated only inside a test file they have never opened -- while docs/testing.md told them to run `cargo test --workspace --all-targets`, the exact threaded harness that makes the race possible, with no warning. Adds the section, the worked example, and the limit the scan cannot see (a test delegating its mutation to an unguarded helper). Two claims narrowed to what CI actually does. "the Linux lanes run nextest" is too strong: `coverage` (cargo llvm-cov, no --nextest) and `e2e` (cargo test -p e2e-cucumber --lib) are threaded single-process harnesses on ubuntu-latest too. They happen not to reach the crates that raced, which is luck, not design. Also passes a planted search root alongside the override in the seam test. It asserted that $ROCM_PATH outranks the hardcoded search roots while passing `&[]`, so the search loop never ran and the ordering held vacuously; it now fails if the override is ignored. Signed-off-by: Roman Inflianskas --- crates/rocm-core/src/fix.rs | 14 +++++++-- crates/rocm-core/src/lib.rs | 7 +++-- docs/testing.md | 48 ++++++++++++++++++++++++++++++ xtask/src/env_mutation_contract.rs | 16 ++++++---- 4 files changed, 75 insertions(+), 10 deletions(-) diff --git a/crates/rocm-core/src/fix.rs b/crates/rocm-core/src/fix.rs index 69bb14e5a7..c6b33e3443 100644 --- a/crates/rocm-core/src/fix.rs +++ b/crates/rocm-core/src/fix.rs @@ -1435,18 +1435,28 @@ mod tests { let install = root.join("rocm-6.10.0"); plant_install(&install); + // A second, older install reachable through the hardcoded search roots. + // Passing it alongside the override is what exercises the ordering the + // assertion below claims: with `&[]` the search loop never runs, so + // "the override outranks the search roots" would hold vacuously. + let searched = root.join("search"); + let older = searched.join("rocm-6.2.0"); + plant_install(&older); + // The override goes in as an argument rather than through // `std::env::set_var`: the environment is process-global, so a sibling // test mutating $ROCM_PATH between this set and its read used to make // this assertion fail on whichever test lost the race. - let found = newest_rocm_install_dir_in(&[], Some(&install)); + // `..._reads_rocm_path_from_the_environment` covers the real read. + let found = newest_rocm_install_dir_in(std::slice::from_ref(&searched), Some(&install)); std::fs::remove_dir_all(&root).ok(); assert_eq!( found, install.to_string_lossy(), - "fix-6-path must resolve installs the same way examine does" + "fix-6-path must resolve installs the same way examine does, and \ + $ROCM_PATH must outrank the hardcoded search roots" ); } diff --git a/crates/rocm-core/src/lib.rs b/crates/rocm-core/src/lib.rs index c934b0c0d7..192df561c6 100644 --- a/crates/rocm-core/src/lib.rs +++ b/crates/rocm-core/src/lib.rs @@ -2894,9 +2894,10 @@ pub(crate) fn discover_rocm_installs() -> Vec { /// Reading `$ROCM_PATH` inside [`discover_rocm_installs`] is what forced its /// callers' tests to mutate the process environment, and two of them racing on /// that global is what made the Windows lane flake — that lane runs `cargo test` -/// (threads in one process) where the Linux lanes run `cargo nextest` (a process -/// per test), so only Windows could ever observe it. Passing the override in -/// keeps those tests hermetic. Same seam as [`discover_rocm_installs_in`], but +/// (threads in one process) where `Test (affected crates)` runs `cargo nextest` +/// (a process per test), so only Windows observed it. Not every Linux lane uses +/// nextest, so that is where it fired rather than where it could. Passing the +/// override in keeps those tests hermetic. Same seam as [`discover_rocm_installs_in`], but /// keeps the host's layout so the caller under test is the real one. #[cfg(test)] pub(crate) fn discover_rocm_installs_on_host_in( diff --git a/docs/testing.md b/docs/testing.md index 22d3524d6e..59f224a221 100644 --- a/docs/testing.md +++ b/docs/testing.md @@ -16,12 +16,60 @@ Run the Rust test suite: cargo test --workspace --all-targets ``` +Note that `cargo test` runs every test as a thread in **one process**, which is +also what the required `windows-build-and-test` lane does. See +[Tests that touch the environment](#tests-that-touch-the-environment) before +writing a test that sets an environment variable. + Run clippy with warnings as errors: ```bash cargo clippy --workspace --all-targets -- -D warnings ``` +### Tests that touch the environment + +`std::env::set_var` / `remove_var` change state shared by every thread in the +process. Under a threaded harness two tests touching the same key race, and one +reads the other's value and fails an assertion unrelated to what it tests. This +is enforced: `cargo xtask`'s `a_test_mutating_the_environment_serializes_itself` +scans the tree and **fails the build** on an unguarded mutation inside a +`#[test]`. + +Best is not to touch the environment at all — pass the value in through a test +seam, as `newest_rocm_install_dir_in` and `engine_envs_root_from` do. A seam +cannot test the wiring it bypasses, though, so when exercising the real +env-reading path *is* the point, take a process-wide lock for the duration of +the test and restore the previous value before releasing it: + +```rust +#[allow(unsafe_code)] // std::env::set_var is unsafe in edition 2024 +#[test] +fn reads_its_setting_from_the_environment() { + let _guard = SOMETHING_ENV_TEST_LOCK + .lock() + .unwrap_or_else(std::sync::PoisonError::into_inner); + let previous = std::env::var_os("KEY"); + unsafe { std::env::set_var("KEY", "value") }; + let observed = production_function(); + match &previous { + Some(value) => unsafe { std::env::set_var("KEY", value) }, + None => unsafe { std::env::remove_var("KEY") }, + } + assert_eq!(observed, "value"); +} +``` + +The guard accepts `ScopedTestEnv`, `ScopedEnvVar`, or **any** static named +`*_TEST_LOCK` taken inside the test body. The suffix is the rule, so a new lock +is recognised the day it is declared rather than when someone remembers to add +it to a list. The exemption is per test function, not per file: one test taking +a lock does not cover its neighbours. + +Keep the mutation and the lock in the same test body. A `#[test]` that delegates +its mutation to an unguarded helper is a known blind spot — the helper is a +different scope, so the scan cannot see the two together. + Run the cross-platform smoke test: ```bash diff --git a/xtask/src/env_mutation_contract.rs b/xtask/src/env_mutation_contract.rs index 89da0361f3..96a562105c 100644 --- a/xtask/src/env_mutation_contract.rs +++ b/xtask/src/env_mutation_contract.rs @@ -10,14 +10,20 @@ //! race — one reads the other's value and fails an assertion that has nothing //! to do with what it is testing. //! -//! This is invisible on most of CI. `ci.yml` runs the Linux lanes under -//! `cargo nextest` (a process per test, so the mutation cannot escape), but -//! `windows-build-and-test` runs `cargo test --workspace --all-targets` — all -//! tests as threads in ONE process. So the Windows lane, a required check, was -//! the only place the race could fire, and it read as "your change broke +//! This is invisible on most of CI. `ci.yml`'s `Test (affected crates)` job +//! runs `cargo nextest` (a process per test, so the mutation cannot escape), +//! but `windows-build-and-test` runs `cargo test --workspace --all-targets` — +//! all tests as threads in ONE process. So the Windows lane, a required check, +//! was the only place the race could fire, and it read as "your change broke //! Windows" on branches that never touched the crate. Nothing about the bug is //! Windows-specific; it is a property of the runner. //! +//! "the Linux lanes use nextest" would be too strong: `coverage` +//! (`cargo llvm-cov`, no `--nextest`) and `e2e` (`cargo test -p e2e-cucumber +//! --lib`) are threaded single-process harnesses on `ubuntu-latest` too. They +//! happen not to reach the crates that raced, which is luck rather than +//! design — so this guard covers the whole tree rather than one crate. +//! //! The repo already had two ways of handling this — `ScopedTestEnv` in //! `apps/rocm/src/main.rs` and `PROCESS_ENV_TEST_LOCK` in //! `apps/rocm/src/therock.rs`, both of which take a process-wide lock — and the From 9b3161bcf9b14bfaa46ad6abdc08588b2b2e5794 Mon Sep 17 00:00:00 2001 From: Roman Inflianskas Date: Tue, 22 Sep 2026 09:29:49 +0000 Subject: [PATCH 04/16] test(xtask): report env mutations left in an unclosed test block The scan dropped any hit it had collected when a file ended with a test body still open, so a brace it mis-read could swallow a real offender without a trace. Report those instead: over-reporting is visible and gets fixed, a silently discarded hit is not. That also makes the opening-brace fixture discriminating. With one brace the enclosing module's close absorbed it, so the test passed against a scanner that tokenizes literals and against one that does not; two braces keep the scan open to EOF, where the leak now surfaces. Records why the depth subtraction saturates, since with literals tokenized away it is a backstop rather than part of the logic. Signed-off-by: Roman Inflianskas --- xtask/src/env_mutation_contract.rs | 27 +++++++++++++++++++++++++-- 1 file changed, 25 insertions(+), 2 deletions(-) diff --git a/xtask/src/env_mutation_contract.rs b/xtask/src/env_mutation_contract.rs index 96a562105c..9167487dca 100644 --- a/xtask/src/env_mutation_contract.rs +++ b/xtask/src/env_mutation_contract.rs @@ -359,6 +359,10 @@ mod tests { pending_test_attr = false; } + // Saturating purely so a file this scan misreads cannot panic the + // build. With literals tokenized away the count is balanced on any + // file that compiles, so the saturation is unreachable in practice + // — it is a backstop, not part of the logic. depth = (depth + opens).saturating_sub(closes); if let Some((open_depth, body, hits)) = current.as_ref() @@ -373,6 +377,18 @@ mod tests { current = None; } } + + // A test body still open when the file ends means the brace bookkeeping + // lost track of something. Report what it collected instead of dropping + // it on the floor: over-reporting is visible and gets fixed, whereas a + // silently discarded hit is the failure mode this guard exists to + // prevent. + if let Some((_, body, hits)) = current + && !serializes(&body) + { + offenses.extend(hits); + } + offenses } @@ -568,13 +584,20 @@ mod tests { ); } - /// The mirror failure: an unbalanced `{{` in a literal inflates the depth and + /// The mirror failure: unbalanced `{{` in a literal inflates the depth and /// keeps the scan inside a test long after it ended, so PRODUCTION code /// downstream gets flagged and the build fails for nothing. + /// + /// Two braces rather than one on purpose. One is swallowed by the enclosing + /// `mod tests` close, which would leave this passing for a reason unrelated + /// to the defect; two keep the scan open past the end of the file, where the + /// EOF flush turns the leak into a reported offense — so this fails against + /// a scanner that does not tokenize literals. `{{model=...}}` in a + /// Prometheus format string is the real shape of it. #[test] fn an_opening_brace_in_a_literal_does_not_drag_in_production_code() { let source = format!( - "#[cfg(test)]\nmod tests {{\n #[test]\n fn t() {{\n let _s = \"{{\";\n }}\n}}\n\ + "#[cfg(test)]\nmod tests {{\n #[test]\n fn t() {{\n let _s = \"{{{{\";\n }}\n}}\n\ fn later_production() {{\n {}\n}}\n", mutation_call("set_var") ); From 47dd42ccc6e30591349fc4dd1d031b443afa84e5 Mon Sep 17 00:00:00 2001 From: Roman Inflianskas Date: Tue, 22 Sep 2026 09:31:14 +0000 Subject: [PATCH 05/16] test(core): say which of the two env disciplines applies where fix.rs now holds both a test seam and a process-wide lock. Left unexplained that reads as a merge artifact, and the next test to touch $ROCM_PATH picks whichever it happens to see first. State the split at the lock: the seam for resolution semantics, the lock only for the test whose subject is the environment read itself. Signed-off-by: Roman Inflianskas --- crates/rocm-core/src/fix.rs | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/crates/rocm-core/src/fix.rs b/crates/rocm-core/src/fix.rs index c6b33e3443..4b9090ae6f 100644 --- a/crates/rocm-core/src/fix.rs +++ b/crates/rocm-core/src/fix.rs @@ -1390,6 +1390,12 @@ mod tests { // Serializes tests that replace the process-global `ROCM_PATH` env var while // they run. Because env is shared across all test threads, two such tests // running concurrently can otherwise see each other's value mid-test. + // + // Deliberately kept alongside the seam rather than instead of it, and the + // split is not arbitrary: tests about resolution semantics take the seam + // and never touch the environment, and exactly one test — the one whose + // subject IS the `$ROCM_PATH` read — takes this lock. Anything provable + // through the seam should not be reaching for the lock. static PROCESS_ENV_TEST_LOCK: std::sync::Mutex<()> = std::sync::Mutex::new(()); #[test] From 3b8b32ce311bf3c23ca7ddbdc5052ccb3a6bd027 Mon Sep 17 00:00:00 2001 From: Roman Inflianskas Date: Wed, 23 Sep 2026 09:51:00 +0000 Subject: [PATCH 06/16] test(xtask): prove every mutating call the guard lists is detected `env::remove_var` was in the MUTATIONS const but no fixture asserted an unguarded one inside a `#[test]` was flagged -- its only appearance was in a fixture asserting the opposite. Dropping it from the const left the whole suite green, so detection worked but nothing held it in place. The new fixture spells the call kinds out rather than iterating MUTATIONS: a fixture reading the const would shrink with it and stay green. Asserting the two lists are the same length is what makes a future entry arrive with a case instead of untested. Signed-off-by: Roman Inflianskas --- xtask/src/env_mutation_contract.rs | 29 +++++++++++++++++++++++++++++ 1 file changed, 29 insertions(+) diff --git a/xtask/src/env_mutation_contract.rs b/xtask/src/env_mutation_contract.rs index 9167487dca..52b863f2b5 100644 --- a/xtask/src/env_mutation_contract.rs +++ b/xtask/src/env_mutation_contract.rs @@ -448,6 +448,35 @@ mod tests { assert_eq!(hits[0].line, 8, "should flag the line inside the test"); } + /// Every entry in [`MUTATIONS`] is actually detected. + /// + /// The kinds are spelled out here rather than read from the const on + /// purpose: a fixture that iterated `MUTATIONS` would shrink along with it, + /// so deleting an entry would leave the suite green — which is exactly the + /// hole this closes. `remove_var` previously appeared in one fixture that + /// asserts `is_empty()`, so nothing anywhere proved an unguarded + /// `remove_var` inside a `#[test]` was flagged at all. + /// + /// The length assertion is what stops the next entry arriving untested: a + /// third call added to the const fails here until it gains a case. + #[test] + fn every_mutating_call_is_flagged_inside_an_unguarded_test() { + let kinds = ["set_var", "remove_var"]; + assert_eq!( + MUTATIONS.len(), + kinds.len(), + "a call was added to MUTATIONS without a case here" + ); + for kind in kinds { + let source = unguarded_test(&mutation_call(kind)); + assert_eq!( + env_mutations_in_unserialized_tests(&source).len(), + 1, + "an unguarded std::env::{kind} inside a #[test] must be flagged" + ); + } + } + #[test] fn the_scanner_ignores_production_mutations() { // Production code owns the process and may legitimately set a variable; From d09ced27dc0ce34955678793878d4a5789740338 Mon Sep 17 00:00:00 2001 From: Roman Inflianskas Date: Wed, 23 Sep 2026 09:52:23 +0000 Subject: [PATCH 07/16] test(core): make the $ROCM_PATH ordering claim hold on Windows too The decoy the resolver was meant to outrank was planted only as a versioned sibling (`rocm-6.2.0`), which the Windows layout does not recognise -- there versions are bare `X.Y` children. So on `windows-build-and-test`, the lane this work exists for, the search loop returned nothing and "the override outranks the search roots" passed vacuously. Plant both shapes, and assert the same search without the override finds something, so a decoy the host layout cannot see fails the test instead of silently hollowing it out. Signed-off-by: Roman Inflianskas --- crates/rocm-core/src/fix.rs | 21 +++++++++++++++++++-- 1 file changed, 19 insertions(+), 2 deletions(-) diff --git a/crates/rocm-core/src/fix.rs b/crates/rocm-core/src/fix.rs index 4b9090ae6f..fee06c3761 100644 --- a/crates/rocm-core/src/fix.rs +++ b/crates/rocm-core/src/fix.rs @@ -1445,9 +1445,16 @@ mod tests { // Passing it alongside the override is what exercises the ordering the // assertion below claims: with `&[]` the search loop never runs, so // "the override outranks the search roots" would hold vacuously. + // + // Planted in BOTH shapes because the resolver is told the host's + // layout: `rocm-6.2.0` is a versioned sibling and only matches on + // Linux, `6.2` is a bare-version child and only matches on Windows. + // Planting one shape would leave the search loop empty on the other + // platform and make the ordering half vacuous again -- on Windows + // first, which is the lane this test exists for. let searched = root.join("search"); - let older = searched.join("rocm-6.2.0"); - plant_install(&older); + plant_install(&searched.join("rocm-6.2.0")); + plant_install(&searched.join("6.2")); // The override goes in as an argument rather than through // `std::env::set_var`: the environment is process-global, so a sibling @@ -1455,9 +1462,19 @@ mod tests { // this assertion fail on whichever test lost the race. // `..._reads_rocm_path_from_the_environment` covers the real read. let found = newest_rocm_install_dir_in(std::slice::from_ref(&searched), Some(&install)); + // Run the same search WITHOUT the override, so the ordering claim below + // cannot pass by finding nothing to outrank. A planted decoy the + // resolver's layout does not recognise is indistinguishable, from the + // assertion's point of view, from no decoy at all. + let without_override = newest_rocm_install_dir_in(std::slice::from_ref(&searched), None); std::fs::remove_dir_all(&root).ok(); + assert!( + !without_override.is_empty(), + "the decoy must be reachable through the search roots on this \ + platform, or 'the override outranks them' holds vacuously" + ); assert_eq!( found, install.to_string_lossy(), From 024c3fa45a9310c2d877c0a9dd6f39272a732162 Mon Sep 17 00:00:00 2001 From: Roman Inflianskas Date: Wed, 23 Sep 2026 09:55:32 +0000 Subject: [PATCH 08/16] test(xtask): bring async tests inside the env-mutation guard The scan armed on the literal `#[test]`, so the 87 `#[tokio::test]` functions across 16 files were invisible to it. They run in the same process under the same threaded harness, so the hazard is identical; none of them mutates the environment today, which is exactly why now is the cheap time to start watching. Attributes are matched by path instead -- last segment `test` -- which takes `#[tokio::test(flavor = "...")]` too and still rejects `#[cfg(test)]`. Also covers the braceless-item disarm, which no fixture killed: removing it left the suite green. And drops the test counts from two comments; they were already wrong (461 and 143, not 379 and 73) and the point they support does not need them. Signed-off-by: Roman Inflianskas --- xtask/src/env_mutation_contract.rs | 105 +++++++++++++++++++++++++---- 1 file changed, 92 insertions(+), 13 deletions(-) diff --git a/xtask/src/env_mutation_contract.rs b/xtask/src/env_mutation_contract.rs index 52b863f2b5..f7fadebe11 100644 --- a/xtask/src/env_mutation_contract.rs +++ b/xtask/src/env_mutation_contract.rs @@ -300,27 +300,55 @@ mod tests { } } - /// A `#[test]` function that mutates the environment. + /// Whether `code` carries a test attribute. + /// + /// The rule is "the attribute path's last segment is `test`", which covers + /// `#[test]`, `#[tokio::test]` and `#[tokio::test(flavor = "...")]` alike. + /// Arming only on the literal `#[test]` left the 87 `#[tokio::test]` + /// functions in this tree invisible to the scan — none of them mutates the + /// environment today, but nothing was watching if one started. + /// + /// `#[cfg(test)]` and `#[cfg_attr(test, ...)]` stop at the `(`, so their + /// path is `cfg`/`cfg_attr` and neither is mistaken for a test. + fn has_test_attribute(code: &str) -> bool { + code.match_indices("#[").any(|(start, _)| { + let path: String = code[start + 2..] + .chars() + .take_while(|c| c.is_ascii_alphanumeric() || *c == '_' || *c == ':') + .collect(); + path.rsplit("::").next() == Some("test") + }) + } + + /// A test function that mutates the environment. #[derive(Debug, PartialEq, Eq)] struct Offense { line: usize, call: String, } - /// Mutations inside a `#[test]` function that does not serialize itself. + /// Mutations inside a test function that does not serialize itself. /// /// Scoped to the test FUNCTION, not the file. The file-level rule this /// replaces asked only whether a marker appeared anywhere in the text, so a /// comment reading "maybe migrate this to ScopedTestEnv one day" exempted - /// every test in the file — and `apps/rocm/src/main.rs` (379 tests) and - /// `apps/rocm/src/therock.rs` (73) were both wholly exempt for that reason, - /// which is precisely where the next unguarded test is most likely to land. + /// every test in the file — and the two largest test modules in the tree, + /// `apps/rocm/src/main.rs` and `apps/rocm/src/therock.rs`, were both wholly + /// exempt for that reason, which is precisely where the next unguarded test + /// is most likely to land. (Deliberately no test counts here: they were + /// wrong within weeks of being written, and the point does not need them.) /// - /// Known limit: a `#[test]` that delegates its mutation to an unguarded - /// helper is not caught, because the helper's body is a different scope. - /// Mutations outside `#[test]` functions are deliberately not flagged — - /// that is production code, and test-support types such as `ScopedTestEnv` - /// whose whole job is to perform the mutation on a test's behalf. + /// Known limits: + /// + /// * A test that delegates its mutation to an unguarded helper is not + /// caught, because the helper's body is a different scope. + /// * Attributes are recognised by path (see [`has_test_attribute`]), so a + /// harness whose attribute does not end in `test` — `#[test_case(..)]`, + /// `#[rstest]` — would not arm the scan. Neither is used in this tree. + /// + /// Mutations outside test functions are deliberately not flagged — that is + /// production code, and test-support types such as `ScopedTestEnv` whose + /// whole job is to perform the mutation on a test's behalf. fn env_mutations_in_unserialized_tests(text: &str) -> Vec { let stripped = strip_literals_and_comments(text); let mut offenses = Vec::new(); @@ -332,7 +360,7 @@ mod tests { for (index, line) in stripped.lines().enumerate() { let code = line.trim(); - if current.is_none() && code.contains("#[test]") { + if current.is_none() && has_test_attribute(code) { pending_test_attr = true; } @@ -477,6 +505,57 @@ mod tests { } } + /// An async test is a test. + /// + /// The scan used to arm on the literal `#[test]`, which left every + /// `#[tokio::test]` in the tree outside the guard. They run in the same + /// process under the same threaded harness, so the hazard is identical. + #[test] + fn the_scanner_sees_a_mutation_inside_an_async_test() { + for attribute in [ + "#[tokio::test]", + "#[tokio::test(flavor = \"multi_thread\")]", + ] { + let source = format!( + "#[cfg(test)]\nmod tests {{\n {attribute}\n async fn t() {{\n {}\n }}\n}}\n", + mutation_call("set_var") + ); + let hits = env_mutations_in_unserialized_tests(&source); + assert_eq!(hits.len(), 1, "{attribute} should arm the scan: {hits:?}"); + } + } + + /// The line after a test attribute need not open a block. + /// + /// This is a text scan, not a parser, so it cannot assume it does. Without + /// the disarm the attribute stays armed and the next brace anywhere in the + /// file — here, production code — is taken for the test body. + #[test] + fn a_test_attribute_on_a_braceless_item_does_not_open_a_block() { + let source = format!( + "#[test]\nfn declared_elsewhere();\n\nfn production() {{\n {}\n}}\n", + mutation_call("set_var") + ); + assert!( + env_mutations_in_unserialized_tests(&source).is_empty(), + "no test body was opened; the mutation below is production code" + ); + } + + /// `#[cfg(test)]` names `test` but is not a test attribute. Arming on it + /// would make the whole rest of the file read as one test body. + #[test] + fn a_cfg_test_gate_is_not_a_test_attribute() { + for attribute in ["#[cfg(test)]", "#[cfg_attr(test, derive(Debug))]"] { + assert!( + !has_test_attribute(attribute), + "{attribute} must not arm the scan" + ); + } + assert!(has_test_attribute("#[test]")); + assert!(has_test_attribute("#[tokio::test]")); + } + #[test] fn the_scanner_ignores_production_mutations() { // Production code owns the process and may legitimately set a variable; @@ -545,8 +624,8 @@ mod tests { /// /// Under the previous rule this whole file was exempt because SOME test in /// it took a lock -- or merely because a comment named one. That is how - /// `apps/rocm/src/main.rs` (379 tests) and `apps/rocm/src/therock.rs` (73) - /// ended up with no line-level enforcement at all. + /// `apps/rocm/src/main.rs` and `apps/rocm/src/therock.rs`, the two largest + /// test modules in the tree, ended up with no line-level enforcement at all. #[test] fn one_serialized_test_does_not_exempt_its_neighbour() { let call = mutation_call("set_var"); From 262eda9d0e0166e855d2f5ff5cd1b1aa598932c0 Mon Sep 17 00:00:00 2001 From: Roman Inflianskas Date: Wed, 23 Sep 2026 09:56:29 +0000 Subject: [PATCH 09/16] fix(xtask): keep reported line numbers right across a continued string Inside a string literal a backslash consumed two characters unconditionally, so a trailing-backslash line continuation swallowed the newline and merged two source lines. Brace totals were unaffected, so the pass/fail verdict was right, but any offense reported later in such a file carried a shifted line number -- and the `file:line` in the assertion is how an author finds the test they have to fix. Several strings in this tree use that form, including this guard's own assertion message. Signed-off-by: Roman Inflianskas --- xtask/src/env_mutation_contract.rs | 31 +++++++++++++++++++++++++++++- 1 file changed, 30 insertions(+), 1 deletion(-) diff --git a/xtask/src/env_mutation_contract.rs b/xtask/src/env_mutation_contract.rs index f7fadebe11..89bc73f8dd 100644 --- a/xtask/src/env_mutation_contract.rs +++ b/xtask/src/env_mutation_contract.rs @@ -223,7 +223,17 @@ mod tests { } State::Str => { if c == '\\' { - out.push_str(" "); + // The escaped character cannot close the literal, so + // it is consumed here. When it is a NEWLINE -- a line + // continuation, which several strings in this tree use, + // including this file's own assertion message -- the + // newline is not part of the string's value but it is + // part of the file's line structure. Replacing it with + // a space merges two source lines and shifts the line + // number of every offense reported after it, which is + // the `file:line` the assertion promises. + out.push(' '); + out.push(if next == Some('\n') { '\n' } else { ' ' }); i += 2; continue; } @@ -735,6 +745,25 @@ mod tests { ); } + /// A `\` at end of line continues a string literal onto the next one. The + /// newline is not part of the string's value, but it is part of the file's + /// line structure, and losing it renumbers everything below. + #[test] + fn a_line_continuation_in_a_literal_does_not_renumber_the_lines() { + let source = format!( + "#[cfg(test)]\nmod tests {{\n #[test]\n fn t() {{\n\ + \x20 let _s = \"continued \\\n here\";\n\ + \x20 {}\n }}\n}}\n", + mutation_call("set_var") + ); + let hits = env_mutations_in_unserialized_tests(&source); + assert_eq!(hits.len(), 1, "{hits:?}"); + assert_eq!( + hits[0].line, 7, + "the continuation spans lines 5-6, so the mutation is on line 7" + ); + } + #[test] fn a_lifetime_is_not_mistaken_for_a_char_literal() { // `'a` opens no literal; treating it as one would swallow the rest of From 9e7bf9fe894bf0e0afa0b3b39174b5ecd413abde Mon Sep 17 00:00:00 2001 From: Roman Inflianskas Date: Wed, 23 Sep 2026 09:57:29 +0000 Subject: [PATCH 10/16] docs(testing): give the env guard's real invocation and a snippet that builds "`cargo xtask`'s a_test_mutating_the_environment_serializes_itself" read as a subcommand; there is none, it is a test. State the command that runs it. The example also used `SOMETHING_ENV_TEST_LOCK` without declaring it, so it did not compile as pasted -- declare the static, and say why the poison case is handled the way it is. Signed-off-by: Roman Inflianskas --- docs/testing.md | 16 +++++++++++++--- 1 file changed, 13 insertions(+), 3 deletions(-) diff --git a/docs/testing.md b/docs/testing.md index 59f224a221..9e1f207286 100644 --- a/docs/testing.md +++ b/docs/testing.md @@ -32,9 +32,14 @@ cargo clippy --workspace --all-targets -- -D warnings `std::env::set_var` / `remove_var` change state shared by every thread in the process. Under a threaded harness two tests touching the same key race, and one reads the other's value and fails an assertion unrelated to what it tests. This -is enforced: `cargo xtask`'s `a_test_mutating_the_environment_serializes_itself` -scans the tree and **fails the build** on an unguarded mutation inside a -`#[test]`. +is enforced by a test, not by an `xtask` subcommand: +`a_test_mutating_the_environment_serializes_itself` in `xtask` scans the whole +tree and **fails the build** on an unguarded mutation inside a `#[test]` or +`#[tokio::test]`. Run it on its own with: + +```bash +cargo test -p xtask a_test_mutating_the_environment_serializes_itself +``` Best is not to touch the environment at all — pass the value in through a test seam, as `newest_rocm_install_dir_in` and `engine_envs_root_from` do. A seam @@ -43,9 +48,14 @@ env-reading path *is* the point, take a process-wide lock for the duration of the test and restore the previous value before releasing it: ```rust +/// Serializes every test in this process that replaces `KEY`. +static SOMETHING_ENV_TEST_LOCK: std::sync::Mutex<()> = std::sync::Mutex::new(()); + #[allow(unsafe_code)] // std::env::set_var is unsafe in edition 2024 #[test] fn reads_its_setting_from_the_environment() { + // Poison is not a failure here: a panicking sibling leaves the value + // restored or not, and either way this test still wants the lock. let _guard = SOMETHING_ENV_TEST_LOCK .lock() .unwrap_or_else(std::sync::PoisonError::into_inner); From 0f725bab7bcf462533ce6781f8546731a60b5b39 Mon Sep 17 00:00:00 2001 From: Roman Inflianskas Date: Thu, 24 Sep 2026 14:37:55 +0000 Subject: [PATCH 11/16] test(xtask): close the scanner branches no fixture could fail on A mutation sweep over every branch in the guard's scanner found 22 of 40 mutants surviving the suite -- the raw-string branch among them, which could be replaced by a constant false with all 18 tests still green. The only raw-string fixture held no quote, so the ordinary-string state consumed the same span; the fixture looked like coverage and was none. Each surviving branch now has a fixture that fails when it is disabled: raw strings holding a quote (and the hashless case, whose opener must consume its own quote), char literals holding a brace or an escaped quote, nested block comments, escaped quotes in strings, literals spanning two lines, the end-of-file flush, attributes that merely contain `test`, a nested `#[test]`, and a name that merely contains `_TEST_LOCK`. Two survivors are equivalent mutants and say so at the line instead: the byte-string `b` prefix, which only shifts the match one character later onto the `r`, and `is_char_literal`'s end-of-input arm, whose two answers differ by one non-brace character the caller never looks at. A lock now has to precede the mutation it covers. Matching the whole accumulated body accepted one written afterwards, which is the race this guard exists to stop. It cannot check that every mutator of a key takes the SAME lock -- the keys are in literals the scan strips -- so the rejection message asks for it and the known limits record it. A mutation sharing the line that opens the test body is now seen; the body used to be opened after that line had been scanned. Signed-off-by: Roman Inflianskas --- xtask/src/env_mutation_contract.rs | 392 ++++++++++++++++++++++++++--- 1 file changed, 362 insertions(+), 30 deletions(-) diff --git a/xtask/src/env_mutation_contract.rs b/xtask/src/env_mutation_contract.rs index 89bc73f8dd..5d734f7735 100644 --- a/xtask/src/env_mutation_contract.rs +++ b/xtask/src/env_mutation_contract.rs @@ -106,7 +106,13 @@ mod tests { /// Whether `text` takes one of the process-wide serializers. /// /// The suffix rule recognises the DISCIPLINE rather than a specific lock, so - /// a new `*_TEST_LOCK` is covered the day it is declared. + /// a new `*_TEST_LOCK` is covered the day it is declared. It is a suffix and + /// not a substring on purpose: `NOT_A_TEST_LOCK_HELPER` names something else. + /// + /// Applied per LINE by the caller, which is what lets it answer "was the + /// lock taken before this mutation?" rather than merely "somewhere in this + /// body". Every lock in this tree names itself on the line that acquires it + /// (`let _guard = SOME_TEST_LOCK` ...), so a per-line match loses nothing. fn serializes(text: &str) -> bool { NAMED_SERIALIZERS.iter().any(|name| text.contains(name)) || text @@ -274,6 +280,14 @@ mod tests { /// `i` (`r"`, `r#"`, `br##"`, ...). fn raw_string_opener(chars: &[char], i: usize) -> Option<(usize, usize)> { let mut j = i; + // Accepting the byte-string `b` here is cosmetic, and deliberately has + // no fixture: removing it only means the caller declines at the `b` and + // matches one character later at the `r`, which opens the same literal + // and strips the same span. The single character of difference is the + // `b` itself, emitted as code rather than as a space — and the stripped + // text is read only for braces and for the names in `MUTATIONS`, so a + // stray `b` cannot change a verdict. An equivalent mutant; a test for it + // would assert nothing. if chars.get(j) == Some(&'b') { j += 1; } @@ -306,6 +320,12 @@ mod tests { // `'\n'`, `'\''`, `'\\'` -- always a literal. Some('\\') => true, Some(_) => chars.get(i + 2) == Some(&'\''), + // A `'` as the final character of the file. Deliberately untested: + // the two answers are indistinguishable, because the caller's loop + // ends on the next step either way and the one character of output + // that differs (`'` versus a space) is neither a brace nor part of + // a mutating call's name. Flipping this arm is an equivalent + // mutant, so a fixture for it would assert nothing. None => false, } } @@ -331,12 +351,38 @@ mod tests { } /// A test function that mutates the environment. - #[derive(Debug, PartialEq, Eq)] + #[derive(Clone, Debug, PartialEq, Eq)] struct Offense { line: usize, call: String, } + /// A test body being scanned. + struct OpenTest { + /// The brace depth the body opened at; it closes on the way back down. + open_depth: usize, + /// The first line that took a serializer, if any. A mutation is exempt + /// only from that line ONWARD — see [`OpenTest::unserialized_hits`]. + serialized_at: Option, + hits: Vec, + } + + impl OpenTest { + /// The hits this body does not serialize. + /// + /// A lock is an RAII guard: it protects from where it is taken until the + /// end of the scope, and nothing before. Matching the whole accumulated + /// body — which is what this used to do — accepted a lock written AFTER + /// the mutation it was supposed to protect, which is exactly the bug + /// this guard exists to catch, spelled slightly differently. + fn unserialized_hits(&self) -> impl Iterator + '_ { + self.hits + .iter() + .filter(move |hit| self.serialized_at.is_none_or(|at| hit.line < at)) + .cloned() + } + } + /// Mutations inside a test function that does not serialize itself. /// /// Scoped to the test FUNCTION, not the file. The file-level rule this @@ -355,6 +401,13 @@ mod tests { /// * Attributes are recognised by path (see [`has_test_attribute`]), so a /// harness whose attribute does not end in `test` — `#[test_case(..)]`, /// `#[rstest]` — would not arm the scan. Neither is used in this tree. + /// * The scan checks that A lock is held, not that it is THE lock every + /// other mutator of the same key takes. Two tests replacing one key under + /// two different mutexes both pass and still race each other. Closing + /// that needs the key each call names, and the keys are string literals + /// this scan has deliberately stripped before it starts — recovering them + /// would mean re-parsing, and they are often constants or variables + /// anyway. The rejection message states the requirement instead. /// /// Mutations outside test functions are deliberately not flagged — that is /// production code, and test-support types such as `ScopedTestEnv` whose @@ -364,8 +417,7 @@ mod tests { let mut offenses = Vec::new(); let mut depth: usize = 0; let mut pending_test_attr = false; - // (depth at which the test fn body opened, body text so far, hits so far) - let mut current: Option<(usize, String, Vec)> = None; + let mut current: Option = None; for (index, line) in stripped.lines().enumerate() { let code = line.trim(); @@ -374,44 +426,53 @@ mod tests { pending_test_attr = true; } - if let Some((_, body, hits)) = current.as_mut() { - body.push_str(line); - body.push('\n'); - if let Some(found) = MUTATIONS.iter().find(|needle| code.contains(*needle)) { - hits.push(Offense { - line: index + 1, - call: (*found).to_owned(), - }); - } - } - let opens = code.matches('{').count(); let closes = code.matches('}').count(); + // Opened BEFORE this line is scanned, so a mutation sharing the + // line with the body's opening brace is seen. The shape is a + // one-line `fn t() { unsafe { set_var(..) } }`; rustfmt normally + // splits it, so only a `#[rustfmt::skip]` test reaches it -- and + // that one used to slip through in silence. if pending_test_attr && opens > 0 { pending_test_attr = false; - current = Some((depth, String::new(), Vec::new())); + current = Some(OpenTest { + open_depth: depth, + serialized_at: None, + hits: Vec::new(), + }); } else if pending_test_attr && code.ends_with(';') { // The attribute gated a braceless item; disarm so the next brace // anywhere in the file is not mistaken for a test body. pending_test_attr = false; } + if let Some(open) = current.as_mut() { + // Before the hit, so a lock and a mutation on ONE line counts as + // serialized -- the lock is taken first in source order. + if open.serialized_at.is_none() && serializes(code) { + open.serialized_at = Some(index + 1); + } + if let Some(found) = MUTATIONS.iter().find(|needle| code.contains(*needle)) { + open.hits.push(Offense { + line: index + 1, + call: (*found).to_owned(), + }); + } + } + // Saturating purely so a file this scan misreads cannot panic the // build. With literals tokenized away the count is balanced on any // file that compiles, so the saturation is unreachable in practice - // — it is a backstop, not part of the logic. + // — it is a backstop, not part of the logic. (Proven by mutation: + // swapping it for a plain `-` leaves the whole suite green, so it + // is an equivalent mutant and no fixture is written for it.) depth = (depth + opens).saturating_sub(closes); - if let Some((open_depth, body, hits)) = current.as_ref() - && depth <= *open_depth + if let Some(open) = current.as_ref() + && depth <= open.open_depth { - if !serializes(body) { - offenses.extend(hits.iter().map(|hit| Offense { - line: hit.line, - call: hit.call.clone(), - })); - } + offenses.extend(open.unserialized_hits()); current = None; } } @@ -421,10 +482,8 @@ mod tests { // it on the floor: over-reporting is visible and gets fixed, whereas a // silently discarded hit is the failure mode this guard exists to // prevent. - if let Some((_, body, hits)) = current - && !serializes(&body) - { - offenses.extend(hits); + if let Some(open) = current.as_ref() { + offenses.extend(open.unserialized_hits()); } offenses @@ -452,7 +511,11 @@ mod tests { runner (the Windows lane, a required check). Prefer passing the \ value in through a seam (see `newest_rocm_install_dir_in`); \ otherwise take `ScopedTestEnv` or any `*_TEST_LOCK` in the test \ - body. Offenders:\n{}", + body. The lock must be taken BEFORE the mutation -- it protects \ + from where it is acquired, not retroactively -- and it must be \ + the SAME lock every test mutating that key takes, which this scan \ + cannot check for you: two tests replacing one key under two \ + different mutexes both satisfy it and still race. Offenders:\n{}", offenders.join("\n") ); } @@ -774,4 +837,273 @@ mod tests { "{stripped:?}" ); } + + /// A raw string ends at its hashes, not at the first `"` inside it. + /// + /// The suite's only raw-string fixture used to be `r#"raw } {"#`, which + /// holds no quote — so the ordinary-string state consumed exactly the same + /// span and the raw-string branch could be deleted with all 18 tests still + /// green. A fixture that looks like coverage and provides none is the worst + /// case for a permanent gate, because the build stays green either way. + /// + /// Each literal here carries a quote, which is what makes the two states + /// diverge: read as an ordinary string, the text after that quote becomes + /// code and its `{` inflates the depth, which leaves the mutation below + /// inside a literal and invisible. + #[test] + fn a_raw_string_holding_a_quote_does_not_leak_its_braces() { + // A hashless `r"..."` cannot hold a quote at all -- that is what the + // hashes are for -- so it gets its own fixture below. + for literal in ["r#\"a \" b {\"#", "r##\"a \"# b {\"##", "br#\"a \" b {\"#"] { + let source = unguarded_test(&format!( + "let _s = {literal};\n {}", + mutation_call("set_var") + )); + let hits = env_mutations_in_unserialized_tests(&source); + assert_eq!( + hits.len(), + 1, + "{literal} must be stripped whole, braces included: {hits:?}" + ); + } + } + + /// A raw string with no hashes is closed by its very next `"`, so the + /// opener has to consume that quote. Consuming one character less leaves + /// the scan sitting on the quote it just opened, which closes the literal + /// immediately and spills its contents into the code stream. + #[test] + fn a_hashless_raw_string_is_not_closed_by_its_own_opening_quote() { + let source = unguarded_test(&format!( + "let _s = r\"leaks }} here\";\n {}", + mutation_call("set_var") + )); + let hits = env_mutations_in_unserialized_tests(&source); + assert_eq!(hits.len(), 1, "r\"...\" must be stripped whole: {hits:?}"); + } + + /// A char literal is a literal. Without the state the `}` in `'}'` closes + /// the enclosing test early and everything after it goes unwatched; with + /// the state but no exit the rest of the file is swallowed instead. Both + /// directions end with the mutation below unreported. + #[test] + fn a_char_literal_holding_a_brace_does_not_close_the_test() { + let source = unguarded_test(&format!( + "let _c = '}}';\n {}", + mutation_call("set_var") + )); + let hits = env_mutations_in_unserialized_tests(&source); + assert_eq!(hits.len(), 1, "'}}' is a literal, not a brace: {hits:?}"); + } + + /// `'\"'` is a char literal holding a quote. Failing to recognise it lets + /// that quote open an ordinary string, which then runs on and swallows the + /// mutation on the next line. + #[test] + fn an_escaped_quote_in_a_char_literal_does_not_open_a_string() { + let source = unguarded_test(&format!( + "let _c = '\\\"';\n {}", + mutation_call("set_var") + )); + let hits = env_mutations_in_unserialized_tests(&source); + assert_eq!(hits.len(), 1, "'\\\"' holds the quote: {hits:?}"); + } + + /// `'\''` is the one char literal whose escape matters: the escaped `'` is + /// not the closing `'`. Consuming it as the close leaves a stray quote in + /// the code stream, and here that quote is followed by `,'` — which reads + /// as another char literal opening, so the scan re-enters the literal state + /// one quote out of phase and the `}` after it escapes as code, closing the + /// test before the mutation. + /// + /// The adjacency is what makes this discriminating, and rustfmt would put a + /// space there. The scan runs over every `.rs` file including + /// `#[rustfmt::skip]` ones, so the unformatted shape is in scope. + #[test] + fn an_escaped_quote_does_not_end_a_char_literal_early() { + let source = unguarded_test(&format!( + "let _pair = ('\\'','}}');\n {}", + mutation_call("set_var") + )); + let hits = env_mutations_in_unserialized_tests(&source); + assert_eq!(hits.len(), 1, "the escaped quote is content: {hits:?}"); + } + + /// Rust block comments nest, so the first `*/` does not necessarily end + /// one. Treating it as the end hands the rest of the outer comment to the + /// code stream — here a `}` that closes the test early. + /// + /// The comment spans two lines so the same fixture also pins the newline: + /// collapsing it merges the two source lines and renumbers the mutation, + /// which is the `file:line` the assertion message promises. + #[test] + fn a_nested_block_comment_runs_to_its_outer_close() { + let source = format!( + "#[cfg(test)]\nmod tests {{\n #[test]\n fn t() {{\n\ + \x20 /* outer /* inner */\n\ + \x20 }} still outer */\n\ + \x20 {}\n }}\n}}\n", + mutation_call("set_var") + ); + let hits = env_mutations_in_unserialized_tests(&source); + assert_eq!(hits.len(), 1, "the whole comment is a comment: {hits:?}"); + assert_eq!( + hits[0].line, 7, + "the comment spans lines 5-6, so the mutation is on line 7" + ); + } + + /// `\"` inside a string is content, not the close. Ending the string there + /// spills the rest of the literal into the code stream — here a `}` that + /// closes the test before the mutation is reached. + #[test] + fn an_escaped_quote_in_a_string_does_not_close_it() { + let source = unguarded_test(&format!( + "let _s = \"esc \\\" }}\";\n {}", + mutation_call("set_var") + )); + let hits = env_mutations_in_unserialized_tests(&source); + assert_eq!(hits.len(), 1, "the escaped quote is content: {hits:?}"); + } + + /// A literal may span lines without a continuation backslash. Every + /// literal state has to put the newline back for the same reason the + /// continuation case does: the reported line number is the whole point. + #[test] + fn a_literal_spanning_two_lines_does_not_renumber_them() { + for (opener, closer) in [("\"", "\""), ("r#\"", "\"#")] { + let source = format!( + "#[cfg(test)]\nmod tests {{\n #[test]\n fn t() {{\n\ + \x20 let _s = {opener}multi\nline{closer};\n\ + \x20 {}\n }}\n}}\n", + mutation_call("set_var") + ); + let hits = env_mutations_in_unserialized_tests(&source); + assert_eq!(hits.len(), 1, "{opener}: {hits:?}"); + assert_eq!( + hits[0].line, 7, + "{opener} spans lines 5-6, so the mutation is on line 7" + ); + } + } + + /// A file that ends with a test body still open had its brace bookkeeping + /// defeated by something. Reporting what was collected is the safe + /// direction — over-reporting is visible and gets fixed, a dropped hit is + /// the silent failure this guard exists to prevent — but the exemption + /// still applies, or a correctly locked test would fail the build. + #[test] + fn an_unclosed_test_body_still_reports_what_it_collected() { + let call = mutation_call("set_var"); + let unclosed = + format!("#[cfg(test)]\nmod tests {{\n #[test]\n fn t() {{\n {call}\n"); + assert_eq!( + env_mutations_in_unserialized_tests(&unclosed).len(), + 1, + "a hit collected before the file ran out must not be dropped" + ); + + let unclosed_but_locked = format!( + "#[cfg(test)]\nmod tests {{\n #[test]\n fn t() {{\n\ + \x20 let _guard = SOME_TEST_LOCK.lock().unwrap();\n {call}\n" + ); + assert!( + env_mutations_in_unserialized_tests(&unclosed_but_locked).is_empty(), + "the exemption applies at the end of the file too" + ); + } + + /// The documented limit, pinned so it cannot drift silently. + /// + /// `#[rstest]` and `#[test_case(..)]` both contain `test`; neither is one. + /// Relaxing the last-segment rule to a substring would arm the scan on + /// them, and since neither harness is used in this tree nothing else would + /// notice. + #[test] + fn an_attribute_merely_containing_test_does_not_arm_the_scan() { + for attribute in ["#[rstest]", "#[test_case(1)]", "#[tests]"] { + assert!( + !has_test_attribute(attribute), + "{attribute}'s path does not end in `test`" + ); + } + } + + /// A `#[test]` met while a body is already open belongs to something + /// nested. Re-arming on it starts a fresh body and throws away everything + /// the enclosing test had collected, mutation included. + #[test] + fn a_nested_test_attribute_does_not_restart_the_enclosing_body() { + let source = format!( + "#[cfg(test)]\nmod tests {{\n #[test]\n fn outer() {{\n {}\n\ + \x20 mod inner {{\n #[test]\n fn t() {{}}\n\ + \x20 }}\n }}\n}}\n", + mutation_call("set_var") + ); + let hits = env_mutations_in_unserialized_tests(&source); + assert_eq!(hits.len(), 1, "the outer test's hit survives: {hits:?}"); + assert_eq!(hits[0].line, 5); + } + + /// A lock protects from where it is taken, not retroactively. + /// + /// Matching the whole accumulated body accepted a lock written after the + /// mutation it was supposed to cover — the same race the guard exists to + /// stop, spelled so that the guard agreed with it. + #[test] + fn a_lock_taken_after_the_mutation_does_not_serialize_it() { + let call = mutation_call("set_var"); + let lock = "let _guard = SOME_TEST_LOCK.lock().unwrap();"; + + let late = unguarded_test(&format!("{call}\n {lock}")); + let hits = env_mutations_in_unserialized_tests(&late); + assert_eq!(hits.len(), 1, "the mutation ran unlocked: {hits:?}"); + + let early = unguarded_test(&format!("{lock}\n {call}")); + assert!( + env_mutations_in_unserialized_tests(&early).is_empty(), + "taking the lock first is the discipline this guard asks for" + ); + + // Same line, lock first in source order: still covered. + let same_line = unguarded_test(&format!("{lock} {call}")); + assert!( + env_mutations_in_unserialized_tests(&same_line).is_empty(), + "a lock earlier on the same line precedes the mutation" + ); + } + + /// The suffix rule is a suffix. `NOT_A_TEST_LOCK_HELPER` contains + /// `_TEST_LOCK` and is not a lock, so relaxing the match to a substring + /// would hand out the exemption to whatever happens to be named that way. + #[test] + fn a_name_merely_containing_test_lock_does_not_exempt_anything() { + let source = unguarded_test(&format!( + "let _x = NOT_A_TEST_LOCK_HELPER.get();\n {}", + mutation_call("set_var") + )); + assert_eq!( + env_mutations_in_unserialized_tests(&source).len(), + 1, + "nothing here takes a lock" + ); + } + + /// A mutation sharing the line that opens the test body. + /// + /// The body used to be opened after the line was scanned, so this one line + /// was never looked at. rustfmt splits the shape, which kept it out of + /// sight — but a `#[rustfmt::skip]` test would have gone through in + /// silence, and a guard that can silently stop catching things is the + /// failure mode this file is written against. + #[test] + fn a_mutation_sharing_the_opening_brace_line_is_flagged() { + let source = format!( + "#[cfg(test)]\nmod tests {{\n #[test]\n fn t() {{ {} }}\n}}\n", + mutation_call("set_var") + ); + let hits = env_mutations_in_unserialized_tests(&source); + assert_eq!(hits.len(), 1, "the whole test is on one line: {hits:?}"); + assert_eq!(hits[0].line, 4); + } } From 1b945908d45f4380d2ca3ad875b7148cbdb12fff Mon Sep 17 00:00:00 2001 From: Roman Inflianskas Date: Thu, 24 Sep 2026 14:43:50 +0000 Subject: [PATCH 12/16] docs(testing): make the env-lock example compile, and say what the guard cannot check The snippet called an undefined `production_function()`, so it did not build as pasted -- the earlier claim that it did was made against a copy with that function supplied locally, which is not the same thing. Define it, and verify by extracting the fenced block straight out of the page and building it with `rustc --edition 2024 --test`. Record the two halves of the discipline the guard only half enforces: it now checks that the lock precedes the mutation, and it cannot check that every test touching a key takes the SAME lock, because the keys live in literals the scan strips. Also state at the `engine_envs_dir` override assertions what they cover. `normalize_runtime_path_for_host` is the identity on every non-Windows target, so routing the expected value through it means these cannot fail if the override arm stopped normalising. They pin the override being consulted and the path shape; the normaliser itself is covered on every host by the runtime tests that pass the platform in explicitly. Signed-off-by: Roman Inflianskas --- crates/rocm-core/src/lib.rs | 17 +++++++++++++++++ docs/testing.md | 16 ++++++++++++++++ 2 files changed, 33 insertions(+) diff --git a/crates/rocm-core/src/lib.rs b/crates/rocm-core/src/lib.rs index 192df561c6..b8e2cec63c 100644 --- a/crates/rocm-core/src/lib.rs +++ b/crates/rocm-core/src/lib.rs @@ -12410,6 +12410,19 @@ Class Name: Display // Passed in rather than set via `std::env::set_var`: the environment is // process-global, so mutating it here would race any concurrent test // that reads the same key under a threaded runner. + // + // What this assertion covers is the override being consulted and the + // `//envs` shape built on it. It deliberately does NOT + // claim to cover the host-normalisation step, and routing the expected + // value through the same call the production code makes is why: on a + // non-Windows target `normalize_runtime_path_for_host` is the identity + // for every input (see `normalize_runtime_path_text_for_platform`), so + // dropping normalisation from the override arm cannot fail this on a + // Linux lane — nor, with an already-normal temp path, on a Windows one. + // Making it fail would need the platform threaded through the seam, and + // the normaliser itself is already covered on every host by + // `runtime_path_normalization_accepts_windows_drive_forms` and its + // neighbours, which pass the platform in explicitly. assert_eq!( paths.engine_envs_dir_from("vllm", Some(&override_root)), normalize_runtime_path_for_host(&override_root) @@ -12449,6 +12462,10 @@ Class Name: Display None => unsafe { std::env::remove_var("ROCM_CLI_ENGINE_ENVS_ROOT") }, } + // Same scope as the seam test above: this pins that `engine_envs_dir` + // reaches the variable, not that the value is host-normalised on the + // way through. See that test for why the normalisation step is not + // observable here. assert_eq!( resolved, normalize_runtime_path_for_host(&override_root) diff --git a/docs/testing.md b/docs/testing.md index 9e1f207286..3001155171 100644 --- a/docs/testing.md +++ b/docs/testing.md @@ -48,6 +48,12 @@ env-reading path *is* the point, take a process-wide lock for the duration of the test and restore the previous value before releasing it: ```rust +/// Stands in for the production code under test. It reads `KEY` itself, which +/// is why the test cannot use a seam and has to set a real variable. +fn production_function() -> String { + std::env::var("KEY").unwrap_or_default() +} + /// Serializes every test in this process that replaces `KEY`. static SOMETHING_ENV_TEST_LOCK: std::sync::Mutex<()> = std::sync::Mutex::new(()); @@ -76,6 +82,16 @@ is recognised the day it is declared rather than when someone remembers to add it to a list. The exemption is per test function, not per file: one test taking a lock does not cover its neighbours. +Two things the shape above gets right, both of which the guard checks only +partly: + +- **Take the lock before the mutation.** A lock protects from where it is + acquired, not retroactively. The guard enforces this ordering. +- **Use the same lock as every other test that touches that key.** Two tests + replacing one key under two different mutexes race each other while both + satisfy the guard — it cannot see which key a call names, because the keys + are string literals it strips before scanning. This one is on you. + Keep the mutation and the lock in the same test body. A `#[test]` that delegates its mutation to an unguarded helper is a known blind spot — the helper is a different scope, so the scan cannot see the two together. From 9f02d832ad80297b79db221bb2ae4e9434612de5 Mon Sep 17 00:00:00 2001 From: Roman Inflianskas Date: Wed, 30 Sep 2026 08:38:16 +0000 Subject: [PATCH 13/16] fix(xtask): match an env mutation however the file imports it MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The needles were `env::set_var` and `env::remove_var`, so a test that had written `use std::env::set_var` and called the bare `set_var(..)` — or `use std::env as e` and `e::set_var(..)` — produced no hits at all. Same call, same hazard, invisible to a guard whose whole argument is that it must not fail silently. Matching unqualified covers every spelling. Unqualified alone would over-report: as a bare prefix it also flagged `env::set_variable(..)`, an unrelated function. The trailing `(` pins the match to a call, which closes that class and is stripped back off before the offender is named. Three more findings from the same round, all of them the same mistake in different places — a claim about the scanner that no fixture holds down: * The depth counter's `saturating_sub` was called an equivalent mutant because swapping it for `-` left the suite green. It is not equivalent; the suite simply had no unbalanced input. A plain `-` panics on a leading `}` where this reports nothing. * The first-wins rule on `serialized_at` was unpinned, so letting a later lock overwrite the first would report a mutation that was covered all along — a guard accusing disciplined code. * A raw string's closer is the quote AND its hashes. Consuming only the quote leaks the hashes into the code stream, and a leaked `#` before a `[` spells the `#[` the scan arms on. The byte-string equivalence argument above `raw_string_opener` stays, but its premise was wrong: the stripped text is also read by `serializes` and `has_test_attribute`, not only for braces and `MUTATIONS`. The conclusion holds on those paths too, now for the stated reason. `#[cfg_attr(unix, test)]` does not arm the scan either. Recognising it means parsing the argument list and skipping the first argument, which is the condition — `#[cfg_attr(test, derive(Debug))]` also contains a bare `test` and must keep not arming. A second attribute grammar inside a text scanner, for a spelling this tree does not use and whose idiomatic form the scan already catches, so it joins the stated limits instead. Signed-off-by: Roman Inflianskas --- xtask/src/env_mutation_contract.rs | 149 +++++++++++++++++++++++++++-- 1 file changed, 139 insertions(+), 10 deletions(-) diff --git a/xtask/src/env_mutation_contract.rs b/xtask/src/env_mutation_contract.rs index 5d734f7735..c3d4e00201 100644 --- a/xtask/src/env_mutation_contract.rs +++ b/xtask/src/env_mutation_contract.rs @@ -92,7 +92,18 @@ mod tests { } /// The mutating calls that need serializing. - const MUTATIONS: [&str; 2] = ["env::set_var", "env::remove_var"]; + /// + /// Matched unqualified, because the qualifier is a matter of how the file + /// happens to import: `std::env::set_var(..)`, `env::set_var(..)`, a bare + /// `set_var(..)` after `use std::env::set_var`, and `e::set_var(..)` after + /// `use std::env as e` are all the same call and all hazardous. Keying on + /// `env::` caught only the first two. + /// + /// The trailing `(` is what keeps that widening from over-reporting: it + /// pins the match to a call rather than a prefix, so `env::set_variable(..)` + /// — an unrelated function whose name merely starts the same way — is not + /// an offense. Both directions have fixtures. + const MUTATIONS: [&str; 2] = ["set_var(", "remove_var("]; /// Named helpers that serialize env mutation for their whole scope. /// @@ -284,10 +295,13 @@ mod tests { // no fixture: removing it only means the caller declines at the `b` and // matches one character later at the `r`, which opens the same literal // and strips the same span. The single character of difference is the - // `b` itself, emitted as code rather than as a space — and the stripped - // text is read only for braces and for the names in `MUTATIONS`, so a - // stray `b` cannot change a verdict. An equivalent mutant; a test for it - // would assert nothing. + // `b` itself, emitted as code rather than as a space. Four things read + // the stripped text — the brace counter, the names in `MUTATIONS`, + // [`serializes`] and [`has_test_attribute`] — and a `b` whose only + // neighbour on the right is the stripped literal's run of spaces cannot + // complete a brace, a `set_var(`, a `_TEST_LOCK`/`ScopedTestEnv`, or a + // `#[`. Equivalent on every path that reads it, so a test for it would + // assert nothing. if chars.get(j) == Some(&'b') { j += 1; } @@ -401,6 +415,15 @@ mod tests { /// * Attributes are recognised by path (see [`has_test_attribute`]), so a /// harness whose attribute does not end in `test` — `#[test_case(..)]`, /// `#[rstest]` — would not arm the scan. Neither is used in this tree. + /// * For the same reason `#[cfg_attr(unix, test)]` does not arm it either: + /// the path stops at the `(`, so it reads as `cfg_attr`. Recognising it + /// means parsing the argument list and skipping the FIRST argument, which + /// is the condition — `#[cfg_attr(test, derive(Debug))]` also contains a + /// bare `test` and must keep NOT arming the scan, or the rest of the file + /// reads as one test body. That is a second attribute grammar inside a + /// text scanner, for a spelling this tree does not use and whose + /// idiomatic form — `#[cfg(unix)]` above `#[test]` — this scan does + /// catch. Stated rather than implemented, deliberately. /// * The scan checks that A lock is held, not that it is THE lock every /// other mutator of the same key takes. Two tests replacing one key under /// two different mutexes both pass and still race each other. Closing @@ -456,17 +479,21 @@ mod tests { if let Some(found) = MUTATIONS.iter().find(|needle| code.contains(*needle)) { open.hits.push(Offense { line: index + 1, - call: (*found).to_owned(), + // Without the `(` the needle carries; the offender is + // named by the call, not by the match pattern. + call: found.trim_end_matches('(').to_owned(), }); } } // Saturating purely so a file this scan misreads cannot panic the // build. With literals tokenized away the count is balanced on any - // file that compiles, so the saturation is unreachable in practice - // — it is a backstop, not part of the logic. (Proven by mutation: - // swapping it for a plain `-` leaves the whole suite green, so it - // is an equivalent mutant and no fixture is written for it.) + // file that compiles, so the saturation is unreachable on this + // tree — it is a backstop, not part of the logic. It is still + // load-bearing and still observable: a plain `-` panics with + // `attempt to subtract with overflow` on a leading `}`, where this + // returns no offenses. Pinned by + // `an_unbalanced_close_returns_nothing_rather_than_panicking`. depth = (depth + opens).saturating_sub(closes); if let Some(open) = current.as_ref() @@ -531,6 +558,15 @@ mod tests { format!("unsafe {{ std::env::{kind}(\"KEY\", \"value\") }}") } + /// The same call reached without the `std::env::` qualifier. + /// + /// `use std::env::set_var` leaves `qualifier` empty; `use std::env as e` + /// makes it `e::`. Assembled at runtime for the same reason as + /// [`mutation_call`]. + fn imported_mutation_call(qualifier: &str, kind: &str) -> String { + format!("unsafe {{ {qualifier}{kind}(\"KEY\", \"value\") }}") + } + fn unguarded_test(body: &str) -> String { format!( "#[cfg(test)]\nmod tests {{\n #[test]\n fn t() {{\n {body}\n }}\n}}\n" @@ -578,6 +614,44 @@ mod tests { } } + /// The qualifier is a matter of how the file imports, not of what the call + /// does. Keying the match on `env::` made a test that had written + /// `use std::env::set_var` invisible to the scan while doing exactly the + /// thing the guard exists to stop. + #[test] + fn a_mutation_reached_through_an_import_is_flagged() { + for qualifier in ["", "e::"] { + for kind in ["set_var", "remove_var"] { + let source = unguarded_test(&imported_mutation_call(qualifier, kind)); + let hits = env_mutations_in_unserialized_tests(&source); + assert_eq!( + hits.len(), + 1, + "an unguarded {qualifier}{kind} inside a #[test] must be flagged: {hits:?}" + ); + assert_eq!( + hits[0].call, kind, + "the offender is named by the call, not by the match pattern" + ); + } + } + } + + /// The other side of widening the match: it is a call, not a prefix. + /// + /// Before the trailing `(`, any name merely STARTING `env::set_var` was + /// reported — a build failure naming a function that never touches the + /// environment, which is the same credibility problem as a miss. + #[test] + fn a_call_merely_starting_like_a_mutation_is_not_flagged() { + let source = unguarded_test(&format!("let _ = env::{}able(\"KEY\");", "set_var")); + let hits = env_mutations_in_unserialized_tests(&source); + assert!( + hits.is_empty(), + "set_variable is a different function: {hits:?}" + ); + } + /// An async test is a test. /// /// The scan used to arm on the literal `#[test]`, which left every @@ -808,6 +882,23 @@ mod tests { ); } + /// A raw string's closer is the quote AND its hashes, and all of it has to + /// be consumed. + /// + /// Stopping at the quote returns to the code stream sitting on the hashes, + /// which then leak out as code. A `#` emitted where the source had a + /// literal is how text turns into an attribute: leaked immediately before a + /// `[`, it spells the `#[` that [`has_test_attribute`] arms on. + #[test] + fn a_raw_string_close_consumes_its_hashes() { + let source = "let a = r#\"x\"#;\nlet b = r##\"y\"##;\n"; + let stripped = strip_literals_and_comments(source); + assert!( + !stripped.contains('#'), + "the closing hashes belong to the literal: {stripped:?}" + ); + } + /// A `\` at end of line continues a string literal onto the next one. The /// newline is not part of the string's value, but it is part of the file's /// line structure, and losing it renumbers everything below. @@ -1073,6 +1164,44 @@ mod tests { ); } + /// The serialization point is the FIRST lock, not the last one seen. + /// + /// Letting a later acquisition overwrite it turns the exemption into a + /// false accusation: a test that locks, mutates, then takes a second lock + /// gets reported for a mutation that was covered the whole time. A guard + /// that cries wolf on disciplined code is how a build check stops being + /// believed. + #[test] + fn a_later_lock_does_not_move_the_serialization_point() { + let call = mutation_call("set_var"); + let lock = "let _guard = SOME_TEST_LOCK.lock().unwrap();"; + + let source = unguarded_test(&format!("{lock}\n {call}\n {lock}")); + let hits = env_mutations_in_unserialized_tests(&source); + assert!( + hits.is_empty(), + "the first lock already covered this mutation: {hits:?}" + ); + } + + /// The depth counter saturates, and that is observable behaviour rather + /// than a formality: on a file this scan misreads, a plain `-` panics with + /// `attempt to subtract with overflow` and takes the build down with a + /// message about the guard rather than about the offending test. Saturating + /// reports nothing instead, which is the right answer for a close with + /// nothing open. + /// + /// This was previously called an equivalent mutant on the grounds that + /// swapping the operator left the suite green. It is not: the suite simply + /// had no input in this shape. + #[test] + fn an_unbalanced_close_returns_nothing_rather_than_panicking() { + assert!( + env_mutations_in_unserialized_tests("}\n}\n").is_empty(), + "a close with nothing open is nothing to report" + ); + } + /// The suffix rule is a suffix. `NOT_A_TEST_LOCK_HELPER` contains /// `_TEST_LOCK` and is not a lock, so relaxing the match to a substring /// would hand out the exemption to whatever happens to be named that way. From eeaafec2ab3a91f7493ad6976e28b232549fb5f3 Mon Sep 17 00:00:00 2001 From: Roman Inflianskas Date: Wed, 30 Sep 2026 08:38:23 +0000 Subject: [PATCH 14/16] test(core): restore env vars on unwind rather than on the next line MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Both lock-held tests set their key, called the code under test, then put the old value back in straight-line code. A panic in between skips the restore — and the `*_TEST_LOCK` these tests take is acquired with `PoisonError::into_inner`, deliberately, so a poisoned lock does not cascade. That also means the leak does not stop there: the next test to take the lock reads the value the panicking one planted, usually a temporary directory that has since been deleted. `RestoredEnvVar` moves the restore into `Drop`, where unwinding runs it. It restores but does not serialize, and is deliberately not named like anything in the guard's serializer list, so a test using it still has to take the key's lock. The documented example still shows the straight-line shape, which is what the two tests were copied from; it now says what that shape costs and points at the guard. The attribute blind spots go there too, beside the helper-delegation one that was already written down. Signed-off-by: Roman Inflianskas --- crates/rocm-core/src/fix.rs | 14 +++----- crates/rocm-core/src/lib.rs | 18 +++++----- crates/rocm-core/src/test_env.rs | 56 ++++++++++++++++++++++++++++++++ docs/testing.md | 20 ++++++++++-- 4 files changed, 87 insertions(+), 21 deletions(-) create mode 100644 crates/rocm-core/src/test_env.rs diff --git a/crates/rocm-core/src/fix.rs b/crates/rocm-core/src/fix.rs index fee06c3761..0d10c8a572 100644 --- a/crates/rocm-core/src/fix.rs +++ b/crates/rocm-core/src/fix.rs @@ -1490,7 +1490,6 @@ mod tests { /// It takes the lock rather than a seam because exercising the env read IS /// the point — the escape hatch the contract guard advertises for exactly /// this case. - #[allow(unsafe_code)] // std::env::set_var is unsafe in edition 2024 #[test] fn the_path_fix_reads_rocm_path_from_the_environment() { let _guard = PROCESS_ENV_TEST_LOCK @@ -1504,15 +1503,12 @@ mod tests { let install = root.join("rocm-6.10.0"); plant_install(&install); - let previous = std::env::var_os("ROCM_PATH"); - // SAFETY: the lock above serializes every test in this process that - // touches this key, and the value is restored before it is released. - unsafe { std::env::set_var("ROCM_PATH", &install) }; + // Restored on drop rather than on the next line, so a panic inside the + // resolver cannot leave this key pointing at the directory removed + // below. The lock above is what serializes it; see `RestoredEnvVar`. + let restore = crate::test_env::RestoredEnvVar::set("ROCM_PATH", &install); let found = newest_rocm_install_dir(); - match &previous { - Some(value) => unsafe { std::env::set_var("ROCM_PATH", value) }, - None => unsafe { std::env::remove_var("ROCM_PATH") }, - } + drop(restore); std::fs::remove_dir_all(&root).ok(); diff --git a/crates/rocm-core/src/lib.rs b/crates/rocm-core/src/lib.rs index b8e2cec63c..7d1779150a 100644 --- a/crates/rocm-core/src/lib.rs +++ b/crates/rocm-core/src/lib.rs @@ -34,6 +34,8 @@ pub mod fix; pub mod openmpi; pub mod proc_lifecycle; pub mod runtime; +#[cfg(test)] +mod test_env; pub mod uv; pub use diagnose::{ DiagnoseReport, Diagnosis, Fix, diagnose as run_diagnose, @@ -12443,7 +12445,6 @@ Class Name: Display /// not read the environment — so on their own the production lookup, and /// the key it names, could both be deleted without failing anything. This /// drives `engine_envs_dir` itself against a real variable. - #[allow(unsafe_code)] // std::env::set_var is unsafe in edition 2024 #[test] fn engine_envs_dir_reads_its_root_from_the_environment() { let _guard = ENGINE_ENVS_ENV_TEST_LOCK @@ -12452,15 +12453,14 @@ Class Name: Display let (root, paths) = temp_app_paths("engine-envs-root-env"); let override_root = root.join("runtime").join("engines"); - let previous = std::env::var_os("ROCM_CLI_ENGINE_ENVS_ROOT"); - // SAFETY: the lock above serializes every test in this process that - // touches this key, and the value is restored before it is released. - unsafe { std::env::set_var("ROCM_CLI_ENGINE_ENVS_ROOT", &override_root) }; + // Restored on drop rather than on the next line, so a panic inside + // `engine_envs_dir` cannot leave this key pointing at the directory + // removed below. The lock above is what serializes it; see + // `RestoredEnvVar`. + let restore = + crate::test_env::RestoredEnvVar::set("ROCM_CLI_ENGINE_ENVS_ROOT", &override_root); let resolved = paths.engine_envs_dir("vllm"); - match &previous { - Some(value) => unsafe { std::env::set_var("ROCM_CLI_ENGINE_ENVS_ROOT", value) }, - None => unsafe { std::env::remove_var("ROCM_CLI_ENGINE_ENVS_ROOT") }, - } + drop(restore); // Same scope as the seam test above: this pins that `engine_envs_dir` // reaches the variable, not that the value is host-normalised on the diff --git a/crates/rocm-core/src/test_env.rs b/crates/rocm-core/src/test_env.rs new file mode 100644 index 0000000000..febd1d5553 --- /dev/null +++ b/crates/rocm-core/src/test_env.rs @@ -0,0 +1,56 @@ +// Copyright © Advanced Micro Devices, Inc., or its affiliates. +// +// SPDX-License-Identifier: MIT + +//! Restoring a process environment variable for the duration of a test. +//! +//! A test that replaces a variable, calls into the code under test, and then +//! puts the old value back in straight-line code leaks that variable if +//! anything in between panics. The `*_TEST_LOCK` mutexes these tests take are +//! acquired with [`std::sync::PoisonError::into_inner`], deliberately, so a +//! poisoned lock does not cascade into every later test — which means the leak +//! is not contained either: the next test to take the lock reads the value the +//! panicking one planted, usually pointing at a temporary directory that has +//! since been deleted. +//! +//! [`RestoredEnvVar`] moves the restore into `Drop`, where unwinding runs it. + +use std::ffi::OsString; +use std::path::Path; + +/// Sets an environment variable and puts the previous value back on drop. +/// +/// This RESTORES; it does not SERIALIZE. Two tests holding one of these for the +/// same key still race each other, so the caller must still take the key's +/// `*_TEST_LOCK` first — and because this type is deliberately not named like +/// one, the env-mutation contract guard in `xtask` keeps asking it to. +pub(crate) struct RestoredEnvVar { + key: &'static str, + previous: Option, +} + +impl RestoredEnvVar { + /// Sets `key` to `value`, remembering what was there before. + #[allow(unsafe_code)] // std::env::set_var is unsafe in edition 2024 + pub(crate) fn set(key: &'static str, value: &Path) -> Self { + let previous = std::env::var_os(key); + // SAFETY: every caller holds the process-wide test lock for this key, + // and the value is restored below before that lock is released. + unsafe { std::env::set_var(key, value) }; + Self { key, previous } + } +} + +impl Drop for RestoredEnvVar { + #[allow(unsafe_code)] // std::env::set_var/remove_var are unsafe in edition 2024 + fn drop(&mut self) { + // SAFETY: as above -- still inside the caller's lock scope, since the + // guard is declared after the lock and so drops before it. + unsafe { + match self.previous.as_ref() { + Some(value) => std::env::set_var(self.key, value), + None => std::env::remove_var(self.key), + } + } + } +} diff --git a/docs/testing.md b/docs/testing.md index 3001155171..99342d1c98 100644 --- a/docs/testing.md +++ b/docs/testing.md @@ -92,9 +92,23 @@ partly: satisfy the guard — it cannot see which key a call names, because the keys are string literals it strips before scanning. This one is on you. -Keep the mutation and the lock in the same test body. A `#[test]` that delegates -its mutation to an unguarded helper is a known blind spot — the helper is a -different scope, so the scan cannot see the two together. +Restoring on the next line, as above, leaks the variable if the code under test +panics — and because the lock is taken with `into_inner`, the next test to hold +it reads what the panicking one left behind. `rocm-core`'s `RestoredEnvVar` +(`crates/rocm-core/src/test_env.rs`) moves the restore into `Drop`, where +unwinding runs it; prefer it where one exists. It restores but does not +serialize, so the lock is still yours to take. + +Keep the mutation and the lock in the same test body. Three known blind spots, +all of which the scan reports nothing for: + +- A `#[test]` that delegates its mutation to an unguarded helper — the helper is + a different scope, so the scan cannot see the two together. +- A harness attribute that does not end in `test`, such as `#[test_case(..)]` or + `#[rstest]`. Neither is used in this tree. +- `#[cfg_attr(unix, test)]`, for the same reason: the attribute's path reads as + `cfg_attr`. Write `#[cfg(unix)]` above `#[test]` instead, which the scan + arms on. Run the cross-platform smoke test: From 39d57a26a1a7a87b2887d1862a06e3a1aa63240d Mon Sep 17 00:00:00 2001 From: Roman Inflianskas Date: Wed, 30 Sep 2026 13:04:23 +0000 Subject: [PATCH 15/16] fix(xtask): order the lock against the mutation within a line too MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The serialization point was a line number, so "the lock is taken first in source order" was assumed rather than checked: `set_var(..); let _g = LOCK.lock();` on one line read as serialized. That is the retroactive lock the per-line rule exists to reject, written sideways. It is now a `(line, column)` point on both sides. A lock also has to be ACQUIRED, not merely named — `let _x = &LOCK;` mentions one and holds nothing, and the name match handed that the exemption. Requiring `.lock(` on the naming line would have been the cheap fix and is wrong: rustfmt splits every `*_TEST_LOCK` site in `crates/rocm-core` across three lines, so that rule rejects the whole disciplined population. The acquisition is looked for across the statement instead, and both shapes are pinned by a fixture. The whole-tree assertion was `offenders.is_empty()`, which also holds when the scan entered no test bodies at all. `workspace_rust_sources` pinned that files were found; nothing pinned that test code was reached, so an arming regression would have turned the guard off and read as a green gate — the failure mode this module is written against. The scan now reports bodies entered (3218 today) against a floor well below it. Two claims in `rocm-core` that were more confident than the code: * The ordering test plants its decoy in both layouts, but only the host's own shape was exercised, so deleting the Windows-shaped one left Linux green and waited for the Windows lane. The layout seam already takes the layout, so it is now driven with both and discriminates on every host. * `normalize_runtime_path_for_host` was called the identity for every input. It round-trips through `Path::display()`, which is lossy for a non-UTF-8 path — it returns its input unchanged for the UTF-8 temp paths these tests use, which is what the surrounding argument needs, but it is not a no-op. Signed-off-by: Roman Inflianskas --- crates/rocm-core/src/fix.rs | 30 ++++ crates/rocm-core/src/lib.rs | 12 +- xtask/src/env_mutation_contract.rs | 216 ++++++++++++++++++++++++++--- 3 files changed, 231 insertions(+), 27 deletions(-) diff --git a/crates/rocm-core/src/fix.rs b/crates/rocm-core/src/fix.rs index 0d10c8a572..defd227fe6 100644 --- a/crates/rocm-core/src/fix.rs +++ b/crates/rocm-core/src/fix.rs @@ -1468,6 +1468,29 @@ mod tests { // assertion's point of view, from no decoy at all. let without_override = newest_rocm_install_dir_in(std::slice::from_ref(&searched), None); + // The check above only exercises whichever decoy shape THIS host's + // layout recognises, so deleting the other one leaves Linux green and + // the regression waits for the Windows lane to surface it. The seam + // already takes the layout, so driving it with both discriminates on + // every host for the cost of one loop. + let by_layout: Vec<(crate::RocmLayout, bool)> = [ + (crate::RocmLayout::Siblings, "rocm-6.2.0"), + (crate::RocmLayout::Children, "6.2"), + ] + .into_iter() + .map(|(layout, decoy)| { + let installs = crate::discover_rocm_installs_in_layout( + std::slice::from_ref(&searched), + None, + layout, + ); + ( + layout, + installs.iter().any(|install| install.path.ends_with(decoy)), + ) + }) + .collect(); + std::fs::remove_dir_all(&root).ok(); assert!( @@ -1475,6 +1498,13 @@ mod tests { "the decoy must be reachable through the search roots on this \ platform, or 'the override outranks them' holds vacuously" ); + for (layout, reached) in by_layout { + assert!( + reached, + "the {layout:?} decoy must be reachable under that layout, or \ + the ordering claim is vacuous on the platform that uses it" + ); + } assert_eq!( found, install.to_string_lossy(), diff --git a/crates/rocm-core/src/lib.rs b/crates/rocm-core/src/lib.rs index 7d1779150a..dd38368aab 100644 --- a/crates/rocm-core/src/lib.rs +++ b/crates/rocm-core/src/lib.rs @@ -12417,10 +12417,14 @@ Class Name: Display // `//envs` shape built on it. It deliberately does NOT // claim to cover the host-normalisation step, and routing the expected // value through the same call the production code makes is why: on a - // non-Windows target `normalize_runtime_path_for_host` is the identity - // for every input (see `normalize_runtime_path_text_for_platform`), so - // dropping normalisation from the override arm cannot fail this on a - // Linux lane — nor, with an already-normal temp path, on a Windows one. + // non-Windows target `normalize_runtime_path_for_host` returns its + // input unchanged (see `normalize_runtime_path_text_for_platform`) for + // any path these tests can produce, so dropping normalisation from the + // override arm cannot fail this on a Linux lane — nor, with an + // already-normal temp path, on a Windows one. Not the identity in the + // strict sense: the helper round-trips through `Path::display()`, which + // is lossy for a non-UTF-8 path. Temp paths here are UTF-8, so the + // distinction does not reach this assertion, but it is not a no-op. // Making it fail would need the platform threaded through the seam, and // the normaliser itself is already covered on every host by // `runtime_path_normalization_accepts_windows_drive_forms` and its diff --git a/xtask/src/env_mutation_contract.rs b/xtask/src/env_mutation_contract.rs index c3d4e00201..056acf5dc3 100644 --- a/xtask/src/env_mutation_contract.rs +++ b/xtask/src/env_mutation_contract.rs @@ -108,27 +108,88 @@ mod tests { /// Named helpers that serialize env mutation for their whole scope. /// /// Anything ending `_TEST_LOCK` counts too, and is matched by suffix rather - /// than listed — see [`serializes`]. A fixed list of lock NAMES went stale + /// than listed — see [`lock_name_column`]. A fixed list of lock NAMES went stale /// within days of this guard being written: `main` added /// `UPDATE_CHECK_ENV_TEST_LOCK` and the guard then flagged correctly /// disciplined code and told its author to rename the lock. const NAMED_SERIALIZERS: [&str; 2] = ["ScopedTestEnv", "ScopedEnvVar"]; - /// Whether `text` takes one of the process-wide serializers. - /// - /// The suffix rule recognises the DISCIPLINE rather than a specific lock, so - /// a new `*_TEST_LOCK` is covered the day it is declared. It is a suffix and - /// not a substring on purpose: `NOT_A_TEST_LOCK_HELPER` names something else. + /// Where `line` takes a serializer, as a column, or `None` if it does not. /// /// Applied per LINE by the caller, which is what lets it answer "was the /// lock taken before this mutation?" rather than merely "somewhere in this /// body". Every lock in this tree names itself on the line that acquires it /// (`let _guard = SOME_TEST_LOCK` ...), so a per-line match loses nothing. - fn serializes(text: &str) -> bool { - NAMED_SERIALIZERS.iter().any(|name| text.contains(name)) - || text - .split(|c: char| !(c.is_ascii_alphanumeric() || c == '_')) - .any(|word| word.ends_with("_TEST_LOCK")) + /// + /// A column rather than a bool because that per-line answer is not enough + /// on its own: the caller also has to order the acquisition against a + /// mutation on the SAME line. Comparing by line number alone read + /// `set_var(..); let _g = LOCK.lock();` as serialized, which is the + /// retroactive-lock bug the per-line rule was introduced to stop, written + /// on one line instead of two. + /// + /// A `*_TEST_LOCK` has to be ACQUIRED, not merely named: `let _x = &LOCK;` + /// mentions one and holds nothing. `rest` carries the remainder of the + /// statement for that check, because rustfmt splits the real shape — + /// + /// ```text + /// let _guard = PROCESS_ENV_TEST_LOCK + /// .lock() + /// .unwrap_or_else(std::sync::PoisonError::into_inner); + /// ``` + /// + /// — across three lines, so demanding `.lock(` on the naming line would + /// reject every correctly disciplined test in `crates/rocm-core`. + /// + /// `NAMED_SERIALIZERS` are types, not mutexes, so they carry no `.lock(` + /// and are matched on the name alone. + fn serializer_column(line: &str, rest: &str) -> Option { + if let Some(at) = NAMED_SERIALIZERS.iter().filter_map(|n| line.find(n)).min() { + return Some(at); + } + let at = lock_name_column(line)?; + (line[at..].contains(".lock(") || rest.contains(".lock(")).then_some(at) + } + + /// The column a `*_TEST_LOCK` static is named at. + /// + /// The suffix rule recognises the DISCIPLINE rather than a specific lock, + /// so a new `*_TEST_LOCK` is covered the day it is declared. It is a suffix + /// and not a substring on purpose: `NOT_A_TEST_LOCK_HELPER` names something + /// else. + fn lock_name_column(line: &str) -> Option { + const SUFFIX: &str = "_TEST_LOCK"; + let identifier = |c: char| c.is_ascii_alphanumeric() || c == '_'; + line.match_indices(SUFFIX).find_map(|(at, _)| { + let ends_word = line[at + SUFFIX.len()..] + .chars() + .next() + .is_none_or(|c| !identifier(c)); + let start = line[..at] + .rfind(|c: char| !identifier(c)) + .map_or(0, |i| i + 1); + ends_word.then_some(start) + }) + } + + /// The rest of the statement beginning at `lines[index]`. + /// + /// Empty when that line already ends the statement. Bounded, because a line + /// with no `;` after it at all — the last line of a truncated file — would + /// otherwise drag the whole remainder of the body in; rustfmt's widest + /// split of a lock acquisition is three lines. + fn statement_continuation(lines: &[&str], index: usize) -> String { + if lines.get(index).is_some_and(|line| line.contains(';')) { + return String::new(); + } + let mut out = String::new(); + for line in lines.iter().skip(index + 1).take(4) { + out.push_str(line); + if line.contains(';') { + break; + } + } + out } /// Replace the CONTENTS of string literals, char literals and comments with @@ -297,7 +358,7 @@ mod tests { // and strips the same span. The single character of difference is the // `b` itself, emitted as code rather than as a space. Four things read // the stripped text — the brace counter, the names in `MUTATIONS`, - // [`serializes`] and [`has_test_attribute`] — and a `b` whose only + // [`serializer_column`] and [`has_test_attribute`] — and a `b` whose only // neighbour on the right is the stripped literal's run of spaces cannot // complete a brace, a `set_var(`, a `_TEST_LOCK`/`ScopedTestEnv`, or a // `#[`. Equivalent on every path that reads it, so a test for it would @@ -368,6 +429,10 @@ mod tests { #[derive(Clone, Debug, PartialEq, Eq)] struct Offense { line: usize, + /// Column the call starts at, used only to order it against a + /// serializer taken on the same line. Never reported: the offender is + /// located by `file:line`, and a column would go stale under rustfmt. + column: usize, call: String, } @@ -375,9 +440,11 @@ mod tests { struct OpenTest { /// The brace depth the body opened at; it closes on the way back down. open_depth: usize, - /// The first line that took a serializer, if any. A mutation is exempt - /// only from that line ONWARD — see [`OpenTest::unserialized_hits`]. - serialized_at: Option, + /// Where the first serializer was taken, as `(line, column)`, if any. A + /// mutation is exempt only from that POINT onward — see + /// [`OpenTest::unserialized_hits`]. The column is what keeps a lock + /// written after a mutation on the same line from covering it. + serialized_at: Option<(usize, usize)>, hits: Vec, } @@ -392,7 +459,10 @@ mod tests { fn unserialized_hits(&self) -> impl Iterator + '_ { self.hits .iter() - .filter(move |hit| self.serialized_at.is_none_or(|at| hit.line < at)) + .filter(move |hit| { + self.serialized_at + .is_none_or(|at| (hit.line, hit.column) < at) + }) .cloned() } } @@ -436,13 +506,30 @@ mod tests { /// production code, and test-support types such as `ScopedTestEnv` whose /// whole job is to perform the mutation on a test's behalf. fn env_mutations_in_unserialized_tests(text: &str) -> Vec { + scan(text).offenses + } + + /// What one pass over a file saw. + /// + /// `bodies` exists so the whole-tree assertion can tell "no offenders" from + /// "nothing was scanned" — see + /// `the_whole_tree_scan_actually_enters_test_bodies`. + struct Scan { + offenses: Vec, + bodies: usize, + } + + fn scan(text: &str) -> Scan { let stripped = strip_literals_and_comments(text); + let lines: Vec<&str> = stripped.lines().collect(); let mut offenses = Vec::new(); + let mut bodies = 0usize; let mut depth: usize = 0; let mut pending_test_attr = false; let mut current: Option = None; - for (index, line) in stripped.lines().enumerate() { + for index in 0..lines.len() { + let line = lines[index]; let code = line.trim(); if current.is_none() && has_test_attribute(code) { @@ -459,6 +546,7 @@ mod tests { // that one used to slip through in silence. if pending_test_attr && opens > 0 { pending_test_attr = false; + bodies += 1; current = Some(OpenTest { open_depth: depth, serialized_at: None, @@ -471,14 +559,20 @@ mod tests { } if let Some(open) = current.as_mut() { - // Before the hit, so a lock and a mutation on ONE line counts as - // serialized -- the lock is taken first in source order. - if open.serialized_at.is_none() && serializes(code) { - open.serialized_at = Some(index + 1); + if open.serialized_at.is_none() + && let Some(column) = + serializer_column(code, &statement_continuation(&lines, index)) + { + open.serialized_at = Some((index + 1, column)); } - if let Some(found) = MUTATIONS.iter().find(|needle| code.contains(*needle)) { + if let Some((column, found)) = MUTATIONS + .iter() + .filter_map(|needle| code.find(*needle).map(|at| (at, *needle))) + .min() + { open.hits.push(Offense { line: index + 1, + column, // Without the `(` the needle carries; the offender is // named by the call, not by the match pattern. call: found.trim_end_matches('(').to_owned(), @@ -513,7 +607,7 @@ mod tests { offenses.extend(open.unserialized_hits()); } - offenses + Scan { offenses, bodies } } #[test] @@ -547,6 +641,40 @@ mod tests { ); } + /// The whole-tree assertion above is `offenders.is_empty()`, which also + /// holds when the scan entered no test bodies at all. + /// + /// `workspace_rust_sources` pins that files were found; nothing pinned that + /// test code inside them was reached. An arming regression — the attribute + /// rule narrowing, the brace bookkeeping closing bodies early — would turn + /// the guard off and read as a green gate, which is the one failure mode + /// this module is written against. + /// + /// The floor is deliberately far below the real count (3218 at the time of + /// writing) and is not a census: it has to survive tests being added and + /// removed without anyone remembering this number, while still failing + /// loudly if arming collapses. + #[test] + fn the_whole_tree_scan_actually_enters_test_bodies() { + const FLOOR: usize = 500; + + let bodies: usize = workspace_rust_sources() + .iter() + .map(|path| { + let text = std::fs::read_to_string(path) + .unwrap_or_else(|e| panic!("reading {}: {e}", path.display())); + scan(&text).bodies + }) + .sum(); + + assert!( + bodies >= FLOOR, + "the scan entered {bodies} test bodies across the tree, under the \ + {FLOOR} floor -- the guard is not looking at test code any more, \ + so its green result means nothing" + ); + } + /// A mutating call, assembled at runtime. /// /// Spelling `env::set_var` literally in a fixture would make this file's own @@ -1162,6 +1290,48 @@ mod tests { env_mutations_in_unserialized_tests(&same_line).is_empty(), "a lock earlier on the same line precedes the mutation" ); + + // ...and the same line the other way round is NOT. Ordering by line + // number alone accepted this, which is the same retroactive lock the + // per-line rule rejects when it is written on the next line down. + let same_line_late = unguarded_test(&format!("{call} {lock}")); + let hits = env_mutations_in_unserialized_tests(&same_line_late); + assert_eq!( + hits.len(), + 1, + "the mutation ran before the lock on that line: {hits:?}" + ); + } + + /// A lock has to be ACQUIRED, not merely named. `let _x = &LOCK;` mentions + /// one and holds nothing, and matching the name alone handed that the + /// exemption. + /// + /// The acquisition is looked for across the statement rather than the line, + /// because rustfmt splits the real shape in this repo over three lines — + /// which is why "require `.lock(` on the naming line" is not the fix: it + /// would reject every disciplined test in `crates/rocm-core`. Both shapes + /// are asserted here so neither can regress into the other. + #[test] + fn a_lock_that_is_named_but_not_taken_does_not_serialize_anything() { + let call = mutation_call("set_var"); + + let named_only = unguarded_test(&format!("let _x = &SOME_TEST_LOCK;\n {call}")); + let hits = env_mutations_in_unserialized_tests(&named_only); + assert_eq!(hits.len(), 1, "naming a lock is not holding it: {hits:?}"); + + for acquisition in [ + "let _guard = SOME_TEST_LOCK.lock().unwrap();", + // rustfmt's split, as every `*_TEST_LOCK` site in `rocm-core` is + // actually written. + "let _guard = SOME_TEST_LOCK\n .lock()\n .unwrap_or_else(std::sync::PoisonError::into_inner);", + ] { + let source = unguarded_test(&format!("{acquisition}\n {call}")); + assert!( + env_mutations_in_unserialized_tests(&source).is_empty(), + "this lock is taken, however rustfmt broke the lines up" + ); + } } /// The serialization point is the FIRST lock, not the last one seen. From f8265b068d6a4f69d7e886fb0a4854ced5abecff Mon Sep 17 00:00:00 2001 From: Roman Inflianskas Date: Thu, 1 Oct 2026 10:39:38 +0000 Subject: [PATCH 16/16] fix(xtask): close the wrapper blind spot and drop a hollow exemption Three defects in the guard this change introduces, all of them places where the stated rule and the enforced rule had come apart. The two tests designated as the sanctioned exception sat outside the guard entirely. The scanner matches call text, and spelling the mutation as a method on a restoring wrapper contains neither direct call -- so deleting their lock acquisition left the whole-tree scan green, while three comments told the next contributor the build would catch them. Name `RestoredEnvVar::set(` in the mutation list, which makes those comments true: removing the lock from either site now fails the scan naming the exact line. The comments and `docs/testing.md` say plainly that the coverage comes from the listing, so a restoring helper added later is understood to be outside the guard until it is listed too. `ScopedEnvVar` was on the named-serializer exemption list and serializes nothing -- it saves and restores, and its one caller takes `BUILTIN_ENGINE_ENV_LOCK` itself. The type is visible to the largest test module in the tree, in the same file, so naming it granted the full exemption while holding nothing. Dropped from the list, the fixture (whose constructor signature did not exist) and the documentation. Six branches from the preceding commits survived mutation with the suite green. One discriminating fixture each: a self-terminating naming line followed by an unrelated acquisition, a statement ending inside the lookahead window, an acquisition split wider than it, two mutations on one line out of list order, and an identifier merely carrying the `_TEST_LOCK` suffix. Each mutation now fails exactly its own fixture and no other. The `.min()` over the named-serializer list became equivalent to first-in-list when that list dropped to one entry; that one is documented as equivalent rather than given a fixture it cannot have. Signed-off-by: Roman Inflianskas --- crates/rocm-core/src/fix.rs | 4 +- crates/rocm-core/src/lib.rs | 5 +- crates/rocm-core/src/test_env.rs | 8 +- docs/testing.md | 11 +- xtask/src/env_mutation_contract.rs | 200 ++++++++++++++++++++++++++++- 5 files changed, 215 insertions(+), 13 deletions(-) diff --git a/crates/rocm-core/src/fix.rs b/crates/rocm-core/src/fix.rs index defd227fe6..4462dd7cc4 100644 --- a/crates/rocm-core/src/fix.rs +++ b/crates/rocm-core/src/fix.rs @@ -1535,7 +1535,9 @@ mod tests { // Restored on drop rather than on the next line, so a panic inside the // resolver cannot leave this key pointing at the directory removed - // below. The lock above is what serializes it; see `RestoredEnvVar`. + // below. `RestoredEnvVar` only restores; the lock above is what + // serializes, and the contract guard requires it here because + // `RestoredEnvVar::set(` is in its mutation list. let restore = crate::test_env::RestoredEnvVar::set("ROCM_PATH", &install); let found = newest_rocm_install_dir(); drop(restore); diff --git a/crates/rocm-core/src/lib.rs b/crates/rocm-core/src/lib.rs index dd38368aab..a656a9a367 100644 --- a/crates/rocm-core/src/lib.rs +++ b/crates/rocm-core/src/lib.rs @@ -12459,8 +12459,9 @@ Class Name: Display // Restored on drop rather than on the next line, so a panic inside // `engine_envs_dir` cannot leave this key pointing at the directory - // removed below. The lock above is what serializes it; see - // `RestoredEnvVar`. + // removed below. `RestoredEnvVar` only restores; the lock above is what + // serializes, and the contract guard requires it here because + // `RestoredEnvVar::set(` is in its mutation list. let restore = crate::test_env::RestoredEnvVar::set("ROCM_CLI_ENGINE_ENVS_ROOT", &override_root); let resolved = paths.engine_envs_dir("vllm"); diff --git a/crates/rocm-core/src/test_env.rs b/crates/rocm-core/src/test_env.rs index febd1d5553..7e5bd9da58 100644 --- a/crates/rocm-core/src/test_env.rs +++ b/crates/rocm-core/src/test_env.rs @@ -22,8 +22,12 @@ use std::path::Path; /// /// This RESTORES; it does not SERIALIZE. Two tests holding one of these for the /// same key still race each other, so the caller must still take the key's -/// `*_TEST_LOCK` first — and because this type is deliberately not named like -/// one, the env-mutation contract guard in `xtask` keeps asking it to. +/// `*_TEST_LOCK` first. +/// +/// The env-mutation contract guard in `xtask` enforces that, but only because +/// `RestoredEnvVar::set(` is named in its `MUTATIONS` list. The guard matches +/// call TEXT, so wrapping a mutation in a method hides it by default — a +/// restoring helper added later is outside the guard until it is listed too. pub(crate) struct RestoredEnvVar { key: &'static str, previous: Option, diff --git a/docs/testing.md b/docs/testing.md index 99342d1c98..c4f249acc6 100644 --- a/docs/testing.md +++ b/docs/testing.md @@ -76,8 +76,8 @@ fn reads_its_setting_from_the_environment() { } ``` -The guard accepts `ScopedTestEnv`, `ScopedEnvVar`, or **any** static named -`*_TEST_LOCK` taken inside the test body. The suffix is the rule, so a new lock +The guard accepts `ScopedTestEnv` or **any** static named `*_TEST_LOCK` taken +inside the test body. The suffix is the rule, so a new lock is recognised the day it is declared rather than when someone remembers to add it to a list. The exemption is per test function, not per file: one test taking a lock does not cover its neighbours. @@ -102,8 +102,11 @@ serialize, so the lock is still yours to take. Keep the mutation and the lock in the same test body. Three known blind spots, all of which the scan reports nothing for: -- A `#[test]` that delegates its mutation to an unguarded helper — the helper is - a different scope, so the scan cannot see the two together. +- A `#[test]` that delegates its mutation to a helper — the helper's body is a + different scope, so the scan cannot see the two together. It matches call + text, so a wrapper hides the mutation until the wrapper itself is named in the + scanner's `MUTATIONS` list, as `RestoredEnvVar::set(` is. Add a new restoring + helper to that list, or it is outside the guard. - A harness attribute that does not end in `test`, such as `#[test_case(..)]` or `#[rstest]`. Neither is used in this tree. - `#[cfg_attr(unix, test)]`, for the same reason: the attribute's path reads as diff --git a/xtask/src/env_mutation_contract.rs b/xtask/src/env_mutation_contract.rs index 056acf5dc3..d035f80423 100644 --- a/xtask/src/env_mutation_contract.rs +++ b/xtask/src/env_mutation_contract.rs @@ -103,16 +103,33 @@ mod tests { /// pins the match to a call rather than a prefix, so `env::set_variable(..)` /// — an unrelated function whose name merely starts the same way — is not /// an offense. Both directions have fixtures. - const MUTATIONS: [&str; 2] = ["set_var(", "remove_var("]; + /// `RestoredEnvVar::set(` is here because the guard matches TEXT, and a + /// mutation spelled as a method on a restoring wrapper contains neither + /// direct call. The two tests that use it are the sanctioned exception this + /// change documents, and before this entry existed they sat outside the + /// guard entirely — deleting their lock acquisition left the scan green, + /// which is the opposite of what their comments told the next contributor. + /// Listing the helper keeps the escape hatch narrow: it is still the lock + /// that is required, the wrapper just stops hiding the requirement. + const MUTATIONS: [&str; 3] = ["set_var(", "remove_var(", "RestoredEnvVar::set("]; /// Named helpers that serialize env mutation for their whole scope. /// + /// Membership is "holds a lock for its whole scope", not "wraps an env + /// mutation". `ScopedEnvVar` (`apps/rocm/src/main.rs`) was listed here and + /// only ever saved and restored — its one caller, + /// `with_scoped_builtin_engine_env`, takes `BUILTIN_ENGINE_ENV_LOCK` + /// itself. The type is visible to the largest test module in the tree, in + /// the same file, so any test that merely named it was granted the full + /// exemption while holding nothing: the exact failure this guard exists to + /// prevent, written into the guard. + /// /// Anything ending `_TEST_LOCK` counts too, and is matched by suffix rather /// than listed — see [`lock_name_column`]. A fixed list of lock NAMES went stale /// within days of this guard being written: `main` added /// `UPDATE_CHECK_ENV_TEST_LOCK` and the guard then flagged correctly /// disciplined code and told its author to rename the lock. - const NAMED_SERIALIZERS: [&str; 2] = ["ScopedTestEnv", "ScopedEnvVar"]; + const NAMED_SERIALIZERS: [&str; 1] = ["ScopedTestEnv"]; /// Where `line` takes a serializer, as a column, or `None` if it does not. /// @@ -143,6 +160,13 @@ mod tests { /// /// `NAMED_SERIALIZERS` are types, not mutexes, so they carry no `.lock(` /// and are matched on the name alone. + /// + /// The `.min()` over that list is equivalent to taking its first element + /// while the list holds one entry, so no fixture can distinguish them — + /// stated rather than tested. It earns its keep the moment a second name is + /// added, which is why it is written positionally now; the equivalent + /// choice over [`MUTATIONS`], which does hold several, is pinned by + /// [`the_reported_mutation_is_the_leftmost_one_on_the_line`]. fn serializer_column(line: &str, rest: &str) -> Option { if let Some(at) = NAMED_SERIALIZERS.iter().filter_map(|n| line.find(n)).min() { return Some(at); @@ -695,6 +719,15 @@ mod tests { format!("unsafe {{ {qualifier}{kind}(\"KEY\", \"value\") }}") } + /// A mutation spelled as a method on a restoring wrapper. + /// + /// Assembled rather than written out for the same reason as + /// [`mutation_call`]: a fixture containing the literal text would make this + /// file match its own scan. + fn delegated_mutation_call(path: &str) -> String { + format!("let _restore = crate::test_env::{path}(\"KEY\", &value);") + } + fn unguarded_test(body: &str) -> String { format!( "#[cfg(test)]\nmod tests {{\n #[test]\n fn t() {{\n {body}\n }}\n}}\n" @@ -727,9 +760,10 @@ mod tests { #[test] fn every_mutating_call_is_flagged_inside_an_unguarded_test() { let kinds = ["set_var", "remove_var"]; + let delegated = ["RestoredEnvVar::set"]; assert_eq!( MUTATIONS.len(), - kinds.len(), + kinds.len() + delegated.len(), "a call was added to MUTATIONS without a case here" ); for kind in kinds { @@ -740,6 +774,41 @@ mod tests { "an unguarded std::env::{kind} inside a #[test] must be flagged" ); } + for path in delegated { + let source = unguarded_test(&delegated_mutation_call(path)); + assert_eq!( + env_mutations_in_unserialized_tests(&source).len(), + 1, + "an unguarded {path} inside a #[test] must be flagged" + ); + } + } + + /// A restoring wrapper does not exempt the test that drives it. + /// + /// The wrapper restores; it does not serialize. Taking the key's lock first + /// is still required, and because the call text carries neither direct + /// mutation the guard only enforces that while the helper is named in + /// [`MUTATIONS`]. Both directions are pinned: unguarded is an offense, + /// guarded is not. + #[test] + fn a_mutation_delegated_to_a_restoring_wrapper_still_needs_the_lock() { + let call = delegated_mutation_call("RestoredEnvVar::set"); + + let hits = env_mutations_in_unserialized_tests(&unguarded_test(&call)); + assert_eq!(hits.len(), 1, "the wrapper does not serialize: {hits:?}"); + assert_eq!( + hits[0].call, "RestoredEnvVar::set", + "the offender is named by the call" + ); + + let guarded = unguarded_test(&format!( + "let _guard = SOME_TEST_LOCK.lock().unwrap();\n {call}" + )); + assert!( + env_mutations_in_unserialized_tests(&guarded).is_empty(), + "the lock above is what makes this shape acceptable" + ); } /// The qualifier is a matter of how the file imports, not of what the call @@ -881,7 +950,6 @@ mod tests { for marker in [ "let _env = ScopedTestEnv::new();", - "let _env = ScopedEnvVar::new(\"K\");", "let _guard = PROCESS_ENV_TEST_LOCK.lock().unwrap();", // The suffix rule: a lock this guard has never heard of. "let _guard = SOME_BRAND_NEW_TEST_LOCK.lock().unwrap();", @@ -1354,6 +1422,130 @@ mod tests { ); } + /// A statement that ends on its own line pulls in no continuation. + /// + /// [`statement_continuation`] returns early on a line already carrying its + /// `;`. Without that early return it would read the lines BELOW as part of + /// the statement, so a line that merely NAMES a lock would borrow the + /// `.lock(` from an unrelated acquisition further down and hand out the + /// exemption retroactively — the mutation here sits between the two. + /// + /// The loop's `break` on the terminator is pinned separately, by + /// [`a_statement_ending_inside_the_window_stops_the_walk_there`]: the early + /// return means a line carrying its own `;` never reaches the loop at all. + #[test] + fn a_self_terminating_line_does_not_borrow_a_later_acquisition() { + let call = mutation_call("set_var"); + let source = unguarded_test(&format!( + "let _x = &SOME_TEST_LOCK;\n {call}\n \ + let _real = OTHER_TEST_LOCK.lock().unwrap();" + )); + let hits = env_mutations_in_unserialized_tests(&source); + assert_eq!( + hits.len(), + 1, + "the naming line ended its own statement; the lock below it covers nothing \ + above it: {hits:?}" + ); + } + + /// The continuation window is bounded, and the bound is load-bearing in + /// both directions. + /// + /// Too narrow and rustfmt's real three-line split of a lock acquisition + /// stops being recognised, which rejects every disciplined test in + /// `rocm-core` — that direction is pinned by + /// [`a_lock_that_is_named_but_not_taken_does_not_serialize_anything`]. Too + /// wide and the walk keeps running past the end of the statement into + /// whatever follows, so an acquisition that is nowhere near the naming line + /// still exempts it. This fixture splits one wider than the window. + #[test] + fn an_acquisition_split_wider_than_the_window_is_not_credited() { + let call = mutation_call("set_var"); + let padding = "\n // filler\n".repeat(5); + let source = unguarded_test(&format!( + "let _guard = SOME_TEST_LOCK{padding} .lock()\n .unwrap();\n {call}" + )); + let hits = env_mutations_in_unserialized_tests(&source); + assert_eq!( + hits.len(), + 1, + "the acquisition is further from its name than the window reaches: {hits:?}" + ); + } + + /// A statement that ends partway through the window stops the walk there. + /// + /// The naming line carries no `;`, so it does reach the loop — and the loop + /// must stop at the line that terminates the statement. Without the + /// `break` it keeps reading to the window's edge and picks up an unrelated + /// acquisition below the mutation, exempting a mutation that ran first. + /// + /// The `.clone()` continuation is what makes this distinct from + /// [`a_self_terminating_line_does_not_borrow_a_later_acquisition`], which + /// never enters the loop. + #[test] + fn a_statement_ending_inside_the_window_stops_the_walk_there() { + let call = mutation_call("set_var"); + let source = unguarded_test(&format!( + "let _x = &SOME_TEST_LOCK\n .clone();\n {call}\n \ + let _real = OTHER_TEST_LOCK.lock().unwrap();" + )); + let hits = env_mutations_in_unserialized_tests(&source); + assert_eq!( + hits.len(), + 1, + "the statement ended at `.clone();`; nothing below it belongs to it: {hits:?}" + ); + } + + /// The offense is the LEFTMOST mutation on the line, not the first one that + /// happens to be listed in [`MUTATIONS`]. + /// + /// The reported column is what orders the mutation against a lock taken on + /// the same line, so picking by list order instead of position is a silent + /// false negative: here the mutation that ran BEFORE the lock is the one + /// later in the list, and taking the list's first reports a column to the + /// right of the acquisition, which reads as serialized. + #[test] + fn the_reported_mutation_is_the_leftmost_one_on_the_line() { + let source = unguarded_test(&format!( + "{} let _g = SOME_TEST_LOCK.lock().unwrap(); {}", + mutation_call("remove_var"), + mutation_call("set_var") + )); + let hits = env_mutations_in_unserialized_tests(&source); + assert_eq!( + hits.len(), + 1, + "the mutation left of the lock is unserialized: {hits:?}" + ); + assert_eq!( + hits[0].call, "remove_var", + "the leftmost call is the one that ran before the lock" + ); + } + + /// `_TEST_LOCK` has to END the identifier. + /// + /// Dropping the word-boundary check hands the exemption to anything merely + /// CARRYING the suffix — `SOME_TEST_LOCK_HELPER` is a different item, and a + /// test naming one holds no lock at all. A false negative, and a silent + /// one: the guard reports nothing and the race stays. + #[test] + fn an_identifier_merely_carrying_the_lock_suffix_is_not_a_lock() { + let call = mutation_call("set_var"); + let source = unguarded_test(&format!( + "let _h = SOME_TEST_LOCK_HELPER.lock().unwrap();\n {call}" + )); + let hits = env_mutations_in_unserialized_tests(&source); + assert_eq!( + hits.len(), + 1, + "`SOME_TEST_LOCK_HELPER` is not a `*_TEST_LOCK`: {hits:?}" + ); + } + /// The depth counter saturates, and that is observable behaviour rather /// than a formality: on a file this scan misreads, a plain `-` panics with /// `attempt to subtract with overflow` and takes the build down with a