Add RootResolverSignatureRector to auto-fix root resolver signatures by spawnia · Pull Request #2779 · nuwave/lighthouse

spawnia · 2026-07-10T11:09:37Z

Summary

Adds a configurable Rector rule (RootResolverSignatureRector) that normalizes root resolver method signatures to match the canonical ($root, array $args, GraphQLContext $context, ResolveInfo $resolveInfo) pattern. Supports custom parameter names, custom context class, and PHP version-aware typing (mixed for 8.0+, null for 8.2+).

Single-param handling:

(array $args) — prepends root: (null $_, array $args). This is the only single-param case that triggers prepending.
All other single-param cases (null $_, mixed $root, untyped $whatever) — strips the param entirely: (). These are useless root params or wrong signatures that static analysis will surface after removal.

Known limitation: the rule assumes every __invoke class directly under the configured resolver namespaces is a root resolver. Non-root-resolver classes (e.g. nested field resolvers receiving a parent model as first argument) should be moved out of those directories or added to the Rector skip list. See docs/master/testing/rector.md.

CI configuration

Remove rector/rector from PHPStan CI job (dependency conflicts with phpstan)
Exclude src/Rector and tests/Unit/Rector from PHPStan paths (rector unavailable after removal)
Bump larastan/larastan to ^3.10 (compatible with phpstan ^2.2 that rector requires)
Pin PHP 8.2 target in Rector test configs (fixtures expect null $root)
Keep rector/rector in PHPUnit job (needed for Rector rule tests)

Key files

src/Rector/RootResolverSignatureRector.php — the Rector rule
src/Schema/RootType.php — added non-empty validation for namespaces, reindex to guarantee list
tests/Unit/Rector/RootResolverSignatureRector/ — test suite
tests/Unit/Schema/RootTypeTest.php — RootType::namespaces() tests
.github/workflows/validate.yml — CI matrix (modified)
docs/master/testing/rector.md — documentation (moved from api-reference/resolvers.md)

…ces() 🤖 Generated with Claude Code

🤖 Generated with Claude Code

The rule calls RootType::namespaces() which requires config() to be available. Instead of silently falling back to defaults when config() is unavailable, fail loudly as the spec requires. The test bootstrap loads the Larastan bootstrap and registers the Lighthouse config. 🤖 Generated with Claude Code

Follow the project convention of protected over private for extensibility. Also remove redundant $objectType->equals() check (isSuperTypeOf covers it). 🤖 Generated with Claude Code

🤖 Generated with Claude Code

When a resolver had multiple params with the first typed array (e.g. __invoke(array $root, array $args)), or a single untyped param, the rule would incorrectly prepend a new $root, creating duplicate variable names. Now only considers root as missing when there is exactly one param that is either untyped or typed array. 🤖 Generated with Claude Code

Assert the value is an array (satisfies PHPStan level-8 type narrowing) and throw InvalidConfigurationException for non-string, non-null elements. 🤖 Generated with Claude Code

Instead of silently doing nothing when config() has no Lighthouse namespaces loaded, throw a RuntimeException guiding the user to add the required bootstrapFiles entry. 🤖 Generated with Claude Code

- Move fixParamType(0, ...) into else branch (no-op after prependRootParam) - Split isset() && fix() into nested ifs (one-thing-per-line) - Replace ensureMinParams while-loop with direct ensureArgsParam - Extract fixObjectParam from duplicate fixContextParam/fixResolveInfoParam 🤖 Generated with Claude Code

🤖 Generated with Claude Code

Cover wrong ResolveInfo type and untyped context/resolveInfo params. 🤖 Generated with Claude Code

🤖 Generated with Claude Code

Copilot

Pull request overview

Adds a new Rector rule to automatically fix Lighthouse root resolver __invoke method signatures so they match Lighthouse’s positional calling convention and avoid runtime TypeErrors. It also centralizes resolver namespace lookup in RootType and documents the new behavior and tooling.

Changes:

Add RootResolverSignatureRector to detect/fix root resolver __invoke parameter order, presence, types, and (optionally) names.
Extract RootType::namespaces() and reuse it from FieldValue.
Add unit tests/fixtures plus user docs and changelog entry.

Reviewed changes

Copilot reviewed 31 out of 32 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
tests/Unit/Rector/RootResolverSignatureRector/Source/CustomContext.php	Test-only custom context implementing `GraphQLContext`.
tests/Unit/Rector/RootResolverSignatureRector/RootResolverSignatureRectorWithNamesTest.php	Test runner for fixtures with name normalization config.
tests/Unit/Rector/RootResolverSignatureRector/RootResolverSignatureRectorTest.php	Main rule test runner.
tests/Unit/Rector/RootResolverSignatureRector/RootResolverSignatureRectorPartialNamesTest.php	Test runner for partial name normalization config.
tests/Unit/Rector/RootResolverSignatureRector/RootResolverSignatureRectorConfigTest.php	Tests for invalid configuration rejection.
tests/Unit/Rector/RootResolverSignatureRector/FixtureWithNames/normalize_names.php.inc	Fixture validating parameter name normalization behavior.
tests/Unit/Rector/RootResolverSignatureRector/FixturePartialNames/normalize_partial.php.inc	Fixture validating partial parameter renaming.
tests/Unit/Rector/RootResolverSignatureRector/Fixture/wrong_second_param.php.inc	Fixture for correcting `$args` type.
tests/Unit/Rector/RootResolverSignatureRector/Fixture/wrong_root_type.php.inc	Fixture for correcting `$root` type.
tests/Unit/Rector/RootResolverSignatureRector/Fixture/wrong_resolve_info_type.php.inc	Fixture for correcting `ResolveInfo` type.
tests/Unit/Rector/RootResolverSignatureRector/Fixture/wrong_context_type.php.inc	Fixture for correcting `GraphQLContext` type.
tests/Unit/Rector/RootResolverSignatureRector/Fixture/untyped_first_param.php.inc	Fixture for prepending missing `$root`.
tests/Unit/Rector/RootResolverSignatureRector/Fixture/untyped_context_and_resolve_info.php.inc	Fixture for typing `$context`/`$resolveInfo`.
tests/Unit/Rector/RootResolverSignatureRector/Fixture/skip_zero_params.php.inc	Fixture ensuring 0-param `__invoke` is skipped.
tests/Unit/Rector/RootResolverSignatureRector/Fixture/skip_subdirectory.php.inc	Fixture ensuring nested namespaces are skipped.
tests/Unit/Rector/RootResolverSignatureRector/Fixture/skip_non_resolver_namespace.php.inc	Fixture ensuring non-resolver namespaces are skipped.
tests/Unit/Rector/RootResolverSignatureRector/Fixture/skip_custom_context.php.inc	Fixture ensuring custom context types are not rewritten.
tests/Unit/Rector/RootResolverSignatureRector/Fixture/skip_correct_null.php.inc	Fixture ensuring already-correct signature is skipped.
tests/Unit/Rector/RootResolverSignatureRector/Fixture/single_wrong_root_param.php.inc	Fixture for single-param root fix + args insertion.
tests/Unit/Rector/RootResolverSignatureRector/Fixture/narrow_mixed_root.php.inc	Fixture for narrowing `mixed $root` to `null` on PHP 8.2+.
tests/Unit/Rector/RootResolverSignatureRector/Fixture/missing_root_param.php.inc	Fixture for detecting missing `$root` when first param looks like `$args`.
tests/Unit/Rector/RootResolverSignatureRector/Fixture/array_root_with_args.php.inc	Fixture for correcting invalid `$root` types.
tests/Unit/Rector/RootResolverSignatureRector/config/configured_rule.php	Rector test config enabling rule (and `importNames()`).
tests/Unit/Rector/RootResolverSignatureRector/config/configured_rule_with_names.php	Rector test config enabling rule with `paramNames`.
tests/Unit/Rector/RootResolverSignatureRector/config/configured_rule_partial_names.php	Rector test config enabling partial `paramNames`.
tests/Unit/Rector/RootResolverSignatureRector/bootstrap.php	Test bootstrap to load Larastan + Lighthouse config.
src/Schema/Values/FieldValue.php	Switch to shared `RootType::namespaces()` for root parent namespaces.
src/Schema/RootType.php	Add `RootType::namespaces()` helper to resolve configured namespaces.
src/Rector/RootResolverSignatureRector.php	New Rector rule implementing signature/type/name corrections.
docs/master/api-reference/resolvers.md	Document root resolver convention + Rector rule usage/config.
CHANGELOG.md	Note new Rector rule in Unreleased section.
.gitignore	Ignore `docs/superpowers`.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Use Rector's VariableRenamer to update all references to the old parameter name within the method body, not just the signature. #2779 (comment) 🤖 Generated with Claude Code

The standalone null type requires PHP 8.2+, but the package supports ^8. Use mixed as the safe default and note that PHP 8.2+ can use null. #2779 (comment) 🤖 Generated with Claude Code

Assertions can be disabled at runtime. Use a proper exception to guarantee validation regardless of PHP assert settings. #2779 (comment) 🤖 Generated with Claude Code

#2779 (comment) 🤖 Generated with Claude Code

🤖 Generated with Claude Code

PHPUnit 9 (Laravel 9) does not support PHP 8 attributes for data providers. Dual-annotating with both PHPDoc and attributes ensures tests run across the full CI matrix. 🤖 Generated with Claude Code

AbstractRectorTestCase sets up error/exception handlers that are not removed, triggering PHPUnit's risky test detection. Since configure() does not use constructor dependencies, use newInstanceWithoutConstructor to sidestep mocking final classes. 🤖 Generated with Claude Code

Remove rector from PHPStan CI job (it's only needed for PHPUnit tests). Rector's presence causes phpstan to resolve to incompatible versions: - rector/rector 1.x pulls phpstan to versions where Composer\InstalledVersions class discovery breaks - rector/rector 2.x requires phpstan ^2.2.2 which conflicts with larastan <3.10 Bump larastan minimum to ^3.10 (first version compatible with phpstan ^2.2). Revert phpstan minimum to ^1.12.18 || ^2 since removing rector from the PHPStan job eliminates the version conflict. 🤖 Generated with Claude Code

rector/rector is removed in the PHPStan CI job to avoid dependency conflicts, so its classes are unavailable for static analysis. 🤖 Generated with Claude Code

Copilot

Pull request overview

Copilot reviewed 34 out of 35 changed files in this pull request and generated 4 comments.

Throw RuntimeException when configured namespaces are empty or contain non-string values, return type is now non-empty-array<int, string>. Remove redundant empty check in RootResolverSignatureRector since RootType::namespaces() now handles this. #2779 (comment) 🤖 Generated with Claude Code

- Use named args for CodeSample and Param constructors - Break compound conditionals into multiple lines - Extract variables for readability - Use mixed in CodeSample (valid on all PHP ^8) - Make test fixtures more realistic (no pre-existing imports) - Use config() helper in bootstrap #2779 🤖 Generated with Claude Code

Fixtures expect `null $root` which is only valid on PHP 8.2+. Without pinning, tests would fail on PHP 8.0/8.1 where Rector produces `mixed $root` instead. #2779 🤖 Generated with Claude Code

#2779 🤖 Generated with Claude Code

Copilot

Pull request overview

Copilot reviewed 35 out of 36 changed files in this pull request and generated 4 comments.

Config may have string keys when defined as an associative array. #2779 🤖 Generated with Claude Code

When a resolver intentionally declares only a root param (e.g. `null $_` or `mixed $root`) with no args, the rule was incorrectly appending `array \$args`. ensureArgsParam now only fires when the root param was prepended by the rule itself (i.e. the resolver had array/untyped args as its only param), not when the root param already existed and was merely type-fixed. Add skip_root_only_param.php.inc fixture to cover this case, and update single_wrong_root_param.php.inc to expect only a type fix. 🤖 Generated with Claude Code

Single-param resolvers that don't match the canonical args signature (array $args) are now stripped entirely rather than having an args param incorrectly added. Only `(array $args)` triggers root prepending. 🤖 Generated with Claude Code

Copilot

Pull request overview

Copilot reviewed 37 out of 38 changed files in this pull request and generated 2 comments.

#2779 (comment) 🤖 Generated with Claude Code

Associative arrays from config would preserve string keys through array spread, potentially causing collisions that drop namespaces. #2779 (comment) 🤖 Generated with Claude Code

… are root resolvers https://mlllab.atlassian.net/browse/PFE-995 🤖 Generated with Claude Code

https://mlllab.atlassian.net/browse/PFE-995 🤖 Generated with Claude Code

…ref from resolvers https://mlllab.atlassian.net/browse/PFE-995 🤖 Generated with Claude Code

🤖 Generated with Claude Code

Copilot

Pull request overview

Copilot reviewed 50 out of 51 changed files in this pull request and generated 6 comments.

+        foreach ($paramNames as $name) {
+            if ($name !== null && ! is_string($name)) {
+                throw new InvalidConfigurationException('Each paramNames element must be a string or null.');
+            }
+        }
+
+        $this->paramNames = $paramNames;
+    }


+        $type = $method->params[0]->type;
+
+        return $type instanceof Identifier && $type->name === 'array';
+    }


+        if ($type instanceof Identifier && $type->name === 'array') {
+            return false;
+        }


+        if ($rootWasPrepended && $this->ensureArgsParam($invokeMethod)) {
+            $changed = true;
+        }


+public function __invoke(array $args): mixed {}
+
+// After
+public function __invoke(null $root, array $args): mixed {}


+public function __invoke(User $root, array $args): mixed {}
+
+// After
+public function __invoke(null $root, array $args): mixed {}


spawnia added 15 commits July 10, 2026 10:35

Extract RootType::namespaces() and refactor FieldValue::parentNamespa…

01508dd

…ces() 🤖 Generated with Claude Code

Add RootResolverSignatureRector with type-fixing behavior

3683814

🤖 Generated with Claude Code

Add name normalization tests for RootResolverSignatureRector

be9a69c

Document root resolvers and the RootResolverSignatureRector rule

e6f85c1

🤖 Generated with Claude Code

Use protected visibility in RootResolverSignatureRector

1110380

Follow the project convention of protected over private for extensibility. Also remove redundant $objectType->equals() check (isSuperTypeOf covers it). 🤖 Generated with Claude Code

Ignore docs/superpowers in .gitignore

96d6bfb

🤖 Generated with Claude Code

Validate paramNames element types in configure()

13435be

Assert the value is an array (satisfies PHPStan level-8 type narrowing) and throw InvalidConfigurationException for non-string, non-null elements. 🤖 Generated with Claude Code

Throw when resolver namespaces are empty (misconfigured bootstrap)

6d7dacd

Instead of silently doing nothing when config() has no Lighthouse namespaces loaded, throw a RuntimeException guiding the user to add the required bootstrapFiles entry. 🤖 Generated with Claude Code

Fix docs: sentence line break and missing $args insertion bullet

7acf822

🤖 Generated with Claude Code

Add missing test fixtures for fixObjectParam paths

1840f90

Cover wrong ResolveInfo type and untyped context/resolveInfo params. 🤖 Generated with Claude Code

Add CHANGELOG entry for RootResolverSignatureRector

03a4ef9

🤖 Generated with Claude Code

Apply fixes from tooling (rector, php-cs-fixer, phpstan)

ebab0a4

🤖 Generated with Claude Code

spawnia requested a review from Copilot July 10, 2026 11:09

Copilot started reviewing on behalf of spawnia July 10, 2026 11:10 View session

Copilot AI reviewed Jul 10, 2026

View reviewed changes

Comment thread src/Rector/RootResolverSignatureRector.php

Comment thread src/Rector/RootResolverSignatureRector.php

Comment thread docs/master/api-reference/resolvers.md Outdated

Comment thread CHANGELOG.md Outdated

spawnia added 12 commits July 10, 2026 13:23

Fix normalizeNames to rename variable usages in method body

d9f02dd

Use Rector's VariableRenamer to update all references to the old parameter name within the method body, not just the signature. #2779 (comment) 🤖 Generated with Claude Code

Use mixed $root in docs example for PHP 8.0/8.1 compat

4db7570

The standalone null type requires PHP 8.2+, but the package supports ^8. Use mixed as the safe default and note that PHP 8.2+ can use null. #2779 (comment) 🤖 Generated with Claude Code

Replace assert with InvalidConfigurationException for paramNames

5c95630

Assertions can be disabled at runtime. Use a proper exception to guarantee validation regardless of PHP assert settings. #2779 (comment) 🤖 Generated with Claude Code

Replace TODO placeholder with actual PR number in CHANGELOG

046cee7

#2779 (comment) 🤖 Generated with Claude Code

Keep rector/rector installed in CI to validate Rector code

332fee5

🤖 Generated with Claude Code

Keep larastan installed in PHPUnit CI job

585638b

🤖 Generated with Claude Code

Add @dataProvider annotations for PHPUnit 9.x compatibility

be1c194

PHPUnit 9 (Laravel 9) does not support PHP 8 attributes for data providers. Dual-annotating with both PHPDoc and attributes ensures tests run across the full CI matrix. 🤖 Generated with Claude Code

Merge branch 'master' into root-resolver-signature-rector-rule

837450d

fix risky test

a657821

bump phpstan and rector minimum versions

20d9943

Exclude Rector files from PHPStan analysis

ced5f40

rector/rector is removed in the PHPStan CI job to avoid dependency conflicts, so its classes are unavailable for static analysis. 🤖 Generated with Claude Code

spawnia requested a review from Copilot July 15, 2026 08:48

Copilot started reviewing on behalf of spawnia July 15, 2026 08:48 View session

Copilot AI reviewed Jul 15, 2026

View reviewed changes

spawnia commented Jul 15, 2026

View reviewed changes

spawnia added 3 commits July 15, 2026 11:24

Pin PHP 8.2 target in Rector test configs

db79118

Fixtures expect `null $root` which is only valid on PHP 8.2+. Without pinning, tests would fail on PHP 8.0/8.1 where Rector produces `mixed $root` instead. #2779 🤖 Generated with Claude Code

spawnia marked this pull request as ready for review July 15, 2026 10:20

spawnia requested a review from Copilot July 15, 2026 10:20

Copilot started reviewing on behalf of spawnia July 15, 2026 10:20 View session

spawnia commented Jul 15, 2026

View reviewed changes

Comment thread src/Rector/RootResolverSignatureRector.php Outdated

Comment thread src/Rector/RootResolverSignatureRector.php Outdated

Comment thread src/Schema/RootType.php Outdated

Use imports instead of FQCNs for GraphQLContext and ResolveInfo

4934a86

#2779 🤖 Generated with Claude Code

Copilot AI reviewed Jul 15, 2026

View reviewed changes

Comment thread src/Schema/RootType.php Outdated

Comment thread src/Rector/RootResolverSignatureRector.php

Comment thread src/Rector/RootResolverSignatureRector.php

Comment thread docs/master/api-reference/resolvers.md

spawnia and others added 4 commits July 15, 2026 12:57

Use array-key in RootType::namespaces() return type annotation

c633c64

Config may have string keys when defined as an associative array. #2779 🤖 Generated with Claude Code

Apply php-cs-fixer changes

3d1eaa5

spawnia requested a review from Copilot July 16, 2026 09:28

Copilot started reviewing on behalf of spawnia July 16, 2026 09:28 View session

Copilot AI reviewed Jul 16, 2026

View reviewed changes

Comment thread docs/master/api-reference/resolvers.md Outdated

Comment thread src/Rector/RootResolverSignatureRector.php

spawnia added 6 commits July 16, 2026 13:41

Update docs to match single-param stripping behavior

60a42e1

#2779 (comment) 🤖 Generated with Claude Code

Reindex namespaces array to guarantee list return type

3597bd9

Associative arrays from config would preserve string keys through array spread, potentially causing collisions that drop namespaces. #2779 (comment) 🤖 Generated with Claude Code

Document that the rule assumes all __invoke classes in resolver paths…

9cfe2e1

… are root resolvers https://mlllab.atlassian.net/browse/PFE-995 🤖 Generated with Claude Code

Add docs for RootResolverSignatureRector including known limitation

d368c88

https://mlllab.atlassian.net/browse/PFE-995 🤖 Generated with Claude Code

Move Rector docs to testing/rector.md as canonical source, add short …

82e6e14

…ref from resolvers https://mlllab.atlassian.net/browse/PFE-995 🤖 Generated with Claude Code

Sync docs/6 from docs/master

3ab761e

🤖 Generated with Claude Code

spawnia requested a review from Copilot July 16, 2026 15:35

Copilot started reviewing on behalf of spawnia July 16, 2026 15:36 View session

Copilot AI reviewed Jul 16, 2026

View reviewed changes

Uh oh!

Uh oh!

Conversation

spawnia commented Jul 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

CI configuration

Key files

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

spawnia commented Jul 10, 2026 •

edited

Loading