elasticgraph-schema_definition 0.18.0.0

data/lib/elastic_graph/schema_definition/rake_tasks.rb

@@ -0,0 +1,190 @@
+# Copyright 2024 Block, Inc.
+#
+# Use of this source code is governed by an MIT-style
+# license that can be found in the LICENSE file or at
+# https://opensource.org/licenses/MIT.
+#
+# frozen_string_literal: true
+
+require "rake/tasklib"
+require "elastic_graph/schema_artifacts/runtime_metadata/schema_element_names"
+
+module ElasticGraph
+  module SchemaDefinition
+    # Defines rake tasks for managing artifacts generated from a schema definition.
+    #
+    # @note {ElasticGraph::Local::RakeTasks} wraps this and provides additional functionality. Most users will not need to interact with
+    #   this class directly.
+    class RakeTasks < ::Rake::TaskLib
+      # @private
+      attr_reader :output
+
+      # @param index_document_sizes [Boolean] When enabled, ElasticGraph will configure the index mappings so that the datastore indexes a
+      #   `_size` field in each document. ElasticGraph itself does not do anything with this field, but it will be available for your use
+      #   in any direct queries (e.g. via Kibana). Important note: this requires the [mapper-size
+      #   plugin](https://www.elastic.co/guide/en/elasticsearch/plugins/8.15/mapper-size.html) to be installed on your datastore cluster.
+      #   You are responsible for ensuring that is installed if you enable this feature. If you enable this and the plugin is not
+      #   installed, you will get errors!
+      # @param path_to_schema [String, Pathname] path to the main (or only) schema definition file
+      # @param schema_artifacts_directory [String, Pathname] Directory to dump the schema artifacts in
+      # @param schema_element_name_form [:camelCase, :snake_case] the form of names for schema elements (fields, arguments, directives)
+      #   generated by ElasticGraph.
+      # @param schema_element_name_overrides [Hash<Symbol, String>] overrides for specific names of schema elements (fields, arguments,
+      #   directives) generated by ElasticGraph. For example, to rename the `gt` filter field to `greaterThan`, pass `{gt: "greaterThan"}`.
+      # @param derived_type_name_formats [Hash<Symbol, String>] overrides for the naming formats used by ElasticGraph for derived GraphQL
+      #   type names. For example, to use `Metrics` instead of `AggregatedValues` as the suffix for the generated types supporting
+      #   getting aggregated metrid values, pass `{AggregatedValues: "%{base}Metrics"}`. See {SchemaElements::TypeNamer::DEFAULT_FORMATS}
+      #   for the available formats.
+      # @param type_name_overrides [Hash<Symbol, String>] overrides for the names of specific GraphQL types. For example, to rename the
+      #   `DateTime` scalar to `Timestamp`, pass `{DateTime: "Timestamp}`.
+      # @param enum_value_overrides_by_type [Hash<Symbol, Hash<Symbol, String>>] overrides for the names of specific enum values for
+      #   specific enum types. For example, to rename the `DayOfWeek.MONDAY` enum to `DayOfWeek.MON`, pass `{DayOfWeek: {MONDAY: "MON"}}`.
+      # @param extension_modules [Array<Module>] List of Ruby modules to extend onto the `SchemaDefinition::API` instance. Designed to
+      #   support ElasticGraph extension gems (such as `elasticgraph-apollo`).
+      # @param enforce_json_schema_version [Boolean] Whether or not to enforce the requirement that the JSON schema version is incremented
+      #   every time dumping the JSON schemas results in a changed artifact. Generally speaking, you will want this to be `true` for any
+      #   ElasticGraph application that is in production as the versioning of JSON schemas is what supports safe schema evolution as it
+      #   allows ElasticGraph to identify which version of the JSON schema the publishing system was operating on when it published an
+      #   event. It can be useful to set it to `false` before your application is in production, as you do not want to be forced to bump
+      #   the version after every single schema change while you are building an initial prototype.
+      # @param output [IO] used for printing task output
+      #
+      # @example Minimal setup with defaults
+      #   ElasticGraph::SchemaDefinition::RakeTasks.new(
+      #     index_document_sizes: false,
+      #     path_to_schema: "config/schema.rb",
+      #     schema_artifacts_directory: "config/schema/artifacts",
+      #     schema_element_name_form: :camelCase
+      #   )
+      #
+      # @example Spell out the full names of the `gt`/`gte`/`lt`/`lte` filter operators
+      #   ElasticGraph::SchemaDefinition::RakeTasks.new(
+      #     index_document_sizes: false,
+      #     path_to_schema: "config/schema.rb",
+      #     schema_artifacts_directory: "config/schema/artifacts",
+      #     schema_element_name_form: :camelCase,
+      #     schema_element_name_overrides: {
+      #       gt: "greaterThan",
+      #       gte: "greaterThanOrEqualTo",
+      #       lt: "lessThan",
+      #       lte: "lessThanOrEqualTo"
+      #     }
+      #   )
+      #
+      # @example Change the `AggregatedValues` type suffix to `Metrics`
+      #   ElasticGraph::SchemaDefinition::RakeTasks.new(
+      #     index_document_sizes: false,
+      #     path_to_schema: "config/schema.rb",
+      #     schema_artifacts_directory: "config/schema/artifacts",
+      #     schema_element_name_form: :camelCase,
+      #     derived_type_name_formats: {AggregatedValues: "Metrics"}
+      #   )
+      #
+      # @example Rename `JsonSafeLong` to `BigInt`
+      #   ElasticGraph::SchemaDefinition::RakeTasks.new(
+      #     index_document_sizes: false,
+      #     path_to_schema: "config/schema.rb",
+      #     schema_artifacts_directory: "config/schema/artifacts",
+      #     schema_element_name_form: :camelCase,
+      #     type_name_overrides: {JsonSafeLong: "BigInt"}
+      #   )
+      #
+      # @example Shorten the names of the `DayOfWeek` enum values
+      #   ElasticGraph::SchemaDefinition::RakeTasks.new(
+      #     index_document_sizes: false,
+      #     path_to_schema: "config/schema.rb",
+      #     schema_artifacts_directory: "config/schema/artifacts",
+      #     schema_element_name_form: :camelCase,
+      #     enum_value_overrides_by_type: {
+      #       DayOfWeek: {
+      #         MONDAY: "MON",
+      #         TUESDAY: "TUE",
+      #         WEDNESDAY: "WED",
+      #         THURSDAY: "THU",
+      #         FRIDAY: "FRI",
+      #         SATURDAY: "SAT",
+      #         SUNDAY: "SUN"
+      #       }
+      #     }
+      #   )
+      def initialize(
+        index_document_sizes:,
+        path_to_schema:,
+        schema_artifacts_directory:,
+        schema_element_name_form:,
+        schema_element_name_overrides: {},
+        derived_type_name_formats: {},
+        type_name_overrides: {},
+        enum_value_overrides_by_type: {},
+        extension_modules: [],
+        enforce_json_schema_version: true,
+        output: $stdout
+      )
+        @schema_element_names = SchemaArtifacts::RuntimeMetadata::SchemaElementNames.new(
+          form: schema_element_name_form,
+          overrides: schema_element_name_overrides
+        )
+
+        @derived_type_name_formats = derived_type_name_formats
+        @type_name_overrides = type_name_overrides
+        @enum_value_overrides_by_type = enum_value_overrides_by_type
+        @index_document_sizes = index_document_sizes
+        @path_to_schema = path_to_schema
+        @schema_artifacts_directory = schema_artifacts_directory
+        @enforce_json_schema_version = enforce_json_schema_version
+        @extension_modules = extension_modules
+        @output = output
+
+        define_tasks
+      end
+
+      private
+
+      def define_tasks
+        namespace :schema_artifacts do
+          desc "Dumps all schema artifacts based on the current ElasticGraph schema definition"
+          task :dump do
+            schema_artifact_manager.dump_artifacts
+          end
+
+          desc "Checks the artifacts to make sure they are up-to-date, raising an exception if not"
+          task :check do
+            schema_artifact_manager.check_artifacts
+          end
+        end
+      end
+
+      def schema_artifact_manager
+        require "elastic_graph/schema_definition/schema_artifact_manager"
+
+        # :nocov: -- tests don't cover the `VERBOSE` side
+        max_diff_lines = ENV["VERBOSE"] ? 999999999 : 50
+        # :nocov:
+
+        SchemaArtifactManager.new(
+          schema_definition_results: schema_definition_results,
+          schema_artifacts_directory: @schema_artifacts_directory.to_s,
+          enforce_json_schema_version: @enforce_json_schema_version,
+          output: @output,
+          max_diff_lines: max_diff_lines
+        )
+      end
+
+      def schema_definition_results
+        require "elastic_graph/schema_definition/api"
+
+        API.new(
+          @schema_element_names,
+          @index_document_sizes,
+          extension_modules: @extension_modules,
+          derived_type_name_formats: @derived_type_name_formats,
+          type_name_overrides: @type_name_overrides,
+          enum_value_overrides_by_type: @enum_value_overrides_by_type,
+          output: @output
+        ).tap do |api|
+          api.as_active_instance { load @path_to_schema.to_s }
+        end.results
+      end
+    end
+  end
+end

data/lib/elastic_graph/schema_definition/results.rb

@@ -0,0 +1,404 @@
+# Copyright 2024 Block, Inc.
+#
+# Use of this source code is governed by an MIT-style
+# license that can be found in the LICENSE file or at
+# https://opensource.org/licenses/MIT.
+#
+# frozen_string_literal: true
+
+require "elastic_graph/constants"
+require "elastic_graph/error"
+require "elastic_graph/schema_artifacts/runtime_metadata/schema"
+require "elastic_graph/schema_artifacts/artifacts_helper_methods"
+require "elastic_graph/schema_definition/indexing/event_envelope"
+require "elastic_graph/schema_definition/indexing/json_schema_with_metadata"
+require "elastic_graph/schema_definition/indexing/relationship_resolver"
+require "elastic_graph/schema_definition/indexing/update_target_resolver"
+require "elastic_graph/schema_definition/mixins/has_readable_to_s_and_inspect"
+require "elastic_graph/schema_definition/schema_elements/field_path"
+require "elastic_graph/schema_definition/scripting/file_system_repository"
+require "elastic_graph/support/memoizable_data"
+
+module ElasticGraph
+  module SchemaDefinition
+    # Provides the results of defining a schema.
+    #
+    # @note This class is designed to implement the same interface as `ElasticGraph::SchemaArtifacts::FromDisk`, so that it can be used
+    # interchangeably with schema artifacts loaded from disk. This allows the artifacts to be used in tests without having to dump them or
+    # reload them.
+    class Results < Support::MemoizableData.define(:state)
+      include Mixins::HasReadableToSAndInspect.new
+      include SchemaArtifacts::ArtifactsHelperMethods
+
+      # @return [String] the generated GraphQL SDL schema string dumped as `schema.graphql`
+      def graphql_schema_string
+        @graphql_schema_string ||= generate_sdl
+      end
+
+      # @return [Hash<String, Object>] the Elasticsearch/OpenSearch configuration dumped as `datastore_config.yaml`
+      def datastore_config
+        @datastore_config ||= generate_datastore_config
+      end
+
+      # @return [Hash<String, Object>] runtime metadata used by other parts of ElasticGraph and dumped as `runtime_metadata.yaml`
+      def runtime_metadata
+        @runtime_metadata ||= build_runtime_metadata
+      end
+
+      # @param version [Integer] desired JSON schema version
+      # @return [Hash<String, Object>] the JSON schema for the requested version, if available
+      # @raise [NotFoundError] if the requested JSON schema version is not available
+      def json_schemas_for(version)
+        unless available_json_schema_versions.include?(version)
+          raise NotFoundError, "The requested json schema version (#{version}) is not available. Available versions: #{available_json_schema_versions.to_a.join(", ")}."
+        end
+
+        @latest_versioned_json_schema ||= merge_field_metadata_into_json_schema(current_public_json_schema).json_schema
+      end
+
+      # @return [Set<Integer>] set of available JSON schema versions
+      def available_json_schema_versions
+        @available_json_schema_versions ||= Set[latest_json_schema_version]
+      end
+
+      # @return [Hash<String, Object>] the newly generated JSON schema
+      def latest_json_schema_version
+        current_public_json_schema[JSON_SCHEMA_VERSION_KEY]
+      end
+
+      # @private
+      def json_schema_version_setter_location
+        state.json_schema_version_setter_location
+      end
+
+      # @private
+      def json_schema_field_metadata_by_type_and_field_name
+        @json_schema_field_metadata_by_type_and_field_name ||= json_schema_indexing_field_types_by_name
+          .transform_values(&:json_schema_field_metadata_by_field_name)
+      end
+
+      # @private
+      def current_public_json_schema
+        @current_public_json_schema ||= build_public_json_schema
+      end
+
+      # @private
+      def merge_field_metadata_into_json_schema(json_schema)
+        json_schema_with_metadata_merger.merge_metadata_into(json_schema)
+      end
+
+      # @private
+      def unused_deprecated_elements
+        json_schema_with_metadata_merger.unused_deprecated_elements
+      end
+
+      # @private
+      STATIC_SCRIPT_REPO = Scripting::FileSystemRepository.new(::File.join(__dir__.to_s, "scripting", "scripts"))
+
+      # @private
+      def derived_indexing_type_names
+        @derived_indexing_type_names ||= state
+          .object_types_by_name
+          .values
+          .flat_map { |type| type.derived_indexed_types.map { |dit| dit.destination_type_ref.name } }
+          .to_set
+      end
+
+      private
+
+      def after_initialize
+        # Record that we are now generating results so that caching can kick in.
+        state.user_definition_complete = true
+      end
+
+      def json_schema_with_metadata_merger
+        @json_schema_with_metadata_merger ||= Indexing::JSONSchemaWithMetadata::Merger.new(self)
+      end
+
+      def generate_datastore_config
+        # We need to check this before generating our datastore configuration.
+        # We can't generate a mapping from a recursively defined schema type.
+        check_for_circular_dependencies!
+
+        index_templates, indices = state.object_types_by_name.values
+          .flat_map(&:indices)
+          .sort_by(&:name)
+          .partition(&:rollover_config)
+
+        datastore_scripts = (build_dynamic_scripts + STATIC_SCRIPT_REPO.scripts)
+
+        {
+          "index_templates" => index_templates.to_h { |i| [i.name, i.to_index_template_config] },
+          "indices" => indices.to_h { |i| [i.name, i.to_index_config] },
+          "scripts" => datastore_scripts.to_h { |s| [s.id, s.to_artifact_payload] }
+        }
+      end
+
+      def build_dynamic_scripts
+        state.object_types_by_name.values
+          .flat_map(&:derived_indexed_types)
+          .map(&:painless_script)
+      end
+
+      def build_runtime_metadata
+        extra_update_targets_by_object_type_name = identify_extra_update_targets_by_object_type_name
+
+        object_types_by_name = all_types_except_root_query_type
+          .select { |t| t.respond_to?(:graphql_fields_by_name) }
+          .to_h { |type| [type.name, (_ = type).runtime_metadata(extra_update_targets_by_object_type_name.fetch(type.name) { [] })] }
+
+        scalar_types_by_name = state.scalar_types_by_name.transform_values(&:runtime_metadata)
+
+        enum_generator = state.factory.new_enums_for_indexed_types
+
+        indexed_enum_types_by_name = state.object_types_by_name.values
+          .select(&:indexed?)
+          .filter_map { |type| enum_generator.sort_order_enum_for(_ = type) }
+          .to_h { |enum_type| [(_ = enum_type).name, (_ = enum_type).runtime_metadata] }
+
+        enum_types_by_name = all_types_except_root_query_type
+          .grep(SchemaElements::EnumType) # : ::Array[SchemaElements::EnumType]
+          .to_h { |t| [t.name, t.runtime_metadata] }
+          .merge(indexed_enum_types_by_name)
+
+        index_definitions_by_name = state.object_types_by_name.values.flat_map(&:indices).to_h do |index|
+          [index.name, index.runtime_metadata]
+        end
+
+        SchemaArtifacts::RuntimeMetadata::Schema.new(
+          object_types_by_name: object_types_by_name,
+          scalar_types_by_name: scalar_types_by_name,
+          enum_types_by_name: enum_types_by_name,
+          index_definitions_by_name: index_definitions_by_name,
+          schema_element_names: state.schema_elements,
+          graphql_extension_modules: state.graphql_extension_modules,
+          static_script_ids_by_scoped_name: STATIC_SCRIPT_REPO.script_ids_by_scoped_name
+        )
+      end
+
+      # Builds a map, keyed by object type name, of extra `update_targets` that have been generated
+      # from any fields that use `sourced_from` on other types.
+      def identify_extra_update_targets_by_object_type_name
+        # The field_path_resolver memoizes some calculations, and we want the same instance to be
+        # used by all UpdateTargetBuilders to maximize its effectiveness.
+        field_path_resolver = SchemaElements::FieldPath::Resolver.new
+        sourced_field_errors = [] # : ::Array[::String]
+        relationship_errors = [] # : ::Array[::String]
+
+        state.object_types_by_name.values.each_with_object(::Hash.new { |h, k| h[k] = [] }) do |object_type, accum|
+          fields_with_sources_by_relationship_name =
+            if object_type.indices.empty?
+              # only indexed types can have `sourced_from` fields, and resolving `fields_with_sources` on an unindexed union type
+              # such as `_Entity` when we are using apollo can lead to exceptions when multiple entity types have the same field name
+              # that use different mapping types.
+              {} # : ::Hash[::String, ::Array[SchemaElements::Field]]
+            else
+              object_type
+                .fields_with_sources
+                .group_by { |f| (_ = f.source).relationship_name }
+            end
+
+          defined_relationships = object_type
+            .graphql_fields_by_name.values
+            .select(&:relationship)
+            .map(&:name)
+
+          (defined_relationships | fields_with_sources_by_relationship_name.keys).each do |relationship_name|
+            sourced_fields = fields_with_sources_by_relationship_name.fetch(relationship_name) { [] }
+            relationship_resolver = Indexing::RelationshipResolver.new(
+              schema_def_state: state,
+              object_type: object_type,
+              relationship_name: relationship_name,
+              sourced_fields: sourced_fields,
+              field_path_resolver: field_path_resolver
+            )
+
+            resolved_relationship, relationship_error = relationship_resolver.resolve
+            relationship_errors << relationship_error if relationship_error
+
+            if object_type.indices.any? && resolved_relationship && sourced_fields.any?
+              update_target_resolver = Indexing::UpdateTargetResolver.new(
+                object_type: object_type,
+                resolved_relationship: resolved_relationship,
+                sourced_fields: sourced_fields,
+                field_path_resolver: field_path_resolver
+              )
+
+              update_target, errors = update_target_resolver.resolve
+              accum[resolved_relationship.related_type.name] << update_target if update_target
+              sourced_field_errors.concat(errors)
+            end
+          end
+        end.tap do
+          full_errors = [] # : ::Array[::String]
+
+          if sourced_field_errors.any?
+            full_errors << "Schema had #{sourced_field_errors.size} error(s) related to `sourced_from` fields:\n\n#{sourced_field_errors.map.with_index(1) { |e, i| "#{i}. #{e}" }.join("\n\n")}"
+          end
+
+          if relationship_errors.any?
+            full_errors << "Schema had #{relationship_errors.size} error(s) related to relationship fields:\n\n#{relationship_errors.map.with_index(1) { |e, i| "#{i}. #{e}" }.join("\n\n")}"
+          end
+
+          unless full_errors.empty?
+            raise SchemaError, full_errors.join("\n\n")
+          end
+        end
+      end
+
+      # Generates the SDL defined by your schema. Intended to be called only once
+      # at the very end (after evaluating the "main" template). `Evaluator` calls this
+      # automatically at the end.
+      def generate_sdl
+        check_for_circular_dependencies!
+        state.object_types_by_name.values.each(&:verify_graphql_correctness!)
+
+        type_defs = state.factory
+          .new_graphql_sdl_enumerator(all_types_except_root_query_type)
+          .map { |sdl| strip_trailing_whitespace(sdl) }
+
+        [type_defs + state.sdl_parts].join("\n\n")
+      end
+
+      def build_public_json_schema
+        json_schema_version = state.json_schema_version
+        if json_schema_version.nil?
+          raise SchemaError, "`json_schema_version` must be specified in the schema. To resolve, add `schema.json_schema_version 1` in a schema definition block."
+        end
+
+        indexed_type_names = state.object_types_by_name.values
+          .select { |type| type.indexed? && !type.abstract? }
+          .reject { |type| derived_indexing_type_names.include?(type.name) }
+          .map(&:name)
+
+        definitions_by_name = json_schema_indexing_field_types_by_name
+          .transform_values(&:to_json_schema)
+          .compact
+
+        {
+          "$schema" => JSON_META_SCHEMA,
+          JSON_SCHEMA_VERSION_KEY => json_schema_version,
+          "$defs" => {
+            "ElasticGraphEventEnvelope" => Indexing::EventEnvelope.json_schema(indexed_type_names, json_schema_version)
+          }.merge(definitions_by_name)
+        }
+      end
+
+      def json_schema_indexing_field_types_by_name
+        @json_schema_indexing_field_types_by_name ||= state
+          .types_by_name.values
+          .reject do |t|
+            derived_indexing_type_names.include?(t.name) ||
+              # Skip graphql framework types
+              t.graphql_only?
+          end
+          .sort_by(&:name)
+          .to_h { |type| [type.name, type.to_indexing_field_type] }
+      end
+
+      def strip_trailing_whitespace(string)
+        string.gsub(/ +$/, "")
+      end
+
+      def check_for_circular_dependencies!
+        return if @no_circular_dependencies
+
+        referenced_types_by_source_type = state.types_by_name
+          .reject { |_, type| type.graphql_only? }
+          .each_with_object(::Hash.new { |h, k| h[k] = ::Set.new }) do |(type_name, _), cache|
+            recursively_add_referenced_types_to(state.type_ref(type_name), cache)
+          end
+
+        circular_reference_sets = referenced_types_by_source_type
+          .select { |source_type, referenced_types| referenced_types.include?(source_type) }
+          .values
+          .uniq
+
+        if circular_reference_sets.any?
+          descriptions = circular_reference_sets.map do |set|
+            "- The set of #{set.to_a} forms a circular reference chain."
+          end
+
+          raise SchemaError, "Your schema has self-referential types, which are not allowed, since " \
+            "it prevents the datastore mapping and GraphQL schema generation from terminating:\n" \
+            "#{descriptions.join("\n")}"
+        end
+
+        @no_circular_dependencies = true
+      end
+
+      def recursively_add_referenced_types_to(source_type_ref, references_cache)
+        return unless (source_type = source_type_ref.as_object_type)
+        references_set = references_cache[source_type_ref.name]
+
+        # Recursive references are allowed only when its a relation, so skip that case.
+        source_type.graphql_fields_by_name.values.reject { |f| f.relationship }.each do |field|
+          field_type = field.type.fully_unwrapped
+
+          if field_type.object? && references_set.add?(field_type.name)
+            recursively_add_referenced_types_to(field_type, references_cache)
+          end
+
+          references_set.merge(references_cache[field_type.name])
+        end
+      end
+
+      def all_types_except_root_query_type
+        @all_types_except_root_query_type ||= state.types_by_name.values.flat_map do |registered_type|
+          related_types = [registered_type] + registered_type.derived_graphql_types
+          apply_customizations_to(related_types, registered_type)
+          related_types
+        end
+      end
+
+      def apply_customizations_to(types, registered_type)
+        built_in_customizers = state.built_in_types_customization_blocks
+        if built_in_customizers.any? && state.initially_registered_built_in_types.include?(registered_type.name)
+          types.each do |type|
+            built_in_customizers.each do |customization_block|
+              customization_block.call(type)
+            end
+          end
+        end
+
+        unless (unknown_type_names = registered_type.derived_type_customizations_by_name.keys - types.map(&:name)).empty?
+          raise SchemaError,
+            "`customize_derived_types` was called on `#{registered_type.name}` with some unrecognized type names " \
+             "(#{unknown_type_names.join(", ")}). Maybe some of the derived GraphQL types are misspelled?"
+        end
+
+        unless (unknown_type_names = registered_type.derived_field_customizations_by_type_and_field_name.keys - types.map(&:name)).empty?
+          raise SchemaError,
+            "`customize_derived_type_fields` was called on `#{registered_type.name}` with some unrecognized type names " \
+             "(#{unknown_type_names.join(", ")}). Maybe some of the derived GraphQL types are misspelled?"
+        end
+
+        unknown_field_names = (types - [registered_type]).flat_map do |type|
+          registered_type.derived_type_customizations_for_type(type).each { |b| b.call(type) }
+          field_customizations_by_name = registered_type.derived_field_customizations_by_name_for_type(type)
+
+          if field_customizations_by_name.any? && !type.respond_to?(:graphql_fields_by_name)
+            raise SchemaError,
+              "`customize_derived_type_fields` was called on `#{registered_type.name}` with a type that can " \
+              "never have fields: `#{type.name}`."
+          end
+
+          field_customizations_by_name.filter_map do |field_name, customization_blocks|
+            if (field = (_ = type).graphql_fields_by_name[field_name])
+              customization_blocks.each { |b| b.call(field) }
+              nil
+            else
+              "#{type.name}.#{field_name}"
+            end
+          end
+        end
+
+        unless unknown_field_names.empty?
+          raise SchemaError,
+            "`customize_derived_type_fields` was called on `#{registered_type.name}` with some unrecognized field names " \
+            "(#{unknown_field_names.join(", ")}). Maybe one of the field names was misspelled?"
+        end
+      end
+    end
+  end
+end