@apollo/federation-internals 2.0.0-alpha.2 → 2.0.0-alpha.6

package/src/federation.ts

@@ -18,22 +18,40 @@ import {
   baseType,
   isInterfaceType,
   isObjectType,
+  isListType,
+  isUnionType,
   sourceASTs,
   VariableDefinitions,
   InterfaceType,
   InputFieldDefinition,
   isCompositeType
 } from "./definitions";
-import { assert, OrderedMap } from "./utils";
+import { assert, joinStrings, MultiMap, OrderedMap } from "./utils";
 import { SDLValidationRule } from "graphql/validation/ValidationContext";
 import { specifiedSDLRules } from "graphql/validation/specifiedRules";
-import { ASTNode, DocumentNode, GraphQLError, KnownTypeNamesRule, parse, PossibleTypeExtensionsRule, Source } from "graphql";
+import {
+  ASTNode,
+  DocumentNode,
+  GraphQLError,
+  Kind,
+  KnownTypeNamesRule,
+  parse,
+  PossibleTypeExtensionsRule,
+  print as printAST,
+  Source,
+  DirectiveLocation,
+} from "graphql";
 import { defaultPrintOptions, printDirectiveDefinition } from "./print";
 import { KnownTypeNamesInFederationRule } from "./validation/KnownTypeNamesInFederationRule";
 import { buildSchema, buildSchemaFromAST } from "./buildSchema";
 import { parseSelectionSet, SelectionSet } from './operations';
 import { tagLocations, TAG_VERSIONS } from "./tagSpec";
-import { error } from "./error";
+import {
+  errorCodeDef,
+  ErrorCodeDefinition,
+  ERROR_CATEGORIES,
+  ERRORS,
+} from "./error";
 
 export const entityTypeName = '_Entity';
 export const serviceTypeName = '_Service';
@@ -107,22 +125,33 @@ function validateFieldSetSelections(
   for (const selection of selectionSet.selections()) {
     if (selection.kind === 'FieldSelection') {
       const field = selection.element().definition;
+      const isExternal = externalTester.isExternal(field);
+      // We collect the field as external before any other validation to avoid getting a (confusing)
+      // "external unused" error on top of another error due to exiting that method too early.
+      if (isExternal) {
+        externalFieldCoordinatesCollector.push(field.coordinate);
+      }
       if (field.hasArguments()) {
-        throw new GraphQLError(`field ${field.coordinate} cannot be included because it has arguments (fields with argument are not allowed in @${directiveName})`, field.sourceAST);
+        throw ERROR_CATEGORIES.FIELDS_HAS_ARGS.get(directiveName).err({
+          message: `field ${field.coordinate} cannot be included because it has arguments (fields with argument are not allowed in @${directiveName})`,
+          nodes: field.sourceAST
+        });
       }
       // The field must be external if we don't allow non-external leaf fields, it's a leaf, and we haven't traversed an external field in parent chain leading here.
       const mustBeExternal = !selection.selectionSet && !allowOnNonExternalLeafFields && !hasExternalInParents;
-      const isExternal = externalTester.isExternal(field);
-      if (isExternal) {
-        externalFieldCoordinatesCollector.push(field.coordinate);
-      } else if (mustBeExternal) {
+      if (!isExternal && mustBeExternal) {
+        const errorCode = ERROR_CATEGORIES.DIRECTIVE_FIELDS_MISSING_EXTERNAL.get(directiveName);
         if (externalTester.isFakeExternal(field)) {
-          throw new GraphQLError(
-            `field "${field.coordinate}" should not be part of a @${directiveName} since it is already "effectively" provided by this subgraph `
-            + `(while it is marked @${externalDirectiveName}, it is a @${keyDirectiveName} field of an extension type, which are not internally considered external for historical/backward compatibility reasons)`,
-            field.sourceAST);
+          throw errorCode.err({
+            message: `field "${field.coordinate}" should not be part of a @${directiveName} since it is already "effectively" provided by this subgraph `
+              + `(while it is marked @${externalDirectiveName}, it is a @${keyDirectiveName} field of an extension type, which are not internally considered external for historical/backward compatibility reasons)`,
+            nodes: field.sourceAST
+          });
         } else {
-          throw new GraphQLError(`field "${field.coordinate}" should not be part of a @${directiveName} since it is already provided by this subgraph (it is not marked @${externalDirectiveName})`, field.sourceAST);
+          throw errorCode.err({
+            message: `field "${field.coordinate}" should not be part of a @${directiveName} since it is already provided by this subgraph (it is not marked @${externalDirectiveName})`,
+            nodes: field.sourceAST
+          });
         }
       }
       if (selection.selectionSet) {
@@ -151,69 +180,97 @@ function validateFieldSetSelections(
 function validateFieldSet(
   type: CompositeType,
   directive: Directive<any, {fields: any}>,
-  targetDescription: string,
   externalTester: ExternalTester,
   externalFieldCoordinatesCollector: string[],
   allowOnNonExternalLeafFields: boolean,
+  onFields?: (field: FieldDefinition<any>) => void,
 ): GraphQLError | undefined {
   try {
-    const selectionSet = parseFieldSetArgument(type, directive);
-    selectionSet.validate();
-    validateFieldSetSelections(directive.name, selectionSet, false, externalTester, externalFieldCoordinatesCollector, allowOnNonExternalLeafFields);
-    return undefined;
-  } catch (e) {
-    if (!(e instanceof GraphQLError)) {
-      throw e;
-    }
-    const nodes = sourceASTs(directive);
-    if (e.nodes) {
-      nodes.push(...e.nodes);
-    }
-    let msg = e.message.trim();
-    // The rule for validating @requires in fed 1 was not properly recursive, so people upgrading
-    // may have a @require that selects some fields but without declaring those fields on the
-    // subgraph. As we fixed the validation, this will now fail, but we try here to provide some
-    // hint for those users for how to fix the problem.
-    // Note that this is a tad fragile to rely on the error message like that, but worth case, a
-    // future change make us not show the hint and that's not the end of the world.
-    if (msg.startsWith('Cannot query field')) {
-      if (msg.endsWith('.')) {
-        msg = msg.slice(0, msg.length - 1);
+    // Note that `parseFieldSetArgument` already properly format the error, hence the separate try-catch.
+    const fieldAcessor = onFields
+      ? (type: CompositeType, fieldName: string) => {
+        const field = type.field(fieldName);
+        if (field) {
+          onFields(field);
+        }
+        return field;
       }
-      if (directive.name === keyDirectiveName) {
-        msg = msg + ' (the field should be either be added to this subgraph or, if it should not be resolved by this subgraph, you need to add it to this subgraph with @external).';
-      } else {
-        msg = msg + ' (if the field is defined in another subgraph, you need to add it to this subgraph with @external).';
+      : undefined;
+    const selectionSet = parseFieldSetArgument(type, directive, fieldAcessor);
+
+    try {
+      validateFieldSetSelections(directive.name, selectionSet, false, externalTester, externalFieldCoordinatesCollector, allowOnNonExternalLeafFields);
+      return undefined;
+    } catch (e) {
+      if (!(e instanceof GraphQLError)) {
+        throw e;
+      }
+      const nodes = sourceASTs(directive);
+      if (e.nodes) {
+        nodes.push(...e.nodes);
       }
+      const codeDef = errorCodeDef(e) ?? ERROR_CATEGORIES.DIRECTIVE_INVALID_FIELDS.get(directive.name);
+      return codeDef.err({
+        message: `${fieldSetErrorDescriptor(directive)}: ${e.message.trim()}`,
+        nodes,
+        originalError: e,
+      });
+    }
+  } catch (e) {
+    if (e instanceof GraphQLError) {
+      return e;
+    } else {
+      throw e;
     }
-    return new GraphQLError(`On ${targetDescription}, for ${directive}: ${msg}`, nodes);
   }
 }
 
+function fieldSetErrorDescriptor(directive: Directive<any, {fields: any}>): string {
+  return `On ${fieldSetTargetDescription(directive)}, for ${directiveStrUsingASTIfPossible(directive)}`;
+}
+
+// This method is called to display @key, @provides or @requires directives in error message in place where the directive `fields`
+// argument might be invalid because it was not a string in the underlying AST. If that's the case, we want to use the AST to
+// print the directive or the message might be a bit confusing for the user.
+function directiveStrUsingASTIfPossible(directive: Directive<any>): string {
+  return directive.sourceAST ? printAST(directive.sourceAST) : directive.toString();
+}
+
+function fieldSetTargetDescription(directive: Directive<any, {fields: any}>): string {
+  const targetKind = directive.parent instanceof FieldDefinition ? "field" : "type";
+  return `${targetKind} "${directive.parent?.coordinate}"`;
+}
+
 function validateAllFieldSet<TParent extends SchemaElement<any, any>>(
   definition: DirectiveDefinition<{fields: any}>,
   targetTypeExtractor: (element: TParent) => CompositeType,
-  targetDescriptionExtractor: (element: TParent) => string,
   errorCollector: GraphQLError[],
   externalTester: ExternalTester,
   externalFieldCoordinatesCollector: string[],
   isOnParentType: boolean,
   allowOnNonExternalLeafFields: boolean,
+  onFields?: (field: FieldDefinition<any>) => void,
 ): void {
   for (const application of definition.applications()) {
     const elt = application.parent as TParent;
     const type = targetTypeExtractor(elt);
-    const targetDescription = targetDescriptionExtractor(elt);
     const parentType = isOnParentType ? type : (elt.parent as NamedType);
     if (isInterfaceType(parentType)) {
-      errorCollector.push(new GraphQLError(
-        isOnParentType
-          ? `Cannot use ${definition.coordinate} on interface ${parentType.coordinate}: ${definition.coordinate} is not yet supported on interfaces`
-          : `Cannot use ${definition.coordinate} on ${targetDescription} of parent type ${parentType}: ${definition.coordinate} is not yet supported within interfaces`,
-        sourceASTs(application).concat(isOnParentType ? [] : sourceASTs(type))
-      ));
-    }
-    const error = validateFieldSet(type, application, targetDescription, externalTester, externalFieldCoordinatesCollector, allowOnNonExternalLeafFields);
+      const code = ERROR_CATEGORIES.DIRECTIVE_UNSUPPORTED_ON_INTERFACE.get(definition.name);
+      errorCollector.push(code.err({
+        message: isOnParentType
+          ? `Cannot use ${definition.coordinate} on interface "${parentType.coordinate}": ${definition.coordinate} is not yet supported on interfaces`
+          : `Cannot use ${definition.coordinate} on ${fieldSetTargetDescription(application)} of parent type "${parentType}": ${definition.coordinate} is not yet supported within interfaces`,
+        nodes: sourceASTs(application).concat(isOnParentType ? [] : sourceASTs(type)),
+      }));
+    }
+    const error = validateFieldSet(
+      type,
+      application,
+      externalTester,
+      externalFieldCoordinatesCollector,
+      allowOnNonExternalLeafFields,
+      onFields);
     if (error) {
       errorCollector.push(error);
     }
@@ -240,11 +297,11 @@ function validateAllExternalFieldsUsed(
       }
 
       if (!isFieldSatisfyingInterface(field)) {
-        errorCollector.push(new GraphQLError(
-          `Field ${field.coordinate} is marked @external but is not used in any federation directive (@key, @provides, @requires) or to satisfy an interface;`
+        errorCollector.push(ERRORS.EXTERNAL_UNUSED.err({
+          message: `Field "${field.coordinate}" is marked @external but is not used in any federation directive (@key, @provides, @requires) or to satisfy an interface;`
           + ' the field declaration has no use and should be removed (or the field should not be @external).',
-          field.sourceAST
-        ));
+          nodes: field.sourceAST,
+        }));
       }
     }
   }
@@ -254,6 +311,52 @@ function isFieldSatisfyingInterface(field: FieldDefinition<ObjectType | Interfac
   return field.parent.interfaces().some(itf => itf.field(field.name));
 }
 
+/**
+ * Register errors when, for an interface field, some of the implementations of that field are @external
+ * _and_ not all of those field implementation have the same type (which otherwise allowed because field
+ * implementation types can be a subtype of the interface field they implement).
+ * This is done because if that is the case, federation may later generate invalid query plans (see details
+ * on https://github.com/apollographql/federation/issues/1257).
+ * This "limitation" will be removed when we stop generating invalid query plans for it.
+ */
+function validateInterfaceRuntimeImplementationFieldsTypes(
+  itf: InterfaceType,
+  externalTester: ExternalTester, 
+  errorCollector: GraphQLError[],
+): void {
+  const runtimeTypes = itf.possibleRuntimeTypes();
+  for (const field of itf.fields()) {
+    const withExternalOrRequires: FieldDefinition<ObjectType>[] = [];
+    const typeToImplems: MultiMap<string, FieldDefinition<ObjectType>> = new MultiMap();
+    const nodes: ASTNode[] = [];
+    for (const type of runtimeTypes) {
+      const implemField = type.field(field.name);
+      if (!implemField) continue;
+      if (implemField.sourceAST) {
+        nodes.push(implemField.sourceAST);
+      }
+      if (externalTester.isExternal(implemField) || implemField.hasAppliedDirective(requiresDirectiveName)) {
+        withExternalOrRequires.push(implemField);
+      }
+      const returnType = implemField.type!;
+      typeToImplems.add(returnType.toString(), implemField);
+    }
+    if (withExternalOrRequires.length > 0 && typeToImplems.size > 1) {
+      const typeToImplemsArray = [...typeToImplems.entries()];
+      errorCollector.push(ERRORS.INTERFACE_FIELD_IMPLEM_TYPE_MISMATCH.err({
+        message: `Some of the runtime implementations of interface field "${field.coordinate}" are marked @external or have a @require (${withExternalOrRequires.map(printFieldCoordinate)}) so all the implementations should use the same type (a current limitation of federation; see https://github.com/apollographql/federation/issues/1257), but ${formatFieldsToReturnType(typeToImplemsArray[0])} while ${joinStrings(typeToImplemsArray.slice(1).map(formatFieldsToReturnType), ' and ')}.`,
+        nodes
+      }));
+    }
+  }
+}
+
+const printFieldCoordinate = (f: FieldDefinition<CompositeType>): string => `"${f.coordinate}"`;
+
+function formatFieldsToReturnType([type, implems]: [string, FieldDefinition<ObjectType>[]]) {
+  return `${joinStrings(implems.map(printFieldCoordinate))} ${implems.length == 1 ? 'has' : 'have'} type "${type}"`;
+}
+
 export class FederationBuiltIns extends BuiltIns {
   addBuiltInTypes(schema: Schema) {
     super.addBuiltInTypes(schema);
@@ -272,7 +375,7 @@ export class FederationBuiltIns extends BuiltIns {
     // Note that we allow @key on interfaces in the definition to not break backward compatibility, because it has historically unfortunately be declared this way, but
     // @key is actually not supported on interfaces at the moment, so if if is "used" then it is rejected.
     const keyDirective = this.addBuiltInDirective(schema, keyDirectiveName)
-      .addLocations('OBJECT', 'INTERFACE');
+      .addLocations(DirectiveLocation.OBJECT, DirectiveLocation.INTERFACE);
     // TODO: I believe fed 1 does not mark key repeatable and relax validation to accept repeating non-repeatable directive.
     // Do we want to perpetuate this? (Obviously, this is for historical reason and some graphQL implementations still do
     // not support 'repeatable'. But since this code does not kick in within users' code, not sure we have to accommodate
@@ -281,14 +384,14 @@ export class FederationBuiltIns extends BuiltIns {
     keyDirective.addArgument('fields', fieldSetType);
 
     this.addBuiltInDirective(schema, extendsDirectiveName)
-      .addLocations('OBJECT', 'INTERFACE');
+      .addLocations(DirectiveLocation.OBJECT, DirectiveLocation.INTERFACE);
 
     this.addBuiltInDirective(schema, externalDirectiveName)
-      .addLocations('OBJECT', 'FIELD_DEFINITION');
+      .addLocations(DirectiveLocation.OBJECT, DirectiveLocation.FIELD_DEFINITION);
 
     for (const name of [requiresDirectiveName, providesDirectiveName]) {
       this.addBuiltInDirective(schema, name)
-        .addLocations('FIELD_DEFINITION')
+        .addLocations(DirectiveLocation.FIELD_DEFINITION)
         .addArgument('fields', fieldSetType);
     }
 
@@ -363,13 +466,12 @@ export class FederationBuiltIns extends BuiltIns {
         // composition error.
         const existing = schema.type(defaultName);
         if (existing) {
-          errors.push(error(
-            `ROOT_${k.toUpperCase()}_USED`,
-            `The schema has a type named "${defaultName}" but it is not set as the ${k} root type ("${type.name}" is instead): `
-            + 'this is not supported by federation. '
-            + 'If a root type does not use its default name, there should be no other type with that default name.',
-            sourceASTs(type, existing)
-          ));
+          errors.push(ERROR_CATEGORIES.ROOT_TYPE_USED.get(k).err({
+            message: `The schema has a type named "${defaultName}" but it is not set as the ${k} root type ("${type.name}" is instead): `
+              + 'this is not supported by federation. '
+              + 'If a root type does not use its default name, there should be no other type with that default name.',
+            nodes: sourceASTs(type, existing),
+          }));
         }
         type.rename(defaultName);
       }
@@ -383,12 +485,20 @@ export class FederationBuiltIns extends BuiltIns {
     validateAllFieldSet<CompositeType>(
       keyDirective,
       type => type,
-      type => `type "${type}"`,
       errors,
       externalTester,
       externalFieldsInFedDirectivesCoordinates,
       true,
-      true
+      true,
+      field => {
+        if (isListType(field.type!) || isUnionType(field.type!) || isInterfaceType(field.type!)) {
+          let kind: string = field.type!.kind;
+          kind = kind.slice(0, kind.length - 'Type'.length);
+          throw ERRORS.KEY_FIELDS_SELECT_INVALID_TYPE.err({
+            message: `field "${field.coordinate}" is a ${kind} type which is not allowed in @key`
+          });
+        }
+      }
     );
     // Note that we currently reject @requires where a leaf field of the selection is not external,
     // because if it's provided by the current subgraph, why "requires" it? That said, it's not 100%
@@ -400,7 +510,6 @@ export class FederationBuiltIns extends BuiltIns {
     validateAllFieldSet<FieldDefinition<CompositeType>>(
       this.requiresDirective(schema),
       field => field.parent,
-      field => `field "${field.coordinate}"`,
       errors,
       externalTester,
       externalFieldsInFedDirectivesCoordinates,
@@ -419,13 +528,13 @@ export class FederationBuiltIns extends BuiltIns {
         }
         const type = baseType(field.type!);
         if (!isCompositeType(type)) {
-          throw new GraphQLError(
-            `Invalid @provides directive on field "${field.coordinate}": field has type "${field.type}" which is not a Composite Type`,
-            field.sourceAST);
+          throw ERRORS.PROVIDES_ON_NON_OBJECT_FIELD.err({
+            message: `Invalid @provides directive on field "${field.coordinate}": field has type "${field.type}" which is not a Composite Type`,
+            nodes: field.sourceAST,
+          });
         }
         return type;
       },
-      field => `field ${field.coordinate}`,
       errors,
       externalTester,
       externalFieldsInFedDirectivesCoordinates,
@@ -444,6 +553,10 @@ export class FederationBuiltIns extends BuiltIns {
       }
     }
 
+    for (const itf of schema.types<InterfaceType>('InterfaceType')) {
+      validateInterfaceRuntimeImplementationFieldsTypes(itf, externalTester, errors);
+    }
+
     return errors;
   }
 
@@ -491,7 +604,7 @@ export class FederationBuiltIns extends BuiltIns {
     }
 
     return {
-      kind: 'Document',
+      kind: Kind.DOCUMENT,
       loc: document.loc,
       definitions
     };
@@ -527,14 +640,17 @@ export function isEntityType(type: NamedType): boolean {
   return type.kind == "ObjectType" && type.hasAppliedDirective(keyDirectiveName);
 }
 
-function buildSubgraph(name: string, source: DocumentNode | string): Schema {
+export function buildSubgraph(name: string, source: DocumentNode | string): Schema {
   try {
     return typeof source === 'string'
       ? buildSchema(new Source(source, name), federationBuiltIns)
       : buildSchemaFromAST(source, federationBuiltIns);
   } catch (e) {
     if (e instanceof GraphQLError) {
-      throw addSubgraphToError(e, name);
+      // Note that `addSubgraphToError` only adds the provided code if the original error
+      // didn't have one, and the only one that will not have a code are GraphQL errors
+      // (since we assign specific codes to the federation errors).
+      throw addSubgraphToError(e, name, ERRORS.INVALID_GRAPHQL);
     } else {
       throw e;
     }
@@ -546,17 +662,72 @@ export function parseFieldSetArgument(
   directive: Directive<NamedType | FieldDefinition<CompositeType>, {fields: any}>,
   fieldAccessor: (type: CompositeType, fieldName: string) => FieldDefinition<any> | undefined = (type, name) => type.field(name)
 ): SelectionSet {
-  return parseSelectionSet(parentType, validateFieldSetValue(directive), new VariableDefinitions(), undefined, fieldAccessor);
+  try {
+    const selectionSet = parseSelectionSet(parentType, validateFieldSetValue(directive), new VariableDefinitions(), undefined, fieldAccessor);
+    selectionSet.validate();
+    return selectionSet;
+  } catch (e) {
+    if (!(e instanceof GraphQLError)) {
+      throw e;
+    }
+
+    const nodes = sourceASTs(directive);
+    if (e.nodes) {
+      nodes.push(...e.nodes);
+    }
+    let msg = e.message.trim();
+    // The rule for validating @requires in fed 1 was not properly recursive, so people upgrading
+    // may have a @require that selects some fields but without declaring those fields on the
+    // subgraph. As we fixed the validation, this will now fail, but we try here to provide some
+    // hint for those users for how to fix the problem.
+    // Note that this is a tad fragile to rely on the error message like that, but worth case, a
+    // future change make us not show the hint and that's not the end of the world.
+    if (msg.startsWith('Cannot query field')) {
+      if (msg.endsWith('.')) {
+        msg = msg.slice(0, msg.length - 1);
+      }
+      if (directive.name === keyDirectiveName) {
+        msg = msg + ' (the field should be either be added to this subgraph or, if it should not be resolved by this subgraph, you need to add it to this subgraph with @external).';
+      } else {
+        msg = msg + ' (if the field is defined in another subgraph, you need to add it to this subgraph with @external).';
+      }
+    }
+
+    const codeDef = errorCodeDef(e) ?? ERROR_CATEGORIES.DIRECTIVE_INVALID_FIELDS.get(directive.name);
+    throw codeDef.err({
+      message: `${fieldSetErrorDescriptor(directive)}: ${msg}`,
+      nodes,
+      originalError: e,
+    });
+  }
 }
 
 function validateFieldSetValue(directive: Directive<NamedType | FieldDefinition<CompositeType>, {fields: any}>): string {
   const fields = directive.arguments().fields;
+  const nodes = directive.sourceAST;
   if (typeof fields !== 'string') {
-    throw new GraphQLError(
-      `Invalid value for argument ${directive.definition!.argument('fields')!.coordinate} on ${directive.parent.coordinate}: must be a string.`,
-      directive.sourceAST
-    );
+    throw ERROR_CATEGORIES.DIRECTIVE_INVALID_FIELDS_TYPE.get(directive.name).err({
+      message: `Invalid value for argument "${directive.definition!.argument('fields')!.name}": must be a string.`,
+      nodes,
+    });
+  }
+  // While validating if the field is a string will work in most cases, this will not catch the case where the field argument was
+  // unquoted but parsed as an enum value (see federation/issues/850 in particular). So if we have the AST (which we will usually
+  // have in practice), use that to check that the argument was truly a string.
+  if (nodes && nodes.kind === 'Directive') {
+    for (const argNode of nodes.arguments ?? []) {
+      if (argNode.name.value === 'fields') {
+        if (argNode.value.kind !== 'StringValue') {
+          throw ERROR_CATEGORIES.DIRECTIVE_INVALID_FIELDS_TYPE.get(directive.name).err({
+            message: `Invalid value for argument "${directive.definition!.argument('fields')!.name}": must be a string.`,
+            nodes,
+          });
+        }
+        break;
+      }
+    }
   }
+
   return fields;
 }
 
@@ -598,7 +769,7 @@ export class Subgraphs {
       : subgraphOrName;
 
     if (toAdd.name === FEDERATION_RESERVED_SUBGRAPH_NAME) {
-      throw new GraphQLError(`Invalid name ${FEDERATION_RESERVED_SUBGRAPH_NAME} for a subgraph: this name is reserved`);
+      throw ERRORS.INVALID_SUBGRAPH_NAME.err({ message: `Invalid name ${FEDERATION_RESERVED_SUBGRAPH_NAME} for a subgraph: this name is reserved` });
     }
 
     if (this.subgraphs.has(toAdd.name)) {
@@ -661,16 +832,36 @@ export function addSubgraphToASTNode(node: ASTNode, subgraph: string): SubgraphA
   };
 }
 
-export function addSubgraphToError(e: GraphQLError, subgraphName: string): GraphQLError {
-  const updatedCauses = errorCauses(e)!.map(cause => new GraphQLError(
-    `[${subgraphName}] ${cause.message}`,
-    cause.nodes ? cause.nodes.map(node => addSubgraphToASTNode(node, subgraphName)) : undefined,
-    cause.source,
-    cause.positions,
-    cause.path,
-    cause.originalError,
-    cause.extensions
-  ));
+export function addSubgraphToError(e: GraphQLError, subgraphName: string, errorCode?: ErrorCodeDefinition): GraphQLError {
+  const updatedCauses = errorCauses(e)!.map(cause => {
+    const message = `[${subgraphName}] ${cause.message}`;
+    const nodes = cause.nodes
+      ? cause.nodes.map(node => addSubgraphToASTNode(node, subgraphName))
+      : undefined;
+
+    const code = errorCodeDef(cause) ?? errorCode;
+    if (code) {
+      return code.err({
+        message,
+        nodes,
+        source: cause.source,
+        positions: cause.positions,
+        path: cause.path,
+        originalError: cause.originalError,
+        extensions: cause.extensions,
+      });
+    } else {
+      return new GraphQLError(
+        message,
+        nodes,
+        cause.source,
+        cause.positions,
+        cause.path,
+        cause.originalError,
+        cause.extensions
+      );
+    }
+  });
 
   return ErrGraphQLValidationFailed(updatedCauses);
 }
@@ -714,4 +905,18 @@ export class ExternalTester {
   isFakeExternal(field: FieldDefinition<any> | InputFieldDefinition) {
     return this.fakeExternalFields.has(field.coordinate);
   }
+
+  selectsAnyExternalField(selectionSet: SelectionSet): boolean {
+    for (const selection of selectionSet.selections()) {
+      if (selection.kind === 'FieldSelection' && this.isExternal(selection.element().definition)) {
+        return true;
+      }
+      if (selection.selectionSet) {
+        if (this.selectsAnyExternalField(selection.selectionSet)) {
+          return true;
+        }
+      }
+    }
+    return false;
+  }
 }

package/src/genErrorCodeDoc.ts

@@ -0,0 +1,69 @@
+import { assert } from './utils';
+import { ERRORS, REMOVED_ERRORS } from './error';
+
+const header = `---
+title: Federation error codes
+sidebar_title: Error codes
+---
+
+When Apollo Gateway attempts to **compose** the schemas provided by your [subgraphs](./subgraphs/) into a **supergraph schema**, it confirms that:
+
+* The subgraphs are valid
+* The resulting supergraph schema is valid
+* The gateway has all of the information it needs to execute operations against the resulting schema
+
+If Apollo Gateway encounters an error, composition fails. This document lists subgraphs and composition error codes and their root causes.
+`;
+
+function makeMardownArray(
+  headers: string[],
+  rows: string[][]
+): string {
+  const columns = headers.length;
+  let out = '| ' + headers.join(' | ') + ' |\n';
+  out += '|' + headers.map(_ => '---').join('|') + '|\n';
+  for (const row of rows) {
+    assert(row.length <= columns, `Row [${row}] has too columns (expect ${columns} but got ${row.length})`);
+    const frow = row.length === columns
+      ? row
+      : row.concat(new Array<string>(columns - row.length).fill(''));
+    out += '| ' + frow.join(' | ') + ' |\n'
+  }
+  return out;
+}
+
+const rows = Object.values(ERRORS).map(def => [
+  '`' + def.code + '`',
+  def.description,
+  def.metadata.addedIn,
+  def.metadata.replaces ? `Replaces: ${def.metadata.replaces.map(c => '`' + c + '`').join(', ')}` : ''
+]);
+
+const sortRowsByCode = (r1: string[], r2: string[]) => r1[0].localeCompare(r2[0]);
+
+rows.sort(sortRowsByCode);
+
+const errorsSection = `## Errors
+
+The following errors may be raised by composition:
+
+` + makeMardownArray(
+  [ 'Code', 'Description', 'Since', 'Comment' ],
+  rows
+);
+
+const removedErrors = REMOVED_ERRORS
+  .map(([code, comment]) => ['`' + code + '`', comment])
+  .sort(sortRowsByCode);
+
+const removedSection = `## Removed codes
+
+The following section lists code that have been removed and are not longer generated by the gateway version this is the documentation for.
+
+` + makeMardownArray(['Removed Code', 'Comment'], removedErrors);
+
+console.log(
+  header + '\n\n'
+  + errorsSection + '\n\n'
+  + removedSection
+);

package/src/inaccessibleSpec.ts

@@ -7,7 +7,7 @@ import {
   isObjectType,
   Schema,
 } from "./definitions";
-import { GraphQLError } from "graphql";
+import { GraphQLError, DirectiveLocation } from "graphql";
 
 export const inaccessibleIdentity = 'https://specs.apollo.dev/inaccessible';
 
@@ -17,7 +17,12 @@ export class InaccessibleSpecDefinition extends FeatureDefinition {
   }
 
   addElementsToSchema(schema: Schema) {
-    this.addDirective(schema, 'inaccessible').addLocations('FIELD_DEFINITION', 'OBJECT', 'INTERFACE', 'UNION');
+    this.addDirective(schema, 'inaccessible').addLocations(
+      DirectiveLocation.FIELD_DEFINITION,
+      DirectiveLocation.OBJECT,
+      DirectiveLocation.INTERFACE,
+      DirectiveLocation.UNION,
+    );
   }
 
   inaccessibleDirective(schema: Schema): DirectiveDefinition<Record<string, never>> {