Add an ability to ignore Mutators for source code line(s) by regular expression

[maks-rafalko]

• Fixes Allow adding mutation exclusions for specific calls #697
• Covered by tests
• Doc PR: Document how to ignore mutations matching the source code by regular expression site#177

Allows to avoid mutating such lines of code as:

- Assert::notNull($variable);

or

- $this->logger->error($message, ['user' => $user]);
+ $this->logger->error($message, []);

and similar if developers are not interested in them.

Example of new config setting usage:

{
    "mutators": {
        "MethodCallRemoval": {
            "ignoreSourceCodeByRegex": [
                "Assert::.*",
                "\\$this->logger.*"
            ]
        }
    }
}

Also, there is a new setting for mutators - global-ignoreSourceCodeByRegex that will be added to all enabled mutators if present. Works similar to global-ignore

{
    "mutators": {
        "global-ignoreSourceCodeByRegex": [
            "Assert::.*"
        ]
    }
}

From an implementation point of view, it's not possible to use IgnoreConfig and IgnoreMutator to ignore mutators for configured lines of code by regex, because, at the step of applying Mutator, we don't have any information about the source line of code.

While we technically can get it (using PrettyPrinter's prettyPrintExpr($expression) function or by passing source code to each mutator and finding the needed line), for me it seems like not the right solution.

This PR tries to filter out mutants before creating Mutant processes, similar to what is being discussed in pre-/post- hooks here #1323

So, before deciding whether we need to ignore mutator or no, we are applying regular expression (if any) to the diff of Mutant. Easy, yet so powerful.

I will continue adding tests/docs after we agree with the implementation.

I see this feature is most requested during the last months, so I would like to release it asap.

Regarding the suggested plugin system - #1323. When we will do it, this implementation can be redeveloped using plugin system/hooks, while for users configuration will be the same, so no BC here.

PS I'm aware of the failed build, it's ok for now since no tests have been updated

[Slamdunk]

I'm very happy with the results. I miss only one functionality: a global-ignoreSourceCodeByRegex, like the already existing global-ignore, as many ignores may be specific to the environment of the mutation, instead of the specific mutation, like the assert one.

[maks-rafalko]

@Slamdunk @sanmai great suggestions, thank you very much. Implemented.

Updated description. Also, added global-ignoreSourceCodeByRegex as you requested.

Ready for review.

[sanmai]

Shouldn't we dog-food this feature already?

[Slamdunk]

As a non-native English speaker, may I ask you what does this mean?

[sanmai]

Sure. I'm slightly surprised to find that there's even a Wikipedia article for the term.

Eating your own dog food or dogfooding is the practice of an organization using its own product.

What I meant is that Infection could use exactly this regex to limit removal of these calls.

[maks-rafalko]

Shouldn't we dog-food this feature already?

if we need to - we certainly can. I didn't do any analysis for this though

[sanmai]

It can certainly wait.

[sanmai]

If we can extend #1327 to allow injecting arbitrary configuration for a plugin, this feature is a great candidate for a standard plugin. Nevertheless I think this idea shouldn't be holding anything up since it should be possible to refactor this ignorer into a plugin without changing the configuration schema in a bit.

[sanmai]

CS Fixer is going nuts 😞

[maks-rafalko]

CS Fixer is going nuts 😞

yeah, it's because it's downloading v2.15.8 instead of v2.16.4 as the latest PHAR for https://cs.sensiolabs.org/download/php-cs-fixer-v2.phar URL

2.16.4 works as expected locally. I will try to resolve it as a separate issue somewhere later today

[maks-rafalko]

If we can extend #1327 to allow injecting arbitrary configuration for a plugin, this feature is a great candidate for a standard plugin.

Agree. That was my plan - to release this one ASAP, and then, when we are ready with the plugin system (which can take some time) - we will refactor internal implementation.

[maks-rafalko]

Regarding php-cs-fixer: there is an open issue, let's see how they will resolve it: PHP-CS-Fixer/PHP-CS-Fixer#5099

I think if they wont' fix it today, we can think about downloading particular hardcoded version for the time being

[sanmai]

I did composer require --dev friendsofphp/php-cs-fixer for local CS works.

[sanmai]

Shall we merge this?

[maks-rafalko]

Thank you @sanmai & @Slamdunk for great review