fix(dead-code): preserve generic @return tags in RemoveReturnTagIncompatibleWithNativeTypeRector (#8183)

The rule incorrectly removed `@return self<T>` and `@return ClassName<T>` annotations when the native return type was `self`. These annotations are not incompatible, because they carry template parameters that the native type cannot express. PHPStan and Psalm rely on them for generic type inference.

Add an early bail-out when the `@return` type node is a `GenericTypeNode`, which covers all parameterized return types (`self<T>`, `static<T>`, `Foo<T>`).

Author: maartenpaauw

rules-tests/DeadCode/Rector/ClassMethod/RemoveReturnTagIncompatibleWithNativeTypeRector/Fixture/skip_generic_fluent_builder.php.inc

@@ -0,0 +1,26 @@
+<?php
+
+namespace Rector\Tests\DeadCode\Rector\ClassMethod\RemoveReturnTagIncompatibleWithNativeTypeRector\Fixture;
+
+/**
+ * @template TPayload
+ * @template TDomainId
+ */
+final class SkipGenericFluentBuilder
+{
+    /**
+     * @return SkipGenericFluentBuilder<TPayload, TDomainId>
+     */
+    public function withFoo(): self
+    {
+        return $this;
+    }
+
+    /**
+     * @return SkipGenericFluentBuilder<TPayload, TDomainId>
+     */
+    public function withBar(): self
+    {
+        return $this;
+    }
+}

rules-tests/DeadCode/Rector/ClassMethod/RemoveReturnTagIncompatibleWithNativeTypeRector/Fixture/skip_generic_self_return.php.inc

@@ -0,0 +1,31 @@
+<?php
+
+namespace Rector\Tests\DeadCode\Rector\ClassMethod\RemoveReturnTagIncompatibleWithNativeTypeRector\Fixture;
+
+/**
+ * @template TAdded
+ * @template TRemoved
+ */
+final readonly class SkipGenericSelfReturn
+{
+    /**
+     * @param list<TAdded> $added
+     * @param list<TRemoved> $removed
+     */
+    private function __construct(
+        public array $added,
+        public array $removed,
+    ) {
+    }
+
+    /**
+     * @param list<TAdded> $added
+     * @param list<TRemoved> $removed
+     *
+     * @return self<TAdded, TRemoved>
+     */
+    public static function create(array $added, array $removed): self
+    {
+        return new self($added, $removed);
+    }
+}

rules/DeadCode/Rector/ClassMethod/RemoveReturnTagIncompatibleWithNativeTypeRector.php

@@ -10,6 +10,7 @@
 use PHPStan\Analyser\Scope;
 use PHPStan\PhpDoc\ResolvedPhpDocBlock;
 use PHPStan\PhpDocParser\Ast\PhpDoc\ReturnTagValueNode;
+use PHPStan\PhpDocParser\Ast\Type\GenericTypeNode;
 use PHPStan\PhpDocParser\Ast\Type\IdentifierTypeNode;
 use Rector\BetterPhpDocParser\PhpDocInfo\PhpDocInfo;
 use Rector\BetterPhpDocParser\PhpDocInfo\PhpDocInfoFactory;
@@ -103,6 +104,11 @@ public function refactor(Node $node): ?Node
             return null;
         }
 
+        // keep generic return types, because they carry template info the native type cannot express
+        if ($returnTagValueNode->type instanceof GenericTypeNode) {
+            return null;
+        }
+
         if ($this->isClassTypeAlias($node, $returnTagValueNode)) {
             return null;
         }