Implement @pure-unless-parameter-passed

[zonuexe]

Implements the @pure-unless-parameter-passed PHPDoc tag: a parameter-level annotation declaring that the function/method is pure unless an argument is passed for that (by-ref out) parameter. Built on top of 2.2.x, following the same architecture as @pure-unless-callable-is-impure (#3482) — the parameter-level flag is TrinaryLogic from the start so it composes correctly on union/intersection method variants.

Background

This closes @staabm's phpstan/phpstan#11884, where he pointed out that str_replace() (and str_ireplace/preg_replace) could be treated as pure when the by-ref $count argument is omitted, and asked for "a solution independent of concrete function signatures" rather than one-off metadata flags. ondrejmirtes suggested the @phpstan-pure-unless-parameter-passed annotation name in response. @staabm then implemented the parser-side syntax support at phpstan/phpdoc-parser#259, which is still open — ondrejmirtes asked there for the phpstan-src implementation to be ready first before merging the parser side. This PR is that implementation.

Parser support

Since phpstan/phpdoc-parser#259 is not merged yet, this PR parses the tag from the generic tag value as a stopgap (PhpDocNodeResolver::resolveParamPureUnlessParameterPassed(), marked with a TODO to switch to PhpDocNode::getPureUnlessParameterIsPassedTagValues() once the parser PR merges).

How it works

• The tag (and its @phpstan- prefixed alias) is resolved into per-parameter flags, threaded through the reflection layer (ExtendedParameterReflection::isPureUnlessParameterPassedParameter(): TrinaryLogic), and populated for builtins via functionMetadata (str_replace, str_ireplace, preg_replace, preg_match, preg_match_all, similar_text).
• SimpleImpurePoint::resolvePureUnlessParameterPassedVerdict() checks whether an argument was actually passed for each flagged parameter:
  • the by-ref parameter is omitted (or explicitly null) → the call stays pure;
  • an argument is passed → unchanged (possibly-impure) behavior.
• combineAcceptors() merges the flag across union method variants with equals-or-Maybe, so a parameter tagged in some members but not others correctly becomes Maybe rather than being silently dropped.

/** @phpstan-pure */
function normalize(string $s): string
{
    return str_replace('_', '-', $s); // no longer "Possibly impure"
}

/** @phpstan-pure */
function normalizeAndCount(string $s, int &$count): string
{
    return str_replace('_', '-', $s, $count); // still "Possibly impure" - $count is written
}

• Add function map (str_replace, str_ireplace, preg_replace, preg_match, preg_match_all, similar_text)
• Add tests (userland functions/methods, builtins, union-variant Maybe combine)
• Add rules (no new rule needed — the impure-point suppression feeds the existing pure-context check)

refs #3482, phpstan/phpdoc-parser#259

Closes phpstan/phpstan#11884

[zonuexe]

Rebased onto latest 2.2.x. While reworking the tests I found and fixed a real asymmetry in SimpleImpurePoint::createFromVariant(): when an argument was passed for a @pure-unless-parameter-passed by-ref parameter, the call was only reported as possibly impure, whereas passing it is a definite side effect. It now reports certain impurity, matching both the @pure-unless-callable-is-impure block right above it and the constructor path in NewHandler. Added coverage for methods, intersection receivers, inheritance (including a renamed parameter), and first-class callables.

Current CI status — the remaining red checks are all unrelated to this PR's code:

• Mutation Testing passes on 8.4 (0 escaped; the two NewHandler TrinaryLogicMutator mutants are killed by static analysis). On 8.3 those same two mutants escape and an unrelated mutant times out — a nondeterministic SA-step/coverage artifact on the slower runner, not a genuine test gap. The two mutants are not killable by a test because a Maybe verdict is unreachable at the constructor call site by construction (single-variant constructors; dynamic new bails out on a union of classes).
• Rector integration fails with undefined method ...getPureUnlessParameterIsPassedTagValues(). This is expected: phpdoc-parser 2.3.3 (which adds that method) was released today, and no PHPStan/Rector release bundling it exists yet, so the integration environment resolves an older phpdoc-parser. It will clear once a release catches up.
• E2E result-cache-restore-without-reflection fails on 2.2.x itself, from an upstream phpstan-phpunit@dev constructor-parameter change.
• Benchmark and the old-PHPUnit Windows job failures are pre-existing/flaky (the latter is an unrelated IntersectionTypeTest data set) and reproduce independently of this PR.

[phpstan-bot]

This pull request has been marked as ready for review.

[staabm]

would it make sense to emit a new error when @pure-unless-parameter-passed is used on a non-optional parameter?

[phpstan-bot]

This pull request has been marked as ready for review.

[zonuexe]

Update after the latest review round:

• Non-optional parameter (suggested above): a non-optional parameter is always passed, so the tag can never keep the function/method pure. This is now reported as a misuse (pureFunction.nonOptionalParameterPassed / pureMethod.nonOptionalParameterPassed), mirroring the existing @pure-unless-callable-is-impure redundancy check. Wiring it up surfaced a gap: the declaration-side flag was dropped for functions (enterFunction() never received it, while the method path already did), fixed as well.
• Function-level map: to find the flagged parameters at a declaration, the check now uses a getPureUnlessParameterPassedParameters() map with array_key_exists, exactly like the callable sibling, instead of the per-parameter ->yes(). This removes an equivalent TrinaryLogicMutator mutant in FunctionPurityCheck (at a declaration site the flag is only ever Yes or No, never Maybe).
• @phpstan-pure-unless-callable-is-impure was missing from the known-tags list and was reported as an unknown tag; added it there too.

Mutation status: 8.4 is green (0 escaped). 8.3 still reports the two NewHandler constructor-path mutants; these are equivalent ($passedVerdict can only be Yes or No at a new call site: a userland constructor has a single variant, and dynamic new bails out on a union of classes, so Maybe is unreachable) and are killed by static analysis on 8.4. The remaining red checks (Benchmark, Rector integration) are unrelated as noted earlier; E2E now passes after picking up the phpstan-phpunit update.

[phpstan-bot]

This pull request has been marked as ready for review.