Add ReturnRemoval mutator

[sanmai]

This PR:

• Adds new ReturnRemoval mutator to fix Return removal mutator #2268
• Implements NextConnectingVisitor to track statement execution order
• Covered by tests
• Doc PR: Add ReturnRemoval mutator site#277

NextConnectingVisitor

Added a new AST visitor that connects sequential statement nodes by adding a "next" attribute. This visitor:

• Tracks execution order between statements only (ignores expressions)
• Skips comment nodes (Nop)
• Resets the connection chain at function boundaries
• Enables the ReturnRemoval mutator to detect if there are statements after a return

ReturnRemoval Mutator

The mutator now intelligently removes return statements without causing language errors:

• Removes any return in functions without return types (void or no type declaration)
• Removes returns that have subsequent statements (detected via NextConnectingVisitor)
• Always preserves the last return in functions with return types, preventing type errors
• Does not mutate return; or return null; at the end of functions without return types, as these are semantically equivalent to implicit null returns

So we avoid both un-killable mutations and fatal errors.

Benefits

This implementation successfully avoids language errors while still exposing untested code paths. By preserving the last return statement in typed functions, we ensure the code remains syntactically valid while still being able to detect:

• Unreachable code after return statements
• Early returns that may not be properly tested
• Redundant return statements in functions

The approach provides maximum mutation coverage without breaking PHP's type system. Just what we wanted 🙂

---

Per-mutator report:

Mutator	Mutations	Killed by Test Framework	Test Timings min/avg/max	Killed by Static Analysis	Static Analysis Timings min/avg/max	Escaped	Errors	Syntax Errors	Timed Out (Limit: 25 secs)	Skipped	Ignored	MSI (%s)	Covered MSI (%s)
ReturnRemoval	569	407	0.30 / 0.49 / 5.57 secs	0	0.00 / 0.00 / 0.00 secs	70	3	0	1	0	0	72.23	85.45

[staabm]

looking at ReturnLastTaggingVisitor, I think we can do it simpler and without a nested NodeTraverser by taking inspiration from PHPParsers builtin NodeConnectingVisitor.

we need to find/tag Return_ nodes, which do not have a 'next' node, right?

[sanmai]

Sadly NodeConnectingVisitor only sets the next attribute on nodes that share the same parent. I.e. these do not:

if ($foo) {
    return $bar;
}
return $baz;

But it is a good starting point for our own connecting visitor.

[staabm]

Yes, posted it for inspiration to implement a smaller/specific one for our use-case

[staabm]

I think we should set references between AstNodes very carefully.
at best this visitor would be very specific for the use-case and set a more specific attribute, like "isLastReturn" and if-possible only on Return_ nodes.

references between ast nodes can be very costly, as they hinder the garbage collector.
see e.g. https://phpstan.org/blog/preprocessing-ast-for-custom-rules which describes the cost of a parent/next/previous attribute the NodeConnectingVisitor incurs.

[sanmai]

If PHPStan has to keep the whole codebase in memory to do its thing, then it makes total sense for it. For us, it is a single file at a time. So it should not be a problem, and we already use the parent connecting visitor.

[maks-rafalko]

so I've went through my todo list and the only one item left is to analyze overlapping, which I will postpone as I don't have time yet for this time-consuming activity.

Also, I've read seggested topics by Markus regarding weak references, and they look very interesting. I will create an issue to have a separate discussion on this topic so we can check if and how weak references help us not only here for the new visitor but for parent connector as well.

• https://phpstan.org/blog/preprocessing-ast-for-custom-rules
• nikic/PHP-Parser#1057

I've also analyzed ~20 escaped mutants generated for Infection and they do make sense.

Let's try!