Fix phpstan/phpstan#13453: Templated return type error message is self-contradictory

[phpstan-bot]

Summary

When two different template types have the same name and bound but belong to different scopes (e.g., a function template T of ResultA and an interface template T of ResultA), error messages like "should return T of ResultA but returns T of ResultA" were self-contradictory and confusing to users. The fix escalates the verbosity level to precise when both types produce identical descriptions, adding scope information to disambiguate them.

Changes

• Modified VerbosityLevel::getRecommendedLevelByType() in src/Type/VerbosityLevel.php to detect when accepting and accepted types have identical descriptions at the chosen level, and escalate to precise verbosity in that case
• Added regression test in tests/PHPStan/Rules/Functions/data/bug-13453.php and corresponding test method in tests/PHPStan/Rules/Functions/ReturnTypeRuleTest.php

Root cause

VerbosityLevel::getRecommendedLevelByType() chose verbosity based on type complexity (constant values, callables, accessory types, etc.) but never considered whether the two types being compared would produce identical string descriptions. Template types from different scopes with the same name and bound are semantically different but described identically at typeOnly and value verbosity levels. Only at precise level does the scope information (e.g., "function run(), argument" vs "class I, parameter") get included.

Test

The regression test reproduces the exact scenario from the issue: a function with @template T of ResultA returning a value whose type is T of ResultA from an interface template. The test verifies the error message now includes scope disambiguation.

Fixes phpstan/phpstan#13453

[VincentLanglet]

You made two changes, but only one test ; could you test the other change too ?

[phpstan-bot]

Done. I added a test (testBug13453Invariant) that covers the second code path in VerbosityLevel::getRecommendedLevelByType() — the branch where $containsInvariantTemplateType is true. The test uses a generic Container<T> (which has an invariant template by default) wrapping template types from different scopes (function run() vs class I), verifying that the descriptions are disambiguated with scope information when they would otherwise be identical.

[VincentLanglet]

the written tests need Requires PHP >= 8.0

[phpstan-bot]

make phpstan also passed successfully — no static analysis issues.

[VincentLanglet]

This fix seems ok (the right one ?) to me, but I'm unsure ondrej agree with the fact some error message will be updated.
On the other side, I don't see any other way to close this issue. Unless we fix other generic issues first...

WDYT @staabm ? Might be worth asking ondrej before merging this (?)