Schema Coordinates

Implements graphql/graphql-spec#794

Adds:

* DOT punctuator in lexer
* Improvements to lexer errors around misuse of `.`
* Minor improvement to parser core which simplified this addition
* `SchemaCoordinate` node and `isSchemaCoodinate()` predicate
* Support in `print()` and `visit()`
* Added function `parseSchemaCoordinate()` since it is a parser entry point.
* Added function `resolveSchemaCoordinate()` and `resolveASTSchemaCoordinate()` which implement the semantics (name mirrored from `buildASTSchema`) as well as the return type `GraphQLSchemaElement`

src/index.ts

@@ -201,6 +201,7 @@ export {
   parseValue,
   parseConstValue,
   parseType,
+  parseSchemaCoordinate,
   /** Print */
   print,
   /** Visit */
@@ -221,6 +222,7 @@ export {
   isTypeDefinitionNode,
   isTypeSystemExtensionNode,
   isTypeExtensionNode,
+  isSchemaCoordinateNode,
 } from './language/index';
 
 export type {
@@ -295,6 +297,7 @@ export type {
   UnionTypeExtensionNode,
   EnumTypeExtensionNode,
   InputObjectTypeExtensionNode,
+  SchemaCoordinateNode,
 } from './language/index';
 
 /** Execute GraphQL queries. */
@@ -436,6 +439,8 @@ export {
   DangerousChangeType,
   findBreakingChanges,
   findDangerousChanges,
+  resolveSchemaCoordinate,
+  resolveASTSchemaCoordinate,
 } from './utilities/index';
 
 export type {
@@ -465,4 +470,5 @@ export type {
   BreakingChange,
   DangerousChange,
   TypedQueryDocumentNode,
+  GraphQLSchemaElement,
 } from './utilities/index';

src/language/__tests__/lexer-test.ts

@@ -657,7 +657,8 @@ describe('Lexer', () => {
     });
 
     expectSyntaxError('.123').to.deep.equal({
-      message: 'Syntax Error: Unexpected character: ".".',
+      message:
+        'Syntax Error: Invalid number, expected digit before ".", did you mean "0.123"?',
       locations: [{ line: 1, column: 1 }],
     });
 
@@ -762,6 +763,13 @@ describe('Lexer', () => {
       value: undefined,
     });
 
+    expect(lexOne('.')).to.contain({
+      kind: TokenKind.DOT,
+      start: 0,
+      end: 1,
+      value: undefined,
+    });
+
     expect(lexOne('...')).to.contain({
       kind: TokenKind.SPREAD,
       start: 0,
@@ -828,7 +836,7 @@ describe('Lexer', () => {
 
   it('lex reports useful unknown character error', () => {
     expectSyntaxError('..').to.deep.equal({
-      message: 'Syntax Error: Unexpected character: ".".',
+      message: 'Syntax Error: Unexpected "..", did you mean "..."?',
       locations: [{ line: 1, column: 1 }],
     });
 

src/language/__tests__/parser-test.ts

@@ -9,7 +9,13 @@ import { inspect } from '../../jsutils/inspect';
 import { Kind } from '../kinds';
 import { Source } from '../source';
 import { TokenKind } from '../tokenKind';
-import { parse, parseValue, parseConstValue, parseType } from '../parser';
+import {
+  parse,
+  parseValue,
+  parseConstValue,
+  parseType,
+  parseSchemaCoordinate,
+} from '../parser';
 
 import { toJSONDeep } from './toJSONDeep';
 
@@ -619,4 +625,129 @@ describe('Parser', () => {
       });
     });
   });
+
+  describe('parseSchemaCoordinate', () => {
+    it('parses Name', () => {
+      const result = parseSchemaCoordinate('MyType');
+      expect(toJSONDeep(result)).to.deep.equal({
+        kind: Kind.SCHEMA_COORDINATE,
+        loc: { start: 0, end: 6 },
+        isDirective: false,
+        name: {
+          kind: Kind.NAME,
+          loc: { start: 0, end: 6 },
+          value: 'MyType',
+        },
+        memberName: undefined,
+        argumentName: undefined,
+      });
+    });
+
+    it('parses Name . Name', () => {
+      const result = parseSchemaCoordinate('MyType.field');
+      expect(toJSONDeep(result)).to.deep.equal({
+        kind: Kind.SCHEMA_COORDINATE,
+        loc: { start: 0, end: 12 },
+        isDirective: false,
+        name: {
+          kind: Kind.NAME,
+          loc: { start: 0, end: 6 },
+          value: 'MyType',
+        },
+        memberName: {
+          kind: Kind.NAME,
+          loc: { start: 7, end: 12 },
+          value: 'field',
+        },
+        argumentName: undefined,
+      });
+    });
+
+    it('rejects Name . Name . Name', () => {
+      expect(() => parseSchemaCoordinate('MyType.field.deep'))
+        .to.throw()
+        .to.deep.equal({
+          message: 'Syntax Error: Expected <EOF>, found ".".',
+          locations: [{ line: 1, column: 13 }],
+        });
+    });
+
+    it('parses Name . Name ( Name : )', () => {
+      const result = parseSchemaCoordinate('MyType.field(arg:)');
+      expect(toJSONDeep(result)).to.deep.equal({
+        kind: Kind.SCHEMA_COORDINATE,
+        loc: { start: 0, end: 18 },
+        isDirective: false,
+        name: {
+          kind: Kind.NAME,
+          loc: { start: 0, end: 6 },
+          value: 'MyType',
+        },
+        memberName: {
+          kind: Kind.NAME,
+          loc: { start: 7, end: 12 },
+          value: 'field',
+        },
+        argumentName: {
+          kind: Kind.NAME,
+          loc: { start: 13, end: 16 },
+          value: 'arg',
+        },
+      });
+    });
+
+    it('rejects Name . Name ( Name : Name )', () => {
+      expect(() => parseSchemaCoordinate('MyType.field(arg: value)'))
+        .to.throw()
+        .to.deep.equal({
+          message: 'Syntax Error: Expected ")", found Name "value".',
+          locations: [{ line: 1, column: 19 }],
+        });
+    });
+
+    it('parses @ Name', () => {
+      const result = parseSchemaCoordinate('@myDirective');
+      expect(toJSONDeep(result)).to.deep.equal({
+        kind: Kind.SCHEMA_COORDINATE,
+        loc: { start: 0, end: 12 },
+        isDirective: true,
+        name: {
+          kind: Kind.NAME,
+          loc: { start: 1, end: 12 },
+          value: 'myDirective',
+        },
+        memberName: undefined,
+        argumentName: undefined,
+      });
+    });
+
+    it('parses @ Name ( Name : )', () => {
+      const result = parseSchemaCoordinate('@myDirective(arg:)');
+      expect(toJSONDeep(result)).to.deep.equal({
+        kind: Kind.SCHEMA_COORDINATE,
+        loc: { start: 0, end: 18 },
+        isDirective: true,
+        name: {
+          kind: Kind.NAME,
+          loc: { start: 1, end: 12 },
+          value: 'myDirective',
+        },
+        memberName: undefined,
+        argumentName: {
+          kind: Kind.NAME,
+          loc: { start: 13, end: 16 },
+          value: 'arg',
+        },
+      });
+    });
+
+    it('rejects @ Name . Name', () => {
+      expect(() => parseSchemaCoordinate('@myDirective.field'))
+        .to.throw()
+        .to.deep.equal({
+          message: 'Syntax Error: Expected <EOF>, found ".".',
+          locations: [{ line: 1, column: 13 }],
+        });
+    });
+  });
 });

src/language/__tests__/predicates-test.ts

@@ -15,6 +15,7 @@ import {
   isTypeDefinitionNode,
   isTypeSystemExtensionNode,
   isTypeExtensionNode,
+  isSchemaCoordinateNode,
 } from '../predicates';
 
 function filterNodes(predicate: (node: ASTNode) => boolean): Array<string> {
@@ -141,4 +142,10 @@ describe('AST node predicates', () => {
       'InputObjectTypeExtension',
     ]);
   });
+
+  it('isSchemaCoordinateNode', () => {
+    expect(filterNodes(isSchemaCoordinateNode)).to.deep.equal([
+      'SchemaCoordinate',
+    ]);
+  });
 });

src/language/__tests__/printer-test.ts

@@ -3,8 +3,8 @@ import { describe, it } from 'mocha';
 
 import { dedent, dedentString } from '../../__testUtils__/dedent';
 import { kitchenSinkQuery } from '../../__testUtils__/kitchenSinkQuery';
+import { parseSchemaCoordinate, parse } from '../parser';
 
-import { parse } from '../parser';
 import { print } from '../printer';
 
 describe('Printer: Query document', () => {
@@ -216,4 +216,18 @@ describe('Printer: Query document', () => {
     `),
     );
   });
+
+  it('prints schema coordinates', () => {
+    expect(print(parseSchemaCoordinate('  Name  '))).to.equal('Name');
+    expect(print(parseSchemaCoordinate('  Name . field '))).to.equal(
+      'Name.field',
+    );
+    expect(print(parseSchemaCoordinate('  Name . field ( arg: )'))).to.equal(
+      'Name.field(arg:)',
+    );
+    expect(print(parseSchemaCoordinate(' @ name  '))).to.equal('@name');
+    expect(print(parseSchemaCoordinate(' @ name (arg:) '))).to.equal(
+      '@name(arg:)',
+    );
+  });
 });

src/language/ast.ts

@@ -176,7 +176,8 @@ export type ASTNode =
   | InterfaceTypeExtensionNode
   | UnionTypeExtensionNode
   | EnumTypeExtensionNode
-  | InputObjectTypeExtensionNode;
+  | InputObjectTypeExtensionNode
+  | SchemaCoordinateNode;
 
 /**
  * Utility type listing all nodes indexed by their kind.
@@ -225,6 +226,7 @@ export interface ASTKindToNode {
   UnionTypeExtension: UnionTypeExtensionNode;
   EnumTypeExtension: EnumTypeExtensionNode;
   InputObjectTypeExtension: InputObjectTypeExtensionNode;
+  SchemaCoordinate: SchemaCoordinateNode;
 }
 
 /** Name */
@@ -670,3 +672,14 @@ export interface InputObjectTypeExtensionNode {
   readonly directives?: ReadonlyArray<ConstDirectiveNode>;
   readonly fields?: ReadonlyArray<InputValueDefinitionNode>;
 }
+
+// Schema Coordinates
+
+export interface SchemaCoordinateNode {
+  readonly kind: 'SchemaCoordinate';
+  readonly loc?: Location;
+  readonly isDirective: boolean;
+  readonly name: NameNode;
+  readonly memberName?: NameNode;
+  readonly argumentName?: NameNode;
+}

src/language/index.ts

@@ -13,7 +13,13 @@ export type { TokenKindEnum } from './tokenKind';
 
 export { Lexer } from './lexer';
 
-export { parse, parseValue, parseConstValue, parseType } from './parser';
+export {
+  parse,
+  parseValue,
+  parseConstValue,
+  parseType,
+  parseSchemaCoordinate,
+} from './parser';
 export type { ParseOptions } from './parser';
 
 export { print } from './printer';
@@ -85,6 +91,7 @@ export type {
   UnionTypeExtensionNode,
   EnumTypeExtensionNode,
   InputObjectTypeExtensionNode,
+  SchemaCoordinateNode,
 } from './ast';
 
 export {
@@ -98,6 +105,7 @@ export {
   isTypeDefinitionNode,
   isTypeSystemExtensionNode,
   isTypeExtensionNode,
+  isSchemaCoordinateNode,
 } from './predicates';
 
 export { DirectiveLocation } from './directiveLocation';

src/language/kinds.ts

@@ -66,6 +66,9 @@ export const Kind = Object.freeze({
   UNION_TYPE_EXTENSION: 'UnionTypeExtension',
   ENUM_TYPE_EXTENSION: 'EnumTypeExtension',
   INPUT_OBJECT_TYPE_EXTENSION: 'InputObjectTypeExtension',
+
+  /** Schema Coordinates */
+  SCHEMA_COORDINATE: 'SchemaCoordinate',
 } as const);
 
 /**