feat: support fragment arguments in Sangria field sets

Bind fragment variables as compact scopes on the same selection-set graph, reject incompatible spread arguments before fieldless-root canonicalization, and share alpha-equivalent bound proofs.

Keep charging unweighted selection scans, field-set expansions, and new proofs as work. Replacing the fallback pairwise fragment comparisons with grouped bound proofs permits lowering the configurable default safety budget from 5,000 to 2,000 units while accepting substantially larger fragment-spread sets.

This builds on [the fragment arguments proposal](graphql/graphql-spec#1224) and [its GraphQL.js implementation](#4015).

Author: yaacovCR

src/validation/__tests__/OverlappingFieldsCanBeMergedRule-test.ts

@@ -1411,8 +1411,8 @@ describe('Validate: Overlapping fields can be merged', () => {
           message:
             'Fields "a" conflict because they have differing arguments. Use different aliases on the fields to fetch both if this was intentional.',
           locations: [
-            { line: 3, column: 11 },
             { line: 7, column: 11 },
+            { line: 3, column: 11 },
           ],
         },
       ]);
@@ -1435,8 +1435,8 @@ describe('Validate: Overlapping fields can be merged', () => {
           message:
             'Fields "a" conflict because they have differing arguments. Use different aliases on the fields to fetch both if this was intentional.',
           locations: [
-            { line: 3, column: 11 },
             { line: 10, column: 11 },
+            { line: 3, column: 11 },
           ],
         },
       ]);
@@ -1456,8 +1456,8 @@ describe('Validate: Overlapping fields can be merged', () => {
           message:
             'Fields "a" conflict because they have differing arguments. Use different aliases on the fields to fetch both if this was intentional.',
           locations: [
-            { line: 3, column: 11 },
             { line: 7, column: 11 },
+            { line: 3, column: 11 },
           ],
         },
       ]);
@@ -1477,8 +1477,8 @@ describe('Validate: Overlapping fields can be merged', () => {
           message:
             'Fields "a" conflict because they have differing arguments. Use different aliases on the fields to fetch both if this was intentional.',
           locations: [
-            { line: 3, column: 11 },
             { line: 7, column: 11 },
+            { line: 3, column: 11 },
           ],
         },
       ]);
@@ -1498,8 +1498,8 @@ describe('Validate: Overlapping fields can be merged', () => {
           message:
             'Fields "a" conflict because they have differing arguments. Use different aliases on the fields to fetch both if this was intentional.',
           locations: [
-            { line: 3, column: 11 },
             { line: 7, column: 11 },
+            { line: 3, column: 11 },
           ],
         },
       ]);
@@ -1521,8 +1521,8 @@ describe('Validate: Overlapping fields can be merged', () => {
           message:
             'Fields "stringListArgField" conflict because they have differing arguments. Use different aliases on the fields to fetch both if this was intentional.',
           locations: [
-            { line: 4, column: 13 },
             { line: 9, column: 11 },
+            { line: 4, column: 13 },
           ],
         },
       ]);
@@ -1544,8 +1544,8 @@ describe('Validate: Overlapping fields can be merged', () => {
           message:
             'Fields "stringListArgField" conflict because they have differing arguments. Use different aliases on the fields to fetch both if this was intentional.',
           locations: [
-            { line: 4, column: 13 },
             { line: 9, column: 11 },
+            { line: 4, column: 13 },
           ],
         },
       ]);
@@ -1567,8 +1567,8 @@ describe('Validate: Overlapping fields can be merged', () => {
           message:
             'Fields "complexArgField" conflict because they have differing arguments. Use different aliases on the fields to fetch both if this was intentional.',
           locations: [
-            { line: 4, column: 13 },
             { line: 9, column: 11 },
+            { line: 4, column: 13 },
           ],
         },
       ]);
@@ -1590,8 +1590,8 @@ describe('Validate: Overlapping fields can be merged', () => {
           message:
             'Fields "complexArgField" conflict because they have differing arguments. Use different aliases on the fields to fetch both if this was intentional.',
           locations: [
-            { line: 4, column: 13 },
             { line: 9, column: 11 },
+            { line: 4, column: 13 },
           ],
         },
       ]);
@@ -1658,9 +1658,9 @@ describe('Validate: Overlapping fields can be merged', () => {
             'Fields "mother" conflict because subfields "doesKnowCommand" conflict because they have differing arguments. Use different aliases on the fields to fetch both if this was intentional.',
           locations: [
             { line: 5, column: 13 },
-            { line: 13, column: 13 },
             { line: 12, column: 11 },
             { line: 11, column: 11 },
+            { line: 13, column: 13 },
           ],
         },
       ]);

src/validation/rules/OverlappingFieldsCanBeMergedHelpers/ComplexityBudget.ts

@@ -3,7 +3,7 @@ import { GraphQLError } from '../../../error/GraphQLError.ts';
 const COMPLEXITY_ERROR = new GraphQLError(
   'This document is too complex to validate overlapping fields.',
 );
-const MAX_WORK = 5_000;
+const MAX_WORK = 2_000;
 
 /**
  * Bounds total field collection, graph expansion, and proof work without

src/validation/rules/OverlappingFieldsCanBeMergedHelpers/ConflictDetector.ts

@@ -14,6 +14,7 @@ import type {
   FieldSelection,
   FieldSet,
   FieldsForResponseName,
+  FragmentSpread,
 } from './FieldSetGraph.ts';
 import { FieldSetGraph } from './FieldSetGraph.ts';
 import { FieldSetProofCache } from './FieldSetProofCache.ts';
@@ -39,6 +40,7 @@ export class ConflictDetector {
   private _complexityBudget: ComplexityBudget;
   private _fieldSetGraph: FieldSetGraph;
   private _coveredFieldSets = new WeakSet<FieldSet>();
+  private _fragmentArgumentChecks?: WeakMap<ReadonlyArray<FieldSet>, boolean>;
   private _reporter?: ConflictReporter;
   private _responseProofs?: FieldSetProofCache;
   private _commonParentProofs?: FieldSetProofCache;
@@ -73,10 +75,13 @@ export class ConflictDetector {
     // A checked closure also proves each fragment closure contained in it.
     // This prevents the visitor from rebuilding every suffix of a fragment
     // chain when it later reaches the fragment definitions themselves.
-    if (this._coveredFieldSets.has(root)) {
+    if (this._coveredFieldSets.has(root.template ?? root)) {
       return;
     }
     this._fieldSetGraph.collectFields(root);
+    if (!this._rootFragmentArgumentsCanMerge([root])) {
+      return;
+    }
     if (
       !root.hasLocalOverlaps &&
       (root.fragmentSpreadsByName.size === 0 ||
@@ -89,8 +94,57 @@ export class ConflictDetector {
     this._checkResponseLevels(fieldSet);
     this._checkFieldsForCommonParents(fieldSet);
     for (const chunk of fieldSet.fieldSets) {
-      this._coveredFieldSets.add(chunk);
+      // Bindings change variable identities, not the proof shape of the
+      // fragment body, so reaching one also covers its source template.
+      this._coveredFieldSets.add(chunk.template ?? chunk);
+    }
+  }
+
+  private _rootFragmentArgumentsCanMerge(
+    fieldSets: ReadonlyArray<FieldSet>,
+  ): boolean {
+    if (!this._fieldSetGraph.usesFragmentArguments) {
+      return true;
+    }
+    const checks = (this._fragmentArgumentChecks ??= new WeakMap());
+    const cached = checks.get(fieldSets);
+    if (cached !== undefined) {
+      return cached;
     }
+    const spreadsByName = new Map<string, Array<FragmentSpread>>();
+    for (const fieldSet of fieldSets) {
+      this._fieldSetGraph.collectFields(fieldSet);
+      for (const [fragmentName, spreads] of fieldSet.fragmentSpreadsByName) {
+        const combined = spreadsByName.get(fragmentName);
+        if (combined === undefined) {
+          spreadsByName.set(fragmentName, spreads.slice());
+        } else {
+          combined.push(...spreads);
+        }
+      }
+    }
+
+    let canMerge = true;
+    for (const [fragmentName, spreads] of spreadsByName) {
+      if (
+        this._getReporter().reportFragmentArgumentConflict(
+          fragmentName,
+          spreads,
+        )
+      ) {
+        canMerge = false;
+      }
+    }
+    checks.set(fieldSets, canMerge);
+    return canMerge;
+  }
+
+  private _getReporter(): ConflictReporter {
+    return (this._reporter ??= new ConflictReporter(this._context));
+  }
+
+  private _fragmentArgumentsCanMerge(fieldSet: EffectiveFieldSet): boolean {
+    return this._rootFragmentArgumentsCanMerge(fieldSet.fieldSets);
   }
 
   private _checkResponseLevels(root: EffectiveFieldSet): void {
@@ -108,6 +162,9 @@ export class ConflictDetector {
       if (!proofs.shouldCheck(check.fieldSet)) {
         continue;
       }
+      if (!this._fragmentArgumentsCanMerge(check.fieldSet)) {
+        continue;
+      }
       for (const [
         responseName,
         fieldGroups,
@@ -122,6 +179,10 @@ export class ConflictDetector {
         if (fields === undefined) {
           continue;
         }
+        const childFieldSet = this._getSubfieldSet(fields);
+        if (childFieldSet === undefined) {
+          continue;
+        }
         const conflictPath = reporter.getConflictPath(
           check.conflictPath,
           responseName,
@@ -130,12 +191,7 @@ export class ConflictDetector {
         if (conflictPath !== undefined && conflictPath.parent === undefined) {
           rootPaths.push(conflictPath);
         }
-        pending.push({
-          fieldSet: this._fieldSetGraph.getEffectiveFieldSet(
-            this._fieldSetGraph.getSubfieldFieldSets(fields),
-          ),
-          conflictPath,
-        });
+        pending.push({ fieldSet: childFieldSet, conflictPath });
       }
     }
     for (const conflictPath of rootPaths) {
@@ -147,10 +203,6 @@ export class ConflictDetector {
     return new FieldSetProofCache(this._complexityBudget);
   }
 
-  private _getReporter(): ConflictReporter {
-    return (this._reporter ??= new ConflictReporter(this._context));
-  }
-
   private _fieldsWithSameResponseShape(
     responseName: string,
     fieldGroups: ReadonlyArray<FieldsForResponseName>,
@@ -189,6 +241,19 @@ export class ConflictDetector {
     return allFields;
   }
 
+  private _getSubfieldSet(
+    fields: ReadonlyArray<FieldSelection>,
+  ): EffectiveFieldSet | undefined {
+    const roots = this._fieldSetGraph.getSubfieldFieldSets(fields);
+    if (roots.length === 0) {
+      return;
+    }
+    if (!this._rootFragmentArgumentsCanMerge(roots)) {
+      return;
+    }
+    return this._fieldSetGraph.getEffectiveFieldSet(roots);
+  }
+
   private _checkFieldsForCommonParents(root: EffectiveFieldSet): void {
     const proofs = (this._commonParentProofs ??= this._newProofCache());
     const pending: Array<FieldSetCheck> = [
@@ -204,6 +269,9 @@ export class ConflictDetector {
       if (!proofs.shouldCheck(check.fieldSet)) {
         continue;
       }
+      if (!this._fragmentArgumentsCanMerge(check.fieldSet)) {
+        continue;
+      }
       for (const [
         responseName,
         fieldsForName,
@@ -242,6 +310,10 @@ export class ConflictDetector {
     ) {
       return;
     }
+    const childFieldSet = this._getSubfieldSet(fields);
+    if (childFieldSet === undefined) {
+      return;
+    }
     const conflictPath = reporter.getConflictPath(
       parentPath,
       responseName,
@@ -250,11 +322,6 @@ export class ConflictDetector {
     if (conflictPath !== undefined && conflictPath.parent === undefined) {
       rootPaths.push(conflictPath);
     }
-    pending.push({
-      fieldSet: this._fieldSetGraph.getEffectiveFieldSet(
-        this._fieldSetGraph.getSubfieldFieldSets(fields),
-      ),
-      conflictPath,
-    });
+    pending.push({ fieldSet: childFieldSet, conflictPath });
   }
 }