@apollo/federation-internals 2.4.10 → 2.5.0

package/src/federation.ts

@@ -68,6 +68,9 @@ import {
   linkDirectiveDefaultName,
   linkIdentity,
   FeatureUrl,
+  CoreImport,
+  extractCoreFeatureImports,
+  CoreOrLinkDirectiveArgs,
 } from "./coreSpec";
 import {
   FEDERATION_VERSIONS,
@@ -86,6 +89,9 @@ import { joinIdentity } from "./joinSpec";
 const linkSpec = LINK_VERSIONS.latest();
 const tagSpec = TAG_VERSIONS.latest();
 const federationSpec = FEDERATION_VERSIONS.latest();
+// Some users rely on auto-expanding fed v1 graphs with fed v2 directives. While technically we should only expand @tag
+// directive from v2 definitions, we will continue expanding other directives (up to v2.4) to ensure backwards compatibility.
+const autoExpandedFederationSpec = FEDERATION_VERSIONS.find(new FeatureVersion(2, 4))!;
 
 // We don't let user use this as a subgraph name. That allows us to use it in `query graphs` to name the source of roots
 // in the "federated query graph" without worrying about conflict (see `FEDERATED_GRAPH_ROOT_SOURCE` in `querygraph.ts`).
@@ -112,6 +118,24 @@ const FEDERATION_SPECIFIC_VALIDATION_RULES = [
 const FEDERATION_VALIDATION_RULES = specifiedSDLRules.filter(rule => !FEDERATION_OMITTED_VALIDATION_RULES.includes(rule)).concat(FEDERATION_SPECIFIC_VALIDATION_RULES);
 
 const ALL_DEFAULT_FEDERATION_DIRECTIVE_NAMES: string[] = Object.values(FederationDirectiveName);
+
+/**
+ * Federation 1 has that specificity that it wasn't using @link to name-space federation elements,
+ * and so to "distinguish" the few federation type names, it prefixed those with a `_`. That is,
+ * the `FieldSet` type was named `_FieldSet` in federation1. To handle this without too much effort,
+ * we use a fake `CoreFeature` with imports for all the fed1 types to use those specific "aliases"
+ * and we pass it when adding those types. This allows to reuse the same `TypeSpecification` objects
+ * for both fed1 and fed2. Note that in the object below, all that is used is the imports, the rest
+ * is just filling the blanks.
+ */
+const FAKE_FED1_CORE_FEATURE_TO_RENAME_TYPES: CoreFeature = new CoreFeature(
+  new FeatureUrl('<fed1>', 'fed1', new FeatureVersion(0, 1)),
+  'fed1',
+  new Directive('fed1'),
+  FEDERATION1_TYPES.map((spec) => ({ name: spec.name, as: '_' + spec.name})),
+);
+
+
 function validateFieldSetSelections({
   directiveName,
   selectionSet,
@@ -738,6 +762,14 @@ export class FederationMetadata {
     return this.getPost20FederationDirective(FederationDirectiveName.INTERFACE_OBJECT);
   }
 
+  authenticatedDirective(): Post20FederationDirectiveDefinition<{}> {
+    return this.getPost20FederationDirective(FederationDirectiveName.AUTHENTICATED);
+  }
+
+  requiresScopesDirective(): Post20FederationDirectiveDefinition<{scopes: string[]}> {
+    return this.getPost20FederationDirective(FederationDirectiveName.REQUIRES_SCOPES);
+  }
+
   allFederationDirectives(): DirectiveDefinition[] {
     const baseDirectives: DirectiveDefinition[] = [
       this.keyDirective(),
@@ -763,6 +795,16 @@ export class FederationMetadata {
       baseDirectives.push(interfaceObjectDirective);
     }
 
+    const authenticatedDirective = this.authenticatedDirective();
+    if (isFederationDirectiveDefinedInSchema(authenticatedDirective)) {
+      baseDirectives.push(authenticatedDirective);
+    }
+
+    const requiresScopesDirective = this.requiresScopesDirective();
+    if (isFederationDirectiveDefinedInSchema(requiresScopesDirective)) {
+      baseDirectives.push(requiresScopesDirective);
+    }
+
     return baseDirectives;
   }
 
@@ -784,16 +826,33 @@ export class FederationMetadata {
   }
 
   allFederationTypes(): NamedType[] {
-    const baseTypes: NamedType[] = [
+    // We manually include the `_Any`, `_Service` and `Entity` types because there are not strictly
+    // speaking part of the federation @link spec.
+    const fedTypes: NamedType[] = [
       this.anyType(),
       this.serviceType(),
-      this.fieldSetType(),
     ];
+
+    const fedFeature = this.federationFeature();
+    if (fedFeature) {
+      const featureDef = FEDERATION_VERSIONS.find(fedFeature.url.version);
+      assert(featureDef, () => `Federation spec should be known, but got ${fedFeature.url}`);
+      for (const typeSpec of featureDef.typeSpecs()) {
+        const type = this.schema.type(fedFeature.typeNameInSchema(typeSpec.name));
+        if (type) {
+          fedTypes.push(type);
+        }
+      }
+    } else {
+      // Fed1: the only type we had was _FieldSet.
+      fedTypes.push(this.fieldSetType());
+    }
+
     const entityType = this.entityType();
     if (entityType) {
-      baseTypes.push(entityType);
+      fedTypes.push(entityType);
     }
-    return baseTypes;
+    return fedTypes;
   }
 }
 
@@ -831,14 +890,20 @@ export class FederationBlueprint extends SchemaBlueprint {
     }
   }
 
-  onMissingDirectiveDefinition(schema: Schema, name: string, args?: {[key: string]: any}): DirectiveDefinition | GraphQLError[] | undefined {
-    if (name === linkDirectiveDefaultName) {
+  onMissingDirectiveDefinition(schema: Schema, directive: Directive): DirectiveDefinition | GraphQLError[] | undefined {
+    if (directive.name === linkDirectiveDefaultName) {
+      const args = directive.arguments();
       const url = args && (args['url'] as string | undefined);
-      const as = url && url.startsWith(linkSpec.identity) ? (args['as'] as string | undefined) : undefined;
-      const errors = linkSpec.addDefinitionsToSchema(schema, as);
-      return errors.length > 0 ? errors : schema.directive(name);
+      let as: string | undefined = undefined;
+      let imports: CoreImport[] = [];
+      if (url && url.startsWith(linkSpec.identity)) {
+        as = args['as'] as string | undefined;
+        imports = extractCoreFeatureImports(linkSpec.url, directive as Directive<SchemaDefinition, CoreOrLinkDirectiveArgs>);
+      }
+      const errors = linkSpec.addDefinitionsToSchema(schema, as, imports);
+      return errors.length > 0 ? errors : schema.directive(directive.name);
     }
-    return super.onMissingDirectiveDefinition(schema, name, args);
+    return super.onMissingDirectiveDefinition(schema, directive);
   }
 
   ignoreParsedField(type: NamedType, fieldName: string): boolean {
@@ -1073,7 +1138,7 @@ function findUnusedNamedForLinkDirective(schema: Schema): string | undefined {
   // The schema already defines a directive named `@link` so we need to use an alias.
   // To keep it simple, we add a number in the end (so we try `@link1`, and if that's taken `@link2`, ...)
   const baseName = linkSpec.url.name;
-  let n = 1;
+  const n = 1;
   for (;;) {
     const candidate = baseName + n;
     if (!schema.directive(candidate)) {
@@ -1106,7 +1171,7 @@ export function setSchemaAsFed2Subgraph(schema: Schema) {
     core.coreItself.nameInSchema,
     {
       url: federationSpec.url.toString(),
-      import: federationSpec.directiveSpecs().map((spec) => `@${spec.name}`),
+      import: autoExpandedFederationSpec.directiveSpecs().map((spec) => `@${spec.name}`),
     }
   );
   const errors = completeSubgraphSchema(schema);
@@ -1117,7 +1182,9 @@ export function setSchemaAsFed2Subgraph(schema: 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_WITH_FULL_IMPORTS = '@link(url: "https://specs.apollo.dev/federation/v2.4", import: ["@key", "@requires", "@provides", "@external", "@tag", "@extends", "@shareable", "@inaccessible", "@override", "@composeDirective", "@interfaceObject"])';
+export const FEDERATION2_LINK_WITH_FULL_IMPORTS = '@link(url: "https://specs.apollo.dev/federation/v2.5", import: ["@key", "@requires", "@provides", "@external", "@tag", "@extends", "@shareable", "@inaccessible", "@override", "@composeDirective", "@interfaceObject", "@authenticated", "@requiresScopes"])';
+// This is the full @link declaration that is added when upgrading fed v1 subgraphs to v2 version. It should only be used by tests.
+export const FEDERATION2_LINK_WITH_AUTO_EXPANDED_IMPORTS = '@link(url: "https://specs.apollo.dev/federation/v2.5", import: ["@key", "@requires", "@provides", "@external", "@tag", "@extends", "@shareable", "@inaccessible", "@override", "@composeDirective", "@interfaceObject"])';
 
 /**
  * Given a document that is assumed to _not_ be a fed2 schema (it does not have a `@link` to the federation spec),
@@ -1126,8 +1193,11 @@ export const FEDERATION2_LINK_WITH_FULL_IMPORTS = '@link(url: "https://specs.apo
  * @param document - the document to "augment".
  * @param options.addAsSchemaExtension - defines whethere the added `@link` is added as a schema extension (`extend schema`) or
  *   added to the schema definition. Defaults to `true` (added as an extension), as this mimics what we tends to write manually.
+ * @param options.includeAllImports - defines whether we should auto import ALL latest federation v2 directive definitions or include
+ *   only limited set of directives (i.e. federation v2.4 definitions)
  */
-export function asFed2SubgraphDocument(document: DocumentNode, options?: { addAsSchemaExtension: boolean }): DocumentNode {
+export function asFed2SubgraphDocument(document: DocumentNode, options?: { addAsSchemaExtension?: boolean, includeAllImports?: boolean }): DocumentNode {
+  const importedDirectives = options?.includeAllImports ? federationSpec.directiveSpecs() : autoExpandedFederationSpec.directiveSpecs();
   const directiveToAdd: ConstDirectiveNode = ({
     kind: Kind.DIRECTIVE,
     name: { kind: Kind.NAME, value: linkDirectiveDefaultName },
@@ -1140,7 +1210,7 @@ export function asFed2SubgraphDocument(document: DocumentNode, options?: { addAs
       {
         kind: Kind.ARGUMENT,
         name: { kind: Kind.NAME, value: 'import' },
-        value: { kind: Kind.LIST, values: federationSpec.directiveSpecs().map((spec) => ({ kind: Kind.STRING, value: `@${spec.name}` })) }
+        value: { kind: Kind.LIST, values: importedDirectives.map((spec) => ({ kind: Kind.STRING, value: `@${spec.name}` })) }
       }
     ]
   });
@@ -1343,7 +1413,7 @@ function completeFed1SubgraphSchema(schema: Schema): GraphQLError[] {
     }
   }
 
-  const errors = FEDERATION1_TYPES.map((spec) => spec.checkOrAdd(schema, '_' + spec.name))
+  const errors = FEDERATION1_TYPES.map((spec) => spec.checkOrAdd(schema, FAKE_FED1_CORE_FEATURE_TO_RENAME_TYPES))
     .concat(FEDERATION1_DIRECTIVES.map((spec) => spec.checkOrAdd(schema)))
     .flat();
 
@@ -1681,6 +1751,15 @@ export class Subgraph {
     }
   }
 
+  /**
+   * Same as `Schema.assumeValid`. Use carefully.
+   */
+  assumeValid(): Subgraph {
+    this.addFederationOperations();
+    this.schema.assumeValid();
+    return this;
+  }
+
   validate(): Subgraph {
     try {
       this.addFederationOperations();

package/src/federationSpec.ts

@@ -15,6 +15,8 @@ import { TAG_VERSIONS } from "./tagSpec";
 import { federationMetadata } from "./federation";
 import { registerKnownFeature } from "./knownCoreFeatures";
 import { INACCESSIBLE_VERSIONS } from "./inaccessibleSpec";
+import { AUTHENTICATED_VERSIONS } from "./authenticatedSpec";
+import { REQUIRES_SCOPES_VERSIONS } from "./requiresScopesSpec";
 
 export const federationIdentity = 'https://specs.apollo.dev/federation';
 
@@ -34,6 +36,8 @@ export enum FederationDirectiveName {
   INACCESSIBLE = 'inaccessible',
   COMPOSE_DIRECTIVE = 'composeDirective',
   INTERFACE_OBJECT = 'interfaceObject',
+  AUTHENTICATED = 'authenticated',
+  REQUIRES_SCOPES = 'requiresScopes',
 }
 
 const fieldSetTypeSpec = createScalarTypeSpecification({ name: FederationTypeName.FIELD_SET });
@@ -116,7 +120,7 @@ export class FederationSpecDefinition extends FeatureDefinition {
       repeatable: version >= (new FeatureVersion(2, 2)),
     }));
 
-    this.registerDirective(INACCESSIBLE_VERSIONS.latest().inaccessibleDirectiveSpec);
+    this.registerSubFeature(INACCESSIBLE_VERSIONS.getMinimumRequiredVersion(version));
 
     this.registerDirective(createDirectiveSpecification({
       name: FederationDirectiveName.OVERRIDE,
@@ -138,9 +142,12 @@ export class FederationSpecDefinition extends FeatureDefinition {
         name: FederationDirectiveName.INTERFACE_OBJECT,
         locations: [DirectiveLocation.OBJECT],
       }));
-      this.registerDirective(
-        TAG_VERSIONS.find(new FeatureVersion(0, 3))!.tagDirectiveSpec
-      );
+      this.registerSubFeature(TAG_VERSIONS.find(new FeatureVersion(0, 3))!);
+    }
+
+    if (version >= (new FeatureVersion(2, 5))) {
+      this.registerSubFeature(AUTHENTICATED_VERSIONS.find(new FeatureVersion(0, 1))!);
+      this.registerSubFeature(REQUIRES_SCOPES_VERSIONS.find(new FeatureVersion(0, 1))!);
     }
   }
 }
@@ -150,6 +157,7 @@ export const FEDERATION_VERSIONS = new FeatureDefinitions<FederationSpecDefiniti
   .add(new FederationSpecDefinition(new FeatureVersion(2, 1)))
   .add(new FederationSpecDefinition(new FeatureVersion(2, 2)))
   .add(new FederationSpecDefinition(new FeatureVersion(2, 3)))
-  .add(new FederationSpecDefinition(new FeatureVersion(2, 4)));
+  .add(new FederationSpecDefinition(new FeatureVersion(2, 4)))
+  .add(new FederationSpecDefinition(new FeatureVersion(2, 5)));
 
 registerKnownFeature(FEDERATION_VERSIONS);

package/src/inaccessibleSpec.ts

@@ -39,8 +39,8 @@ export class InaccessibleSpecDefinition extends FeatureDefinition {
   public readonly inaccessibleDirectiveSpec: DirectiveSpecification;
   private readonly printedInaccessibleDefinition: string;
 
-  constructor(version: FeatureVersion) {
-    super(new FeatureUrl(inaccessibleIdentity, 'inaccessible', version));
+  constructor(version: FeatureVersion, minimumFederationVersion?: FeatureVersion) {
+    super(new FeatureUrl(inaccessibleIdentity, 'inaccessible', version), minimumFederationVersion);
     this.inaccessibleLocations = [
       DirectiveLocation.FIELD_DEFINITION,
       DirectiveLocation.OBJECT,
@@ -63,7 +63,7 @@ export class InaccessibleSpecDefinition extends FeatureDefinition {
       name: 'inaccessible',
       locations: this.inaccessibleLocations,
       composes: true,
-      supergraphSpecification: () => INACCESSIBLE_VERSIONS.latest(),
+      supergraphSpecification: (fedVersion) => INACCESSIBLE_VERSIONS.getMinimumRequiredVersion(fedVersion),
     });
     this.registerDirective(this.inaccessibleDirectiveSpec);
   }
@@ -95,7 +95,7 @@ export class InaccessibleSpecDefinition extends FeatureDefinition {
 
 export const INACCESSIBLE_VERSIONS = new FeatureDefinitions<InaccessibleSpecDefinition>(inaccessibleIdentity)
   .add(new InaccessibleSpecDefinition(new FeatureVersion(0, 1)))
-  .add(new InaccessibleSpecDefinition(new FeatureVersion(0, 2)));
+  .add(new InaccessibleSpecDefinition(new FeatureVersion(0, 2), new FeatureVersion(2, 0)));
 
 registerKnownFeature(INACCESSIBLE_VERSIONS);
 

package/src/index.ts

@@ -13,7 +13,6 @@ export * from './tagSpec';
 export * from './inaccessibleSpec';
 export * from './federationSpec';
 export * from './supergraphs';
-export * from './extractSubgraphsFromSupergraph';
 export * from './error';
 export * from './schemaUpgrader';
 export * from './suggestions';
@@ -21,3 +20,5 @@ export * from './graphQLJSSchemaToAST';
 export * from './directiveAndTypeSpecification';
 export { coreFeatureDefinitionIfKnown } from './knownCoreFeatures';
 export * from './argumentCompositionStrategies';
+export * from './authenticatedSpec';
+export * from './requiresScopesSpec';

package/src/joinSpec.ts

@@ -30,9 +30,27 @@ function sanitizeGraphQLName(name: string) {
   return toUpper;
 }
 
+export type JoinTypeDirectiveArguments = {
+  graph: string,
+  key?: string,
+  extension?: boolean,
+  resolvable?: boolean,
+  isInterfaceObject?: boolean
+};
+
+export type JoinFieldDirectiveArguments = {
+  graph?: string,
+  requires?: string,
+  provides?: string,
+  override?: string,
+  type?: string,
+  external?: boolean,
+  usedOverridden?: boolean,
+}
+
 export class JoinSpecDefinition extends FeatureDefinition {
-  constructor(version: FeatureVersion) {
-    super(new FeatureUrl(joinIdentity, 'join', version));
+  constructor(version: FeatureVersion, minimumFederationVersion?: FeatureVersion) {
+    super(new FeatureUrl(joinIdentity, 'join', version), minimumFederationVersion);
   }
 
   private isV01() {
@@ -174,7 +192,7 @@ export class JoinSpecDefinition extends FeatureDefinition {
     return this.directive(schema, 'graph')!;
   }
 
-  typeDirective(schema: Schema): DirectiveDefinition<{graph: string, key?: string, extension?: boolean, resolvable?: boolean, isInterfaceObject?: boolean}> {
+  typeDirective(schema: Schema): DirectiveDefinition<JoinTypeDirectiveArguments> {
     return this.directive(schema, 'type')!;
   }
 
@@ -182,15 +200,7 @@ export class JoinSpecDefinition extends FeatureDefinition {
     return this.directive(schema, 'implements');
   }
 
-  fieldDirective(schema: Schema): DirectiveDefinition<{
-    graph?: string,
-    requires?: string,
-    provides?: string,
-    override?: string,
-    type?: string,
-    external?: boolean,
-    usedOverridden?: boolean,
-  }> {
+  fieldDirective(schema: Schema): DirectiveDefinition<JoinFieldDirectiveArguments> {
     return this.directive(schema, 'field')!;
   }
 
@@ -220,6 +230,6 @@ 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)))
-  .add(new JoinSpecDefinition(new FeatureVersion(0, 3)));
+  .add(new JoinSpecDefinition(new FeatureVersion(0, 3), new FeatureVersion(2, 0)));
 
 registerKnownFeature(JOIN_VERSIONS);

package/src/precompute.ts

@@ -20,7 +20,7 @@ export function computeShareables(schema: Schema): (field: FieldDefinition<Compo
   // by default are key fields).
   const shareableDirective = metadata.isFed2Schema() ? metadata.shareableDirective() : undefined;
 
-  const shareableFields: Set<String> = new Set();
+  const shareableFields: Set<string> = new Set();
   const addKeyFields = (type: CompositeType) => {
     for (const key of type.appliedDirectivesOf(keyDirective)) {
       collectTargetFields({

package/src/requiresScopesSpec.ts

@@ -0,0 +1,76 @@
+import { DirectiveLocation } from "graphql";
+import {
+  CorePurpose,
+  FeatureDefinition,
+  FeatureDefinitions,
+  FeatureUrl,
+  FeatureVersion,
+} from "./coreSpec";
+import { DirectiveDefinition, ListType, NonNullType, Schema } from "./definitions";
+import { createDirectiveSpecification, createScalarTypeSpecification } from "./directiveAndTypeSpecification";
+import { registerKnownFeature } from "./knownCoreFeatures";
+import { ARGUMENT_COMPOSITION_STRATEGIES } from "./argumentCompositionStrategies";
+import { assert } from "./utils";
+
+export enum RequiresScopesTypeName {
+  SCOPE = 'Scope',
+}
+
+export class RequiresScopesSpecDefinition extends FeatureDefinition {
+  public static readonly directiveName = "requiresScopes";
+  public static readonly identity =
+    `https://specs.apollo.dev/${RequiresScopesSpecDefinition.directiveName}`;
+
+  constructor(version: FeatureVersion) {
+    super(
+      new FeatureUrl(
+        RequiresScopesSpecDefinition.identity,
+        RequiresScopesSpecDefinition.directiveName,
+        version,
+      )
+    );
+
+    this.registerType(createScalarTypeSpecification({ name: RequiresScopesTypeName.SCOPE }));
+
+    this.registerDirective(createDirectiveSpecification({
+      name: RequiresScopesSpecDefinition.directiveName,
+      args: [{
+        name: 'scopes',
+        type: (schema, feature) => {
+          assert(feature, "Shouldn't be added without being attached to a @link spec");
+          const scopeName = feature.typeNameInSchema(RequiresScopesTypeName.SCOPE);
+          const scopeType = schema.type(scopeName);
+          assert(scopeType, () => `Expected "${scopeName}" to be defined`);
+          return new NonNullType(new ListType(new NonNullType(scopeType)));
+        },
+        compositionStrategy: ARGUMENT_COMPOSITION_STRATEGIES.UNION,
+      }],
+      locations: [
+        DirectiveLocation.FIELD_DEFINITION,
+        DirectiveLocation.OBJECT,
+        DirectiveLocation.INTERFACE,
+        DirectiveLocation.SCALAR,
+        DirectiveLocation.ENUM,
+      ],
+      composes: true,
+      supergraphSpecification: () => REQUIRES_SCOPES_VERSIONS.latest(),
+    }));
+  }
+
+  requiresScopesDirective(
+    schema: Schema
+  ): DirectiveDefinition<{ name: string }> {
+    return this.directive(schema, RequiresScopesSpecDefinition.directiveName)!;
+  }
+
+  get defaultCorePurpose(): CorePurpose {
+    return 'SECURITY';
+  }
+}
+
+export const REQUIRES_SCOPES_VERSIONS =
+  new FeatureDefinitions<RequiresScopesSpecDefinition>(
+    RequiresScopesSpecDefinition.identity
+  ).add(new RequiresScopesSpecDefinition(new FeatureVersion(0, 1)));
+
+registerKnownFeature(REQUIRES_SCOPES_VERSIONS);

package/src/supergraphs.ts

@@ -3,10 +3,11 @@ import { ErrCoreCheckFailed, FeatureUrl, FeatureVersion } from "./coreSpec";
 import { CoreFeatures, Schema, sourceASTs } from "./definitions";
 import { joinIdentity, JoinSpecDefinition, JOIN_VERSIONS } from "./joinSpec";
 import { buildSchema, buildSchemaFromAST } from "./buildSchema";
-import { extractSubgraphsNamesAndUrlsFromSupergraph } from "./extractSubgraphsFromSupergraph";
+import { extractSubgraphsNamesAndUrlsFromSupergraph, extractSubgraphsFromSupergraph } from "./extractSubgraphsFromSupergraph";
 import { ERRORS } from "./error";
+import { Subgraphs } from ".";
 
-const SUPPORTED_FEATURES = new Set([
+export const DEFAULT_SUPPORTED_SUPERGRAPH_FEATURES = new Set([
   'https://specs.apollo.dev/core/v0.1',
   'https://specs.apollo.dev/core/v0.2',
   'https://specs.apollo.dev/join/v0.1',
@@ -21,24 +22,12 @@ const SUPPORTED_FEATURES = new Set([
 
 const coreVersionZeroDotOneUrl = FeatureUrl.parse('https://specs.apollo.dev/core/v0.1');
 
-export function buildSupergraphSchema(supergraphSdl: string | DocumentNode): [Schema, {name: string, url: string}[]] {
-  // We delay validation because `checkFeatureSupport` gives slightly more useful errors if, say, 'for' is used with core v0.1.
-  const schema = typeof supergraphSdl === 'string'
-    ? buildSchema(supergraphSdl, { validate: false })
-    : buildSchemaFromAST(supergraphSdl, { validate: false });
-
-  const [coreFeatures] = validateSupergraph(schema);
-  checkFeatureSupport(coreFeatures);
-  schema.validate();
-  return [schema, extractSubgraphsNamesAndUrlsFromSupergraph(schema)];
-}
-
 /**
  * Checks that only our hard-coded list of features are part of the provided schema, and that if
  * the schema uses core v0.1, then it doesn't use the 'for' (purpose) argument.
  * Throws if that is not true.
  */
-function checkFeatureSupport(coreFeatures: CoreFeatures) {
+function checkFeatureSupport(coreFeatures: CoreFeatures, supportedFeatures: Set<string>) {
   const errors: GraphQLError[] = [];
   const coreItself = coreFeatures.coreItself;
   if (coreItself.url.equals(coreVersionZeroDotOneUrl)) {
@@ -56,7 +45,7 @@ function checkFeatureSupport(coreFeatures: CoreFeatures) {
 
   for (const feature of coreFeatures.allFeatures()) {
     if (feature.url.equals(coreVersionZeroDotOneUrl) || feature.purpose === 'EXECUTION' || feature.purpose === 'SECURITY') {
-      if (!SUPPORTED_FEATURES.has(feature.url.base.toString())) {
+      if (!supportedFeatures.has(feature.url.base.toString())) {
         errors.push(ERRORS.UNSUPPORTED_LINKED_FEATURE.err(
           `feature ${feature.url} is for: ${feature.purpose} but is unsupported`,
           { nodes: feature.directive.sourceAST },
@@ -89,3 +78,62 @@ export function validateSupergraph(supergraph: Schema): [CoreFeatures, JoinSpecD
 export function isFed1Supergraph(supergraph: Schema): boolean {
   return validateSupergraph(supergraph)[1].version.equals(new FeatureVersion(0, 1));
 }
+
+export class Supergraph {
+  private readonly containedSubgraphs: readonly {name: string, url: string}[];
+  // Lazily computed as that requires a bit of work.
+  private _subgraphs?: Subgraphs;
+
+  constructor(
+    readonly schema: Schema,
+    supportedFeatures: Set<string> | null = DEFAULT_SUPPORTED_SUPERGRAPH_FEATURES,
+    private readonly shouldValidate: boolean = true,
+  ) {
+    const [coreFeatures] = validateSupergraph(schema);
+    
+    if (supportedFeatures !== null) {
+      checkFeatureSupport(coreFeatures, supportedFeatures);
+    }
+    
+    if (shouldValidate) {
+      schema.validate();
+    } else {
+      schema.assumeValid();
+    }
+
+    this.containedSubgraphs = extractSubgraphsNamesAndUrlsFromSupergraph(schema);
+  }
+
+  static build(supergraphSdl: string | DocumentNode, options?: { supportedFeatures?: Set<string>, validateSupergraph?: boolean }) {
+    // We delay validation because `checkFeatureSupport` in the constructor gives slightly more useful errors if, say, 'for' is used with core v0.1.
+    const schema = typeof supergraphSdl === 'string'
+      ? buildSchema(supergraphSdl, { validate: false })
+      : buildSchemaFromAST(supergraphSdl, { validate: false });
+
+    return new Supergraph(schema, options?.supportedFeatures, options?.validateSupergraph);
+  }
+
+  /**
+   * The list of names/urls of the subgraphs contained in this subgraph.
+   *
+   * Note that this is a subset of what `this.subgraphs()` returns, but contrarily to that method, this method does not do a full extraction of the
+   * subgraphs schema.
+   */
+  subgraphsMetadata(): readonly {name: string, url: string}[] {
+    return this.containedSubgraphs;
+  }
+
+  subgraphs(): Subgraphs {
+    if (!this._subgraphs) {
+      // Note that `extractSubgraphsFromSupergraph` redo a little bit of work we're already one, like validating
+      // the supergraph. We could refactor things to avoid it, but it's completely negligible in practice so we
+      // can leave that to "some day, maybe".
+      this._subgraphs = extractSubgraphsFromSupergraph(this.schema, this.shouldValidate);
+    }
+    return this._subgraphs;
+  }
+
+  apiSchema(): Schema {
+    return this.schema.toAPISchema();
+  }
+}

package/src/tagSpec.ts

@@ -13,8 +13,8 @@ export class TagSpecDefinition extends FeatureDefinition {
   public readonly tagDirectiveSpec: DirectiveSpecification;
   private readonly printedTagDefinition: string;
 
-  constructor(version: FeatureVersion) {
-    super(new FeatureUrl(tagIdentity, 'tag', version));
+  constructor(version: FeatureVersion, minimumFederationVersion?: FeatureVersion) {
+    super(new FeatureUrl(tagIdentity, 'tag', version), minimumFederationVersion);
     this.tagLocations = [
       DirectiveLocation.FIELD_DEFINITION,
       DirectiveLocation.OBJECT,
@@ -43,7 +43,7 @@ export class TagSpecDefinition extends FeatureDefinition {
       repeatable: true,
       args: [{ name: 'name', type: (schema) => new NonNullType(schema.stringType()) }],
       composes: true,
-      supergraphSpecification: () => TAG_VERSIONS.latest(),
+      supergraphSpecification: (fedVersion) => TAG_VERSIONS.getMinimumRequiredVersion(fedVersion),
     });
     this.registerDirective(this.tagDirectiveSpec);
   }
@@ -77,6 +77,6 @@ export class TagSpecDefinition extends FeatureDefinition {
 export const TAG_VERSIONS = new FeatureDefinitions<TagSpecDefinition>(tagIdentity)
   .add(new TagSpecDefinition(new FeatureVersion(0, 1)))
   .add(new TagSpecDefinition(new FeatureVersion(0, 2)))
-  .add(new TagSpecDefinition(new FeatureVersion(0, 3)));
+  .add(new TagSpecDefinition(new FeatureVersion(0, 3), new FeatureVersion(2, 0)));
 
 registerKnownFeature(TAG_VERSIONS);

package/src/utils.ts

@@ -431,3 +431,13 @@ export function isNonEmptyArray<T>(array: T[]): array is NonEmptyArray<T> {
   return array.length > 0;
 }
 
+// We can switch to `Array.prototype.findLast` when we drop support for Node 16
+export function findLast<T>(array: T[], predicate: (t: T) => boolean): T | undefined {
+  for (let i = array.length - 1; i >= 0; i--) {
+    const t = array[i];
+    if (predicate(t)) {
+      return t;
+    }
+  }
+  return undefined;
+}