Descriptions on executable documents

src/__testUtils__/kitchenSinkQuery.ts

@@ -1,5 +1,10 @@
 export const kitchenSinkQuery: string = String.raw`
-query queryName($foo: ComplexType, $site: Site = MOBILE) @onQuery {
+"Query description"
+query queryName(
+  "Very complex variable"
+  $foo: ComplexType,
+  $site: Site = MOBILE
+) @onQuery {
   whoever123is: node(id: [123, 456]) {
     id
     ... on User @onInlineFragment {
@@ -44,6 +49,9 @@ subscription StoryLikeSubscription(
   }
 }
 
+"""
+  Fragment description
+"""
 fragment frag on Friend @onFragmentDefinition {
   foo(
     size: $size

src/language/__tests__/parser-test.ts

@@ -163,11 +163,25 @@ describe('Parser', () => {
       # This comment has a \u0A0A multi-byte character.
       { field(arg: "Has a \u0A0A multi-byte character.") }
     `);
-
-    expect(ast).to.have.nested.property(
-      'definitions[0].selectionSet.selections[0].arguments[0].value.value',
-      'Has a \u0A0A multi-byte character.',
+    const opDef = ast.definitions.find(
+      (d) => d.kind === Kind.OPERATION_DEFINITION,
     );
+    if (!opDef || opDef.kind !== Kind.OPERATION_DEFINITION) {
+      throw new Error('No operation definition found');
+    }
+    const fieldSel = opDef.selectionSet.selections[0];
+    if (fieldSel.kind !== Kind.FIELD) {
+      throw new Error('Expected a field selection');
+    }
+    const args = fieldSel.arguments;
+    if (!args || args.length === 0) {
+      throw new Error('No arguments found');
+    }
+    const argValueNode = args[0].value;
+    if (argValueNode.kind !== Kind.STRING) {
+      throw new Error('Expected a string value');
+    }
+    expect(argValueNode.value).to.equal('Has a \u0A0A multi-byte character.');
   });
 
   it('parses kitchen sink', () => {
@@ -259,6 +273,7 @@ describe('Parser', () => {
         {
           kind: Kind.OPERATION_DEFINITION,
           loc: { start: 0, end: 40 },
+          description: undefined,
           operation: 'query',
           name: undefined,
           variableDefinitions: [],
@@ -335,6 +350,7 @@ describe('Parser', () => {
 
   it('creates ast from nameless query without variables', () => {
     const result = parse(dedent`
+      "Query description"
       query {
         node {
           id
@@ -344,41 +360,47 @@ describe('Parser', () => {
 
     expectJSON(result).toDeepEqual({
       kind: Kind.DOCUMENT,
-      loc: { start: 0, end: 29 },
+      loc: { start: 0, end: 49 },
       definitions: [
         {
           kind: Kind.OPERATION_DEFINITION,
-          loc: { start: 0, end: 29 },
+          loc: { start: 0, end: 49 },
+          description: {
+            kind: Kind.STRING,
+            loc: { start: 0, end: 19 },
+            block: false,
+            value: 'Query description',
+          },
           operation: 'query',
           name: undefined,
           variableDefinitions: [],
           directives: [],
           selectionSet: {
             kind: Kind.SELECTION_SET,
-            loc: { start: 6, end: 29 },
+            loc: { start: 26, end: 49 },
             selections: [
               {
                 kind: Kind.FIELD,
-                loc: { start: 10, end: 27 },
+                loc: { start: 30, end: 47 },
                 alias: undefined,
                 name: {
                   kind: Kind.NAME,
-                  loc: { start: 10, end: 14 },
+                  loc: { start: 30, end: 34 },
                   value: 'node',
                 },
                 arguments: [],
                 directives: [],
                 selectionSet: {
                   kind: Kind.SELECTION_SET,
-                  loc: { start: 15, end: 27 },
+                  loc: { start: 35, end: 47 },
                   selections: [
                     {
                       kind: Kind.FIELD,
-                      loc: { start: 21, end: 23 },
+                      loc: { start: 41, end: 43 },
                       alias: undefined,
                       name: {
                         kind: Kind.NAME,
-                        loc: { start: 21, end: 23 },
+                        loc: { start: 41, end: 43 },
                         value: 'id',
                       },
                       arguments: [],
@@ -657,4 +679,93 @@ describe('Parser', () => {
       });
     });
   });
+
+  describe('operation and variable definition descriptions', () => {
+    it('parses operation with description and variable descriptions', () => {
+      const result = parse(dedent`
+        "Operation description"
+        query myQuery(
+          "Variable a description"
+          $a: Int,
+          """Variable b\nmultiline description"""
+          $b: String
+        ) {
+          field(a: $a, b: $b)
+        }
+      `);
+      // Find the operation definition
+      const opDef = result.definitions.find(
+        (d) => d.kind === Kind.OPERATION_DEFINITION,
+      );
+      if (!opDef || opDef.kind !== Kind.OPERATION_DEFINITION) {
+        throw new Error('No operation definition found');
+      }
+      expect(opDef.description?.value).to.equal('Operation description');
+      expect(opDef.name?.value).to.equal('myQuery');
+      expect(opDef.variableDefinitions?.[0].description?.value).to.equal(
+        'Variable a description',
+      );
+      expect(opDef.variableDefinitions?.[0].description?.block).to.equal(false);
+      expect(opDef.variableDefinitions?.[1].description?.value).to.equal(
+        'Variable b\nmultiline description',
+      );
+      expect(opDef.variableDefinitions?.[1].description?.block).to.equal(true);
+      expect(opDef.variableDefinitions?.[0].variable.name.value).to.equal('a');
+      expect(opDef.variableDefinitions?.[1].variable.name.value).to.equal('b');
+      // Check type names safely
+      const typeA = opDef.variableDefinitions?.[0].type;
+      if (typeA && typeA.kind === Kind.NAMED_TYPE) {
+        expect(typeA.name.value).to.equal('Int');
+      }
+      const typeB = opDef.variableDefinitions?.[1].type;
+      if (typeB && typeB.kind === Kind.NAMED_TYPE) {
+        expect(typeB.name.value).to.equal('String');
+      }
+    });
+
+    it('parses variable definition with description, default value, and directives', () => {
+      const result = parse(dedent`
+        query (
+          "desc"
+          $foo: Int = 42 @dir
+        ) {
+          field(foo: $foo)
+        }
+      `);
+      const opDef = result.definitions.find(
+        (d) => d.kind === Kind.OPERATION_DEFINITION,
+      );
+      if (!opDef || opDef.kind !== Kind.OPERATION_DEFINITION) {
+        throw new Error('No operation definition found');
+      }
+      const varDef = opDef.variableDefinitions?.[0];
+      expect(varDef?.description?.value).to.equal('desc');
+      expect(varDef?.variable.name.value).to.equal('foo');
+      if (varDef?.type.kind === Kind.NAMED_TYPE) {
+        expect(varDef.type.name.value).to.equal('Int');
+      }
+      if (varDef?.defaultValue && 'value' in varDef.defaultValue) {
+        expect(varDef.defaultValue.value).to.equal('42');
+      }
+      expect(varDef?.directives?.[0].name.value).to.equal('dir');
+    });
+
+    it('parses fragment with variable description (legacy)', () => {
+      const result = parse('fragment Foo("desc" $foo: Int) on Bar { baz }', {
+        allowLegacyFragmentVariables: true,
+      });
+      const fragDef = result.definitions.find(
+        (d) => d.kind === Kind.FRAGMENT_DEFINITION,
+      );
+      if (!fragDef || fragDef.kind !== Kind.FRAGMENT_DEFINITION) {
+        throw new Error('No fragment definition found');
+      }
+      const varDef = fragDef.variableDefinitions?.[0];
+      expect(varDef?.description?.value).to.equal('desc');
+      expect(varDef?.variable.name.value).to.equal('foo');
+      if (varDef?.type.kind === Kind.NAMED_TYPE) {
+        expect(varDef.type.name.value).to.equal('Int');
+      }
+    });
+  });
 });

src/language/__tests__/printer-test.ts

@@ -44,19 +44,21 @@ describe('Printer: Query document', () => {
     `);
 
     const queryASTWithArtifacts = parse(
-      'query ($foo: TestType) @testDirective { id, name }',
+      '"Query description" query ($foo: TestType) @testDirective { id, name }',
     );
     expect(print(queryASTWithArtifacts)).to.equal(dedent`
+      "Query description"
       query ($foo: TestType) @testDirective {
         id
         name
       }
     `);
 
     const mutationASTWithArtifacts = parse(
-      'mutation ($foo: TestType) @testDirective { id, name }',
+      '"Mutation description" mutation ($foo: TestType) @testDirective { id, name }',
     );
     expect(print(mutationASTWithArtifacts)).to.equal(dedent`
+      "Mutation description"
       mutation ($foo: TestType) @testDirective {
         id
         name
@@ -66,10 +68,13 @@ describe('Printer: Query document', () => {
 
   it('prints query with variable directives', () => {
     const queryASTWithVariableDirective = parse(
-      'query ($foo: TestType = {a: 123} @testDirective(if: true) @test) { id }',
+      'query ("Variable description" $foo: TestType = {a: 123} @testDirective(if: true) @test) { id }',
     );
     expect(print(queryASTWithVariableDirective)).to.equal(dedent`
-      query ($foo: TestType = {a: 123} @testDirective(if: true) @test) {
+      query (
+      "Variable description"
+      $foo: TestType = {a: 123} @testDirective(if: true) @test
+      ) {
         id
       }
     `);
@@ -110,6 +115,19 @@ describe('Printer: Query document', () => {
     `);
   });
 
+  it('prints fragment', () => {
+    const printed = print(
+      parse('"Fragment description" fragment Foo on Bar { baz }'),
+    );
+
+    expect(printed).to.equal(dedent`
+      "Fragment description"
+      fragment Foo on Bar {
+        baz
+      }
+    `);
+  });
+
   it('Legacy: prints fragment with variable directives', () => {
     const queryASTWithVariableDirective = parse(
       'fragment Foo($foo: TestType @test) on TestType @testDirective { id }',
@@ -150,7 +168,12 @@ describe('Printer: Query document', () => {
 
     expect(printed).to.equal(
       dedentString(String.raw`
-      query queryName($foo: ComplexType, $site: Site = MOBILE) @onQuery {
+      "Query description"
+      query queryName(
+      "Very complex variable"
+      $foo: ComplexType
+      $site: Site = MOBILE
+      ) @onQuery {
         whoever123is: node(id: [123, 456]) {
           id
           ... on User @onInlineFragment {
@@ -192,6 +215,7 @@ describe('Printer: Query document', () => {
         }
       }
 
+      """Fragment description"""
       fragment frag on Friend @onFragmentDefinition {
         foo(
           size: $size

src/language/__tests__/schema-parser-test.ts

@@ -331,7 +331,7 @@ describe('Schema Parser', () => {
       }
     `).to.deep.equal({
       message:
-        'Syntax Error: Unexpected description, descriptions are supported only on type definitions.',
+        'Syntax Error: Unexpected description, descriptions are not supported on type extensions.',
       locations: [{ line: 2, column: 7 }],
     });
 
@@ -353,7 +353,7 @@ describe('Schema Parser', () => {
       }
     `).to.deep.equal({
       message:
-        'Syntax Error: Unexpected description, descriptions are supported only on type definitions.',
+        'Syntax Error: Unexpected description, descriptions are not supported on type extensions.',
       locations: [{ line: 2, column: 7 }],
     });
 

src/language/__tests__/visitor-test.ts

@@ -539,9 +539,13 @@ describe('Visitor', () => {
     expect(visited).to.deep.equal([
       ['enter', 'Document', undefined, undefined],
       ['enter', 'OperationDefinition', 0, undefined],
+      ['enter', 'StringValue', 'description', 'OperationDefinition'],
+      ['leave', 'StringValue', 'description', 'OperationDefinition'],
       ['enter', 'Name', 'name', 'OperationDefinition'],
       ['leave', 'Name', 'name', 'OperationDefinition'],
       ['enter', 'VariableDefinition', 0, undefined],
+      ['enter', 'StringValue', 'description', 'VariableDefinition'],
+      ['leave', 'StringValue', 'description', 'VariableDefinition'],
       ['enter', 'Variable', 'variable', 'VariableDefinition'],
       ['enter', 'Name', 'name', 'Variable'],
       ['leave', 'Name', 'name', 'Variable'],
@@ -793,6 +797,8 @@ describe('Visitor', () => {
       ['leave', 'SelectionSet', 'selectionSet', 'OperationDefinition'],
       ['leave', 'OperationDefinition', 2, undefined],
       ['enter', 'FragmentDefinition', 3, undefined],
+      ['enter', 'StringValue', 'description', 'FragmentDefinition'],
+      ['leave', 'StringValue', 'description', 'FragmentDefinition'],
       ['enter', 'Name', 'name', 'FragmentDefinition'],
       ['leave', 'Name', 'name', 'FragmentDefinition'],
       ['enter', 'NamedType', 'typeCondition', 'FragmentDefinition'],

src/language/ast.ts

@@ -198,12 +198,19 @@ export const QueryDocumentKeys: {
 
   Document: ['definitions'],
   OperationDefinition: [
+    'description',
     'name',
     'variableDefinitions',
     'directives',
     'selectionSet',
   ],
-  VariableDefinition: ['variable', 'type', 'defaultValue', 'directives'],
+  VariableDefinition: [
+    'description',
+    'variable',
+    'type',
+    'defaultValue',
+    'directives',
+  ],
   Variable: ['name'],
   SelectionSet: ['selections'],
   Field: ['alias', 'name', 'arguments', 'directives', 'selectionSet'],
@@ -212,6 +219,7 @@ export const QueryDocumentKeys: {
   FragmentSpread: ['name', 'directives'],
   InlineFragment: ['typeCondition', 'directives', 'selectionSet'],
   FragmentDefinition: [
+    'description',
     'name',
     // Note: fragment variable definitions are deprecated and will removed in v17.0.0
     'variableDefinitions',
@@ -317,6 +325,7 @@ export type ExecutableDefinitionNode =
 export interface OperationDefinitionNode {
   readonly kind: Kind.OPERATION_DEFINITION;
   readonly loc?: Location;
+  readonly description?: StringValueNode;
   readonly operation: OperationTypeNode;
   readonly name?: NameNode;
   readonly variableDefinitions?: ReadonlyArray<VariableDefinitionNode>;
@@ -334,6 +343,7 @@ export { OperationTypeNode };
 export interface VariableDefinitionNode {
   readonly kind: Kind.VARIABLE_DEFINITION;
   readonly loc?: Location;
+  readonly description?: StringValueNode;
   readonly variable: VariableNode;
   readonly type: TypeNode;
   readonly defaultValue?: ConstValueNode;
@@ -398,6 +408,7 @@ export interface InlineFragmentNode {
 export interface FragmentDefinitionNode {
   readonly kind: Kind.FRAGMENT_DEFINITION;
   readonly loc?: Location;
+  readonly description?: StringValueNode;
   readonly name: NameNode;
   /** @deprecated variableDefinitions will be removed in v17.0.0 */
   readonly variableDefinitions?: ReadonlyArray<VariableDefinitionNode>;