fix(mutation): honor test filters/isolation, tighten cache key, drop compound assignment mutation, reject incompatible flags

- runner: thread FilterArgs and --isolate through MutationRunConfig into
  compile_and_test_inner; rebuild ProjectPathsAwareFilter against the
  per-mutant temp config so --match-test/--match-contract/--match-path
  work and mutants exercise the same test set/execution model as baseline
- mod: add runtime_context_digest folded into the per-file cache key so
  cached results aren't reused when filters, isolation, fork URL/block,
  sender, or initial_balance change
- orchestrator: compute runtime_context_digest once per run and bind it
  to every MutationHandler
- binary_op_mutator: stop mutating compound assignments (a += b would
  silently be rewritten to a - b dropping the assignment); add regression
  tests
- cmd/test: bail when --mutate is combined with --list/--debug/
  --flamegraph/--flamechart/--junit instead of silently mixing modes
- fs_permissions guard now narrowed to permissions whose path can reach
  symlinked dependency trees (lib/node_modules/dependencies)

Amp-Thread-ID: https://ampcode.com/threads/T-019e4567-e7ca-717e-bcc0-bb67a3667c4d
Co-authored-by: Amp <amp@ampcode.com>

Author: 2 people

crates/forge/src/cmd/test/mod.rs

@@ -1,4 +1,4 @@
-use super::{install, test::filter::ProjectPathsAwareFilter, watch::WatchArgs};
+use super::{install, watch::WatchArgs};
 use crate::{
     MultiContractRunner, MultiContractRunnerBuilder,
     decode::decode_console_logs,
@@ -64,7 +64,7 @@ use yansi::Paint;
 mod filter;
 mod summary;
 use crate::{result::TestKind, traces::render_trace_arena_inner};
-pub use filter::FilterArgs;
+pub use filter::{FilterArgs, ProjectPathsAwareFilter};
 use quick_junit::{NonSuccessKind, Report, TestCase, TestCaseStatus, TestSuite};
 use summary::{TestSummaryReport, format_invariant_metrics_table};
 
@@ -353,6 +353,39 @@ impl TestArgs {
             bail!("`fuzz.run` must be greater than 0");
         }
 
+        // Mutation testing has bespoke orchestration (per-mutant temp
+        // workspaces, baseline + N mutants, aggregated mutation report). It is
+        // not compatible with the single-run debug / flame / list / junit
+        // modes — running them together would either mix incompatible output
+        // formats, or run the secondary mode against the baseline tests and
+        // then silently continue into mutation testing. Reject up front with a
+        // clear error rather than do the wrong thing.
+        if self.mutate.is_some() {
+            let mut conflicts = Vec::new();
+            if self.list {
+                conflicts.push("--list");
+            }
+            if self.debug {
+                conflicts.push("--debug");
+            }
+            if self.flamegraph {
+                conflicts.push("--flamegraph");
+            }
+            if self.flamechart {
+                conflicts.push("--flamechart");
+            }
+            if self.junit {
+                conflicts.push("--junit");
+            }
+            if !conflicts.is_empty() {
+                bail!(
+                    "`--mutate` cannot be combined with: {}. Re-run without those flags to use \
+                     mutation testing.",
+                    conflicts.join(", ")
+                );
+            }
+        }
+
         // Explicitly enable isolation for gas reports for more correct gas accounting.
         if self.gas_report {
             evm_opts.isolate = true;
@@ -582,9 +615,6 @@ impl TestArgs {
             // Detect both up front so users aren't surprised by races or
             // corruption of their real dependency tree.
             use foundry_config::fs_permissions::FsAccessPermission;
-            let has_broad_write = config_for_mutation.fs_permissions.permissions.iter().any(|p| {
-                matches!(p.access, FsAccessPermission::Write | FsAccessPermission::ReadWrite)
-            });
             if config_for_mutation.ffi {
                 eyre::bail!(
                     "Mutation testing is unsafe with `ffi = true`: per-mutant workspaces share \
@@ -593,13 +623,58 @@ impl TestArgs {
                      Disable ffi in your foundry.toml to run mutation tests."
                 );
             }
-            if has_broad_write {
+
+            // Only refuse write-capable `fs_permissions` whose path can actually
+            // reach one of the symlinked dependency trees. Scoped writes (e.g.
+            // `./out`, `./snapshots`) are safe because they target paths that
+            // never resolve into the shared `lib`/`node_modules`/`dependencies`
+            // trees.
+            let root = &config_for_mutation.root;
+            let mut shared_dep_dirs: Vec<PathBuf> = config_for_mutation.libs.clone();
+            shared_dep_dirs.push(root.join("node_modules"));
+            shared_dep_dirs.push(root.join("dependencies"));
+            let shared_dep_dirs: Vec<PathBuf> =
+                shared_dep_dirs.into_iter().map(|p| dunce::canonicalize(&p).unwrap_or(p)).collect();
+
+            let touches_shared_dep = |perm_path: &Path| -> bool {
+                let resolved = if perm_path.is_absolute() {
+                    perm_path.to_path_buf()
+                } else {
+                    root.join(perm_path)
+                };
+                let canon = dunce::canonicalize(&resolved).unwrap_or(resolved);
+                shared_dep_dirs.iter().any(|dep| {
+                    // Either the permission path is inside a shared dep dir
+                    // (write directly into deps), or it is an ancestor of one
+                    // (broad permission like `./` covers them transitively).
+                    canon.starts_with(dep) || dep.starts_with(&canon)
+                })
+            };
+
+            let unsafe_write_paths: Vec<&Path> = config_for_mutation
+                .fs_permissions
+                .permissions
+                .iter()
+                .filter(|p| {
+                    matches!(p.access, FsAccessPermission::Write | FsAccessPermission::ReadWrite)
+                })
+                .filter(|p| touches_shared_dep(&p.path))
+                .map(|p| p.path.as_path())
+                .collect();
+
+            if !unsafe_write_paths.is_empty() {
+                let paths = unsafe_write_paths
+                    .iter()
+                    .map(|p| format!("  - {}", p.display()))
+                    .collect::<Vec<_>>()
+                    .join("\n");
                 eyre::bail!(
-                    "Mutation testing is unsafe with write-capable `fs_permissions`: per-mutant \
-                     workspaces share symlinked dependency directories, and `vm.writeFile` \
-                     calls can race against or corrupt the real `lib`/`node_modules`/\
-                     `dependencies` trees. Restrict `fs_permissions` to read-only (or scope it \
-                     away from dependency paths) to run mutation tests."
+                    "Mutation testing is unsafe with write-capable `fs_permissions` that can \
+                     reach the symlinked dependency trees (`lib`/`node_modules`/`dependencies`); \
+                     per-mutant workspaces share those trees, so `vm.writeFile` calls would race \
+                     against or corrupt your real dependencies. Restrict the following \
+                     `fs_permissions` entries to read-only or scope them away from dependency \
+                     paths:\n{paths}"
                 );
             }
 
@@ -612,6 +687,13 @@ impl TestArgs {
                 num_workers: self.mutation_jobs.unwrap_or(0),
                 show_progress: self.show_progress,
                 json_output,
+                // Carry the same filter args (--match-test, --match-contract,
+                // --match-path, ...) and isolation flag the baseline run used,
+                // so every mutant exercises the exact same test set under the
+                // same execution model. Without this, mutant runs silently
+                // diverge from baseline and produce false kills/survivors.
+                filter_args: self.filter.clone(),
+                isolate: evm_opts_for_mutation.isolate,
             };
 
             let result = run_mutation_testing(

crates/forge/src/mutation/mutators/binary_op_mutator.rs

@@ -9,6 +9,12 @@ pub struct BinaryOpMutator;
 impl Mutator for BinaryOpMutator {
     fn generate_mutants(&self, context: &MutationContext<'_>) -> Result<Vec<Mutant>> {
         let expr = context.expr.ok_or_eyre("BinaryOpMutator: no expression")?;
+        // Compound assignments (`a += b`, etc.) are intentionally not mutated
+        // here: the mutation text we build is `"lhs new_op rhs"` and the
+        // replacement span covers the whole assignment, which would silently
+        // rewrite `a += b` to `a - b` and corrupt the test. See
+        // `is_applicable` — those expressions are filtered out up-front so
+        // this case is unreachable, but guard defensively.
         let (bin_op, _op_span, lhs, rhs) = get_bin_op_parts(expr)?;
         let op = bin_op.kind;
 
@@ -82,18 +88,19 @@ impl Mutator for BinaryOpMutator {
             return false;
         }
 
-        match ctxt.expr.unwrap().kind {
-            ExprKind::Binary(_, _, _) => true,
-            ExprKind::Assign(_, bin_op, _) => bin_op.is_some(),
-            _ => false,
-        }
+        // We only mutate plain binary expressions. Compound assignments
+        // (`a += b`, `a *= b`, ...) are deliberately excluded: the textual
+        // replacement we build is `"lhs new_op rhs"` over the whole assignment
+        // span, which would rewrite `a += b` into `a - b` (dropping the
+        // assignment) rather than `a -= b`. Until we emit `lhs new_op= rhs`
+        // for the compound case, leave it alone.
+        matches!(ctxt.expr.unwrap().kind, ExprKind::Binary(_, _, _))
     }
 }
 
 /// Extract the binary operator, its span, and LHS/RHS expressions
 fn get_bin_op_parts<'a>(expr: &'a Expr<'a>) -> Result<(BinOp, Span, &'a Expr<'a>, &'a Expr<'a>)> {
     match &expr.kind {
-        ExprKind::Assign(lhs, Some(bin_op), rhs) => Ok((*bin_op, bin_op.span, lhs, rhs)),
         ExprKind::Binary(lhs, op, rhs) => Ok((*op, op.span, lhs, rhs)),
         _ => eyre::bail!("BinaryOpMutator: unexpected expression kind"),
     }

crates/forge/src/mutation/mutators/tests/binary_op_mutator_test.rs

@@ -14,4 +14,10 @@ mutator_tests!(BinaryOpMutator;
     bit_or:                    "x | y"   => Some(vec!["x + y", "x - y", "x * y", "x / y", "x % y", "x ** y", "x << y", "x >> y", "x >>> y", "x & y", "x ^ y"]);
     bit_xor:                   "x ^ y"   => Some(vec!["x + y", "x - y", "x * y", "x / y", "x % y", "x ** y", "x << y", "x >> y", "x >>> y", "x & y", "x | y"]);
     non_binary:                "a = true" => None;
+    // Compound assignments are intentionally skipped: the current textual
+    // replacement would rewrite `a += b` to `a - b` (dropping the assignment)
+    // instead of `a -= b`, so the mutator must report them as inapplicable.
+    compound_assign_add:       "a += b" => None;
+    compound_assign_sub:       "a -= b" => None;
+    compound_assign_mul:       "a *= b" => None;
 );

crates/forge/src/mutation/orchestrator.rs

@@ -20,9 +20,12 @@ use foundry_compilers::{
 use foundry_config::{Config, filter::GlobMatcher};
 use foundry_evm::opts::EvmOpts;
 
-use crate::mutation::{
-    MutationHandler, MutationProgress, MutationReporter, MutationsSummary, mutant::MutationResult,
-    runner::run_mutations_parallel_with_progress,
+use crate::{
+    cmd::test::FilterArgs,
+    mutation::{
+        MutationHandler, MutationProgress, MutationReporter, MutationsSummary,
+        mutant::MutationResult, runner::run_mutations_parallel_with_progress,
+    },
 };
 
 #[derive(Clone, Debug, Eq, Ord, PartialEq, PartialOrd, serde::Serialize)]
@@ -57,6 +60,13 @@ pub struct MutationRunConfig {
     pub show_progress: bool,
     /// Whether to output JSON (suppress all other output).
     pub json_output: bool,
+    /// Test filter (`--match-test`, `--match-contract`, `--match-path`, ...)
+    /// applied identically to baseline and every mutant run so they exercise
+    /// the same test set.
+    pub filter_args: FilterArgs,
+    /// EVM isolation flag — mirrors the canonical `forge test` runner so
+    /// baseline and mutant runs use the same execution model.
+    pub isolate: bool,
 }
 
 impl MutationRunConfig {
@@ -203,6 +213,8 @@ pub async fn run_mutation_testing(
             num_workers,
             progress.clone(),
             json_output,
+            mutation_config.filter_args.clone(),
+            mutation_config.isolate,
         )?;
 
         // Collect results for caching