graph_weaver 0.6.0 → 0.7.0

data/lib/graph_weaver.rb

@@ -7,10 +7,12 @@ require_relative "graph_weaver/errors"
 require_relative "graph_weaver/coerce"
 require_relative "graph_weaver/hints"
 require_relative "graph_weaver/input_struct"
+require_relative "graph_weaver/result_struct"
 require_relative "graph_weaver/query_module"
 require_relative "graph_weaver/response"
 require_relative "graph_weaver/inflect"
 require_relative "graph_weaver/codegen"
+require_relative "graph_weaver/graph"
 require_relative "graph_weaver/client"
 require_relative "graph_weaver/in_process"
 require_relative "graph_weaver/transport/http"
@@ -19,8 +21,6 @@ require_relative "graph_weaver/schema_loader"
 require_relative "graph_weaver/version"
 require_relative "graph_weaver/railtie" if defined?(::Rails::Railtie)
 
-# opt-in extras:
-#      require "graph_weaver/transport/faraday"        # Faraday transport
 module GraphWeaver
   # The line every generated file opens with (see Codegen::Emit) — the marker
   # that tells generate! which files in the output directory are its to prune.
@@ -44,6 +44,21 @@ module GraphWeaver
       Client.new(source, **options, &middleware)
     end
 
+    # Every setting below, in initializer style — the shape an app already
+    # knows from Sidekiq, Devise and GraphWeaver::Testing:
+    #
+    #      GraphWeaver.configure do |config|
+    #        config.client = GraphWeaver.new(url, auth: token)
+    #        config.queries_paths = "app/graphql/operations"
+    #      end
+    #
+    # `config` is GraphWeaver itself, so this is the same call as the flat
+    # `GraphWeaver.client = ...`; both spellings stay valid.
+    def configure
+      yield self
+      self
+    end
+
     # The app's default client — how generated modules find their server:
     #
     #      GraphWeaver.client = GraphWeaver.new(url, auth: token)
@@ -83,11 +98,11 @@ module GraphWeaver
     end
     def cast_data(struct, data, errors)
       struct.from_h(data)
-    rescue GraphWeaver::TypeError => e
+    rescue GraphWeaver::CastError => e
       raise if errors.empty?
 
       detail = e.message.delete_prefix("failed to cast response into #{struct}: ")
-      raise GraphWeaver::TypeError.new(
+      raise GraphWeaver::CastError.new(
         struct:,
         message: "#{detail} — the server also reported: #{errors.map(&:message).join("; ")}",
       )
@@ -103,19 +118,19 @@ module GraphWeaver
     def check_envelope!(raw, struct)
       raw = raw.to_h if !raw.is_a?(Hash) && raw.respond_to?(:to_h)
       unless raw.is_a?(Hash)
-        raise GraphWeaver::TypeError.new(struct:, message: "response must be an object, got #{raw.class}")
+        raise GraphWeaver::CastError.new(struct:, message: "response must be an object, got #{raw.class}")
       end
 
       %w[data extensions].each do |key|
         value = raw[key]
         next if value.nil? || value.is_a?(Hash)
 
-        raise GraphWeaver::TypeError.new(struct:, message: "response #{key.inspect} must be an object, got #{value.class}")
+        raise GraphWeaver::CastError.new(struct:, message: "response #{key.inspect} must be an object, got #{value.class}")
       end
 
       errors = raw["errors"]
       unless errors.nil? || (errors.is_a?(Array) && errors.all?(Hash))
-        raise GraphWeaver::TypeError.new(struct:, message: "response \"errors\" must be an array of objects")
+        raise GraphWeaver::CastError.new(struct:, message: "response \"errors\" must be an array of objects")
       end
 
       # A response with neither key isn't a GraphQL response at all — a client
@@ -123,7 +138,7 @@ module GraphWeaver
       # "dat". Each otherwise passes as a success carrying no data.
       unless raw.key?("data") || raw.key?("errors")
         found = raw.empty? ? "it is empty" : "got #{raw.keys.first(5).map(&:inspect).join(", ")}"
-        raise GraphWeaver::TypeError.new(struct:, message:
+        raise GraphWeaver::CastError.new(struct:, message:
           "response carried neither \"data\" nor \"errors\" — #{found}; " \
           "the keys are the wire's own, as strings")
       end
@@ -160,9 +175,9 @@ module GraphWeaver
     #      GraphWeaver.queries_paths = "app/graphql/operations"
     #      GraphWeaver.generated_paths << "spec/graphql/generated"
     #
-    # schema_path is the exception, and singular on purpose: one generate! run
-    # reads ONE schema, so a second dump in a list is a file nothing would ever
-    # read. A second schema is a second generate! (schema: names it).
+    # schema_path is the exception, and singular on purpose: these settings
+    # describe ONE graph, so a second dump in a list is a file nothing would
+    # ever read. A second schema is a second graph (see #graph).
     attr_writer :schema_path
 
     def queries_paths = @queries_paths ||= ["app/graphql/queries"]
@@ -203,6 +218,160 @@ module GraphWeaver
 
     def types_module = @types_module || "GraphQLTypes"
 
+    # Declare a second schema — and a third, and the rest. Everything a graph
+    # knows is said inside its block, in call style:
+    #
+    #      GraphWeaver.graph :billing do
+    #        schema    -> { Billing::Schema }
+    #        queries   "app/graphql/billing/queries"
+    #        output    "app/graphql/billing/generated"
+    #        client    Billing::Schema
+    #        namespace "Billing"
+    #        register_scalar "Money", BigDecimal
+    #      end
+    #
+    # Every entry point then walks the list: one `rake graph_weaver:generate`
+    # does the app, one `verify` gates it, `check_queries` checks each graph
+    # against its own schema.
+    #
+    # Six settings — schema, queries, output, client, namespace, types_module —
+    # and the three registrations you already write at the top level. `schema "x"`
+    # sets and bare `schema` reads back; there is no `schema = "x"` form, since
+    # the block is instance_eval'd and that would be a local variable (this is
+    # graphql-ruby's `field :x` convention). Anything else the block calls is
+    # refused, naming the nine it takes.
+    #
+    # Each setting falls back to the matching top-level one, so a graph says
+    # only what differs; `namespace` nests everything that graph generates (the
+    # query modules and its shared types module) so two schemas with a
+    # person.graphql don't fight over one constant. The registrations reach this
+    # graph alone, on top of the top-level ones as they stand at declaration.
+    #
+    # The block runs where it is written. `schema` also takes a callable, which
+    # is how a Rails app names an autoloaded schema class from an initializer:
+    # `schema -> { Billing::Schema }` resolves when generation asks, and resolves
+    # again after a dev reload has replaced the class object. A registration
+    # naming an autoloaded constant has the same problem, and the same answer
+    # top-level registrations have always had (Codegen::AUTOLOAD_HINT).
+    #
+    # The name is the graph's identity, so re-declaring one REPLACES it —
+    # declaring from a `to_prepare` block, which re-runs on every reload, is
+    # safe. Declaring any graph replaces the implicit one the settings
+    # describe: an app either has graphs or has settings, never a silent third
+    # thing.
+    def graph(name, **keywords, &block)
+      unless name.is_a?(Symbol) || name.is_a?(String)
+        # codegen writes the name into every module this graph generates, so
+        # it has to be something source can spell
+        raise ArgumentError, "graph name must be a Symbol or a String, got #{name.inspect}"
+      end
+      # the name is the graph's identity, so the two spellings are one graph —
+      # re-declaring as `graph "billing"` replaces `graph :billing` rather than
+      # quietly making a second one that generates over the first's output
+      name = name.to_sym
+      unless keywords.empty?
+        raise ArgumentError, "GraphWeaver.graph takes a block, not keywords — say " \
+          "#{keywords.keys.join(", ")} inside it:\n" \
+          "    GraphWeaver.graph #{name.inspect} do\n" \
+          "      #{keywords.keys.first} #{keywords.values.first.inspect}\n" \
+          "    end"
+      end
+      unless block
+        raise ArgumentError, "GraphWeaver.graph #{name.inspect} needs a block — a graph says " \
+          "what it is inside one"
+      end
+
+      graph = Internal::GraphBuilder.build(name, &block)
+      @graphs ||= []
+      # replace in place, so the declaration order an app wrote is the order
+      # generate! reports in however many times the initializer has re-run
+      existing = @graphs.index { |candidate| candidate.name == name }
+      existing ? @graphs[existing] = graph : @graphs << graph
+      graph
+    end
+
+    # Every graph an entry point walks: the declared ones, or the single graph
+    # the top-level settings describe. Never empty.
+    def graphs = @graphs&.dup || [default_graph]
+
+    # Forget every declared graph — back to the settings alone.
+    def reset_graphs!
+      @graphs = nil
+      self
+    end
+
+    # The graph the settings describe. Built fresh each time: the settings are
+    # writable, and it holds the default registry rather than a copy so a
+    # top-level register_scalar reaches it.
+    def default_graph = Graph.new
+    private :default_graph
+
+    # The graphs one generate!/verify run covers. Explicit arguments describe
+    # one graph inline — the call generate! has always taken — and otherwise
+    # it is every graph.
+    def graphs_for(**overrides)
+      overrides = overrides.compact
+      return [Graph.new(**overrides)] unless overrides.empty?
+
+      refuse_orphaned_paths!
+      graphs
+    end
+    private :graphs_for
+
+    # Declaring a graph replaces the implicit one the top-level settings
+    # describe — so nothing then reads the directories those settings name, and
+    # an app that declared a graph beside its existing queries got no word
+    # about it. A .graphql left behind generates nothing, verify calls the tree
+    # up to date and queries:check calls the file validated; a generated module
+    # left behind is regenerated by nothing, pruned by nothing, and loaded by
+    # the railtie every boot. The docs promise an app either has graphs or has
+    # settings and never a silent third thing, so this is where that is true.
+    #
+    # Only an app that declared graphs can have one: for every other app the
+    # settings ARE its graph, and everything under them is covered by
+    # definition.
+    def refuse_orphaned_paths!
+      return unless @graphs
+
+      strays = Internal::Util.query_files(queries_paths) -
+        graphs.flat_map { |graph| Internal::Util.query_files(graph.queries) }
+      # generated_paths holds globs, so a graph's own output is found by this
+      # sweep — matched by where it writes rather than by how the glob spells it
+      written = graphs.map { |graph| Internal::Util.resolve(graph.output) }
+      strays += generated_paths.flat_map { |path| generated_files(path) }
+        .reject { |file| written.any? { |dir| file == dir || file.start_with?("#{dir}/") } }
+      return if strays.empty?
+
+      covers = graphs.map do |graph|
+        "  #{graph.name ? "graph #{graph.name.inspect}" : "this app"}: " \
+          "#{Array(graph.queries).join(", ")} -> #{Internal::Util.relative(graph.output)}"
+      end
+      raise Error, ["these files are under directories no declared graph covers:",
+        *strays.uniq.sort.map { |path| "  #{Internal::Util.relative(path)}" },
+        "Nothing generates or prunes them, verify and queries:check pass over them, and a " \
+          "generated module left here still loads in production. The graphs this app declared cover:",
+        *covers,
+        "These are the directories the top-level settings name — the graph this app had before " \
+          "it declared any — so declaring a second graph means declaring the first too:",
+        *settings_as_graph,
+        "Its directories and nothing else: no schema, so it reads the one the settings already " \
+          "name, and no namespace:, which keeps every constant name exactly as it is. Or name " \
+          "these directories in a graph above (queries/output in its block), or delete them."].join("\n")
+    end
+    private :refuse_orphaned_paths!
+
+    # The graph the top-level settings already describe, spelled as a
+    # declaration — the fix for the commonest way to arrive at the refusal
+    # above, which is declaring graph two in an app that had only settings.
+    def settings_as_graph
+      queries = queries_paths.map { |path| Internal::Util.relative(path).inspect }
+      ["  GraphWeaver.graph :app do",
+        "    queries #{queries.join(", ")}",
+        "    output  #{Internal::Util.relative(generated_paths.first).inspect}",
+        "  end"]
+    end
+    private :settings_as_graph
+
     # Generate every query in a directory — .graphql/.gql, subdirectories
     # included — into checked-in Ruby files. Paths default to the conventions
     # above; schema: defaults to the dump at schema_path (any supported
@@ -211,26 +380,44 @@ module GraphWeaver
     #
     #      GraphWeaver.generate!   # queries_paths -> generated_paths.first
     #
+    # With no arguments it generates every graph (see #graph) — which, for an
+    # app that declared none, is the one the settings above describe. Arguments
+    # describe one graph inline instead.
+    #
     # person.graphql => person_query.rb defining PersonQuery. Returns every
     # path the plan produces; a file already byte-identical is left untouched
     # (see #changed_files). Generated files the plan no longer produces are deleted
     # (see #orphaned), so renaming or dropping a .graphql leaves nothing
     # behind. Pair with a freshness spec (docs/generated_modules.md).
-    def generate!(schema: nil, queries: queries_paths, output: generated_paths.first, client: nil,
-      types_module: nil)
-      schema = schema ? schema_for(schema) : locate_schema!
-
-      if Internal::Util.query_files(queries).empty?
-        # a brand-new app legitimately has none; a mistyped queries_paths looks
-        # exactly the same, and prints nothing either way
-        Internal::Log.log(:warn) { "no query documents under #{Array(queries).join(", ")} — nothing to generate" }
+    def generate!(schema: nil, queries: nil, output: nil, client: nil, types_module: nil)
+      @changed_files = []
+      @unmatched_registrations = []
+      @untyped_scalars_by_graph = {}
+      seen = new_seen
+
+      # Every plan first, then every write. Generation refusing must leave the
+      # tree exactly as it was — the railtie's watch mode regenerates on a
+      # request and promises a failed save changes nothing, and that promise
+      # was true within a graph and false across them.
+      planned = graphs_for(schema:, queries:, output:, client:, types_module:).map do |graph|
+        if Internal::Util.query_files(graph.queries).empty?
+          # a brand-new app legitimately has none; a mistyped queries_paths looks
+          # exactly the same, and prints nothing either way
+          Internal::Log.log(:warn) do
+            "no query documents under #{Array(graph.queries).join(", ")}#{graph.described} — nothing to generate"
+          end
+        end
+
+        [graph, generation_plan(graph, seen)]
       end
 
-      plan = generation_plan(queries:, schema:, client:, types_module:)
-      @unmatched_registrations = Codegen.unmatched_registrations(schema)
-      @changed_files = []
+      planned.flat_map { |graph, plan| write_plan!(graph, plan) }
+    end
+
+    # One graph's plan onto disk, pruning what it no longer produces.
+    def write_plan!(graph, plan)
       written = plan.map do |filename, source|
-        target = File.join(Internal::Util.resolve(output), filename)
+        target = File.join(Internal::Util.resolve(graph.output), filename)
         next target if current?(target, source)
 
         FileUtils.mkdir_p(File.dirname(target))
@@ -244,13 +431,28 @@ module GraphWeaver
         target
       end
 
-      orphaned(output, written).each do |orphan|
+      pruned = orphaned(graph.output, written)
+      pruned.each do |orphan|
         File.delete(orphan)
         Internal::Log.log(:info) { "pruned #{Internal::Util.relative(orphan)}" }
       end
+      prune_empty!(graph, pruned)
 
       written.map { |target| Internal::Util.relative(target) }
     end
+    private :write_plan!
+
+    # Pruning promises to leave nothing behind, and the types/ directory whose
+    # last file just went is something behind. One level deep is the whole of
+    # it: a generated file's name is its base name, so types/ is the only
+    # subdirectory generation makes.
+    def prune_empty!(graph, pruned)
+      output = Internal::Util.resolve(graph.output)
+      pruned.map { |orphan| File.dirname(orphan) }.uniq.each do |dir|
+        Dir.rmdir(dir) if dir != output && Dir.exist?(dir) && Dir.empty?(dir)
+      end
+    end
+    private :prune_empty!
 
     # Which of those files the last generate! actually wrote — the rest were
     # already byte-identical, so a run that changed one query touches one file
@@ -286,33 +488,71 @@ module GraphWeaver
     #      it "generated queries are current" do
     #        GraphWeaver.verify_generated!
     #      end
-    def verify_generated!(schema: nil, queries: queries_paths, output: generated_paths.first, client: nil,
-      types_module: nil)
-      if Internal::Util.query_files(queries).empty?
-        # green over nothing is worse than red: a CI gate stays passing
-        # forever because someone typed app/graphql/querys
-        raise Error, "no query documents under #{Array(queries).join(", ")} — this checked nothing, " \
-          "so it proved nothing (set GraphWeaver.queries_paths, or pass queries:)"
-      end
+    def verify_generated!(schema: nil, queries: nil, output: nil, client: nil, types_module: nil)
+      @unmatched_registrations = []
+      @untyped_scalars_by_graph = {}
+      seen = new_seen
+      graphs = graphs_for(schema:, queries:, output:, client:, types_module:)
+
+      # The dump is checked in too, and everything below reads it — so a
+      # stale one is answered before staleness downstream of it, because
+      # refreshing has to come first. Asked only where it can be: a live
+      # class, and one introspection of it.
+      graphs.each { |graph| refuse_stale_dump!(graph) }
+
+      graphs.each do |graph|
+        if Internal::Util.query_files(graph.queries).empty?
+          # green over nothing is worse than red: a CI gate stays passing
+          # forever because someone typed app/graphql/querys
+          raise Error, "no query documents under #{Array(graph.queries).join(", ")}#{graph.described} — " \
+            "this checked nothing, so it proved nothing (set GraphWeaver.queries_paths, or pass queries:)"
+        end
 
-      schema = schema ? schema_for(schema) : locate_schema!
-      plan = generation_plan(queries:, schema:, client:, types_module:)
-      @unmatched_registrations = Codegen.unmatched_registrations(schema)
-      stale = plan.filter_map do |filename, source|
-        target = File.join(Internal::Util.resolve(output), filename)
-        target unless current?(target, source)
-      end
-      # strays: a generated file the current schema + queries no longer produce
-      stale += orphaned(output, plan.map { |filename, _| File.join(Internal::Util.resolve(output), filename) })
+        plan = generation_plan(graph, seen)
+        resolved = ->(filename) { File.join(Internal::Util.resolve(graph.output), filename) }
+        stale = plan.filter_map do |filename, source|
+          target = resolved.call(filename)
+          target unless current?(target, source)
+        end
+        # strays: a generated file the current schema + queries no longer produce
+        stale += orphaned(graph.output, plan.map { |filename, _| resolved.call(filename) })
 
-      unless stale.empty?
-        raise Error, "stale generated queries — regenerate (rake graph_weaver:generate): " \
-          "#{stale.map { |path| Internal::Util.relative(path) }.join(", ")}"
+        unless stale.empty?
+          raise Error, "stale generated queries#{graph.described} — regenerate (rake graph_weaver:generate): " \
+            "#{stale.map { |path| Internal::Util.relative(path) }.join(", ")}"
+        end
       end
 
       true
     end
 
+    # A dump that has fallen behind the graphql-ruby class it was built
+    # from. `verify` asks whether what is checked in is current, and for an
+    # app that serves its own schema the dump is an artifact derived from
+    # code in the same repo: it drifts silently, and generating from it
+    # then produces stale Ruby that verify would call fresh.
+    #
+    # Only a live class is asked — it answers introspection in-process, so
+    # this costs one introspection and no network. A dump that records a
+    # url is `schema:diff`'s subject: reaching for it here would put a
+    # network call in every build and in every spec that calls this.
+    def refuse_stale_dump!(graph)
+      path = graph.dump_path
+      source = graph.dump_source
+      return unless path && source.is_a?(Module)
+
+      diff = SchemaLoader.diff(path, transport: source)
+      return if diff.empty?
+
+      breaking = diff.breaking.size
+      raise Error, "the dump is behind the schema#{graph.described} — " \
+        "#{Internal::Util.relative(path)} no longer matches #{SchemaLoader.endpoint(source)} " \
+        "(#{diff.changes.size} #{(diff.changes.size == 1) ? "change" : "changes"}, " \
+        "#{breaking} breaking). Run rake graph_weaver:schema:refresh, then rake " \
+        "graph_weaver:generate — rake graph_weaver:schema:diff names what moved."
+    end
+    private :refuse_stale_dump!
+
     # Whether the file on disk is already what the plan would write — asked
     # before writing it, and before calling it stale. autocrlf rewrites line
     # endings on checkout, and a Windows working copy is neither stale
@@ -328,6 +568,21 @@ module GraphWeaver
     # instead of once per query file.
     def unmatched_registrations = @unmatched_registrations || []
 
+    # The custom scalars the last generate!/verify_generated! found no
+    # registration for — they generate as T.untyped, which is legitimate but
+    # is the one hole in an otherwise exact result type. Names, sorted, empty
+    # when every scalar a query touched is registered. The same list codegen
+    # logs at info, kept here so the build can print it once instead of once
+    # per query file.
+    def untyped_scalars = untyped_scalars_by_graph.values.flatten.uniq.sort
+
+    # The same, kept apart by the graph that found them. A registration is
+    # scoped to one graph, so a scalar registered for one and forgotten for
+    # the next is a different finding from one forgotten everywhere — and a
+    # merged list can't tell them apart. Keyed by graph name, nil for an app
+    # that declared none.
+    def untyped_scalars_by_graph = @untyped_scalars_by_graph || {}
+
     # Which checked-in queries no longer validate — breaking-change
     # detection scoped to the operations you actually ship. Reports rather
     # than raising, keyed by file, JSON-ready like every #to_h here:
@@ -350,29 +605,42 @@ module GraphWeaver
     # A different question from verify_generated!, which asks whether the
     # committed Ruby matches the committed schema. `rake
     # graph_weaver:queries:check` prints this and exits non-zero.
-    def check_queries(schema: nil, queries: queries_paths, fragments: fragments_paths)
-      # subgraph branding comes from the local supergraph dump, so a caller
-      # supplying its own schema opts out of it
-      table = schema ? nil : checked_routing_table
-      schema = schema ? schema_for(schema) : refreshed_schema
+    def check_queries(schema: nil, queries: nil, fragments: fragments_paths)
       shared = Codegen.load_fragments(fragments)
 
-      Internal::Util.query_files(queries).each_with_object({}) do |path, failures|
-        errors = validation_errors(schema, File.read(path), shared, table)
-        failures[Internal::Util.relative(path)] = errors if errors.any?
+      graphs_for(schema:, queries:).each_with_object({}) do |graph, failures|
+        checked = checked_schema(graph)
+        table = checked_routing_table(graph)
+        Internal::Util.query_files(graph.queries).each do |path|
+          errors = validation_errors(checked, File.read(path), shared, table)
+          next if errors.empty?
+
+          # keyed by file, as it has always been — and two graphs may share a
+          # queries directory (the same operations against two subgraphs), so
+          # the second one's errors join the first's rather than replacing them
+          key = Internal::Util.relative(path)
+          failures[key] = failures.key?(key) ? failures[key] | errors : errors
+        end
       end
     end
 
+    # What this graph is checked against. A graph that names its schema is
+    # checked against exactly that, so nothing touches the network; the default
+    # graph names none, so its dump is re-introspected first (see
+    # refreshed_schema).
+    def checked_schema(graph) = graph.named_schema? ? graph.schema : refreshed_schema
+    private :checked_schema
+
     # The routing table behind the schema check_queries is about to use,
     # when there is one: a composed supergraph dump says who resolves what,
     # so a validation error can name the subgraph whose code to look at. nil
     # for every other source — a plain schema is entirely unaffected — and
     # nil when a live schema class is what gets checked, since the dump then
     # isn't what the errors came from.
-    def checked_routing_table
-      return if Internal::Util.live_schema
+    def checked_routing_table(graph)
+      return if graph.live_schema
 
-      path = SchemaLoader.locate_path
+      path = graph.dump_path
       return unless path&.end_with?(".graphql", ".gql")
 
       sdl = File.read(path)
@@ -392,8 +660,8 @@ module GraphWeaver
       live = Internal::Util.live_schema
       return live if live
 
-      # locate_schema! raises the conventional "no schema dump" message
-      path = SchemaLoader.locate_path or locate_schema!
+      # Internal::Util.locate_schema! raises the conventional "no schema dump" message
+      path = SchemaLoader.locate_path or Internal::Util.locate_schema!
       return SchemaLoader.load(path) unless SchemaLoader.provenance(path)&.key?("url")
 
       # source_transport rather than one built here: it reads the auth ENV var
@@ -420,12 +688,12 @@ module GraphWeaver
         }
         subgraphs.empty? ? entry : entry.merge("subgraphs" => subgraphs)
       end
-    rescue GraphWeaver::ValidationError => e
+    rescue GraphWeaver::QueryValidationError => e
       # an unparseable query: codegen folds the position (and the file) into
       # the message, and this report keeps them separate — same splitter the
       # rendered error uses, so the two can't drift apart
       e.errors.map do |detail|
-        _path, _position, message = ValidationError.split(detail)
+        _path, _position, message = QueryValidationError.split(detail)
         detail.transform_keys(&:to_s).merge("message" => message)
       end
     end
@@ -460,19 +728,34 @@ module GraphWeaver
     # generated code only changes on regeneration anyway (restart, like
     # a schema migration).
     def load_generated!(path = nil)
-      paths = path ? [path] : generated_paths
+      paths = path ? [path] : Internal::Util.generated_dirs
       files = paths.flat_map { |dir| Dir[File.join(Internal::Util.resolve(dir), "**/*.rb")].sort }.uniq
       files.each do |file|
         require file
       rescue NameError => e
         reported = Internal::Util.relative(file)
+        # Zeitwerk autoloading the file rather than this require: it expects
+        # the constant the path spells, and generated modules are top-level.
+        # Nothing was dropped, so the advice below would send you hunting for
+        # a registration that is still there.
+        if zeitwerk_name_error?(e)
+          raise Error, "#{reported} can't load: #{e.message}. Zeitwerk owns that directory, and a " \
+            "generated module defines a top-level constant — so the one Zeitwerk expects never appears. " \
+            "The directory has to be hidden from autoloading: name it in GraphWeaver.generated_paths " \
+            "from config/initializers (the Railtie ignores what is listed there, and only before Rails " \
+            "sets Zeitwerk up), or generate into the conventional app/graphql/*/generated."
+        end
+
         # a dropped extend_type leaves this include dangling; say so here,
         # because the raw NameError points at generated code and names no fix
-        helper = e.message[/GraphWeaver::TypeHelpers::(\w+)/, 1]
+        # a block-built helper is named for its graph as well as its type
+        # (TypeHelpers::Billing::Pet), so the constant says where to look
+        # rather than spelling the extend_type back
+        helper = e.message[/GraphWeaver::TypeHelpers::[\w:]+/]
         if helper
-          raise Error, "#{reported} includes GraphWeaver::TypeHelpers::#{helper}, but nothing registers it — " \
-            "the extend_type(#{helper.inspect}) it was generated from is gone. Re-add that registration, " \
-            "or regenerate without it: rake graph_weaver:generate"
+          raise Error, "#{reported} includes #{helper}, but nothing registers it — the extend_type " \
+            "block it was generated from is gone. Re-add that registration, or regenerate without " \
+            "it: rake graph_weaver:generate"
         end
 
         # an app's own mixin or enum class named by extend_type/register_enum
@@ -498,10 +781,15 @@ module GraphWeaver
     # whose query was just deleted keeps its old constant until restart —
     # nothing on disk says what it was called any more.
     def reload_generated!
-      names = Internal::Util.query_files.map { |path| Internal::Util.module_name(path, File.read(path)) } << types_module
+      names = graphs.flat_map do |graph|
+        modules = Internal::Util.query_files(graph.queries).map do |path|
+          graph.generated_names(path, File.read(path)).first
+        end
+        modules << graph.types_module
+      end
       names.each { |name| undefine(name) }
 
-      generated_paths.each do |dir|
+      Internal::Util.generated_dirs.each do |dir|
         Dir[File.join(Internal::Util.resolve(dir), "**/*.rb")].each do |file|
           # require stores the realpath; the path load_generated! passed is
           # the other one under a symlinked checkout
@@ -512,6 +800,19 @@ module GraphWeaver
       load_generated!
     end
 
+    # The class when zeitwerk is loaded; its message otherwise, since the gem
+    # doesn't depend on zeitwerk and load_generated! runs outside Rails too.
+    # const_get rather than a bare Zeitwerk, as in rails_root: sorbet can't
+    # resolve a constant the gem doesn't depend on.
+    def zeitwerk_name_error?(error)
+      if Object.const_defined?("Zeitwerk::NameError")
+        error.is_a?(Object.const_get("Zeitwerk::NameError"))
+      else
+        error.message.match?(/\Aexpected file .* to define constant /)
+      end
+    end
+    private :zeitwerk_name_error?
+
     # remove_const takes a bare name, and types_module may be namespaced
     def undefine(name)
       *outer, base = name.split("::")
@@ -524,26 +825,6 @@ module GraphWeaver
     end
     private :undefine
 
-    # Anywhere GraphWeaver takes schema:, a Client stands for its schema — so
-    # the console object and the rake task point at the same thing. A path
-    # (String or Pathname) or SDL loads like it does everywhere else in the
-    # library; without that it reached `schema.validate` as itself and failed
-    # as `undefined method 'validate' for an instance of String`.
-    def schema_for(source)
-      return source.schema if source.is_a?(Client)
-      return SchemaLoader.load(source) if source.is_a?(String) || source.respond_to?(:to_path)
-
-      source
-    end
-    private :schema_for
-
-    # the conventional schema dump, required
-    def locate_schema!
-      SchemaLoader.locate or raise Error,
-        "no schema dump at #{schema_path} (.json/.graphql/.gql) — pass schema:, or cache one: GraphWeaver.new(url, cache: true).schema"
-    end
-    private :locate_schema!
-
     # (filename, source) per artifact. Types a schema shares across queries —
     # input types, schema enums, and each named shared fragment spread as a
     # whole-union field — are emitted once into the shared module, with query
@@ -551,51 +832,119 @@ module GraphWeaver
     # duplicated bool_exp structs (or one Ruby class per query for the same
     # schema enum) and one copy per schema. (Single-query parse inlines
     # everything — there's no cross-query set to share against.)
-    def generation_plan(queries:, schema:, client:, types_module: nil, fragments: fragments_paths)
-      types_module ||= self.types_module
+    # What one run has already produced, shared across every graph in it:
+    # constants are global and output files are just files, so two graphs
+    # landing on either would overwrite each other silently.
+    def new_seen = { modules: {}, files: {}, types: {} }
+    private :new_seen
+
+    def generation_plan(graph, seen = new_seen, fragments: fragments_paths)
+      @untyped_scalars_by_graph ||= {}
+      found = (@untyped_scalars_by_graph[graph.name] ||= [])
+      schema = graph.schema
+      registry = graph.registry
+      @unmatched_registrations |= registry.unmatched_registrations(schema)
+
       used = { inputs: [], enums: [], mapped: [] }
       used_unions = []
       shared = Codegen.load_fragments(fragments)
 
-      seen = {} # module name => the file that produced it, for the collision message
-
-      plan = Internal::Util.query_files(queries).map do |path|
+      plan = Internal::Util.query_files(graph.queries).map do |path|
         source = File.read(path)
-        name, filename = Internal::Util.generated_names(path, source)
-        if (earlier = seen[name])
-          raise Error, "duplicate query module #{name} — #{Internal::Util.relative(earlier)} and " \
-            "#{Internal::Util.relative(path)} both generate it; " \
-            "the module name comes from the file name alone (directories don't namespace it), so rename one"
-        end
-        seen[name] = path
+        name, filename = graph.generated_names(path, source)
+        refuse_duplicate!(seen, name, filename, graph, path)
 
         codegen = Codegen.new(
           schema:,
           query: Codegen.inline_fragments(source, shared, path),
           name:,
-          client:,
-          types_namespace: types_module,
+          client: graph.client,
+          graph_name: graph.name,
+          types_namespace: graph.types_module,
           hoistable_unions: Codegen.shared_fragment_spreads(source, shared, path),
           path:,
+          registry:,
         )
         out = codegen.generate
         codegen.variable_type_names.each { |kind, names| used[kind] |= names }
+        found.concat(codegen.untyped_scalars).uniq!
         used_unions |= codegen.used_union_names
         [filename, out]
       end
 
       if used_unions.any? || used.values.any?(&:any?)
-        codegen = Codegen.new(schema:, query: "", name: types_module)
-        plan = codegen.generate_types(
+        refuse_duplicate_types!(seen, graph)
+        codegen = Codegen.new(schema:, query: "", name: graph.types_module, registry:)
+        types = codegen.generate_types(
           inputs: used[:inputs], enums: used[:enums] + used[:mapped],
           unions: used_unions, fragments: shared,
-        ).to_a + plan
+        )
+        found.concat(codegen.untyped_scalars).uniq!
+        # these land in the graph's output like any other file, so they collide
+        # with another graph's the same way
+        types.each_key { |filename| refuse_duplicate_file!(seen, filename, graph, graph.types_module) }
+        plan = types.to_a + plan
       end
 
       plan
     end
     private :generation_plan
 
+    # Two query files landing on one constant, or on one output file. Within a
+    # graph the fix is a rename, as it has always been; across two graphs it is
+    # `namespace:` for the constant and `output:` for the file — so the message
+    # names whichever one applies.
+    #
+    # The two checks are separate because a namespace fixes only the first:
+    # `person_query.rb` is named after `person.graphql` whatever module it
+    # defines, so two graphs sharing an output directory still collide there.
+    def refuse_duplicate!(seen, name, filename, graph, path)
+      refuse_collision!(seen[:modules], name, graph, path, "query module #{name}",
+        across: "give one of the graphs a namespace:, or rename one of the files",
+        within: "the module name comes from the file name alone (directories don't " \
+          "namespace it), so rename one")
+      refuse_duplicate_file!(seen, filename, graph, path)
+    end
+    private :refuse_duplicate!
+
+    def refuse_duplicate_file!(seen, filename, graph, path)
+      target = File.join(Internal::Util.resolve(graph.output), filename)
+      refuse_collision!(seen[:files], target, graph, path,
+        "generated file #{Internal::Util.relative(target)}",
+        across: "give one of the graphs its own output:", within: "rename one of the files")
+    end
+    private :refuse_duplicate_file!
+
+    # Two graphs hoisting shared types into one module. Unlike a query module
+    # there is no file to rename — the name is a setting — and the failure it
+    # replaces was the worst kind: generation succeeded, and the app died at
+    # boot on sorbet-runtime's "Enum GraphQLTypes::Status was already
+    # initialized", which names neither graph.
+    def refuse_duplicate_types!(seen, graph)
+      earlier = seen[:types][graph.types_module]
+      seen[:types][graph.types_module] = graph
+      return if earlier.nil? || earlier.equal?(graph)
+
+      raise Error, "two graphs hoist shared types into #{graph.types_module} — " \
+        "#{earlier.name.inspect} and #{graph.name.inspect} both generate it, and a generated " \
+        "enum refuses a second definition; give one of the graphs a namespace: (or its own types_module:)"
+    end
+    private :refuse_duplicate_types!
+
+    # `across` is the fix when the two are in different graphs, `within` when
+    # they are the same graph — two situations with two different answers.
+    def refuse_collision!(seen, key, graph, path, subject, across:, within:)
+      earlier_graph, earlier = seen[key]
+      seen[key] = [graph, path]
+      return unless earlier
+
+      raise Error, "duplicate #{subject} — " \
+        "#{Internal::Util.relative(earlier)}#{earlier_graph.described} and " \
+        "#{Internal::Util.relative(path)}#{graph.described} both generate it; " \
+        "#{earlier_graph.equal?(graph) ? within : across}"
+    end
+    private :refuse_collision!
+
     # Whether generated modules/structs emit `extend T::Sig` (so `sig`
     # resolves standalone). Default (nil) auto-detects: an app that globally
     # injects T::Sig (`class Module; include T::Sig`) makes the per-struct
@@ -620,20 +969,26 @@ module GraphWeaver
     # rich Ruby object (and serializes back onto the wire when used as a
     # variable):
     #
-    #      GraphWeaver.register_scalar("Money", Money, requires: "bigdecimal")
+    #      GraphWeaver.register_scalar("Decimal", BigDecimal)
+    #      GraphWeaver.register_scalar("Money", Money)
     #
     # A field typed `Money` then generates `const :price, T.nilable(Money)`
-    # and casts with `Money.parse(...)` in from_h. Pass a real class as
-    # type: and cast:/serialize: are inferred from it — .parse/#to_s, or
-    # .load/.dump — by probing the deserialize side (see ScalarType::CODECS).
-    # Override with a Symbol method name (safest — no string to misspell), a
-    # Proc(expr) => code string, or :itself to force pass-through. requires:
-    # (a String or Array) names files the generated code needs — validated,
-    # and actually required to confirm it resolves when type: is a real class.
+    # and casts with `Money.parse(...)` in from_h. Pass a real class as type:
+    # and cast:/serialize: are inferred from it: a stdlib type the library
+    # knows (BigDecimal, Date, Time) brings its own codec and require, and
+    # anything else is probed on the deserialize side — .parse/#to_s,
+    # .load/.dump, or a Kernel conversion of its name (see ScalarType).
+    # Override with a Symbol method name (safest — no string to misspell),
+    # an Array for a method with arguments ([:to_s, "F"]), a Proc(expr) =>
+    # code string, or :itself to force pass-through. requires: (a String or
+    # Array) names files the generated code needs — validated, and actually
+    # required to confirm it resolves when type: is a real class.
     # cast: is also what an untyped variable input coerces through, so a
     # variable of this scalar takes the value OR its raw input ("12.00") with
-    # no static loosening — see GraphWeaver::Coerce. Built-in scalars are
-    # pre-registered the same way, so this also overrides them.
+    # no static loosening — see GraphWeaver::Coerce. The spec's own scalars
+    # and the conventional names (ISO8601Date, ISO8601DateTime, DateTime,
+    # BigInt, JSON) are pre-registered the same way, so this also overrides
+    # them — see Codegen::BUILTIN_SCALARS and docs/scalars.md.
     #
     # A scalar registered as a class of your own is the one value the testing
     # harness can't invent — only your `cast:` knows what it accepts — so it
@@ -708,9 +1063,15 @@ module GraphWeaver
     # "Query" for anonymous operations — collisions are impossible since each
     # parse gets its own container). Pass name: to override, client: to bake
     # the module's default client/transport.
-    def parse(schema:, query:, name: nil, client: nil, fragments: fragments_paths)
+    #
+    # graph: names the graph this module belongs to, which is what a test mode
+    # runs it against in an app with more than one — the same thing generation
+    # bakes into a file. Left out, it is the graph running this schema, when
+    # one is declared; an app with one graph never needs it.
+    def parse(schema:, query:, name: nil, client: nil, graph: nil, fragments: fragments_paths)
       client ||= schema if schema.is_a?(Client)
-      schema = schema_for(schema)
+      schema = Internal::Util.schema_for(schema)
+      graph_name = graph ? named_graph!(graph) : Internal::Util.graph_for(schema)&.name
       # Rails.root.join(...) hands you a Pathname, and to_path is the
       # ecosystem's "I am a path" — the same conversion schema: gets through
       # SchemaLoader.load. Without it end_with? below is a NoMethodError.
@@ -726,8 +1087,21 @@ module GraphWeaver
       end
       query = Codegen.inline_fragments(query, Codegen.load_fragments(fragments), path)
 
-      Codegen.parse(schema:, query:, name:, client:, path:)
+      Codegen.parse(schema:, query:, name:, client:, path:, graph_name:)
+    end
+
+    # `graph:`'s name, checked against what is declared — an unknown one would
+    # otherwise bake a GRAPH no mode can match, and be reported as a module
+    # that doesn't say which graph it came from.
+    def named_graph!(name)
+      declared = graphs.map(&:name).compact
+      found = declared.find { |candidate| candidate.to_s == name.to_s }
+      return found if found
+
+      raise ArgumentError, "graph: #{name.inspect} isn't declared — this app declares " \
+        "#{declared.empty? ? "none (see GraphWeaver.graph)" : declared.map(&:inspect).join(", ")}"
     end
+    private :named_graph!
 
     # One-shot dynamic execution — a throwaway client, no build step:
     #