[DeadCode] Keep generic @var/@return self<...> narrowing annotations

rules-tests/DeadCode/Rector/ClassMethod/RemoveDuplicatedReturnSelfDocblockRector/Fixture/skip_generic_return_self.php.inc

@@ -0,0 +1,18 @@
+<?php
+
+namespace Rector\Tests\DeadCode\Rector\ClassMethod\RemoveDuplicatedReturnSelfDocblockRector\Fixture;
+
+/**
+ * @template TSuccessValue
+ * @template TFailureValue
+ */
+final class SkipGenericReturnSelf
+{
+    /**
+     * @return self<TSuccessValue, never>
+     */
+    public function success(): self
+    {
+        return $this;
+    }
+}

rules-tests/DeadCode/Rector/Node/RemoveNonExistingVarAnnotationRector/Fixture/skip_generic_var_on_new_self.php.inc

@@ -0,0 +1,16 @@
+<?php
+
+namespace Rector\Tests\DeadCode\Rector\Node\RemoveNonExistingVarAnnotationRector\Fixture;
+
+/**
+ * @template TSuccessValue
+ * @template TFailureValue
+ */
+final class SkipGenericVarOnNewSelf
+{
+    public static function success(mixed $value = null): self
+    {
+        /** @var self<TSuccessValue, never> */
+        return new self();
+    }
+}

rules/DeadCode/Rector/ClassMethod/RemoveDuplicatedReturnSelfDocblockRector.php

@@ -11,6 +11,7 @@
 use PHPStan\PhpDocParser\Ast\PhpDoc\ReturnTagValueNode;
 use PHPStan\PhpDocParser\Ast\Type\TypeNode;
 use PHPStan\Reflection\ClassReflection;
+use PHPStan\Type\Generic\GenericObjectType;
 use PHPStan\Type\ObjectType;
 use PHPStan\Type\StaticType;
 use Rector\BetterPhpDocParser\PhpDocInfo\PhpDocInfo;
@@ -126,6 +127,11 @@ private function isCurrentObjectReturnDocType(
     ): bool {
         $docType = $this->staticTypeMapper->mapPHPStanPhpDocTypeNodeToPHPStanType($typeNode, $classMethod);
 
+        // generic narrowing, e.g. @return self<TValue, never> is not a plain duplicate of the native self type
+        if ($docType instanceof GenericObjectType) {
+            return false;
+        }
+
         // covers @return $this and @return static
         if ($docType instanceof StaticType) {
             return $docType->getClassName() === $classReflection->getName();

rules/DeadCode/Rector/Node/RemoveNonExistingVarAnnotationRector.php

@@ -22,6 +22,7 @@
 use PhpParser\Node\Stmt\Switch_;
 use PhpParser\Node\Stmt\While_;
 use PHPStan\PhpDocParser\Ast\PhpDoc\VarTagValueNode;
+use PHPStan\PhpDocParser\Ast\Type\GenericTypeNode;
 use PHPStan\PhpDocParser\Ast\Type\IdentifierTypeNode;
 use Rector\BetterPhpDocParser\PhpDocInfo\PhpDocInfoFactory;
 use Rector\Comments\NodeDocBlock\DocBlockUpdater;
@@ -157,7 +158,7 @@ public function refactor(Node $node): ?Node
 
                 $variableName = ltrim($varTagValueNode->variableName, '$');
 
-                if ($variableName === '' && $this->isAllowedEmptyVariableName($stmt)) {
+                if ($variableName === '' && $this->isAllowedEmptyVariableName($stmt, $varTagValueNode)) {
                     continue;
                 }
 
@@ -252,12 +253,34 @@ private function isObjectShapePseudoType(VarTagValueNode $varTagValueNode): bool
         return str_contains($varTagValueNode->description, '}');
     }
 
-    private function isAllowedEmptyVariableName(Stmt $stmt): bool
+    private function isAllowedEmptyVariableName(Stmt $stmt, VarTagValueNode $varTagValueNode): bool
     {
         if ($stmt instanceof Return_ && $stmt->expr instanceof CallLike && ! $stmt->expr instanceof New_) {
             return true;
         }
 
+        // generic/template narrowing over the instantiated class, e.g. /** @var self<TValue, never> */ return new self(...)
+        if ($stmt instanceof Return_ && $stmt->expr instanceof New_ && $this->isGenericTypeOfNewClass(
+            $stmt->expr,
+            $varTagValueNode
+        )) {
+            return true;
+        }
+
         return $stmt instanceof Expression && $stmt->expr instanceof Assign && $stmt->expr->var instanceof Variable;
     }
+
+    private function isGenericTypeOfNewClass(New_ $new, VarTagValueNode $varTagValueNode): bool
+    {
+        if (! $varTagValueNode->type instanceof GenericTypeNode) {
+            return false;
+        }
+
+        $newClassName = $this->getName($new->class);
+        if ($newClassName === null) {
+            return false;
+        }
+
+        return strcasecmp($varTagValueNode->type->type->name, $newClassName) === 0;
+    }
 }