graphql-stitching 1.7.0 → 1.7.1

data/docs/serving_a_supergraph.md

@@ -0,0 +1,152 @@
+## Serving a supergraph
+
+Serving a stitched schema should be optimized by environment. In `production` we favor speed and stability over flexibility, while in `development` we favor the reverse. Among the simplest ways to deploy a stitched schema is to compose it locally, write the composed schema as a `.graphql` file in your repo, and then load the pre-composed schema into a stitching client at runtime. This assures that composition always happens before deployment where failures can be detected.
+
+### Exporting a production schema
+
+1. Make a helper class for building your supergraph and exporting it as an SDL string:
+
+```ruby
+class SupergraphHelper
+  def self.export
+    client = GraphQL::Stitching::Client.new({
+      remote: {
+        schema: GraphQL::Schema.from_definition(File.read("db/schema/remote.graphql"))
+      },
+      local: {
+        schema: MyLocalSchema
+      }
+    })
+
+    client.supergraph.to_definition
+  end
+end
+```
+
+2. Setup a `rake` task for writing the export to a repo file:
+
+```ruby
+task :compose_supergraph do
+  File.write("db/schema/supergraph.graphql", SupergraphHelper.export)
+  puts "Schema composition was successful."
+end
+
+# bundle exec rake compose-supergraph
+```
+
+3. Also as part of the export Rake task, it's advisable to run a [schema comparator](https://github.com/xuorig/graphql-schema_comparator) across the `main` version and the current compilation to catch breaking change regressions that may arise [during composition](./composing_a_supergraph.md#schema-merge-patterns):
+
+```ruby
+task :compose_supergraph do
+  # ...
+
+  supergraph_file = "db/schema/supergraph.graphql"
+  head_commit = %x(git merge-base HEAD origin/main).strip!
+  head_source = %x(git show #{head_commit}:#{supergraph_file})
+
+  old_schema = GraphQL::Schema.from_definition(head_source)
+  new_schema = GraphQL::Schema.from_definition(File.read(supergraph_file))
+  diff = GraphQL::SchemaComparator.compare(old_schema, new_schema)
+  raise "Breaking changes found:\n-#{diff.breaking_changes.join("\n-")}" if diff.breaking?
+
+  # ...
+end
+```
+
+4. As a CI safeguard, be sure to write a test that compares the supergraph export against the current repo file. This assures the latest schema is always expored before deploying:
+
+```ruby
+test "supergraph export is up to date." do
+  assert_equal SupergraphHelper.export, File.read("db/schema/supergraph.graphql")
+end
+```
+
+### Supergraph controller
+
+Then at runtime, execute requests using a client built for the environment. The `production` client should load the pre-composed export schema, while the `development` client can live reload using runtime composition. Be sure to memoize any static schemas that the development client uses to minimize reloading overhead:
+
+```ruby
+class SupergraphController < ApplicationController
+  protect_from_forgery with: :null_session, prepend: true
+
+  def execute
+    # see visibility docs...
+    visibility_profile = select_visibility_profile_for_audience(current_user)
+    
+    client.execute(
+      query: params[:query],
+      variables: params[:variables],
+      operation_name: params[:operation_name],
+      context: { visibility_profile: visibility_profile },
+    )
+  end
+
+  private
+
+  # select which client to use based on the environment...
+  def client
+    Rails.env.production? ? production_client : development_client
+  end
+
+  # production uses a pre-composed supergraph read from the repo...
+  def production_client
+    @production_client ||= begin
+      supergraph_sdl = File.read("db/schema/supergraph.graphql")
+
+      GraphQL::Stitching::Client.from_definition(supergraph_sdl, executables: {
+        remote: GraphQL::Stitching::HttpExecutable.new("https://api.remote.com/graphql"),
+        local: MyLocalSchema,
+      }).tap do |client|
+        # see performance and error handling docs...
+        client.on_cache_read { ... }
+        client.on_cache_write { ... }
+        client.on_error { ... }
+      end
+    end
+  end
+
+  # development uses a supergraph composed on the fly...
+  def development_client
+    GraphQL::Stitching::Client.new(locations: {
+      remote: {
+        schema: remote_schema,
+        executable: GraphQL::Stitching::HttpExecutable.new("https://localhost:3001/graphql"),
+      },
+      local: {
+        schema: MyLocalSchema,
+      },
+    })
+  end
+
+  # other flat schemas used in development should be 
+  # cached in memory to avoid as much runtime overhead as possible
+  def remote_schema
+    @remote_schema ||= GraphQL::Schema.from_definition(File.read("db/schema/remote.graphql"))
+  end
+end
+```
+
+### Client execution
+
+The `Client.execute` method provides a mostly drop-in replacement for [`GraphQL::Schema.execute`](https://graphql-ruby.org/queries/executing_queries):
+
+```ruby
+client.execute(
+  query: params[:query],
+  variables: params[:variables],
+  operation_name: params[:operation_name],
+  context: { visibility_profile: visibility_profile },
+)
+```
+
+It provides a subset of the standard `execute` arguments:
+
+* `query`: a query (or mutation) as a string or parsed AST.
+* `variables`: a hash of variables for the request.
+* `operation_name`: the name of the operation to execute (when multiple are provided).
+* `validate`: true if static validation should run on the supergraph schema before execution.
+* `context`: an object passed through to executable calls and client hooks.
+
+### Production reloading
+
+It is possible to "hot" reload a production supergraph (ie: update the graph without a server deployment) using a background process to poll a remote supergraph file for changes and then build it into a new client for the controller at runtime. This works fine as long as locations and their executables don't change. If locations will change, the runtime _must_ be prepared to dynamically generate appropraite location executables.

data/docs/subscriptions.md

@@ -1,4 +1,4 @@
-## Stitching subscriptions
+## Subscriptions
 
 Stitching is an interesting prospect for subscriptions because socket-based interactions can be isolated to their own schema/server with very little implementation beyond resolving entity keys. Then, entity data can be stitched onto subscription payloads from other locations.
 

data/docs/visibility.md

@@ -1,8 +1,8 @@
 # Visibility
 
-Visibility controls can hide parts of a supergraph from select audiences without compromising stitching operations. Restricted schema elements are hidden from introspection and validate as though they do not exist (which is different from traditional authorization where an element is acknowledged as restricted). Visibility is useful for managing multiple distributions of a schema for different audiences.
+Visibility controls can hide parts of a supergraph from select audiences without compromising stitching operations. Restricted schema elements are hidden from introspection and validate as though they do not exist (which is different from traditional authorization where an element is acknowledged as restricted). Visibility is useful for managing multiple distributions of a schema for different audiences, and provides a flexible analog to Apollo Federation's `@inaccessible` rule.
 
-Under the hood, this system wraps `GraphQL::Schema::Visibility` (with nil profile support) and requires at least GraphQL Ruby v2.5.3.
+Under the hood, this system wraps [GraphQL visibility](https://graphql-ruby.org/authorization/visibility) (specifically, the newer `GraphQL::Schema::Visibility` with nil profile support) and requires at least GraphQL Ruby v2.5.3.
 
 ## Example
 
@@ -41,7 +41,7 @@ type Query {
 }
 ```
 
-When composing a stitching client, the names of all possible visibility profiles that the supergraph responds to should be specified in composer options:
+When composing a stitching client, the names of all possible visibility profiles that the supergraph should respond to are specified in composer options:
 
 ```ruby
 client = GraphQL::Stitching::Client.new(
@@ -61,20 +61,20 @@ client = GraphQL::Stitching::Client.new(
 )
 ```
 
-The client can then execute requests with a `visibility_profile` parameter in context that specifies the name of any profile the supergraph was composed with, or nil:
+The client can then execute requests with a `visibility_profile` parameter in context that specifies one of these names:
 
 ```ruby
 query = %|{
   featuredProduct {
     title  # always visible
     price  # always visible
-    msrp   # only visible to internal and nil profiles
-    id     # only visible to nil profile
+    msrp   # only visible to "private" or without profile
+    id     # only visible without profile
   }
 }|
 
 result = client.execute(query, context: { 
-  visibility_profile: "public", # << or private, or nil
+  visibility_profile: "public", # << or "private"
 })
 ```
 
@@ -82,9 +82,9 @@ The `visibility_profile` parameter will select which visibility distribution to
 
 - Using `visibility_profile: "public"` will say the `msrp` field does not exist (because it is restricted to "private").
 - Using `visibility_profile: "private"` will accesses the `msrp` field as usual. 
-- Using `visibility_profile: nil` will access the entire graph without any visibility constraints.
+- Providing no profile parameter (or `visibility_profile: nil`) will access the entire graph without any visibility constraints.
 
-The full potential of visibility comes when hiding stitching implementation details, such as the `id` field (which is the stitching key for the Product type). While the `id` field is hidden from all named profiles, it remains operational for the stitching implementation.
+The full potential of visibility comes when hiding stitching implementation details, such as the `id` field (which is the stitching key for the Product type). While the `id` field is hidden from all named profiles, it remains operational for use by the stitching implementation.
 
 ## Adding visibility directives
 
@@ -105,7 +105,7 @@ end
 
 ## Merging visibilities
 
-Visibility directives merge across schemas into the narrowest constraint possible. Profile sets for an element will intersect into its supergraph constraint:
+Visibility directives merge across schemas into the narrowest constraint possible. Profiles for an element will intersect into its merged supergraph constraint:
 
 ```graphql
 # location 1
@@ -165,4 +165,14 @@ type Query {
 }
 ```
 
-In this example, hiding the `Widget` type will also hide the `Query.widget` field that returns it.
+In this example, hiding the `Widget` type will also hide the `Query.widget` field that returns it. You can review materialized visibility profiles by printing their respective schemas:
+
+```ruby
+public_schema = client.supergraph.to_definition(visibility_profile: "public")
+File.write("schemas/supergraph_public.graphql", public_schema)
+
+private_schema = client.supergraph.to_definition(visibility_profile: "private")
+File.write("schemas/supergraph_private.graphql", private_schema)
+```
+
+It's helpful to commit these outputs to your repo where you can monitor their diffs during the PR process.

data/lib/graphql/stitching/client.rb

@@ -7,6 +7,12 @@ module GraphQL
     # Client is an out-of-the-box helper that assembles all 
     # stitching components into a workflow that executes requests.
     class Client
+      class << self
+        def from_definition(schema, executables:)
+          new(supergraph: Supergraph.from_definition(schema, executables: executables))
+        end
+      end
+      
       # @return [Supergraph] composed supergraph that services incoming requests.
       attr_reader :supergraph
 

data/lib/graphql/stitching/composer.rb

@@ -26,9 +26,6 @@ module GraphQL
       # @api private
       VISIBILITY_PROFILES_MERGER = ->(values_by_location, _info) { values_by_location.values.reduce(:&) }
 
-      # @api private
-      BASIC_ROOT_FIELD_LOCATION_SELECTOR = ->(locations, _info) { locations.last }
-
       # @api private
       COMPOSITION_VALIDATORS = [
         ValidateInterfaces,
@@ -59,7 +56,8 @@ module GraphQL
         deprecation_merger: nil,
         default_value_merger: nil,
         directive_kwarg_merger: nil,
-        root_field_location_selector: nil
+        root_field_location_selector: nil,
+        root_entrypoints: nil
       )
         @query_name = query_name
         @mutation_name = mutation_name
@@ -68,7 +66,8 @@ module GraphQL
         @deprecation_merger = deprecation_merger || BASIC_VALUE_MERGER
         @default_value_merger = default_value_merger || BASIC_VALUE_MERGER
         @directive_kwarg_merger = directive_kwarg_merger || BASIC_VALUE_MERGER
-        @root_field_location_selector = root_field_location_selector || BASIC_ROOT_FIELD_LOCATION_SELECTOR
+        @root_field_location_selector = root_field_location_selector
+        @root_entrypoints = root_entrypoints || {}
         
         @field_map = {}
         @resolver_map = {}
@@ -631,11 +630,20 @@ module GraphQL
             root_field_locations = @field_map[root_type.graphql_name][root_field_name]
             next unless root_field_locations.length > 1
 
-            target_location = @root_field_location_selector.call(root_field_locations, {
-              type_name: root_type.graphql_name,
-              field_name: root_field_name,
-            })
-            next unless root_field_locations.include?(target_location)
+            root_field_path = "#{root_type.graphql_name}.#{root_field_name}"
+            target_location = if @root_field_location_selector && @root_entrypoints.empty?
+              Warning.warn("Composer option `root_field_location_selector` is deprecated and will be removed.")
+              @root_field_location_selector.call(root_field_locations, {
+                type_name: root_type.graphql_name,
+                field_name: root_field_name,
+              })
+            else
+              @root_entrypoints[root_field_path] || root_field_locations.last
+            end
+
+            unless root_field_locations.include?(target_location)
+              raise CompositionError, "Invalid `root_entrypoints` configuration: `#{root_field_path}` has no `#{target_location}` location."
+            end
 
             root_field_locations.reject! { _1 == target_location }
             root_field_locations.unshift(target_location)

data/lib/graphql/stitching/request.rb

@@ -57,6 +57,10 @@ module GraphQL
         @context[:request] = self
       end
 
+      def original_document
+        @query.document
+      end
+
       # @return [String] the original document string, or a print of the parsed AST document.
       def string
         with_prepared_document { @string || normalized_string }

data/lib/graphql/stitching/supergraph.rb

@@ -58,8 +58,10 @@ module GraphQL
         end
       end
 
-      def to_definition
-        @schema.to_definition
+      def to_definition(visibility_profile: nil)
+        @schema.to_definition(context: { 
+          visibility_profile: visibility_profile,
+        }.tap(&:compact!))
       end
 
       def resolvers_by_version

data/lib/graphql/stitching/version.rb

@@ -2,6 +2,6 @@
 
 module GraphQL
   module Stitching
-    VERSION = "1.7.0"
+    VERSION = "1.7.1"
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: graphql-stitching
 version: !ruby/object:Gem::Version
-  version: 1.7.0
+  version: 1.7.1
 platform: ruby
 authors:
 - Greg MacWilliam
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-05-01 00:00:00.000000000 Z
+date: 2025-05-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: graphql
@@ -79,19 +79,19 @@ files:
 - LICENSE
 - README.md
 - Rakefile
-- docs/README.md
-- docs/client.md
-- docs/composer.md
-- docs/federation_entities.md
-- docs/http_executable.md
+- docs/composing_a_supergraph.md
+- docs/error_handling.md
+- docs/executables.md
 - docs/images/library.png
 - docs/images/merging.png
 - docs/images/stitching.png
-- docs/mechanics.md
-- docs/request.md
+- docs/introduction.md
+- docs/merged_types.md
+- docs/merged_types_apollo.md
+- docs/performance.md
+- docs/query_planning.md
+- docs/serving_a_supergraph.md
 - docs/subscriptions.md
-- docs/supergraph.md
-- docs/type_resolver.md
 - docs/visibility.md
 - examples/file_uploads/Gemfile
 - examples/file_uploads/Procfile

data/docs/README.md

@@ -1,19 +0,0 @@
-## GraphQL::Stitching
-
-This module provides a collection of components that may be composed into a stitched schema.
-
-![Library flow](./images/library.png)
-
-Major components include:
-
-- [Client](./client.md) - an out-of-the-box setup for performing stitched requests.
-- [Composer](./composer.md) - merges and validates many schemas into one graph.
-- [Supergraph](./supergraph.md) - manages the combined schema and location routing maps. Can be exported, cached, and rehydrated.
-- [Request](./request.md) - prepares a requested GraphQL document and variables for stitching.
-- [HttpExecutable](./http_executable.md) - proxies requests to remotes with multipart file upload support.
-
-Additional topics:
-
-- [Stitching mechanics](./mechanics.md) - more about building for stitching and how it operates.
-- [Subscriptions](./subscriptions.md) - explore how to stitch realtime event subscriptions.
-- [Federation entities](./federation_entities.md) - more about Apollo Federation compatibility.

data/docs/client.md

@@ -1,107 +0,0 @@
-## GraphQL::Stitching::Client
-
-The `Client` is an out-of-the-box convenience with all stitching components assembled into a default workflow. A client is designed to work for most common needs, though you're welcome to assemble the component parts into your own configuration (see the [client source](../lib/graphql/stitching/client.rb) for an example). A client is constructed with the same [location settings](./composer.md#performing-composition) used to perform supergraph composition:
-
-```ruby
-movies_schema = "type Query { ..."
-showtimes_schema = "type Query { ..."
-
-client = GraphQL::Stitching::Client.new(locations: {
-  products: {
-    schema: GraphQL::Schema.from_definition(movies_schema),
-    executable: GraphQL::Stitching::HttpExecutable.new(url: "http://localhost:3000"),
-    stitch: [{ field_name: "products", key: "id" }],
-  },
-  showtimes: {
-    schema: GraphQL::Schema.from_definition(showtimes_schema),
-    executable: GraphQL::Stitching::HttpExecutable.new(url: "http://localhost:3001"),
-  },
-  my_local: {
-    schema: MyLocal::GraphQL::Schema,
-  },
-})
-```
-
-Alternatively, you may pass a prebuilt `Supergraph` instance to the `Client` constructor. This is useful when [exporting and rehydrating](./supergraph.md#export-and-caching) supergraph instances, which bypasses the need for runtime composition:
-
-```ruby
-supergraph_sdl = File.read("precomposed_schema.graphql")
-supergraph = GraphQL::Stitching::Supergraph.from_definition(
-  supergraph_sdl,
-  executables: { ... },
-)
-
-client = GraphQL::Stitching::Client.new(supergraph: supergraph)
-```
-
-### Execution
-
-A client provides an `execute` method with a subset of arguments provided by [`GraphQL::Schema.execute`](https://graphql-ruby.org/queries/executing_queries). Executing requests on a stitching client becomes mostly a drop-in replacement to executing on a `GraphQL::Schema` instance:
-
-```ruby
-result = client.execute(
-  query: "query MyProduct($id: ID!) { product(id: $id) { name } }",
-  variables: { "id" => "1" },
-  operation_name: "MyProduct",
-)
-```
-
-Arguments for the `execute` method include:
-
-* `query`: a query (or mutation) as a string or parsed AST.
-* `variables`: a hash of variables for the request.
-* `operation_name`: the name of the operation to execute (when multiple are provided).
-* `validate`: true if static validation should run on the supergraph schema before execution.
-* `context`: an object passed through to executable calls and client hooks.
-
-### Cache hooks
-
-The client provides cache hooks to enable caching query plans across requests. Without caching, every request made to the client will be planned individually. With caching, a query may be planned once, cached, and then executed from cache for subsequent requests. Cache keys are a normalized digest of each query string.
-
-```ruby
-client.on_cache_read do |request|
-  $cache.get(request.digest) # << 3P code
-end
-
-client.on_cache_write do |request, payload|
-  $cache.set(request.digest, payload) # << 3P code
-end
-```
-
-All request digests use SHA2 by default. You can swap in [a faster algorithm](https://github.com/Shopify/blake3-rb) and/or add base scoping by reconfiguring the stitching library:
-
-```ruby
-GraphQL::Stitching.digest { |str| Digest::MD5.hexdigest("v2/#{str}") }
-```
-
-Note that inlined input data works against caching, so you should _avoid_ these input literals when possible:
-
-```graphql
-query {
-  product(id: "1") { name }
-}
-```
-
-Instead, leverage query variables so that the document body remains consistent across requests:
-
-```graphql
-query($id: ID!) {
-  product(id: $id) { name }
-}
-
-# variables: { "id" => "1" }
-```
-
-### Error hooks
-
-The client also provides an error hook. Any program errors rescued during execution will be passed to the `on_error` handler, which can report on the error as needed and return a formatted error message for the client to add to the [GraphQL errors](https://spec.graphql.org/June2018/#sec-Errors) result.
-
-```ruby
-client.on_error do |request, err|
-  # log the error
-  Bugsnag.notify(err)
-
-  # return a formatted message for the public response
-  "Whoops, please contact support abount request '#{request.context[:request_id]}'"
-end
-```

data/docs/composer.md

@@ -1,125 +0,0 @@
-## GraphQL::Stitching::Composer
-
-A `Composer` receives many individual `GraphQL::Schema` instances representing various graph locations and _composes_ them into one combined [`Supergraph`](./supergraph.md) that is validated for integrity.
-
-### Configuring composition
-
-A `Composer` may be constructed with optional settings that tune how it builds a schema:
-
-```ruby
-composer = GraphQL::Stitching::Composer.new(
-  query_name: "Query",
-  mutation_name: "Mutation",
-  subscription_name: "Subscription",
-  description_merger: ->(values_by_location, info) { values_by_location.values.join("\n") },
-  deprecation_merger: ->(values_by_location, info) { values_by_location.values.first },
-  default_value_merger: ->(values_by_location, info) { values_by_location.values.first },
-  directive_kwarg_merger: ->(values_by_location, info) { values_by_location.values.last },
-  root_field_location_selector: ->(locations, info) { locations.last },
-)
-```
-
-Constructor arguments:
-
-- **`query_name:`** _optional_, the name of the root query type in the composed schema; `Query` by default. The root query types from all location schemas will be merged into this type, regardless of their local names.
-
-- **`mutation_name:`** _optional_, the name of the root mutation type in the composed schema; `Mutation` by default. The root mutation types from all location schemas will be merged into this type, regardless of their local names.
-
-- **`subscription_name:`** _optional_, the name of the root subscription type in the composed schema; `Subscription` by default. The root subscription types from all location schemas will be merged into this type, regardless of their local names.
-
-- **`description_merger:`** _optional_, a [value merger function](#value-merger-functions) for merging element description strings from across locations.
-
-- **`deprecation_merger:`** _optional_, a [value merger function](#value-merger-functions) for merging element deprecation strings from across locations.
-
-- **`default_value_merger:`** _optional_, a [value merger function](#value-merger-functions) for merging argument default values from across locations.
-
-- **`directive_kwarg_merger:`** _optional_, a [value merger function](#value-merger-functions) for merging directive keyword arguments from across locations.
-
-- **`root_field_location_selector:`** _optional_, selects a default routing location for root fields with multiple locations. Use this to prioritize sending root fields to their primary data sources (only applies while routing the root operation scope). This handler receives an array of possible locations and an info object with field information, and should return the prioritized location. The last location is used by default.
-
-#### Value merger functions
-
-Static data values such as element descriptions and directive arguments must also merge across locations. By default, the first non-null value encountered for a given element attribute is used. A value merger function may customize this process by selecting a different value or computing a new one:
-
-```ruby
-composer = GraphQL::Stitching::Composer.new(
-  description_merger: ->(values_by_location, info) { values_by_location.values.compact.join("\n") },
-)
-```
-
-A merger function receives `values_by_location` and `info` arguments; these provide possible values keyed by location and info about where in the schema these values were encountered:
-
-```ruby
-values_by_location = {
-  "storefronts" => "A fabulous data type.",
-  "products" => "An excellent data type.",
-}
-
-info = {
-  type_name: "Product",
-  # field_name: ...,
-  # argument_name: ...,
-  # directive_name: ...,
-}
-```
-
-### Performing composition
-
-Construct a `Composer` and call its `perform` method with location settings to compose a supergraph:
-
-```ruby
-storefronts_sdl = "type Query { ..."
-products_sdl = "type Query { ..."
-
-supergraph = GraphQL::Stitching::Composer.new.perform({
-  storefronts: {
-    schema: GraphQL::Schema.from_definition(storefronts_sdl),
-    executable: GraphQL::Stitching::HttpExecutable.new(url: "http://localhost:3001"),
-    stitch: [{ field_name: "storefront", key: "id" }],
-  },
-  products: {
-    schema: GraphQL::Schema.from_definition(products_sdl),
-    executable: GraphQL::Stitching::HttpExecutable.new(url: "http://localhost:3002"),
-  },
-  my_local: {
-    schema: MyLocalSchema,
-  },
-})
-
-combined_schema = supergraph.schema
-```
-
-Location settings have top-level keys that specify arbitrary location names, each of which provide:
-
-- **`schema:`** _required_, provides a `GraphQL::Schema` class for the location. This may be a class-based schema that inherits from `GraphQL::Schema`, or built from SDL (Schema Definition Language) string using `GraphQL::Schema.from_definition` and mapped to a remote location. The provided schema is only used for type reference and does not require any real data resolvers (unless it is also used as the location's executable, see below).
-
-- **`executable:`** _optional_, provides an executable resource to be called when delegating a request to this location. Executables are `GraphQL::Schema` classes or any object with a `.call(request, source, variables)` method that returns a GraphQL response. Omitting the executable option will use the location's provided `schema` as the executable resource.
-
-- **`stitch:`** _optional_, an array of configs used to dynamically apply `@stitch` directives to select root fields prior to composing. This is useful when you can't easily render stitching directives into a location's source schema.
-
-### Merge patterns
-
-The strategy used to merge source schemas into the combined schema is based on each element type:
-
-- Arguments of fields, directives, and `InputObject` types intersect for each parent element across locations (an element's arguments must appear in all locations):
-  - Arguments must share a value type, and the strictest nullability across locations is used.
-  - Composition fails if argument intersection would eliminate a non-null argument.
-
-- `Object` and `Interface` types merge their fields and directives together:
-  - Common fields across locations must share a value type, and the weakest nullability is used.
-  - Objects with unique fields across locations must implement [`@stitch` accessors](../README.md#merged-types).
-  - Shared object types without `@stitch` accessors must contain identical fields.
-  - Merged interfaces must remain compatible with all underlying implementations.
-
-- `Enum` types merge their values based on how the enum is used:
-  - Enums used anywhere as an argument will intersect their values (common values across all locations).
-  - Enums used exclusively in read contexts will provide a union of values (all values across all locations).
-
-- `Union` types merge all possible types from across all locations.
-
-- `Scalar` types are added for all scalar names across all locations.
-
-- `Directive` definitions are added for all distinct names across locations:
-  - Stitching directives (both definitions and assignments) are omitted.
-
-Note that the structure of a composed schema may change based on new schema additions and/or element usage (ie: changing input object arguments in one service may cause the intersection of arguments to change). Therefore, it's highly recommended that you use a [schema comparator](https://github.com/xuorig/graphql-schema_comparator) to flag regressions across composed schema versions.