fix(mutation): address fresh oracle review blockers and mediums

Blockers
- filter parity: pass materialized baseline filter (filter.args().clone())
  into MutationRunConfig so positional 'forge test <path>' and --rerun
  reach mutant runs too; raw self.filter dropped them silently
- bail when baseline matched zero tests; without it every compileable
  mutant was reported as 'Alive'
- negative literal mutation: add OwnedLiteral::NegatedNumber(U256)
  formatted as '-{val}'; the old Number(-*val) wrapped via two's
  complement and produced wrong-source mutants
- mutator test harness: wrap snippets in valid Solidity, panic on parse
  failure, and check emitted replacement text. Fixed 6 stale test
  expectations and 1 unmatched delegate-pattern case the old vacuous
  harness was hiding

Mediums
- survived-span resume: load retrieve_survived_spans BEFORE mutant
  generation/cached load and filter cached mutants through
  should_skip_span so cross-run adaptive skipping actually works
- runtime context digest: hash the full serialized EvmOpts (networks,
  env, gas-limit toggles, fork, sender, balance, ...) instead of a
  hand-picked 4-field subset that missed several mutation-affecting
  knobs
- deterministic output: BTreeMap for JSON survived_mutants with sorted
  entries; reporter sorts survived list by (path, line, col, span,
  mutation); persisted results_vec sorted by span
- --mutate-contract: intersect with explicit --mutate <paths> instead of
  silently overriding them; explicit paths are now respected
- workspace: copy 'script/' when present and distinct from src/test so
  projects that import script-side helpers don't see false Invalid
  mutants

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

@@ -583,6 +583,19 @@ impl TestArgs {
                 eyre::bail!("Cannot run mutation testing with failed tests");
             }
 
+            // A green baseline that ran *zero* tests is not a useful baseline:
+            // every compileable mutant would be reported as `Alive` (no test
+            // failed, so nothing killed it), which produces a wildly
+            // misleading mutation report. Hard-error so users get an actual
+            // signal that their filter / path / setup matched nothing.
+            if outcome.tests().next().is_none() {
+                eyre::bail!(
+                    "Mutation testing requires at least one matching baseline test; the current \
+                     filter/path selection matched zero tests. Loosen `--match-test` / \
+                     `--match-contract` / `--match-path` or check the project layout."
+                );
+            }
+
             // Explicit paths on --mutate cannot be combined with the --mutate-path
             // glob filter: clap can't express this directly because --mutate takes
             // an optional list of paths.
@@ -688,11 +701,16 @@ impl TestArgs {
                 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(),
+                // --match-path, positional path shorthand, --rerun, ...) and
+                // isolation flag the baseline actually used, so every mutant
+                // exercises the exact same test set under the same execution
+                // model. We pull from the materialized `filter`, not the raw
+                // CLI flags on `self`, because the baseline applies extras:
+                // the positional `forge test <path>` shorthand is folded into
+                // `path_pattern`, and `--rerun` injects last-run failures
+                // into `test_pattern`. Using `self.filter.clone()` would lose
+                // those and let mutant runs silently diverge from baseline.
+                filter_args: filter.args().clone(),
                 isolate: evm_opts_for_mutation.isolate,
             };
 

crates/forge/src/mutation/mod.rs

@@ -1,8 +1,4 @@
-use std::{
-    collections::{HashMap, HashSet},
-    path::PathBuf,
-    sync::Arc,
-};
+use std::{collections::HashSet, path::PathBuf, sync::Arc};
 
 use crate::mutation::{
     mutant::{Mutant, MutationResult},
@@ -146,16 +142,35 @@ impl MutationsSummary {
         if valid_mutants == 0 { 0.0 } else { self.dead.len() as f64 / valid_mutants as f64 * 100.0 }
     }
 
-    /// Convert to JSON output format
+    /// Convert to JSON output format.
+    ///
+    /// Output is sorted deterministically: files in lexicographic order
+    /// (`BTreeMap` keys), and survived mutants within each file sorted by
+    /// `(span.lo, span.hi, mutation_text)`. Without this, parallel worker
+    /// completion order leaks into the JSON and breaks downstream diffing,
+    /// snapshot tests, and reproducibility.
     pub fn to_json_output(&self, duration_secs: f64) -> MutationJsonOutput {
-        let mut survived_mutants: HashMap<String, Vec<SurvivedMutantJson>> = HashMap::new();
+        use std::collections::BTreeMap;
+
+        let mut survived_mutants: BTreeMap<String, Vec<SurvivedMutantJson>> = BTreeMap::new();
 
         for mutant in &self.survived {
             let file_path = mutant.relative_path();
             let entry = survived_mutants.entry(file_path).or_default();
             entry.push(SurvivedMutantJson::from_mutant(mutant));
         }
 
+        for entries in survived_mutants.values_mut() {
+            entries.sort_by(|a, b| {
+                (a.line, a.column, &a.original, &a.mutant).cmp(&(
+                    b.line,
+                    b.column,
+                    &b.original,
+                    &b.mutant,
+                ))
+            });
+        }
+
         MutationJsonOutput {
             summary: MutationSummaryJson {
                 total: self.total_mutants(),
@@ -172,11 +187,14 @@ impl MutationsSummary {
     }
 }
 
-/// JSON output for mutation testing results
+/// JSON output for mutation testing results.
+///
+/// Uses [`BTreeMap`] for `survived_mutants` so file ordering in the emitted
+/// JSON is deterministic.
 #[derive(Debug, Clone, Serialize)]
 pub struct MutationJsonOutput {
     pub summary: MutationSummaryJson,
-    pub survived_mutants: HashMap<String, Vec<SurvivedMutantJson>>,
+    pub survived_mutants: std::collections::BTreeMap<String, Vec<SurvivedMutantJson>>,
 }
 
 /// Summary section of JSON output

crates/forge/src/mutation/mutant.rs

@@ -108,12 +108,20 @@ pub enum OwnedStrKind {
 
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub enum OwnedLiteral {
-    Str { kind: OwnedStrKind, text: String },
+    Str {
+        kind: OwnedStrKind,
+        text: String,
+    },
     Number(alloy_primitives::U256),
     Rational(String),
     Address(String),
     Bool(bool),
     Err(String),
+    /// Signed-negation of a numeric literal (e.g. `-123`). We cannot represent
+    /// negative values inside `Number(U256)` (the cast wraps via two's
+    /// complement and renders as a huge unsigned literal), so we carry the
+    /// negation textually and render it as `-{val}`.
+    NegatedNumber(alloy_primitives::U256),
 }
 
 impl From<&LitKind<'_>> for OwnedLiteral {
@@ -142,6 +150,7 @@ impl Display for OwnedLiteral {
         match self {
             Self::Bool(val) => write!(f, "{val}"),
             Self::Number(val) => write!(f, "{val}"),
+            Self::NegatedNumber(val) => write!(f, "-{val}"),
             Self::Rational(s) => write!(f, "{s}"),
             Self::Address(s) => write!(f, "{s}"),
             Self::Str { kind, text } => match kind {

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

@@ -47,10 +47,14 @@ impl Mutator for AssignmentMutator {
                         line_number,
                         column_number,
                     },
+                    // Negation of a numeric literal must be carried textually:
+                    // applying `-*val` on a `U256` wraps via two's complement
+                    // and would render as a huge unsigned literal (e.g. `1`
+                    // becomes `2^256 - 1`), producing wrong-source mutants.
                     Mutant {
                         span: replacement_span,
                         mutation: MutationType::Assignment(AssignVarTypes::Literal(
-                            OwnedLiteral::Number(-*val),
+                            OwnedLiteral::NegatedNumber(*val),
                         )),
                         path: context.path.clone(),
                         original,
@@ -63,6 +67,10 @@ impl Mutator for AssignmentMutator {
                 OwnedLiteral::Rational(_) => Ok(vec![]),
                 OwnedLiteral::Address(_) => Ok(vec![]),
                 OwnedLiteral::Err(_) => Ok(vec![]),
+                // `NegatedNumber` is only ever constructed *as* a mutant; it
+                // does not appear as an original literal in the source AST,
+                // so there is nothing to mutate here.
+                OwnedLiteral::NegatedNumber(_) => Ok(vec![]),
             },
             AssignVarTypes::Identifier(ref ident) => Ok(vec![
                 Mutant {

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

@@ -2,11 +2,14 @@ use crate::mutation::mutators::{
     assignment_mutator::AssignmentMutator, tests::helper::mutator_tests,
 };
 
+// Each emitted mutation only carries the *replacement text* for the RHS
+// span — not the full statement. So `x = 123` mutates to `0` (zero) and
+// `-123` (signed-negation), not `x = 0` / `x = -123`.
 mutator_tests!(AssignmentMutator;
-    assign_lit:     "x = y"            => Some(vec!["x = 0", "x = -y"]);
-    assign_number:  "x = 123"          => Some(vec!["x = 0", "x = -123"]);
-    assign_true:    "x = true"         => Some(vec!["x = false"]);
-    assign_false:   "x = false"        => Some(vec!["x = true"]);
-    assign_declare: "uint256 x = 123"  => Some(vec!["uint256 x = 0", "uint256 x = -123"]);
+    assign_lit:     "x = y"            => Some(vec!["0", "-y"]);
+    assign_number:  "x = 123"          => Some(vec!["0", "-123"]);
+    assign_true:    "x = true"         => Some(vec!["false"]);
+    assign_false:   "x = false"        => Some(vec!["true"]);
+    assign_declare: "uint256 x = 123"  => Some(vec!["0", "-123"]);
     non_assign:     "a = b + c"        => None;
 );

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

@@ -2,7 +2,10 @@ use crate::mutation::mutators::{
     delete_expression_mutator::DeleteExpressionMutator, tests::helper::mutator_tests,
 };
 
+// `delete x` is replaced by `assert(true)` (a no-op statement) — the test
+// expects the mutation's *replacement text*, not the original expression
+// stripped of the `delete` keyword.
 mutator_tests!(DeleteExpressionMutator;
-    delete_expr: "delete x"  => Some(vec!["x"]);
+    delete_expr: "delete x"  => Some(vec!["assert(true)"]);
     non_delete:  "a = b + c" => None;
 );

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

@@ -2,7 +2,12 @@ use crate::mutation::mutators::{
     elim_delegate_mutator::ElimDelegateMutator, tests::helper::mutator_tests,
 };
 
+// The mutator narrows the replacement span to just the `delegatecall`
+// identifier and rewrites it to `call`, so the emitted mutation text is
+// just `"call"`. It only matches plain `<expr>.delegatecall(args)` Call
+// expressions; the variant with `{value: ...}` parses as a `CallOptions`
+// wrapper and is intentionally left to a follow-up.
 mutator_tests!(ElimDelegateMutator;
-    delegate_expr: "address(this).delegatecall{value: 1 ether}(0)" => Some(vec!["address(this).call{value: 1 ether}(0)"]);
-    non_delegate:  "address(this).call{value: 1 ether}(0)"         => None;
+    delegate_expr: "target.delegatecall(data)" => Some(vec!["call"]);
+    non_delegate:  "target.call(data)"         => None;
 );

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

@@ -18,16 +18,32 @@ pub struct MutatorTestCase<'a> {
 
 pub trait MutatorTester {
     fn test_mutator<M: Mutator + 'static>(mutator: M, test_case: MutatorTestCase<'_>) {
+        // Wrap the snippet in a minimal but valid Solidity source unit so the
+        // parser/visitor actually walks into expression contexts. Bare
+        // fragments like `"x + y"` or `"a += b"` are not parseable on their
+        // own; without wrapping, the parser would emit errors that the test
+        // harness used to swallow, silently making mutator tests vacuous.
+        let wrapped = format!(
+            "// SPDX-License-Identifier: MIT\n\
+             pragma solidity ^0.8.0;\n\
+             contract __TestC {{\n\
+                 function __test() public {{\n\
+                     {input};\n\
+                 }}\n\
+             }}\n",
+            input = test_case.input,
+        );
+
         let sess = Session::builder().with_silent_emitter(None).build();
 
-        let _ = sess.enter(|| -> solar::interface::Result<()> {
+        let outcome = sess.enter(|| -> solar::interface::Result<Vec<String>> {
             let arena = Arena::new();
 
             let mut parser = Parser::from_lazy_source_code(
                 &sess,
                 &arena,
                 FileName::Real(PathBuf::from("test.sol")),
-                || Ok(test_case.input.to_string()),
+                || Ok(wrapped.clone()),
             )?;
 
             let ast = parser.parse_file().map_err(|e| e.emit())?;
@@ -36,41 +52,50 @@ pub trait MutatorTester {
                 PathBuf::from("test.sol"),
                 vec![Box::new(mutator)],
             )
-            .with_source(test_case.input);
+            .with_source(&wrapped);
 
             let _ = mutant_visitor.visit_source_unit(&ast);
 
-            let mutations = mutant_visitor.mutation_to_conduct;
+            Ok(mutant_visitor
+                .mutation_to_conduct
+                .into_iter()
+                .map(|m| m.mutation.to_string())
+                .collect())
+        });
 
-            if let Some(expected) = test_case.expected_mutations {
-                assert_eq!(
-                    mutations.len(),
-                    expected.len(),
-                    "Expected {} mutations, got {}: {:?}",
-                    expected.len(),
-                    mutations.len(),
-                    mutations.iter().map(|m| m.mutation.to_string()).collect::<Vec<_>>()
-                );
+        // Surface parse/visit errors instead of silently passing the test.
+        let mutations = outcome.unwrap_or_else(|_| {
+            panic!(
+                "mutator test input failed to parse/visit; wrapped source was:\n{wrapped}\n\
+                 raw input: {input:?}",
+                input = test_case.input,
+            )
+        });
 
-                for mutation in &mutations {
-                    let mutation_str = mutation.mutation.to_string();
-                    assert!(
-                        expected.contains(&mutation_str.as_str()),
-                        "Unexpected mutation: {mutation_str}. Expected one of: {expected:?}",
-                    );
-                }
-            } else {
-                assert_eq!(
-                    mutations.len(),
-                    0,
-                    "Expected no mutations, got {}: {:?}",
-                    mutations.len(),
-                    mutations.iter().map(|m| m.mutation.to_string()).collect::<Vec<_>>()
+        if let Some(expected) = test_case.expected_mutations {
+            assert_eq!(
+                mutations.len(),
+                expected.len(),
+                "Expected {} mutations, got {}: {:?}",
+                expected.len(),
+                mutations.len(),
+                mutations,
+            );
+
+            for mutation_str in &mutations {
+                assert!(
+                    expected.contains(&mutation_str.as_str()),
+                    "Unexpected mutation: {mutation_str}. Expected one of: {expected:?}",
                 );
             }
-
-            Ok(())
-        });
+        } else {
+            assert!(
+                mutations.is_empty(),
+                "Expected no mutations, got {}: {:?}",
+                mutations.len(),
+                mutations,
+            );
+        }
     }
 }