fix(mutation): honor filters and isolation

[zerosnacks]

Stacked on #14971 towards OSS-1

• Honor Forge test filters and isolation settings during mutation runs.
• Reject mutation mode with incompatible test flags instead of silently producing misleading results.
• Preserve fix(mutation): key cached results by execution inputs #14971's execution-aware result/survived cache keys while layering the remaining runtime correctness fixes on top.
• Improve adaptive/resume behavior by loading survived spans before mutant generation.
• Avoid invalid/duplicate mutations for compound assignments and tighten mutator tests.
• Improve reporting/runner plumbing for skipped, timed out, and resumed mutants.

[stevencartavia]

three things worth a look. All reproduced end-to-end against this branch (pr-14848 @ 79abd60e7).

stale

[grandizzy]

Blocking — per-mutant compilation still ignores the baseline-selected file set.

In crates/forge/src/mutation/runner.rs, compile_and_test_inner (around L612):

let compiler =
    ProjectCompiler::new().dynamic_test_linking(config.dynamic_test_linking).quiet(true);

let compile_output = compiler.compile(&config.project()?)?;
...
let filter = filter_args.clone().merge_with_config(config);
...
runner.test_collect(&filter)

Execution is now filter-aware, but compilation is not: each mutant compiles every test file in the temp workspace. A filtered-out test that fails to compile against the mutated source (or is otherwise uncompilable) will mark the mutant Invalid and diverge from the baseline filtered forge test — which already excludes such files via TestArgs::get_sources_to_compile.

Suggested shape

Mirror what baseline compile_and_run does. Compute the selected set once, carry it through MutationRunConfig, and re-anchor it onto each temp workspace.

1. In TestArgs::run_tests, before constructing MutationRunConfig:

let selected_sources_relative = self
    .get_sources_to_compile(&config_for_mutation, &filter)?
    .into_iter()
    .filter_map(|p| p.strip_prefix(&config_for_mutation.root).ok().map(PathBuf::from))
    .collect::<Vec<_>>();

Add selected_sources_relative: Vec<PathBuf> to MutationRunConfig.

2. Thread through run_mutations_parallel_with_progress → test_single_mutant_isolated → compile_and_test next to filter_args (same Arc<…> pattern that's already there).

3. In compile_and_test_inner, re-anchor onto the temp config.root and pass to .files(...):

let files: Vec<PathBuf> = selected_sources_relative
    .iter()
    .map(|rel| config.root.join(rel))
    .filter(|p| p.exists())
    .collect();

let compile_output = ProjectCompiler::new()
    .dynamic_test_linking(config.dynamic_test_linking)
    .quiet(true)
    .files(files)
    .compile(&config.project()?)?;

Why this is the right shape

• Single source of truth. get_sources_to_compile is already the canonical filter-aware compile-set helper used by forge test. Reusing it guarantees baseline and mutants stay in lockstep — no second implementation to drift.
• Computed once. The (expensive) ABI compile inside get_sources_to_compile runs once on the original project, not per mutant.
• Path-stable. Stripping to project-relative and re-joining onto the temp root matches the existing src_rel/test_rel/script_rel pattern in test_single_mutant_isolated.
• Tolerant of missing files. .filter(|p| p.exists()) mirrors how the PR already handles fs_permissions paths.
• Empty-filter fast path preserved. get_sources_to_compile returns the full src + test set when the filter is empty, so unfiltered mutation runs are unchanged.

Regression test

Add to crates/forge/tests/cli/test_cmd/mutation.rs. Without the fix every mutant is Invalid; with the fix the broken file is excluded from per-mutant compilation just like the baseline.

forgetest_init!(mutation_honors_match_path_at_compile_time, |prj, cmd| {
    // Source with a mutable arithmetic operator → guarantees ≥1 mutant
    // (e.g. `+` → `-`, `+` → `*`) that the selected test will kill.
    prj.add_source(
        "Foo.sol",
        r#"
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.13;

contract Foo {
    function add(uint256 a, uint256 b) public pure returns (uint256) {
        return a + b;
    }
}
"#,
    );

    // Selected test: compiles and passes against the original, kills the
    // arithmetic mutants.
    prj.add_test(
        "FooSelected.t.sol",
        r#"
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.13;

import "../src/Foo.sol";

contract FooSelectedTest {
    Foo internal foo;

    function setUp() public {
        foo = new Foo();
    }

    function test_Add() public view {
        assert(foo.add(2, 3) == 5);
    }
}
"#,
    );

    // Unselected test: deliberately fails to compile (undefined symbol).
    // Baseline `forge test --match-path FooSelected.t.sol` succeeds because
    // `get_sources_to_compile` excludes this file from the compile set.
    // Mutation runs must behave the same — otherwise every mutant gets
    // misclassified as `Invalid` due to a test the user explicitly excluded.
    prj.add_test(
        "FooBroken.t.sol",
        r#"
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.13;

import "../src/Foo.sol";

contract FooBrokenTest {
    function test_Broken() public pure {
        // `NonExistent` is undefined → this file cannot compile.
        NonExistent x = NonExistent(0);
        x.doSomething();
    }
}
"#,
    );

    // Sanity check: baseline filtered `forge test` succeeds despite
    // FooBroken.t.sol being uncompilable. If this fails, the test scaffold
    // itself is wrong (not the mutation code under test).
    cmd.forge_fuse()
        .args(["test", "--match-path", "test/FooSelected.t.sol"])
        .assert_success();

    // Mutation run with the same path filter must also succeed and must
    // NOT mark mutants as `Invalid` due to FooBroken.t.sol failing to
    // compile against the mutated source.
    cmd.forge_fuse().args([
        "test",
        "--mutate", "src/Foo.sol",
        "--match-path", "test/FooSelected.t.sol",
        "--mutation-jobs", "1",
        "--json",
    ]);

    let out = cmd.assert_success().get_output().stdout_lossy();
    let summary = mutation_summary(&out);

    let invalid = summary["invalid"].as_u64().unwrap_or(u64::MAX);
    let killed  = summary["killed"].as_u64().unwrap_or(0);
    let alive   = summary["survived"].as_u64().unwrap_or(0);

    assert_eq!(
        invalid, 0,
        "filtered-out FooBroken.t.sol must not cause Invalid mutants; summary={summary}"
    );
    assert!(
        killed + alive >= 1,
        "expected at least one Killed/Alive mutant from arithmetic ops; summary={summary}"
    );
});

Worth considering as follow-up variants in the same file: mutation_honors_match_test_at_compile_time (use --match-test test_Add) and mutation_honors_no_match_path (invert via --no-match-path 'test/FooBroken.t.sol').

[grandizzy]

lgtm!