Fix phpstan/phpstan#13453: Disambiguate identical template type descriptions in error messages

- When two different template types produce the same description at the chosen verbosity level, escalate to precise verbosity to include scope information
- This fixes self-contradictory messages like "should return T of ResultA but returns T of ResultA" by showing "T of ResultA (function run(), argument) but returns T of ResultA (class I, parameter)"
- New regression test in tests/PHPStan/Rules/Functions/data/bug-13453.php

Author: github-actions[bot]

src/Type/VerbosityLevel.php

@@ -221,7 +221,13 @@ public static function getRecommendedLevelByType(Type $acceptingType, ?Type $acc
 		});
 
 		if (!$containsInvariantTemplateType) {
-			return $verbosity ?? self::typeOnly();
+			$level = $verbosity ?? self::typeOnly();
+
+			if ($acceptingType->describe($level) === $acceptedType->describe($level)) {
+				return self::precise();
+			}
+
+			return $level;
 		}
 
 		/** @var bool $moreVerbose */
@@ -234,7 +240,13 @@ public static function getRecommendedLevelByType(Type $acceptingType, ?Type $acc
 			return self::precise();
 		}
 
-		return $moreVerbose ? self::value() : $verbosity ?? self::typeOnly();
+		$level = $moreVerbose ? self::value() : $verbosity ?? self::typeOnly();
+
+		if ($acceptingType->describe($level) === $acceptedType->describe($level)) {
+			return self::precise();
+		}
+
+		return $level;
 	}
 
 	/**

tests/PHPStan/Rules/Functions/ReturnTypeRuleTest.php

@@ -411,4 +411,16 @@ public function testBug12397(): void
 		$this->analyse([__DIR__ . '/data/bug-12397.php'], []);
 	}
 
+	public function testBug13453(): void
+	{
+		$this->checkNullables = true;
+		$this->checkExplicitMixed = true;
+		$this->analyse([__DIR__ . '/data/bug-13453.php'], [
+			[
+				'Function Bug13453\run() should return T of Bug13453\ResultA (function Bug13453\run(), argument) but returns T of Bug13453\ResultA (class Bug13453\I, parameter).',
+				33,
+			],
+		]);
+	}
+
 }

tests/PHPStan/Rules/Functions/data/bug-13453.php

@@ -0,0 +1,40 @@
+<?php // lint >= 8.3
+
+declare(strict_types = 1);
+
+namespace Bug13453;
+
+/** @template T of ResultA */
+interface I {
+	/** @var class-string<T> */
+	public const string ResultType = ResultA::class;
+}
+
+class ResultA {
+	public function __construct(public string $value) {}
+}
+
+class ResultB extends ResultA {
+	public function rot13(): string { return str_rot13($this->value); }
+}
+
+/** @template-implements I<ResultB> */
+class In implements I {
+	public const string ResultType = ResultB::class;
+}
+
+/**
+ * @template T of ResultA
+ * @param I<T> $in
+ * @return T
+ */
+function run(I $in): ResultA {
+	$value = 'abc';
+	return new ($in::ResultType)($value);
+}
+
+function main(): void {
+	$in = new In();
+	$ret = run($in);
+	print $ret->rot13();
+}