Narrow object return type (#7575)

* Narrow object return type

When the actual return type of a method is a subtype of the declared
return type, we can replace the declared return type with the actual return type

* replace override attribute

* skip when parent has specific class return type

* apply feedback

* skip non final classes

* scope return and allow final methods

* Handle generics using AST instead of PHPStan

* remove dummy classes

* use isFinalByKeyword

* move to source

* update description

* use isFinalByKeyword

* return if method is private

* Resolve returned class via generics

* Revert "Resolve returned class via generics"

This reverts commit b6e08c8.

Author: Orest-Divintari

rules-tests/TypeDeclaration/Rector/ClassMethod/NarrowObjectReturnTypeRector/Fixture/narrow_final_method_in_non_final_class.php.inc

@@ -0,0 +1,31 @@
+<?php
+
+namespace Rector\Tests\TypeDeclaration\Rector\ClassMethod\NarrowObjectReturnTypeRector\Fixture;
+
+use Rector\Tests\TypeDeclaration\Rector\ClassMethod\NarrowObjectReturnTypeRector\Source\ConferenceTalk;
+
+class NonFinalClassWithFinalMethod
+{
+    final public function create(): object
+    {
+        return new ConferenceTalk();
+    }
+}
+
+?>
+-----
+<?php
+
+namespace Rector\Tests\TypeDeclaration\Rector\ClassMethod\NarrowObjectReturnTypeRector\Fixture;
+
+use Rector\Tests\TypeDeclaration\Rector\ClassMethod\NarrowObjectReturnTypeRector\Source\ConferenceTalk;
+
+class NonFinalClassWithFinalMethod
+{
+    final public function create(): \Rector\Tests\TypeDeclaration\Rector\ClassMethod\NarrowObjectReturnTypeRector\Source\ConferenceTalk
+    {
+        return new ConferenceTalk();
+    }
+}
+
+?>

rules-tests/TypeDeclaration/Rector/ClassMethod/NarrowObjectReturnTypeRector/Fixture/narrow_from_object.php.inc

@@ -0,0 +1,33 @@
+<?php
+
+namespace Rector\Tests\TypeDeclaration\Rector\ClassMethod\NarrowObjectReturnTypeRector\Fixture;
+
+use Rector\Tests\TypeDeclaration\Rector\ClassMethod\NarrowObjectReturnTypeRector\Source\AbstractFactory;
+use Rector\Tests\TypeDeclaration\Rector\ClassMethod\NarrowObjectReturnTypeRector\Source\ConferenceTalk;
+
+final class TalkFactory extends AbstractFactory
+{
+    protected function build(): object
+    {
+        return new ConferenceTalk();
+    }
+}
+
+?>
+-----
+<?php
+
+namespace Rector\Tests\TypeDeclaration\Rector\ClassMethod\NarrowObjectReturnTypeRector\Fixture;
+
+use Rector\Tests\TypeDeclaration\Rector\ClassMethod\NarrowObjectReturnTypeRector\Source\AbstractFactory;
+use Rector\Tests\TypeDeclaration\Rector\ClassMethod\NarrowObjectReturnTypeRector\Source\ConferenceTalk;
+
+final class TalkFactory extends AbstractFactory
+{
+    protected function build(): \Rector\Tests\TypeDeclaration\Rector\ClassMethod\NarrowObjectReturnTypeRector\Source\ConferenceTalk
+    {
+        return new ConferenceTalk();
+    }
+}
+
+?>

rules-tests/TypeDeclaration/Rector/ClassMethod/NarrowObjectReturnTypeRector/Fixture/narrow_from_parent_to_child.php.inc

@@ -0,0 +1,33 @@
+<?php
+
+namespace Rector\Tests\TypeDeclaration\Rector\ClassMethod\NarrowObjectReturnTypeRector\Fixture;
+
+use Rector\Tests\TypeDeclaration\Rector\ClassMethod\NarrowObjectReturnTypeRector\Source\Talk;
+use Rector\Tests\TypeDeclaration\Rector\ClassMethod\NarrowObjectReturnTypeRector\Source\ConferenceTalkExtended;
+
+final class TalkFactoryExtended
+{
+    public function createConferenceTalk(): Talk
+    {
+        return new ConferenceTalkExtended();
+    }
+}
+
+?>
+-----
+<?php
+
+namespace Rector\Tests\TypeDeclaration\Rector\ClassMethod\NarrowObjectReturnTypeRector\Fixture;
+
+use Rector\Tests\TypeDeclaration\Rector\ClassMethod\NarrowObjectReturnTypeRector\Source\Talk;
+use Rector\Tests\TypeDeclaration\Rector\ClassMethod\NarrowObjectReturnTypeRector\Source\ConferenceTalkExtended;
+
+final class TalkFactoryExtended
+{
+    public function createConferenceTalk(): \Rector\Tests\TypeDeclaration\Rector\ClassMethod\NarrowObjectReturnTypeRector\Source\ConferenceTalkExtended
+    {
+        return new ConferenceTalkExtended();
+    }
+}
+
+?>

rules-tests/TypeDeclaration/Rector/ClassMethod/NarrowObjectReturnTypeRector/Fixture/narrow_with_generic_parent.php.inc

@@ -0,0 +1,39 @@
+<?php
+
+namespace Rector\Tests\TypeDeclaration\Rector\ClassMethod\NarrowObjectReturnTypeRector\Fixture;
+
+use Rector\Tests\TypeDeclaration\Rector\ClassMethod\NarrowObjectReturnTypeRector\Source\AbstractGenericFactory;
+use Rector\Tests\TypeDeclaration\Rector\ClassMethod\NarrowObjectReturnTypeRector\Source\ConferenceTalk;
+
+/**
+ * @extends AbstractGenericFactory<ConferenceTalk>
+ */
+final class ConcreteGenericFactory extends AbstractGenericFactory
+{
+    public function build(): object
+    {
+        return new ConferenceTalk();
+    }
+}
+
+?>
+-----
+<?php
+
+namespace Rector\Tests\TypeDeclaration\Rector\ClassMethod\NarrowObjectReturnTypeRector\Fixture;
+
+use Rector\Tests\TypeDeclaration\Rector\ClassMethod\NarrowObjectReturnTypeRector\Source\AbstractGenericFactory;
+use Rector\Tests\TypeDeclaration\Rector\ClassMethod\NarrowObjectReturnTypeRector\Source\ConferenceTalk;
+
+/**
+ * @extends AbstractGenericFactory<ConferenceTalk>
+ */
+final class ConcreteGenericFactory extends AbstractGenericFactory
+{
+    public function build(): \Rector\Tests\TypeDeclaration\Rector\ClassMethod\NarrowObjectReturnTypeRector\Source\ConferenceTalk
+    {
+        return new ConferenceTalk();
+    }
+}
+
+?>

rules-tests/TypeDeclaration/Rector/ClassMethod/NarrowObjectReturnTypeRector/Fixture/skip_abstract_class.php.inc

@@ -0,0 +1,15 @@
+<?php
+
+namespace Rector\Tests\TypeDeclaration\Rector\ClassMethod\NarrowObjectReturnTypeRector\Fixture;
+
+use Rector\Tests\TypeDeclaration\Rector\ClassMethod\NarrowObjectReturnTypeRector\Source\ConferenceTalk;
+
+abstract class AbstractItemFactory
+{
+    public function create(): object
+    {
+        return new ConferenceTalk();
+    }
+}
+
+?>

rules-tests/TypeDeclaration/Rector/ClassMethod/NarrowObjectReturnTypeRector/Fixture/skip_final_return_type.php.inc

@@ -0,0 +1,13 @@
+<?php
+
+namespace Rector\Tests\TypeDeclaration\Rector\ClassMethod\NarrowObjectReturnTypeRector\Fixture;
+
+final class FinalProductFactory
+{
+    public function create(): \DateTime
+    {
+        return new \DateTime();
+    }
+}
+
+?>

rules-tests/TypeDeclaration/Rector/ClassMethod/NarrowObjectReturnTypeRector/Fixture/skip_multiple_return_types.php.inc

@@ -0,0 +1,17 @@
+<?php
+
+namespace Rector\Tests\TypeDeclaration\Rector\ClassMethod\NarrowObjectReturnTypeRector\Fixture;
+
+final class MixedFactory
+{
+    public function create(): object
+    {
+        if (rand(0, 1)) {
+            return new \DateTime();
+        }
+
+        return new \stdClass();
+    }
+}
+
+?>

rules-tests/TypeDeclaration/Rector/ClassMethod/NarrowObjectReturnTypeRector/Fixture/skip_non_final_class.php.inc

@@ -0,0 +1,15 @@
+<?php
+
+namespace Rector\Tests\TypeDeclaration\Rector\ClassMethod\NarrowObjectReturnTypeRector\Fixture;
+
+use Rector\Tests\TypeDeclaration\Rector\ClassMethod\NarrowObjectReturnTypeRector\Source\ConferenceTalk;
+
+class NonFinalFactory
+{
+    public function create(): object
+    {
+        return new ConferenceTalk();
+    }
+}
+
+?>

rules-tests/TypeDeclaration/Rector/ClassMethod/NarrowObjectReturnTypeRector/Fixture/skip_parent_has_specific_return_type.php.inc

@@ -0,0 +1,17 @@
+<?php
+
+namespace Rector\Tests\TypeDeclaration\Rector\ClassMethod\NarrowObjectReturnTypeRector\Fixture;
+
+use Rector\Tests\TypeDeclaration\Rector\ClassMethod\NarrowObjectReturnTypeRector\Source\AbstractTalkFactory;
+use Rector\Tests\TypeDeclaration\Rector\ClassMethod\NarrowObjectReturnTypeRector\Source\Talk;
+use Rector\Tests\TypeDeclaration\Rector\ClassMethod\NarrowObjectReturnTypeRector\Source\ConferenceTalkExtended;
+
+final class ConcreteTalkFactory extends AbstractTalkFactory
+{
+    public function build(): Talk
+    {
+        return new ConferenceTalkExtended();
+    }
+}
+
+?>

rules-tests/TypeDeclaration/Rector/ClassMethod/NarrowObjectReturnTypeRector/NarrowObjectReturnTypeRectorTest.php

@@ -0,0 +1,28 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Rector\Tests\TypeDeclaration\Rector\ClassMethod\NarrowObjectReturnTypeRector;
+
+use Iterator;
+use PHPUnit\Framework\Attributes\DataProvider;
+use Rector\Testing\PHPUnit\AbstractRectorTestCase;
+
+final class NarrowObjectReturnTypeRectorTest extends AbstractRectorTestCase
+{
+    #[DataProvider('provideData')]
+    public function test(string $filePath): void
+    {
+        $this->doTestFile($filePath);
+    }
+
+    public static function provideData(): Iterator
+    {
+        return self::yieldFilesFromDirectory(__DIR__ . '/Fixture');
+    }
+
+    public function provideConfigFilePath(): string
+    {
+        return __DIR__ . '/config/configured_rule.php';
+    }
+}