feat(graphql-language-service): support GraphQL 17 fragment arguments (#4462)

Revives #3761 now that GraphQL.js 17 ships experimental fragment
argument support.

## What changed

- parse fragment variable definitions and fragment spread arguments in
the online parser
- enable GraphQL.js 17's `experimentalFragmentArguments` parser option
across diagnostics, outlines, operation facts, fragment dependencies,
document mode detection, and external fragments
- resolve fragment variable definitions into language-service type
information
- autocomplete fragment argument names and values, including incomplete
documents and external fragments
- keep variable completion scope-aware across operations and fragments,
including fragment-local shadowing and transitively reachable operations
- show fragment argument type hover information
- validate fragment arguments with GraphQL.js 17's specified rules
- add a dedicated GraphQL 17 CI job and a release changeset

Author: JoviDeCroock

.changeset/tidy-fragments-argue.md

@@ -0,0 +1,17 @@
+---
+'graphql-language-service': minor
+'graphql-language-service-server': minor
+'monaco-graphql': minor
+'@graphiql/react': minor
+'graphiql': minor
+'codemirror-graphql': patch
+'cm6-graphql': patch
+---
+
+Add opt-in GraphQL 17 fragment argument syntax support to parsing, validation,
+type information, autocomplete, hover, and editor integrations. Enable it with
+`experimentalFragmentArguments: true`; it defaults to `false` until server
+capabilities can advertise support.
+
+Also fix variable autocomplete to respect operation and fragment scope while
+including variables from operations that spread the current fragment.

.github/workflows/pr.yml

@@ -78,6 +78,24 @@ jobs:
           path: ${{ env.BUILD-CACHE-LIST }}
       - run: yarn test
 
+  graphql-17-fragment-arguments:
+    name: GraphQL 17 Fragment Arguments
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-node@v6
+        with:
+          node-version-file: '.node-version'
+          cache: yarn
+      - run: yarn install --immutable
+      - run: yarn workspace graphql-language-service add --dev graphql@17.0.2
+      - name: Build and typecheck graphql-language-service
+        run: yarn workspace graphql-language-service exec tsc
+      - name: Test fragment argument integration
+        run: >-
+          yarn vitest run packages/graphql-language-service/src/parser/__tests__/OnlineParser.test.ts packages/graphql-language-service/src/interface/__tests__/getAutocompleteSuggestions.test.ts packages/graphql-language-service/src/interface/__tests__/getDiagnostics.test.ts packages/graphql-language-service/src/interface/__tests__/getHoverInformation.test.ts
+
+
   lint:
     name: Lint
     runs-on: ubuntu-latest

packages/cm6-graphql/src/lint.ts

@@ -39,7 +39,14 @@ export const lint: Extension = linter(
         },
       ];
     }
-    const results = getDiagnostics(view.state.doc.toString(), schema);
+    const results = getDiagnostics(
+      view.state.doc.toString(),
+      schema,
+      undefined,
+      undefined,
+      undefined,
+      options?.autocompleteOptions,
+    );
 
     return results
       .map((item): Diagnostic | null => {

packages/codemirror-graphql/src/lint.ts

@@ -9,7 +9,10 @@
 
 import CodeMirror from 'codemirror';
 import { FragmentDefinitionNode, GraphQLSchema, ValidationRule } from 'graphql';
-import { getDiagnostics } from 'graphql-language-service';
+import {
+  getDiagnostics,
+  GraphQLLanguageServiceOptions,
+} from 'graphql-language-service';
 
 const SEVERITY = ['error', 'warning', 'information', 'hint'];
 const TYPE: Record<string, string> = {
@@ -22,6 +25,7 @@ interface GraphQLLintOptions {
   schema?: GraphQLSchema;
   validationRules: ValidationRule[];
   externalFragments?: string | FragmentDefinitionNode[];
+  languageServiceOptions?: GraphQLLanguageServiceOptions;
 }
 
 /**
@@ -42,13 +46,19 @@ CodeMirror.registerHelper(
   'lint',
   'graphql',
   (text: string, options: GraphQLLintOptions): CodeMirror.Annotation[] => {
-    const { schema, validationRules, externalFragments } = options;
+    const {
+      schema,
+      validationRules,
+      externalFragments,
+      languageServiceOptions,
+    } = options;
     const rawResults = getDiagnostics(
       text,
       schema,
       validationRules,
       undefined,
       externalFragments,
+      languageServiceOptions,
     );
 
     const results = rawResults.map(error => ({

packages/graphiql-react/src/components/operation-editor.tsx

@@ -82,6 +82,7 @@ export const OperationEditor: FC<OperationEditorProps> = ({
     ),
   );
   const ref = useRef<HTMLDivElement>(null!);
+  const { monacoGraphQL, monaco } = useMonaco();
   const onClickReferenceRef = useRef<OperationEditorProps['onClickReference']>(
     null!,
   );
@@ -158,7 +159,14 @@ export const OperationEditor: FC<OperationEditorProps> = ({
     */
 
   function getAndUpdateOperationFacts(editorInstance: MonacoEditor) {
-    const operationFacts = getOperationFacts(schema, editorInstance.getValue());
+    const operationFacts = getOperationFacts(
+      schema,
+      editorInstance.getValue(),
+      {
+        experimentalFragmentArguments:
+          monacoGraphQL?.experimentalFragmentArguments,
+      },
+    );
     // Update the operation name should any query names change.
     const newOperationName = getSelectedOperationName(
       operations,
@@ -206,8 +214,6 @@ export const OperationEditor: FC<OperationEditorProps> = ({
     };
   }, [operationName, operations, run, setOperationName]);
 
-  const { monacoGraphQL, monaco } = useMonaco();
-
   useEffect(() => {
     if (!monaco || !monacoGraphQL) {
       return;

packages/graphiql-react/src/components/provider.tsx

@@ -57,6 +57,8 @@ interface GraphiQLProviderProps
     ThemeProps,
     StorageProps {
   children: ReactNode;
+  /** Enable experimental fragment arguments in the operation editor. */
+  experimentalFragmentArguments?: boolean;
 }
 
 type GraphiQLStore = UseBoundStore<StoreApi<SlicesWithActions>>;
@@ -128,7 +130,9 @@ useEffect(() => {
   const [mounted, setMounted] = useState(false);
 
   useEffect(() => {
-    void actions.initialize();
+    void actions.initialize({
+      experimentalFragmentArguments: props.experimentalFragmentArguments,
+    });
     setMounted(true);
   }, []); // eslint-disable-line react-hooks/exhaustive-deps
 

packages/graphiql-react/src/stores/monaco.ts

@@ -1,5 +1,8 @@
 import { createStore } from 'zustand';
-import type { MonacoGraphQLAPI } from 'monaco-graphql';
+import type {
+  MonacoGraphQLAPI,
+  MonacoGraphQLInitializeConfig,
+} from 'monaco-graphql';
 import { createBoundedUseStore } from '../utility';
 import {
   JSON_DIAGNOSTIC_OPTIONS,
@@ -12,7 +15,12 @@ interface MonacoStoreType {
   monaco?: typeof import('monaco-editor');
   monacoGraphQL?: MonacoGraphQLAPI;
   actions: {
-    initialize: () => Promise<void>;
+    initialize: (
+      options?: Pick<
+        MonacoGraphQLInitializeConfig,
+        'experimentalFragmentArguments'
+      >,
+    ) => Promise<void>;
   };
 }
 
@@ -65,7 +73,7 @@ async function patchFirefox() {
  */
 export const monacoStore = createStore<MonacoStoreType>((set, get) => ({
   actions: {
-    async initialize() {
+    async initialize(options) {
       const isInitialized = Boolean(get().monaco);
       if (isInitialized) {
         return;
@@ -88,6 +96,7 @@ export const monacoStore = createStore<MonacoStoreType>((set, get) => ({
       }
       const monacoGraphQL = initializeMode({
         diagnosticSettings: MONACO_GRAPHQL_DIAGNOSTIC_SETTINGS,
+        ...options,
       });
       set({ monaco, monacoGraphQL });
     },

packages/graphiql/README.md

@@ -117,6 +117,10 @@ const root = createRoot(document.getElementById('root'));
 root.render(<GraphiQL fetcher={fetcher} />);
 ```
 
+When the connected server supports GraphQL.js 17 fragment arguments, opt in
+with `<GraphiQL fetcher={fetcher} experimentalFragmentArguments />`. The syntax
+is disabled by default.
+
 ## Customize
 
 GraphiQL supports customization in UI and behavior by accepting React props and

packages/graphql-language-service-server/README.md

@@ -167,6 +167,8 @@ module.exports = {
       enableValidation: true,
       // (experimental) enhanced auto expansion of graphql leaf fields and arguments
       fillLeafsOnComplete: true,
+      // enable GraphQL.js 17 experimental fragment arguments across language features
+      experimentalFragmentArguments: true,
       // instead of jumping directly to the SDL file, you can override definition peek/jump results to point to different files or locations
       // (for example, source files for your schema in any language!)
       // based on Relay vscode's pathToLocateCommand

packages/graphql-language-service-server/src/GraphQLCache.ts

@@ -18,6 +18,7 @@ import {
   parse,
   visit,
 } from 'graphql';
+import type { ParseOptions } from 'graphql';
 import type {
   CachedContent,
   GraphQLFileMetadata,
@@ -162,6 +163,17 @@ export class GraphQLCache {
 
   getGraphQLConfig = (): GraphQLConfig => this._graphQLConfig;
 
+  _parseGraphQL = (query: string, filePath?: Uri): DocumentNode => {
+    const projectConfig = filePath
+      ? this.getProjectForFile(filePath)
+      : undefined;
+    return parse(query, {
+      experimentalFragmentArguments:
+        projectConfig?.extensions?.languageService
+          ?.experimentalFragmentArguments === true,
+    } as ParseOptions);
+  };
+
   getProjectForFile = (uri: string): GraphQLProjectConfig | void => {
     try {
       const project = this._graphQLConfig.getProjectForFile(
@@ -184,6 +196,7 @@ export class GraphQLCache {
   getFragmentDependencies = async (
     query: string,
     fragmentDefinitions?: Map<string, FragmentInfo> | null,
+    experimentalFragmentArguments = false,
   ): Promise<FragmentInfo[]> => {
     // If there isn't context for fragment references,
     // return an empty array.
@@ -194,7 +207,9 @@ export class GraphQLCache {
     // Return an empty array.
     let parsedQuery;
     try {
-      parsedQuery = parse(query);
+      parsedQuery = parse(query, {
+        experimentalFragmentArguments,
+      } as ParseOptions);
     } catch {
       return [];
     }
@@ -452,7 +467,7 @@ export class GraphQLCache {
     const asts = contents.map(({ query }) => {
       try {
         return {
-          ast: parse(query),
+          ast: this._parseGraphQL(query, filePath),
           query,
         };
       } catch {
@@ -507,7 +522,7 @@ export class GraphQLCache {
     const asts = contents.map(({ query }) => {
       try {
         return {
-          ast: parse(query),
+          ast: this._parseGraphQL(query, filePath),
           query,
         };
       } catch {
@@ -821,7 +836,7 @@ export class GraphQLCache {
         }
 
         for (const { query } of queries) {
-          asts.push(parse(query));
+          asts.push(this._parseGraphQL(query, filePath));
         }
         return {
           filePath,