Add OrderedRectorInterface to order dependent rules in a single pass

A rule implementing OrderedRectorInterface declares precededRule(), the rule
that must run before it. RectorRegistry topologically sorts active rules so each
dependent rule runs after its predecessor within one file pass, instead of
relying on repeated FileProcessor passes to converge.

Author: TomasVotruba

src/Application/RectorRegistry.php

@@ -6,7 +6,9 @@
 
 use PhpParser\Node;
 use Rector\Configuration\ConfigurationRuleFilter;
+use Rector\Contract\Rector\OrderedRectorInterface;
 use Rector\Contract\Rector\RectorInterface;
+use Rector\Exception\ShouldNotHappenException;
 use Rector\Skipper\Skipper\Skipper;
 use Rector\ValueObject\Application\File;
 use Rector\VersionBonding\ComposerPackageConstraintFilter;
@@ -112,9 +114,77 @@ private function prepareRectors(): void
 
         $activeRectors = $this->phpVersionedFilter->filter($this->rectors);
         $activeRectors = $this->composerPackageConstraintFilter->filter($activeRectors);
+        $activeRectors = $this->configurationRuleFilter->filter($activeRectors);
 
-        $this->activeRectors = $this->configurationRuleFilter->filter($activeRectors);
+        $this->activeRectors = $this->sortByPrecededRule($activeRectors);
 
         $this->areRectorsPrepared = true;
     }
+
+    /**
+     * Rules implementing OrderedRectorInterface are moved after the rule they depend on,
+     * so a chain of dependent rules converges in a single file pass.
+     *
+     * @param RectorInterface[] $rectors
+     * @return RectorInterface[]
+     */
+    private function sortByPrecededRule(array $rectors): array
+    {
+        $rectorByClass = [];
+        foreach ($rectors as $rector) {
+            $rectorByClass[$rector::class] = $rector;
+        }
+
+        $precededClassByClass = [];
+        foreach ($rectors as $rector) {
+            if (! $rector instanceof OrderedRectorInterface) {
+                continue;
+            }
+
+            $precededClass = $rector->precededRule();
+
+            // ignore a predecessor filtered out of the active set
+            if (isset($rectorByClass[$precededClass])) {
+                $precededClassByClass[$rector::class] = $precededClass;
+            }
+        }
+
+        if ($precededClassByClass === []) {
+            return $rectors;
+        }
+
+        $sortedRectors = [];
+        $emittedClasses = [];
+        $remainingRectors = $rectors;
+
+        while ($remainingRectors !== []) {
+            $hasProgress = false;
+
+            foreach ($remainingRectors as $key => $rector) {
+                $precededClass = $precededClassByClass[$rector::class] ?? null;
+                if ($precededClass !== null && ! isset($emittedClasses[$precededClass])) {
+                    continue;
+                }
+
+                $sortedRectors[] = $rector;
+                $emittedClasses[$rector::class] = true;
+                unset($remainingRectors[$key]);
+                $hasProgress = true;
+            }
+
+            if (! $hasProgress) {
+                $remainingClasses = [];
+                foreach ($remainingRectors as $rector) {
+                    $remainingClasses[] = $rector::class;
+                }
+
+                throw new ShouldNotHappenException(sprintf(
+                    'Circular rule ordering detected among: %s',
+                    implode(', ', $remainingClasses)
+                ));
+            }
+        }
+
+        return $sortedRectors;
+    }
 }

src/Contract/Rector/OrderedRectorInterface.php

@@ -0,0 +1,15 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Rector\Contract\Rector;
+
+interface OrderedRectorInterface
+{
+    /**
+     * Rule that must run before this one, so dependent changes converge in a single file pass.
+     *
+     * @return class-string<RectorInterface>
+     */
+    public function precededRule(): string;
+}

tests/Application/RectorRegistryTest.php

@@ -7,6 +7,7 @@
 use PhpParser\Node\Stmt\Class_;
 use Rector\Application\RectorRegistry;
 use Rector\Testing\PHPUnit\AbstractLazyTestCase;
+use Rector\Tests\PhpParser\NodeTraverser\Class_\OrderedClassRector;
 use Rector\Tests\PhpParser\NodeTraverser\Class_\RuleUsingClassRector;
 use Rector\Tests\PhpParser\NodeTraverser\ClassLike\RuleUsingClassLikeRector;
 use Rector\Tests\PhpParser\NodeTraverser\Function_\RuleUsingFunctionRector;
@@ -72,4 +73,19 @@ public function testForNodeWhenAllRectorsMatch(): void
 
         $this->assertEquals([$this->ruleUsingClassRector, $this->ruleUsingClassLikeRector], $rectors);
     }
+
+    public function testForNodeSortsByPrecededRule(): void
+    {
+        $orderedClassRector = new OrderedClassRector();
+
+        // registered before the rule it depends on
+        $this->rectorRegistry->refreshRectors([
+            $orderedClassRector,
+            $this->ruleUsingClassRector,
+        ]);
+
+        $rectors = $this->rectorRegistry->forNode(new Class_('test'));
+
+        $this->assertEquals([$this->ruleUsingClassRector, $orderedClassRector], $rectors);
+    }
 }

tests/Issues/RepeatedThreeTimes/Source/NarrowParamUnionDocblockRector.php

@@ -11,15 +11,21 @@
 use PHPStan\Type\ObjectType;
 use Rector\BetterPhpDocParser\PhpDocInfo\PhpDocInfoFactory;
 use Rector\Comments\NodeDocBlock\DocBlockUpdater;
+use Rector\Contract\Rector\OrderedRectorInterface;
 use Rector\Rector\AbstractRector;
 use Rector\RuleDoc\RuleDefinition;
 use Rector\StaticTypeMapper\StaticTypeMapper;
 
 /**
  * @param array|SomeCollection $items → @param SomeCollection $items
  */
-final class NarrowParamUnionDocblockRector extends AbstractRector
+final class NarrowParamUnionDocblockRector extends AbstractRector implements OrderedRectorInterface
 {
+    public function precededRule(): string
+    {
+        return NarrowArrayCollectionDocblockRector::class;
+    }
+
     public function __construct(
         private readonly PhpDocInfoFactory $phpDocInfoFactory,
         private readonly DocBlockUpdater $docBlockUpdater,

tests/Issues/RepeatedThreeTimes/Source/ParamTypeFromDocblockRector.php

@@ -9,14 +9,20 @@
 use PhpParser\Node\Stmt\ClassMethod;
 use PHPStan\Type\ObjectType;
 use Rector\BetterPhpDocParser\PhpDocInfo\PhpDocInfoFactory;
+use Rector\Contract\Rector\OrderedRectorInterface;
 use Rector\Rector\AbstractRector;
 use Rector\RuleDoc\RuleDefinition;
 
 /**
  * @param SomeCollection $items → native SomeCollection $items param type
  */
-final class ParamTypeFromDocblockRector extends AbstractRector
+final class ParamTypeFromDocblockRector extends AbstractRector implements OrderedRectorInterface
 {
+    public function precededRule(): string
+    {
+        return NarrowParamUnionDocblockRector::class;
+    }
+
     public function __construct(
         private readonly PhpDocInfoFactory $phpDocInfoFactory
     ) {

tests/PhpParser/NodeTraverser/Class_/OrderedClassRector.php

@@ -0,0 +1,44 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Rector\Tests\PhpParser\NodeTraverser\Class_;
+
+use PhpParser\Node;
+use PhpParser\Node\Stmt\Class_;
+use Rector\Contract\Rector\OrderedRectorInterface;
+use Rector\Rector\AbstractRector;
+use Rector\RuleDoc\CodeSample\CodeSample;
+use Rector\RuleDoc\RuleDefinition;
+
+/**
+ * @see \Rector\Tests\Application\RectorRegistryTest
+ */
+final class OrderedClassRector extends AbstractRector implements OrderedRectorInterface
+{
+    public function precededRule(): string
+    {
+        return RuleUsingClassRector::class;
+    }
+
+    public function getRuleDefinition(): RuleDefinition
+    {
+        return new RuleDefinition('This rule runs after RuleUsingClassRector', [new CodeSample('', '')]);
+    }
+
+    /**
+     * @return array<class-string<Node>>
+     */
+    public function getNodeTypes(): array
+    {
+        return [Class_::class];
+    }
+
+    /**
+     * @param Class_ $node
+     */
+    public function refactor(Node $node): Node
+    {
+        return $node;
+    }
+}