graph_weaver 0.6.1 → 0.7.0

data/lib/graph_weaver/codegen.rb

@@ -4,6 +4,8 @@
 require "graphql"
 require "sorbet-runtime"
 
+require_relative "result_struct"
+
 # Generates plain, statically-typecheckable Ruby from a GraphQL query +
 # schema: nested T::Structs, from_h casting code, and a sig'd execute
 # method. The output is source on disk, so srb tc sees the exact result
@@ -32,6 +34,8 @@ require_relative "codegen/scalar_type"
 require_relative "codegen/nodes"
 require_relative "codegen/aliases"
 require_relative "codegen/emit"
+# after the three files that fill Registrations in — it gives them a home
+require_relative "codegen/registry"
 
 class GraphWeaver::Codegen
   include GraphWeaver::Inflect
@@ -61,7 +65,9 @@ class GraphWeaver::Codegen
   #
   # 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=). name: is the module the file
+  # the app default (GraphWeaver.client=). graph_name: is the graph the
+  # module belongs to, baked in so a test mode can build its stand-in from
+  # the right schema. name: is the module the file
   # defines, defaulting to the operation's own name; default_name: is
   # parse's container-scoped fallback (file generation stays strict — a
   # checked-in file deserves a deliberate name). types_namespace: is the shared-types workflow (see
@@ -73,9 +79,13 @@ class GraphWeaver::Codegen
   # 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:, name: nil, client: nil, default_name: nil,
-    types_namespace: nil, hoistable_unions: nil, path: nil, module_name: nil)
+    types_namespace: nil, hoistable_unions: nil, path: nil, module_name: nil,
+    graph_name: nil, registry: GraphWeaver::Codegen.registry)
     renamed!(module_name)
     @schema = schema
+    # the registrations this generation reads — one graph's, or the default
+    # graph's, which is what every top-level register_scalar writes to
+    @registry = registry
     @query = query.strip
     # only ever quoted in a message, so it is stored the way it is reported
     @path = path && GraphWeaver::Internal::Util.relative(path)
@@ -87,11 +97,26 @@ class GraphWeaver::Codegen
     # scalars this generation had no registration for (see report_untyped_scalars)
     @untyped_scalars = []
     @client_const = CLIENT_CONST.call(client)
+    # the graph this module belongs to, baked in beside the client: a test
+    # mode builds its stand-in from the module's own schema, and only the
+    # module can say whose that is (GraphWeaver::Internal::TestClients).
+    # A Symbol, as GraphWeaver.graph makes it — the name is the identity.
+    @graph_name = graph_name&.to_sym
 
     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"
+      raise ArgumentError, "client: must be a named constant or String (got #{client.inspect}) — " \
+        "put the object in a constant and name it, client: \"MyApi::CLIENT\"; pass live objects to parse"
+    end
+    # The String is written into the module verbatim, so anything that isn't a
+    # constant path emits source that doesn't parse. A url is the way to get
+    # here — it is where the endpoint is spelled everywhere else — so the fix
+    # names the value that was passed.
+    if @client_const && !@client_const.match?(CONSTANT_NAME)
+      raise ArgumentError, "client: #{@client_const.inspect} isn't a constant — generated source " \
+        "spells this name, so it has to be one: CLIENT = GraphWeaver.new(#{@client_const.inspect}), " \
+        "then client \"CLIENT\""
     end
   end
 
@@ -126,10 +151,10 @@ 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:, name: nil, client: nil, path: nil, module_name: nil)
+  def self.parse(schema:, query:, name: nil, client: nil, path: nil, module_name: nil, graph_name: nil)
     client_const = CLIENT_CONST.call(client)
 
-    codegen = new(schema:, query:, name:, client: client_const, path:, module_name:,
+    codegen = new(schema:, query:, name:, client: client_const, path:, module_name:, graph_name:,
       default_name: "Query")
     source = codegen.generate
 
@@ -148,16 +173,6 @@ class GraphWeaver::Codegen
     mod
   end
 
-  # 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.
@@ -170,6 +185,11 @@ class GraphWeaver::Codegen
   # must contain.
   def used_union_names = @used_unions.dup
 
+  # The custom scalars this walk found no registration for (see
+  # report_untyped_scalars) — the generate! workflow unions these across
+  # queries so the build says them once, for GraphWeaver.untyped_scalars.
+  def untyped_scalars = @untyped_scalars.uniq.sort
+
   # 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
@@ -253,6 +273,12 @@ class GraphWeaver::Codegen
   def reset_walk_state!
     @enums = {}
     @variable_inputs = {}
+    # the variable declaration the input walk descends from, and the field
+    # hops it has taken since — an input collision is about a type the user
+    # usually never named, so the refusal has to point back at what they wrote
+    @input_from = nil
+    @input_list = false
+    @input_hops = []
     @mapped_enums = {}
     @used_unions = []
     # requires the generated file needs (custom scalars, enum mappings,
@@ -265,6 +291,15 @@ class GraphWeaver::Codegen
   CONSTANT_NAME = /\A[A-Z]\w*(::[A-Z]\w*)*\z/
 
   def validate_module_name!(subject)
+    # Generated code spells Sorbet's T inside the module's own body (T.let,
+    # T::Struct), and constant lookup finds a top-level T first — so a module
+    # whose path starts with one shadows the thing it depends on. A generated
+    # file can't get here (a file name always gains a Query/Mutation word);
+    # an explicit name:, a namespace, and parse can.
+    if @name&.split("::")&.first == "T"
+      raise ArgumentError, "#{subject} #{@name.inspect} — a top-level module named T shadows " \
+        "Sorbet's T, which generated code uses in its own body (T.let, T::Struct)"
+    end
     return if @name&.match?(CONSTANT_NAME)
 
     problem = "#{subject} must be a constant name, got #{@name.inspect}"
@@ -299,23 +334,90 @@ class GraphWeaver::Codegen
   # 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
-  private_constant :RUBY_KEYWORDS, :GENERATED_METHODS, :RESERVED_KWARGS, :STRUCT_METHODS
+  # One rule: a prop may not shadow a method its struct answers. Three kinds of
+  # name land in it — the ones T::Struct and Object answer PUBLICLY, the hooks
+  # Ruby and Rails call on any object without it defining one, and the ones the
+  # gem's own mixins define.
+  #
+  # Kernel's PRIVATE methods are deliberately NOT here. A struct doesn't answer
+  # them, so a prop shadows one only for a bare call from inside the struct —
+  # which is the gem's code to keep qualified (`Kernel.raise` in hints.rb and
+  # input_struct.rb), not the schema's to avoid. Reserving them refused real
+  # columns: a Hasura bool_exp has one input field per column, and `format`,
+  # `select`, `test`, `open`, `load` and `pp` are all columns somebody has.
+  #
+  # Listed, not derived from the live T::Struct: derivation made generation a
+  # function of require order — with ActiveSupport loaded first `as_json` was
+  # refused, loaded second it became a prop that shadowed the real #as_json —
+  # and generated output must depend on nothing but the schema, the query and
+  # the gem. sorbet-runtime's own BANNED_METHOD_NAMES is that same snapshot of
+  # `Object.instance_methods`, so it can't be leaned on either. A name a later
+  # Ruby adds and this misses is loud anyway: the generated file raises
+  # ArgumentError when it is required.
+  #
+  # The gem's own mixins stay derived — they are the gem's to track, so adding
+  # a method to one reserves its name without a second edit here.
+  RESERVED_PROPS = (GENERATED_METHODS +
+    # what T::Struct and Object answer publicly. `to_yaml` and `pretty_print*`
+    # ride in on psych and pp, which land on Object whenever they are loaded —
+    # listed unconditionally, since what else is loaded is not generation's
+    # business.
+    %w[
+      ! != !~ <=> == === __id__ __send__
+      class clone define_singleton_method deserialize display dup enum_for eql?
+      equal? extend freeze frozen? hash inspect instance_eval instance_exec
+      instance_of? instance_variable_defined? instance_variable_get instance_variable_set
+      instance_variables is_a? itself kind_of? method methods nil? object_id
+      pretty_inspect pretty_print pretty_print_cycle pretty_print_inspect
+      pretty_print_instance_variables private_methods protected_methods
+      public_method public_methods public_send remove_instance_variable respond_to?
+      send serialize singleton_class singleton_method singleton_methods tap then
+      to_enum to_s to_yaml with yield_self
+    ] +
+    # hooks called on an object that doesn't define them: `initialize` from
+    # .new, `initialize_copy` from dup, `to_ary` from `puts`, `deconstruct`
+    # from an array pattern, `as_json` from `render json:`
+    %w[
+      as_json deconstruct deconstruct_keys each initialize initialize_clone
+      initialize_copy initialize_dup presence to_a to_ary to_hash to_int to_json
+      to_param to_proc to_query to_str try
+    ] +
+    [GraphWeaver::ResultStruct, GraphWeaver::Hints, GraphWeaver::InputStruct].flat_map { |mod|
+      (mod.instance_methods(false) + mod.private_instance_methods(false)).map(&:to_s)
+    }).freeze
+  private_constant :RUBY_KEYWORDS, :GENERATED_METHODS, :RESERVED_KWARGS, :RESERVED_PROPS
+
+  # The Ruby name for a GraphQL field or result key: snake_case, plus a
+  # trailing underscore when that would shadow a method the struct answers
+  # (`class` -> `class_`, `hash` -> `hash_`). A schema's field name is not the
+  # user's to rename, and `class`, `hash`, `display` and `supplied` are all
+  # columns somebody has — so renaming beats refusing. Only the Ruby side
+  # moves: the wire name, and everything read from or written to the wire,
+  # is untouched.
+  #
+  # Public because the rule has readers outside generation: Hints maps a wire
+  # key onto the prop that holds it, and the round-trip harness checks what
+  # came back against them. A second spelling of the rule is how the two sides
+  # drift apart.
+  def self.prop_name(graphql_name)
+    prop = GraphWeaver::Inflect.underscore(graphql_name)
+    RESERVED_PROPS.include?(prop) ? "#{prop}_" : prop
+  end
 
   def generate
-    begin
-      errors = @schema.validate(@query)
+    document = begin
+      GraphQL.parse(@query)
     rescue GraphQL::ParseError => e
       # unparseable queries wrap like invalid ones — everything raised
       # here descends from GraphWeaver::Error
-      raise GraphWeaver::ValidationError.new([detail(e.message, e.line, e.col)])
+      raise GraphWeaver::QueryValidationError.new([detail(e.message, e.line, e.col)])
     end
+
+    refuse_incremental!(document)
+
+    errors = @schema.validate(document)
     if errors.any?
-      raise GraphWeaver::ValidationError.new(errors.map { |e| validation_detail(e) })
+      raise GraphWeaver::QueryValidationError.new(errors.map { |e| validation_detail(e) })
     end
 
     validate_registrations!
@@ -340,7 +442,7 @@ class GraphWeaver::Codegen
     # operationName the document doesn't declare). The conventional .graphql
     # file names nothing, so without this every trace arrives anonymous.
     operation_name = operation.name || @name.split("::").last
-    @query = declare_operation_name(operation, operation_name) unless operation.name
+    @query = declare_operation_name(operation_name) unless operation.name
 
     emit_module(root, variables, representation_nodes(operation, root_type), operation_name)
       .tap { report_untyped_scalars }
@@ -352,12 +454,51 @@ class GraphWeaver::Codegen
   # 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
+  def declare_operation_name(name)
+    at = operation_offset
     keyword = @query[at..].to_s[/\A(?:query|mutation|subscription)\b/]
-    return "#{@query[0, at]}query #{name} #{@query[at..]}" unless keyword # `{ ... }` shorthand
+    named = if keyword
+      "#{@query[0, at + keyword.length]} #{name}#{@query[(at + keyword.length)..]}"
+    else # `{ ... }` shorthand
+      "#{@query[0, at]}query #{name} #{@query[at..]}"
+    end
+
+    declares!(named, name)
+  end
+
+  # Where the operation starts in @query, in characters. graphql-ruby subtracts
+  # a CHARACTER line start from the lexer's BYTE position
+  # (Language::Parser#column_at over Lexer's @scanner.pos), so line start plus
+  # col is a byte offset — and col falls back to a whole-document offset for a
+  # token with no newline after it, which .strip guarantees for the last line,
+  # hence the copy that ends in one.
+  def operation_offset
+    operation = sole_operation("#{@query}\n")
+    bytes = @query.lines.first(operation.line - 1).sum(&:length) + operation.col - 1
+    @query.byteslice(0, bytes).length
+  end
+
+  # The splice above is arithmetic over a position graphql-ruby reports, so it
+  # can land wrong and still emit a module that looks fine — and OPERATION_NAME
+  # would then be an operationName the document doesn't declare, which every
+  # server rejects. Nothing else re-reads the query, so this is the only place
+  # that can refuse.
+  def declares!(query, name)
+    declared = begin
+      sole_operation(query)&.name
+    rescue GraphQL::ParseError
+      nil
+    end
+    return query if declared == name
+
+    raise GraphWeaver::Error, "#{@path ? "#{@path}: " : ""}could not name the anonymous operation — " \
+      "the document GraphWeaver would send does not declare #{name.inspect}. Name the operation in " \
+      "the query itself (`query #{name} { ... }`) and please report this as a bug."
+  end
 
-    "#{@query[0, at + keyword.length]} #{name}#{@query[(at + keyword.length)..]}"
+  # load_operation has already refused a document with a second one.
+  def sole_operation(query)
+    GraphQL.parse(query).definitions.grep(GraphQL::Language::Nodes::OperationDefinition).first
   end
 
   # The operation's variables as execute's kwarg surface: one VarDef each,
@@ -365,6 +506,9 @@ class GraphWeaver::Codegen
   # optional kwargs default to nil and are omitted from the wire.
   def build_variables(operation)
     variables = operation.variables.map do |var|
+      @input_from = "$#{var.name}"
+      @input_list = ast_list?(var.type)
+      @input_hops = []
       node = ast_type_ref(var.type)
       required = node.non_null? && var.default_value.nil?
       kwarg = underscore(var.name)
@@ -475,46 +619,95 @@ class GraphWeaver::Codegen
   # "id organization { id }" — flattened to the dotted leaf paths the wire
   # hash needs. The same reading the routing table does of the same syntax,
   # so a supergraph and a subgraph SDL can't disagree about one key.
+  #
+  # Each hop the schema declares as a list is marked: "id lineItems { sku }"
+  # over a `[LineItem!]!` becomes "lineItems[].sku". The runtime builds the
+  # wire representation from these paths and nothing else, so list-ness has
+  # to travel in them — otherwise a list arrives as one object and the
+  # subgraph is asked about an entity that doesn't exist.
   def key_paths(entity, fields)
-    GraphWeaver::SchemaLoader::RoutingTable.parse_field_set(fields)
+    GraphWeaver::SchemaLoader::RoutingTable.parse_field_set(fields).map do |path|
+      mark_lists(entity.graphql_name, path)
+    end
   rescue GraphQL::ParseError => e
     raise GraphWeaver::Error, "#{entity.graphql_name} @key(fields: #{fields.inspect}) isn't a selection set: #{e.message}"
   end
 
+  # A hop the schema doesn't declare is left as written — key_params names
+  # the first of those, and a deeper one is the runtime's to complain about.
+  def mark_lists(type_name, path)
+    path.split(".").map do |segment|
+      field = @schema.get_field(type_name, segment) or next segment
+
+      type_name = field.type.unwrap.graphql_name
+      field.type.list? ? "#{segment}#{GraphWeaver::Representation::LIST_HOP}" : segment
+    end.join(".")
+  end
+
+  # The leaf a nested @key passes through as: an open hash the runtime
+  # narrows to the declared sub-paths, rather than the sig. Identity
+  # everywhere, so `key_node` can wrap it in the same List a scalar leaf gets.
+  class OpaqueHash < Node
+    def bare_type = "T::Hash[T.untyped, T.untyped]"
+    def identity? = true
+    def serialize_identity? = true
+    def hash_coerce_identity? = true
+  end
+  private_constant :OpaqueHash
+
   # 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.
+  # type, a nested one an open Hash whose shape the runtime checks, and a key
+  # field the schema declares as a list takes a list of whichever it is.
   def key_params(entity, key_sets, required:)
-    key_sets.flatten.map { |path| path.split(".").first }.uniq.map do |name|
+    key_sets.flatten.map { |path|
+      path.split(".").first.delete_suffix(GraphWeaver::Representation::LIST_HOP)
+    }.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
-
+      kwarg = key_kwarg(name)
       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 = representation_value(entity, name, kwarg, node)
+      leaf = if core.kind.name == "SCALAR"
+        scalar_node(core.graphql_name, "#{entity.graphql_name}.#{name}")
       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
+        # a nested key set, or an enum one
+        OpaqueHash.new
       end
-
-      RepresentationNode::Param.new(kwarg, name, type, value, required)
+      # the outermost non-null is `required`'s call rather than the SDL's: an
+      # entity with two @keys makes every kwarg optional however it declares
+      # the fields
+      node = key_node(field.type.non_null? ? field.type.of_type : field.type, leaf)
+      type = required ? node.bare_type : node.prop_type
+
+      RepresentationNode::Param.new(kwarg, name, type,
+        representation_value(entity, name, kwarg, node), required)
     end
   end
 
+  # A @key field's list wrappers, rebuilt around its leaf node — `@key(fields:
+  # "id lineItems { sku }")` over a `[LineItem!]!` takes a list of hashes, and
+  # `Representation` walks it to reach the leaf of every element.
+  def key_node(type, leaf)
+    return NonNull.new(key_node(type.of_type, leaf)) if type.non_null?
+    return List.new(key_node(type.of_type, leaf)) if type.list?
+
+    leaf
+  end
+
+  # A @key field's kwarg. The prop rule, plus the one thing a kwarg can't be
+  # that a prop can: a Ruby keyword, since a kwarg is declared and passed
+  # bare. Renaming rather than refusing, because a subgraph's @key field is
+  # even less the user's to rename than a schema's field name — there is no
+  # escape to point them at. The SAME underscore the entity struct's prop
+  # took, or reading `slot.hash_` and writing it back is an ArgumentError.
+  def key_kwarg(name)
+    kwarg = GraphWeaver::Codegen.prop_name(name)
+    RUBY_KEYWORDS.include?(kwarg) ? "#{kwarg}_" : kwarg
+  end
+
   # The kwarg's trip onto the wire — the same normalize-then-serialize an
   # execute kwarg gets (see Emit#variable_serialize), since the builder's sig
   # is `.checked(:never)` too and a representation is built from params just
@@ -528,96 +721,6 @@ class GraphWeaver::Codegen
       "{ |v1| #{inner} }"
   end
 
-  # What a registry's names must be in the schema. extend_type decorates
-  # whatever composite a query reaches, so it demands no particular kind.
-  REGISTERED_KIND = { "scalar" => "SCALAR", "enum" => "ENUM" }.freeze
-  # the type registry is reached via extend_type; scalars/enums via register_*
-  REGISTRATION_METHOD = { "type" => "extend_type", "scalar" => "register_scalar", "enum" => "register_enum" }.freeze
-  private_constant :REGISTERED_KIND, :REGISTRATION_METHOD
-
-  # Every registration this schema can't match, one sentence each. The answer
-  # depends on the schema and the registry alone, not on any one document, so
-  # a whole generate! run gets the same list — which is what lets the build
-  # report it once (see GraphWeaver.unmatched_registrations).
-  #
-  # 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 self.unmatched_registrations(schema)
-    {
-      "enum" => enum_registry,
-      "scalar" => scalar_registry.except(*BUILTIN_SCALARS),
-      "type" => type_registry,
-    }.flat_map do |kind, registry|
-      registry.keys.filter_map { |name| validate_registration!(schema, kind, name) }
-    end
-  end
-
-  # One registry serves the whole graph, but a generation sees one schema — so
-  # a registration fails generation only where THIS schema can disprove it: a
-  # name it declares as something else, or a coordinate whose field it declares
-  # as a composite. A name it can't match at all proves nothing, because an
-  # entity type is declared by every subgraph that references it while its
-  # fields are split among them; that returns the sentence to say instead.
-  def self.validate_registration!(schema, kind, name)
-    method = REGISTRATION_METHOD.fetch(kind)
-    # register_scalar("Type.field", ...) overrides one field's scalar — validate
-    # the field, not that a type named "Type.field" exists.
-    return validate_scalar_field!(schema, name, method) if kind == "scalar" && name.include?(".")
-
-    type = schema.get_type(name)
-    return unmatched(schema, method, name, kind, GraphWeaver::Internal::Util.did_you_mean(schema.types.keys, name)) unless type
-
-    expected = REGISTERED_KIND[kind]
-    return if expected.nil? || type.kind.name == expected
-
-    found = type.kind.name.downcase.tr("_", " ")
-    # a leaf registered as the other kind has a method that would have worked
-    other = REGISTERED_KIND.key(type.kind.name)
-    raise GraphWeaver::Error,
-      "#{method}(#{name.inspect}) names #{article(found)} #{found}, not #{article(kind)} " \
-      "#{kind}#{other ? " — use #{REGISTRATION_METHOD.fetch(other)}" : ""}"
-  end
-  private_class_method :validate_registration!
-
-  # A per-field override, register_scalar("Type.field", ...). Neither an absent
-  # type nor an absent field is disprovable here; what is, is a field this
-  # schema declares as something a scalar codec could never read.
-  def self.validate_scalar_field!(schema, name, method)
-    type_name, field_name = name.split(".", 2)
-    type = schema.get_type(type_name)
-    unless type
-      near = GraphWeaver::Internal::Util.did_you_mean(schema.types.keys, type_name)
-      return unmatched(schema, method, name, "scalar field", near && "#{near}.#{field_name}")
-    end
-
-    fields = type.respond_to?(:fields) ? type.fields : {}
-    field = fields[field_name]
-    unless field
-      near = GraphWeaver::Internal::Util.did_you_mean(fields.keys, field_name)
-      return unmatched(schema, method, name, "scalar field", near && "#{type_name}.#{near}")
-    end
-    return if field.type.unwrap.kind.name == "SCALAR"
-
-    raise GraphWeaver::Error,
-      "#{method}(#{name.inspect}): #{name} isn't a scalar field (it's #{field.type.unwrap.kind.name.downcase})"
-  end
-  private_class_method :validate_scalar_field!
-
-  # What to say about a name this schema has nothing for. Registrations are
-  # graph-scoped — federation composes by name, so one `Money` codec serves
-  # every subgraph that declares it — which is exactly why this schema can't
-  # tell a typo from a registration for the subgraph next door. Say both.
-  def self.unmatched(schema, method, name, what, suggestion)
-    hint = suggestion ? " (did you mean '#{suggestion}'?)" : ""
-    "#{method}(#{name.inspect}) matches no #{what} in #{schema.name || "this schema"} " \
-      "— a typo#{hint}, or a registration for another schema"
-  end
-  private_class_method :unmatched
-
-  def self.article(word) = word.downcase.start_with?(/[aeiou]/) ? "an" : "a"
-  private_class_method :article
-
   # Parse every fragment file under `paths` into one { name => FragmentDefinition }
   # map — reusable fragments a query can spread. Fragment files hold only
   # fragments (no operations); names are unique across them.
@@ -664,7 +767,7 @@ class GraphWeaver::Codegen
     GraphQL.parse(query)
   rescue GraphQL::ParseError => e
     prefix = [path && GraphWeaver::Internal::Util.relative(path), e.line, e.col].compact.join(":")
-    raise GraphWeaver::ValidationError.new(
+    raise GraphWeaver::QueryValidationError.new(
       [{ message: prefix.empty? ? e.message : "#{prefix} #{e.message}", line: e.line, column: e.col }],
     )
   end
@@ -705,14 +808,32 @@ class GraphWeaver::Codegen
   end
   private_class_method :fragment_spreads
 
+  # @defer/@stream deliver the answer in instalments over a multipart body,
+  # and generated code reads one JSON response — so there is nothing to
+  # generate, whether or not the schema in hand declares the directives.
+  # Above validation because most schemas don't: "Directive @defer is not
+  # defined" reads like a typo, and it stops being raised at all the day a
+  # supergraph @links the defer spec.
+  def refuse_incremental!(document)
+    node = GraphWeaver::Internal::Selection.incremental_directive(document) or return
+
+    raise GraphWeaver::QueryValidationError.new([detail(
+      "this query carries @#{node.name}, and the answer would arrive in more than one payload " \
+      "(incremental delivery) — generated code reads a single JSON response, so drop the " \
+      "directive or move those selections into their own query",
+      node.line, node.col,
+    )])
+  end
+  private :refuse_incremental!
+
   # Structured shape for a schema-validation error: message plus its first
-  # source location, so ValidationError#errors is inspectable.
+  # source location, so QueryValidationError#errors is inspectable.
   def validation_detail(error)
     loc = (error.to_h["locations"]&.first if error.respond_to?(:to_h))
     detail(error.message, loc && loc["line"], loc && loc["column"])
   end
 
-  # One ValidationError entry, its message prefixed "file:line:col" like a
+  # One QueryValidationError 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)
@@ -725,7 +846,7 @@ class GraphWeaver::Codegen
   # The build channel prints the same list once per run; see
   # GraphWeaver.unmatched_registrations.
   def validate_registrations!
-    self.class.unmatched_registrations(@schema).each { |message| GraphWeaver::Internal::Log.log(:warn) { message } }
+    @registry.unmatched_registrations(@schema).each { |message| GraphWeaver::Internal::Log.log(:warn) { message } }
   end
 
   # The @include/@skip a fragment carries applies to what it guards, so it has
@@ -755,7 +876,9 @@ class GraphWeaver::Codegen
     node = ObjectNode.new(class_name)
     node.graphql_type = type.graphql_name
     node.mixins = type_mixins(type.graphql_name)
-    taken = [class_name]
+    # class name => the result key that claimed it; the struct itself first,
+    # claimed by nothing (see pick_name)
+    taken = { class_name => nil }
     # Dedup structurally-identical dispatch-union fields on this struct: the
     # same union selected two ways (unblockOptions vs selectedOption) shares
     # one Ruby type, so consumers get one exhaustive `case ... T.absurd`.
@@ -765,7 +888,7 @@ class GraphWeaver::Codegen
     gather_conditional(type, selections).each do |key, occurrences|
       field_nodes = occurrences.map(&:first)
       field_name = field_nodes.first.name
-      prop = underscore(key)
+      prop = GraphWeaver::Codegen.prop_name(key)
       check_output_prop!(type, key, prop, props)
 
       child = if field_name == "__typename"
@@ -867,7 +990,7 @@ class GraphWeaver::Codegen
   def check_shadowing!(node, scope = {})
     case node
     when UnionNode
-      members = node.members.each_value.to_a + [node.catch_all].compact
+      members = node.members.each_value.to_a + [node.catch_all]
       inner = scope.merge(members.to_h { |m| [m.class_name, "the member struct #{m.class_name}"] })
       members.each { |member| check_shadowing!(member, inner) }
     when ObjectNode
@@ -920,20 +1043,12 @@ class GraphWeaver::Codegen
     node
   end
 
-  # 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.
+  # The one way a result key can still fail to become a prop: a second key that
+  # underscores onto an earlier one. That emits a struct that misbehaves (an
+  # ArgumentError at require time), so refuse here; an alias in the query fixes
+  # it. A reserved name doesn't get here — prop_name renames it. `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
-
     if (earlier = props[prop])
       raise GraphWeaver::Error,
         "result keys #{earlier.inspect} and #{key.inspect} on #{type.graphql_name} both map to the " \
@@ -1032,18 +1147,35 @@ class GraphWeaver::Codegen
   # 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 dispatchable_typename?(type, selections)
-      raise ArgumentError,
-        "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
+    raise ArgumentError, typename_refusal(type, selections) unless dispatchable_typename?(type, selections)
 
     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
 
+  # Why a selection can't dispatch. The near miss is worth its own sentence:
+  # putting __typename in every `... on Type` and nowhere else looks like
+  # compliance — it is what Linear's published SDK documents do — and the tag
+  # really is on the wire, but from_h reads it before it knows which member is
+  # live, and a member the query never named would carry none at all.
+  def typename_refusal(type, selections)
+    base = "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)"
+    return base unless member_typename?(type, selections)
+
+    "#{base}. The __typename in each `... on Type` here is read only after the dispatch it " \
+      "would decide, so it can't stand in for one on #{type.graphql_name} itself"
+  end
+
+  # Does every member the selection names carry its own unconditional
+  # __typename? Asked only to explain a refusal, never to permit one.
+  def member_typename?(type, selections)
+    members = selected_members(type, selections).to_a
+    members.any? && members.all? { |member| dispatchable_typename?(member, selections) }
+  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
@@ -1127,9 +1259,9 @@ class GraphWeaver::Codegen
 
   # 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, catch_all = nil)
+  def union_signature(members, catch_all)
     parts = members.map { |gname, member| "#{gname}=#{signature(member)}" }
-    parts << "*=#{signature(catch_all)}" if catch_all
+    parts << "*=#{signature(catch_all)}"
     parts.sort.join(",")
   end
 
@@ -1191,28 +1323,101 @@ class GraphWeaver::Codegen
   def input_node(core)
     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))
+    class_name = camelize(core.graphql_name)
+    # enum_node's twin. Without it `class Result` was emitted twice, the second
+    # reopening the first into one struct answering for both the variable and
+    # the response — and `class QUERY` raised a bare TypeError about the heredoc.
+    if MODULE_RESERVED.include?(class_name)
+      raise GraphWeaver::Error,
+        "input type #{core.graphql_name} generates #{class_name}, which collides with a generated " \
+        "constant — every query module defines #{MODULE_RESERVED.to_a.join(", ")}, so an input type " \
+        "by one of those names has no room here"
+    end
+
+    node = @variable_inputs[core.graphql_name] = InputNode.new(class_name, 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)
       # 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 a method every struct defines"
-      end
-
+      prop = GraphWeaver::Codegen.prop_name(argument.graphql_name)
+      @input_hops.push(InputHop.new(argument.graphql_name, list_type?(argument.type)))
       child = type_ref(argument.type) { variable_core(argument.type.unwrap) }
+      @input_hops.pop
       required = child.non_null? && !argument.default_value?
       node.fields << InputNode::Field.new(prop, argument.graphql_name, child, required)
     end
+    check_input_props!(core, node)
     node
   end
 
+  # check_output_prop!'s twin: two input fields that underscore onto one prop
+  # emit `const :x` twice, which raises ArgumentError when the generated file
+  # is REQUIRED — a stack trace with no schema in it. A schema's field name
+  # isn't the user's to rename and an input struct has no alias, so the fix is
+  # to keep the type out of the variables.
+  def check_input_props!(core, node)
+    collision = node.fields.group_by(&:prop).find { |_, group| group.size > 1 }
+    return unless collision
+
+    fields = collision.last.map { |field| field.wire.inspect }.join(" and ")
+    raise GraphWeaver::Error,
+      "input fields #{fields} on #{core.graphql_name} both map to the prop " \
+      "'#{collision.first}' — #{input_collision_advice(core)}"
+  end
+
+  # One hop of the input walk: the field taken, and whether taking it crosses
+  # a list.
+  InputHop = Struct.new(:name, :list)
+  private_constant :InputHop
+
+  def list_type?(type)
+    type = type.of_type if type.kind.name == "NON_NULL"
+    type.kind.name == "LIST"
+  end
+
+  # What to do about an input collision, said in terms of the declaration the
+  # user wrote: the colliding type is usually several hops below it, and
+  # naming the type alone sends them looking for a variable they never
+  # declared. The escape — inline the path as a literal, keeping a variable
+  # per leaf — exists only when no hop crosses a list, since a literal list
+  # can't stand in for a length only the runtime knows.
+  def input_collision_advice(core)
+    from = @input_from || "a variable that reaches it"
+    path = @input_hops.map(&:name).join(".")
+    crossed = @input_hops.find(&:list)
+
+    if crossed || @input_list
+      blocked =
+        if crossed
+          "#{from} reaches #{core.graphql_name} through #{path}, and #{crossed.name} is a list"
+        else
+          "#{from} is declared as a list of #{core.graphql_name}"
+        end
+      return "#{blocked} — a literal list can't stand in for a length only the runtime knows, so " \
+        "no form of this query generates. Keep #{core.graphql_name} out of the variables."
+    end
+
+    if @input_hops.any?
+      return "#{from} reaches #{core.graphql_name} through #{path} — drop #{from} and write that " \
+        "path as a literal in the query, with a variable per field of #{core.graphql_name}"
+    end
+
+    "pass #{core.graphql_name} as a literal in the query, with a variable per field, instead of " \
+      "declaring #{from}"
+  end
+
+  # Does this AST type reference cross a list on its way to the core type?
+  def ast_list?(ast_type)
+    case ast_type
+    when GraphQL::Language::Nodes::ListType then true
+    when GraphQL::Language::Nodes::NonNullType then ast_list?(ast_type.of_type)
+    else false
+    end
+  end
+
   # 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)
@@ -1255,7 +1460,7 @@ class GraphWeaver::Codegen
 
   # Registered helper-module names for a GraphQL type, collecting their requires.
   def type_mixins(graphql_name)
-    entry = GraphWeaver::Codegen.type_registry[graphql_name]
+    entry = @registry.type_registry[graphql_name]
     return [] unless entry
 
     @requires.concat(entry[:requires])
@@ -1265,7 +1470,7 @@ class GraphWeaver::Codegen
   # The MappedEnum node for a schema enum with a registered app-enum
   # mapping; nil when unregistered, falling back to a generated T::Enum.
   def mapped_enum_node(core)
-    enum_type = GraphWeaver::Codegen.enum_registry[core.graphql_name]
+    enum_type = @registry.enum_registry[core.graphql_name]
     return unless enum_type
 
     @requires.concat(enum_type.requires)
@@ -1277,9 +1482,9 @@ class GraphWeaver::Codegen
   # Resolution, most specific first: a per-field override (`Type.field`), then
   # the scalar-name registration.
   def scalar_node(name, coordinate = nil, result: false)
-    registry = GraphWeaver::Codegen.scalar_registry
-    @untyped_scalars << name.to_s unless (coordinate && registry[coordinate]) || registry[name.to_s]
-    scalar = GraphWeaver::Codegen.scalar(name, coordinate)
+    scalars = @registry.scalar_registry
+    @untyped_scalars << name.to_s unless (coordinate && scalars[coordinate]) || scalars[name.to_s]
+    scalar = @registry.scalar(name, coordinate)
     refuse_uncastable!(scalar, coordinate || name) if result
     @requires.concat(scalar.requires)
     Scalar.new(scalar)
@@ -1296,11 +1501,9 @@ class GraphWeaver::Codegen
     klass = Object.const_get(scalar.type)
     return unless klass.is_a?(Class) && ScalarType::WIRE_CLASSES.none? { |native| native <= klass }
 
-    raise GraphWeaver::Error,
-      "register_scalar(#{scalar.graphql_name.inspect}, #{scalar.type}) has no cast, so nothing " \
-      "builds a #{scalar.type} out of the JSON at #{where} — give it one (cast: :parse names a " \
-      "class method, cast: ->(v) { \"#{scalar.type}(\#{v})\" } emits any expression), or register " \
-      "a type the wire already parses into"
+    # why there is no cast — and so what to do — is the registration's own
+    # knowledge, not the walk's
+    raise GraphWeaver::Error, scalar.uncastable_message(where)
   rescue ::NameError
     nil # a type: given as a String names a class this process may not have
   end
@@ -1308,14 +1511,15 @@ class GraphWeaver::Codegen
   # 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.
+  # silent. Informational: not a warning, never an error. The logger is the
+  # runtime channel, so a console `parse` says it too; the build channel prints
+  # the same list once per run (see GraphWeaver.untyped_scalars).
   def report_untyped_scalars
-    names = @untyped_scalars.uniq.sort
+    names = untyped_scalars
     return if names.empty?
 
     GraphWeaver::Internal::Log.log(:info) do
-      "#{names.size} unregistered custom scalar#{"s" unless names.one?} → T.untyped: " \
-        "#{names.join(", ")} (register with GraphWeaver.register_scalar)"
+      GraphWeaver::Internal::Util.untyped_scalars_report(@graph_name => names)
     end
   end
 
@@ -1336,12 +1540,14 @@ class GraphWeaver::Codegen
   # 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.
+  # struct's scope => the key that claimed each, its first entry the struct
+  # itself (claimed by nothing) — the key is what a collision has to name.
   #
   # (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)
+    struct = taken.keys.first
 
     # a key that camelizes to no constant at all ("_", "_1") would emit
     # `class  < T::Struct`
@@ -1350,18 +1556,19 @@ class GraphWeaver::Codegen
         "result key #{key.inspect} makes no class name (#{name.inspect}) — alias it to one starting with a letter"
     end
 
-    if name == taken.first
+    if name == struct
       # 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}")
+      suffix += 1 while taken.key?("#{name}#{suffix}")
       name = "#{name}#{suffix}"
-    elsif taken.include?(name)
+    elsif (earlier = taken[name])
       raise GraphWeaver::Error,
-        "result keys on #{taken.first} both generate the class #{name} — alias one to a distinct name"
+        "result keys #{earlier.inspect} and #{key.inspect} on #{struct} both generate the class " \
+        "#{name} — alias one to a distinct name"
     end
 
-    taken << name
+    taken[name] = key
     name
   end