graph_weaver 0.4.4 → 0.5.0

data/lib/graph_weaver/codegen.rb

@@ -16,22 +16,31 @@ require "sorbet-runtime"
 # 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.
+# codegen/nodes.rb (the typed IR), codegen/aliases.rb (registered alias
+# paths), codegen/emit.rb (source emission); this file holds the public
+# API and the query walk.
 require_relative "hints"
 require_relative "input_struct"
+require_relative "representation"
 require_relative "inflect"
 require_relative "selection"
 require_relative "codegen/enum_type"
 require_relative "codegen/scalar_type"
 require_relative "codegen/nodes"
+require_relative "codegen/aliases"
 require_relative "codegen/emit"
 
 class GraphWeaver::Codegen
   include GraphWeaver::Inflect
   include GraphWeaver::Selection
+  include Aliases
   include Emit
 
+  # How a directory of GraphQL documents is scanned: both extensions the rest of
+  # the library already accepts, and nested — `queries/admin/pets.graphql` is
+  # how anyone with sixty queries organizes them.
+  DOCUMENT_GLOB = "**/*.{graphql,gql}"
+
   attr_reader :module_name
 
   # A client is anything responding to `execute(query, variables:)`
@@ -44,31 +53,26 @@ class GraphWeaver::Codegen
   # 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). inputs_namespace: is the
-  # shared-inputs workflow (see GraphWeaver.generate!): variable types
-  # live once in that module and the query module aliases what it uses.
-  # unions_namespace:/hoistable_unions: are the parallel shared-unions
-  # workflow — a whole-union field spread as a named shared fragment resolves
-  # to one canonical type in that module (see used_union_names).
+  # name). types_namespace: is the shared-types workflow (see
+  # GraphWeaver.generate!): input types, schema enums, and unions hoisted from
+  # shared fragments live once in that module and the query module aliases what
+  # it uses. hoistable_unions: is the set of shared fragment names this query
+  # may hoist (spreads it inlined, minus any it shadows locally) — a
+  # whole-union field spread as one of them resolves to a canonical type in the
+  # shared module (see used_union_names). path: is the file the query was read
+  # from, named alongside line and column in validation errors.
   def initialize(schema:, query:, module_name: nil, client: nil, default_module_name: nil,
-    scalars: nil, enums: nil, types: nil, inputs_namespace: nil, unions_namespace: nil,
-    hoistable_unions: nil)
+    types_namespace: nil, hoistable_unions: nil, path: nil)
     @schema = schema
     @query = query.strip
+    @path = path
     @module_name = module_name
     @default_module_name = default_module_name
-    @scalars = scalars || {}
-    @enums = enums || {}
-    @types = types || {}
-    @inputs_namespace = inputs_namespace
-    # the shared-unions workflow: unions_namespace names the module hoisted
-    # unions live in; hoistable_unions is the set of shared fragment names this
-    # query may hoist (spreads it inlined, minus any it shadows locally)
-    @unions_namespace = unions_namespace
+    @types_namespace = types_namespace
     @hoistable_unions = hoistable_unions || []
     @used_unions = []
+    # scalars this generation had no registration for (see report_untyped_scalars)
+    @untyped_scalars = []
     @client_const = self.class.client_const(client)
 
     if client && @client_const.nil?
@@ -88,8 +92,8 @@ class GraphWeaver::Codegen
   end
 
   # 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
+  def self.generate(schema:, query:, module_name: nil, client: nil, path: nil)
+    new(schema:, query:, module_name:, client:, path:).generate
   end
 
   # Development convenience: generate + eval in one step, no build
@@ -97,11 +101,11 @@ class GraphWeaver::Codegen
   # file, but invisible to srb tc — use the build step for static typing.
   # 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)
+  def self.parse(schema:, query:, module_name: nil, client: nil, path: nil)
     client_const = client_const(client)
 
-    codegen = new(schema:, query:, module_name:, client: client_const, default_module_name: "Query",
-      scalars:, enums:, types:)
+    codegen = new(schema:, query:, module_name:, client: client_const, path:,
+      default_module_name: "Query")
     source = codegen.generate
 
     container = Module.new
@@ -114,80 +118,141 @@ class GraphWeaver::Codegen
     mod
   end
 
-  # The schema-level variable types this query touched, by GraphQL
-  # name — the generate! workflow unions these across queries to decide
-  # what the shared inputs module must contain.
+  # Every registry back to its starting state — scalars (built-ins restored),
+  # enum mappings, and type helpers. The clean slate between tests, and the
+  # one call that stays right when a fourth kind of registration shows up.
+  def self.reset_registrations!
+    reset_scalars!
+    reset_enums!
+    reset_type_helpers!
+    self
+  end
+
+  # The schema-level types this walk touched, by GraphQL name — the generate!
+  # workflow unions these across queries to decide what the shared types module
+  # must contain.
   def variable_type_names
-    { inputs: @variable_inputs.keys, enums: @variable_enums.keys, mapped: @mapped_enums.keys }
+    { inputs: @variable_inputs.keys, enums: @enums.keys, mapped: @mapped_enums.keys }
   end
 
   # The shared union fragments this query hoisted, by name — the generate!
-  # workflow unions these across queries to decide what the shared unions
-  # module must contain.
+  # workflow unions these across queries to decide what the shared types module
+  # must contain.
   def used_union_names = @used_unions.dup
 
-  # The shared inputs artifact: the named input/enum types — plus
-  # everything they transitively reference — emitted once per schema as
-  # a manifest (inputs.rb) plus one file per type under inputs/, so a
-  # schema migration diffs only the types it touched. Returns
-  # { relative_filename => source }.
-  def self.generate_inputs(schema:, module_name:, input_types: [], enum_types: [],
-    scalars: nil, enums: nil, types: nil)
-    codegen = new(schema:, query: "", module_name:, scalars:, enums:, types:)
-    codegen.generate_inputs(input_types, enum_types)
+  # The shared types artifact: every type a schema shares across query modules,
+  # emitted once as a manifest (types.rb) plus one file per type under types/,
+  # so a schema migration diffs only the types it touched. Returns
+  # { relative_filename => source }. Three kinds live here:
+  #
+  # - inputs: the named input types, plus everything they transitively
+  #   reference (nested types stay unaliased — the query module names only the
+  #   variable roots);
+  # - enums: one Ruby type per schema enum a query touched — a generated
+  #   T::Enum, or the wire tables for one mapped onto an app enum
+  #   (register_enum) — so a value read out of one query's result hands
+  #   straight back into another's variable;
+  # - unions: each named shared fragment a query spread as a whole union field,
+  #   so the same union across queries is one Ruby type family. `fragments` is
+  #   the loaded shared-fragment table (nested spreads resolve through it).
+  #
+  # Unions are built first: a hoisted fragment's own selections are the one
+  # place a query walk never reaches, so the enums they touch are only known
+  # once the fragments are built.
+  def generate_types(inputs:, enums:, unions:, fragments:)
+    validate_module_name!("types module name")
+    reset_walk_state!
+    # nested spreads inside a shared fragment resolve through the whole table
+    @fragments = fragments
+
+    union_nodes = unions.uniq.sort.map { |name| hoisted_union(fragments, name) }
+    inputs.sort.each { |name| input_node(@schema.get_type(name)) }
+    enums.uniq.sort.each { |name| variable_core(@schema.get_type(name)) }
+    check_shared_collisions!(unions)
+
+    emit_types_files(union_nodes).tap { report_untyped_scalars }
   end
 
-  def generate_inputs(input_types, enum_types)
-    unless @module_name&.match?(/\A[A-Z]\w*(::[A-Z]\w*)*\z/)
-      raise ArgumentError, "inputs module name must be a constant name, got #{@module_name.inspect}"
+  # module-level constants every generated query module defines — a shared
+  # type aliased to one of these would clash at load
+  MODULE_RESERVED = %w[Result QUERY Representations].to_set.freeze
+
+  # One hoisted shared fragment, built against the schema and named for the
+  # fragment rather than the field that spread it.
+  def hoisted_union(fragments, name)
+    class_name = camelize(name)
+    # the query module aliases <class_name> = <shared module>::<class_name>; a
+    # name that camelizes to a generated module-level constant (the Result
+    # struct, the QUERY heredoc) would collide with that alias at load
+    if MODULE_RESERVED.include?(class_name)
+      raise GraphWeaver::Error,
+        "shared fragment #{name.inspect} hoists to #{class_name}, which collides with a generated constant — rename the fragment"
     end
 
-    @variable_enums = {}
-    @variable_inputs = {}
-    @mapped_enums = {}
-    @requires = []
-
-    enum_types.sort.each { |name| variable_core(@schema.get_type(name)) }
-    input_types.sort.each { |name| input_node(@schema.get_type(name)) }
+    fragment = fragments.fetch(name)
+    type = @schema.get_type(fragment.type.name)
+    members = union_members(type, fragment.selections)
+    UnionNode.new(class_name, members, catch_all_member(type, fragment.selections, members))
+  end
+  private :hoisted_union
+
+  # Schema type names are unique, so an input and an enum can never land on the
+  # same name — but a hoisted union is named for its FRAGMENT, which the schema
+  # knows nothing about. One shared module means one namespace, so a fragment
+  # named after a type it doesn't describe has to refuse rather than overwrite.
+  def check_shared_collisions!(names)
+    taken = {}
+    @enums.each { |graphql_name, node| taken[node.class_name] = "the schema enum #{graphql_name}" }
+    @mapped_enums.each_key { |graphql_name| taken[camelize(graphql_name)] = "the schema enum #{graphql_name}" }
+    @variable_inputs.each { |graphql_name, node| taken[node.class_name] = "the input type #{graphql_name}" }
+
+    names.each do |name|
+      class_name = camelize(name)
+      claim = taken[class_name] or next
 
-    emit_inputs_files
+      raise GraphWeaver::Error,
+        "shared fragment #{name.inspect} hoists to #{@module_name}::#{class_name}, " \
+        "where #{claim} already generates — rename the fragment"
+    end
   end
+  private :check_shared_collisions!
 
-  # The shared unions artifact: each named shared fragment a query hoisted,
-  # built once against the schema as <module_name>::<Name>, so the same union
-  # across queries resolves to one Ruby type family. `fragments` is the loaded
-  # shared-fragment table (nested spreads resolve through it); `names` the
-  # fragments to build. Returns { "unions.rb" => source }.
-  def self.generate_unions(schema:, module_name:, fragments:, names:,
-    scalars: nil, enums: nil, types: nil)
-    codegen = new(schema:, query: "", module_name:, scalars:, enums:, types:)
-    codegen.generate_unions(fragments, names)
+  # per-run walk state, cleared so one Codegen can generate more than once
+  def reset_walk_state!
+    @enums = {}
+    @variable_inputs = {}
+    @mapped_enums = {}
+    @used_unions = []
+    # requires the generated file needs (custom scalars, enum mappings,
+    # type helpers all contribute)
+    @requires = []
   end
+  private :reset_walk_state!
 
-  def generate_unions(fragments, names)
-    unless @module_name&.match?(/\A[A-Z]\w*(::[A-Z]\w*)*\z/)
-      raise ArgumentError, "unions module name must be a constant name, got #{@module_name.inspect}"
-    end
+  # generated source is eval'd by parse — never let a name inject code
+  CONSTANT_NAME = /\A[A-Z]\w*(::[A-Z]\w*)*\z/
 
-    @requires = []
-    @mapped_enums = {}
-    # nested spreads inside a shared fragment resolve through the whole table
-    @fragments = fragments
+  def validate_module_name!(subject)
+    return if @module_name&.match?(CONSTANT_NAME)
 
-    unions = names.uniq.sort.map do |name|
-      fragment = fragments.fetch(name)
-      type = @schema.get_type(fragment.type.name)
-      UnionNode.new(camelize(name), union_members(type, fragment.selections))
-    end
+    problem = "#{subject} must be a constant name, got #{@module_name.inspect}"
+    # An explicit module_name: is an argument wrong on its face. A derived one
+    # is a verdict on a FILE — a numeric prefix (01_home.graphql) is the usual
+    # way in — so it names the file, says the fix is a rename, and brands so
+    # `rake graph_weaver:generate` aborts on it instead of burying it under a
+    # backtrace through codegen.
+    raise ArgumentError, problem unless @path
 
-    emit_unions_file(unions)
+    raise GraphWeaver::Error, "#{@path}: #{problem} — it comes from the file name, so rename the " \
+      "file to one a constant can spell (a letter first, then letters, digits or underscores)"
   end
+  private :validate_module_name!
 
   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.
+  # Names generated Ruby can't spell bare — as a kwarg, a local, or a method
+  # name. As a prop they're fine (`const :next`), since a prop is only ever
+  # read off a receiver.
   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
@@ -195,6 +260,17 @@ class GraphWeaver::Codegen
     BEGIN END __FILE__ __LINE__ __ENCODING__
   ].to_set.freeze
   GENERATED_METHODS = %w[serialize to_h].to_set.freeze
+  # Names the generated `execute` body owns: the per-call client kwarg and the
+  # variables hash it builds. A GraphQL variable by either name redeclares one
+  # — `def self.execute(client:, client: nil)` doesn't even parse. No legal
+  # Ruby local is unreachable by a GraphQL variable name, so this is a guard
+  # rather than a rename.
+  RESERVED_KWARGS = %w[client variables].to_set.freeze
+  # Every method a struct instance already answers: T::Props refuses to redefine
+  # those (`class`, `hash`, `send`, `to_s`), so the generated file would raise
+  # ArgumentError at require time. Derived rather than listed, so it tracks
+  # whatever the Ruby and sorbet-runtime in play actually define.
+  STRUCT_METHODS = (GENERATED_METHODS + T::Struct.instance_methods.map(&:to_s)).freeze
 
   def generate
     begin
@@ -202,21 +278,14 @@ class GraphWeaver::Codegen
     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 }])
+      raise GraphWeaver::ValidationError.new([detail(e.message, e.line, e.col)])
     end
     if errors.any?
       raise GraphWeaver::ValidationError.new(errors.map { |e| validation_detail(e) })
     end
 
     validate_registrations!
-
-    @variable_enums = {}
-    @variable_inputs = {}
-    @mapped_enums = {}
-    @used_unions = []
-    # requires the generated file needs (custom scalars, enum mappings,
-    # type helpers all contribute)
-    @requires = []
+    reset_walk_state!
 
     operation = load_operation(@query)
     root_type = operation_root_type(operation)
@@ -226,15 +295,42 @@ class GraphWeaver::Codegen
       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
+    validate_module_name!("module_name:")
+
+    variables = build_variables(operation)
+    root = object_node(root_type, operation.selections, "Result")
+
+    # An anonymous operation takes the module's name — declared in the document
+    # AND sent as operationName, which have to agree (a server rejects an
+    # operationName the document doesn't declare). The conventional .graphql
+    # file names nothing, so without this every trace arrives anonymous.
+    operation_name = operation.name || @module_name.split("::").last
+    @query = declare_operation_name(operation, operation_name) unless operation.name
+
+    emit_module(root, variables, representation_nodes(operation, root_type), operation_name)
+      .tap { report_untyped_scalars }
+  end
+
+  private
+
+  # Insert `name` into the operation's own declaration, leaving the rest of the
+  # document exactly as written — re-printing the AST would reformat the query
+  # the reader reviews. The module name is already constrained to
+  # /[A-Z]\w*(::[A-Z]\w*)*/, so its last segment is always a legal GraphQL name.
+  def declare_operation_name(operation, name)
+    at = @query.lines.first(operation.line - 1).sum(&:length) + operation.col - 1
+    keyword = @query[at..].to_s[/\A(?:query|mutation|subscription)\b/]
+    return "#{@query[0, at]}query #{name} #{@query[at..]}" unless keyword # `{ ... }` shorthand
 
+    "#{@query[0, at + keyword.length]} #{name}#{@query[(at + keyword.length)..]}"
+  end
+
+  # The operation's variables as execute's kwarg surface: one VarDef each,
+  # typed from the AST. A variable is optional when nullable or defaulted —
+  # optional kwargs default to nil and are omitted from the wire.
+  def build_variables(operation)
     variables = operation.variables.map do |var|
       node = ast_type_ref(var.type)
-      # 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?
       kwarg = underscore(var.name)
       # kwargs are declared and forwarded bare in generated source
@@ -243,22 +339,156 @@ class GraphWeaver::Codegen
           "variable $#{var.name} would become the kwarg '#{kwarg}:', which generated code can't declare " \
           "(a Ruby keyword) — rename the variable"
       end
+      if RESERVED_KWARGS.include?(kwarg)
+        raise GraphWeaver::Error,
+          "variable $#{var.name} would become the kwarg '#{kwarg}:', which generated execute already " \
+          "uses — rename the variable (query($#{var.name}Id: ...))"
+      end
       VarDef.new(kwarg, var.name, node, required)
     end
 
-    root = object_node(root_type, operation.selections, "Result")
+    # two variables that underscore to the same kwarg ($userId + $user_id) would
+    # silently drop one on the wire — flag it like a prop collision
+    collision = variables.group_by(&:kwarg).find { |_, vars| vars.size > 1 }
+    if collision
+      wire = collision.last.map { |var| "$#{var.wire}" }.join(", ")
+      raise GraphWeaver::Error,
+        "variables #{wire} both map to the kwarg '#{collision.first}:' — rename one"
+    end
 
-    emit_module(root, variables)
+    variables
   end
 
-  private
+  # Builders for the entity types this query's representation-taking fields
+  # can return. The hook is the schema, not the field name: the subgraph spec
+  # types a representation as `_Any`, so a field taking one is asking for
+  # entity references, and the entity types are the @key'd members its
+  # selection names. Query-driven like everything else — a subgraph with
+  # fifty entities emits builders only for the ones the query reaches.
+  def representation_nodes(operation, root_type)
+    nodes = entity_types(operation, root_type).filter_map { |entity| representation_node(entity) }
+
+    collision = nodes.group_by(&:method_name).find { |_, group| group.size > 1 }
+    if collision
+      types = collision.last.map(&:graphql_type).join(" and ")
+      raise GraphWeaver::Error,
+        "entities #{types} both build Representations.#{collision.first} — rename one, or drop it from the selection"
+    end
+
+    nodes
+  end
+
+  # The types a representation-taking field's selection names. `_entities` is
+  # a root field and the spec defines it nowhere else, so this looks no deeper.
+  def entity_types(operation, root_type)
+    gather_conditional(root_type, operation.selections).each_value.flat_map { |occurrences|
+      fields = occurrences.map(&:first)
+      definition = @schema.get_field(root_type.graphql_name, fields.first.name)
+      next [] unless definition && representation_field?(definition)
+
+      core = definition.type.unwrap
+      next [] unless %w[UNION INTERFACE].include?(core.kind.name)
+
+      selected_members(core, fields.flat_map(&:selections))
+    }.uniq(&:graphql_name)
+  end
+
+  # The subgraph spec's representation scalar. A field taking one is the
+  # entity resolver, whatever it's called.
+  REPRESENTATION_SCALAR = "_Any"
+
+  def representation_field?(definition)
+    definition.arguments.each_value.any? { |argument| argument.type.unwrap.graphql_name == REPRESENTATION_SCALAR }
+  end
+
+  # A `@key` this subgraph resolves. Matched by local name, since a fed-2
+  # subgraph linking the spec under a namespace applies @federation__key;
+  # `resolvable: false` declares a key the subgraph explicitly does NOT
+  # answer for, so it can't stand behind a representation.
+  def resolvable_keys(type)
+    return [] unless type.respond_to?(:directives)
+
+    type.directives.filter_map do |directive|
+      name = directive.graphql_name
+      next unless name == "key" || name.end_with?("__key")
+
+      arguments = directive.arguments.keyword_arguments
+      next if arguments[:resolvable] == false
+
+      arguments[:fields]&.to_s
+    end
+  end
+
+  # An entity's builder, or nil when the type isn't one (no resolvable @key).
+  def representation_node(entity)
+    key_fields = resolvable_keys(entity)
+    key_sets = key_fields.map { |fields| key_paths(entity, fields) }
+    return if key_sets.empty?
+
+    method_name = underscore(entity.graphql_name)
+    if RUBY_KEYWORDS.include?(method_name)
+      raise GraphWeaver::Error,
+        "entity #{entity.graphql_name} would build Representations.#{method_name}, which generated code can't declare (a Ruby keyword)"
+    end
+
+    RepresentationNode.new(method_name, entity.graphql_name, key_fields, key_sets,
+      key_params(entity, key_sets, required: key_sets.one?))
+  end
 
-  # 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.
+  # A @key field set is a GraphQL selection set — "upc sku", or a nested
+  # "id organization { id }" — so parse it and flatten to the leaf paths the
+  # wire hash needs. Dotted, since a GraphQL name can't contain a dot.
+  def key_paths(entity, fields)
+    selections = GraphQL.parse("{ #{fields} }").definitions.first.selections
+    leaf_paths(selections)
+  rescue GraphQL::ParseError => e
+    raise GraphWeaver::Error, "#{entity.graphql_name} @key(fields: #{fields.inspect}) isn't a selection set: #{e.message}"
+  end
+
+  def leaf_paths(selections, prefix = [])
+    selections.flat_map do |node|
+      path = prefix + [node.name]
+      node.selections.empty? ? [path.join(".")] : leaf_paths(node.selections, path)
+    end
+  end
+
+  # The kwargs a builder takes: every key set's top-level field, once. Typed
+  # from the schema — a leaf key field gets its registered scalar's Ruby
+  # type, a nested one an open Hash whose shape the runtime checks.
+  def key_params(entity, key_sets, required:)
+    key_sets.flatten.map { |path| path.split(".").first }.uniq.map do |name|
+      field = @schema.get_field(entity.graphql_name, name)
+      unless field
+        raise GraphWeaver::Error, "#{entity.graphql_name} @key names #{name.inspect}, which the type doesn't declare"
+      end
+
+      kwarg = underscore(name)
+      if RUBY_KEYWORDS.include?(kwarg)
+        raise GraphWeaver::Error,
+          "#{entity.graphql_name} @key field #{name.inspect} would become the kwarg '#{kwarg}:', " \
+          "which generated code can't declare (a Ruby keyword)"
+      end
+
+      core = field.type.unwrap
+      if core.kind.name == "SCALAR"
+        node = scalar_node(core.graphql_name, "#{entity.graphql_name}.#{name}")
+        type = required ? node.bare_type : node.prop_type
+        value = node.serialize_identity? ? kwarg : "#{kwarg}&.then { |v1| #{node.serialize("v1", 2)} }"
+      else
+        # a nested key set — or an enum/composite one — passes through as an
+        # open hash, narrowed to the declared sub-paths by the runtime
+        type = "T::Hash[T.untyped, T.untyped]"
+        type = "T.nilable(#{type})" unless required
+        value = kwarg
+      end
+
+      RepresentationNode::Param.new(kwarg, name, type, value, required)
+    end
+  end
+
+  # A 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 at generation for every registration in play.
   def self.validate_registration!(schema, kind, name)
     # register_scalar("Type.field", ...) overrides one field's scalar — validate
     # the field exists and is a scalar, not that a type named "Type.field" exists.
@@ -270,8 +500,7 @@ class GraphWeaver::Codegen
 
     return if schema.get_type(name)
 
-    suggestion = defined?(DidYouMean::SpellChecker) &&
-      DidYouMean::SpellChecker.new(dictionary: schema.types.keys).correct(name).first
+    suggestion = GraphWeaver.did_you_mean(schema.types.keys, name)
     hint = suggestion ? " — did you mean '#{suggestion}'?" : ""
     # the type registry is reached via extend_type; scalars/enums via register_*
     method = kind == "type" ? "extend_type" : "register_#{kind}"
@@ -294,13 +523,19 @@ class GraphWeaver::Codegen
   # map — reusable fragments a query can spread. Fragment files hold only
   # fragments (no operations); names are unique across them.
   def self.load_fragments(paths)
-    Array(paths).flat_map { |dir| Dir[File.join(dir, "*.graphql")].sort }.each_with_object({}) do |file, out|
-      doc = GraphQL.parse(File.read(file))
+    source = {} # fragment name => the file that defined it, for the collision message
+
+    Array(paths).flat_map { |dir| Dir[File.join(dir, DOCUMENT_GLOB)].sort }.each_with_object({}) do |file, out|
+      doc = parse_document(File.read(file), file)
       if doc.definitions.grep(GraphQL::Language::Nodes::OperationDefinition).any?
         raise GraphWeaver::Error, "#{file}: fragment files define only fragments, no operations"
       end
       doc.definitions.grep(GraphQL::Language::Nodes::FragmentDefinition).each do |frag|
-        raise GraphWeaver::Error, "duplicate shared fragment '#{frag.name}' (#{file})" if out.key?(frag.name)
+        if (earlier = source[frag.name])
+          raise GraphWeaver::Error,
+            "duplicate shared fragment '#{frag.name}' — defined in #{earlier} and #{file}; rename one"
+        end
+        source[frag.name] = file
         out[frag.name] = frag
       end
     end
@@ -310,18 +545,34 @@ class GraphWeaver::Codegen
   # shadows with a local definition of the same name — the names
   # inline_fragments appends, and the set the generate! workflow may hoist
   # when they sit on a whole-union field.
-  def self.shared_fragment_spreads(query, shared)
+  def self.shared_fragment_spreads(query, shared, path = nil)
+    # parsed even with nothing to spread: this is the first look at the document
+    # on the generate! path, so it's where a syntax error gets branded and
+    # pinned to the file it came from
+    doc = parse_document(query, path)
     return [] if shared.empty?
 
-    doc = GraphQL.parse(query)
     local = doc.definitions.grep(GraphQL::Language::Nodes::FragmentDefinition).map(&:name)
     reachable_fragments(fragment_spreads(doc.definitions), shared, local)
   end
 
+  # Parse a GraphQL document, branding graphql-ruby's ParseError under the
+  # umbrella and naming the file it came from — its own location is a line and
+  # column in a document the caller never sees. This runs on the generate! path
+  # BEFORE Codegen#generate's rescue, so it needs its own guard.
+  def self.parse_document(query, path = nil)
+    GraphQL.parse(query)
+  rescue GraphQL::ParseError => e
+    prefix = [path, e.line, e.col].compact.join(":")
+    raise GraphWeaver::ValidationError.new(
+      [{ message: prefix.empty? ? e.message : "#{prefix} #{e.message}", line: e.line, column: e.col }],
+    )
+  end
+
   # Append the shared fragments a query spreads (transitively) to its source, so
   # the sent query is self-contained. Unused shared fragments are left out.
-  def self.inline_fragments(query, shared)
-    used = shared_fragment_spreads(query, shared)
+  def self.inline_fragments(query, shared, path = nil)
+    used = shared_fragment_spreads(query, shared, path)
     return query if used.empty?
 
     "#{query.rstrip}\n\n#{used.sort.map { |name| shared.fetch(name).to_query_string }.join("\n\n")}\n"
@@ -357,24 +608,30 @@ class GraphWeaver::Codegen
   # 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"] }
+    detail(error.message, loc && loc["line"], loc && loc["column"])
+  end
+
+  # One ValidationError entry, its message prefixed "file:line:col" like a
+  # compiler — the position is captured either way, and without it a project
+  # with thirty query files leaves the reader hunting for the typo.
+  def detail(message, line, column)
+    prefix = [@path, line, column].compact.join(":")
+    { message: prefix.empty? ? message : "#{prefix} #{message}", line:, column: }
   end
 
+  # Every registration this generation could consult. The built-in scalars are
+  # pre-registered entries in the same table rather than user intent, so
+  # they're exempt — a schema with no Date scalar is not a mistake.
   def validate_registrations!
-    { "enum" => @enums, "scalar" => @scalars, "type" => @types }.each do |kind, registry|
+    {
+      "enum" => GraphWeaver::Codegen.enum_registry,
+      "scalar" => GraphWeaver::Codegen.scalar_registry.except(*BUILTIN_SCALARS),
+      "type" => GraphWeaver::Codegen.type_registry,
+    }.each do |kind, registry|
       registry.each_key { |name| self.class.validate_registration!(@schema, kind, name) }
     end
   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
@@ -384,10 +641,13 @@ class GraphWeaver::Codegen
     # same union selected two ways (unblockOptions vs selectedOption) shares
     # one Ruby type, so consumers get one exhaustive `case ... T.absurd`.
     union_cache = {}
+    props = {}
 
-    gather(type, selections).each do |key, field_nodes|
+    gather_conditional(type, selections).each do |key, occurrences|
+      field_nodes = occurrences.map(&:first)
       field_name = field_nodes.first.name
       prop = underscore(key)
+      check_output_prop!(type, key, prop, props)
 
       child = if field_name == "__typename"
         NonNull.new(scalar_node("String"))
@@ -395,59 +655,66 @@ class GraphWeaver::Codegen
         field_type = @schema.get_field(type.graphql_name, field_name).type
         sub_selections = field_nodes.flat_map(&:selections)
 
-        case (core = unwrap(field_type)).kind.name
+        case (core = field_type.unwrap).kind.name
         when "OBJECT"
-          name = pick_name(core.graphql_name, key, taken)
+          name = pick_name(key, taken)
           type_ref(field_type) { object_node(core, sub_selections, name) }
         when "UNION", "INTERFACE"
           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)
+          if conditions.empty?
+            # abstract-level fields only — every member shares them, so one
+            # struct suffices and no __typename dispatch is needed (for a
+            # union that selection can only be __typename)
+            name = pick_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)
+            # With `__typename` selected the match is read off the tag;
+            # without one there is nothing to read but emptiness, and a
+            # fragment whose every field hides behind @skip/@include would
+            # make a real match indistinguishable from a miss ({} either
+            # way) — refuse rather than guess.
+            tag = member.graphql_name if dispatchable_typename?(core, sub_selections)
+            unless tag || 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"
+                "@skip/@include (or a `__typename` to match on) — 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)) }
-          elsif @unions_namespace && (frag = lone_shared_spread(sub_selections)) &&
+            name = pick_name(key, taken)
+            nilable_type_ref(field_type) { NarrowedNode.new(object_node(member, sub_selections, name), typename: tag) }
+          elsif @types_namespace && (frag = lone_shared_spread(sub_selections)) &&
               @hoistable_unions.include?(frag)
             # a whole-union field spread as a named shared fragment: hoist to
-            # the shared unions module so the same union across queries is one
+            # the shared types module so the same union across queries is one
             # Ruby type family (one exhaustive `case ... T.absurd`).
             @used_unions << frag unless @used_unions.include?(frag)
             ref = UnionRefNode.new(camelize(frag))
             type_ref(field_type) { ref }
           else
             members = union_members(core, sub_selections)
-            # reuse an identical sibling union (pick_name/name only on a miss)
-            union = (union_cache[union_signature(members)] ||=
-              UnionNode.new(pick_name(core.graphql_name, key, taken), members))
+            catch_all = catch_all_member(core, sub_selections, members)
+            # reuse an identical sibling union — the shared type takes the
+            # first of the sharing keys alphabetically, not in walk order
+            signature = union_signature(members, catch_all)
+            union = union_cache[signature]
+            if union
+              rename_union(union, key, taken) if camelize(key) < union.class_name
+            else
+              union = union_cache[signature] = UnionNode.new(pick_name(key, taken), members, catch_all)
+            end
             type_ref(field_type) { union }
           end
         when "ENUM"
-          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
+          # one schema enum is one Ruby type: module-level, named for the enum,
+          # shared by every result field and variable that reaches it (and, on
+          # the generate! path, by every query module — see types_namespace)
+          type_ref(field_type) { variable_core(core) }
         when "SCALAR"
           coordinate = "#{type.graphql_name}.#{field_name}"
           type_ref(field_type) { scalar_node(core.graphql_name, coordinate) }
@@ -456,9 +723,11 @@ class GraphWeaver::Codegen
         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) } }
+      # A field under @skip/@include — on the field itself, or on any fragment
+      # it was reached through — may be absent from the response no matter what
+      # the schema says, so its type must admit nil. One unconditional
+      # selection of the same key still guarantees it, though.
+      if occurrences.all? { |node, conditional| conditional || conditional?(node) }
         child = child.of if child.is_a?(NonNull)
       end
 
@@ -469,79 +738,47 @@ class GraphWeaver::Codegen
     node
   end
 
-  # Resolve each registered alias (extend_type alias:) for this struct's type
-  # against its actual selection — path -> a typed delegator emitted into the
-  # struct body. Validated here, per query, so an unselected or untraversable
-  # path fails at generation with a pointed message.
-  def resolve_aliases(node)
-    type_aliases(node.graphql_type).map do |name, segments|
-      resolve_alias(node, name, segments)
+  # Both ways a result key can fail to become a prop — a name the struct
+  # already answers, or a second key that underscores onto an earlier one.
+  # Either emits a file that raises ArgumentError at require time, so refuse
+  # here; an alias in the query fixes both. `props` accumulates prop => key.
+  def check_output_prop!(type, key, prop, props)
+    # Keywords are fine: `const :next` and `next: data["next"]` are legal, and
+    # the one place a prop is read bare (an alias delegator) qualifies it.
+    # `pageInfo { next }` and `filter { in }` are ordinary API shapes.
+    if STRUCT_METHODS.include?(prop)
+      raise GraphWeaver::Error,
+        "#{type.graphql_name}.#{key} would become prop '#{prop}', which every generated struct " \
+        "already defines — alias it in the query (`#{prop}Value: #{key}`)"
     end
-  end
-
-  # Registered aliases for a GraphQL type: global registry plus this client's
-  # overlay (client-scoped wins on a name clash).
-  def type_aliases(graphql_name)
-    global = GraphWeaver::Codegen.type_registry[graphql_name]&.dig(:aliases) || {}
-    (global.merge(@types[graphql_name]&.dig(:aliases) || {}))
-  end
 
-  ALIAS_RESERVED = (%w[from_h serialize to_h].to_set + RUBY_KEYWORDS).freeze
-
-  # Walk a dotted path (Ruby prop names) through this struct's selected fields,
-  # building the delegator expression (`meta&.tag`) and its return type. Any hop
-  # is nilable -> the accessor is nilable; a list hop or an unselected segment
-  # raises. The leaf may be any node (scalar, enum, nested struct).
-  def resolve_alias(node, name, segments)
-    if node.fields.any? { |f| f.prop == name } || ALIAS_RESERVED.include?(name)
+    if (earlier = props[prop])
       raise GraphWeaver::Error,
-        "alias #{name.inspect} on #{node.graphql_type} collides with an existing field or method"
+        "result keys #{earlier.inspect} and #{key.inspect} on #{type.graphql_name} both map to the " \
+        "prop '#{prop}' — alias one to a distinct name"
     end
 
-    current = T.let(node, T.untyped)
-    parts = []
-    nilable = T.let(false, T::Boolean)
-    segments.each_with_index do |seg, i|
-      field = current.fields.find { |f| f.prop == seg }
-      unless field
-        props = current.fields.map(&:prop)
-        suggestion = defined?(DidYouMean::SpellChecker) &&
-          DidYouMean::SpellChecker.new(dictionary: props).correct(seg).first
-        hint = suggestion ? " — did you mean '#{suggestion}'?" : " (have: #{props.join(", ")})"
-        raise GraphWeaver::Error,
-          "alias #{name.inspect} on #{node.graphql_type}: '#{seg}' is not a selected field#{hint}"
-      end
-      nilable ||= !field.node.non_null?
-
-      if i == segments.size - 1
-        leaf = field.node.bare_type
-        type = nilable && leaf != "T.untyped" ? "T.nilable(#{leaf})" : leaf
-        return ObjectNode::Alias.new(name, (parts << seg).join, type)
-      end
-
-      inner = T.let(field.node, T.untyped)
-      inner = inner.of while inner.is_a?(NonNull)
-      raise GraphWeaver::Error, "alias #{name.inspect}: cannot traverse list-typed '#{seg}'" if inner.is_a?(List)
-      unless inner.is_a?(ObjectNode)
-        raise GraphWeaver::Error, "alias #{name.inspect}: '#{seg}' is not an object to traverse into"
-      end
-
-      parts << seg << (field.node.non_null? ? "." : "&.")
-      current = inner
-    end
+    props[prop] = key
   end
 
-  # 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|
+  # The concrete type conditions a selection mentions, minus conditions naming
+  # the abstract type itself — recursing into named-fragment and inline bodies,
+  # so a `... on X` nested inside a spread (`{ ...NodeFields }` where NodeFields
+  # holds `... on X`) still drives dispatch instead of being silently dropped.
+  def concrete_conditions(core, selections, visiting = Set.new)
+    selections.flat_map do |selection|
       case selection
       when GraphQL::Language::Nodes::InlineFragment
-        selection.type&.name
+        [selection.type&.name, *concrete_conditions(core, selection.selections, visiting)]
       when GraphQL::Language::Nodes::FragmentSpread
-        @fragments.fetch(selection.name).type.name
+        next [] if visiting.include?(selection.name)
+
+        fragment = @fragments.fetch(selection.name)
+        [fragment.type.name, *concrete_conditions(core, fragment.selections, visiting | [selection.name])]
+      else
+        []
       end
-    end.uniq - [core.graphql_name]
+    end.compact.uniq - [core.graphql_name]
   end
 
   # result keys selected as plain fields (outside any type condition)
@@ -563,12 +800,23 @@ class GraphWeaver::Codegen
   # 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) }
+    each_field(member, selections) do |_key, node, conditional|
+      return true if !conditional && !conditional?(node)
     end
     false
   end
 
+  # Is the response guaranteed to carry a plain "__typename" key for this
+  # abstract selection? Every dispatch reads the tag unguarded, so an alias
+  # (which files it under another key) or an @skip/@include (which may drop
+  # it) means there is no tag to dispatch on.
+  def dispatchable_typename?(type, selections)
+    occurrences = gather_conditional(type, selections)["__typename"]
+    !!occurrences&.any? do |node, conditional|
+      node.name == "__typename" && !conditional && !conditional?(node)
+    end
+  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)
@@ -582,29 +830,65 @@ class GraphWeaver::Codegen
     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.
-  # The union's member structs (graphql type name => ObjectNode), sorted for
-  # deterministic output. Dispatch reads __typename, so the query must select
-  # it; for interfaces the interface-level fields gather into every member.
+  # Abstract types (unions AND interfaces) whose selections vary by concrete
+  # type: one member struct per type the selection NAMES (graphql type name =>
+  # ObjectNode, sorted for deterministic output), never one per schema member —
+  # a query against an interface with 278 implementations types the two it asked
+  # about. Dispatch reads __typename, so the query must select it; for
+  # interfaces the interface-level fields gather into every member.
   def union_members(type, selections)
-    unless gather(type, selections).key?("__typename")
+    unless dispatchable_typename?(type, selections)
       raise ArgumentError,
-        "select __typename on #{type.graphql_name} so the union can dispatch — " \
-        "or narrow to a single `... on Type` condition (no dispatch needed)"
+        "select __typename on #{type.graphql_name} so the union can dispatch — unaliased and " \
+        "not under @skip/@include, since from_h reads it on every response — or narrow to a " \
+        "single `... on Type` condition (no dispatch needed)"
     end
 
-    @schema.possible_types(type).sort_by(&:graphql_name).to_h do |possible|
+    selected_members(type, selections).sort_by(&:graphql_name).to_h do |possible|
       [possible.graphql_name, object_node(possible, selections, camelize(possible.graphql_name))]
     end
   end
 
+  # The concrete types a selection names through its type conditions, kept to
+  # the abstract type's own members. A condition naming another abstract type
+  # (`... on Named` inside a union) stands for the members it covers, since its
+  # fields are typed per member.
+  def selected_members(type, selections)
+    possible = @schema.possible_types(type).to_h { |member| [member.graphql_name, member] }
+
+    concrete_conditions(type, selections).flat_map { |name|
+      condition = @schema.get_type(name)
+      condition.kind.name == "OBJECT" ? [condition] : @schema.possible_types(condition)
+    }.map(&:graphql_name).uniq.filter_map { |name| possible[name] }
+  end
+
+  # The one struct everything else deserializes into: a member the query didn't
+  # name, and — the point — a member the schema grows AFTER this file was
+  # generated. It carries only what the abstract type itself guarantees (an
+  # interface's selected interface-level fields; for a union, just __typename),
+  # so a new upstream member bends the result rather than breaking it.
+  def catch_all_member(type, selections, members)
+    object_node(type, selections, catch_all_name(members))
+  end
+
+  # "Other", unless a real member already claims that name.
+  def catch_all_name(members)
+    taken = members.each_value.map(&:class_name)
+    name = "Other"
+    suffix = 2
+    while taken.include?(name)
+      name = "Other#{suffix}"
+      suffix += 1
+    end
+    name
+  end
+
   # A name-independent structural fingerprint of a union's members, so two
   # occurrences that generate identical structs collapse to one Ruby type.
-  def union_signature(members)
-    members.map { |gname, member| "#{gname}=#{signature(member)}" }.sort.join(",")
+  def union_signature(members, catch_all = nil)
+    parts = members.map { |gname, member| "#{gname}=#{signature(member)}" }
+    parts << "*=#{signature(catch_all)}" if catch_all
+    parts.sort.join(",")
   end
 
   # Structural signature of a node — ignores the generated class name (which
@@ -621,7 +905,7 @@ class GraphWeaver::Codegen
     when ObjectNode
       inner = node.fields.map { |f| "#{f.prop}=#{signature(f.node)}" }.sort.join(",")
       "o:#{node.graphql_type}(#{inner})"
-    when UnionNode then "u:(#{union_signature(node.members)})"
+    when UnionNode then "u:(#{union_signature(node.members, node.catch_all)})"
     when UnionRefNode then "ur:#{node.class_name}" # hoisted — identity is its shared name
     else "x:#{node.object_id}" # unknown node kind — never collapse
     end
@@ -648,8 +932,7 @@ class GraphWeaver::Codegen
     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))
+      mapped_enum_node(core) || (@enums[core.graphql_name] ||= enum_node(core))
     when "INPUT_OBJECT"
       input_node(core)
     else
@@ -665,40 +948,70 @@ class GraphWeaver::Codegen
     return @variable_inputs[core.graphql_name] if @variable_inputs.key?(core.graphql_name)
 
     node = @variable_inputs[core.graphql_name] = InputNode.new(camelize(core.graphql_name))
+    node.one_of = core.respond_to?(:one_of?) && core.one_of?
     # 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)
+      # Keywords are fine here: nothing reads an input prop bare (serialize goes
+      # through public_send), and `const :in` is legal — which matters, since a
+      # schema's field name is not the user's to rename. `Tricky.in` filters are
+      # standard Hasura/Gatsby shape.
+      if STRUCT_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}"}"
+          "which collides with a method every struct defines"
       end
 
-      child = type_ref(argument.type) { variable_core(unwrap(argument.type)) }
+      child = type_ref(argument.type) { variable_core(argument.type.unwrap) }
       required = child.non_null? && !argument.default_value?
       node.fields << InputNode::Field.new(prop, argument.graphql_name, child, required)
     end
     node
   end
 
-  # The InputNodes a struct's fields reference, through NON_NULL/LIST
-  # wrappers — the edges of the input dependency graph.
+  # The module-level T::Enum for a schema enum, named for the enum itself —
+  # it is shared by every field and variable of that type.
+  def enum_node(core)
+    class_name = camelize(core.graphql_name)
+    if MODULE_RESERVED.include?(class_name)
+      raise GraphWeaver::Error,
+        "enum #{core.graphql_name} generates #{class_name}, which collides with a generated " \
+        "constant — map it onto one of yours: register_enum(#{core.graphql_name.inspect}, YourEnum)"
+    end
+
+    EnumNode.new(class_name, enum_values(core))
+  end
+
+  # A schema enum's wire values, sorted so output is deterministic across schema
+  # sources (SDL round-trips reorder values alphabetically). Values that differ
+  # only in case name the same T::Enum constant, which raises at LOAD time
+  # ("Enum values must be assigned to constants") — catch it here instead.
+  def enum_values(core)
+    values = core.values.keys.sort
+    collision = values.group_by { |value| camelize(value.downcase) }.find { |_, group| group.size > 1 }
+    if collision
+      raise GraphWeaver::Error,
+        "enum #{core.graphql_name} values #{collision.last.join(" and ")} both become the constant " \
+        "#{collision.first} — map the enum onto one of yours: " \
+        "register_enum(#{core.graphql_name.inspect}, YourEnum)"
+    end
 
+    values
+  end
 
-  # Registered helper-module names for a GraphQL type (additive: global
-  # registrations plus this client's), collecting their requires.
+  # Registered helper-module names for a GraphQL type, 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) }
+    entry = GraphWeaver::Codegen.type_registry[graphql_name]
+    return [] unless entry
+
+    @requires.concat(entry[:requires])
+    entry[:mixins].map(&:name)
   end
 
   # 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.
+  # mapping; 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]
+    enum_type = GraphWeaver::Codegen.enum_registry[core.graphql_name]
     return unless enum_type
 
     @requires.concat(enum_type.requires)
@@ -708,16 +1021,32 @@ class GraphWeaver::Codegen
   # A Scalar node, recording any requires its registered type needs so the
   # generated file can require them (collected across the whole query).
   # Resolution, most specific first: a per-field override (`Type.field`), then
-  # the scalar-name registration — each checked client-scoped, then global.
+  # the scalar-name registration.
   def scalar_node(name, coordinate = nil)
-    scalar =
-      (coordinate && (@scalars[coordinate] || GraphWeaver::Codegen.scalar_registry[coordinate])) ||
-      @scalars[name.to_s] ||
-      GraphWeaver::Codegen.scalar(name)
+    registry = GraphWeaver::Codegen.scalar_registry
+    scalar = (coordinate && registry[coordinate]) || registry[name.to_s]
+    if scalar.nil?
+      @untyped_scalars << name.to_s
+      scalar = GraphWeaver::Codegen.scalar(name)
+    end
     @requires.concat(scalar.requires)
     Scalar.new(scalar)
   end
 
+  # An unregistered custom scalar passes through as T.untyped — legitimate
+  # (nobody needs a codec for every scalar), but it's the one hole in an
+  # otherwise exact result type, so name the holes rather than leave them
+  # silent. Informational: not a warning, never an error.
+  def report_untyped_scalars
+    names = @untyped_scalars.uniq.sort
+    return if names.empty?
+
+    GraphWeaver.log(:info) do
+      "#{names.size} unregistered custom scalar#{"s" unless names.one?} → T.untyped: " \
+        "#{names.join(", ")} (register with GraphWeaver.register_scalar)"
+    end
+  end
+
   # rebuild the NON_NULL/LIST wrappers around the core node
   def type_ref(type, &core)
     case type.kind.name
@@ -730,21 +1059,45 @@ class GraphWeaver::Codegen
     end
   end
 
-  def unwrap(type)
-    type = type.of_type while type.kind.name == "NON_NULL" || type.kind.name == "LIST"
-    type
-  end
+  # A generated type is named for the response key that selects it, camelized
+  # (`stargazers` => Stargazers) — a function of the field's own position and
+  # nothing else, so adding, removing, or reordering an unrelated selection can
+  # never rename it. Generated code is app-code API; a name that shifts under
+  # an unrelated edit is a silent break. `taken` is the names claimed in this
+  # struct's scope, its first entry the struct itself.
+  #
+  # (Union members are the exception: they are named for the type condition
+  # that produces them, which is equally position-determined.)
+  def pick_name(key, taken)
+    name = camelize(key)
+
+    # a key that camelizes to no constant at all ("_", "_1") would emit
+    # `class  < T::Struct`
+    unless name.match?(/\A[A-Z]/)
+      raise GraphWeaver::Error,
+        "result key #{key.inspect} makes no class name (#{name.inspect}) — alias it to one starting with a letter"
+    end
 
-  # 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 name == taken.first
+      # would shadow the struct it nests in — the parent's own `returns(Name)`
+      # resolves lexically and would find the child
+      suffix = 2
+      suffix += 1 while taken.include?("#{name}#{suffix}")
+      name = "#{name}#{suffix}"
+    elsif taken.include?(name)
+      raise GraphWeaver::Error,
+        "result keys on #{taken.first} both generate the class #{name} — alias one to a distinct name"
+    end
 
-    taken << candidate
-    candidate
+    taken << name
+    name
   end
 
+  # Fields whose union selections are structurally identical share one Ruby
+  # type; name it for the alphabetically first of their keys, so which field
+  # the walk happened to reach first doesn't decide.
+  def rename_union(union, key, taken)
+    taken.delete(union.class_name)
+    union.class_name = pick_name(key, taken)
+  end
 end