Skip to content

Add documentation for selective mutation ignore annotations support - #7

Merged
maks-rafalko merged 9 commits into
mainfrom
docs/selective-ignore-annotations
Nov 8, 2026
Merged

maks-rafalko merged 9 commits into
mainfrom
docs/selective-ignore-annotations

Conversation

@theofidry

@theofidry theofidry commented Nov 3, 2026 •

Copy link
Copy Markdown
Member

Comment thread guide/usage.md Resolved

@theofidry theofidry left a comment

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

not too happy with the result tbh... But I think I need a deeper review of the whole page

theofidry added a commit to infection/infection that referenced this pull request Nov 5, 2026
## Description

When only one mutator produces unwanted mutations,
`@infection-ignore-all` also excludes mutations users want to keep. The
new `@infection-ignore` annotation lets users name the mutators to
exclude:

```php
class Example
{
    /** @infection-ignore ArrayItemRemoval, FalseValue */
    public function values(): array
    {
        return [false, true];
    }
}
```

The annotation applies to the annotated code and everything nested
inside it. Nested annotations add to the inherited exclusions. Ordinary
comments work too:

```php
/** @infection-ignore ArrayItemRemoval */
class Example
{
    public function values(): array
    {
        // @infection-ignore FalseValue
        $defaults = [false, true];

        return [false, true];
    }
}
```

`ArrayItemRemoval` is excluded throughout the class. `FalseValue` is
excluded only in the assignment to `$defaults`; it can still mutate the
`false` in the return statement. `TrueValue` remains enabled in both
statements.

An annotation on an array item doesn't exclude `ArrayItemRemoval`,
because that mutator targets the array itself. The same annotation on
the return statement covers the array and excludes the mutation:

```php
class Example
{
    public function itemAnnotation(): array
    {
        return [
            // @infection-ignore ArrayItemRemoval
            false,
        ]; // ArrayItemRemoval can still produce [].
    }

    public function statementAnnotation(): array
    {
        // @infection-ignore ArrayItemRemoval
        return [false]; // ArrayItemRemoval is excluded here.
    }
}
```

**Names are exact and case-sensitive**. Warnings for unknown names and
empty lists include the source file and the annotated node's line
number. Built-in mutator names are recognised even when disabled, along
with configured custom mutator names.

As with `@infection-ignore-all`, excluded mutations aren't generated and
don't contribute to the `Ignored` result count.

## Changes

- Introduce `ExcludeIgnoredMutatorsVisitor` to attach ignored mutator
names to nodes during AST enrichment.
- Adapt `NodeMutationGenerator` to filter out each node's ignored
mutators.
- Clarify in the nomenclature that these exclusions apply during
mutation generation, after node eligibility has been determined.

## Documentation

See infection/infection.github.io#7.

## Related issues

Closes #2291.
@theofidry

Copy link
Copy Markdown
Member Author

Actually could add a post for it too

@theofidry
theofidry marked this pull request as ready for review November 7, 2026 10:06

@sanmai sanmai left a comment •

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Some nits. It does read like Codex but reads easy so I'm not inclined to rewrite it.

Comment thread guide/how-to.md Resolved
Comment thread guide/how-to.md Resolved
Comment thread guide/how-to.md Resolved
Comment thread guide/usage.md Resolved
Comment thread guide/usage.md Resolved
Comment thread posts/whats-new-in-0.35.10.md Resolved
Comment thread posts/whats-new-in-0.35.10.md Resolved
Comment thread posts/whats-new-in-0.35.10.md Resolved
Comment thread posts/whats-new-in-0.35.10.md Resolved
Comment thread guide/usage.md Resolved
@theofidry

Copy link
Copy Markdown
Member Author

Updated, also improved it a bit and added some more examples

@maks-rafalko
maks-rafalko merged commit 0f027c4 into main Nov 8, 2026
3 checks passed
@maks-rafalko
maks-rafalko deleted the docs/selective-ignore-annotations branch November 8, 2026 18:07
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants