[dx] Add OrderedRectorInterface to order dependent rules in a single pass

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/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;
+    }
+}