From b677cfa1aad45a7da47db57b77bc8e933a978643 Mon Sep 17 00:00:00 2001
From: Abdul Malik Ikhsan <samsonasik@gmail.com>
Date: Sun, 12 Jul 2026 22:51:45 +0700
Subject: [PATCH] [DeadCode] Skip template type on
 RemoveReturnTagIncompatibleWithNativeTypeRector

---
 .../Fixture/skip_templated_type.php.inc          | 16 ++++++++++++++++
 .../Fixture/skip_union_return_template.php.inc   | 16 ++++++++++++++++
 ...ReturnTagIncompatibleWithNativeTypeRector.php | 13 +++++++++++++
 3 files changed, 45 insertions(+)
 create mode 100644 rules-tests/DeadCode/Rector/ClassMethod/RemoveReturnTagIncompatibleWithNativeTypeRector/Fixture/skip_templated_type.php.inc
 create mode 100644 rules-tests/DeadCode/Rector/ClassMethod/RemoveReturnTagIncompatibleWithNativeTypeRector/Fixture/skip_union_return_template.php.inc

diff --git a/rules-tests/DeadCode/Rector/ClassMethod/RemoveReturnTagIncompatibleWithNativeTypeRector/Fixture/skip_templated_type.php.inc b/rules-tests/DeadCode/Rector/ClassMethod/RemoveReturnTagIncompatibleWithNativeTypeRector/Fixture/skip_templated_type.php.inc
new file mode 100644
index 00000000000..ff01d109f1d
--- /dev/null
+++ b/rules-tests/DeadCode/Rector/ClassMethod/RemoveReturnTagIncompatibleWithNativeTypeRector/Fixture/skip_templated_type.php.inc
@@ -0,0 +1,16 @@
+<?php
+
+namespace Rector\Tests\DeadCode\Rector\ClassMethod\RemoveReturnTagIncompatibleWithNativeTypeRector\Fixture;
+
+final class SkipTemplatedType
+{
+    /**
+     * @template T of array<string>
+     * @param T $value
+     * @return T
+     */
+    public function run(array $value): array
+    {
+        return $value;
+    }
+}
diff --git a/rules-tests/DeadCode/Rector/ClassMethod/RemoveReturnTagIncompatibleWithNativeTypeRector/Fixture/skip_union_return_template.php.inc b/rules-tests/DeadCode/Rector/ClassMethod/RemoveReturnTagIncompatibleWithNativeTypeRector/Fixture/skip_union_return_template.php.inc
new file mode 100644
index 00000000000..d6073b2a331
--- /dev/null
+++ b/rules-tests/DeadCode/Rector/ClassMethod/RemoveReturnTagIncompatibleWithNativeTypeRector/Fixture/skip_union_return_template.php.inc
@@ -0,0 +1,16 @@
+<?php
+
+namespace Rector\Tests\DeadCode\Rector\ClassMethod\RemoveReturnTagIncompatibleWithNativeTypeRector\Fixture;
+
+final class SkipUnionReturnTemplate
+{
+    /**
+     * @template T of array<string>
+     * @param T|null $value
+     * @return T|null
+     */
+    public function run(?array $value): ?array
+    {
+        return $value;
+    }
+}
diff --git a/rules/DeadCode/Rector/ClassMethod/RemoveReturnTagIncompatibleWithNativeTypeRector.php b/rules/DeadCode/Rector/ClassMethod/RemoveReturnTagIncompatibleWithNativeTypeRector.php
index 12396fdd761..c412683ffcb 100644
--- a/rules/DeadCode/Rector/ClassMethod/RemoveReturnTagIncompatibleWithNativeTypeRector.php
+++ b/rules/DeadCode/Rector/ClassMethod/RemoveReturnTagIncompatibleWithNativeTypeRector.php
@@ -108,6 +108,10 @@ public function refactor(Node $node): ?Node
         }
 
         $nativeReturnType = $this->staticTypeMapper->mapPhpParserNodePHPStanType($node->returnType);
+        if ($this->isReturnTemplate($phpDocInfo, $returnTagValueNode)) {
+            return null;
+        }
+
         $docReturnType = $phpDocInfo->getReturnType();
 
         // a subtype/narrowing is legitimate; only a contradiction is dead
@@ -145,4 +149,13 @@ private function isClassTypeAlias(Node $node, ReturnTagValueNode $returnTagValue
         return $returnTagValueNode->type instanceof IdentifierTypeNode
             && isset($typeAliases[$returnTagValueNode->type->name]);
     }
+
+    private function isReturnTemplate(PhpDocInfo $phpDocInfo, ReturnTagValueNode $returnTagValueNode): bool
+    {
+        if (! $returnTagValueNode->type instanceof IdentifierTypeNode) {
+            return false;
+        }
+
+        return in_array($returnTagValueNode->type->name, $phpDocInfo->getTemplateNames(), true);
+    }
 }