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

package/src/definitions.ts

@@ -39,6 +39,8 @@ 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';
 
@@ -505,7 +507,10 @@ export abstract class SchemaElement<TOwnType extends SchemaElement<any, TParent>
         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}"`);
+          throw this.schema().blueprint.onGraphQLJSValidationError(
+            this.schema(),
+            new GraphQLError(`Unknown directive "@${nameOrDefOrDirective}".`)
+          );
         }
         name = nameOrDefOrDirective;
       } else {
@@ -857,6 +862,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();
@@ -873,7 +910,8 @@ export class CoreFeature {
 
   isFeatureDefinition(element: NamedType | DirectiveDefinition): boolean {
     return element.name.startsWith(this.nameInSchema + '__')
-      || (element.kind === 'DirectiveDefinition' && element.name === this.nameInSchema);
+      || (element.kind === 'DirectiveDefinition' && element.name === this.nameInSchema)
+      || !!this.imports.find((i) => element.name === (i.as ?? i.name));
   }
 
   directiveNameInSchema(name: string): string {
@@ -931,7 +969,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);
@@ -995,6 +1033,10 @@ const graphQLBuiltInDirectivesSpecifications: readonly DirectiveSpecification[]
   }),
 ];
 
+
+// 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>();
@@ -1311,7 +1353,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 +1406,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> {
@@ -1403,7 +1495,7 @@ 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);
     } else if (coreFeatures) {
@@ -2711,9 +2803,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());

package/src/error.ts

@@ -105,6 +105,34 @@ export function errorCodeDef(e: GraphQLError | string): ErrorCodeDefinition | un
   return code ? codeDefByCode[code] : undefined;
 }
 
+export function withModifiedErrorMessage(e: GraphQLError, newMessage: string): GraphQLError {
+  return new GraphQLError(
+    newMessage,
+    {
+      nodes: e.nodes,
+      source: e.source,
+      positions: e.positions,
+      path: e.path,
+      originalError: e.originalError,
+      extensions: e.extensions
+    }
+  );
+}
+
+export function withModifiedErrorNodes(e: GraphQLError, newNodes: readonly ASTNode[] | ASTNode | undefined): GraphQLError {
+  return new GraphQLError(
+    e.message,
+    {
+      nodes: newNodes,
+      source: e.source,
+      positions: e.positions,
+      path: e.path,
+      originalError: e.originalError,
+      extensions: e.extensions
+    }
+  );
+}
+
 const INVALID_GRAPHQL = makeCodeDefinition(
   'INVALID_GRAPHQL',
   'A schema is invalid GraphQL: it violates one of the rule of the specification.'
@@ -252,6 +280,11 @@ const EXTERNAL_ON_INTERFACE = makeCodeDefinition(
   'The field of an interface type is marked with `@external`: as external is about marking field not resolved by the subgraph and as interface field are not resolved (only implementations of those fields are), an "external" interface field is nonsensical',
 );
 
+const MERGED_DIRECTIVE_APPLICATION_ON_EXTERNAL = makeCodeDefinition(
+  'MERGED_DIRECTIVE_APPLICATION_ON_EXTERNAL',
+  'In a subgraph, a field is both marked @external and has a merged directive applied to it',
+);
+
 const FIELD_TYPE_MISMATCH = makeCodeDefinition(
   'FIELD_TYPE_MISMATCH',
   'A field has a type that is incompatible with other declarations of that field in other subgraphs.',
@@ -306,6 +339,16 @@ const INVALID_LINK_DIRECTIVE_USAGE = makeCodeDefinition(
   'An application of the @link directive is invalid/does not respect the specification.'
 );
 
+const LINK_IMPORT_NAME_MISMATCH = makeCodeDefinition(
+  'LINK_IMPORT_NAME_MISMATCH',
+  'The import name for a merged directive (as declared by the relevant `@link(import:)` argument) is inconsistent between subgraphs.'
+);
+
+const REFERENCED_INACCESSIBLE = makeCodeDefinition(
+  'REFERENCED_INACCESSIBLE',
+  'An element is marked as @inaccessible but is referenced by a non-inaccessible element.'
+);
+
 const REQUIRED_ARGUMENT_MISSING_IN_SOME_SUBGRAPH = makeCodeDefinition(
   'REQUIRED_ARGUMENT_MISSING_IN_SOME_SUBGRAPH',
   'An argument of a field or directive definition is mandatory in some subgraphs, but the argument is not defined in all subgraphs that define the field or directive definition.'
@@ -360,6 +403,7 @@ export const ERRORS = {
   EXTERNAL_ARGUMENT_TYPE_MISMATCH,
   EXTERNAL_ARGUMENT_DEFAULT_MISMATCH,
   EXTERNAL_ON_INTERFACE,
+  MERGED_DIRECTIVE_APPLICATION_ON_EXTERNAL,
   FIELD_TYPE_MISMATCH,
   ARGUMENT_TYPE_MISMATCH,
   INPUT_FIELD_DEFAULT_MISMATCH,
@@ -370,6 +414,8 @@ export const ERRORS = {
   INTERFACE_FIELD_IMPLEM_TYPE_MISMATCH,
   INVALID_FIELD_SHARING,
   INVALID_LINK_DIRECTIVE_USAGE,
+  LINK_IMPORT_NAME_MISMATCH,
+  REFERENCED_INACCESSIBLE,
   REQUIRED_ARGUMENT_MISSING_IN_SOME_SUBGRAPH,
   SATISFIABILITY_ERROR,
 };

package/src/federation.ts

@@ -50,6 +50,7 @@ import {
   ErrorCodeDefinition,
   ERROR_CATEGORIES,
   ERRORS,
+  withModifiedErrorMessage,
 } from "./error";
 import { computeShareables } from "./sharing";
 import {
@@ -71,10 +72,14 @@ import {
   extendsDirectiveSpec,
   shareableDirectiveSpec,
   tagDirectiveSpec,
+  inaccessibleDirectiveSpec,
   FEDERATION2_SPEC_DIRECTIVES,
+  ALL_FEDERATION_DIRECTIVES_DEFAULT_NAMES,
+  FEDERATION2_ONLY_SPEC_DIRECTIVES,
 } from "./federationSpec";
 import { defaultPrintOptions, PrintOptions as PrintOptions, printSchema } from "./print";
 import { createObjectTypeSpecification, createScalarTypeSpecification, createUnionTypeSpecification } from "./directiveAndTypeSpecification";
+import { didYouMean, suggestionList } from "./suggestions";
 
 const linkSpec = LINK_VERSIONS.latest();
 const tagSpec = TAG_VERSIONS.latest();
@@ -102,6 +107,7 @@ const FEDERATION_SPECIFIC_VALIDATION_RULES = [
 
 const FEDERATION_VALIDATION_RULES = specifiedSDLRules.filter(rule => !FEDERATION_OMITTED_VALIDATION_RULES.includes(rule)).concat(FEDERATION_SPECIFIC_VALIDATION_RULES);
 
+
 // Returns a list of the coordinate of all the fields in the selection that are marked external.
 function validateFieldSetSelections(
   directiveName: string,
@@ -417,16 +423,6 @@ function formatFieldsToReturnType([type, implems]: [string, FieldDefinition<Obje
   return `${joinStrings(implems.map(printFieldCoordinate))} ${implems.length == 1 ? 'has' : 'have'} type "${type}"`;
 }
 
-function checkIfFed2Schema(schema: Schema): boolean {
-  const core = schema.coreFeatures;
-  if (!core) {
-    return false
-  }
-
-  const federationFeature = core.getByIdentity(federationSpec.identity);
-  return !!federationFeature && federationFeature.url.version.satisfies(new FeatureVersion(2, 0));
-}
-
 export class FederationMetadata {
   private _externalTester?: ExternalTester;
   private _sharingPredicate?: (field: FieldDefinition<CompositeType>) => boolean;
@@ -443,11 +439,16 @@ export class FederationMetadata {
 
   isFed2Schema(): boolean {
     if (!this._isFed2Schema) {
-      this._isFed2Schema = checkIfFed2Schema(this.schema);
+      const feature = this.federationFeature();
+      this._isFed2Schema = !!feature && feature.url.version.satisfies(new FeatureVersion(2, 0))
     }
     return this._isFed2Schema;
   }
 
+  federationFeature(): CoreFeature | undefined {
+    return this.schema.coreFeatures?.getByIdentity(federationSpec.identity);
+  }
+
   private externalTester(): ExternalTester {
     if (!this._externalTester) {
       this._externalTester = new ExternalTester(this.schema);
@@ -557,6 +558,10 @@ export class FederationMetadata {
     return this.getFederationDirective(tagDirectiveSpec.name);
   }
 
+  inaccessibleDirective(): DirectiveDefinition<{}> {
+    return this.getFederationDirective(inaccessibleDirectiveSpec.name);
+  }
+
   allFederationDirectives(): DirectiveDefinition[] {
     const baseDirectives = [
       this.keyDirective(),
@@ -567,7 +572,7 @@ export class FederationMetadata {
       this.extendsDirective(),
     ];
     return this.isFed2Schema()
-      ? baseDirectives.concat(this.shareableDirective())
+      ? baseDirectives.concat(this.shareableDirective(), this.inaccessibleDirective())
       : baseDirectives;
   }
 
@@ -769,6 +774,52 @@ export class FederationBlueprint extends SchemaBlueprint {
   validationRules(): readonly SDLValidationRule[] {
     return FEDERATION_VALIDATION_RULES;
   }
+
+  onUnknownDirectiveValidationError(schema: Schema, unknownDirectiveName: string, error: GraphQLError): GraphQLError {
+    const metadata = federationMetadata(schema);
+    assert(metadata, `This method should only have been called on a subgraph schema`)
+    if (ALL_FEDERATION_DIRECTIVES_DEFAULT_NAMES.includes(unknownDirectiveName)) {
+      // The directive name is "unknown" but it is a default federation directive name. So it means one of a few things
+      // happened:
+      //  1. it's a fed1 schema but the directive is a fed2 only one (only possible case for fed1 schema).
+      //  2. the directive has not been imported at all (so needs to be prefixed for it to work).
+      //  3. the directive has an `import`, but it's been aliased to another name.
+      if (metadata.isFed2Schema()) {
+        const federationFeature = metadata.federationFeature();
+        assert(federationFeature, 'Fed2 subgraph _must_ link to the federation feature')
+        const directiveNameInSchema = federationFeature.directiveNameInSchema(unknownDirectiveName);
+        console.log(`For ${unknownDirectiveName}, name in schema = ${directiveNameInSchema}`);
+        if (directiveNameInSchema.startsWith(federationFeature.nameInSchema + '__')) {
+          // There is no import for that directive
+          return withModifiedErrorMessage(
+            error,
+            `${error.message} If you meant the "@${unknownDirectiveName}" federation directive, you should use fully-qualified name "@${directiveNameInSchema}" or add "@${unknownDirectiveName}" to the \`import\` argument of the @link to the federation specification.`
+          );
+        } else {
+          // There's an import, but it's renamed
+          return withModifiedErrorMessage(
+            error,
+            `${error.message} If you meant the "@${unknownDirectiveName}" federation directive, you should use "@${directiveNameInSchema}" as it is imported under that name in the @link to the federation specification of this schema.`
+          );
+        }
+      } else {
+        return withModifiedErrorMessage(
+          error, 
+          `${error.message} If you meant the "@${unknownDirectiveName}" federation 2 directive, note that this schema is a federation 1 schema. To be a federation 2 schema, it needs to @link to the federation specifcation v2.`
+        );
+      }
+    } else if (!metadata.isFed2Schema()) {
+      // We could get here in the case where a fed1 schema has tried to use a fed2 directive but mispelled it.
+      const suggestions = suggestionList(unknownDirectiveName, FEDERATION2_ONLY_SPEC_DIRECTIVES.map((spec) => spec.name));
+      if (suggestions.length > 0) {
+        return withModifiedErrorMessage(
+          error, 
+          `${error.message}${didYouMean(suggestions.map((s) => '@' + s))} If so, note that ${suggestions.length === 1 ? 'it is a federation 2 directive' : 'they are federation 2 directives'} but this schema is a federation 1 one. To be a federation 2 schema, it needs to @link to the federation specifcation v2.`
+        );
+      }
+    }
+    return error;
+  }
 }
 
 const federationBlueprint = new FederationBlueprint();
@@ -817,6 +868,10 @@ export function setSchemaAsFed2Subgraph(schema: Schema) {
   completeSubgraphSchema(schema);
 }
 
+// This is the full @link declaration as added by `asFed2SubgraphDocument`. It's here primarily for uses by tests that print and match
+// subgraph schema to avoid having to update 20+ tests every time we use a new directive or the order of import changes ...
+export const FEDERATION2_LINK_WTH_FULL_IMPORTS = '@link(url: "https://specs.apollo.dev/federation/v2.0", import: ["@key", "@requires", "@provides", "@external", "@tag", "@extends", "@shareable", "@inaccessible"])';
+
 export function asFed2SubgraphDocument(document: DocumentNode): DocumentNode {
   const fed2LinkExtension: SchemaExtensionNode = {
     kind: Kind.SCHEMA_EXTENSION,

package/src/federationSpec.ts

@@ -13,6 +13,8 @@ import { DirectiveLocation } from "graphql";
 import { assert } from "./utils";
 import { tagLocations } from "./tagSpec";
 import { federationMetadata } from "./federation";
+import { registerKnownFeature } from "./knownCoreFeatures";
+import { inaccessibleLocations } from "./inaccessibleSpec";
 
 export const federationIdentity = 'https://specs.apollo.dev/federation';
 
@@ -62,11 +64,17 @@ export const shareableDirectiveSpec = createDirectiveSpecification({
 export const tagDirectiveSpec = createDirectiveSpecification({
   name:'tag',
   locations: tagLocations,
+  repeatable: true,
   argumentFct: (schema) => {
     return [{ name: 'name', type: new NonNullType(schema.stringType()) }];
   }
 });
 
+export const inaccessibleDirectiveSpec = createDirectiveSpecification({
+  name:'inaccessible',
+  locations: inaccessibleLocations,
+});
+
 function fieldsArgument(schema: Schema): ArgumentSpecification {
   return { name: 'fields', type: fieldSetType(schema) };
 }
@@ -77,17 +85,27 @@ function fieldSetType(schema: Schema): InputType {
   return new NonNullType(metadata.fieldSetType());
 }
 
+export const FEDERATION2_ONLY_SPEC_DIRECTIVES = [
+  shareableDirectiveSpec,
+  inaccessibleDirectiveSpec,
+];
+
 // Note that this is only used for federation 2+ (federation 1 adds the same directive, but not through a core spec).
 export const FEDERATION2_SPEC_DIRECTIVES = [
   keyDirectiveSpec,
   requiresDirectiveSpec,
   providesDirectiveSpec,
   externalDirectiveSpec,
-  shareableDirectiveSpec,
   tagDirectiveSpec,
   extendsDirectiveSpec, // TODO: should we stop supporting that?
+  ...FEDERATION2_ONLY_SPEC_DIRECTIVES,
 ];
 
+// Note that this is meant to contain _all_ federation directive names ever supported, regardless of which version.
+// But currently, fed2 directives are a superset of fed1's so ... (but this may change if we stop supporting `@extends`
+// in fed2).
+export const ALL_FEDERATION_DIRECTIVES_DEFAULT_NAMES = FEDERATION2_SPEC_DIRECTIVES.map((spec) => spec.name);
+
 export const FEDERATION_SPEC_TYPES = [
   fieldSetTypeSpec,
 ]
@@ -107,7 +125,15 @@ export class FederationSpecDefinition extends FeatureDefinition {
       directive.checkOrAdd(schema, feature.directiveNameInSchema(directive.name));
     }
   }
+
+  allElementNames(): string[] {
+    return FEDERATION2_SPEC_DIRECTIVES.map((spec) => `@${spec.name}`).concat([
+      fieldSetTypeSpec.name,
+    ])
+  }
 }
 
 export const FEDERATION_VERSIONS = new FeatureDefinitions<FederationSpecDefinition>(federationIdentity)
   .add(new FederationSpecDefinition(new FeatureVersion(2, 0)));
+
+registerKnownFeature(FEDERATION_VERSIONS);

package/src/inaccessibleSpec.ts

@@ -8,31 +8,41 @@ import {
   Schema,
 } from "./definitions";
 import { GraphQLError, DirectiveLocation } from "graphql";
+import { registerKnownFeature } from "./knownCoreFeatures";
+import { ERRORS } from "./error";
 
 export const inaccessibleIdentity = 'https://specs.apollo.dev/inaccessible';
 
+export const inaccessibleLocations = [
+  DirectiveLocation.FIELD_DEFINITION,
+  DirectiveLocation.OBJECT,
+  DirectiveLocation.INTERFACE,
+  DirectiveLocation.UNION,
+];
+
 export class InaccessibleSpecDefinition extends FeatureDefinition {
   constructor(version: FeatureVersion) {
     super(new FeatureUrl(inaccessibleIdentity, 'inaccessible', version));
   }
 
   addElementsToSchema(schema: Schema) {
-    this.addDirective(schema, 'inaccessible').addLocations(
-      DirectiveLocation.FIELD_DEFINITION,
-      DirectiveLocation.OBJECT,
-      DirectiveLocation.INTERFACE,
-      DirectiveLocation.UNION,
-    );
+    this.addDirective(schema, 'inaccessible').addLocations(...inaccessibleLocations);
   }
 
   inaccessibleDirective(schema: Schema): DirectiveDefinition<Record<string, never>> {
     return this.directive(schema, 'inaccessible')!;
   }
+
+  allElementNames(): string[] {
+    return ['@inaccessible'];
+  }
 }
 
 export const INACCESSIBLE_VERSIONS = new FeatureDefinitions<InaccessibleSpecDefinition>(inaccessibleIdentity)
   .add(new InaccessibleSpecDefinition(new FeatureVersion(0, 1)));
 
+registerKnownFeature(INACCESSIBLE_VERSIONS);
+
 export function removeInaccessibleElements(schema: Schema) {
   const coreFeatures = schema.coreFeatures;
   if (!coreFeatures) {
@@ -69,10 +79,16 @@ export function removeInaccessibleElements(schema: Schema) {
         // field type will be `undefined`).
         if (reference.kind === 'FieldDefinition') {
           if (!reference.hasAppliedDirective(inaccessibleDirective)) {
-            throw new GraphQLError(
-              `Field ${reference.coordinate} returns an @inaccessible type without being marked @inaccessible itself.`,
-              reference.sourceAST,
-            );
+            // We ship the inaccessible type and it's invalid reference in the extensions so composition can extract those and add proper links
+            // in the subgraphs for those elements.
+            throw ERRORS.REFERENCED_INACCESSIBLE.err({
+              message: `Field "${reference.coordinate}" returns @inaccessible type "${type}" without being marked @inaccessible itself.`,
+              nodes: reference.sourceAST,
+              extensions: {
+                "inaccessible_element": type.coordinate,
+                "inaccessible_reference": reference.coordinate,
+              }
+            });
           }
         }
         // Other references can be:

package/src/index.ts

@@ -10,6 +10,7 @@ export * from './debug';
 export * from './coreSpec';
 export * from './joinSpec';
 export * from './tagSpec';
+export * from './inaccessibleSpec';
 export * from './federationSpec';
 export * from './supergraphs';
 export * from './extractSubgraphsFromSupergraph';

package/src/joinSpec.ts

@@ -8,6 +8,7 @@ import {
   NonNullType,
 } from "./definitions";
 import { Subgraph, Subgraphs } from "./federation";
+import { registerKnownFeature } from './knownCoreFeatures';
 import { MultiMap } from "./utils";
 
 export const joinIdentity = 'https://specs.apollo.dev/join';
@@ -90,6 +91,22 @@ export class JoinSpecDefinition extends FeatureDefinition {
     }
   }
 
+  allElementNames(): string[] {
+    const names = [
+      'graph',
+      'Graph',
+      'FieldSet',
+      '@type',
+      '@field',
+    ];
+    if (this.isV01()) {
+      names.push('@owner');
+    } else {
+      names.push('@implements');
+    }
+    return names;
+  }
+
   populateGraphEnum(schema: Schema, subgraphs: Subgraphs): Map<string, string> {
     // Duplicate enum values can occur due to sanitization and must be accounted for
     // collect the duplicates in an array so we can uniquify them in a second pass.
@@ -160,3 +177,5 @@ export class JoinSpecDefinition extends FeatureDefinition {
 export const JOIN_VERSIONS = new FeatureDefinitions<JoinSpecDefinition>(joinIdentity)
   .add(new JoinSpecDefinition(new FeatureVersion(0, 1)))
   .add(new JoinSpecDefinition(new FeatureVersion(0, 2)));
+
+registerKnownFeature(JOIN_VERSIONS);

package/src/knownCoreFeatures.ts

@@ -0,0 +1,13 @@
+import { FeatureDefinition, FeatureDefinitions, FeatureUrl } from "./coreSpec";
+
+const registeredFeatures: Map<string, FeatureDefinitions> = new Map();
+
+export function registerKnownFeature(definitions: FeatureDefinitions) {
+  if (!registeredFeatures.has(definitions.identity)) {
+    registeredFeatures.set(definitions.identity, definitions);
+  }
+}
+
+export function coreFeatureDefinitionIfKnown(url: FeatureUrl): FeatureDefinition | undefined {
+  return registeredFeatures.get(url.identity)?.find(url.version);
+}

package/src/tagSpec.ts

@@ -2,6 +2,7 @@ import { DirectiveLocation, GraphQLError } from "graphql";
 import { FeatureDefinition, FeatureDefinitions, FeatureUrl, FeatureVersion } from "./coreSpec";
 import { DirectiveDefinition, NonNullType, Schema } from "./definitions";
 import { ERRORS } from "./error";
+import { registerKnownFeature } from "./knownCoreFeatures";
 import { sameType } from "./types";
 
 export const tagIdentity = 'https://specs.apollo.dev/tag';
@@ -22,6 +23,7 @@ export class TagSpecDefinition extends FeatureDefinition {
 
   addElementsToSchema(schema: Schema) {
     const directive = this.addDirective(schema, 'tag').addLocations(...tagLocations);
+    directive.repeatable = true;
     directive.addArgument("name", new NonNullType(schema.stringType()));
   }
 
@@ -42,7 +44,13 @@ export class TagSpecDefinition extends FeatureDefinition {
     }
     return undefined;
   }
+
+  allElementNames(): string[] {
+    return ["@tag"];
+  }
 }
 
 export const TAG_VERSIONS = new FeatureDefinitions<TagSpecDefinition>(tagIdentity)
   .add(new TagSpecDefinition(new FeatureVersion(0, 1)));
+
+registerKnownFeature(TAG_VERSIONS);