Add PHPStan rule to flag same class-type union in param and return

Flags methods like (A|B $node): A|B|null that should use a @template generic to narrow the return to the passed type. Applies the template to the 13 existing matches.

Author: TomasVotruba

phpstan.neon

@@ -4,6 +4,7 @@ includes:
 rules:
     - Rector\Utils\PHPStan\Rule\RegisterRelatedPolyfillRectorRule
     - Rector\Utils\PHPStan\Rule\NoScopeFetchBeforeCheapGuardRule
+    - Rector\Utils\PHPStan\Rule\PreferGenericTemplateOnSameUnionTypeRule
 
 parameters:
     level: 8

rules/CodingStyle/Rector/ClassMethod/FuncGetArgsToVariadicParamRector.php

@@ -109,6 +109,11 @@ public function provideMinPhpVersion(): int
         return PhpVersionFeature::VARIADIC_PARAM;
     }
 
+    /**
+     * @template TFunctionLike of ClassMethod|Function_|Closure
+     * @param TFunctionLike $node
+     * @return TFunctionLike|null
+     */
     private function applyVariadicParams(
         ClassMethod|Function_|Closure $node,
         string $variableName

rules/Php81/Rector/MethodCall/MyCLabsMethodCallToEnumConstRector.php

@@ -244,6 +244,11 @@ private function getValidEnumExpr(Node $node): null|ClassConstFetch|Expr
         };
     }
 
+    /**
+     * @template TExpr of PropertyFetch|Variable
+     * @param TExpr $expr
+     * @return TExpr|null
+     */
     private function getPropertyFetchOrVariable(PropertyFetch|Variable $expr): null|PropertyFetch|Variable
     {
         if (! $this->isObjectType($expr, new ObjectType('MyCLabs\Enum\Enum'))) {

rules/Privatization/NodeManipulator/VisibilityManipulator.php

@@ -159,6 +159,11 @@ public function removeReadonly(Class_|Property|Param $node): void
         }
     }
 
+    /**
+     * @template TNode of ClassConst|ClassMethod|Property
+     * @param TNode $node
+     * @return TNode|null
+     */
     public function publicize(ClassConst|ClassMethod|Property $node): ClassConst|ClassMethod|Property|null
     {
         // already non-public

rules/Renaming/Rector/MethodCall/RenameMethodRector.php

@@ -157,6 +157,11 @@ private function shouldKeepForParentInterface(
         );
     }
 
+    /**
+     * @template TClassLike of Class_|Trait_|Interface_
+     * @param TClassLike $classOrInterface
+     * @return TClassLike|null
+     */
     private function refactorClass(
         Class_|Trait_|Interface_ $classOrInterface,
         Scope $scope

rules/Renaming/Rector/PropertyFetch/RenamePropertyRector.php

@@ -128,6 +128,11 @@ private function isUsingTrait(ClassLike $classLike, string $traitName): bool
         return $classReflection->hasTraitUse($traitName);
     }
 
+    /**
+     * @template TPropertyFetch of PropertyFetch|StaticPropertyFetch
+     * @param TPropertyFetch $propertyFetch
+     * @return TPropertyFetch|null
+     */
     private function refactorPropertyFetch(
         PropertyFetch|StaticPropertyFetch $propertyFetch
     ): null|PropertyFetch|StaticPropertyFetch {

rules/TypeDeclaration/NodeAnalyzer/StrictReturnNewArrayResolver.php

@@ -49,6 +49,11 @@ public function __construct(
     /**
      * @return ClassMethod|Function_|null the passed node when an array return type was added, null otherwise
      */
+    /**
+     * @template TFunctionLike of ClassMethod|Function_
+     * @param TFunctionLike $node
+     * @return TFunctionLike|null
+     */
     public function resolve(ClassMethod|Function_ $node): ClassMethod|Function_|null
     {
         // 1. is variable instantiated with array
@@ -90,6 +95,11 @@ public function resolve(ClassMethod|Function_ $node): ClassMethod|Function_|null
         return $this->processAddArrayReturnType($node, $returnType);
     }
 
+    /**
+     * @template TFunctionLike of ClassMethod|Function_
+     * @param TFunctionLike $node
+     * @return TFunctionLike|null
+     */
     private function processAddArrayReturnType(
         ClassMethod|Function_ $node,
         Type $returnType

rules/TypeDeclaration/NodeManipulator/AddNeverReturnType.php

@@ -33,6 +33,11 @@ public function __construct(
     ) {
     }
 
+    /**
+     * @template TFunctionLike of ClassMethod|Function_|Closure
+     * @param TFunctionLike $node
+     * @return TFunctionLike|null
+     */
     public function add(ClassMethod|Function_|Closure $node, Scope $scope): ClassMethod|Function_|Closure|null
     {
         if ($this->shouldSkip($node, $scope)) {

rules/TypeDeclaration/NodeManipulator/AddReturnTypeFromCast.php

@@ -27,6 +27,11 @@ public function __construct(
     ) {
     }
 
+    /**
+     * @template TFunctionLike of ClassMethod|Function_
+     * @param TFunctionLike $functionLike
+     * @return TFunctionLike|null
+     */
     public function add(ClassMethod|Function_ $functionLike, Scope $scope): ClassMethod|Function_|null
     {
         if ($functionLike->returnType instanceof Node) {

rules/TypeDeclaration/NodeManipulator/AddReturnTypeFromParam.php

@@ -36,6 +36,11 @@ public function __construct(
     ) {
     }
 
+    /**
+     * @template TFunctionLike of ClassMethod|Function_
+     * @param TFunctionLike $functionLike
+     * @return TFunctionLike|null
+     */
     public function add(ClassMethod|Function_ $functionLike, Scope $scope): ClassMethod|Function_|null
     {
         if ($functionLike->stmts === null) {