Add descriptions to executable definitions

Implements graphql/graphql-spec#892

Author: IvanGoncharov

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

@@ -241,6 +241,7 @@ describe('Parser', () => {
         {
           kind: Kind.OPERATION_DEFINITION,
           loc: { start: 0, end: 40 },
+          description: undefined,
           operation: 'query',
           name: undefined,
           variableDefinitions: [],
@@ -317,6 +318,7 @@ describe('Parser', () => {
 
   it('creates ast from nameless query without variables', () => {
     const result = parse(dedent`
+      "Query description"
       query {
         node {
           id
@@ -326,41 +328,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: [],

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',
@@ -316,6 +324,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>;
@@ -332,6 +341,7 @@ export enum OperationTypeNode {
 export interface VariableDefinitionNode {
   readonly kind: Kind.VARIABLE_DEFINITION;
   readonly loc?: Location;
+  readonly description?: StringValueNode;
   readonly variable: VariableNode;
   readonly type: TypeNode;
   readonly defaultValue?: ConstValueNode;
@@ -396,6 +406,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>;

src/language/parser.ts

@@ -250,6 +250,12 @@ export class Parser {
 
     if (keywordToken.kind === TokenKind.NAME) {
       switch (keywordToken.value) {
+        case 'query':
+        case 'mutation':
+        case 'subscription':
+          return this.parseOperationDefinition();
+        case 'fragment':
+          return this.parseFragmentDefinition();
         case 'schema':
           return this.parseSchemaDefinition();
         case 'scalar':
@@ -266,24 +272,14 @@ export class Parser {
           return this.parseInputObjectTypeDefinition();
         case 'directive':
           return this.parseDirectiveDefinition();
-      }
-
-      if (hasDescription) {
-        throw syntaxError(
-          this._lexer.source,
-          this._lexer.token.start,
-          'Unexpected description, descriptions are supported only on type definitions.',
-        );
-      }
-
-      switch (keywordToken.value) {
-        case 'query':
-        case 'mutation':
-        case 'subscription':
-          return this.parseOperationDefinition();
-        case 'fragment':
-          return this.parseFragmentDefinition();
         case 'extend':
+          if (hasDescription) {
+            throw syntaxError(
+              this._lexer.source,
+              this._lexer.token.start,
+              'Unexpected description, descriptions are not supported on type extensions.',
+            );
+          }
           return this.parseTypeSystemExtension();
       }
     }
@@ -300,23 +296,28 @@ export class Parser {
    */
   parseOperationDefinition(): OperationDefinitionNode {
     const start = this._lexer.token;
+
     if (this.peek(TokenKind.BRACE_L)) {
       return this.node<OperationDefinitionNode>(start, {
         kind: Kind.OPERATION_DEFINITION,
+        description: undefined,
         operation: OperationTypeNode.QUERY,
         name: undefined,
         variableDefinitions: [],
         directives: [],
         selectionSet: this.parseSelectionSet(),
       });
     }
+
+    const description = this.parseDescription();
     const operation = this.parseOperationType();
     let name;
     if (this.peek(TokenKind.NAME)) {
       name = this.parseName();
     }
     return this.node<OperationDefinitionNode>(start, {
       kind: Kind.OPERATION_DEFINITION,
+      description,
       operation,
       name,
       variableDefinitions: this.parseVariableDefinitions(),
@@ -359,6 +360,7 @@ export class Parser {
   parseVariableDefinition(): VariableDefinitionNode {
     return this.node<VariableDefinitionNode>(this._lexer.token, {
       kind: Kind.VARIABLE_DEFINITION,
+      description: this.parseDescription(),
       variable: this.parseVariable(),
       type: (this.expectToken(TokenKind.COLON), this.parseTypeReference()),
       defaultValue: this.expectOptionalToken(TokenKind.EQUALS)
@@ -506,13 +508,15 @@ export class Parser {
    */
   parseFragmentDefinition(): FragmentDefinitionNode {
     const start = this._lexer.token;
+    const description = this.parseDescription();
     this.expectKeyword('fragment');
     // Legacy support for defining variables within fragments changes
     // the grammar of FragmentDefinition:
     //   - fragment FragmentName VariableDefinitions? on TypeCondition Directives? SelectionSet
     if (this._options?.allowLegacyFragmentVariables === true) {
       return this.node<FragmentDefinitionNode>(start, {
         kind: Kind.FRAGMENT_DEFINITION,
+        description,
         name: this.parseFragmentName(),
         variableDefinitions: this.parseVariableDefinitions(),
         typeCondition: (this.expectKeyword('on'), this.parseNamedType()),
@@ -522,6 +526,7 @@ export class Parser {
     }
     return this.node<FragmentDefinitionNode>(start, {
       kind: Kind.FRAGMENT_DEFINITION,
+      description,
       name: this.parseFragmentName(),
       typeCondition: (this.expectKeyword('on'), this.parseNamedType()),
       directives: this.parseDirectives(false),