[TypeDeclarationDocblocks] Skip overridden methods in DocblockReturnArrayFromDirectArrayInstanceRector (#7995)

Skip @return docblock generation when the ClassMethod overrides a
parent/interface method, to avoid conflicting with the existing
parent docblock contract.

Fixes rectorphp/rector#9599

Author: TomasVotruba

rules-tests/TypeDeclarationDocblocks/Rector/ClassMethod/DocblockReturnArrayFromDirectArrayInstanceRector/Fixture/skip_overridden_method.php.inc

@@ -0,0 +1,38 @@
+<?php
+
+namespace Rector\Tests\TypeDeclarationDocblocks\Rector\ClassMethod\DocblockReturnArrayFromDirectArrayInstanceRector\Fixture;
+
+interface SomeOverriddenInterface
+{
+    /**
+     * @return int[]
+     */
+    public function getCodes(): iterable;
+}
+
+abstract class SomeOverriddenBase
+{
+    /**
+     * @return string[]
+     */
+    abstract public function getMethods(): iterable;
+}
+
+final class SomeOverriddenChild extends SomeOverriddenBase implements SomeOverriddenInterface
+{
+    public function getCodes(): iterable
+    {
+        return [
+            200,
+            201,
+        ];
+    }
+
+    public function getMethods(): iterable
+    {
+        return [
+            'GET',
+            'POST',
+        ];
+    }
+}

rules/TypeDeclarationDocblocks/Rector/ClassMethod/DocblockReturnArrayFromDirectArrayInstanceRector.php

@@ -19,6 +19,7 @@
 use Rector\TypeDeclarationDocblocks\NodeFinder\ReturnNodeFinder;
 use Rector\TypeDeclarationDocblocks\TagNodeAnalyzer\UsefulArrayTagNodeAnalyzer;
 use Rector\TypeDeclarationDocblocks\TypeResolver\ConstantArrayTypeGeneralizer;
+use Rector\VendorLocker\ParentClassMethodTypeOverrideGuard;
 use Symplify\RuleDocGenerator\ValueObject\CodeSample\CodeSample;
 use Symplify\RuleDocGenerator\ValueObject\RuleDefinition;
 
@@ -32,7 +33,8 @@ public function __construct(
         private readonly PhpDocTypeChanger $phpDocTypeChanger,
         private readonly ConstantArrayTypeGeneralizer $constantArrayTypeGeneralizer,
         private readonly ReturnNodeFinder $returnNodeFinder,
-        private readonly UsefulArrayTagNodeAnalyzer $usefulArrayTagNodeAnalyzer
+        private readonly UsefulArrayTagNodeAnalyzer $usefulArrayTagNodeAnalyzer,
+        private readonly ParentClassMethodTypeOverrideGuard $parentClassMethodTypeOverrideGuard
     ) {
     }
 
@@ -88,6 +90,11 @@ public function refactor(Node $node): ?Node
             return null;
         }
 
+        // skip overridden methods to not conflict with parent/interface @return docblock
+        if ($node instanceof ClassMethod && $this->parentClassMethodTypeOverrideGuard->hasParentClassMethod($node)) {
+            return null;
+        }
+
         $phpDocInfo = $this->phpDocInfoFactory->createFromNodeOrEmpty($node);
 
         if ($this->usefulArrayTagNodeAnalyzer->isUsefulArrayTag($phpDocInfo->getReturnTagValue())) {