Introduce @requiresScopes directive in composition (#2649)

With this change, users can now compose `@requiresScopes`
applications from their subgraphs into a supergraph. This addition
will support a future version of Apollo Router that enables
authenticated access to specific types and fields via directive
applications.

Since the implementation of `@requiresScopes` is strictly a
composition and execution concern, there's no change to the
query planner with this work. The execution work is well under way
in Apollo Router (and won't be built at all for Gateway). So as far as
this repo is concerned, only composition is concerned with
`@requiresScopes`.

Co-authored-by: Sylvain Lebresne <[email protected]>

Author: trevor-scheer

.changeset/thirty-fans-deliver.md

@@ -0,0 +1,32 @@
+---
+"@apollo/query-planner": minor
+"@apollo/composition": minor
+"@apollo/federation-internals": minor
+"@apollo/gateway": minor
+---
+
+Introduce the new `@requiresScopes` directive for composition
+
+> Note that this directive will only be _fully_ supported by the Apollo Router as a GraphOS Enterprise feature at runtime. Also note that _composition_ of valid `@requiresScopes` directive applications will succeed, but the resulting supergraph will not be _executable_ by the Gateway or an Apollo Router which doesn't have the GraphOS Enterprise entitlement.
+
+Users may now compose `@requiresScopes` applications from their subgraphs into a supergraph. This addition will support a future version of Apollo Router that enables scoped access to specific types and fields via directive applications.
+
+The directive is defined as follows:
+
+```graphql
+scalar federation__Scope
+
+directive @requiresScopes(scopes: [federation__Scope!]!) on
+  | FIELD_DEFINITION
+  | OBJECT
+  | INTERFACE
+  | SCALAR
+  | ENUM
+```
+
+The `Scope` scalar is effectively a `String`, similar to the `FieldSet` type.
+
+In order to compose your `@requiresScopes` usages, you must update your subgraph's federation spec version to v2.5 and add the `@requiresScopes` import to your existing imports like so:
+```graphql
+@link(url: "https://specs.apollo.dev/federation/v2.5", import: [..., "@requiresScopes"])
+```

.cspell/cspell-dict.txt

@@ -221,6 +221,7 @@ subraph
 subraphs
 Substrat
 sugraph
+supergraph
 svitejs
 Sylvain
 sylvain

composition-js/src/__tests__/compose.composeDirective.test.ts

@@ -261,7 +261,7 @@ describe('composing custom core directives', () => {
   });
 
   it.each([
-    '@tag', '@inaccessible', '@authenticated',
+    '@tag', '@inaccessible', '@authenticated', '@requiresScopes',
   ])('federation directives that result in a hint', (directive) => {
     const subgraphA = generateSubgraph({
       name: 'subgraphA',
@@ -282,7 +282,7 @@ describe('composing custom core directives', () => {
   });
 
   it.each([
-    '@tag', '@inaccessible', '@authenticated',
+    '@tag', '@inaccessible', '@authenticated', '@requiresScopes',
   ])('federation directives (with rename) that result in a hint', (directive) => {
     const subgraphA = {
       name: 'subgraphA',