graph_weaver 0.6.1 → 0.7.1

data/lib/graph_weaver/federation.rb

@@ -20,16 +20,20 @@ module GraphWeaver
     # where {SchemaLoader.diff} needs the server and answers a different
     # question (has the *server* drifted from my dump).
     #
-    # Both directions, because they mean opposite things:
+    # Three kinds, because they mean different things:
     #
     # - **stale** — the supergraph carries `Product.weight` and no schema
     #   here defines it any more. Recompose.
+    # - **shape** — both carry `Product.weight`, with different types
+    #   (`Int!` composed, `Float` here). Recompose — but nothing was added or
+    #   dropped, so every coordinate matches and only the signatures tell.
     # - **not composed in** — a schema here defines `Product.dimensions` and
     #   the supergraph doesn't carry it. Publish the subgraph.
     #
     # What "defines" means: a coordinate is compared only against the
     # schemas that could *be* the subgraph the supergraph attributes it to —
-    # the ones defining every non-root type it declares. Exact field-set
+    # the ones defining every non-root type that subgraph declares **and**
+    # something the supergraph attributes to it alone. Exact field-set
     # equality would be too strict in both directions: a subgraph carries
     # federation plumbing (`_entities`, `_service`) the supergraph never
     # has, and a field can legitimately sit in more than one subgraph
@@ -46,8 +50,7 @@ module GraphWeaver
     # misleading on the graphs this is for.
     class Drift
       # Composition names the root types conventionally, and every subgraph
-      # declares one — so a root can't tell subgraphs apart, and a schema
-      # is recognized by the other types it defines.
+      # declares one — so a root can't tell subgraphs apart (see #identifying).
       ROOTS = %w[Query Mutation Subscription].freeze
       private_constant :ROOTS
 
@@ -55,12 +58,20 @@ module GraphWeaver
       # subgraphs resolve it, and no schema of theirs here defines it
       attr_reader :stale
 
+      # { "Product.weight" => { "subgraphs" => ["products"], "supergraph" =>
+      # "Int!", "here" => ["Float"] } } — both carry the field, with
+      # different types. Its own kind because the fix is the same recompose
+      # and the cause is not: nothing was added or dropped, so the
+      # coordinates match and only the signatures say the composition is
+      # describing a graph nobody serves.
+      attr_reader :shape
+
       # { "Product.dimensions" => ["Products::Schema"] } — defined here,
       # absent from the supergraph
       attr_reader :uncomposed
 
-      # { "inventory" => ["Warehouse"] } — subgraph => the types that would
-      # identify it, which nothing here defines
+      # { "inventory" => ["Warehouse", "Warehouse.bays"] } — subgraph => the
+      # coordinates that would identify it, which nothing here defines
       attr_reader :skipped
 
       # subgraphs answered with fabricated data, so there's no real schema
@@ -70,6 +81,18 @@ module GraphWeaver
       # every subgraph that was actually compared
       attr_reader :checked
 
+      # every subgraph this supergraph names, compared or not
+      def subgraphs = @table.subgraphs
+
+      # The federated schemas in this process that no subgraph of this
+      # supergraph is. `stale` looks from the supergraph's side — every task
+      # here walks its subgraph list — and this looks from the code's, which
+      # is the only side a subgraph dropped from the composition is still on.
+      # Not `drift?`: a process that loads a subgraph of a supergraph nobody
+      # here reads looks exactly the same, and nothing on either side tells
+      # them apart.
+      def unplaced = @schemas.select { |schema| subgraph?(schema) } - @compared
+
       # supergraph: the composed SDL (a path or the content); defaults to
       # the conventional dump. subgraphs: the same map {Testing::Router}
       # takes — a named schema skips detection, `:fake` (like anything else
@@ -85,15 +108,17 @@ module GraphWeaver
         @given = @table.named_subgraphs(subgraphs)
         @schemas = schemas || GraphWeaver::Internal::Schemas.loaded
         @stale = {}
+        @shape = {}
         @uncomposed = {}
         @skipped = {}
         @faked = []
         @checked = []
+        @compared = []
         compare
       end
 
       # whether the supergraph and the code here disagree — what CI gates on
-      def drift? = @stale.any? || @uncomposed.any?
+      def drift? = @stale.any? || @shape.any? || @uncomposed.any?
 
       # Nothing was compared, so "no drift" is vacuous: the gate would pass
       # whatever the subgraphs said. Categorically different from "checked 3
@@ -107,6 +132,7 @@ module GraphWeaver
       def to_h
         {
           "stale" => @stale,
+          "shape" => @shape,
           "uncomposed" => @uncomposed,
           "skipped" => @skipped,
           "faked" => @faked,
@@ -116,19 +142,29 @@ module GraphWeaver
       def report
         return "#{@source} names no subgraphs" if @table.subgraphs.empty?
 
-        [headline, *section(STALE, @stale), *section(UNCOMPOSED, @uncomposed),
+        # the scope caveat rides with the verdict that overclaims without it;
+        # a drift report is already telling you to recompose
+        [headline, *(NOT_COMPARED unless drift? || vacuous?),
+          *section(STALE, @stale), *shape_section, *section(UNCOMPOSED, @uncomposed),
           *skipped_section, *faked_section].join("\n")
       end
       alias to_s report
 
       def inspect
-        "#<#{self.class.name} #{@stale.size} stale, #{@uncomposed.size} uncomposed, " \
-          "#{@checked.size}/#{@table.subgraphs.size} checked>"
+        "#<#{self.class.name} #{@stale.size} stale, #{@shape.size} shape, " \
+          "#{@uncomposed.size} uncomposed, #{@checked.size}/#{@table.subgraphs.size} checked>"
       end
 
       private
 
+      # A pass says the supergraph still describes the fields these schemas
+      # have — not that the next composition would succeed. Both categories
+      # below are composition's business, and this reads neither.
+      NOT_COMPARED = "not compared: @key (added, removed, or made unresolvable), and one field " \
+        "two subgraphs define without @shareable — recompose to catch those"
+
       STALE = "stale — the supergraph carries these, no schema here defines them (recompose):"
+      SHAPE = "shape — both carry these, with different types (recompose):"
       UNCOMPOSED = "not composed in — a schema here defines these, the supergraph doesn't carry them:"
 
       def compare
@@ -136,15 +172,24 @@ module GraphWeaver
           next unless (fitting = comparable(name))
 
           @checked << name
+          @compared |= fitting
           record_stale(name, fitting)
           record_uncomposed(name, fitting)
         end
       end
 
+      # A federation subgraph serves Query._service — that is how a gateway
+      # reads one to compose it, so every implementation carries it and an
+      # app's own API schema doesn't.
+      def subgraph?(schema) = !!schema.query&.fields&.key?("_service")
+
       # The schemas to compare this subgraph against, or nil when there are
-      # none — recording why. A named schema is taken as given; otherwise
-      # the schemas defining every type the supergraph says it declares are
-      # the ones that could be it.
+      # none — recording why. A named schema is taken as given; otherwise a
+      # schema could be this subgraph when it defines every non-root type the
+      # supergraph says it declares AND at least one coordinate the supergraph
+      # attributes to it alone: the types say it is the same shape, the
+      # exclusive coordinate says it is THIS subgraph and not the neighbour it
+      # shares an entity with.
       def comparable(name)
         if @given.key?(name)
           schema = @given[name]
@@ -156,8 +201,12 @@ module GraphWeaver
           return
         end
 
-        anchors = identifying_types(name)
-        fitting = anchors.empty? ? [] : @schemas.select { |s| anchors.all? { |t| s.get_type(t) } }
+        shape = identifying_types(name)
+        anchors = identifying(name)
+        fitting = @schemas.select do |schema|
+          shape.all? { |type| schema.get_type(type) } &&
+            anchors.any? { |coordinate| GraphWeaver::Internal::Schemas.defines?(schema, coordinate) }
+        end
         return fitting if fitting.any?
 
         @skipped[name] = anchors
@@ -168,23 +217,52 @@ module GraphWeaver
         @table.types.select { |type| @table.declared_in(type).include?(name) }
       end
 
-      # The types that recognize this subgraph's schema: the ones it
-      # declares, minus the roots every subgraph has.
+      # The types this subgraph's schema has to have: the ones it declares,
+      # minus the roots every subgraph has.
       def identifying_types(name) = declared_types(name) - ROOTS
 
-      # Fields the supergraph says this subgraph resolves, but none of its
-      # candidate schemas still defines. Every declared field, not only the
-      # explicitly routed ones — a field with no @join__field lives wherever
-      # its type does, and dropping one is exactly the drift this looks for.
+      # What tells this subgraph apart: the coordinates the supergraph
+      # attributes to it and to nobody else. The entity two subgraphs extend
+      # is declared by both, so it says nothing about which of them a schema
+      # is — taken as the whole of the evidence it matched an absent subgraph
+      # to its neighbour and called every field only the absent one resolves
+      # stale. A subgraph that shares everything it declares has no evidence
+      # at all, and is "not here" rather than guessed at.
+      def identifying(name)
+        types = declared_types(name).select { |type| @table.declared_in(type) == [name] } - ROOTS
+        types + @table.types.flat_map do |type|
+          @table.declared_fields(type).filter_map do |field|
+            "#{type}.#{field}" if @table.owners(type, field) == [name]
+          end
+        end
+      end
+
+      # Fields the supergraph says this subgraph resolves that its candidate
+      # schemas no longer define (stale), or define with another type
+      # (shape). Every declared field, not only the explicitly routed ones —
+      # a field with no @join__field lives wherever its type does, and
+      # dropping one is exactly the drift this looks for.
+      #
+      # A field can legitimately sit in more than one candidate (@shareable,
+      # an @external copy), so one agreeing schema settles it: the subgraph
+      # this supergraph describes is here somewhere.
       def record_stale(name, fitting)
         declared_types(name).each do |type_name|
           @table.declared_fields(type_name).each do |field_name|
             next unless @table.owners(type_name, field_name).include?(name)
 
             coordinate = "#{type_name}.#{field_name}"
-            next if fitting.any? { |schema| GraphWeaver::Internal::Schemas.defines?(schema, coordinate) }
+            here = fitting.filter_map { |schema| GraphWeaver::Internal::Schemas.signature(schema, coordinate) }
+            if here.empty?
+              (@stale[coordinate] ||= []) << name
+              next
+            end
+
+            composed = @table.signature(type_name, field_name)
+            next if composed.nil? || here.include?(composed)
 
-            (@stale[coordinate] ||= []) << name
+            entry = (@shape[coordinate] ||= { "subgraphs" => [], "supergraph" => composed, "here" => here.uniq })
+            entry["subgraphs"] << name
           end
         end
       end
@@ -221,6 +299,7 @@ module GraphWeaver
       def headline
         counts = [
           ("#{@stale.size} stale" if @stale.any?),
+          ("#{@shape.size} shape" if @shape.any?),
           ("#{@uncomposed.size} not composed in" if @uncomposed.any?),
         ].compact
         # "matches the schemas here" over nothing compared is the one verdict
@@ -228,12 +307,24 @@ module GraphWeaver
         verdict =
           if counts.any? then counts.join(", ")
           elsif vacuous? then "compared against nothing here"
-          else "matches the schemas here"
+          else "matches the schemas here, field for field and type for type"
           end
         "#{@source}: #{verdict} " \
           "(checked #{@checked.size} of #{@table.subgraphs.size} subgraphs)"
       end
 
+      # both signatures, because neither alone says which way to move: the
+      # supergraph's is what callers are generating against, the local one is
+      # what would actually answer
+      def shape_section
+        return [] if @shape.empty?
+
+        ["", SHAPE, *@shape.sort.map do |coordinate, entry|
+          "  #{coordinate} (#{entry["subgraphs"].join(", ")}): #{entry["supergraph"]} in the " \
+            "supergraph, #{entry["here"].join(", ")} here"
+        end]
+      end
+
       def section(title, entries)
         return [] if entries.empty?
 
@@ -245,9 +336,20 @@ module GraphWeaver
       def skipped_section
         return [] if @skipped.empty?
 
-        ["", "not checked — nothing here defines what the supergraph says these declare " \
-          "(running elsewhere, or the type is gone):",
-          *@skipped.sort.map { |name, types| "  #{name} (#{types.empty? ? "root types only" : types.join(", ")})" }]
+        ["", "not checked — no schema here matches what the supergraph says only these resolve " \
+          "(running elsewhere, or the subgraph is gone):",
+          *@skipped.sort.map { |name, what| "  #{name} (#{evidence(what)})" }]
+      end
+
+      # how many coordinates the report names before it says "and N more"
+      SAMPLE = 5
+      private_constant :SAMPLE
+
+      def evidence(coordinates)
+        return "the supergraph attributes nothing to it alone" if coordinates.empty?
+        return coordinates.join(", ") if coordinates.size <= SAMPLE
+
+        "#{coordinates.first(SAMPLE).join(", ")} and #{coordinates.size - SAMPLE} more"
       end
 
       def faked_section

data/lib/graph_weaver/graph.rb

@@ -0,0 +1,315 @@
+# typed: true
+# frozen_string_literal: true
+
+# One schema and everything generation needs to know about it: where its
+# queries live, where its Ruby goes, which client its modules call, what its
+# custom scalars and enums mean, and the namespace that keeps its constants
+# off another graph's.
+#
+# An app has at least one. The top-level settings (GraphWeaver.schema_path,
+# queries_paths, generated_paths, types_module) describe it, so a single-schema
+# app never says the word "graph" — and a second schema is a second graph
+# rather than a second copy of the recipe.
+
+module GraphWeaver
+  class Graph
+    # nil for the default graph — the one the settings describe, which has
+    # nothing to be called because there is nothing to tell it apart from.
+    attr_reader :name
+
+    # Each of these falls back to the matching top-level setting, so a graph
+    # says only what differs. output is one directory (a graph writes to one
+    # place); generated_paths stays the list of places to READ from.
+    def initialize(name: nil, schema: nil, queries: nil, output: nil, client: nil,
+      namespace: nil, types_module: nil, registrations: nil)
+      @name = name
+      @schema = schema
+      @queries = queries
+      @output = output
+      @client = client
+      @namespace = namespace
+      @types_module = types_module
+      @registrations = registrations
+    end
+
+    # The registrations this graph generates with: the top-level ones as they
+    # stand now, with this graph's own laid on top. Read here rather than
+    # captured at declaration, because in Rails the initializer that registers
+    # a scalar and the one that declares a graph run in alphabetical filename
+    # order — which can't be allowed to decide whether the registration lands.
+    # The default graph is the top-level registry.
+    def registry
+      return GraphWeaver::Codegen.registry unless @registrations
+
+      GraphWeaver::Codegen.registry.dup.tap do |registry|
+        registry.graph_name = @name
+        @registrations.each { |registration| replay(registry, registration) }
+      end
+    end
+
+    # One recorded registration, against this read's copy of the registry.
+    #
+    # A block-form extend_type mints a module whose constant name generated
+    # source spells, and a registration is replayed on every read — so the
+    # block runs once, at the declaration (GraphBuilder.build reads the
+    # registry there), and every read after replays the module it made.
+    def replay(registry, registration)
+      call, args, kwargs, block = registration
+      entry = registry.public_send(call, *args, **kwargs, &block)
+      return unless block && call == :extend_type
+
+      registration[1] = args + [entry[:mixins].last]
+      registration[3] = nil
+    end
+    private :replay
+
+    def queries = @queries || GraphWeaver.queries_paths
+    def output = @output || GraphWeaver.generated_paths.first
+    def client = @client
+
+    # Every constant this graph generates lives under `namespace:` — the query
+    # modules and the shared types module alike. Two schemas that each have a
+    # person.graphql, or that each hoist an enum, otherwise fight over one
+    # constant; this is the one knob that settles both.
+    def namespace = @namespace
+
+    def types_module
+      @types_module || (namespace ? "#{namespace}::#{GraphWeaver.types_module}" : GraphWeaver.types_module)
+    end
+
+    # The graphql-ruby schema, however it was named: a class, a Client, a path
+    # to a dump, SDL, or a callable returning one. Resolved each time rather
+    # than memoized — in dev the class object is replaced on reload, as
+    # Internal::Util.live_schema notes, and a callable is how an initializer
+    # names a class Zeitwerk hasn't loaded yet.
+    def schema
+      return GraphWeaver::Internal::Util.locate_schema! unless @schema
+
+      GraphWeaver::Internal::Util.schema_for(named_source)
+    end
+
+    # Whether this graph names its own schema. The default graph doesn't — it
+    # is whatever dump is at schema_path — which is what lets check_queries
+    # re-introspect that one and leave a named schema alone.
+    def named_schema? = !@schema.nil?
+
+    # The dump this graph's schema was named by, when it was named by a file —
+    # what a validation error's subgraph branding is read off. nil for a live
+    # class, a Client, or inline SDL.
+    def dump_path
+      path = named_dump_path
+      path if path && File.exist?(path)
+    end
+
+    # The dump this graph's schema NAMES, file or no file — dump_path once
+    # there is one, and where `schema:refresh` writes the first. A path is
+    # told from SDL by its extension, which is how SchemaLoader reads one
+    # anyway, and is the only question askable before the file exists.
+    def named_dump_path
+      return GraphWeaver::SchemaLoader.locate_path unless @schema
+
+      source = named_source
+      path = source.respond_to?(:to_path) ? source.to_path : source
+      path if path.is_a?(String) && GraphWeaver::SchemaLoader.dump_path?(path)
+    end
+
+    # What this graph's dump is derived FROM — what `schema:refresh`
+    # rewrites it from and `schema:diff` compares it against. The url the
+    # dump recorded, else the graphql-ruby schema class this process runs.
+    # nil when the dump is its own source: a committed artifact with nothing
+    # behind it to re-read.
+    #
+    # The recorded url wins because it is a fact the file states about
+    # itself, where a live class is an inference from whatever this app
+    # happens to execute against — and refreshing a foreign API's dump from
+    # the app's own schema would overwrite it with the wrong graph.
+    def dump_source
+      path = dump_path
+      # A dump this graph names but hasn't written yet has no provenance to
+      # read a source off, so the source is where its modules already post.
+      # That is what bootstraps a second graph's dump: URL= names one
+      # endpoint, and each graph has its own.
+      url = path ? GraphWeaver::SchemaLoader.provenance(path)&.dig("url") : (client_url if named_dump_path)
+      url || live_schema
+    end
+
+    # The url this graph's modules post to, or nil. `client:` holds a constant
+    # or its name — codegen spells it into source — so a name is resolved here
+    # the way the generated DEFAULT_CLIENT lambda resolves it; a graph baking
+    # none posts to the app default, which is where its modules go too.
+    def client_url
+      client = @client.is_a?(String) ? resolve_client! : @client
+      client ||= GraphWeaver.client
+      target = (client.transport if client.respond_to?(:transport)) || client
+      target.url if target.respond_to?(:url)
+    end
+    private :client_url
+
+    def resolve_client!
+      Object.const_get(@client)
+    rescue NameError
+      raise GraphWeaver::Error, "graph #{name.inspect} bakes client #{@client.inspect} into its " \
+        "modules and nothing defines that constant, so there is no endpoint to introspect " \
+        "#{named_dump_path} from"
+    end
+    private :resolve_client!
+
+    # The composed supergraph this graph plans against, or nil — the dump it
+    # names (for the default graph, the conventional one) when that dump
+    # carries the @join__* routing table. A graph whose schema is an API
+    # schema, or a live class, is in no supergraph of its own.
+    #
+    # One rule, asked by everything that needs one: the federation rake tasks
+    # report per graph off this, and Testing::Config resolves :router's
+    # supergraph through it.
+    def supergraph
+      path = dump_path
+      path if path && GraphWeaver::Internal::Util.composed?(path)
+    end
+
+    # The graphql-ruby schema class this graph runs in-process, or nil. The
+    # default graph's is the app client's (Internal::Util.live_schema).
+    def live_schema
+      return GraphWeaver::Internal::Util.live_schema unless @schema
+
+      source = named_source
+      source if source.is_a?(Class) && source <= GraphQL::Schema
+    end
+
+    # What `schema:` was given, with a callable called. A Proc is how an
+    # initializer names an autoloaded class; calling it here rather than at
+    # declaration is the whole point of allowing one — and the commonest way
+    # for one to be wrong is to answer nil (a config value that wasn't set, a
+    # guarded `defined?`, a safe_constantize). Refuse it here, where the graph
+    # and the setting are still in hand: dump_path, supergraph and live_schema
+    # all read this too, and every one of them would otherwise answer nil and
+    # send the blame somewhere else.
+    def named_source
+      source = @schema.respond_to?(:call) ? @schema.call : @schema
+      return source unless source.nil?
+
+      raise GraphWeaver::Error, "schema#{described} resolved to nil — schema takes a graphql-ruby " \
+        "schema class, a Client, a path to a dump, SDL, or a callable returning one"
+    end
+    private :named_source
+
+    # The module `path` generates, and the file it lands in. The namespace is
+    # the only thing a graph adds to the naming rule; the rest is the file name,
+    # as it is everywhere else.
+    def generated_names(path, source)
+      module_name, filename = GraphWeaver::Internal::Util.generated_names(path, source)
+      [namespace ? "#{namespace}::#{module_name}" : module_name, filename]
+    end
+
+    # How a message names this graph: " in graph :billing", or nothing at all
+    # for the default one, so a single-schema app's errors are unchanged.
+    def described = name ? " in graph #{name.inspect}" : ""
+  end
+
+  module Internal
+    # What a `GraphWeaver.graph` block is evaluated against: it collects the
+    # settings, runs the registrations, and refuses everything else — a typo
+    # is a mistake worth a message, not a call that vanishes.
+    #
+    # A separate object rather than the Graph itself, so a block can't reach a
+    # Graph's internals and a Graph stays a plain value. An app writes the
+    # block and never names this.
+    class GraphBuilder
+      # Everything a graph can say, in the order the docs teach it. `schema "x"`
+      # sets and bare `schema` reads back — there is no `schema =` form, because
+      # instance_eval would make that a local variable that silently does nothing.
+      SETTINGS = %i[schema queries output client namespace types_module].freeze
+      # The same three calls an app already writes at the top level, scoped here
+      # to this graph alone.
+      REGISTRATIONS = %i[register_scalar register_enum extend_type].freeze
+      # These three end up spelled in generated source, so each takes the
+      # constant or its name and stores the name.
+      CONSTANT_SETTINGS = %i[client namespace types_module].freeze
+      # …and these two are spelled as a `module` DEFINITION rather than a
+      # reference, which is why a root anchor is refused on them below.
+      MODULE_SETTINGS = %i[namespace types_module].freeze
+      private_constant :CONSTANT_SETTINGS, :MODULE_SETTINGS
+
+      attr_reader :settings, :registrations
+
+      # The Graph a block describes.
+      def self.build(name, &block)
+        builder = new(name)
+        builder.instance_eval(&block)
+        graph = GraphWeaver::Graph.new(name:, registrations: builder.registrations, **builder.settings)
+        # the block's registrations are applied at generation; run them once
+        # here so a bad one is a mistake in the block, said where it is written
+        graph.registry
+        graph
+      rescue NameError => e
+        # Ruby raises on the argument before the registration is ever called, so
+        # the block is the only place that can say why — and in Rails this is
+        # the commonest way to meet it. NoMethodError is a NameError too, and
+        # means something else entirely.
+        raise if e.is_a?(NoMethodError)
+
+        raise e.class, "#{e.message} — a graph block runs where it is written, so a registration " \
+          "in it stands where a top-level one does. #{GraphWeaver::Codegen::AUTOLOAD_HINT} " \
+          "Declare graph #{name.inspect} from one.", e.backtrace
+      end
+
+      def initialize(name)
+        @name = name
+        @settings = {}
+        # kept as calls rather than applied here: the graph replays them over
+        # the top-level registry at generation (see Graph#registry)
+        @registrations = []
+      end
+
+      SETTINGS.each do |setting|
+        define_method(setting) do |*value|
+          return @settings[setting] if value.empty?
+          raise ArgumentError, "#{setting} takes one value, got #{value.size}" if value.size > 1
+
+          @settings[setting] = GraphBuilder.constant_name(setting, value.first)
+        end
+      end
+
+      REGISTRATIONS.each do |registration|
+        define_method(registration) do |*args, **kwargs, &block|
+          @registrations << [registration, args, kwargs, block]
+        end
+      end
+
+      def method_missing(name, *, **, &) = raise(ArgumentError, refusal(name))
+
+      # Nothing reaches method_missing but a mistake, so the honest answer for
+      # every name it would catch is false.
+      def respond_to_missing?(name, _private = false) = false
+
+      # A Module where a constant's name goes says the same thing, and is what
+      # `client Billing::CLIENT` reads like. Anything else passes through:
+      # a schema is a path, SDL, a class, a Client, or a callable.
+      # On the singleton so the define_method setters above can reach it — srb
+      # reads a define_method block's self as the class.
+      def self.constant_name(setting, value)
+        return value unless CONSTANT_SETTINGS.include?(setting)
+
+        # Generated modules are defined at the top level, where a root anchor
+        # says nothing — and `module ::A::B` is not a name const_get can spell,
+        # so it used to surface as a verdict on the .graphql file's name.
+        if MODULE_SETTINGS.include?(setting) && value.is_a?(String) && value.start_with?("::")
+          raise ArgumentError, "#{setting} #{value.inspect}: drop the leading `::` — #{setting} " \
+            "names a module generated source defines, and it defines it at the top level either way"
+        end
+        return value unless value.is_a?(Module)
+
+        value.name || raise(ArgumentError, "#{setting} needs a constant — generated source has " \
+          "to spell it — and #{value.inspect} is anonymous")
+      end
+
+      def refusal(name)
+        takes = SETTINGS + REGISTRATIONS
+        near = GraphWeaver::Internal::Util.did_you_mean(takes.map(&:to_s), name.to_s)
+        "#{name} isn't something a graph block takes#{near ? " (did you mean #{near}?)" : ""} — " \
+          "graph #{@name.inspect} takes #{takes.join(", ")}"
+      end
+      private :refusal
+    end
+  end
+end