feat: add support for phpdoc return types

Author: calebdw

rules-tests/DeadCode/Rector/FunctionLike/NarrowTooWideReturnTypeRector/Fixture/final_class.php.inc

@@ -2,7 +2,7 @@
 
 namespace Rector\Tests\DeadCode\Rector\FunctionLike\NarrowTooWideReturnTypeRector\Fixture;
 
-final class ClassMethodCase
+final class FinalClass
 {
     public function getData(): string|int|\DateTime
     {
@@ -46,7 +46,7 @@ final class ClassMethodCase
 
 namespace Rector\Tests\DeadCode\Rector\FunctionLike\NarrowTooWideReturnTypeRector\Fixture;
 
-final class ClassMethodCase
+final class FinalClass
 {
     public function getData(): string|int
     {

rules-tests/DeadCode/Rector/FunctionLike/NarrowTooWideReturnTypeRector/Fixture/phpdocs.php.inc

@@ -0,0 +1,83 @@
+<?php
+
+namespace Rector\Tests\DeadCode\Rector\FunctionLike\NarrowTooWideReturnTypeRector\Fixture;
+
+use Rector\Tests\DeadCode\Rector\FunctionLike\NarrowTooWideReturnTypeRector\Source\SomeInterface;
+
+final class PhpDocs
+{
+    /** @return string|int|float */
+    public function foo(): string|int|float
+    {
+        if (rand(0, 1)) {
+            return 'text';
+        }
+
+        return 1000;
+    }
+
+    /**
+     * @param class-string<SomeInterface> $class
+     * @return class-string<SomeInterface>|int
+     */
+    public function bar($class): string|int
+    {
+        return $class;
+    }
+
+    /** @return class-string<SomeInterface>|int */
+    public function baz($class): string|int
+    {
+        return SomeInterface::class;
+    }
+
+    /** @return \Iterator<int, int>|string */
+    function qux(): \Iterator|string
+    {
+       return new \ArrayIterator([1]);
+    }
+}
+
+?>
+-----
+<?php
+
+namespace Rector\Tests\DeadCode\Rector\FunctionLike\NarrowTooWideReturnTypeRector\Fixture;
+
+use Rector\Tests\DeadCode\Rector\FunctionLike\NarrowTooWideReturnTypeRector\Source\SomeInterface;
+
+final class PhpDocs
+{
+    /** @return int|string */
+    public function foo(): string|int
+    {
+        if (rand(0, 1)) {
+            return 'text';
+        }
+
+        return 1000;
+    }
+
+    /**
+     * @param class-string<SomeInterface> $class
+     * @return class-string<Rector\Tests\DeadCode\Rector\FunctionLike\NarrowTooWideReturnTypeRector\Source\SomeInterface>
+     */
+    public function bar($class): string
+    {
+        return $class;
+    }
+
+    /** @return class-string<Rector\Tests\DeadCode\Rector\FunctionLike\NarrowTooWideReturnTypeRector\Source\SomeInterface> */
+    public function baz($class): string
+    {
+        return SomeInterface::class;
+    }
+
+    /** @return \Iterator<int, int> */
+    function qux(): \Iterator
+    {
+       return new \ArrayIterator([1]);
+    }
+}
+
+?>

rules/DeadCode/Rector/FunctionLike/NarrowTooWideReturnTypeRector.php

@@ -4,6 +4,7 @@
 
 namespace Rector\DeadCode\Rector\FunctionLike;
 
+use PHPStan\Type\UnionType as PHPStanUnionType;
 use PhpParser\Node;
 use PhpParser\Node\ComplexType;
 use PhpParser\Node\Expr;
@@ -23,6 +24,9 @@
 use PHPStan\Type\NullType;
 use PHPStan\Type\Type;
 use PHPStan\Type\TypeCombinator;
+use Rector\BetterPhpDocParser\PhpDocInfo\PhpDocInfo;
+use Rector\BetterPhpDocParser\PhpDocInfo\PhpDocInfoFactory;
+use Rector\BetterPhpDocParser\PhpDocManipulator\PhpDocTypeChanger;
 use Rector\PhpParser\Node\BetterNodeFinder;
 use Rector\PHPStan\ScopeFetcher;
 use Rector\PHPStanStaticTypeMapper\Enum\TypeKind;
@@ -46,6 +50,8 @@ public function __construct(
         private readonly StaticTypeMapper $staticTypeMapper,
         private readonly ReflectionResolver $reflectionResolver,
         private readonly SilentVoidResolver $silentVoidResolver,
+        private readonly PhpDocTypeChanger $phpDocTypeChanger,
+        private readonly PhpDocInfoFactory $phpDocInfoFactory,
     ) {
     }
 
@@ -120,17 +126,31 @@ public function refactor(Node $node): ?Node
             return null;
         }
 
-        $returnType = $node->returnType;
-        Assert::isInstanceOfAny($returnType, [UnionType::class, NullableType::class]);
+        $phpDocInfo = $this->phpDocInfoFactory->createFromNode($node);
+
+        if ($phpDocInfo?->hasByName('@return')) {
+            $returnType = $phpDocInfo->getReturnType();
+        } else {
+            $returnType = $node->returnType;
+            Assert::isInstanceOfAny($returnType, [UnionType::class, NullableType::class]);
+            $returnType = $this->staticTypeMapper->mapPhpParserNodePHPStanType($returnType);
+        }
 
         $actualReturnTypes = $this->collectActualReturnTypes($node, $returnStatements, $isAlwaysTerminating);
-        $newReturnType = $this->narrowUnionReturnType($returnType, $actualReturnTypes);
+        $newReturnType = $this->narrowReturnType($returnType, $actualReturnTypes);
 
         if ($newReturnType === null) {
             return null;
         }
 
-        $node->returnType = $newReturnType;
+        $node->returnType = $this->staticTypeMapper->mapPHPStanTypeToPhpParserNode(
+            $newReturnType,
+            TypeKind::RETURN
+        );
+
+        if ($phpDocInfo instanceof PhpDocInfo) {
+            $this->phpDocTypeChanger->changeReturnType($node, $phpDocInfo, $newReturnType);
+        }
 
         return $node;
     }
@@ -182,7 +202,7 @@ private function collectActualReturnTypes(
         bool $isAlwaysTerminating,
     ): array {
         if ($node instanceof ArrowFunction) {
-            return [$this->nodeTypeResolver->getNativeType($node->expr)];
+            return [$this->getType($node->expr)];
         }
 
         $returnTypes = [];
@@ -192,7 +212,7 @@ private function collectActualReturnTypes(
                 continue;
             }
 
-            $returnTypes[] = $this->nodeTypeResolver->getNativeType($returnStatement->expr);
+            $returnTypes[] = $this->getType($returnStatement->expr);
         }
 
         if (! $isAlwaysTerminating) {
@@ -205,23 +225,15 @@ private function collectActualReturnTypes(
     /**
      * @param Type[] $actualReturnTypes
      */
-    private function narrowUnionReturnType(
-        UnionType|NullableType $returnType,
-        array $actualReturnTypes
-    ): ComplexType|Identifier|Name|null {
-        $types = $returnType instanceof UnionType
-            ? $returnType->types
-            : [$returnType->type, new Identifier('null')];
+    private function narrowReturnType(Type $returnType, array $actualReturnTypes): Type|null
+    {
+        $types = $returnType instanceof PHPStanUnionType ? $returnType->getTypes() : [$returnType];
         $usedTypes = [];
 
         foreach ($types as $type) {
-            $declaredType = $type instanceof Expr
-                ? $this->nodeTypeResolver->getNativeType($type)
-                : $this->getType($type);
-
             foreach ($actualReturnTypes as $actualType) {
-                if (! $declaredType->isSuperTypeOf($actualType)->no()) {
-                    $usedTypes[] = $declaredType;
+                if (! $type->isSuperTypeOf($actualType)->no()) {
+                    $usedTypes[] = $type;
                     break;
                 }
             }
@@ -233,10 +245,7 @@ private function narrowUnionReturnType(
             return null;
         }
 
-        return $this->staticTypeMapper->mapPHPStanTypeToPhpParserNode(
-            TypeCombinator::union(...$usedTypes),
-            TypeKind::RETURN
-        );
+        return TypeCombinator::union(...$usedTypes);
     }
 
     private function hasYield(ClassMethod|Function_|Closure|ArrowFunction $node): bool