[TypeDeclarationDocblocks] Deprecate AddReturnDocblockFromMethodCallDocblockRector

rules/TypeDeclarationDocblocks/Rector/ClassMethod/AddReturnDocblockFromMethodCallDocblockRector.php

@@ -5,38 +5,18 @@
 namespace Rector\TypeDeclarationDocblocks\Rector\ClassMethod;
 
 use PhpParser\Node;
-use PhpParser\Node\Expr\MethodCall;
-use PhpParser\Node\Expr\StaticCall;
 use PhpParser\Node\Stmt\ClassMethod;
-use PhpParser\Node\Stmt\Return_;
-use PHPStan\Reflection\MethodReflection;
-use PHPStan\Reflection\ParametersAcceptorSelector;
-use PHPStan\Type\MixedType;
-use PHPStan\Type\ObjectType;
-use Rector\BetterPhpDocParser\PhpDocInfo\PhpDocInfoFactory;
-use Rector\BetterPhpDocParser\PhpDocManipulator\PhpDocTypeChanger;
-use Rector\Doctrine\Enum\DoctrineClass;
+use Rector\Configuration\Deprecation\Contract\DeprecatedInterface;
+use Rector\Exception\ShouldNotHappenException;
 use Rector\Rector\AbstractRector;
-use Rector\Reflection\ReflectionResolver;
-use Rector\TypeDeclarationDocblocks\NodeFinder\ReturnNodeFinder;
-use Rector\TypeDeclarationDocblocks\TagNodeAnalyzer\UsefulArrayTagNodeAnalyzer;
 use Symplify\RuleDocGenerator\ValueObject\CodeSample\CodeSample;
 use Symplify\RuleDocGenerator\ValueObject\RuleDefinition;
 
 /**
- * @see \Rector\Tests\TypeDeclarationDocblocks\Rector\ClassMethod\AddReturnDocblockFromMethodCallDocblockRector\AddReturnDocblockFromMethodCallDocblockRectorTest
+ * @deprecated This rule is deprecated, as it copies docblock from another method call. The docblock can be incorrect or outdated, and spreads the error further.
  */
-final class AddReturnDocblockFromMethodCallDocblockRector extends AbstractRector
+final class AddReturnDocblockFromMethodCallDocblockRector extends AbstractRector implements DeprecatedInterface
 {
-    public function __construct(
-        private readonly PhpDocInfoFactory $phpDocInfoFactory,
-        private readonly ReturnNodeFinder $returnNodeFinder,
-        private readonly UsefulArrayTagNodeAnalyzer $usefulArrayTagNodeAnalyzer,
-        private readonly ReflectionResolver $reflectionResolver,
-        private readonly PhpDocTypeChanger $phpDocTypeChanger,
-    ) {
-    }
-
     public function getRuleDefinition(): RuleDefinition
     {
         return new RuleDefinition(
@@ -106,51 +86,9 @@ public function getNodeTypes(): array
      */
     public function refactor(Node $node): ?Node
     {
-        // definitely not an array return
-        if (! $node->returnType instanceof Node || ! $this->isName($node->returnType, 'array')) {
-            return null;
-        }
-
-        $phpDocInfo = $this->phpDocInfoFactory->createFromNodeOrEmpty($node);
-        if ($this->usefulArrayTagNodeAnalyzer->isUsefulArrayTag($phpDocInfo->getReturnTagValue())) {
-            return null;
-        }
-
-        $onlyReturnWithExpr = $this->returnNodeFinder->findOnlyReturnWithExpr($node);
-        if (! $onlyReturnWithExpr instanceof Return_ || (! $onlyReturnWithExpr->expr instanceof MethodCall && ! $onlyReturnWithExpr->expr instanceof StaticCall)) {
-            return null;
-        }
-
-        $returnedMethodCall = $onlyReturnWithExpr->expr;
-
-        // skip doctrine connection calls, as to generic and not helpful
-        $callerType = $this->getType(
-            $returnedMethodCall instanceof MethodCall ? $returnedMethodCall->var : $returnedMethodCall->class
-        );
-        if ($callerType instanceof ObjectType && $callerType->isInstanceOf(DoctrineClass::CONNECTION)->yes()) {
-            return null;
-        }
-
-        $calledMethodReflection = $this->reflectionResolver->resolveFunctionLikeReflectionFromCall($returnedMethodCall);
-        if (! $calledMethodReflection instanceof MethodReflection) {
-            return null;
-        }
-
-        $extendedParametersAcceptor = ParametersAcceptorSelector::combineAcceptors($calledMethodReflection->getVariants());
-
-        // native return type must be a plain array
-        if (! $extendedParametersAcceptor->getNativeReturnType()->isArray()->yes()) {
-            return null;
-        }
-
-        // docblock must carry a more specific array value type, e.g. SomeEntity[]
-        $calledReturnType = $extendedParametersAcceptor->getReturnType();
-        if ($calledReturnType->getIterableValueType() instanceof MixedType) {
-            return null;
-        }
-
-        $this->phpDocTypeChanger->changeReturnType($node, $phpDocInfo, $calledReturnType);
-
-        return $node;
+        throw new ShouldNotHappenException(sprintf(
+            '"%s" is deprecated, as it copies docblock from another method call that can be incorrect or outdated',
+            self::class
+        ));
     }
 }

src/Config/Level/TypeDeclarationDocblocksLevel.php

@@ -61,8 +61,5 @@ final class TypeDeclarationDocblocksLevel
 
         // run latter after other rules, as more generic
         AddReturnDocblockForDimFetchArrayFromAssignsRector::class,
-
-        // @todo test first, 2026-01
-        // AddReturnDocblockFromMethodCallDocblockRector::class,
     ];
 }