graph_weaver 0.0.1 → 0.2.0

data/lib/graph_weaver/codegen.rb

@@ -6,244 +6,145 @@ require "sorbet-runtime"
 
 # Generates plain, statically-typecheckable Ruby from a GraphQL query +
 # schema: nested T::Structs, from_h casting code, and a sig'd execute
-# method. Unlike StructTypes (which builds classes at parse time, visible
-# only at runtime), the output is source on disk — srb tc sees the exact
-# result type of each query.
+# method. The output is source on disk, so srb tc sees the exact result
+# type of each query.
 #
 # Supports queries and mutations; plain fields, inline fragments, named
 # fragment spreads (including interface type conditions), union- and
 # interface-typed fields (dispatch on __typename), enums (generated
-# T::Enum), and typed variables (kwargs on execute). Input objects and
-# subscriptions are still open.
-class GraphWeaver::Codegen
-  # sorbet types for scalars
-  SCALARS = {
-    "ID" => "String",
-    "String" => "String",
-    "Int" => "Integer",
-    "Float" => "Float",
-    "Boolean" => "T::Boolean",
-    "Date" => "Date",
-  }.freeze
-
-  # deserialization for scalars whose wire format differs from their Ruby
-  # type; anything absent passes through untouched
-  SCALAR_CASTS = {
-    "Date" => ->(expr) { "Date.iso8601(#{expr})" },
-  }.freeze
-
-  # the inverse, for serializing variables onto the wire
-  SCALAR_SERIALIZERS = {
-    "Date" => ->(expr) { "#{expr}.iso8601" },
-  }.freeze
-
-  class Scalar
-    def initialize(name)
-      @name = name
-    end
-
-    def bare_type
-      SCALARS.fetch(@name, "T.untyped")
-    end
-
-    def prop_type
-      "T.nilable(#{bare_type})"
-    end
-
-    def cast(expr, _depth)
-      SCALAR_CASTS.fetch(@name) { return expr }.call(expr)
-    end
-
-    def identity?
-      !SCALAR_CASTS.key?(@name)
-    end
-
-    def serialize(expr, _depth)
-      SCALAR_SERIALIZERS.fetch(@name) { return expr }.call(expr)
-    end
-
-    def serialize_identity?
-      !SCALAR_SERIALIZERS.key?(@name)
-    end
-
-    def non_null? = false
-    def nested = nil
-  end
-
-  class NonNull
-    def initialize(of)
-      @of = of
-    end
-
-    def bare_type = @of.bare_type
-    def prop_type = bare_type
-    def cast(expr, depth) = @of.cast(expr, depth)
-    def identity? = @of.identity?
-    def serialize(expr, depth) = @of.serialize(expr, depth)
-    def serialize_identity? = @of.serialize_identity?
-    def non_null? = true
-    def nested = @of.nested
-  end
-
-  class List
-    def initialize(of)
-      @of = of
-    end
-
-    def bare_type
-      "T::Array[#{@of.prop_type}]"
-    end
-
-    def prop_type
-      "T.nilable(#{bare_type})"
-    end
-
-    def cast(expr, depth)
-      var = "v#{depth}"
-      element = if @of.non_null? || @of.identity?
-        @of.identity? ? var : @of.cast(var, depth + 1)
-      else
-        "#{var}&.then { |v#{depth + 1}| #{@of.cast("v#{depth + 1}", depth + 2)} }"
-      end
-
-      "#{expr}.map { |#{var}| #{element} }"
-    end
-
-    def identity? = @of.identity?
-
-    def serialize(expr, depth)
-      var = "v#{depth}"
-      element = if @of.non_null? || @of.serialize_identity?
-        @of.serialize_identity? ? var : @of.serialize(var, depth + 1)
-      else
-        "#{var}&.then { |v#{depth + 1}| #{@of.serialize("v#{depth + 1}", depth + 2)} }"
-      end
-
-      "#{expr}.map { |#{var}| #{element} }"
-    end
-
-    def serialize_identity? = @of.serialize_identity?
-    def non_null? = false
-    def nested = @of.nested
-  end
-
-  class ObjectNode
-    Field = Struct.new(:prop, :key, :node)
-
-    attr_reader :class_name, :fields
-
-    def initialize(class_name)
-      @class_name = class_name
-      @fields = []
-    end
-
-    def bare_type = class_name
-
-    def prop_type
-      "T.nilable(#{bare_type})"
-    end
-
-    def cast(expr, _depth)
-      "#{class_name}.from_h(#{expr})"
-    end
-
-    def identity? = false
-    def non_null? = false
-    def nested = self
-  end
-
-  class EnumNode
-    attr_reader :class_name, :values
-
-    def initialize(class_name, values)
-      @class_name = class_name
-      @values = values
-    end
-
-    def bare_type = class_name
-
-    def prop_type
-      "T.nilable(#{bare_type})"
-    end
-
-    def cast(expr, _depth)
-      "#{class_name}.deserialize(#{expr})"
-    end
+# T::Enum), and typed variables (kwargs on execute). Subscriptions are
+# still open.
+#
+# Split across: codegen/scalar_type.rb (the scalar registry),
+# codegen/nodes.rb (the typed IR), codegen/emit.rb (source emission);
+# this file holds the public API and the query walk.
+require_relative "hints"
+require_relative "inflect"
+require_relative "selection"
+require_relative "codegen/enum_type"
+require_relative "codegen/scalar_type"
+require_relative "codegen/nodes"
+require_relative "codegen/emit"
 
-    def identity? = false
+class GraphWeaver::Codegen
+  include GraphWeaver::Inflect
+  include GraphWeaver::Selection
+  include Emit
+
+  attr_reader :module_name
+
+  # A client is anything responding to `execute(query, variables:)`
+  # whose result `to_h`s into {"data" => ..., "errors" => ...} — a
+  # GraphWeaver::Client, a transport, a schema class, a fake.
+  #
+  # client: (a constant, or its name as a string) becomes the generated
+  # module's baked default; when omitted, generated code falls back to
+  # the app default (GraphWeaver.client=). module_name:
+  # defaults to the operation's
+  # name; default_module_name: is parse's container-scoped fallback (file
+  # generation stays strict — a checked-in file deserves a deliberate
+  # name). scalars:/enums:/types: are client-scoped overlays consulted
+  # before the global registries (ScalarType, EnumType, and arrays of
+  # mixin modules, each keyed by GraphQL name).
+  def initialize(schema:, query:, module_name: nil, client: nil, default_module_name: nil,
+    scalars: nil, enums: nil, types: nil)
+    @schema = schema
+    @query = query.strip
+    @module_name = module_name
+    @default_module_name = default_module_name
+    @scalars = scalars || {}
+    @enums = enums || {}
+    @types = types || {}
+    @client_const = self.class.client_const(client)
 
-    def serialize(expr, _depth)
-      "#{expr}.serialize"
+    if client && @client_const.nil?
+      # a live object can't be spelled in generated source — parse can
+      # set one via the module's writer, but file generation cannot
+      raise ArgumentError, "client: must be a named constant or String (got #{client.inspect}); pass live objects to parse"
     end
-
-    def serialize_identity? = false
-    def non_null? = false
-    def nested = self
   end
 
-  class UnionNode
-    attr_reader :class_name, :members # graphql type name => ObjectNode
-
-    def initialize(class_name, members)
-      @class_name = class_name
-      @members = members
+  # The constant name a client can be referenced by in generated
+  # source — nil when it can't be (live objects, anonymous modules).
+  def self.client_const(client)
+    case client
+    when String then client
+    when Module then client.name
     end
-
-    def bare_type = "#{class_name}::Type"
-
-    def prop_type
-      "T.nilable(#{bare_type})"
-    end
-
-    def cast(expr, _depth)
-      "#{class_name}.from_h(#{expr})"
-    end
-
-    def identity? = false
-    def non_null? = false
-    def nested = self
   end
 
-  # executor_const names anything responding to
-  # `execute(query, variables:)` whose result `to_h`s into
-  # {"data" => ..., "errors" => ...} — a Schema class for in-process
-  # execution, or an HttpExecutor for a remote endpoint. The generated
-  # execute also accepts an executor: override at runtime.
-  def initialize(schema:, executor_const:, query:, module_name:)
-    @schema = schema
-    @executor_const = executor_const
-    @query = query.strip
-    @module_name = module_name
+  # one-step shorthand
+  def self.generate(schema:, query:, module_name: nil, client: nil, scalars: nil, enums: nil, types: nil)
+    new(schema:, query:, module_name:, client:, scalars:, enums:, types:).generate
   end
 
   # Development convenience: generate + eval in one step, no build
   # artifact or checked-in file. Same runtime semantics as the generated
   # file, but invisible to srb tc — use the build step for static typing.
-  def self.load(schema:, executor_const:, query:, module_name:)
-    source = new(schema:, executor_const:, query:, module_name:).generate
-    Object.class_eval(source, "(struct_codegen)", 1)
-    Object.const_get(module_name)
+  # Evaluates into an anonymous container, so no global constants leak;
+  # client: additionally accepts a live object (set via .client=).
+  def self.parse(schema:, query:, module_name: nil, client: nil, scalars: nil, enums: nil, types: nil)
+    client_const = client_const(client)
+
+    codegen = new(schema:, query:, module_name:, client: client_const, default_module_name: "Query",
+      scalars:, enums:, types:)
+    source = codegen.generate
+
+    container = Module.new
+    container.module_eval(source, "(graph_weaver)", 1)
+    mod = container.const_get(codegen.module_name)
+    GraphWeaver.log(:debug) { "parsed #{codegen.module_name} (dynamic module, #{source.bytesize} bytes)" }
+    # live objects (or anonymous modules) can't be referenced from
+    # generated source — set them via the module's writer instead
+    mod.client = client if client && client_const.nil?
+    mod
   end
 
   VarDef = Struct.new(:kwarg, :wire, :node, :required)
 
+  # Names that cannot appear bare in generated Ruby: keywords aren't
+  # valid identifiers, and the struct's own generated methods would be
+  # silently replaced by a same-named prop reader.
+  RUBY_KEYWORDS = %w[
+    alias and begin break case class def defined? do else elsif end
+    ensure false for if in module next nil not or redo rescue retry
+    return self super then true undef unless until when while yield
+    BEGIN END __FILE__ __LINE__ __ENCODING__
+  ].to_set.freeze
+  GENERATED_METHODS = %w[serialize to_h].to_set.freeze
+
   def generate
-    errors = @schema.validate(@query)
+    begin
+      errors = @schema.validate(@query)
+    rescue GraphQL::ParseError => e
+      # unparseable queries wrap like invalid ones — everything raised
+      # here descends from GraphWeaver::Error
+      raise GraphWeaver::ValidationError.new([{ message: e.message, line: nil, column: nil }])
+    end
     if errors.any?
-      raise ArgumentError, "invalid query: #{errors.map(&:message).join("; ")}"
+      raise GraphWeaver::ValidationError.new(errors.map { |e| validation_detail(e) })
     end
 
-    doc = GraphQL.parse(@query)
-    @fragments = doc.definitions
-      .grep(GraphQL::Language::Nodes::FragmentDefinition)
-      .to_h { |fragment| [fragment.name, fragment] }
+    validate_registrations!
+
     @variable_enums = {}
+    @variable_inputs = {}
+    @mapped_enums = {}
+    # requires the generated file needs (custom scalars, enum mappings,
+    # type helpers all contribute)
+    @requires = []
 
-    operation = doc.definitions.grep(GraphQL::Language::Nodes::OperationDefinition).first
-    root_type = case operation&.operation_type
-    when "query", nil then @schema.query
-    when "mutation" then @schema.mutation
-    else raise NotImplementedError, "unsupported operation: #{operation.operation_type}"
+    operation = load_operation(@query)
+    root_type = operation_root_type(operation)
+
+    @module_name ||= operation.name || @default_module_name
+    unless @module_name
+      raise ArgumentError, "module_name: required for anonymous operations"
+    end
+
+    # generated source is eval'd by parse — never let a name inject code
+    unless @module_name.match?(/\A[A-Z]\w*(::[A-Z]\w*)*\z/)
+      raise ArgumentError, "module_name: must be a constant name, got #{@module_name.inspect}"
     end
 
     variables = operation.variables.map do |var|
@@ -251,7 +152,14 @@ class GraphWeaver::Codegen
       # a variable is optional when nullable or defaulted; optional kwargs
       # default to nil and are omitted from the wire
       required = node.non_null? && var.default_value.nil?
-      VarDef.new(underscore(var.name), var.name, node, required)
+      kwarg = underscore(var.name)
+      # kwargs are declared and forwarded bare in generated source
+      if RUBY_KEYWORDS.include?(kwarg)
+        raise GraphWeaver::Error,
+          "variable $#{var.name} would become the kwarg '#{kwarg}:', which generated code can't declare " \
+          "(a Ruby keyword) — rename the variable"
+      end
+      VarDef.new(kwarg, var.name, node, required)
     end
 
     root = object_node(root_type, operation.selections, "Result")
@@ -262,20 +170,52 @@ class GraphWeaver::Codegen
     out << ""
     out << "# Generated by GraphWeaver — do not edit."
     out << ""
+    requires = @requires.uniq.sort
+    if requires.any?
+      requires.each { |req| out << "require #{req.inspect}" }
+      out << ""
+    end
     out << "module #{@module_name}"
     out << "  extend T::Sig"
     out << ""
-    out << "  QUERY = T.let(<<~'GRAPHQL', String)"
+    # a GraphQL block string could contain a bare GRAPHQL line, which
+    # would terminate the heredoc early — pick a delimiter the query
+    # can't collide with
+    delimiter = "GRAPHQL"
+    delimiter += "_" while @query.match?(/^\s*#{delimiter}\s*$/)
+    out << "  QUERY = T.let(<<~'#{delimiter}', String)"
     @query.each_line { |line| out << "    #{line}".rstrip }
-    out << "  GRAPHQL"
+    out << "  #{delimiter}"
     out << ""
+    @mapped_enums.each_value do |mapped|
+      emit_mapped_enum(mapped, out, 1)
+      out << ""
+    end
     @variable_enums.each_value do |enum|
       emit_enum(enum, out, 1)
       out << ""
     end
+    inputs, cyclic = ordered_inputs
+    if cyclic
+      # Recursive input types (Hasura bool_exp et al) reference each other,
+      # so no definition order satisfies the runtime — forward-declare every
+      # class empty, then let the full definitions below reopen with props.
+      # eval'd so srb sees only the full bodies (reopening a T::Struct to
+      # add props is a static error; adding them at runtime is fine).
+      out << "  # runtime-only forward declarations: these input types reference"
+      out << "  # each other, so the full definitions below need the constants"
+      out << "  eval(<<~RUBY, binding, __FILE__, __LINE__ + 1)"
+      inputs.each { |input| out << "    class #{input.class_name} < T::Struct; end" }
+      out << "  RUBY"
+      out << ""
+    end
+    inputs.each do |input|
+      emit_input(input, out, 1)
+      out << ""
+    end
     emit_nested(root, out, 1)
     out << ""
-    emit_execute(out, variables)
+    emit_execute(out, variables, flatten: flatten_input(variables))
     out << "end"
 
     out.join("\n") + "\n"
@@ -283,55 +223,61 @@ class GraphWeaver::Codegen
 
   private
 
-  # GraphQL names are plain camelCase/SCREAMING_SNAKE — no acronym edge
-  # cases, so minimal inflection beats an activesupport dependency
-  def underscore(name)
-    name.gsub(/([a-z\d])([A-Z])/, '\1_\2').downcase
+  # A client-scoped registration names a type in a specific schema — a
+  # typo'd name would otherwise be a silent no-op, the most confusing
+  # failure mode available. Called eagerly by Client#register_* when the
+  # schema is already loaded, and again at generation (covers clients
+  # whose schema introspects lazily). Global registrations skip this:
+  # they may target a different client's server.
+  def self.validate_registration!(schema, kind, name)
+    return if schema.get_type(name)
+
+    suggestion = defined?(DidYouMean::SpellChecker) &&
+      DidYouMean::SpellChecker.new(dictionary: schema.types.keys).correct(name).first
+    hint = suggestion ? " — did you mean '#{suggestion}'?" : ""
+    raise GraphWeaver::Error, "register_#{kind}(#{name.inspect}) matches no type in this schema#{hint}"
   end
 
-  def camelize(name)
-    name.split("_").map { |part| "#{part[0].upcase}#{part[1..]}" }.join
+  # Structured shape for a schema-validation error: message plus its first
+  # source location, so ValidationError#errors is inspectable.
+  def validation_detail(error)
+    loc = (error.to_h["locations"]&.first if error.respond_to?(:to_h))
+    { message: error.message, line: loc && loc["line"], column: loc && loc["column"] }
   end
 
-  # Flatten a selection set as seen by `type`: plain fields collect
-  # directly; inline fragments and named spreads recurse when their type
-  # condition matches (exact name match — interface conditions are out of
-  # scope for this spike).
-  def gather(type, selections, out = {})
-    selections.each do |selection|
-      case selection
-      when GraphQL::Language::Nodes::Field
-        (out[selection.alias || selection.name] ||= []) << selection
-      when GraphQL::Language::Nodes::InlineFragment
-        gather(type, selection.selections, out) if applies?(selection.type&.name, type)
-      when GraphQL::Language::Nodes::FragmentSpread
-        fragment = @fragments.fetch(selection.name) do
-          raise ArgumentError, "unknown fragment: #{selection.name}"
-        end
-        gather(type, fragment.selections, out) if applies?(fragment.type.name, type)
-      else
-        raise NotImplementedError, "unsupported selection: #{selection.class}"
-      end
+  def validate_registrations!
+    { "enum" => @enums, "scalar" => @scalars, "type" => @types }.each do |kind, registry|
+      registry.each_key { |name| self.class.validate_registration!(@schema, kind, name) }
     end
-
-    out
   end
 
-  # A fragment's type condition applies when it names this type exactly,
-  # or an interface/union this type belongs to (`... on Named { ... }`).
-  def applies?(condition, type)
-    return true if condition.nil? || condition == type.graphql_name
+  # The Relay convention — an operation whose only variable is a required
+  # input object — reads better flattened: the input's fields become
+  # execute's kwargs directly, and the wrapping level is rebuilt on the
+  # wire. Multi-variable (or nullable-input) operations keep the
+  # variable-per-kwarg surface.
+  def flatten_input(variables)
+    return unless variables.size == 1
 
-    condition_type = @schema.get_type(condition)
-    return false unless condition_type
+    var = variables.first
+    return unless var.required && var.node.is_a?(NonNull)
 
-    kind = condition_type.kind.name
-    (kind == "INTERFACE" || kind == "UNION") &&
-      @schema.possible_types(condition_type).include?(type)
+    input = var.node.of
+    input if input.is_a?(InputNode)
+  end
+
+  # Selection#each_field, collected by result key (codegen groups
+  # repeated selections of one field so it can merge them)
+  def gather(type, selections)
+    out = {}
+    each_field(type, selections) { |key, node| (out[key] ||= []) << node }
+    out
   end
 
   def object_node(type, selections, class_name)
     node = ObjectNode.new(class_name)
+    node.graphql_type = type.graphql_name
+    node.mixins = type_mixins(type.graphql_name)
     taken = [class_name]
 
     gather(type, selections).each do |key, field_nodes|
@@ -339,7 +285,7 @@ class GraphWeaver::Codegen
       prop = underscore(key)
 
       child = if field_name == "__typename"
-        NonNull.new(Scalar.new("String"))
+        NonNull.new(scalar_node("String"))
       else
         field_type = @schema.get_field(type.graphql_name, field_name).type
         sub_selections = field_nodes.flat_map(&:selections)
@@ -349,38 +295,116 @@ class GraphWeaver::Codegen
           name = pick_name(core.graphql_name, key, taken)
           type_ref(field_type) { object_node(core, sub_selections, name) }
         when "UNION", "INTERFACE"
-          name = pick_name(core.graphql_name, key, taken)
-          type_ref(field_type) { union_node(core, sub_selections, name) }
+          conditions = concrete_conditions(core, sub_selections)
+          bare = bare_fields(sub_selections) - ["__typename"]
+
+          if conditions.empty? && core.kind.name == "INTERFACE"
+            # interface-level fields only — every member shares them, so
+            # one struct suffices and no __typename dispatch is needed
+            name = pick_name(core.graphql_name, key, taken)
+            type_ref(field_type) { object_node(core, sub_selections, name) }
+          elsif conditions.size == 1 && bare.empty? &&
+              (member = @schema.get_type(conditions.first)).kind.name == "OBJECT"
+            # a single `... on X` condition: narrow to X's struct — nil
+            # when the runtime type doesn't match (narrowing filters).
+            # Narrowing reads "no fields came back" as "type didn't
+            # match", so a fragment whose every field hides behind
+            # @skip/@include would make a real match indistinguishable
+            # from a miss ({} either way) — refuse rather than guess.
+            unless unconditional_field?(member, sub_selections)
+              raise GraphWeaver::Error,
+                "narrowed `... on #{member.graphql_name}` needs at least one field not under " \
+                "@skip/@include — an all-conditional selection makes a match indistinguishable from nil"
+            end
+
+            name = pick_name(member.graphql_name, key, taken)
+            nilable_type_ref(field_type) { NarrowedNode.new(object_node(member, sub_selections, name)) }
+          else
+            name = pick_name(core.graphql_name, key, taken)
+            type_ref(field_type) { union_node(core, sub_selections, name) }
+          end
         when "ENUM"
-          name = pick_name(core.graphql_name, key, taken)
-          # sorted so output is deterministic across schema sources
-          # (SDL round-trips reorder values alphabetically)
-          type_ref(field_type) { EnumNode.new(name, core.values.keys.sort) }
+          if (mapped = mapped_enum_node(core))
+            type_ref(field_type) { mapped }
+          else
+            name = pick_name(core.graphql_name, key, taken)
+            # sorted so output is deterministic across schema sources
+            # (SDL round-trips reorder values alphabetically)
+            type_ref(field_type) { EnumNode.new(name, core.values.keys.sort) }
+          end
         when "SCALAR"
-          type_ref(field_type) { Scalar.new(core.graphql_name) }
+          type_ref(field_type) { scalar_node(core.graphql_name) }
         else
-          raise NotImplementedError, "unsupported kind: #{core.kind.name}"
+          raise GraphWeaver::Error, "unsupported kind: #{core.kind.name}"
         end
       end
 
+      # a field under @skip/@include may be absent from the response no
+      # matter what the schema says — its type must admit nil
+      if field_nodes.any? { |n| n.directives.any? { |d| %w[skip include].include?(d.name) } }
+        child = child.of if child.is_a?(NonNull)
+      end
+
       node.fields << ObjectNode::Field.new(prop, key, child)
     end
 
     node
   end
 
-  # Abstract types (unions AND interfaces): one member struct per
-  # possible type; wire dispatch reads __typename, so the query must
-  # select it. For interfaces, the interface's own field selections
-  # gather into every member.
+  # The concrete type conditions a selection mentions (inline fragments
+  # and named spreads), minus conditions naming the abstract type itself.
+  def concrete_conditions(core, selections)
+    selections.filter_map do |selection|
+      case selection
+      when GraphQL::Language::Nodes::InlineFragment
+        selection.type&.name
+      when GraphQL::Language::Nodes::FragmentSpread
+        @fragments.fetch(selection.name).type.name
+      end
+    end.uniq - [core.graphql_name]
+  end
+
+  # result keys selected as plain fields (outside any type condition)
+  def bare_fields(selections)
+    selections.grep(GraphQL::Language::Nodes::Field).map { |field| field.alias || field.name }
+  end
+
+  # does the flattened selection (as seen by member) include at least one
+  # field guaranteed to be present in a matching response?
+  def unconditional_field?(member, selections)
+    each_field(member, selections) do |_key, node|
+      return true if node.directives.none? { |d| %w[skip include].include?(d.name) }
+    end
+    false
+  end
+
+  # rebuild LIST wrappers but drop NON_NULLs — a narrowed member is nil
+  # whenever the runtime type doesn't match, whatever the schema promises
+  def nilable_type_ref(type, &core)
+    case type.kind.name
+    when "NON_NULL"
+      nilable_type_ref(type.of_type, &core)
+    when "LIST"
+      List.new(nilable_type_ref(type.of_type, &core))
+    else
+      core.call
+    end
+  end
+
+  # Abstract types (unions AND interfaces) whose selections vary by
+  # concrete type: one member struct per possible type; wire dispatch
+  # reads __typename, so the query must select it. For interfaces, the
+  # interface's own field selections gather into every member.
   def union_node(type, selections, class_name)
     unless gather(type, selections).key?("__typename")
-      raise ArgumentError, "select __typename on #{type.graphql_name} so #{class_name} can dispatch"
+      raise ArgumentError,
+        "select __typename on #{type.graphql_name} so #{class_name} can dispatch — " \
+        "or narrow to a single `... on Type` condition (no dispatch needed)"
     end
 
     # sorted so output is deterministic across schema sources
     members = @schema.possible_types(type).sort_by(&:graphql_name).to_h do |possible|
-      [possible.graphql_name, object_node(possible, selections, possible.graphql_name)]
+      [possible.graphql_name, object_node(possible, selections, camelize(possible.graphql_name))]
     end
 
     UnionNode.new(class_name, members)
@@ -395,173 +419,144 @@ class GraphWeaver::Codegen
     when GraphQL::Language::Nodes::ListType
       List.new(ast_type_ref(ast_type.of_type))
     when GraphQL::Language::Nodes::TypeName
-      core = @schema.get_type(ast_type.name)
-      case core.kind.name
-      when "SCALAR"
-        Scalar.new(core.graphql_name)
-      when "ENUM"
-        @variable_enums[core.graphql_name] ||=
-          EnumNode.new(core.graphql_name, core.values.keys.sort)
-      else
-        raise NotImplementedError, "unsupported variable kind: #{core.kind.name}"
-      end
+      variable_core(@schema.get_type(ast_type.name))
     else
-      raise NotImplementedError, "unsupported type node: #{ast_type.class}"
+      raise GraphWeaver::Error, "unsupported type node: #{ast_type.class}"
     end
   end
 
-  # rebuild the NON_NULL/LIST wrappers around the core node
-  def type_ref(type, &core)
-    case type.kind.name
-    when "NON_NULL"
-      NonNull.new(type_ref(type.of_type, &core))
-    when "LIST"
-      List.new(type_ref(type.of_type, &core))
+  # the input-side core kinds a variable (or input-object field) can have
+  def variable_core(core)
+    case core.kind.name
+    when "SCALAR"
+      scalar_node(core.graphql_name)
+    when "ENUM"
+      mapped_enum_node(core) || (@variable_enums[core.graphql_name] ||=
+        EnumNode.new(camelize(core.graphql_name), core.values.keys.sort))
+    when "INPUT_OBJECT"
+      input_node(core)
     else
-      core.call
+      raise GraphWeaver::Error, "unsupported variable kind: #{core.kind.name}"
     end
   end
 
-  def unwrap(type)
-    type = type.of_type while type.kind.name == "NON_NULL" || type.kind.name == "LIST"
-    type
-  end
-
-  def pick_name(type_name, key, taken)
-    candidate = type_name
-    candidate = "#{camelize(key)}#{type_name}" if taken.include?(candidate)
-    raise NotImplementedError, "class name collision: #{candidate}" if taken.include?(candidate)
+  # A module-level T::Struct per input type, with a serialize method
+  # producing the wire hash. Registered once per type — and registered
+  # BEFORE its fields walk, so recursive references (Hasura's bool_exp
+  # _and/_or/_not) resolve to the same node instead of looping.
+  def input_node(core)
+    return @variable_inputs[core.graphql_name] if @variable_inputs.key?(core.graphql_name)
 
-    taken << candidate
-    candidate
-  end
+    node = @variable_inputs[core.graphql_name] = InputNode.new(camelize(core.graphql_name))
+    # sorted so output is deterministic across schema sources
+    core.arguments.values.sort_by(&:graphql_name).each do |argument|
+      prop = underscore(argument.graphql_name)
+      # prop readers are bare method calls in the generated struct
+      if RUBY_KEYWORDS.include?(prop) || GENERATED_METHODS.include?(prop)
+        raise GraphWeaver::Error,
+          "input field #{core.graphql_name}.#{argument.graphql_name} would become prop '#{prop}', " \
+          "which collides with #{RUBY_KEYWORDS.include?(prop) ? "a Ruby keyword" : "the struct's generated ##{prop}"}"
+      end
 
-  def emit_nested(node, out, indent)
-    case node
-    when UnionNode then emit_union(node, out, indent)
-    when EnumNode then emit_enum(node, out, indent)
-    else emit_object(node, out, indent)
+      child = type_ref(argument.type) { variable_core(unwrap(argument.type)) }
+      required = child.non_null? && !argument.default_value?
+      node.fields << InputNode::Field.new(prop, argument.graphql_name, child, required)
     end
+    node
   end
 
-  def emit_enum(node, out, indent)
-    pad = "  " * indent
-
-    out << "#{pad}class #{node.class_name} < T::Enum"
-    out << "#{pad}  enums do"
-    node.values.each do |value|
-      out << "#{pad}    #{camelize(value.downcase)} = new(#{value.inspect})"
+  # The InputNodes a struct's fields reference, through NON_NULL/LIST
+  # wrappers — the edges of the input dependency graph.
+  def input_references(node)
+    node.fields.filter_map do |field|
+      child = field.node
+      child = child.of while child.respond_to?(:of)
+      child if child.is_a?(InputNode)
     end
-    out << "#{pad}  end"
-    out << "#{pad}end"
   end
 
-  def emit_object(node, out, indent)
-    pad = "  " * indent
-
-    out << "#{pad}class #{node.class_name} < T::Struct"
-    out << "#{pad}  extend T::Sig"
-    out << ""
-
-    node.fields.filter_map { |field| field.node.nested }.each do |child|
-      emit_nested(child, out, indent + 1)
-      out << ""
-    end
+  # Input structs in dependency order (referenced types before their
+  # referrers) so each emitted const names an already-defined class.
+  # Cycles make that impossible — flagged so emission can forward-declare
+  # every input class first, then reopen each to add its props.
+  def ordered_inputs
+    ordered = []
+    seen = {} # node => :done | :visiting (bool_exp graphs get big)
+    cyclic = T.let(false, T::Boolean)
+
+    visit = lambda do |node|
+      next if seen[node] == :done
+
+      if seen[node] == :visiting
+        cyclic = true
+        next
+      end
 
-    node.fields.each do |field|
-      out << "#{pad}  const :#{field.prop}, #{field.node.prop_type}"
+      seen[node] = :visiting
+      input_references(node).each(&visit)
+      seen[node] = :done
+      ordered << node
     end
+    @variable_inputs.each_value(&visit)
 
-    out << ""
-    out << "#{pad}  sig { params(data: T::Hash[String, T.untyped]).returns(#{node.class_name}) }"
-    out << "#{pad}  def self.from_h(data)"
-    out << "#{pad}    new("
-    node.fields.each do |field|
-      out << "#{pad}      #{field.prop}: #{field_cast(field)},"
-    end
-    out << "#{pad}    )"
-    out << "#{pad}  end"
-    out << "#{pad}end"
+    [ordered, cyclic]
   end
 
-  def emit_union(node, out, indent)
-    pad = "  " * indent
-
-    out << "#{pad}module #{node.class_name}"
-    out << "#{pad}  extend T::Sig"
-    out << ""
-
-    node.members.each_value do |member|
-      emit_object(member, out, indent + 1)
-      out << ""
-    end
-
-    member_names = node.members.values.map(&:class_name)
-    type_alias = member_names.size == 1 ? member_names.first : "T.any(#{member_names.join(", ")})"
-    out << "#{pad}  Type = T.type_alias { #{type_alias} }"
-    out << ""
-    out << "#{pad}  sig { params(data: T::Hash[String, T.untyped]).returns(Type) }"
-    out << "#{pad}  def self.from_h(data)"
-    out << "#{pad}    case (typename = data.fetch(\"__typename\"))"
-    node.members.each do |graphql_name, member|
-      out << "#{pad}    when #{graphql_name.inspect} then #{member.class_name}.from_h(data)"
-    end
-    out << "#{pad}    else raise \"unexpected __typename: \#{typename}\""
-    out << "#{pad}    end"
-    out << "#{pad}  end"
-    out << "#{pad}end"
+  # Registered helper-module names for a GraphQL type (additive: global
+  # registrations plus this client's), collecting their requires.
+  def type_mixins(graphql_name)
+    entries = [GraphWeaver::Codegen.type_registry[graphql_name], @types[graphql_name]].compact
+    entries.each { |entry| @requires.concat(entry[:requires]) }
+    entries.flat_map { |entry| entry[:mixins].map(&:name) }
   end
 
-  def emit_execute(out, variables)
-    sig_params = variables.map do |var|
-      kwarg_type = var.required ? var.node.prop_type : "T.nilable(#{var.node.bare_type})"
-      "#{var.kwarg}: #{kwarg_type}"
-    end
-    sig_params << "executor: T.untyped"
+  # The MappedEnum node for a schema enum with a registered app-enum
+  # mapping (client overlay first, then the global registry); nil when
+  # unregistered, falling back to a generated T::Enum.
+  def mapped_enum_node(core)
+    enum_type = @enums[core.graphql_name] || GraphWeaver::Codegen.enum_registry[core.graphql_name]
+    return unless enum_type
 
-    kwargs = variables.map { |var| var.required ? "#{var.kwarg}:" : "#{var.kwarg}: nil" }
-    kwargs << "executor: #{@executor_const}"
+    @requires.concat(enum_type.requires)
+    @mapped_enums[core.graphql_name] ||= MappedEnum.new(enum_type, core.values.keys.sort)
+  end
 
-    out << "  sig { params(#{sig_params.join(", ")}).returns(Result) }"
-    out << "  def self.execute(#{kwargs.join(", ")})"
+  # A Scalar node, recording any requires its registered type needs so the
+  # generated file can require them (collected across the whole query).
+  # Resolution: the client-scoped overlay first, then the global registry.
+  def scalar_node(name)
+    scalar = @scalars[name.to_s] || GraphWeaver::Codegen.scalar(name)
+    @requires.concat(scalar.requires)
+    Scalar.new(scalar)
+  end
 
-    required, optional = variables.partition(&:required)
-    if required.empty?
-      out << "    variables = {}"
+  # rebuild the NON_NULL/LIST wrappers around the core node
+  def type_ref(type, &core)
+    case type.kind.name
+    when "NON_NULL"
+      NonNull.new(type_ref(type.of_type, &core))
+    when "LIST"
+      List.new(type_ref(type.of_type, &core))
     else
-      out << "    variables = {"
-      required.each do |var|
-        out << "      #{var.wire.inspect} => #{variable_serialize(var)},"
-      end
-      out << "    }"
-    end
-    optional.each do |var|
-      out << "    variables[#{var.wire.inspect}] = #{variable_serialize(var)} unless #{var.kwarg}.nil?"
+      core.call
     end
-
-    out << ""
-    out << "    result = executor.execute(QUERY, variables: variables).to_h"
-    out << "    if (errors = result[\"errors\"])"
-    out << "      raise \"query failed: \#{errors.inspect}\""
-    out << "    end"
-    out << ""
-    out << "    Result.from_h(result.fetch(\"data\"))"
-    out << "  end"
   end
 
-  def variable_serialize(var)
-    var.node.serialize_identity? ? var.kwarg : var.node.serialize(var.kwarg, 1)
+  def unwrap(type)
+    type = type.of_type while type.kind.name == "NON_NULL" || type.kind.name == "LIST"
+    type
   end
 
-  def field_cast(field)
-    node = field.node
+  # GraphQL type names become struct names — camelized, because schemas
+  # in the wild use snake_case type names (Hasura, PostGraphile) and a
+  # verbatim lowercase name is not a Ruby constant
+  def pick_name(type_name, key, taken)
+    candidate = camelize(type_name)
+    candidate = "#{camelize(key)}#{candidate}" if taken.include?(candidate)
+    raise GraphWeaver::Error, "class name collision: #{candidate}" if taken.include?(candidate)
 
-    if node.non_null?
-      raw = "data.fetch(#{field.key.inspect})"
-      node.identity? ? raw : node.cast(raw, 1)
-    else
-      raw = "data[#{field.key.inspect}]"
-      node.identity? ? raw : "#{raw}&.then { |v1| #{node.cast("v1", 2)} }"
-    end
+    taken << candidate
+    candidate
   end
+
 end