feat(forge): mutation testing

crates/config/Cargo.toml

@@ -48,6 +48,7 @@ tracing.workspace = true
 walkdir.workspace = true
 yansi.workspace = true
 clap = { version = "4", features = ["derive"] }
+strum = { workspace = true, features = ["derive"] }
 
 [target.'cfg(target_os = "windows")'.dependencies]
 path-slash = "0.2"

crates/config/src/lib.rs

@@ -113,6 +113,9 @@ pub use fuzz::{FuzzConfig, FuzzCorpusConfig, FuzzDictionaryConfig};
 mod invariant;
 pub use invariant::InvariantConfig;
 
+pub mod mutation;
+pub use mutation::{MutationConfig, MutatorType};
+
 mod inline;
 pub use inline::{InlineConfig, InlineConfigError, NatSpec};
 
@@ -351,6 +354,8 @@ pub struct Config {
     pub coverage_pattern_inverse: Option<RegexWrapper>,
     /// Path where last test run failures are recorded.
     pub test_failures_file: PathBuf,
+    /// Path where mutation tests are cached, to resume running them
+    pub mutation_dir: PathBuf,
     /// Max concurrent threads to use.
     pub threads: Option<usize>,
     /// Whether to show test execution progress.
@@ -359,6 +364,8 @@ pub struct Config {
     pub fuzz: FuzzConfig,
     /// Configuration for invariant testing
     pub invariant: InvariantConfig,
+    /// Configuration for mutation testing
+    pub mutation: MutationConfig,
     /// Whether to allow ffi cheatcodes in test
     pub ffi: bool,
     /// Whether to show `console.log` outputs in realtime during script/test execution
@@ -710,6 +717,7 @@ impl Config {
         "doc",
         "fuzz",
         "invariant",
+        "mutation",
         "labels",
         "dependencies",
         "soldeer",
@@ -1329,6 +1337,9 @@ impl Config {
             ));
         }
 
+        // Remove mutation test cache directory
+        let _ = fs::remove_dir_all(project.root().join(&self.mutation_dir));
+
         // Remove fuzz and invariant cache directories.
         let mut remove_test_dir = |test_dir: &Option<PathBuf>| {
             if let Some(test_dir) = test_dir {
@@ -2684,10 +2695,12 @@ impl Default for Config {
             path_pattern_inverse: None,
             coverage_pattern_inverse: None,
             test_failures_file: "cache/test-failures".into(),
+            mutation_dir: "cache/mutation".into(),
             threads: None,
             show_progress: false,
             fuzz: FuzzConfig::new("cache/fuzz".into()),
             invariant: InvariantConfig::new("cache/invariant".into()),
+            mutation: MutationConfig::default(),
             always_use_create_2_factory: false,
             ffi: false,
             live_logs: false,
@@ -6953,6 +6966,9 @@ mod tests {
                 runs = 256
                 unknown_invariant_key = "should_warn"
 
+                [mutation]
+                unknown_mutation_key = "should_warn"
+
                 [vyper]
                 unknown_vyper_key = "should_warn"
 
@@ -6981,6 +6997,9 @@ mod tests {
                 runs = 512
                 unknown_nested_invariant_key = "should_warn"
 
+                [profile.default.mutation]
+                unknown_nested_mutation_key = "should_warn"
+
                 [profile.default.vyper]
                 unknown_nested_vyper_key = "should_warn"
 
@@ -7019,6 +7038,7 @@ mod tests {
                 ("unknown_doc_key", "doc"),
                 ("unknown_fuzz_key", "fuzz"),
                 ("unknown_invariant_key", "invariant"),
+                ("unknown_mutation_key", "mutation"),
                 ("unknown_vyper_key", "vyper"),
                 ("unknown_bind_json_key", "bind_json"),
             ];
@@ -7044,6 +7064,7 @@ mod tests {
                 ("unknown_nested_doc_key", "doc"),
                 ("unknown_nested_fuzz_key", "fuzz"),
                 ("unknown_nested_invariant_key", "invariant"),
+                ("unknown_nested_mutation_key", "mutation"),
                 ("unknown_nested_vyper_key", "vyper"),
                 ("unknown_nested_bind_json_key", "bind_json"),
             ];
@@ -7092,11 +7113,11 @@ mod tests {
                 })
                 .collect();
 
-            // 1 profile key + 7 standalone + 7 nested + 2 array = 17 total
+            // 1 profile key + 8 standalone + 8 nested + 2 array = 19 total
             assert_eq!(
                 unknown_key_warnings.len(),
-                17,
-                "Expected 17 unknown key warnings (1 profile + 7 standalone + 7 nested + 2 array), got {}: {:?}",
+                19,
+                "Expected 19 unknown key warnings (1 profile + 8 standalone + 8 nested + 2 array), got {}: {:?}",
                 unknown_key_warnings.len(),
                 unknown_key_warnings
             );

crates/config/src/mutation.rs

@@ -0,0 +1,80 @@
+//! Configuration for mutation testing.
+
+use serde::{Deserialize, Serialize};
+use strum::IntoEnumIterator;
+
+/// Represents each available mutation operator.
+#[derive(
+    Debug,
+    Clone,
+    Copy,
+    PartialEq,
+    Eq,
+    Hash,
+    Serialize,
+    Deserialize,
+    strum::Display,
+    strum::EnumString,
+    strum::EnumIter,
+)]
+#[serde(rename_all = "kebab-case")]
+#[strum(serialize_all = "kebab-case")]
+pub enum MutatorType {
+    Assembly,
+    Assignment,
+    BinaryOp,
+    DeleteExpression,
+    ElimDelegate,
+    Require,
+    UnaryOp,
+}
+
+impl MutatorType {
+    /// Returns a list of all available mutator types.
+    pub fn all() -> Vec<Self> {
+        Self::iter().collect()
+    }
+
+    /// Returns the operators that are excluded by default.
+    pub const fn default_excluded() -> Vec<Self> {
+        Vec::new()
+    }
+}
+
+/// Configuration for mutation testing.
+#[derive(Clone, Debug, Default, PartialEq, Eq, Serialize, Deserialize)]
+pub struct MutationConfig {
+    /// Re-enable operators that are excluded by default.
+    pub include_operators: Vec<MutatorType>,
+    /// Exclude additional operators beyond the defaults.
+    pub exclude_operators: Vec<MutatorType>,
+    /// Per-mutant wall-clock timeout, in seconds.
+    ///
+    /// When set, each mutant's compile-and-test work is bounded by this
+    /// duration; mutants that exceed it are recorded as `TimedOut`. This is
+    /// the analog of `invariant.timeout` for mutation campaigns.
+    ///
+    /// Note: enforcement is best-effort. Background work for a timed-out
+    /// mutant may continue briefly until the underlying compile / test loop
+    /// reaches a checkpoint, but the worker slot is freed immediately so
+    /// other mutants can proceed. Cleanup backlog is bounded by the configured
+    /// mutation worker count.
+    pub timeout: Option<u32>,
+}
+
+impl MutationConfig {
+    /// Returns the list of operators that are currently enabled.
+    ///
+    /// Effective set: `all() - default_excluded - exclude_operators + include_operators`
+    pub fn enabled_operators(&self) -> Vec<MutatorType> {
+        let default_excluded = MutatorType::default_excluded();
+        MutatorType::all()
+            .into_iter()
+            .filter(|op| {
+                let excluded = default_excluded.contains(op) || self.exclude_operators.contains(op);
+                let included = self.include_operators.contains(op);
+                !excluded || included
+            })
+            .collect()
+    }
+}

crates/forge/Cargo.toml

@@ -65,8 +65,6 @@ alloy-transport.workspace = true
 
 tempo-alloy.workspace = true
 
-revm.workspace = true
-
 clap = { version = "4", features = ["derive", "env", "unicode", "wrap_help"] }
 clap_complete.workspace = true
 dunce.workspace = true
@@ -75,13 +73,14 @@ inferno = { version = "0.12", default-features = false }
 itertools.workspace = true
 parking_lot.workspace = true
 regex = { workspace = true, default-features = false }
+revm.workspace = true
 semver.workspace = true
 serde_json.workspace = true
 similar = { version = "2", features = ["inline"] }
 solar.workspace = true
 strum = { workspace = true, features = ["derive"] }
 thiserror.workspace = true
-tokio = { workspace = true, features = ["time"] }
+tokio = { workspace = true, features = ["time", "signal"] }
 toml_edit.workspace = true
 watchexec = "8.0"
 watchexec-events = "6.0"
@@ -101,6 +100,7 @@ opener = "0.8"
 soldeer-commands.workspace = true
 soldeer-core.workspace = true
 quick-junit = "0.5.2"
+tempfile.workspace = true
 
 [dev-dependencies]
 alloy-hardforks.workspace = true