graph_weaver 0.5.1 → 0.6.0

data/lib/graph_weaver/codegen.rb

@@ -20,12 +20,13 @@ require "sorbet-runtime"
 # registry), codegen/nodes.rb (the typed IR), codegen/aliases.rb (resolving
 # registered alias paths against a node), codegen/emit.rb (source emission);
 # this file holds the public API and the query walk.
+require_relative "internal"
 require_relative "hints"
 require_relative "input_struct"
 require_relative "schema_loader"
 require_relative "representation"
 require_relative "inflect"
-require_relative "selection"
+require_relative "internal/selection"
 require_relative "codegen/enum_type"
 require_relative "codegen/scalar_type"
 require_relative "codegen/nodes"
@@ -34,9 +35,11 @@ require_relative "codegen/emit"
 
 class GraphWeaver::Codegen
   include GraphWeaver::Inflect
-  include GraphWeaver::Selection
+  include GraphWeaver::Internal::Selection
   include Aliases
   include Emit
+  # the walk's two halves, split for file size rather than for reuse
+  private_constant :Aliases, :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
@@ -50,7 +53,7 @@ class GraphWeaver::Codegen
     "run; register from a Rails.application.config.to_prepare block, which generation " \
     "also runs first."
 
-  attr_reader :module_name
+  attr_reader :name
 
   # A client is anything responding to `execute(query, variables:)`
   # whose result `to_h`s into {"data" => ..., "errors" => ...} — a
@@ -58,11 +61,10 @@ 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=). module_name:
-  # defaults to the operation's
-  # name; default_module_name: is parse's container-scoped fallback (file
-  # generation stays strict — a checked-in file deserves a deliberate
-  # name). types_namespace: is the shared-types workflow (see
+  # the app default (GraphWeaver.client=). 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
   # 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
@@ -70,19 +72,21 @@ class GraphWeaver::Codegen
   # 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,
-    types_namespace: nil, hoistable_unions: nil, path: nil)
+  def initialize(schema:, query:, name: nil, client: nil, default_name: nil,
+    types_namespace: nil, hoistable_unions: nil, path: nil, module_name: nil)
+    renamed!(module_name)
     @schema = schema
     @query = query.strip
-    @path = path
-    @module_name = module_name
-    @default_module_name = default_module_name
+    # only ever quoted in a message, so it is stored the way it is reported
+    @path = path && GraphWeaver::Internal::Util.relative(path)
+    @name = name
+    @default_name = default_name
     @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)
+    @client_const = CLIENT_CONST.call(client)
 
     if client && @client_const.nil?
       # a live object can't be spelled in generated source — parse can
@@ -91,18 +95,30 @@ class GraphWeaver::Codegen
     end
   end
 
+  # 0.5 spelled it module_name:, in two of the three doors. One knob, one
+  # spelling — but a silent "unknown keyword" would send the caller hunting.
+  def renamed!(module_name)
+    return unless module_name
+
+    raise ArgumentError, "module_name: is now name: (got #{module_name.inspect})"
+  end
+  private :renamed!
+
   # The constant name a client can be referenced by in generated
   # source — nil when it can't be (live objects, anonymous modules).
-  def self.client_const(client)
+  # A lambda rather than a method: both `parse` and `initialize` need it,
+  # from the class and from an instance.
+  CLIENT_CONST = lambda do |client|
     case client
     when String then client
     when Module then client.name
     end
   end
+  private_constant :CLIENT_CONST
 
   # one-step shorthand
-  def self.generate(schema:, query:, module_name: nil, client: nil, path: nil)
-    new(schema:, query:, module_name:, client:, path:).generate
+  def self.generate(schema:, query:, name: nil, client: nil, path: nil, module_name: nil)
+    new(schema:, query:, name:, client:, path:, module_name:).generate
   end
 
   # Development convenience: generate + eval in one step, no build
@@ -110,17 +126,22 @@ 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, path: nil)
-    client_const = client_const(client)
+  def self.parse(schema:, query:, name: nil, client: nil, path: nil, module_name: nil)
+    client_const = CLIENT_CONST.call(client)
 
-    codegen = new(schema:, query:, module_name:, client: client_const, path:,
-      default_module_name: "Query")
+    codegen = new(schema:, query:, name:, client: client_const, path:, module_name:,
+      default_name: "Query")
     source = codegen.generate
 
     container = Module.new
+    # otherwise every runtime error names the container by address
+    # ("#<Module:0x...>::Result::Person"); assigning the module to a constant,
+    # which is the documented usage, replaces this with the real path
+    # T.unsafe: sorbet's Module RBI predates set_temporary_name (Ruby 3.3)
+    T.unsafe(container).set_temporary_name("GraphWeaver.parse")
     container.module_eval(source, "(graph_weaver)", 1)
-    mod = container.const_get(codegen.module_name)
-    GraphWeaver.log(:debug) { "parsed #{codegen.module_name} (dynamic module, #{source.bytesize} bytes)" }
+    mod = container.const_get(codegen.name)
+    GraphWeaver::Internal::Log.log(:debug) { "parsed #{codegen.name} (dynamic module, #{source.bytesize} bytes)" }
     # live objects (or anonymous modules) can't be referenced from
     # generated source — set them via the module's writer instead
     mod.client = client if client && client_const.nil?
@@ -178,6 +199,7 @@ class GraphWeaver::Codegen
     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)
+    union_nodes.each { |union| check_shadowing!(union) }
 
     emit_types_files(union_nodes).tap { report_untyped_scalars }
   end
@@ -185,6 +207,7 @@ class GraphWeaver::Codegen
   # 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
+  private_constant :MODULE_RESERVED
 
   # One hoisted shared fragment, built against the schema and named for the
   # fragment rather than the field that spread it.
@@ -220,7 +243,7 @@ class GraphWeaver::Codegen
       claim = taken[class_name] or next
 
       raise GraphWeaver::Error,
-        "shared fragment #{name.inspect} hoists to #{@module_name}::#{class_name}, " \
+        "shared fragment #{name.inspect} hoists to #{@name}::#{class_name}, " \
         "where #{claim} already generates — rename the fragment"
     end
   end
@@ -242,10 +265,10 @@ class GraphWeaver::Codegen
   CONSTANT_NAME = /\A[A-Z]\w*(::[A-Z]\w*)*\z/
 
   def validate_module_name!(subject)
-    return if @module_name&.match?(CONSTANT_NAME)
+    return if @name&.match?(CONSTANT_NAME)
 
-    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
+    problem = "#{subject} must be a constant name, got #{@name.inspect}"
+    # An explicit 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
@@ -258,6 +281,7 @@ class GraphWeaver::Codegen
   private :validate_module_name!
 
   VarDef = Struct.new(:kwarg, :wire, :node, :required)
+  private_constant :VarDef
 
   # 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
@@ -280,6 +304,7 @@ class GraphWeaver::Codegen
   # 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
 
   def generate
     begin
@@ -299,21 +324,22 @@ class GraphWeaver::Codegen
     operation = load_operation(@query)
     root_type = operation_root_type(operation)
 
-    @module_name ||= operation.name || @default_module_name
-    unless @module_name
-      raise ArgumentError, "module_name: required for anonymous operations"
+    @name ||= operation.name || @default_name
+    unless @name
+      raise ArgumentError, "name: required for anonymous operations"
     end
 
-    validate_module_name!("module_name:")
+    validate_module_name!("name:")
 
     variables = build_variables(operation)
     root = object_node(root_type, operation.selections, "Result")
+    check_shadowing!(root)
 
     # 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
+    operation_name = operation.name || @name.split("::").last
     @query = declare_operation_name(operation, operation_name) unless operation.name
 
     emit_module(root, variables, representation_nodes(operation, root_type), operation_name)
@@ -405,6 +431,7 @@ class GraphWeaver::Codegen
   # The subgraph spec's representation scalar. A field taking one is the
   # entity resolver, whatever it's called.
   REPRESENTATION_SCALAR = "_Any"
+  private_constant :REPRESENTATION_SCALAR
 
   def representation_field?(definition)
     definition.arguments.each_value.any? { |argument| argument.type.unwrap.graphql_name == REPRESENTATION_SCALAR }
@@ -475,7 +502,7 @@ class GraphWeaver::Codegen
       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)} }"
+        value = representation_value(entity, name, kwarg, node)
       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
@@ -488,38 +515,108 @@ class GraphWeaver::Codegen
     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.
+  # 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
+  # as often. Identity both ways emits the bare kwarg.
+  def representation_value(entity, name, kwarg, node)
+    return kwarg if !node.coerce? && node.serialize_identity?
+
+    inner = node.coerce? ? node.coerce("v1") : "v1"
+    inner = node.serialize(inner, 2) unless node.serialize_identity?
+    "GraphWeaver::Representation.field(#{entity.graphql_name.inspect}, #{name.inspect}, #{kwarg}) " \
+      "{ |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 exists and is a scalar, not that a type named "Type.field" exists.
-    if kind == "scalar" && name.include?(".")
-      return if scalar_field?(schema, name)
+    # the field, not that a type named "Type.field" exists.
+    return validate_scalar_field!(schema, name, method) if kind == "scalar" && name.include?(".")
 
-      raise GraphWeaver::Error, "register_scalar(#{name.inspect}) matches no scalar field in this schema"
-    end
+    type = schema.get_type(name)
+    return unmatched(schema, method, name, kind, GraphWeaver::Internal::Util.did_you_mean(schema.types.keys, name)) unless type
 
-    return if schema.get_type(name)
+    expected = REGISTERED_KIND[kind]
+    return if expected.nil? || type.kind.name == expected
 
-    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}"
-    raise GraphWeaver::Error, "#{method}(#{name.inspect}) matches no type in this schema#{hint}"
+    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
 
-  # Whether `coordinate` ("Type.field") names an existing scalar field — the
-  # validation for a per-field register_scalar override.
-  def self.scalar_field?(schema, coordinate)
-    type_name, field_name = coordinate.split(".", 2)
-    return false unless field_name
+    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"
 
-    field = schema.get_field(type_name, field_name)
-    !!field && field.type.unwrap.kind.name == "SCALAR"
-  rescue StandardError
-    false
+    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
@@ -527,17 +624,18 @@ class GraphWeaver::Codegen
   def self.load_fragments(paths)
     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|
+    GraphWeaver::Internal::Util.query_files(paths).each_with_object({}) do |file, out|
       doc = parse_document(File.read(file), file)
+      reported = GraphWeaver::Internal::Util.relative(file)
       if doc.definitions.grep(GraphQL::Language::Nodes::OperationDefinition).any?
-        raise GraphWeaver::Error, "#{file}: fragment files define only fragments, no operations"
+        raise GraphWeaver::Error, "#{reported}: fragment files define only fragments, no operations"
       end
       doc.definitions.grep(GraphQL::Language::Nodes::FragmentDefinition).each do |frag|
         if (earlier = source[frag.name])
           raise GraphWeaver::Error,
-            "duplicate shared fragment '#{frag.name}' — defined in #{earlier} and #{file}; rename one"
+            "duplicate shared fragment '#{frag.name}' — defined in #{earlier} and #{reported}; rename one"
         end
-        source[frag.name] = file
+        source[frag.name] = reported
         out[frag.name] = frag
       end
     end
@@ -565,11 +663,12 @@ class GraphWeaver::Codegen
   def self.parse_document(query, path = nil)
     GraphQL.parse(query)
   rescue GraphQL::ParseError => e
-    prefix = [path, e.line, e.col].compact.join(":")
+    prefix = [path && GraphWeaver::Internal::Util.relative(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
+  private_class_method :parse_document
 
   # Append the shared fragments a query spreads (transitively) to its source, so
   # the sent query is self-contained. Unused shared fragments are left out.
@@ -621,17 +720,12 @@ class GraphWeaver::Codegen
     { 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.
+  # Raises on the registrations this schema disproves, and narrates the rest
+  # on the logger — the runtime channel, so a console `parse` says it too.
+  # The build channel prints the same list once per run; see
+  # GraphWeaver.unmatched_registrations.
   def validate_registrations!
-    {
-      "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
+    self.class.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
@@ -686,7 +780,7 @@ class GraphWeaver::Codegen
           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"]
+          shared = abstract_level_fields(core, sub_selections)
 
           if conditions.empty?
             # abstract-level fields only — every member shares them, so one
@@ -694,7 +788,7 @@ class GraphWeaver::Codegen
             # 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? &&
+          elsif conditions.size == 1 && shared.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).
@@ -742,7 +836,7 @@ class GraphWeaver::Codegen
           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) }
+          type_ref(field_type) { scalar_node(core.graphql_name, coordinate, result: true) }
         else
           raise GraphWeaver::Error, "unsupported kind: #{core.kind.name}"
         end
@@ -763,6 +857,69 @@ class GraphWeaver::Codegen
     node
   end
 
+  # A generated class name is only ever a name; Ruby resolves it lexically. So
+  # a struct nesting `class Date < T::Struct` (from a result key `date`) turns
+  # a sibling `Date` scalar prop into that struct, and `Date.iso8601` into a
+  # NoMethodError — the file typechecks against itself and means something
+  # else. Refuse instead, naming both keys: aliasing either one in the query
+  # fixes it. `scope` is what enclosing structs have already introduced, since
+  # a nested class shadows for everything lexically inside it too.
+  def check_shadowing!(node, scope = {})
+    case node
+    when UnionNode
+      members = node.members.each_value.to_a + [node.catch_all].compact
+      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
+      nested = node.fields.filter_map { |field|
+        child = field.node.nested
+        [child, field.key] if child && !module_level?(child)
+      }.uniq(&:first)
+      inner = scope.merge(nested.to_h { |child, key| [child.class_name, "the class result key #{key.inspect} generates"] })
+
+      external_constants(node).each do |name, source|
+        shadow = inner[name] or next
+
+        raise GraphWeaver::Error,
+          "#{source} resolves to #{name}, but #{shadow} is also named #{name} and shadows it " \
+          "inside #{node.class_name} — alias one in the query to a distinct name"
+      end
+
+      nested.each { |child, _| check_shadowing!(child, inner) }
+    end
+  end
+
+  # Constants a struct's body names but doesn't define: the runtimes it always
+  # mentions, a registered scalar's Ruby type, a module-level enum, a hoisted
+  # union's alias, an extend_type mixin. Keyed by the constant's first segment,
+  # which is all Ruby resolves — `Money::Amount` goes through `Money`.
+  def external_constants(node)
+    refs = { "T" => "the Sorbet runtime", "GraphWeaver" => "the GraphWeaver runtime" }
+    node.mixins.each { |mixin| refs[root_constant(mixin)] ||= "the mixin #{mixin} registered with extend_type" }
+
+    node.fields.each do |field|
+      child = field.node.nested
+      name = if child
+        next unless module_level?(child)
+
+        child.class_name
+      else
+        root_constant(unwrapped(field.node).bare_type)
+      end
+      refs[name] ||= "result key #{field.key.inspect}"
+    end
+    refs
+  end
+
+  def root_constant(name) = name[/\A[A-Za-z_]\w*/]
+
+  # a leaf node with its NON_NULL/LIST wrappers removed
+  def unwrapped(node)
+    node = T.let(node, T.untyped)
+    node = node.of while node.is_a?(NonNull) || node.is_a?(List)
+    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
@@ -806,9 +963,19 @@ class GraphWeaver::Codegen
     end.compact.uniq - [core.graphql_name]
   end
 
-  # result keys selected as plain fields (outside any type condition)
-  def bare_fields(selections)
-    selections.grep(GraphQL::Language::Nodes::Field).map { |field| field.alias || field.name }
+  # Result keys the abstract type itself answers — every member carries them,
+  # so their presence rules out narrowing to one. Walked as the type sees it,
+  # not read off the top level: `... on Named { name }` under a Named field is
+  # the same selection as a bare `name`, and treating it as a type condition
+  # would narrow the field away and drop what the server sent for every other
+  # member. `__typename` is excluded — it's the dispatch tag, not a field.
+  def abstract_level_fields(core, selections)
+    keys = gather_conditional(core, selections).keys
+    # __typename is the dispatch tag rather than a field — but only where it can
+    # actually be read. One behind @skip/@include still arrives for the member a
+    # narrowing means to filter out, and then the object isn't empty and
+    # "empty means no match" casts a Review into an Announcement.
+    dispatchable_typename?(core, selections) ? keys - ["__typename"] : keys
   end
 
   # The fragment name when a selection is exactly one bare fragment spread
@@ -1065,6 +1232,16 @@ class GraphWeaver::Codegen
   # ("Enum values must be assigned to constants") — catch it here instead.
   def enum_values(core)
     values = core.values.keys.sort
+    # `_` and `__` are legal GraphQL enum values and camelize to nothing, so
+    # the emitted `= new("_")` isn't even parseable — the file fails at load
+    # with a syntax error pointing into generated source
+    nameless = values.find { |value| !camelize(value.downcase).match?(/\A[A-Z]/) }
+    if nameless
+      raise GraphWeaver::Error,
+        "enum #{core.graphql_name} value #{nameless} makes no constant name — map the enum onto " \
+        "one of yours: register_enum(#{core.graphql_name.inspect}, YourEnum)"
+    end
+
     collision = values.group_by { |value| camelize(value.downcase) }.find { |_, group| group.size > 1 }
     if collision
       raise GraphWeaver::Error,
@@ -1099,17 +1276,40 @@ class GraphWeaver::Codegen
   # 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.
-  def scalar_node(name, coordinate = nil)
+  def scalar_node(name, coordinate = nil, result: false)
     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
+    @untyped_scalars << name.to_s unless (coordinate && registry[coordinate]) || registry[name.to_s]
+    scalar = GraphWeaver::Codegen.scalar(name, coordinate)
+    refuse_uncastable!(scalar, coordinate || name) if result
     @requires.concat(scalar.requires)
     Scalar.new(scalar)
   end
 
+  # Everything JSON.parse can hand back. A registered type outside this set
+  # has to be BUILT from one of them, which is what cast: is for.
+  WIRE_CLASSES = [String, Integer, Float, Hash, Array, TrueClass, FalseClass].freeze
+  private_constant :WIRE_CLASSES
+
+  # A registered type nothing on the wire can be, with no cast to build one:
+  # the prop is unsatisfiable, so every response fails — at runtime, a long
+  # way from the registration that caused it. BigDecimal is the one people
+  # reach for (it defines neither .parse nor .load, so inference finds no
+  # codec and leaves the value untouched).
+  def refuse_uncastable!(scalar, where)
+    return if scalar.cast?
+
+    klass = Object.const_get(scalar.type)
+    return unless klass.is_a?(Class) && 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"
+  rescue ::NameError
+    nil # a type: given as a String names a class this process may not have
+  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
@@ -1118,7 +1318,7 @@ class GraphWeaver::Codegen
     names = @untyped_scalars.uniq.sort
     return if names.empty?
 
-    GraphWeaver.log(:info) do
+    GraphWeaver::Internal::Log.log(:info) do
       "#{names.size} unregistered custom scalar#{"s" unless names.one?} → T.untyped: " \
         "#{names.join(", ")} (register with GraphWeaver.register_scalar)"
     end