Schema Coordinates

src/index.ts

@@ -230,12 +230,14 @@ export {
   printSourceLocation,
   // Lex
   Lexer,
+  SchemaCoordinateLexer,
   TokenKind,
   // Parse
   parse,
   parseValue,
   parseConstValue,
   parseType,
+  parseSchemaCoordinate,
   // Print
   print,
   // Visit
@@ -255,10 +257,12 @@ export {
   isTypeDefinitionNode,
   isTypeSystemExtensionNode,
   isTypeExtensionNode,
+  isSchemaCoordinateNode,
 } from './language/index.js';
 
 export type {
   ParseOptions,
+  ParseSchemaCoordinateOptions,
   SourceLocation,
   // Visitor utilities
   ASTVisitor,
@@ -327,6 +331,7 @@ export type {
   UnionTypeExtensionNode,
   EnumTypeExtensionNode,
   InputObjectTypeExtensionNode,
+  SchemaCoordinateNode,
 } from './language/index.js';
 
 // Execute GraphQL queries.
@@ -496,6 +501,8 @@ export {
   findBreakingChanges,
   findDangerousChanges,
   findSchemaChanges,
+  resolveSchemaCoordinate,
+  resolveASTSchemaCoordinate,
 } from './utilities/index.js';
 
 export type {
@@ -526,4 +533,5 @@ export type {
   SafeChange,
   DangerousChange,
   TypedQueryDocumentNode,
+  ResolvedSchemaElement,
 } from './utilities/index.js';

src/language/__tests__/lexer-test.ts

@@ -9,7 +9,11 @@ import { inspect } from '../../jsutils/inspect.js';
 import { GraphQLError } from '../../error/GraphQLError.js';
 
 import type { Token } from '../ast.js';
-import { isPunctuatorTokenKind, Lexer } from '../lexer.js';
+import {
+  isPunctuatorTokenKind,
+  Lexer,
+  SchemaCoordinateLexer,
+} from '../lexer.js';
 import { Source } from '../source.js';
 import { TokenKind } from '../tokenKind.js';
 
@@ -166,8 +170,8 @@ describe('Lexer', () => {
   });
 
   it('reports unexpected characters', () => {
-    expectSyntaxError('.').to.deep.equal({
-      message: 'Syntax Error: Unexpected character: ".".',
+    expectSyntaxError('^').to.deep.equal({
+      message: 'Syntax Error: Unexpected character: "^".',
       locations: [{ line: 1, column: 1 }],
     });
   });
@@ -965,6 +969,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,
@@ -1182,6 +1193,33 @@ describe('Lexer', () => {
   });
 });
 
+describe('SchemaCoordinateLexer', () => {
+  it('can be stringified', () => {
+    const lexer = new SchemaCoordinateLexer(new Source('Name.field'));
+    expect(Object.prototype.toString.call(lexer)).to.equal(
+      '[object SchemaCoordinateLexer]',
+    );
+  });
+
+  it('tracks a schema coordinate', () => {
+    const lexer = new SchemaCoordinateLexer(new Source('Name.field'));
+    expect(lexer.advance()).to.contain({
+      kind: TokenKind.NAME,
+      start: 0,
+      end: 4,
+      value: 'Name',
+    });
+  });
+
+  it('forbids ignored tokens', () => {
+    const lexer = new SchemaCoordinateLexer(new Source('\nName.field'));
+    expectToThrowJSON(() => lexer.advance()).to.deep.equal({
+      message: 'Syntax Error: Invalid character: U+000A.',
+      locations: [{ line: 1, column: 1 }],
+    });
+  });
+});
+
 describe('isPunctuatorTokenKind', () => {
   function isPunctuatorToken(text: string) {
     return isPunctuatorTokenKind(lexOne(text).kind);

src/language/__tests__/parser-test.ts

@@ -11,7 +11,13 @@ import { kitchenSinkQuery } from '../../__testUtils__/kitchenSinkQuery.js';
 import { inspect } from '../../jsutils/inspect.js';
 
 import { Kind } from '../kinds.js';
-import { parse, parseConstValue, parseType, parseValue } from '../parser.js';
+import {
+  parse,
+  parseConstValue,
+  parseSchemaCoordinate,
+  parseType,
+  parseValue,
+} from '../parser.js';
 import { Source } from '../source.js';
 import { TokenKind } from '../tokenKind.js';
 
@@ -679,4 +685,118 @@ describe('Parser', () => {
       });
     });
   });
+
+  describe('parseSchemaCoordinate', () => {
+    it('parses Name', () => {
+      const result = parseSchemaCoordinate('MyType');
+      expectJSON(result).toDeepEqual({
+        kind: Kind.TYPE_COORDINATE,
+        loc: { start: 0, end: 6 },
+        name: {
+          kind: Kind.NAME,
+          loc: { start: 0, end: 6 },
+          value: 'MyType',
+        },
+      });
+    });
+
+    it('parses Name . Name', () => {
+      const result = parseSchemaCoordinate('MyType.field');
+      expectJSON(result).toDeepEqual({
+        kind: Kind.MEMBER_COORDINATE,
+        loc: { start: 0, end: 12 },
+        name: {
+          kind: Kind.NAME,
+          loc: { start: 0, end: 6 },
+          value: 'MyType',
+        },
+        memberName: {
+          kind: Kind.NAME,
+          loc: { start: 7, end: 12 },
+          value: 'field',
+        },
+      });
+    });
+
+    it('rejects Name . Name . Name', () => {
+      expect(() => parseSchemaCoordinate('MyType.field.deep'))
+        .to.throw()
+        .to.deep.include({
+          message: 'Syntax Error: Expected <EOF>, found ".".',
+          locations: [{ line: 1, column: 13 }],
+        });
+    });
+
+    it('parses Name . Name ( Name : )', () => {
+      const result = parseSchemaCoordinate('MyType.field(arg:)');
+      expectJSON(result).toDeepEqual({
+        kind: Kind.ARGUMENT_COORDINATE,
+        loc: { start: 0, end: 18 },
+        name: {
+          kind: Kind.NAME,
+          loc: { start: 0, end: 6 },
+          value: 'MyType',
+        },
+        fieldName: {
+          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.include({
+          message: 'Syntax Error: Expected ")", found Name "value".',
+          locations: [{ line: 1, column: 18 }],
+        });
+    });
+
+    it('parses @ Name', () => {
+      const result = parseSchemaCoordinate('@myDirective');
+      expectJSON(result).toDeepEqual({
+        kind: Kind.DIRECTIVE_COORDINATE,
+        loc: { start: 0, end: 12 },
+        name: {
+          kind: Kind.NAME,
+          loc: { start: 1, end: 12 },
+          value: 'myDirective',
+        },
+      });
+    });
+
+    it('parses @ Name ( Name : )', () => {
+      const result = parseSchemaCoordinate('@myDirective(arg:)');
+      expectJSON(result).toDeepEqual({
+        kind: Kind.DIRECTIVE_ARGUMENT_COORDINATE,
+        loc: { start: 0, end: 18 },
+        name: {
+          kind: Kind.NAME,
+          loc: { start: 1, end: 12 },
+          value: 'myDirective',
+        },
+        argumentName: {
+          kind: Kind.NAME,
+          loc: { start: 13, end: 16 },
+          value: 'arg',
+        },
+      });
+    });
+
+    it('rejects @ Name . Name', () => {
+      expect(() => parseSchemaCoordinate('@myDirective.field'))
+        .to.throw()
+        .to.deep.include({
+          message: 'Syntax Error: Expected <EOF>, found ".".',
+          locations: [{ line: 1, column: 13 }],
+        });
+    });
+  });
 });

src/language/__tests__/predicates-test.ts

@@ -8,6 +8,7 @@ import {
   isConstValueNode,
   isDefinitionNode,
   isExecutableDefinitionNode,
+  isSchemaCoordinateNode,
   isSelectionNode,
   isTypeDefinitionNode,
   isTypeExtensionNode,
@@ -141,4 +142,14 @@ describe('AST node predicates', () => {
       'UnionTypeExtension',
     ]);
   });
+
+  it('isSchemaCoordinateNode', () => {
+    expect(filterNodes(isSchemaCoordinateNode)).to.deep.equal([
+      'ArgumentCoordinate',
+      'DirectiveArgumentCoordinate',
+      'DirectiveCoordinate',
+      'MemberCoordinate',
+      'TypeCoordinate',
+    ]);
+  });
 });

src/language/__tests__/printer-test.ts

@@ -5,7 +5,7 @@ import { dedent, dedentString } from '../../__testUtils__/dedent.js';
 import { kitchenSinkQuery } from '../../__testUtils__/kitchenSinkQuery.js';
 
 import { Kind } from '../kinds.js';
-import { parse } from '../parser.js';
+import { parse, parseSchemaCoordinate } from '../parser.js';
 import { print } from '../printer.js';
 
 describe('Printer: Query document', () => {
@@ -299,4 +299,26 @@ 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:)');
+  });
+
+  it('throws syntax error for ignored tokens in schema coordinates', () => {
+    expect(() => print(parseSchemaCoordinate('# foo\nName'))).to.throw(
+      'Syntax Error: Invalid character: "#"',
+    );
+    expect(() => print(parseSchemaCoordinate('\nName'))).to.throw(
+      'Syntax Error: Invalid character: U+000A.',
+    );
+    expect(() => print(parseSchemaCoordinate('Name .field'))).to.throw(
+      'Syntax Error: Invalid character: " "',
+    );
+  });
 });

src/language/ast.ts

@@ -181,7 +181,12 @@ export type ASTNode =
   | InterfaceTypeExtensionNode
   | UnionTypeExtensionNode
   | EnumTypeExtensionNode
-  | InputObjectTypeExtensionNode;
+  | InputObjectTypeExtensionNode
+  | TypeCoordinateNode
+  | MemberCoordinateNode
+  | ArgumentCoordinateNode
+  | DirectiveCoordinateNode
+  | DirectiveArgumentCoordinateNode;
 
 /**
  * Utility type listing all nodes indexed by their kind.
@@ -287,6 +292,13 @@ export const QueryDocumentKeys: {
   UnionTypeExtension: ['name', 'directives', 'types'],
   EnumTypeExtension: ['name', 'directives', 'values'],
   InputObjectTypeExtension: ['name', 'directives', 'fields'],
+
+  // Schema Coordinates
+  TypeCoordinate: ['name'],
+  MemberCoordinate: ['name', 'memberName'],
+  ArgumentCoordinate: ['name', 'fieldName', 'argumentName'],
+  DirectiveCoordinate: ['name'],
+  DirectiveArgumentCoordinate: ['name', 'argumentName'],
 };
 
 const kindValues = new Set<string>(Object.keys(QueryDocumentKeys));
@@ -762,3 +774,46 @@ export interface InputObjectTypeExtensionNode {
   readonly directives?: ReadonlyArray<ConstDirectiveNode> | undefined;
   readonly fields?: ReadonlyArray<InputValueDefinitionNode> | undefined;
 }
+
+/** Schema Coordinates */
+
+export type SchemaCoordinateNode =
+  | TypeCoordinateNode
+  | MemberCoordinateNode
+  | ArgumentCoordinateNode
+  | DirectiveCoordinateNode
+  | DirectiveArgumentCoordinateNode;
+
+export interface TypeCoordinateNode {
+  readonly kind: typeof Kind.TYPE_COORDINATE;
+  readonly loc?: Location;
+  readonly name: NameNode;
+}
+
+export interface MemberCoordinateNode {
+  readonly kind: typeof Kind.MEMBER_COORDINATE;
+  readonly loc?: Location;
+  readonly name: NameNode;
+  readonly memberName: NameNode;
+}
+
+export interface ArgumentCoordinateNode {
+  readonly kind: typeof Kind.ARGUMENT_COORDINATE;
+  readonly loc?: Location;
+  readonly name: NameNode;
+  readonly fieldName: NameNode;
+  readonly argumentName: NameNode;
+}
+
+export interface DirectiveCoordinateNode {
+  readonly kind: typeof Kind.DIRECTIVE_COORDINATE;
+  readonly loc?: Location;
+  readonly name: NameNode;
+}
+
+export interface DirectiveArgumentCoordinateNode {
+  readonly kind: typeof Kind.DIRECTIVE_ARGUMENT_COORDINATE;
+  readonly loc?: Location;
+  readonly name: NameNode;
+  readonly argumentName: NameNode;
+}