@apollo/federation-internals 2.0.0-preview.7 → 2.0.0

package/src/definitions.ts

@@ -24,7 +24,7 @@ import {
   FeatureUrl,
   findCoreSpecVersion,
   isCoreSpecDirectiveApplication,
-  removeFeatureElements,
+  removeAllCoreFeatures,
 } from "./coreSpec";
 import { assert, mapValues, MapWithCachedArrays, setValues } from "./utils";
 import { withDefaultValues, valueEquals, valueToString, valueToAST, variablesInValue, valueFromAST, valueNodeToConstValueNode } from "./values";
@@ -39,12 +39,23 @@ import { SDLValidationRule } from "graphql/validation/ValidationContext";
 import { specifiedSDLRules } from "graphql/validation/specifiedRules";
 import { validateSchema } from "./validate";
 import { createDirectiveSpecification, createScalarTypeSpecification, DirectiveSpecification, TypeSpecification } from "./directiveAndTypeSpecification";
+import { didYouMean, suggestionList } from "./suggestions";
+import { withModifiedErrorMessage } from "./error";
 
 const validationErrorCode = 'GraphQLValidationFailed';
+const DEFAULT_VALIDATION_ERROR_MESSAGE = 'The schema is not a valid GraphQL schema.';
 
-export const ErrGraphQLValidationFailed = (causes: GraphQLError[]) =>
+export const ErrGraphQLValidationFailed = (causes: GraphQLError[], message: string = DEFAULT_VALIDATION_ERROR_MESSAGE) =>
   err(validationErrorCode, {
-    message: 'The schema is not a valid GraphQL schema',
+    message: message + '. Caused by:\n' + causes.map((c) => c.toString()).join('\n\n'),
+    causes
+  });
+
+const apiSchemaValidationErrorCode = 'GraphQLAPISchemaValidationFailed';
+
+export const ErrGraphQLAPISchemaValidationFailed = (causes: GraphQLError[]) =>
+  err(apiSchemaValidationErrorCode, {
+    message: 'The supergraph schema failed to produce a valid API schema',
     causes
   });
 
@@ -54,7 +65,7 @@ export const ErrGraphQLValidationFailed = (causes: GraphQLError[]) =>
  */
 export function errorCauses(e: Error): GraphQLError[] | undefined {
   if (e instanceof GraphQLErrorExt) {
-    if (e.code === validationErrorCode) {
+    if (e.code === validationErrorCode || e.code === apiSchemaValidationErrorCode) {
       return ((e as any).causes) as GraphQLError[];
     }
     return [e];
@@ -211,6 +222,22 @@ export function isInputType(type: Type): type is InputType {
   }
 }
 
+export function isTypeOfKind<T extends Type>(type: Type, kind: T['kind']): type is T {
+  return type.kind === kind;
+}
+
+export function filterTypesOfKind<T extends Type>(types: readonly Type[], kind: T['kind']): T[] {
+  return types.reduce(
+    (acc: T[], type: Type) => {
+      if (isTypeOfKind(type, kind)) {
+        acc.push(type);
+      }
+      return acc;
+    },
+    [],
+  );
+}
+
 export function baseType(type: Type): NamedType {
   return isWrapperType(type) ? type.baseType() : type;
 }
@@ -380,8 +407,8 @@ export class DirectiveTargetElement<T extends DirectiveTargetElement<T>> {
   }
 }
 
-export function sourceASTs(...elts: ({ sourceAST?: ASTNode } | undefined)[]): ASTNode[] {
-  return elts.map(elt => elt?.sourceAST).filter(elt => elt !== undefined) as ASTNode[];
+export function sourceASTs<TNode extends ASTNode = ASTNode>(...elts: ({ sourceAST?: TNode } | undefined)[]): TNode[] {
+  return elts.map(elt => elt?.sourceAST).filter((elt): elt is TNode => elt !== undefined);
 }
 
 // Not exposed: mostly about avoid code duplication between SchemaElement and Directive (which is not a SchemaElement as it can't
@@ -489,34 +516,36 @@ export abstract class SchemaElement<TOwnType extends SchemaElement<any, TParent>
   }
 
   applyDirective<TApplicationArgs extends {[key: string]: any} = {[key: string]: any}>(
-    nameOrDefOrDirective: Directive<TOwnType, TApplicationArgs> | DirectiveDefinition<TApplicationArgs> | string,
-    args?: TApplicationArgs
+    nameOrDef: DirectiveDefinition<TApplicationArgs> | string,
+    args?: TApplicationArgs,
+    asFirstDirective: boolean = false,
   ): Directive<TOwnType, TApplicationArgs> {
-    let toAdd: Directive<TOwnType, TApplicationArgs>;
-    if (nameOrDefOrDirective instanceof Directive) {
-      this.checkUpdate(nameOrDefOrDirective);
-      toAdd = nameOrDefOrDirective;
-      if (args) {
-        toAdd.setArguments(args);
+    let name: string;
+    if (typeof nameOrDef === 'string') {
+      this.checkUpdate();
+      const def = this.schema().directive(nameOrDef) ?? this.schema().blueprint.onMissingDirectiveDefinition(this.schema(), nameOrDef, args);
+      if (!def) {
+        throw this.schema().blueprint.onGraphQLJSValidationError(
+          this.schema(),
+          new GraphQLError(`Unknown directive "@${nameOrDef}".`)
+        );
       }
-    } else {
-      let name: string;
-      if (typeof nameOrDefOrDirective === 'string') {
-        this.checkUpdate();
-        const def = this.schema().directive(nameOrDefOrDirective) ?? this.schema().blueprint.onMissingDirectiveDefinition(this.schema(), nameOrDefOrDirective);
-        if (!def) {
-          throw new GraphQLError(`Cannot apply unknown directive "@${nameOrDefOrDirective}"`);
-        }
-        name = nameOrDefOrDirective;
-      } else {
-        this.checkUpdate(nameOrDefOrDirective);
-        name = nameOrDefOrDirective.name;
+      if (Array.isArray(def)) {
+        throw ErrGraphQLValidationFailed(def);
       }
-      toAdd = new Directive<TOwnType, TApplicationArgs>(name, args ?? Object.create(null));
-      Element.prototype['setParent'].call(toAdd, this);
+      name = nameOrDef;
+    } else {
+      this.checkUpdate(nameOrDef);
+      name = nameOrDef.name;
     }
+    const toAdd = new Directive<TOwnType, TApplicationArgs>(name, args ?? Object.create(null));
+    Element.prototype['setParent'].call(toAdd, this);
     // TODO: we should typecheck arguments or our TApplicationArgs business is just a lie.
-    this._appliedDirectives.push(toAdd);
+    if (asFirstDirective) {
+      this._appliedDirectives.unshift(toAdd);
+    } else {
+      this._appliedDirectives.push(toAdd);
+    }
     DirectiveDefinition.prototype['addReferencer'].call(toAdd.definition!, toAdd);
     this.onModification();
     return toAdd;
@@ -694,7 +723,7 @@ abstract class BaseNamedType<TReferencer, TOwnType extends NamedType & NamedSche
   /**
    * Removes this type definition from its parent schema.
    *
-   * After calling this method, this type will be "detached": it wil have no parent, schema, fields,
+   * After calling this method, this type will be "detached": it will have no parent, schema, fields,
    * values, directives, etc...
    *
    * Note that it is always allowed to remove a type, but this may make a valid schema
@@ -710,15 +739,18 @@ abstract class BaseNamedType<TReferencer, TOwnType extends NamedType & NamedSche
     }
     this.checkRemoval();
     this.onModification();
-    this.removeInnerElements();
-    Schema.prototype['removeTypeInternal'].call(this._parent, this);
-    this.removeAppliedDirectives();
+    // Remove this type's children.
     this.sourceAST = undefined;
+    this.removeAppliedDirectives();
+    this.removeInnerElements();
+    // Remove this type's references.
     const toReturn = setValues(this._referencers).map(r => {
       SchemaElement.prototype['removeTypeReferenceInternal'].call(r, this);
       return r;
     });
     this._referencers.clear();
+    // Remove this type from its parent schema.
+    Schema.prototype['removeTypeInternal'].call(this._parent, this);
     this._parent = undefined;
     return toReturn;
   }
@@ -823,13 +855,14 @@ abstract class BaseExtensionMember<TExtended extends ExtendableElement> extends
 }
 
 export class SchemaBlueprint {
-  onMissingDirectiveDefinition(_schema: Schema, _name: string): DirectiveDefinition | undefined {
+  onMissingDirectiveDefinition(_schema: Schema, _name: string, _args?: {[key: string]: any}): DirectiveDefinition | GraphQLError[] | undefined {
     // No-op by default, but used for federation.
     return undefined;
   }
 
-  onDirectiveDefinitionAndSchemaParsed(_: Schema) {
+  onDirectiveDefinitionAndSchemaParsed(_: Schema): GraphQLError[] {
     // No-op by default, but used for federation.
+    return [];
   }
 
   ignoreParsedField(_type: NamedType, _fieldName: string): boolean {
@@ -857,6 +890,38 @@ export class SchemaBlueprint {
   validationRules(): readonly SDLValidationRule[] {
     return specifiedSDLRules;
   }
+
+  /**
+   * Allows to intercept some graphQL-js error messages when we can provide additional guidance to users.
+   */
+  onGraphQLJSValidationError(schema: Schema, error: GraphQLError): GraphQLError {
+    // For now, the main additional guidance we provide is around directives, where we could provide additional help in 2 main ways:
+    // - if a directive name is likely misspelled (somehow, graphQL-js has methods to offer suggestions on likely mispelling, but don't use this (at the
+    //   time of this writting) for directive names).
+    // - for fed 2 schema, if a federation directive is refered under it's "default" naming but is not properly imported (not enforced
+    //   in the method but rather in the `FederationBlueprint`).
+    //
+    // Note that intercepting/parsing error messages to modify them is never ideal, but pragmatically, it's probably better than rewriting the relevant
+    // rules entirely (in that later case, our "copied" rule would stop getting any potential graphQL-js made improvements for instance). And while such
+    // parsing is fragile, in that it'll break if the original message change, we have unit tests to surface any such breakage so it's not really a risk.
+    const matcher = /^Unknown directive "@(?<directive>[_A-Za-z][_0-9A-Za-z]*)"\.$/.exec(error.message);
+    const name = matcher?.groups?.directive;
+    if (!name) {
+      return error;
+    }
+
+    const allDefinedDirectiveNames = schema.allDirectives().map((d) => d.name);
+    const suggestions = suggestionList(name, allDefinedDirectiveNames);
+    if (suggestions.length === 0) {
+      return this.onUnknownDirectiveValidationError(schema, name, error);
+    } else {
+      return withModifiedErrorMessage(error, `${error.message}${didYouMean(suggestions.map((s) => '@' + s))}`);
+    }
+  }
+
+  onUnknownDirectiveValidationError(_schema: Schema, _unknownDirectiveName: string, error: GraphQLError): GraphQLError {
+    return error;
+  }
 }
 
 export const defaultSchemaBlueprint = new SchemaBlueprint();
@@ -872,8 +937,12 @@ export class CoreFeature {
   }
 
   isFeatureDefinition(element: NamedType | DirectiveDefinition): boolean {
+    const importName = element.kind === 'DirectiveDefinition'
+      ? '@' + element.name
+      : element.name;
     return element.name.startsWith(this.nameInSchema + '__')
-      || (element.kind === 'DirectiveDefinition' && element.name === this.nameInSchema);
+      || (element.kind === 'DirectiveDefinition' && element.name === this.nameInSchema)
+      || !!this.imports.find((i) => importName === (i.as ?? i.name));
   }
 
   directiveNameInSchema(name: string): string {
@@ -931,7 +1000,7 @@ export class CoreFeatures {
     if (existing) {
       throw error(`Duplicate inclusion of feature ${url.identity}`);
     }
-    const imports = extractCoreFeatureImports(typedDirective);
+    const imports = extractCoreFeatureImports(url, typedDirective);
     const feature = new CoreFeature(url, args.as ?? url.name, directive, imports, args.for);
     this.add(feature);
     directive.schema().blueprint.onAddedCoreFeature(directive.schema(), feature);
@@ -976,25 +1045,29 @@ const graphQLBuiltInDirectivesSpecifications: readonly DirectiveSpecification[]
   createDirectiveSpecification({
     name: 'include',
     locations: [DirectiveLocation.FIELD, DirectiveLocation.FRAGMENT_SPREAD, DirectiveLocation.INLINE_FRAGMENT],
-    argumentFct: (schema) => [{ name: 'if', type: new NonNullType(schema.booleanType()) }]
+    argumentFct: (schema) => ({ args: [{ name: 'if', type: new NonNullType(schema.booleanType()) }], errors: [] })
   }),
   createDirectiveSpecification({
     name: 'skip',
     locations: [DirectiveLocation.FIELD, DirectiveLocation.FRAGMENT_SPREAD, DirectiveLocation.INLINE_FRAGMENT],
-    argumentFct: (schema) => [{ name: 'if', type: new NonNullType(schema.booleanType()) }]
+    argumentFct: (schema) => ({ args: [{ name: 'if', type: new NonNullType(schema.booleanType()) }], errors: [] })
   }),
   createDirectiveSpecification({
     name: 'deprecated',
     locations: [DirectiveLocation.FIELD_DEFINITION, DirectiveLocation.ENUM_VALUE, DirectiveLocation.ARGUMENT_DEFINITION, DirectiveLocation.INPUT_FIELD_DEFINITION],
-    argumentFct: (schema) => [{ name: 'reason', type: schema.stringType(), defaultValue: 'No longer supported' }]
+    argumentFct: (schema) => ({ args: [{ name: 'reason', type: schema.stringType(), defaultValue: 'No longer supported' }], errors: [] })
   }),
   createDirectiveSpecification({
     name: 'specifiedBy',
     locations: [DirectiveLocation.SCALAR],
-    argumentFct: (schema) => [{ name: 'url', type: new NonNullType(schema.stringType()) }]
+    argumentFct: (schema) => ({ args: [{ name: 'url', type: new NonNullType(schema.stringType()) }], errors: [] })
   }),
 ];
 
+
+// A coordinate is up to 3 "graphQL name" ([_A-Za-z][_0-9A-Za-z]*).
+const coordinateRegexp = /^@?[_A-Za-z][_0-9A-Za-z]*(\.[_A-Za-z][_0-9A-Za-z]*)?(\([_A-Za-z][_0-9A-Za-z]*:\))?$/;
+
 export class Schema {
   private _schemaDefinition: SchemaDefinition;
   private readonly _builtInTypes = new MapWithCachedArrays<string, NamedType>();
@@ -1084,13 +1157,7 @@ export class Schema {
 
       const apiSchema = this.clone();
       removeInaccessibleElements(apiSchema);
-      const coreFeatures = apiSchema.coreFeatures;
-      if (coreFeatures) {
-        // Note that core being a feature itself, this will remove core itself and mark apiSchema as 'not core'
-        for (const coreFeature of coreFeatures.allFeatures()) {
-          removeFeatureElements(apiSchema, coreFeature);
-        }
-      }
+      removeAllCoreFeatures(apiSchema);
       assert(!apiSchema.isCoreSchema(), "The API schema shouldn't be a core schema")
       apiSchema.validate();
       this.apiSchema = apiSchema;
@@ -1118,20 +1185,42 @@ export class Schema {
   /**
    * All the types defined on this schema, excluding the built-in types.
    */
-  types<T extends NamedType>(kind?: T['kind']): readonly T[] {
-    const allKinds = this._types.values();
-    return (kind ? allKinds.filter(t => t.kind === kind) : allKinds) as readonly T[];
+  types(): readonly NamedType[] {
+    return this._types.values();
+  }
+
+  interfaceTypes(): readonly InterfaceType[] {
+    return filterTypesOfKind<InterfaceType>(this.types(), 'InterfaceType');
+  }
+
+  objectTypes(): readonly ObjectType[] {
+    return filterTypesOfKind<ObjectType>(this.types(), 'ObjectType');
+  }
+
+  unionTypes(): readonly UnionType[] {
+    return filterTypesOfKind<UnionType>(this.types(), 'UnionType');
+  }
+
+  scalarTypes(): readonly ScalarType[] {
+    return filterTypesOfKind<ScalarType>(this.types(), 'ScalarType');
+  }
+
+  inputTypes(): readonly InputObjectType[] {
+    return filterTypesOfKind<InputObjectType>(this.types(), 'InputObjectType');
+  }
+
+  enumTypes(): readonly EnumType[] {
+    return filterTypesOfKind<EnumType>(this.types(), 'EnumType');
   }
 
   /**
    * All the built-in types for this schema (those that are not displayed when printing the schema).
    */
-  builtInTypes<T extends NamedType>(kind?: T['kind'], includeShadowed: boolean = false): readonly T[] {
+  builtInTypes(includeShadowed: boolean = false): readonly NamedType[] {
     const allBuiltIns = this._builtInTypes.values();
-    const forKind = (kind ? allBuiltIns.filter(t => t.kind === kind) : allBuiltIns) as readonly T[];
     return includeShadowed
-      ? forKind
-      : forKind.filter(t => !this.isShadowedBuiltInType(t));
+      ? allBuiltIns
+      : allBuiltIns.filter(t => !this.isShadowedBuiltInType(t));
   }
 
   private isShadowedBuiltInType(type: NamedType) {
@@ -1141,8 +1230,8 @@ export class Schema {
   /**
     * All the types, including the built-in ones.
     */
-  allTypes<T extends NamedType>(kind?: T['kind']): readonly T[] {
-    return this.builtInTypes(kind).concat(this.types(kind));
+  allTypes(): readonly NamedType[] {
+    return this.builtInTypes().concat(this.types());
   }
 
   /**
@@ -1311,7 +1400,7 @@ export class Schema {
 
     // TODO: we check that all types are properly set (aren't undefined) in `validateSchema`, but `validateSDL` will error out beforehand. We should
     // probably extract that part of `validateSchema` and run `validateSDL` conditionally on that first check.
-    let errors = validateSDL(this.toAST(), undefined, this.blueprint.validationRules());
+    let errors = validateSDL(this.toAST(), undefined, this.blueprint.validationRules()).map((e) => this.blueprint.onGraphQLJSValidationError(this, e));
     errors = errors.concat(validateSchema(this));
 
     // We avoid adding federation-specific validations if the base schema is not proper graphQL as the later can easily trigger
@@ -1364,6 +1453,56 @@ export class Schema {
   specifiedByDirective(schema: Schema): DirectiveDefinition<{url: string}> {
     return this.getBuiltInDirective(schema, 'specifiedBy');
   }
+
+  /**
+   * Gets an element of the schema given its "schema coordinate".
+   *
+   * Note that the syntax for schema coordinates is the one from the upcoming GraphQL spec: https://github.com/graphql/graphql-spec/pull/794.
+   */
+  elementByCoordinate(coordinate: string): NamedSchemaElement<any, any, any> | undefined {
+    if (!coordinate.match(coordinateRegexp)) {
+      throw error(`Invalid argument "${coordinate}: it is not a syntactically valid graphQL coordinate."`);
+    }
+
+    const argStartIdx = coordinate.indexOf('(');
+    const start = argStartIdx < 0 ? coordinate : coordinate.slice(0, argStartIdx);
+    // Argument syntax is `foo(argName:)`, so the arg name start after the open parenthesis and go until the final ':)'.
+    const argName = argStartIdx < 0 ? undefined : coordinate.slice(argStartIdx + 1, coordinate.length - 2);
+    const splittedStart = start.split('.');
+    const typeOrDirectiveName = splittedStart[0];
+    const fieldOrEnumName = splittedStart[1];
+    const isDirective = typeOrDirectiveName.startsWith('@');
+    if (isDirective) {
+      if (fieldOrEnumName) {
+        throw error(`Invalid argument "${coordinate}: it is not a syntactically valid graphQL coordinate."`);
+      }
+      const directive = this.directive(typeOrDirectiveName.slice(1));
+      return argName ? directive?.argument(argName) : directive;
+    } else {
+      const type = this.type(typeOrDirectiveName);
+      if (!type || !fieldOrEnumName) {
+        return type;
+      }
+      switch (type.kind) {
+        case 'ObjectType':
+        case 'InterfaceType':
+          const field = type.field(fieldOrEnumName);
+          return argName ? field?.argument(argName) : field;
+        case 'InputObjectType':
+          if (argName) {
+            throw error(`Invalid argument "${coordinate}: it is not a syntactically valid graphQL coordinate."`);
+          }
+          return type.field(fieldOrEnumName);
+        case 'EnumType':
+          if (argName) {
+            throw error(`Invalid argument "${coordinate}: it is not a syntactically valid graphQL coordinate."`);
+          }
+          return type.value(fieldOrEnumName);
+        default:
+          throw error(`Invalid argument "${coordinate}: it is not a syntactically valid graphQL coordinate."`);
+      }
+    }
+  }
 }
 
 export class RootType extends BaseExtensionMember<SchemaDefinition> {
@@ -1390,10 +1529,11 @@ export class SchemaDefinition extends SchemaElement<SchemaDefinition, Schema>  {
   }
 
   applyDirective<TApplicationArgs extends {[key: string]: any} = {[key: string]: any}>(
-    nameOrDefOrDirective: Directive<SchemaDefinition, TApplicationArgs> | DirectiveDefinition<TApplicationArgs> | string,
-    args?: TApplicationArgs
+    nameOrDef: DirectiveDefinition<TApplicationArgs> | string,
+    args?: TApplicationArgs,
+    asFirstDirective: boolean = false,
   ): Directive<SchemaDefinition, TApplicationArgs> {
-    const applied = super.applyDirective(nameOrDefOrDirective, args) as Directive<SchemaDefinition, TApplicationArgs>;
+    const applied = super.applyDirective(nameOrDef, args, asFirstDirective) as Directive<SchemaDefinition, TApplicationArgs>;
     const schema = this.schema();
     const coreFeatures = schema.coreFeatures;
     if (isCoreSpecDirectiveApplication(applied)) {
@@ -1403,9 +1543,13 @@ export class SchemaDefinition extends SchemaElement<SchemaDefinition, Schema>  {
       const schemaDirective = applied as Directive<SchemaDefinition, CoreOrLinkDirectiveArgs>;
       const args = schemaDirective.arguments();
       const url = FeatureUrl.parse((args.url ?? args.feature)!);
-      const imports = extractCoreFeatureImports(schemaDirective);
+      const imports = extractCoreFeatureImports(url, schemaDirective);
       const core = new CoreFeature(url, args.as ?? url.name, schemaDirective, imports, args.for);
       Schema.prototype['markAsCoreSchema'].call(schema, core);
+      // We also any core features that may have been added before we saw the @link for link itself
+      this.appliedDirectives
+        .filter((a) => a !== applied)
+        .forEach((other) => CoreFeatures.prototype['maybeAddFeature'].call(schema.coreFeatures, other));
     } else if (coreFeatures) {
       CoreFeatures.prototype['maybeAddFeature'].call(coreFeatures, applied);
     }
@@ -1914,7 +2058,12 @@ export class EnumType extends BaseNamedType<OutputTypeReferencer, EnumType> {
   protected readonly _values: EnumValue[] = [];
 
   get values(): readonly EnumValue[] {
-    return this._values;
+    // Because our abstractions are mutable, and removal is done by calling
+    // `remove()` on the element to remove, it's not unlikely someone mauy
+    // try to iterate on the result of this method and call `remove()` on
+    // some of the return value based on some condition. But this will break
+    // in an error-prone way if we don't copy, so we do.
+    return Array.from(this._values);
   }
 
   value(name: string): EnumValue | undefined {
@@ -2213,23 +2362,36 @@ export class FieldDefinition<TParent extends CompositeType> extends NamedSchemaE
   /**
    * Removes this field definition from its parent type.
    *
-   * After calling this method, this field definition will be "detached": it wil have no parent, schema, type,
-   * arguments or directives.
+   * After calling this method, this field definition will be "detached": it will have no parent, schema, type,
+   * arguments, or directives.
    */
   remove(): never[] {
     if (!this._parent) {
       return [];
     }
+    this.checkRemoval();
     this.onModification();
-    this.removeAppliedDirectives();
+    // Remove this field's children.
+    this.sourceAST = undefined;
     this.type = undefined;
-    this._extension = undefined;
+    this.removeAppliedDirectives();
     for (const arg of this.arguments()) {
       arg.remove();
     }
+    // Note that we don't track field references outside of parents, so no
+    // removal needed there.
+    //
+    // TODO: One could consider interface fields as references to implementing
+    //   object/interface fields, in the sense that removing an implementing
+    //   object/interface field breaks the validity of the implementing
+    //   interface field. Being aware that an object/interface field is being
+    //   referenced in such a way would be useful for understanding breakages
+    //   that need to be resolved as a consequence of removal.
+    //
+    // Remove this field from its parent object/interface type.
     FieldBasedType.prototype['removeFieldInternal'].call(this._parent, this);
     this._parent = undefined;
-    // Fields have nothing that can reference them outside of their parents
+    this._extension = undefined;
     return [];
   }
 
@@ -2292,20 +2454,38 @@ export class InputFieldDefinition extends NamedSchemaElementWithType<InputType,
   }
 
   /**
-   * Removes this field definition from its parent type.
+   * Removes this input field definition from its parent type.
    *
-   * After calling this method, this field definition will be "detached": it wil have no parent, schema, type,
-   * arguments or directives.
+   * After calling this method, this input field definition will be "detached": it will have no parent, schema,
+   * type, default value, or directives.
    */
   remove(): never[] {
     if (!this._parent) {
       return [];
     }
+    this.checkRemoval();
     this.onModification();
+    // Remove this input field's children.
+    this.sourceAST = undefined;
+    this.type = undefined;
+    this.defaultValue = undefined;
+    this.removeAppliedDirectives();
+    // Note that we don't track input field references outside of parents, so no
+    // removal needed there.
+    //
+    // TODO: One could consider default values (in field arguments, input
+    //   fields, or directive definitions) as references to input fields they
+    //   use, in the sense that removing the input field breaks the validity of
+    //   the default value. Being aware that an input field is being referenced
+    //   in such a way would be useful for understanding breakages that need to
+    //   be resolved as a consequence of removal. (The reference is indirect
+    //   though, as input field usages are currently represented as strings
+    //   within GraphQL values).
+    //
+    // Remove this input field from its parent input object type.
     InputObjectType.prototype['removeFieldInternal'].call(this._parent, this);
     this._parent = undefined;
-    this.type = undefined;
-    // Fields have nothing that can reference them outside of their parents
+    this._extension = undefined;
     return [];
   }
 
@@ -2350,22 +2530,39 @@ export class ArgumentDefinition<TParent extends FieldDefinition<any> | Directive
   /**
    * Removes this argument definition from its parent element (field or directive).
    *
-   * After calling this method, this argument definition will be "detached": it wil have no parent, schema, type,
-   * default value or directives.
+   * After calling this method, this argument definition will be "detached": it will have no parent, schema, type,
+   * default value, or directives.
    */
   remove(): never[] {
     if (!this._parent) {
       return [];
     }
+    this.checkRemoval();
     this.onModification();
+    // Remove this argument's children.
+    this.sourceAST = undefined;
+    this.type = undefined;
+    this.defaultValue = undefined;
+    this.removeAppliedDirectives();
+    // Note that we don't track argument references outside of parents, so no
+    // removal needed there.
+    //
+    // TODO: One could consider the arguments of directive applications as
+    //   references to the arguments of directive definitions, in the sense that
+    //   removing a directive definition argument can break the validity of the
+    //   directive application. Being aware that a directive definition argument
+    //   is being referenced in such a way would be useful for understanding
+    //   breakages that need to be resolved as a consequence of removal. (You
+    //   could make a similar claim about interface field arguments being
+    //   references to object field arguments.)
+    //
+    // Remove this argument from its parent field or directive definition.
     if (this._parent instanceof FieldDefinition) {
       FieldDefinition.prototype['removeArgumentInternal'].call(this._parent, this.name);
     } else {
       DirectiveDefinition.prototype['removeArgumentInternal'].call(this._parent, this.name);
     }
     this._parent = undefined;
-    this.type = undefined;
-    this.defaultValue = undefined;
     return [];
   }
 
@@ -2406,23 +2603,36 @@ export class EnumValue extends NamedSchemaElement<EnumValue, EnumType, never> {
   }
 
   /**
-   * Removes this field definition from its parent type.
+   * Removes this enum value definition from its parent type.
    *
-   * After calling this method, this field definition will be "detached": it wil have no parent, schema, type,
-   * arguments or directives.
+   * After calling this method, this enum value definition will be "detached": it will have no parent, schema, type,
+   * arguments, or directives.
    */
   remove(): never[] {
     if (!this._parent) {
       return [];
     }
+    this.checkRemoval();
     this.onModification();
+    // Remove this enum value's children.
+    this.sourceAST = undefined;
+    this.removeAppliedDirectives();
+    // Note that we don't track enum value references outside of parents, so no
+    // removal needed there.
+    //
+    // TODO: One could consider default values (in field arguments, input
+    //   fields, or directive definitions) as references to enum values they
+    //   use, in the sense that removing the enum value breaks the validity of
+    //   the default value. Being aware that an enum value is being referenced
+    //   in such a way would be useful for understanding breakages that need to
+    //   be resolved as a consequence of removal. (The reference is indirect
+    //   though, as enum value usages are currently represented as strings
+    //   within GraphQL values).
+    //
+    // Remove this enum value from its parent enum type.
     EnumType.prototype['removeValueInternal'].call(this._parent, this);
     this._parent = undefined;
-    // Enum values have nothing that can reference them outside of their parents
-    // TODO: that's actually only semi-true if you include arguments, because default values in args and concrete directive applications can
-    //   indirectly refer to enum value. It's indirect though as we currently keep enum value as string in values. That said, it would
-    //   probably be really nice to be able to known if an enum value is used or not, rather then removing it and not knowing if we broke
-    //   something).
+    this._extension = undefined;
     return [];
   }
 
@@ -2552,22 +2762,35 @@ export class DirectiveDefinition<TApplicationArgs extends {[key: string]: any} =
     assert(false, `Directive definition ${this} can't reference other types (it's arguments can); shouldn't be asked to remove reference to ${type}`);
   }
 
+    /**
+   * Removes this directive definition from its parent schema.
+   *
+   * After calling this method, this directive definition will be "detached": it will have no parent, schema, or
+   * arguments.
+   */
   remove(): Directive[] {
     if (!this._parent) {
       return [];
     }
+    this.checkRemoval();
     this.onModification();
-    Schema.prototype['removeDirectiveInternal'].call(this._parent, this);
-    this._parent = undefined;
+    // Remove this directive definition's children.
+    this.sourceAST = undefined;
     assert(this._appliedDirectives.length === 0, "Directive definition should not have directive applied to it");
     for (const arg of this.arguments()) {
       arg.remove();
     }
-    // Note that directive applications don't link directly to their definitions. Instead, we fetch
-    // their definition from the schema when requested. So we don't have to do anything on the referencers
-    // other than return them.
+    // Remove this directive definition's references.
+    //
+    // Note that while a directive application references its definition, it
+    // doesn't store a link to that definition. Instead, we fetch the definition
+    // from the schema when requested. So we don't have to do anything on the
+    // referencers other than clear them (and return the pre-cleared set).
     const toReturn = setValues(this._referencers);
     this._referencers.clear();
+    // Remove this directive definition from its parent schema.
+    Schema.prototype['removeDirectiveInternal'].call(this._parent, this);
+    this._parent = undefined;
     return toReturn;
   }
 
@@ -2711,9 +2934,9 @@ export class Directive<
     this.onModification();
     const coreFeatures = this.schema().coreFeatures;
     if (coreFeatures && this.name === coreFeatures.coreItself.nameInSchema) {
-      // We're removing a @core directive application, so we remove it from the list of core features. And
+      // We're removing a @core/@link directive application, so we remove it from the list of core features. And
       // if it is @core itself, we clean all features (to avoid having things too inconsistent).
-      const url = FeatureUrl.parse(this._args['feature']!);
+      const url = FeatureUrl.parse(this._args[coreFeatures.coreDefinition.urlArgName()]!);
       if (url.identity === coreFeatures.coreItself.url.identity) {
         // Note that we unmark first because the loop after that will nuke our parent.
         Schema.prototype['unmarkAsCoreSchema'].call(this.schema());
@@ -2733,10 +2956,12 @@ export class Directive<
     if (!this._parent) {
       return false;
     }
+    // Remove this directive application's reference to its definition.
     const definition = this.definition;
     if (definition && this.isAttachedToSchemaElement()) {
       DirectiveDefinition.prototype['removeReferencer'].call(definition, this as Directive<SchemaElement<any, any>>);
     }
+    // Remove this directive application from its parent schema element.
     const parentDirectives = this._parent.appliedDirectives as Directive<TParent>[];
     const index = parentDirectives.indexOf(this);
     assert(index >= 0, () => `Directive ${this} lists ${this._parent} as parent, but that parent doesn't list it as applied directive`);