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

[sandersaares]

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

Closes #551.

Behavior

• Regex matches against the full mutant name (the same string shown by cargo mutants --list), using the same syntax as --exclude-re on the command line.
• Scopes supported: functions, impl blocks, trait blocks, modules, files (as #![mutants::exclude_re(...)] inner attribute), and expressions that can carry an attribute (match, struct literals, calls, method calls, unary).
• Patterns from outer scopes are inherited: if an impl block excludes a pattern, every method inside also excludes it, in addition to any patterns on the method itself. Patterns combine — a mutant matching any active pattern is excluded.
• Multiple #[mutants::exclude_re(...)] attributes on the same item are all honoured.
• Recognized inside cfg_attr, e.g. #[cfg_attr(test, mutants::exclude_re("..."))]. As with mutants::skip, the cfg condition is not evaluated; the inner attribute is always honoured.
• A malformed attribute (missing/non-string/multiple arguments) or invalid regex is a hard error that names the offending source location and explains the failure. Only the first such error per run is surfaced, so the user gets a single actionable message.

Changes

• mutants_attrs/src/lib.rs: new exclude_re proc-macro attribute (no-op, like skip); mutants crate bumped 0.0.4 → 0.0.5.
• src/visit.rs: exclude_re_stack on DiscoveryVisitor with scoped push/pop helpers (in_exclude_re_scope), attrs_exclude_re_patterns for direct and cfg_attr-wrapped attributes, filtering in collect_mutant, and self.error.get_or_insert_with(...) to preserve the first error.
• src/visit/test/: unit tests for every supported scope (function, impl, trait, mod, file, cfg_attr, outer-scope inheritance, malformed/invalid attribute reporting), and dedicated submodules for each expression-attribute kind (exclude_re_expr_call, _match, _method_call, _struct, _unary, and a _common module covering outer-scope inheritance into expressions and the skip > exclude_re precedence).
• tests/main.rs + testdata/exclude_re_attr_two_invalid_regexes/: integration test exclude_re_attr_two_invalid_regexes_reports_only_the_first verifying end-to-end CLI behavior — the first malformed regex is reported with source location and the regex parser's explanation, and any subsequent malformed regex is silently suppressed.
• book/src/attrs.md: documentation, including the mutants crate version requirement.
• NEWS.md: changelog entry.

[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.

[sourcefrog]

Like in #618, it seems the integration test and test tree is mostly(?) duplicating things covered by the unit tests. I think I would rather keep the test collection relatively smaller and non-duplicative, both for the sake of making it easier to navigate and for test speed.

However, one thing I would think about adding at this level is a check that the error from a malformed regex comes out of the CLI.

[sandersaares]

Adjusted as requested - unit test duplicating integration tests removed, added invalid-regex CLII integration test.

[sourcefrog]

Should we caution here that you need mutants_attrs 0.5.0?

[sandersaares]

Added version number notice.

Personally, I am of the opinion that "docs apply to latest version" is a given and such notes are mostly noise but I defer to your judgement.

[sourcefrog]

Should we also mention a new mutants_attrs 0.5.0 is needed for this feature?

[sandersaares]

Added version number notice.