Add RootResolverSignatureRector to auto-fix root resolver signatures

.github/workflows/validate.yml

@@ -168,7 +168,7 @@ jobs:
           key: php-${{ matrix.php-version }}-composer-${{ matrix.laravel-version }}-os-${{ matrix.os }}-composer-${{ matrix.composer.name }}
 
       - name: "Remove conflicting dependencies that are not needed here"
-        run: composer remove --dev --no-update larastan/larastan phpstan/phpstan-mockery phpbench/phpbench rector/rector
+        run: composer remove --dev --no-update phpstan/phpstan-mockery phpbench/phpbench
 
       - name: "Remove Pennant for Laravel 9 because it is not compatible"
         if: matrix.laravel-version == '^9'
@@ -224,7 +224,7 @@ jobs:
           path: ~/.composer/cache
           key: php-${{ matrix.php-version }}-composer-${{ matrix.laravel-version }}
 
-      - run: composer remove --dev phpbench/phpbench rector/rector --no-update
+      - run: composer remove --dev phpbench/phpbench --no-update
 
       - run: composer require laravel/framework:${{ matrix.laravel-version }} --no-interaction --prefer-dist --no-progress
 

.gitignore

@@ -7,6 +7,7 @@
 .vscode
 phpunit.xml
 .gitpod.yml
+docs/superpowers
 
 # Generated files
 .phpunit.result.cache

CHANGELOG.md

@@ -9,6 +9,10 @@ You can find and compare releases at the [GitHub release page](https://github.co
 
 ## Unreleased
 
+### Added
+
+- Add `RootResolverSignatureRector` rule to auto-fix root resolver `__invoke` signatures https://github.com/nuwave/lighthouse/pull/2779
+
 ## v6.68.0
 
 ### Added

composer.json

@@ -49,7 +49,7 @@
         "ergebnis/composer-normalize": "^2.2.2",
         "fakerphp/faker": "^1.21",
         "google/protobuf": "^3.21 || ^4.33.6",
-        "larastan/larastan": "^2.9.14 || ^3.0.4",
+        "larastan/larastan": "^2.9.14 || ^3.10",
         "laravel/framework": "^9 || ^10 || ^11 || ^12 || ^13",
         "laravel/legacy-factories": "^1.1.1",
         "laravel/pennant": "^1",
@@ -68,7 +68,7 @@
         "phpunit/phpunit": "^9.6.4 || ^10 || ^11 || ^12",
         "predis/predis": "^1.1 || ^2.1",
         "pusher/pusher-php-server": "^5 || ^6 || ^7.0.2",
-        "rector/rector": "^1 || ^2",
+        "rector/rector": "^1.2.10 || ^2.5.7",
         "thecodingmachine/phpstan-safe-rule": "^1.2"
     },
     "suggest": {

docs/master/api-reference/resolvers.md

@@ -22,6 +22,77 @@ function (mixed $root, array $args, GraphQLContext $context, ResolveInfo $resolv
 
 The return value of this must fit the return type defined for the corresponding field from the schema.
 
+## Root resolvers
+
+Root resolvers are classes with an `__invoke` method that sit directly in the configured
+`lighthouse.namespaces.queries` or `lighthouse.namespaces.mutations` namespaces.
+Lighthouse calls them with positional arguments `($root, $args, $context, $resolveInfo)` where `$root` is always `null` for root types.
+
+Omitting `$root` causes Lighthouse's positional `null` to bind to `$args`, producing TypeErrors at runtime.
+The canonical signature for a root resolver is:
+
+```php
+use Nuwave\Lighthouse\Execution\ResolveInfo;
+use Nuwave\Lighthouse\Support\Contracts\GraphQLContext;
+
+class MyQuery
+{
+    public function __invoke(mixed $root, array $args, GraphQLContext $context, ResolveInfo $resolveInfo)
+    {
+        // ...
+    }
+}
+```
+
+On PHP 8.2+, you can use the more precise `null` type instead of `mixed`.
+The Rector rule below automatically picks the correct type for your PHP version.
+
+### Rector rule
+
+Lighthouse ships a Rector rule that enforces correct `__invoke` signatures on root resolvers.
+Enable it in your `rector.php`:
+
+```php
+use Nuwave\Lighthouse\Rector\RootResolverSignatureRector;
+use Rector\Config\RectorConfig;
+
+return static function (RectorConfig $rectorConfig): void {
+    $rectorConfig->rule(RootResolverSignatureRector::class);
+
+    // Required: Larastan bootstrap makes config() available
+    $rectorConfig->bootstrapFiles([
+        __DIR__ . '/vendor/larastan/larastan/bootstrap.php',
+    ]);
+};
+```
+
+The rule fixes:
+
+- Missing `$root` parameter (detected when there is a single param typed `array` or untyped)
+- Missing `$args` parameter when only `$root` is present
+- Wrong type on the `$root` parameter (must be `null` on PHP 8.2+, `mixed` on earlier versions)
+- Wrong type on `$args` (must be `array`)
+- Wrong type on `$context` if present (must implement `GraphQLContext`)
+- Wrong type on `$resolveInfo` if present (must be or extend `ResolveInfo`)
+
+#### Name normalization
+
+Optionally configure preferred parameter names:
+
+```php
+$rectorConfig->ruleWithConfiguration(RootResolverSignatureRector::class, [
+    'paramNames' => ['_', 'args', 'context', 'resolveInfo'],
+]);
+```
+
+Use `null` at any position to skip renaming that parameter:
+
+```php
+$rectorConfig->ruleWithConfiguration(RootResolverSignatureRector::class, [
+    'paramNames' => [null, null, 'context', 'resolveInfo'],
+]);
+```
+
 ## Complexity function signature
 
 The complexity function is used to calculate a query complexity score for a field.

phpstan.neon

@@ -21,6 +21,9 @@ parameters:
   # laravel/pennant requires Laravel 10
   - src/Pennant
   - tests/Integration/Pennant
+  # rector/rector is removed for PHPStan CI to avoid dependency conflicts
+  - src/Rector
+  - tests/Unit/Rector
   - src/Tracing/FederatedTracing/Proto # Generated classes from protobuf
   # Ignore errors caused by the absence of Lumen in the dev dependencies
   - tests/Unit/Testing/TestingTraitDummyLumen.php