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