@apollo/federation-internals 2.0.0-preview.8 → 2.0.1

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";
@@ -43,10 +43,19 @@ 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
   });
 
@@ -56,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];
@@ -213,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;
 }
@@ -382,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
@@ -491,37 +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 this.schema().blueprint.onGraphQLJSValidationError(
-            this.schema(),
-            new GraphQLError(`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;
@@ -699,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
@@ -715,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;
   }
@@ -828,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 {
@@ -909,9 +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)
-      || !!this.imports.find((i) => element.name === (i.as ?? i.name));
+      || !!this.imports.find((i) => importName === (i.as ?? i.name));
   }
 
   directiveNameInSchema(name: string): string {
@@ -1014,22 +1045,22 @@ 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: [] })
   }),
 ];
 
@@ -1126,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;
@@ -1160,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) {
@@ -1183,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());
   }
 
   /**
@@ -1482,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)) {
@@ -1498,6 +1546,10 @@ export class SchemaDefinition extends SchemaElement<SchemaDefinition, Schema>  {
       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);
     }
@@ -2006,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 {
@@ -2305,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 [];
   }
 
@@ -2384,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 [];
   }
 
@@ -2442,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 [];
   }
 
@@ -2498,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 [];
   }
 
@@ -2644,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;
   }
 
@@ -2825,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`);