[glen-84]

Summary

• Fragment spread arguments are now validated: an argument the target fragment does not declare, a duplicate argument, and a required argument that is missing or explicitly null are each reported. The existing argument messages are reused with a fragment extension, so no new wording was needed for them.
• A fragment's variable definitions form their own scope. They shadow an operation variable of the same name for the duration of the fragment and are restored on leave, so a usage after the spread resolves against the operation again. Uniqueness applies per operation or per fragment, and a usage that a fragment's own declaration satisfies neither requires an operation variable to declare it nor counts towards the usages of one it shadows.
• A fragment that declares a variable it never uses is reported, tracked per fragment so that a nested spread does not discard the enclosing fragment's declarations.
• Value checking follows from the same scope work rather than duplicating it: a literal is checked against the declared fragment variable type by the values-of-correct-type rule, and a variable passed as a fragment argument by the variable-usage rule.

Also corrected here: ArgumentDoesNotExist linked to sec-Required-Arguments, which is the section asserting that a required argument was supplied. An argument the target does not declare belongs to sec-Argument-Names, as the fragment-arguments RFC states explicitly: "Every argument provided to a named fragment spread must be defined in the set of possible variables of that named fragment." The fix applies to fields and directives too, which moves the specifiedBy link in 12 existing snapshots.

Two rules are deliberately held back, because both depend on how the rewrite pass substitutes arguments: the FieldsInSetCanMerge extension for same-name spreads carrying different argument sets, and the rejection of a defaulted fragment variable fed a possibly-unprovided operation variable.

All of this is reachable only with the experimental parser option, which no server configuration exposes, so the rules are exercised through DocumentValidator directly.

Test plan

• dotnet test src/HotChocolate/Core/test/Validation.Tests passes 2540 tests across net8.0, net9.0, net10.0, and net11.0.
• Ten new tests, eight of them snapshot-based via ExpectErrors, which pins each error's message, locations, path, and extensions, including the new fragment extension.
• The test base gained ParserOptions overloads so fragment-argument documents parse through the existing ExpectValid/ExpectErrors helpers instead of hand-rolled parse calls.
• Each behaviour was mutation-checked: dropping the shadow restore, never reporting unused fragment variables, counting a fragment-satisfied usage as an operation usage, and omitting the declared-type push each fail exactly the tests that claim them.
• src/All.slnx builds with 0 errors. Execution.Tests was clean apart from SubscriptionEventTimeoutTests, a load-sensitive timing flake that passes in isolation.

[Copilot]

Pull request overview

This PR extends HotChocolate’s document validation to support the experimental “fragment variable definitions + fragment spread arguments” syntax by (1) validating fragment-spread arguments against the target fragment’s declared variables and (2) introducing fragment-local variable scoping/shadowing so fragment variables do not interfere with operation variables outside the fragment.

Changes:

• Add fragment-spread argument validation (unknown arg, duplicate arg, missing required arg / explicit null for required) and reuse existing error messages with a fragment extension.
• Implement fragment variable scoping + shadowing behavior and update variable/value visitors so fragment-spread arguments are typed from the target fragment’s variable definitions.
• Add/adjust validation tests and snapshots to cover fragment-argument parsing/validation and updated specifiedBy links.

Reviewed changes

Copilot reviewed 35 out of 36 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
src/HotChocolate/Core/test/Validation.Tests/VariablesAreInputTypesRuleTests.cs	Adds coverage for fragment-declared variable being an output type.
src/HotChocolate/Core/test/Validation.Tests/ValuesOfCorrectTypeRuleTests.cs	Adds coverage for wrong-typed literal passed to fragment spread argument.
src/HotChocolate/Core/test/Validation.Tests/RequiredArgumentRuleTests.cs	Adds coverage for missing required fragment variable at spread site.
src/HotChocolate/Core/test/Validation.Tests/DocumentValidatorVisitorTestBase.cs	Adds parser-option overloads + shared parser options enabling fragment arguments in tests.
src/HotChocolate/Core/test/Validation.Tests/ArgumentUniquenessRuleTests.cs	Adds coverage for duplicate fragment spread arguments.
src/HotChocolate/Core/test/Validation.Tests/ArgumentNamesRuleTests.cs	Adds coverage for unknown fragment spread argument names.
src/HotChocolate/Core/test/Validation.Tests/AllVariableUsagesAreAllowedRuleTests.cs	Adds coverage for shadowing restore + nullable-to-nonnull fragment argument variable passing.
src/HotChocolate/Core/test/Validation.Tests/AllVariablesUsedRuleTests.cs	Adds coverage for fragment-only declaration, unused fragment variables, and operation var used only inside shadowing fragment.
src/HotChocolate/Core/test/Validation.Tests/snapshots/VariablesAreInputTypesRuleTests.Validate_Should_Report_When_AFragmentDeclaresAnOutputTypeVariable.snap	New snapshot for fragment variable input-type validation + fragment-unused-variable reporting.
src/HotChocolate/Core/test/Validation.Tests/snapshots/ValuesOfCorrectTypeRuleTests.Validate_Should_Report_When_AFragmentArgumentValueHasTheWrongType.snap	New snapshot for wrong-typed fragment argument value.
src/HotChocolate/Core/test/Validation.Tests/snapshots/RequiredArgumentRuleTests.Validate_Should_Report_When_ASpreadOmitsARequiredFragmentVariable.snap	New snapshot for missing required fragment argument.
src/HotChocolate/Core/test/Validation.Tests/snapshots/RequiredArgumentRuleTests.MissingOneNonNullableArgument.snap	Updates specifiedBy link for ArgumentDoesNotExist.
src/HotChocolate/Core/test/Validation.Tests/snapshots/RequiredArgumentRuleTests.IncorrectValueAndMissingArgument.snap	Updates specifiedBy link for ArgumentDoesNotExist.
src/HotChocolate/Core/test/Validation.Tests/snapshots/DocumentValidatorTests.InvalidFieldArgName.snap	Updates specifiedBy link for ArgumentDoesNotExist.
src/HotChocolate/Core/test/Validation.Tests/snapshots/ArgumentUniquenessRuleTests.Validate_Should_Report_When_ASpreadPassesTheSameArgumentTwice.snap	New snapshot for duplicate fragment arguments error including fragment extension.
src/HotChocolate/Core/test/Validation.Tests/snapshots/ArgumentNamesRuleTests.Validate_Should_Report_When_ASpreadPassesAnArgumentTheFragmentDoesNotDeclare.snap	New snapshot for unknown fragment argument error including fragment extension.
src/HotChocolate/Core/test/Validation.Tests/snapshots/ArgumentNamesRuleTests.UnknownArgsDeeply.snap	Updates specifiedBy link for ArgumentDoesNotExist.
src/HotChocolate/Core/test/Validation.Tests/snapshots/ArgumentNamesRuleTests.UnknownArgsAmongstKnowArgs.snap	Updates specifiedBy link for ArgumentDoesNotExist (two occurrences).
src/HotChocolate/Core/test/Validation.Tests/snapshots/ArgumentNamesRuleTests.MisspelledFieldArgsAreReported.snap	Updates specifiedBy link for ArgumentDoesNotExist.
src/HotChocolate/Core/test/Validation.Tests/snapshots/ArgumentNamesRuleTests.MisspelledDirectiveArgsAreReported.snap	Updates specifiedBy link for ArgumentDoesNotExist.
src/HotChocolate/Core/test/Validation.Tests/snapshots/ArgumentNamesRuleTests.InvalidFieldArgNameInReusedFragment.snap	Updates specifiedBy link for ArgumentDoesNotExist.
src/HotChocolate/Core/test/Validation.Tests/snapshots/ArgumentNamesRuleTests.InvalidFieldArgName.snap	Updates specifiedBy link for ArgumentDoesNotExist.
src/HotChocolate/Core/test/Validation.Tests/snapshots/ArgumentNamesRuleTests.InvalidDirectiveArgName.snap	Updates specifiedBy link for ArgumentDoesNotExist.
src/HotChocolate/Core/test/Validation.Tests/snapshots/ArgumentNamesRuleTests.DirectiveWithWrongArgsIsInvalid.snap	Updates specifiedBy link for ArgumentDoesNotExist.
src/HotChocolate/Core/test/Validation.Tests/snapshots/AllVariableUsagesAreAllowedRuleTests.Validate_Should_Report_When_ANullableVariableIsPassedToANonNullFragmentArgument.snap	New snapshot for variable-usage compatibility when passing op var to required fragment arg.
src/HotChocolate/Core/test/Validation.Tests/snapshots/AllVariablesUsedRuleTests.Validate_Should_Report_When_AnOperationVariableIsOnlyUsedInsideAShadowingFragment.snap	New snapshot for operation variable reported unused due to fragment shadowing.
src/HotChocolate/Core/test/Validation.Tests/snapshots/AllVariablesUsedRuleTests.Validate_Should_Report_When_AFragmentDeclaresAVariableItDoesNotUse.snap	New snapshot for fragment-specific unused-variable reporting.
src/HotChocolate/Core/src/Validation/TypeDocumentValidatorVisitor.cs	Adds fragment-variable scope enter/leave and prevents fragment vars registering as op vars.
src/HotChocolate/Core/src/Validation/Rules/VariableVisitor.cs	Implements fragment variable frames, fragment-unused-variable reporting, and fragment-spread argument typing/default handling.
src/HotChocolate/Core/src/Validation/Rules/ValueVisitor.cs	Types fragment-spread arguments based on target fragment variable definitions.
src/HotChocolate/Core/src/Validation/Rules/ArgumentVisitor.cs	Adds fragment-spread argument validation (unknown/duplicate/missing required/null required).
src/HotChocolate/Core/src/Validation/Properties/Resources.resx	Adds resource string for fragment-unused-variable error message.
src/HotChocolate/Core/src/Validation/Properties/Resources.Designer.cs	Adds strongly-typed accessor for new fragment-unused-variable resource.
src/HotChocolate/Core/src/Validation/FragmentArguments.cs	New helper for resolving fragment spread arguments to fragment variable definitions/types.
src/HotChocolate/Core/src/Validation/ErrorHelper.cs	Adds fragment-unused-variable error + extends argument error helpers to include optional fragment extension and correct specifiedBy for unknown args.
src/HotChocolate/Core/src/Validation/DocumentValidatorContext.cs	Adds fragment-variable scoping/shadowing state and APIs, resets/clears the new state.

Files not reviewed (1)

• src/HotChocolate/Core/src/Validation/Properties/Resources.Designer.cs: Generated file

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[github-actions]

Patch coverage

95.5% of changed lines covered (254/266)

File	Covered	Changed	Patch %
…/HotChocolate/Core/src/Validation/Rules/ArgumentVisitor.cs	47	54	87.0% 🟡
src/HotChocolate/Core/src/Validation/FragmentArguments.cs	21	23	91.3% 🟡
src/HotChocolate/Core/src/Validation/Rules/ValueVisitor.cs	14	15	93.3% 🟡
…/HotChocolate/Core/src/Validation/DocumentValidatorContext.cs	45	46	97.8% 🟡
…/HotChocolate/Core/src/Validation/Rules/VariableVisitor.cs	99	100	99.0% 🟡
src/HotChocolate/Core/src/Validation/ErrorHelper.cs	23	23	100.0% 🟢
…/Core/src/Validation/TypeDocumentValidatorVisitor.cs	5	5	100.0% 🟢

Uncovered changed lines (JSON)

{
  "sha": "9173ae2d3766a4da22e97f4a1af7fbef37d5dd96",
  "files": [
    { "path": "src/HotChocolate/Core/src/Validation/Rules/ArgumentVisitor.cs", "ranges": [[159, 165]] },
    { "path": "src/HotChocolate/Core/src/Validation/FragmentArguments.cs", "ranges": [[30, 31]] },
    { "path": "src/HotChocolate/Core/src/Validation/Rules/ValueVisitor.cs", "ranges": [[162, 162]] },
    { "path": "src/HotChocolate/Core/src/Validation/DocumentValidatorContext.cs", "ranges": [[216, 216]] },
    { "path": "src/HotChocolate/Core/src/Validation/Rules/VariableVisitor.cs", "ranges": [[281, 281]] }
  ]
}

---

Project coverage: 56.0% (261477/466652 lines)