Introduce FileNode to handle file-level changes (#7728)

* introduce FileNode to handle file-level changes; deprecate IncreaseDeclareStrictTypesRector

* update use resolving

* make use of FileNode in imports

* add fixture to keep protected method

* require rector repo updated PRs

* add FileNode upgrade to UPGRADING

* [ci] add job to check laravel rector with latest dev-main build

* add node matching support for FileWithoutNamespace

* warn about deprecated type

* print stmts with false

* [docs] add specific example how to iterate stmts of namespaced and non-namespaced file

Author: TomasVotruba

.github/workflows/code_analysis.yaml

@@ -50,7 +50,7 @@ jobs:
 
                     -
                         name: 'Finalize classes'
-                        run: vendor/bin/swiss-knife finalize-classes src tests rules --dry-run
+                        run: vendor/bin/swiss-knife finalize-classes src tests rules --dry-run --skip-file="src/PhpParser/Node/FileNode.php"
 
                     -
                         name: 'Check before/after test fixture on no-changes'

.github/workflows/rector_laravel_rector_dev.yaml

@@ -28,3 +28,4 @@ jobs:
             -   run: git clone https://github.com/driftingly/rector-laravel.git
             -   run: composer require rector/rector:dev-main --working-dir rector-laravel
             -   run: cd rector-laravel && vendor/bin/phpunit
+

UPGRADING.md

@@ -1,3 +1,110 @@
+# Upgrading from Rector 2.2.14 to 2.3
+
+* `FileWithoutNamespace` is deprecated, and replaced by `FileNode` that represents both namespaced and non-namespaced files and allow changes inside
+* `beforeTraverse()` is now marked as `@final`, use `getNodeTypes()` with `FileNode::class` instead
+
+**Before**
+
+```php
+use Rector\PhpParser\Node\FileWithoutNamespace;
+use Rector\Rector\AbstractRector;
+
+final class SomeRector extends AbstractRector
+{
+    public function getNodeTypes(): array
+    {
+        return [FileWithoutNamespace::class];
+    }
+
+    public function beforeTraverse(array $nodes): array
+    {
+        // some node hacking
+    }
+
+    /**
+     * @param FileWithoutNamespace $node
+     */
+    public function refactor(Node $node): ?Node
+    {
+        // ...
+    }
+
+}
+```
+
+**After**
+
+```php
+use Rector\PhpParser\Node\FileNode;
+use Rector\Rector\AbstractRector;
+
+final class SomeRector extends AbstractRector
+{
+    public function getNodeTypes(): array
+    {
+        return [FileNode::class];
+    }
+
+    /**
+     * @param FileNode $node
+     */
+    public function refactor(Node $node): ?Node
+    {
+        foreach ($node->stmts as $stmt) {
+            // check if has declare_strict already?
+            // ...
+
+            // create it
+            $declareStrictTypes = $this->createDeclareStrictTypesNode();
+
+            // add it
+            $node->stmts = array_merge([$declareStrictTypes], $node->stmts);
+        }
+
+        return $node;
+    }
+
+}
+```
+
+<br>
+
+The `FileNode` handles both namespaced and non-namespaced files. To handle the first stmts inside the file, you hook into 2 nodes:
+
+```php
+use Rector\PhpParser\Node\FileNode;
+use Rector\Rector\AbstractRector;
+use PhpParser\Node\Stmt\Namespace_;
+
+final class SomeRector extends AbstractRector
+{
+    public function getNodeTypes(): array
+    {
+        return [FileNode::class, Namespace_::class];
+    }
+
+    /**
+     * @param FileNode|Namespace_ $node
+     */
+    public function refactor(Node $node): ?Node
+    {
+        if ($node instanceof FileNode && $node->isNamespaced()) {
+            // handled in the Namespace_ node
+            return null;
+        }
+
+        foreach ($node->stmts as $stmt) {
+            // modify stmts in desired way here
+        }
+
+        return $node;
+    }
+
+}
+```
+
+<br>
+
 # Upgrading from Rector 1.x to 2.0
 
 ## PHP version requirements

composer-dependency-analyser.php

@@ -17,8 +17,6 @@
     // ensure use version ^3.2.0
     ->ignoreErrorsOnPackage('composer/pcre', [ErrorType::UNUSED_DEPENDENCY])
 
-    ->ignoreErrorsOnPath(__DIR__ . '/src/Reporting/DeprecatedRulesReporter.php', [ErrorType::UNKNOWN_CLASS])
-
     ->ignoreErrorsOnPaths([
         __DIR__ . '/stubs',
         __DIR__ . '/tests',

phpstan.neon

@@ -10,7 +10,7 @@ parameters:
 
     # see https://phpstan.org/writing-php-code/phpdoc-types#global-type-aliases
     typeAliases:
-        StmtsAware: \PhpParser\Node\Stmt\Block | \PhpParser\Node\Expr\Closure | \PhpParser\Node\Stmt\Case_ | \PhpParser\Node\Stmt\Catch_ | \PhpParser\Node\Stmt\ClassMethod | \PhpParser\Node\Stmt\Do_ | \PhpParser\Node\Stmt\Else_ | \PhpParser\Node\Stmt\ElseIf_ | \PhpParser\Node\Stmt\Finally_ | \PhpParser\Node\Stmt\For_ | \PhpParser\Node\Stmt\Foreach_ | \PhpParser\Node\Stmt\Function_ | \PhpParser\Node\Stmt\If_ | \PhpParser\Node\Stmt\Namespace_ | \PhpParser\Node\Stmt\TryCatch | \PhpParser\Node\Stmt\While_ | \Rector\PhpParser\Node\CustomNode\FileWithoutNamespace
+        StmtsAware: \PhpParser\Node\Stmt\Block | \PhpParser\Node\Expr\Closure | \PhpParser\Node\Stmt\Case_ | \PhpParser\Node\Stmt\Catch_ | \PhpParser\Node\Stmt\ClassMethod | \PhpParser\Node\Stmt\Do_ | \PhpParser\Node\Stmt\Else_ | \PhpParser\Node\Stmt\ElseIf_ | \PhpParser\Node\Stmt\Finally_ | \PhpParser\Node\Stmt\For_ | \PhpParser\Node\Stmt\Foreach_ | \PhpParser\Node\Stmt\Function_ | \PhpParser\Node\Stmt\If_ | \PhpParser\Node\Stmt\Namespace_ | \PhpParser\Node\Stmt\TryCatch | \PhpParser\Node\Stmt\While_ | \Rector\PhpParser\Node\FileNode
 
     # requires exact closure types
     checkMissingCallableSignature: true
@@ -189,8 +189,10 @@ parameters:
             message: '#Method Rector\\Util\\ArrayParametersMerger\:\:mergeLeftToRightWithCallable\(\) has parameter \$mergeCallback with no signature specified for callable#'
             path: src/Util/ArrayParametersMerger.php
 
-        # fixture class
-        - '#Class "Rector\\Tests\\Issues\\ScopeNotAvailable\\Variable\\ArrayItemForeachValueRector" is missing @see annotation with test case class reference#'
+        # fixture Rector rules
+        -
+            identifier:  symplify.seeAnnotationToTest
+            path: tests/Issues/
 
         # classes are part of *.php.inc fixture
         -
@@ -286,7 +288,6 @@ parameters:
                 - src/Configuration/RectorConfigBuilder.php
                 - src/Reporting/DeprecatedRulesReporter.php
             identifier: classConstant.deprecatedInterface
-        - '#Class Rector\\PhpParser\\Node\\CustomNode\\FileWithoutNamespace implements deprecated interface Rector\\Contract\\PhpParser\\Node\\StmtsAwareInterface#'
 
         # allowed internally only
         -
@@ -398,12 +399,6 @@ parameters:
             paths:
                 - rules/Php70/Rector/If_/IfToSpaceshipRector.php
 
-        # handles full file
-        -
-            paths:
-                - rules/TypeDeclaration/Rector/StmtsAwareInterface/IncreaseDeclareStrictTypesRector.php
-            identifier: rector.noOnlyNullReturnInRefactor
-
         -
             identifier: rector.noIntegerRefactorReturn
             paths:
@@ -416,22 +411,22 @@ parameters:
         # condition check, just to be sure
         - '#Method Rector\\Rector\\AbstractRector\:\:enterNode\(\) never returns 3 so it can be removed from the return type#'
 
-        # special case, working on a file-level
-        -
-            identifier: rector.noOnlyNullReturnInRefactor
-            path: rules/TypeDeclaration/Rector/StmtsAwareInterface/DeclareStrictTypesRector.php
-
-        # handle next with FileNode
-        -
-            identifier: method.parentMethodFinalByPhpDoc
-            path: rules/TypeDeclaration/Rector/StmtsAwareInterface/DeclareStrictTypesRector.php
-
         # deprecated
         -
             identifier: public.method.unused
             paths:
                 - rules/Transform/ValueObject/ClassMethodReference.php
                 - rules/CodeQuality/ValueObject/KeyAndExpr.php
+        -
+            identifier: symplify.forbiddenExtendOfNonAbstractClass
+            path: src/PhpParser/Node/FileNode.php
+        -
+            identifier: method.deprecatedClass
+            path: src/PhpParser/Node/FileNode.php
+
+        -
+            identifier: class.extendsDeprecatedClass
+            path: src/PhpParser/Node/FileNode.php
 
         -
             identifier: public.classConstant.unused
@@ -450,8 +445,22 @@ parameters:
         - '#Register "Rector\\Php81\\Rector\\Array_\\FirstClassCallableRector" service to "php81\.php" config set#'
         - '#Class "Rector\\CodingStyle\\Rector\\String_\\SymplifyQuoteEscapeRector" is missing @see annotation with test case class reference#'
         - '#Access to constant on deprecated class Rector\\Php81\\Rector\\Array_\\FirstClassCallableRector#'
+
+        # BC layer for FileWithoutNamespace node
+        - message: '#Use @see \\Rector\\PhpParser\\Node\\FileNode instead#'
+        - '#BC layer for FileNode and FileWithoutNamespace compat, use FileNode instead#'
+        -
+            path: src/PhpParser/Node/CustomNode/FileWithoutNamespace.php
+            identifier: symplify.forbiddenExtendOfNonAbstractClass
         -
             message: '#Only abstract classes can be extended#'
             path: rules/Php81/Rector/Array_/FirstClassCallableRector.php
 
+        - '#Method Rector\\Tests\\Issues\\FileWithoutNamespaceCompat\\Rector\\SubscribedToFileWithoutNamespaceRector\:\:refactor\(\) should return Rector\\PhpParser\\Node\\FileNode but returns Rector\\PhpParser\\Node\\CustomNode\\FileWithoutNamespace#'
 
+        # BC layer for FileWithoutNamespace node
+        - message: '#Use @see \\Rector\\PhpParser\\Node\\FileNode instead#'
+        - '#Class Rector\\PhpParser\\Node\\CustomNode\\FileWithoutNamespace extends final class Rector\\PhpParser\\Node\\FileNode#'
+        -
+            path: src/PhpParser/Node/CustomNode/FileWithoutNamespace.php
+            identifier: symplify.forbiddenExtendOfNonAbstractClass

rules-tests/Privatization/Rector/ClassMethod/PrivatizeFinalClassMethodRector/Fixture/keep_magic_parent_called_method.php.inc

@@ -3,11 +3,12 @@
 namespace Rector\Tests\Privatization\Rector\ClassMethod\PrivatizeFinalClassMethodRector\Fixture;
 
 use PhpParser\PrettyPrinter\Standard;
+use Rector\PhpParser\Node\FileNode;
 
 final class KeepMagicParentCalledMethod extends Standard
 {
     // called from parent by $this->{'p'} method
-    protected function pFileNode($fileNode)
+    protected function pFileNode(FileNode $fileNode)
     {
     }
 }

rules/CodingStyle/Application/UseImportsAdder.php

@@ -14,7 +14,7 @@
 use Rector\CodingStyle\ClassNameImport\UsedImportsResolver;
 use Rector\NodeTypeResolver\Node\AttributeKey;
 use Rector\NodeTypeResolver\PHPStan\Type\TypeFactory;
-use Rector\PhpParser\Node\CustomNode\FileWithoutNamespace;
+use Rector\PhpParser\Node\FileNode;
 use Rector\StaticTypeMapper\ValueObject\Type\AliasedObjectType;
 use Rector\StaticTypeMapper\ValueObject\Type\FullyQualifiedObjectType;
 
@@ -33,7 +33,7 @@ public function __construct(
      * @param array<FullyQualifiedObjectType|AliasedObjectType> $functionUseImportTypes
      */
     public function addImportsToStmts(
-        FileWithoutNamespace $fileWithoutNamespace,
+        FileNode $fileNode,
         array $stmts,
         array $useImportTypes,
         array $constantUseImportTypes,
@@ -45,10 +45,12 @@ public function addImportsToStmts(
         $existingFunctionUseImports = $usedImports->getFunctionImports();
 
         $useImportTypes = $this->diffFullyQualifiedObjectTypes($useImportTypes, $existingUseImportTypes);
+
         $constantUseImportTypes = $this->diffFullyQualifiedObjectTypes(
             $constantUseImportTypes,
             $existingConstantUseImports
         );
+
         $functionUseImportTypes = $this->diffFullyQualifiedObjectTypes(
             $functionUseImportTypes,
             $existingFunctionUseImports
@@ -90,17 +92,17 @@ public function addImportsToStmts(
 
             array_splice($stmts, $key + 1, 0, $nodesToAdd);
 
-            $fileWithoutNamespace->stmts = $stmts;
-            $fileWithoutNamespace->stmts = array_values($fileWithoutNamespace->stmts);
+            $fileNode->stmts = $stmts;
+            $fileNode->stmts = array_values($fileNode->stmts);
 
             return true;
         }
 
         $this->mirrorUseComments($stmts, $newUses);
 
         // make use stmts first
-        $fileWithoutNamespace->stmts = array_merge($newUses, $this->resolveInsertNop($fileWithoutNamespace), $stmts);
-        $fileWithoutNamespace->stmts = array_values($fileWithoutNamespace->stmts);
+        $fileNode->stmts = array_merge($newUses, $this->resolveInsertNop($fileNode), $stmts);
+        $fileNode->stmts = array_values($fileNode->stmts);
 
         return true;
     }
@@ -154,7 +156,7 @@ public function addImportsToNamespace(
     /**
      * @return Nop[]
      */
-    private function resolveInsertNop(FileWithoutNamespace|Namespace_ $namespace): array
+    private function resolveInsertNop(FileNode|Namespace_ $namespace): array
     {
         $currentStmt = $namespace->stmts[0] ?? null;
         if (! $currentStmt instanceof Stmt || $currentStmt instanceof Use_ || $currentStmt instanceof GroupUse) {

rules/CodingStyle/Application/UseImportsRemover.php

@@ -6,7 +6,7 @@
 
 use PhpParser\Node\Stmt\Namespace_;
 use PhpParser\Node\Stmt\Use_;
-use Rector\PhpParser\Node\CustomNode\FileWithoutNamespace;
+use Rector\PhpParser\Node\FileNode;
 use Rector\Renaming\Collector\RenamedNameCollector;
 
 final readonly class UseImportsRemover
@@ -19,7 +19,7 @@ public function __construct(
     /**
      * @param string[] $removedUses
      */
-    public function removeImportsFromStmts(FileWithoutNamespace|Namespace_ $node, array $removedUses): bool
+    public function removeImportsFromStmts(FileNode|Namespace_ $node, array $removedUses): bool
     {
         $hasRemoved = false;
         foreach ($node->stmts as $key => $stmt) {

rules/CodingStyle/ClassNameImport/AliasUsesResolver.php

@@ -10,7 +10,7 @@
 use PhpParser\Node\Stmt\Namespace_;
 use PhpParser\Node\Stmt\Use_;
 use PhpParser\Node\UseItem;
-use Rector\PhpParser\Node\CustomNode\FileWithoutNamespace;
+use Rector\PhpParser\Node\FileNode;
 
 final readonly class AliasUsesResolver
 {
@@ -25,11 +25,11 @@ public function __construct(
      */
     public function resolveFromNode(Node $node, array $stmts): array
     {
-        if (! $node instanceof Namespace_ && ! $node instanceof FileWithoutNamespace) {
-            /** @var Namespace_[]|FileWithoutNamespace[] $namespaces */
+        if (! $node instanceof Namespace_ && ! $node instanceof FileNode) {
+            /** @var Namespace_[]|FileNode[] $namespaces */
             $namespaces = array_filter(
                 $stmts,
-                static fn (Stmt $stmt): bool => $stmt instanceof Namespace_ || $stmt instanceof FileWithoutNamespace
+                static fn (Stmt $stmt): bool => $stmt instanceof Namespace_ || $stmt instanceof FileNode
             );
             if (count($namespaces) !== 1) {
                 return [];

rules/CodingStyle/ClassNameImport/ShortNameResolver.php

@@ -9,7 +9,6 @@
 use PhpParser\Node\Name;
 use PhpParser\Node\Stmt;
 use PhpParser\Node\Stmt\ClassLike;
-use PhpParser\Node\Stmt\Namespace_;
 use PHPStan\PhpDocParser\Ast\PhpDoc\PhpDocTagNode;
 use PHPStan\PhpDocParser\Ast\Type\IdentifierTypeNode;
 use Rector\BetterPhpDocParser\PhpDocInfo\PhpDocInfo;
@@ -20,7 +19,6 @@
 use Rector\PhpDocParser\NodeTraverser\SimpleCallableNodeTraverser;
 use Rector\PhpDocParser\PhpDocParser\PhpDocNodeTraverser;
 use Rector\PhpParser\Node\BetterNodeFinder;
-use Rector\PhpParser\Node\CustomNode\FileWithoutNamespace;
 use Rector\ValueObject\Application\File;
 
 /**
@@ -65,22 +63,15 @@ public function resolveFromFile(File $file): array
      */
     public function resolveShortClassLikeNames(File $file): array
     {
-        $newStmts = $file->getNewStmts();
-
-        /** @var Namespace_[]|FileWithoutNamespace[] $namespaces */
-        $namespaces = array_filter(
-            $newStmts,
-            static fn (Stmt $stmt): bool => $stmt instanceof Namespace_ || $stmt instanceof FileWithoutNamespace
-        );
-        if (count($namespaces) !== 1) {
-            // only handle single namespace nodes
+        $rootNode = $file->getUseImportsRootNode();
+
+        // nothing to resolve
+        if (! $rootNode instanceof Node) {
             return [];
         }
 
-        $namespace = current($namespaces);
-
         /** @var ClassLike[] $classLikes */
-        $classLikes = $this->betterNodeFinder->findInstanceOf($namespace->stmts, ClassLike::class);
+        $classLikes = $this->betterNodeFinder->findInstanceOf($rootNode->stmts, ClassLike::class);
 
         $shortClassLikeNames = [];
         foreach ($classLikes as $classLike) {