[DeadCode] Skip RemoveReturnTagIncompatibleWithNativeTypeRector on a type alias nested in a union

A @phpstan-type alias name is not resolved to the type it stands for, it
becomes a NonExistingObjectType. So "@return ConfigArray|CustomConfig" over a
native "array" looked like a contradiction and the tag was removed.

The alias guard only matched when the whole @return type was a single
IdentifierTypeNode. Look the name up in every identifier of the type node
instead, which covers unions, nullables and intersections as well.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: Philosoft

rules-tests/DeadCode/Rector/ClassMethod/RemoveReturnTagIncompatibleWithNativeTypeRector/Fixture/remove_object_return_next_to_type_alias.php.inc

@@ -0,0 +1,36 @@
+<?php
+
+namespace Rector\Tests\DeadCode\Rector\ClassMethod\RemoveReturnTagIncompatibleWithNativeTypeRector\Fixture;
+
+/**
+ * @phpstan-type ConfigArray array{is_dry: bool}
+ */
+final class RemoveObjectReturnNextToTypeAlias
+{
+    /**
+     * @return \stdClass
+     */
+    public function getName(): string
+    {
+        return 'name';
+    }
+}
+
+?>
+-----
+<?php
+
+namespace Rector\Tests\DeadCode\Rector\ClassMethod\RemoveReturnTagIncompatibleWithNativeTypeRector\Fixture;
+
+/**
+ * @phpstan-type ConfigArray array{is_dry: bool}
+ */
+final class RemoveObjectReturnNextToTypeAlias
+{
+    public function getName(): string
+    {
+        return 'name';
+    }
+}
+
+?>

rules-tests/DeadCode/Rector/ClassMethod/RemoveReturnTagIncompatibleWithNativeTypeRector/Fixture/skip_union_of_phpstan_type_aliases.php.inc

@@ -0,0 +1,13 @@
+<?php
+
+namespace Rector\Tests\DeadCode\Rector\ClassMethod\RemoveReturnTagIncompatibleWithNativeTypeRector\Fixture;
+
+/**
+ * @phpstan-type ConfigArray array{is_dry: bool}
+ * @phpstan-type CustomConfig array{}
+ */
+interface SkipUnionOfPHPStanTypeAliases
+{
+    /** @return ConfigArray|CustomConfig */
+    public function getConfig(): array;
+}

rules/DeadCode/Rector/ClassMethod/RemoveReturnTagIncompatibleWithNativeTypeRector.php

@@ -9,15 +9,20 @@
 use PhpParser\Node\Stmt\Function_;
 use PHPStan\Analyser\Scope;
 use PHPStan\PhpDoc\ResolvedPhpDocBlock;
+use PHPStan\PhpDoc\Tag\TypeAliasImportTag;
+use PHPStan\PhpDoc\Tag\TypeAliasTag;
+use PHPStan\PhpDocParser\Ast\Node as AstNode;
 use PHPStan\PhpDocParser\Ast\PhpDoc\ReturnTagValueNode;
 use PHPStan\PhpDocParser\Ast\Type\GenericTypeNode;
 use PHPStan\PhpDocParser\Ast\Type\IdentifierTypeNode;
 use PHPStan\PhpDocParser\Ast\Type\ThisTypeNode;
+use PHPStan\PhpDocParser\Ast\Type\TypeNode;
 use PHPStan\Reflection\ClassReflection;
 use PHPStan\Type\ObjectType;
 use Rector\BetterPhpDocParser\PhpDocInfo\PhpDocInfo;
 use Rector\BetterPhpDocParser\PhpDocInfo\PhpDocInfoFactory;
 use Rector\Comments\NodeDocBlock\DocBlockUpdater;
+use Rector\PhpDocParser\PhpDocParser\PhpDocNodeTraverser;
 use Rector\PHPStan\ScopeFetcher;
 use Rector\Rector\AbstractRector;
 use Rector\StaticTypeMapper\StaticTypeMapper;
@@ -163,8 +168,36 @@ private function isClassTypeAlias(Scope $scope, ReturnTagValueNode $returnTagVal
             return false;
         }
 
-        return $returnTagValueNode->type instanceof IdentifierTypeNode
-            && isset($typeAliases[$returnTagValueNode->type->name]);
+        return $this->containsTypeAliasName($returnTagValueNode->type, $typeAliases);
+    }
+
+    /**
+     * The alias can be nested in a composed type as well, e.g. "ConfigArray|CustomConfig" or "?ConfigArray"
+     *
+     * @param array<string, TypeAliasTag|TypeAliasImportTag> $typeAliases
+     */
+    private function containsTypeAliasName(TypeNode $typeNode, array $typeAliases): bool
+    {
+        if ($typeNode instanceof IdentifierTypeNode) {
+            return isset($typeAliases[$typeNode->name]);
+        }
+
+        $hasTypeAliasName = false;
+
+        // the traverser visits sub-nodes only, that is why the type node itself is checked above
+        $phpDocNodeTraverser = new PhpDocNodeTraverser();
+        $phpDocNodeTraverser->traverseWithCallable($typeNode, '', static function (AstNode $astNode) use (
+            $typeAliases,
+            &$hasTypeAliasName
+        ): ?int {
+            if ($astNode instanceof IdentifierTypeNode && isset($typeAliases[$astNode->name])) {
+                $hasTypeAliasName = true;
+            }
+
+            return null;
+        });
+
+        return $hasTypeAliasName;
     }
 
     private function isReturnTemplate(PhpDocInfo $phpDocInfo, ReturnTagValueNode $returnTagValueNode): bool