graph_weaver 0.4.6 → 0.5.1

data/lib/graph_weaver.rb

@@ -5,10 +5,12 @@ require_relative "graph_weaver/logging"
 require_relative "graph_weaver/errors"
 require_relative "graph_weaver/hints"
 require_relative "graph_weaver/input_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/client"
+require_relative "graph_weaver/in_process"
 require_relative "graph_weaver/transport/http"
 require_relative "graph_weaver/retry"
 require_relative "graph_weaver/schema_loader"
@@ -18,6 +20,14 @@ 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.
+  GENERATED_HEADER = "# Generated by GraphWeaver"
+
+  # How far into a file to look for it: the header sits under the `typed:` and
+  # `frozen_string_literal:` magic comments, never deeper.
+  HEADER_SCAN_LINES = 10
+
   class << self
     # A client for one GraphQL server — transport, schema, and scoped
     # scalars in one object (see Client):
@@ -35,40 +45,113 @@ module GraphWeaver
     #
     #      GraphWeaver.client = GraphWeaver.new(url, auth: token)
     #
-    # Accepts a Client or anything satisfying the execute contract (a
-    # schema class, a fake — testing's auto_fake swaps one in per
+    # Anything satisfying the execute contract — a Client, a schema class,
+    # a transport, a fake (testing's graphql: tag swaps one in per
     # example). Generated modules resolve per call -> per module
     # (MyQuery.client=) -> baked constant -> here.
     attr_accessor :client
 
     # the default client, when one is required
     def client!
-      @client or raise Error, "no client configured — set GraphWeaver.client= or pass a client"
+      # in a spec suite this is nearly always a forgotten tag, and "set
+      # GraphWeaver.client=" is advice for the wrong file — graph_weaver/rspec
+      # being loaded is what says which suggestion is the useful one
+      @client or raise Error, "no client configured — " + if defined?(Testing::RSpecIntegration)
+        "tag the example graphql: :fake (or :in_process / :router), or build one with graphql_fake"
+      else
+        "set GraphWeaver.client= or pass a client"
+      end
+    end
+
+    # Shape-check a raw response envelope, returning it. Generated
+    # from_response is public API taking anything with #to_h, so a malformed
+    # body has to brand rather than escape as a raw Sorbet TypeError from a sig
+    # (which fires before the struct's own rescue can see it). Lives here rather
+    # than unrolled into every generated module.
+    # Cast a response's data, keeping the server's own errors on a failure.
+    # The common cause of a cast failure is a field that came back null *with
+    # a reason attached* — a permission rule, a partial outage — and raising
+    # only Sorbet's nil complaint throws that reason away, leaving whoever is
+    # on call with a type error and no explanation.
+    sig do
+      params(struct: T.untyped, data: T.untyped, errors: T::Array[GraphWeaver::GraphQLError])
+        .returns(T.untyped)
+    end
+    def cast_data(struct, data, errors)
+      struct.from_h(data)
+    rescue GraphWeaver::TypeError => e
+      raise if errors.empty?
+
+      detail = e.message.delete_prefix("failed to cast response into #{struct}: ")
+      raise GraphWeaver::TypeError.new(
+        struct:,
+        message: "#{detail} — the server also reported: #{errors.map(&:message).join("; ")}",
+      )
+    end
+
+    def check_envelope!(raw, struct)
+      unless raw.is_a?(Hash)
+        raise GraphWeaver::TypeError.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}")
+      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")
+      end
+
+      raw
     end
 
-    # The transport behind a client-or-transport value: a Client resolves
-    # to its own transport, anything else already speaks execute.
-    # Generated modules call this on every execute, so any slot in the
-    # resolution chain can hold either kind.
-    def resolve_transport(target)
-      target.is_a?(Client) ? target.transport! : target
+    # The module a .graphql file generates, and the basename of the file it
+    # generates into: the camelized file name plus the operation's own word.
+    #
+    #      person.graphql          => PersonQuery       (person_query.rb)
+    #      save_list_entry.graphql => SaveListEntryMutation
+    #                                 (save_list_entry_mutation.rb)
+    #
+    # Every naming site goes through here — generate!, parse(path), and
+    # load_queries! — so the constant a file produces is the same one
+    # whichever door you came in by, and the file it lands in matches it.
+    def generated_names(path, source)
+      base = File.basename(path, ".*")
+      suffix = operation_suffix(source)
+      ["#{Inflect.camelize(base)}#{suffix}", "#{base}_#{suffix.downcase}.rb"]
+    end
+
+    # just the module name — see generated_names
+    def module_name(path, source) = generated_names(path, source).first
+
+    # "Mutation" for a mutation document, "Query" for everything else.
+    def operation_suffix(source)
+      operation = GraphQL.parse(source).definitions
+        .grep(GraphQL::Language::Nodes::OperationDefinition).first
+      (operation&.operation_type == "mutation") ? "Mutation" : "Query"
+    rescue GraphQL::ParseError
+      "Query" # unparseable: codegen brands the real error a moment later
     end
 
-    # Conventional locations, factory_bot-style — LISTS, so extra
-    # locations (a test-only dir, an engine's) can be appended and every
-    # loader walks them all:
+    # Conventional locations. Every directory setting is a LIST,
+    # factory_bot-style: extra locations (a test-only dir, an engine's) can be
+    # appended and every reader walks them all. Entries may be glob patterns,
+    # and the generated default already matches per-schema layouts
+    # (app/graphql/github/generated). Assigning a String wraps it, so pointing
+    # at one directory stays a one-liner:
     #
-    #      # e.g. in spec/support/graph_weaver.rb
-    #      GraphWeaver.generated_paths << "spec/support/graphql/generated"
-    #      GraphWeaver.queries_paths << "spec/support/graphql/queries"
+    #      GraphWeaver.queries_paths = "app/graphql/operations"
+    #      GraphWeaver.generated_paths << "spec/graphql/generated"
     #
-    # The singular accessors read the first entry (the default target
-    # for generate! and the rake tasks); assigning one replaces the list.
-    attr_writer :queries_paths, :generated_paths, :schema_path, :fragments_paths
+    # 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).
+    attr_writer :schema_path
 
-    # Entries may be glob patterns — the generated default also matches
-    # per-schema layouts (app/graphql/github/generated). Queries stay
-    # single-schema: load_queries! parses everything against one client.
     def queries_paths = @queries_paths ||= ["app/graphql/queries"]
     def generated_paths = @generated_paths ||= ["app/graphql/generated", "app/graphql/*/generated"]
 
@@ -77,65 +160,59 @@ module GraphWeaver
     # query stays self-contained.
     def fragments_paths = @fragments_paths ||= ["app/graphql/fragments"]
 
-    def queries_path = queries_paths.first
-    def generated_path = generated_paths.first
-    def fragments_path = fragments_paths.first
+    # nil restores the default; a String is one entry, not a second spelling
+    def queries_paths=(paths)
+      @queries_paths = paths && Array(paths)
+    end
 
-    def queries_path=(path)
-      @queries_paths = path.nil? ? nil : [path]
+    def generated_paths=(paths)
+      @generated_paths = paths && Array(paths)
     end
 
-    def generated_path=(path)
-      @generated_paths = path.nil? ? nil : [path]
+    def fragments_paths=(paths)
+      @fragments_paths = paths && Array(paths)
     end
 
     def schema_path = @schema_path || "app/graphql/schema.json"
 
-    # The shared-inputs / shared-unions module names: set them globally, pass
-    # inputs_module:/unions_module: per generate!, or let them derive from the
-    # output path — the directory above generated/ names the schema in
-    # multi-schema layouts (app/graphql/github/generated => GithubInputs /
-    # GithubUnions); the conventional layout (and anything unrecognizable)
-    # stays GraphQLInputs / GraphQLUnions.
-    attr_writer :inputs_module, :unions_module
-
-    def inputs_module(output = generated_path)
-      @inputs_module || derive_module("Inputs", output)
-    end
-
-    def unions_module(output = generated_path)
-      @unions_module || derive_module("Unions", output)
-    end
+    # Set by every graph_weaver rake task: those tasks WRITE the generated
+    # files, so loading them first lets a stale one block its own repair.
+    # None of them needs the modules loaded.
+    attr_accessor :skip_generated_load
 
-    # Name a shared module from the output path: <Schema><suffix> in a
-    # multi-schema layout, else GraphQL<suffix>.
-    def derive_module(suffix, output)
-      segments = File.expand_path(output.to_s).split(File::SEPARATOR)
-      segments.pop if segments.last == "generated"
-      parent = segments.last.to_s
-      if parent.match?(/\A[a-zA-Z]\w*\z/) && !%w[graphql app lib spec support test].include?(parent)
-        "#{Inflect.camelize(parent)}#{suffix}"
-      else
-        "GraphQL#{suffix}"
-      end
+    # Every query document under these directories, sorted — the files
+    # generate!, verify_generated!, check_queries and load_queries! all read.
+    def query_files(paths = queries_paths)
+      Array(paths).flat_map { |dir| Dir[File.join(dir, Codegen::DOCUMENT_GLOB)].sort }
     end
-    private :derive_module
 
-    # Generate every .graphql query in a directory into checked-in Ruby
-    # files. Paths default to the conventions above; schema: defaults to
-    # the dump at schema_path (any supported extension):
+    # The name of the shared module — the types that live once per schema
+    # (input types, enums, unions hoisted from shared fragments) and are
+    # aliased into every query module that touches them. Constant, not derived
+    # from where you put the files: set it globally, or pass types_module: per
+    # generate!. A multi-schema layout names it in the same initializer that
+    # sets its paths.
+    attr_writer :types_module
+
+    def types_module = @types_module || "GraphQLTypes"
+
+    # 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
+    # extension), and also takes a Client (its schema — the console object,
+    # no dump needed):
     #
-    #      GraphWeaver.generate!   # queries_path -> generated_path
+    #      GraphWeaver.generate!   # queries_paths -> generated_paths.first
     #
     # person.graphql => person_query.rb defining PersonQuery. Returns the
-    # written paths. Pair with a freshness spec (docs/generated_modules.md).
-    def generate!(schema: nil, queries: queries_path, output: generated_path, client: nil,
-      inputs_module: nil, unions_module: nil)
-      schema ||= locate_schema!
-      inputs_module ||= self.inputs_module(output)
-      unions_module ||= self.unions_module(output)
-
-      plan = generation_plan(queries:, schema:, client:, inputs_module:, unions_module:)
+    # written paths. 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!
+
+      plan = generation_plan(queries:, schema:, client:, types_module:)
       written = plan.map do |filename, source|
         target = File.join(output, filename)
         FileUtils.mkdir_p(File.dirname(target))
@@ -144,9 +221,7 @@ module GraphWeaver
         target
       end
 
-      # a type dropped from the schema (or a union no longer hoisted) must not
-      # linger as a stale file — inputs/ and unions.rb are wholly generated
-      (shared_artifacts(output) - written).each do |orphan|
+      orphaned(output, written).each do |orphan|
         File.delete(orphan)
         log(:info) { "pruned #{orphan}" }
       end
@@ -154,32 +229,48 @@ module GraphWeaver
       written
     end
 
-    # The wholly-generated shared-artifact files under output (inputs/*.rb and
-    # unions.rb) — safe to prune when regeneration no longer produces them.
-    def shared_artifacts(output)
-      Dir[File.join(output, "inputs", "*.rb")] + Dir[File.join(output, "unions.rb")]
+    # Generated files under output the current plan no longer produces — a
+    # query renamed or deleted, a type dropped from the schema, a union no
+    # longer hoisted. Left alone they'd keep being required by
+    # load_generated!, resolving against a query that no longer exists.
+    def orphaned(output, produced)
+      current = produced.map { |path| File.expand_path(path) }
+      generated_files(output).reject { |path| current.include?(File.expand_path(path)) }
     end
-    private :shared_artifacts
+    private :orphaned
+
+    # Every .rb under output that GraphWeaver wrote, identified by the header
+    # it emits. The header — not a *_query.rb glob — is what makes pruning
+    # safe: this is a real directory, and a hand-written file in it must
+    # survive regeneration.
+    def generated_files(output)
+      Dir[File.join(output, "**/*.rb")].sort.select do |path|
+        File.foreach(path).first(HEADER_SCAN_LINES).any? { |line| line.start_with?(GENERATED_HEADER) }
+      end
+    end
+    private :generated_files
 
     # The freshness guard: raise unless every generated file matches what
-    # the current schema + queries + scalar registrations would produce.
-    # One line in a spec, or `rake graph_weaver:verify` in CI:
+    # the current schema + queries + scalar registrations would produce —
+    # counting a generated file the plan no longer produces as stale, so a
+    # deleted query can't leave a live module behind. One line in a spec, or
+    # `rake graph_weaver:verify` in CI:
     #
     #      it "generated queries are current" do
     #        GraphWeaver.verify_generated!
     #      end
-    def verify_generated!(schema: nil, queries: queries_path, output: generated_path, client: nil,
-      inputs_module: nil, unions_module: nil)
-      schema ||= locate_schema!
-      inputs_module ||= self.inputs_module(output)
-      unions_module ||= self.unions_module(output)
-      plan = generation_plan(queries:, schema:, client:, inputs_module:, unions_module:)
+    def verify_generated!(schema: nil, queries: queries_paths, output: generated_paths.first, client: nil,
+      types_module: nil)
+      schema = schema ? schema_for(schema) : locate_schema!
+      plan = generation_plan(queries:, schema:, client:, types_module:)
       stale = plan.filter_map do |filename, source|
         target = File.join(output, filename)
-        target unless File.exist?(target) && File.read(target) == source
+        # git's autocrlf rewrites line endings on checkout — a Windows working
+        # copy is not stale generated code, so don't fail CI over it
+        target unless File.exist?(target) && File.read(target).gsub("\r\n", "\n") == source.gsub("\r\n", "\n")
       end
-      # strays: a shared-artifact file the current schema + queries no longer produce
-      stale += shared_artifacts(output) - plan.map { |f, _| File.join(output, f) }
+      # strays: a generated file the current schema + queries no longer produce
+      stale += orphaned(output, plan.map { |filename, _| File.join(output, filename) })
 
       unless stale.empty?
         raise Error, "stale generated queries — regenerate (rake graph_weaver:generate): #{stale.join(", ")}"
@@ -188,6 +279,140 @@ module GraphWeaver
       true
     end
 
+    # 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:
+    #
+    #      GraphWeaver.check_queries
+    #      # => { "app/graphql/queries/person.graphql" =>
+    #      #      [{ "message" => "Field 'titel' doesn't exist on type 'Person'",
+    #      #         "line" => 4, "column" => 5 }] }
+    #
+    # Empty means every query validates. schema: defaults to the server as
+    # it is now — a FRESH introspection of the url the dump records, or the
+    # live schema class when the app default runs in-process — and the dump
+    # is left alone; pass schema: and nothing touches the network.
+    #
+    # When that dump is a composed supergraph, an error naming a type is
+    # branded with the subgraphs behind it — "…on type 'Product'
+    # (products, reviews)", plus a "subgraphs" key — since knowing whose
+    # code to look at is half the answer. A plain schema is unaffected.
+    #
+    # 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
+      shared = Codegen.load_fragments(fragments)
+
+      query_files(queries).each_with_object({}) do |path, failures|
+        errors = validation_errors(schema, File.read(path), shared, table)
+        failures[path] = errors if errors.any?
+      end
+    end
+
+    # 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 live_schema
+
+      path = SchemaLoader.locate_path
+      return unless path&.end_with?(".graphql", ".gql")
+
+      sdl = File.read(path)
+      SchemaLoader.routing_table(sdl) if SchemaLoader.federation_sdl?(sdl)
+    end
+    private :checked_routing_table
+
+    # The schema check_queries defaults to: the server as it is now. Over a
+    # socket that's a fresh introspection of the url the local dump recorded,
+    # so no refresh step (and no rewritten dump) is needed first. In-process
+    # it's the live schema class — for an app that IS the server, a dump is a
+    # snapshot of its own code, and checking against it reports phantom
+    # errors about a field you just added. Dumps with no url and no live
+    # class — hand-written SDL, a composed supergraph — have nothing to
+    # re-read, so they're checked as they are.
+    def refreshed_schema
+      live = live_schema
+      return live if live
+
+      # locate_schema! raises the conventional "no schema dump" message
+      path = SchemaLoader.locate_path or 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
+      # the dump named, so `--auth MY_TOKEN` reaches this path too
+      SchemaLoader.introspect(SchemaLoader.source_transport(path))
+    end
+    private :refreshed_schema
+
+    # The graphql-ruby schema class the app default executes against, when it
+    # runs in-process — a Client wrapping one, or the class in the slot bare.
+    # nil for every network client. Not memoized: in dev the class object is
+    # replaced on reload. (Public because testing's :in_process mode asks:
+    # a client already running in-process names its own schema class.)
+    def live_schema
+      # through #transport, not #schema: a url client's #schema introspects,
+      # so asking it would answer this question over the network
+      target = client.is_a?(Client) ? client.transport : client
+      target = target.schema if target.is_a?(InProcess)
+      target if target.is_a?(Class) && target <= GraphQL::Schema
+    end
+
+    # One query's schema-validation errors as JSON-ready hashes, with the
+    # source position graphql-ruby reports. Unparseable counts as an error
+    # too — it doesn't validate either, and inline_fragments (which parses
+    # first) has already branded it with its position.
+    def validation_errors(schema, source, shared, table = nil)
+      # path omitted: the caller keys the report by file, so branding the
+      # message with it too would just print the path twice
+      schema.validate(Codegen.inline_fragments(source, shared)).map do |error|
+        detail = error.to_h
+        location = detail["locations"]&.first || {}
+        subgraphs = table ? attribute(table, detail["extensions"]) : []
+        entry = {
+          "message" => subgraphs.empty? ? error.message : "#{error.message} (#{subgraphs.join(", ")})",
+          "line" => location["line"],
+          "column" => location["column"],
+        }
+        subgraphs.empty? ? entry : entry.merge("subgraphs" => subgraphs)
+      end
+    rescue GraphWeaver::ValidationError => 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)
+        detail.transform_keys(&:to_s).merge("message" => message)
+      end
+    end
+    private :validation_errors
+
+    # Which subgraphs a validation error is about, on a federated schema:
+    # "Field 'weight' doesn't exist on type 'Product'" is much less useful
+    # than the same line plus "(products)" — whose code to look at, whose
+    # team to talk to. graphql-ruby reports the coordinate structurally, so
+    # this is a lookup rather than message parsing. Both halves of the
+    # coordinate are required: an argument error reports typeName "Field"
+    # (the AST node kind, not a type), and looking that up would attribute
+    # confidently and wrongly.
+    def attribute(table, extensions)
+      return [] unless extensions
+
+      type_name, field_name = extensions.values_at("typeName", "fieldName")
+      return [] unless type_name && field_name
+
+      table.responsible(type_name, field_name)
+    end
+    private :attribute
+
     # Load the generated modules — one line in an initializer or spec
     # helper (loading happens only when you call this; skip it and
     # require files yourself if you'd rather):
@@ -201,11 +426,33 @@ module GraphWeaver
     def load_generated!(path = nil)
       paths = path ? [path] : generated_paths
       files = paths.flat_map { |dir| Dir[File.join(dir, "**/*.rb")].sort }.uniq
-      files.each { |file| require File.expand_path(file) }
+      files.each do |file|
+        require File.expand_path(file)
+      rescue NameError => e
+        # 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] or raise
+        raise Error, "#{file} 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"
+      end
       log(:info) { "loaded #{files.size} generated module(s) from #{paths.join(", ")}" }
       files
     end
 
+    # 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,
@@ -213,65 +460,64 @@ module GraphWeaver
     end
     private :locate_schema!
 
-    # (filename, source) per artifact. Every variable type is emitted once into
-    # inputs.rb, and each named shared fragment spread as a whole-union field
-    # once into unions.rb, with query modules aliasing what they use — the
-    # difference between hundreds of duplicated bool_exp structs (or the same
-    # union re-typed per query) and one copy per schema. (Single-query parse
-    # inlines both — there's no cross-query set to share against.)
-    def generation_plan(queries:, schema:, client:, inputs_module: self.inputs_module,
-      unions_module: self.unions_module, fragments: fragments_paths)
+    # (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
+    # modules aliasing what they use. That's the difference between hundreds of
+    # 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
       used = { inputs: [], enums: [], mapped: [] }
       used_unions = []
       shared = Codegen.load_fragments(fragments)
 
-      plan = Dir[File.join(queries, "*.graphql")].sort.map do |path|
-        base = File.basename(path, ".graphql")
+      seen = {} # module name => the file that produced it, for the collision message
+
+      plan = query_files(queries).map do |path|
         source = File.read(path)
+        name, filename = generated_names(path, source)
+        if (earlier = seen[name])
+          raise Error, "duplicate query module #{name} — #{earlier} and #{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
+
         codegen = Codegen.new(
           schema:,
-          query: Codegen.inline_fragments(source, shared),
-          module_name: "#{Inflect.camelize(base)}Query",
+          query: Codegen.inline_fragments(source, shared, path),
+          module_name: name,
           client:,
-          inputs_namespace: inputs_module,
-          unions_namespace: unions_module,
-          hoistable_unions: Codegen.shared_fragment_spreads(source, shared),
+          types_namespace: types_module,
+          hoistable_unions: Codegen.shared_fragment_spreads(source, shared, path),
+          path:,
         )
         out = codegen.generate
         codegen.variable_type_names.each { |kind, names| used[kind] |= names }
         used_unions |= codegen.used_union_names
-        ["#{base}_query.rb", out]
+        [filename, out]
       end
 
-      if inputs_module && used.values.any?(&:any?)
-        inputs = Codegen.generate_inputs(
-          schema:, module_name: inputs_module,
-          input_types: used[:inputs], enum_types: used[:enums] + used[:mapped],
-        )
-        plan = inputs.to_a + plan
-      end
-
-      if unions_module && used_unions.any?
-        unions = Codegen.generate_unions(
-          schema:, module_name: unions_module, fragments: shared, names: used_unions,
-        )
-        plan = unions.to_a + plan
+      if used_unions.any? || used.values.any?(&:any?)
+        codegen = Codegen.new(schema:, query: "", module_name: types_module)
+        plan = codegen.generate_types(
+          inputs: used[:inputs], enums: used[:enums] + used[:mapped],
+          unions: used_unions, fragments: shared,
+        ).to_a + plan
       end
 
       plan
     end
     private :generation_plan
 
-    # Default input coercion for scalars that don't say coerce: themselves,
-    # resolved lazily at generation time (so set it any time before you
-    # generate — no reset_scalars! ordering dance):
+    # coerce: true for every scalar that doesn't say coerce: itself —
+    # the same switch at global scope, resolved lazily at generation time
+    # (so set it any time before you generate, no ordering dance):
     #
     #      GraphWeaver.auto_coerce = true
     #
-    # Convertible built-ins take their conversion (Int accepts 5/"5"),
-    # and any scalar with a full cast/serialize pair (Date, your Money)
-    # accepts its raw wire form. An explicit coerce: true/false/Symbol on
-    # a registration always wins.
+    # An explicit coerce: on a registration always wins.
     attr_accessor :auto_coerce
 
     # Whether generated modules/structs emit `extend T::Sig` (so `sig`
@@ -317,9 +563,10 @@ module GraphWeaver
     # (a String or Array) names files the generated code needs — validated,
     # and actually required to confirm it resolves when type: is a real class.
     # coerce: true makes a variable of this scalar accept the value OR its
-    # raw input (e.g. "12.00"), running the latter through the cast before
-    # serializing — it raises on bad input, so some safety survives. Built-in
-    # scalars are pre-registered the same way, so this also overrides them.
+    # raw input (e.g. "12.00"), normalizing the latter before serializing —
+    # it raises on bad input, so some safety survives; GraphWeaver.auto_coerce
+    # is the same switch for every scalar at once. Built-in scalars are
+    # pre-registered the same way, so this also overrides them.
     #
     # Pass a `Type.field` coordinate instead of a scalar name to override just
     # that one field — so the same scalar can deserialize as different Ruby
@@ -342,15 +589,9 @@ module GraphWeaver
     # renames, fallback: absorbs unknown wire values on cast (inputs stay
     # strict), requires: names files the generated code should require.
     # Generation fails naming any schema value that doesn't resolve —
-    # exhaustiveness checked ahead of runtime. Global; client.register_enum
-    # scopes to one client.
-    def register_enum(graphql_name, type, map: nil, fallback: nil, requires: nil)
-      Codegen.register_enum(graphql_name, type, map:, fallback:, requires:)
-    end
-
-    # Bulk, inference-only form: register_enums("Species" => PetKind, ...)
-    def register_enums(mappings)
-      Codegen.register_enums(mappings)
+    # exhaustiveness checked ahead of runtime.
+    def register_enum(graphql_name, type, positional_map = nil, map: nil, fallback: nil, requires: nil)
+      Codegen.register_enum(graphql_name, type, positional_map, map:, fallback:, requires:)
     end
 
     # Include app-owned helper modules into every struct generated from a
@@ -368,65 +609,68 @@ module GraphWeaver
     #        def display_name = "#{name} the pet"
     #      end
     #
-    # Additive (repeated and client-scoped registrations stack). Global;
-    # client.extend_type scopes to one client.
+    # Additive — repeated registrations stack.
     def extend_type(graphql_name, *mixins, requires: nil, **kw, &block)
       Codegen.extend_type(graphql_name, *mixins, requires:, **kw, &block)
     end
 
-    # Restore the built-in scalars, dropping every custom registration —
-    # the clean slate to reach for between tests or to undo overrides.
-    # (Coercible built-ins are auto_coerce's job, not a reset flavor.)
-    def reset_scalars!
-      Codegen.reset_scalars!
-    end
-
-    # Empty the scalar registry entirely, built-ins included (see
-    # reset_scalars! to restore the defaults).
-    def clear_scalars!
-      Codegen.clear_scalars!
+    # Every registry back to its starting state: built-in scalars restored,
+    # enum mappings and type helpers dropped — the clean slate between
+    # tests. (One registry at a time is a Codegen call:
+    # GraphWeaver::Codegen.reset_enums!, .reset_scalars!, .clear_scalars!,
+    # .reset_type_helpers!)
+    def reset_registrations!
+      Codegen.reset_registrations!
     end
 
     # Parse a query into a typed query module:
     #
     #      PersonQuery = GraphWeaver.parse(schema:, query: "queries/person.graphql")
     #
-    # query is a .graphql/.gql path (module name derived from the file
-    # name) or a raw query string (name derived from the operation name,
-    # falling back to "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, scalars: nil, enums: nil, types: nil,
-      fragments: fragments_paths)
-      if query.end_with?(".graphql", ".gql")
-        name ||= "#{Inflect.camelize(File.basename(query, ".*"))}Query"
-        query = File.read(query)
+    # schema: is a graphql-ruby schema or a Client (its schema, and its
+    # transport as the module's default). query is a .graphql/.gql path (module
+    # name derived from the file name and the operation — see #module_name) or
+    # a raw query string (name derived from the operation name, falling back to
+    # "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)
+      client ||= schema if schema.is_a?(Client)
+      schema = schema_for(schema)
+      # 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.
+      query = query.to_path if query.respond_to?(:to_path)
+      path = query if query.end_with?(".graphql", ".gql")
+      if path
+        query = File.read(path)
+        name ||= module_name(path, query)
       end
-      query = Codegen.inline_fragments(query, Codegen.load_fragments(fragments))
+      query = Codegen.inline_fragments(query, Codegen.load_fragments(fragments), path)
 
-      Codegen.parse(schema:, query:, module_name: name, client:, scalars:, enums:, types:)
+      Codegen.parse(schema:, query:, module_name: name, client:, path:)
     end
 
     # One-shot dynamic execution — a throwaway client, no build step:
     #
-    #      GraphWeaver.execute(schema, "query($id: ID!) { ... }", id: "1")   # => Response
-    #      GraphWeaver.execute!(url, "query { viewer { login } }")           # => Result (or raise)
+    #      GraphWeaver.run(schema, "query($id: ID!) { ... }", id: "1")   # => Response
+    #      GraphWeaver.run!(url, "query { viewer { login } }")           # => Result (or raise)
     #
     # The first argument is a url or schema source, exactly as
-    # GraphWeaver.new; this is Client#execute on a client you don't keep.
+    # GraphWeaver.new; this is Client#run on a client you don't keep.
     # (A url source introspects the schema on every call — keep a client
     # for more than one query.) Variables are plain kwargs, as on a
-    # generated module (nothing reserved). execute returns the
-    # Response envelope, execute! the typed result, raising QueryError on
-    # top-level errors.
-    def execute(source, query, **variables)
-      client = source.is_a?(Client) ? source : Client.new(source)
-      client.execute(query, **variables)
+    # generated module (nothing reserved). run returns the Response
+    # envelope, run! the typed result, raising QueryError on top-level
+    # errors.
+    def run(source, query, **variables)
+      client = source.is_a?(Client) ? source : new(source)
+      client.run(query, **variables)
     end
 
-    # execute + data! — the typed result, or a raised QueryError. See execute.
-    def execute!(source, query, **variables)
-      execute(source, query, **variables).data!
+    # run + data! — the typed result, or a raised QueryError. See run.
+    def run!(source, query, **variables)
+      run(source, query, **variables).data!
     end
   end
 end