[deprecation] Deprecate AddParamArrayDocblockBasedOnArrayMapRector, as a single array_map() call is a vague type source

The rule reads the closure param type of one array_map() call inside the body
and turns it into a @PARAM docblock for the whole parameter. One call site
does not prove what every caller passes, so the added type is often too
narrow. Add the docblock manually instead.

Author: TomasVotruba

phpstan.neon

@@ -466,6 +466,7 @@ parameters:
         - '#Class "Rector\\CodeQuality\\Rector\\Concat\\JoinStringConcatRector" is missing @see annotation with test case class reference#'
         - '#Class "Rector\\CodeQuality\\Rector\\Switch_\\SwitchTrueToIfRector" is missing @see annotation with test case class reference#'
         - '#Class "Rector\\TypeDeclarationDocblocks\\Rector\\ClassMethod\\AddReturnDocblockForDimFetchArrayFromAssignsRector" is missing @see annotation with test case class reference#'
+        - '#Class "Rector\\TypeDeclarationDocblocks\\Rector\\ClassMethod\\AddParamArrayDocblockBasedOnArrayMapRector" is missing @see annotation with test case class reference#'
 
         # @todo fix in phpstan-rules
         -

rules-tests/TypeDeclarationDocblocks/Rector/ClassMethod/AddParamArrayDocblockBasedOnArrayMapRector/AddParamArrayDocblockBasedOnArrayMapRectorTest.php

@@ -5,36 +5,19 @@
 namespace Rector\TypeDeclarationDocblocks\Rector\ClassMethod;
 
 use PhpParser\Node;
-use PhpParser\Node\Identifier;
-use PhpParser\Node\Param;
 use PhpParser\Node\Stmt\ClassMethod;
 use PhpParser\Node\Stmt\Function_;
-use PHPStan\Type\ArrayType;
-use PHPStan\Type\MixedType;
-use Rector\BetterPhpDocParser\PhpDocInfo\PhpDocInfoFactory;
+use Rector\Configuration\Deprecation\Contract\DeprecatedInterface;
+use Rector\Exception\ShouldNotHappenException;
 use Rector\Rector\AbstractRector;
-use Rector\StaticTypeMapper\StaticTypeMapper;
-use Rector\TypeDeclarationDocblocks\NodeDocblockTypeDecorator;
-use Rector\TypeDeclarationDocblocks\NodeFinder\ArrayMapClosureExprFinder;
-use Rector\TypeDeclarationDocblocks\TagNodeAnalyzer\UsefulArrayTagNodeAnalyzer;
 use Symplify\RuleDocGenerator\ValueObject\CodeSample\CodeSample;
 use Symplify\RuleDocGenerator\ValueObject\RuleDefinition;
 
 /**
- * @see \Rector\Tests\TypeDeclarationDocblocks\Rector\ClassMethod\AddParamArrayDocblockBasedOnArrayMapRector\AddParamArrayDocblockBasedOnArrayMapRectorTest
+ * @deprecated This rule is deprecated, as a single array_map() closure only proves what one call site reads. The param type is vague and unreliable. Add the @param docblock manually instead.
  */
-final class AddParamArrayDocblockBasedOnArrayMapRector extends AbstractRector
+final class AddParamArrayDocblockBasedOnArrayMapRector extends AbstractRector implements DeprecatedInterface
 {
-    public function __construct(
-        private readonly ArrayMapClosureExprFinder $arrayMapClosureExprFinder,
-        private readonly StaticTypeMapper $staticTypeMapper,
-        private readonly PhpDocInfoFactory $phpDocInfoFactory,
-        private readonly UsefulArrayTagNodeAnalyzer $usefulArrayTagNodeAnalyzer,
-        private readonly NodeDocblockTypeDecorator $nodeDocblockTypeDecorator
-    ) {
-
-    }
-
     public function getRuleDefinition(): RuleDefinition
     {
         return new RuleDefinition('Add @param array docblock if array_map is used on the parameter', [
@@ -78,73 +61,9 @@ public function getNodeTypes(): array
      */
     public function refactor(Node $node): ?Node
     {
-        if ($node->getParams() === []) {
-            return null;
-        }
-
-        $hasChanged = false;
-        $functionPhpDocInfo = $this->phpDocInfoFactory->createFromNodeOrEmpty($node);
-
-        foreach ($node->params as $param) {
-            // handle only arrays
-            if (! $this->isArrayParam($param)) {
-                continue;
-            }
-
-            $paramName = $this->getName($param);
-
-            $arrayMapClosures = $this->arrayMapClosureExprFinder->findByVariableName($node, $paramName);
-            if ($arrayMapClosures === []) {
-                continue;
-            }
-
-            foreach ($arrayMapClosures as $arrayMapClosure) {
-                $params = $arrayMapClosure->getParams();
-                if ($params === []) {
-                    continue;
-                }
-
-                $firstParam = $params[0];
-                $paramTypeNode = $firstParam->type;
-                if ($paramTypeNode === null) {
-                    continue;
-                }
-
-                if ($this->usefulArrayTagNodeAnalyzer->isUsefulArrayTag(
-                    $functionPhpDocInfo->getParamTagValueByName($paramName)
-                )) {
-                    continue;
-                }
-
-                $paramType = $this->staticTypeMapper->mapPhpParserNodePHPStanType($paramTypeNode);
-                $arrayParamType = new ArrayType(new MixedType(), $paramType);
-
-                if ($this->nodeDocblockTypeDecorator->decorateGenericIterableParamType(
-                    $arrayParamType,
-                    $functionPhpDocInfo,
-                    $node,
-                    $param,
-                    $paramName
-                )) {
-                    $hasChanged = true;
-                }
-            }
-
-        }
-
-        if (! $hasChanged) {
-            return null;
-        }
-
-        return $node;
-    }
-
-    private function isArrayParam(Param $param): bool
-    {
-        if (! $param->type instanceof Identifier) {
-            return false;
-        }
-
-        return $this->isName($param->type, 'array');
+        throw new ShouldNotHappenException(sprintf(
+            '"%s" rule is deprecated, as the param type guessed from a single array_map() closure is vague and unreliable. Add the @param docblock manually instead',
+            self::class
+        ));
     }
 }