[deprecation] Add RenameDeprecatedMethodCallRector inferring rename from @deprecated docblock (#8015)

* [Renaming] Add RenameDeprecatedMethodCallRector inferring rename from @deprecated docblock

* extract DeprecatedMethodCallReplacementResolver

* cover with test

Author: TomasVotruba

rules-tests/Renaming/NodeAnalyzer/DeprecatedMethodCallReplacementResolverTest.php

@@ -0,0 +1,52 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Rector\Tests\Renaming\NodeAnalyzer;
+
+use Iterator;
+use PHPStan\Reflection\ReflectionProvider;
+use PHPUnit\Framework\Attributes\DataProvider;
+use Rector\Renaming\NodeAnalyzer\DeprecatedMethodCallReplacementResolver;
+use Rector\Testing\PHPUnit\AbstractLazyTestCase;
+use Rector\Tests\Renaming\NodeAnalyzer\Source\DeprecatedMethodsClient;
+
+final class DeprecatedMethodCallReplacementResolverTest extends AbstractLazyTestCase
+{
+    private DeprecatedMethodCallReplacementResolver $deprecatedMethodCallReplacementResolver;
+
+    private ReflectionProvider $reflectionProvider;
+
+    protected function setUp(): void
+    {
+        parent::setUp();
+
+        $this->deprecatedMethodCallReplacementResolver = $this->make(DeprecatedMethodCallReplacementResolver::class);
+        $this->reflectionProvider = $this->make(ReflectionProvider::class);
+    }
+
+    #[DataProvider('provideData')]
+    public function test(string $methodName, ?string $expectedReplacement): void
+    {
+        $classReflection = $this->reflectionProvider->getClass(DeprecatedMethodsClient::class);
+        $extendedMethodReflection = $classReflection->getNativeMethod($methodName);
+
+        $resolvedReplacement = $this->deprecatedMethodCallReplacementResolver->resolve($extendedMethodReflection);
+        $this->assertSame($expectedReplacement, $resolvedReplacement);
+    }
+
+    /**
+     * @return Iterator<string, array{string, (string | null)}>
+     */
+    public static function provideData(): Iterator
+    {
+        yield 'use ...() instead' => ['getData', 'fetchData'];
+        yield 'replaced by ...()' => ['loadData', 'fetchData'];
+        yield '{@see ...()}' => ['readData', 'fetchData'];
+        yield 'static use ...() instead' => ['makeOld', 'make'];
+        yield 'deprecated without method suggestion' => ['legacyData', null];
+        yield 'suggested method does not exist' => ['vanishedData', null];
+        yield 'suggested method is itself deprecated' => ['deadEndData', null];
+        yield 'not deprecated at all' => ['fetchData', null];
+    }
+}

rules-tests/Renaming/NodeAnalyzer/Source/DeprecatedMethodsClient.php

@@ -0,0 +1,74 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Rector\Tests\Renaming\NodeAnalyzer\Source;
+
+final class DeprecatedMethodsClient
+{
+    /**
+     * @deprecated since 2.0, use fetchData() instead
+     */
+    public function getData(): array
+    {
+        return $this->fetchData();
+    }
+
+    /**
+     * @deprecated replaced by fetchData()
+     */
+    public function loadData(): array
+    {
+        return $this->fetchData();
+    }
+
+    /**
+     * @deprecated {@see fetchData()}
+     */
+    public function readData(): array
+    {
+        return $this->fetchData();
+    }
+
+    /**
+     * @deprecated since 2.0, use the repository layer instead
+     */
+    public function legacyData(): array
+    {
+        return $this->fetchData();
+    }
+
+    /**
+     * @deprecated use missingMethod() instead
+     */
+    public function vanishedData(): array
+    {
+        return $this->fetchData();
+    }
+
+    /**
+     * @deprecated use loadData() instead
+     */
+    public function deadEndData(): array
+    {
+        return $this->fetchData();
+    }
+
+    public function fetchData(): array
+    {
+        return [];
+    }
+
+    /**
+     * @deprecated use make() instead
+     */
+    public static function makeOld(): self
+    {
+        return new self();
+    }
+
+    public static function make(): self
+    {
+        return new self();
+    }
+}

rules-tests/Renaming/Rector/MethodCall/RenameDeprecatedMethodCallRector/Fixture/rename_replaced_by.php.inc

@@ -0,0 +1,25 @@
+<?php
+
+namespace Rector\Tests\Renaming\Rector\MethodCall\RenameDeprecatedMethodCallRector\Fixture;
+
+use Rector\Tests\Renaming\Rector\MethodCall\RenameDeprecatedMethodCallRector\Source\SomeApiClient;
+
+function renameReplacedBy(SomeApiClient $apiClient)
+{
+    return $apiClient->loadData();
+}
+
+?>
+-----
+<?php
+
+namespace Rector\Tests\Renaming\Rector\MethodCall\RenameDeprecatedMethodCallRector\Fixture;
+
+use Rector\Tests\Renaming\Rector\MethodCall\RenameDeprecatedMethodCallRector\Source\SomeApiClient;
+
+function renameReplacedBy(SomeApiClient $apiClient)
+{
+    return $apiClient->fetchData();
+}
+
+?>

rules-tests/Renaming/Rector/MethodCall/RenameDeprecatedMethodCallRector/Fixture/rename_see_tag.php.inc

@@ -0,0 +1,25 @@
+<?php
+
+namespace Rector\Tests\Renaming\Rector\MethodCall\RenameDeprecatedMethodCallRector\Fixture;
+
+use Rector\Tests\Renaming\Rector\MethodCall\RenameDeprecatedMethodCallRector\Source\SomeApiClient;
+
+function renameSeeTag(SomeApiClient $apiClient)
+{
+    return $apiClient->readData();
+}
+
+?>
+-----
+<?php
+
+namespace Rector\Tests\Renaming\Rector\MethodCall\RenameDeprecatedMethodCallRector\Fixture;
+
+use Rector\Tests\Renaming\Rector\MethodCall\RenameDeprecatedMethodCallRector\Source\SomeApiClient;
+
+function renameSeeTag(SomeApiClient $apiClient)
+{
+    return $apiClient->fetchData();
+}
+
+?>

rules-tests/Renaming/Rector/MethodCall/RenameDeprecatedMethodCallRector/Fixture/rename_static_call.php.inc

@@ -0,0 +1,25 @@
+<?php
+
+namespace Rector\Tests\Renaming\Rector\MethodCall\RenameDeprecatedMethodCallRector\Fixture;
+
+use Rector\Tests\Renaming\Rector\MethodCall\RenameDeprecatedMethodCallRector\Source\SomeApiClient;
+
+function renameStaticCall()
+{
+    return SomeApiClient::makeOld();
+}
+
+?>
+-----
+<?php
+
+namespace Rector\Tests\Renaming\Rector\MethodCall\RenameDeprecatedMethodCallRector\Fixture;
+
+use Rector\Tests\Renaming\Rector\MethodCall\RenameDeprecatedMethodCallRector\Source\SomeApiClient;
+
+function renameStaticCall()
+{
+    return SomeApiClient::make();
+}
+
+?>

rules-tests/Renaming/Rector/MethodCall/RenameDeprecatedMethodCallRector/Fixture/rename_use_instead.php.inc

@@ -0,0 +1,25 @@
+<?php
+
+namespace Rector\Tests\Renaming\Rector\MethodCall\RenameDeprecatedMethodCallRector\Fixture;
+
+use Rector\Tests\Renaming\Rector\MethodCall\RenameDeprecatedMethodCallRector\Source\SomeApiClient;
+
+function renameUseInstead(SomeApiClient $apiClient)
+{
+    return $apiClient->getData();
+}
+
+?>
+-----
+<?php
+
+namespace Rector\Tests\Renaming\Rector\MethodCall\RenameDeprecatedMethodCallRector\Fixture;
+
+use Rector\Tests\Renaming\Rector\MethodCall\RenameDeprecatedMethodCallRector\Source\SomeApiClient;
+
+function renameUseInstead(SomeApiClient $apiClient)
+{
+    return $apiClient->fetchData();
+}
+
+?>

rules-tests/Renaming/Rector/MethodCall/RenameDeprecatedMethodCallRector/Fixture/skip_magic_method_suggestion.php.inc

@@ -0,0 +1,11 @@
+<?php
+
+namespace Rector\Tests\Renaming\Rector\MethodCall\RenameDeprecatedMethodCallRector\Fixture;
+
+use Rector\Tests\Renaming\Rector\MethodCall\RenameDeprecatedMethodCallRector\Source\MagicMethodApiClient;
+
+function skipMagicMethodSuggestion(MagicMethodApiClient $apiClient)
+{
+    // suggested fetchData() exists only as a @method magic method, not a real native one
+    return $apiClient->getData();
+}

rules-tests/Renaming/Rector/MethodCall/RenameDeprecatedMethodCallRector/Fixture/skip_no_suggestion.php.inc

@@ -0,0 +1,11 @@
+<?php
+
+namespace Rector\Tests\Renaming\Rector\MethodCall\RenameDeprecatedMethodCallRector\Fixture;
+
+use Rector\Tests\Renaming\Rector\MethodCall\RenameDeprecatedMethodCallRector\Source\SomeApiClient;
+
+function skipNoSuggestion(SomeApiClient $apiClient)
+{
+    // @deprecated description has no "use newMethod()" hint
+    return $apiClient->legacyData();
+}

rules-tests/Renaming/Rector/MethodCall/RenameDeprecatedMethodCallRector/Fixture/skip_not_deprecated.php.inc

@@ -0,0 +1,10 @@
+<?php
+
+namespace Rector\Tests\Renaming\Rector\MethodCall\RenameDeprecatedMethodCallRector\Fixture;
+
+use Rector\Tests\Renaming\Rector\MethodCall\RenameDeprecatedMethodCallRector\Source\SomeApiClient;
+
+function skipNotDeprecated(SomeApiClient $apiClient)
+{
+    return $apiClient->fetchData();
+}

rules-tests/Renaming/Rector/MethodCall/RenameDeprecatedMethodCallRector/RenameDeprecatedMethodCallRectorTest.php

@@ -0,0 +1,28 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Rector\Tests\Renaming\Rector\MethodCall\RenameDeprecatedMethodCallRector;
+
+use Iterator;
+use PHPUnit\Framework\Attributes\DataProvider;
+use Rector\Testing\PHPUnit\AbstractRectorTestCase;
+
+final class RenameDeprecatedMethodCallRectorTest 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';
+    }
+}