Add #[mutants::exclude_re("pattern")] attribute

[sandersaares]

Add a new attribute that excludes specific mutations by regex, without disabling all mutations on the function like #[mutants::skip] does.

The attribute can be placed on functions, impl blocks, trait blocks, modules, and files (as an inner attribute). Patterns from outer scopes are inherited. Also supported within cfg_attr.

Changes

• mutants_attrs/src/lib.rs: New exclude_re proc-macro attribute (no-op, like skip)
• src/visit.rs: Core implementation - exclude_re_stack on the discovery visitor, push/pop at scope boundaries, attrs_exclude_re_patterns parsing, filtering in collect_mutant
• testdata/exclude_re_attr/: Test tree exercising all supported scopes (function, impl, trait, mod, scope inheritance, cfg_attr)
• tests/main.rs: Integration test
• book/src/attrs.md: Documentation
• NEWS.md: Changelog entry

Design decisions

• Invalid regex in an attribute returns a hard error, matching --exclude-re CLI behavior
• Multiple #[mutants::exclude_re] attributes on the same item are OR'd
• Patterns on outer scopes (impl/trait/mod/file) are inherited by all items within (not 100% sure how valuable it is but it was trivial to add and feels "logically fitting" so maybe useful)

Closes #551

[Copilot]

Pull request overview

Adds a new #[mutants::exclude_re("...")] attribute to allow excluding only specific mutants (by regex) while still generating other mutations, including inheritance from outer scopes and support inside cfg_attr.

Changes:

• Introduces the mutants::exclude_re proc-macro attribute (no-op at compile time) and documents it.
• Implements exclude-by-regex behavior in the discovery visitor via an inherited scope stack, plus regex parsing from attributes (including cfg_attr).
• Adds integration + fixture coverage (new testdata tree, new snapshot, and a new integration test).

Reviewed changes

Copilot reviewed 8 out of 8 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
mutants_attrs/src/lib.rs	Adds the exclude_re proc-macro attribute entry point and docs.
src/visit.rs	Implements exclude-re parsing, scope inheritance, and filtering during mutant collection; adds unit tests.
testdata/exclude_re_attr/src/lib.rs	New fixture crate source exercising supported scopes.
testdata/exclude_re_attr/Cargo_test.toml	New fixture crate manifest for the exclude-re attribute tests.
tests/main.rs	Adds an integration test to snapshot --list output for the new fixture.
tests/util/snapshots/main__util__list_mutants_in_exclude_re_attr.snap	Snapshot for the new integration test output.
book/src/attrs.md	Documents the new attribute, usage, and scope inheritance rules.
NEWS.md	Adds an “Unreleased” changelog entry for the new attribute.

Comments suppressed due to low confidence (1)

src/visit.rs:636

• visit_item_mod pushes an exclude_re scope, but the early-return path when find_path_attribute reports an invalid (absolute) #[path] returns without popping. That leaves the exclude_re stack unbalanced and can incorrectly apply the module’s exclude patterns to the rest of the file. Pop the scope before returning (or use an RAII guard to ensure pop on all exits).

        if !self.push_exclude_re(&node.attrs) {
            return;
        }

        let source_location = Span::from(node.span());

        // Extract path attribute value, if any (e.g. `#[path="..."]`)
        let path_attribute = match find_path_attribute(&node.attrs) {
            Ok(path) => path,
            Err(path_attribute) => {
                let definition_site = self
                    .source_file
                    .format_source_location(source_location.start);
                error!(?path_attribute, ?definition_site, %mod_name, "invalid filesystem traversal in mod path attribute");
                return;
            }

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[sandersaares]

Addressed all feedback. Robot summary:

Owner feedback (@sourcefrog):

• mutants_attrs version bumped 0.0.4 → 0.0.5.
• Invalid-regex (and malformed-attribute) errors now include the source file/line and the bad pattern.
• cfg_attr parsing rewritten from TokenStream::to_string() substring scan to proper AST traversal via Attribute::parse_nested_meta + syn::LitStr.
• Misleading i32 + with () example in book/src/attrs.md replaced with "with 0".

Copilot reviewer feedback:

• Fragile string scan replaced with AST parse (above).
• Malformed #[mutants::exclude_re] (no arg / multiple args / non-string arg) is now a hard error instead of silent no-op, with 4 new unit tests.
• Unit test that previously couldn't have detected a broken regex filter has been rewritten to exclude with 0 against -> i32 and now asserts that with 0 is gone while with 1, with -1, and the binop mutants survive.
• Same misleading example fixed in book/src/attrs.md and testdata/exclude_re_attr/src/lib.rs; the snapshot main__util__list_mutants_in_exclude_re_attr.snap was regenerated and now visibly omits replace add_numbers -> i32 with 0.

Also addressed (from the suppressed low-confidence review comment about visit_item_mod): the early-return path on an invalid #[path] attribute could leave exclude_re_stack unbalanced. Fixed by introducing an in_exclude_re_scope(attrs, |v| { ... }) closure helper that does the push/pop around the visit body, and converting every visitor method (visit_file, visit_item_fn, visit_impl_item_fn, visit_trait_item_fn, visit_item_impl, visit_item_trait, visit_item_mod) to use it, so a future early return can't desync the stack.

Also added exclude_re_attr_keeps_all_when_no_match, strengthened to compare full mutant names — proves that a pattern matching nothing produces the exact same mutant set as no attribute at all, matching --exclude-re CLI behaviour.

[sandersaares]

I noticed that #[mutants::skip] is actually parsed at many different scopes not just functions (as the book suggests) and that #[mutants::exclude_re] was missing support for expression-level parsing, differing from #[mutants::skip] in this regard. Added expression-level support now. Will make a 2nd PR to align the book with the implementation, as well.