graph_weaver 0.3.0 → 0.4.4

data/lib/graph_weaver/codegen/emit.rb

@@ -115,10 +115,10 @@ class GraphWeaver::Codegen
         names.uniq
       end
 
-      def emit_shared_aliases(out, names)
+      def emit_shared_aliases(out, names, namespace = @inputs_namespace)
         return if names.empty?
 
-        names.each { |name| out << "  #{name} = #{@inputs_namespace}::#{name}" }
+        names.each { |name| out << "  #{name} = #{namespace}::#{name}" }
         out << ""
       end
 
@@ -175,6 +175,35 @@ class GraphWeaver::Codegen
         files
       end
 
+      # The shared unions artifact as a single file: every hoisted union as a
+      # <module_name>::<Name> module. Unions don't cross-reference (each is a
+      # self-contained fragment), so there's no need for per-type files or the
+      # forward declarations recursive input types require.
+      def emit_unions_file(unions)
+        out = []
+        out << "# typed: strict"
+        out << "# frozen_string_literal: true"
+        out << ""
+        out << "# Generated by GraphWeaver — do not edit. Shared union types for this"
+        out << "# schema (named fragments on union fields); query modules alias what they use."
+        out << ""
+        requires = @requires.uniq.sort
+        if requires.any?
+          requires.each { |req| out << "require #{req.inspect}" }
+          out << ""
+        end
+        out << "module #{@module_name}"
+        out << "  extend T::Sig" << "" if GraphWeaver.extend_t_sig?
+        unions.each do |union|
+          emit_union(union, out, 1)
+          out << ""
+        end
+        out.pop if out.last == ""
+        out << "end"
+
+        { "unions.rb" => out.join("\n") + "\n" }
+      end
+
       # one type per file, wrapped in the namespace so bare sibling
       # references resolve lexically
       def inputs_file(files, name)
@@ -200,6 +229,9 @@ class GraphWeaver::Codegen
     def emit_module(root, variables)
       flatten = flatten_input(variables)
       aliases = @inputs_namespace ? shared_alias_names(variables, flatten) : []
+      # hoisted unions the result tree references, aliased so <Name>::Type and
+      # <Name>.from_h resolve to the shared module
+      union_aliases = @used_unions.map { |name| camelize(name) }.uniq.sort
 
       out = []
       out << "# typed: strict"
@@ -218,9 +250,12 @@ class GraphWeaver::Codegen
         out << "require_relative \"inputs\""
         out << ""
       end
+      if union_aliases.any?
+        out << "require_relative \"unions\""
+        out << ""
+      end
       out << "module #{@module_name}"
-      out << "  extend T::Sig"
-      out << ""
+      out << "  extend T::Sig" << "" if GraphWeaver.extend_t_sig?
       # a GraphQL block string could contain a bare GRAPHQL line, which
       # would terminate the heredoc early — pick a delimiter the query
       # can't collide with
@@ -235,6 +270,7 @@ class GraphWeaver::Codegen
       else
         emit_variable_types(out)
       end
+      emit_shared_aliases(out, union_aliases, @unions_namespace)
       emit_nested(root, out, 1)
       out << ""
       emit_execute(out, variables, flatten:)
@@ -282,14 +318,16 @@ class GraphWeaver::Codegen
       pad = "  " * indent
 
       out << "#{pad}class #{node.class_name} < T::Struct"
-      out << "#{pad}  extend T::Sig"
+      out << "#{pad}  extend T::Sig" if GraphWeaver.extend_t_sig?
       out << "#{pad}  include GraphWeaver::Hints"
       node.mixins.each do |mixin|
         out << "#{pad}  include #{mixin} # registered for #{node.graphql_type}"
       end
       out << ""
 
-      node.fields.filter_map { |field| field.node.nested }.each do |child|
+      # uniq by object identity: deduped sibling unions share one node, so the
+      # shared type is emitted once (both fields' consts already reference it).
+      node.fields.filter_map { |field| field.node.nested }.uniq.each do |child|
         emit_nested(child, out, indent + 1)
         out << ""
       end
@@ -311,6 +349,14 @@ class GraphWeaver::Codegen
       out << "#{pad}  rescue TypeError, ArgumentError, KeyError => e"
       out << "#{pad}    raise GraphWeaver::TypeError.new(struct: self, error: e)"
       out << "#{pad}  end"
+
+      # alias delegators (extend_type alias:) — typed accessors that project a
+      # selected field onto the struct, next to the honest wire data
+      node.aliases.each do |a|
+        out << ""
+        out << "#{pad}  sig { returns(#{a.type}) }"
+        out << "#{pad}  def #{a.name} = #{a.expr}"
+      end
       out << "#{pad}end"
     end
 
@@ -318,8 +364,7 @@ class GraphWeaver::Codegen
       pad = "  " * indent
 
       out << "#{pad}module #{node.class_name}"
-      out << "#{pad}  extend T::Sig"
-      out << ""
+      out << "#{pad}  extend T::Sig" << "" if GraphWeaver.extend_t_sig?
 
       node.members.each_value do |member|
         emit_object(member, out, indent + 1)
@@ -346,8 +391,7 @@ class GraphWeaver::Codegen
       out << "  @client = T.let(nil, T.untyped)"
       out << ""
       out << "  class << self"
-      out << "    extend T::Sig"
-      out << ""
+      out << "    extend T::Sig" << "" if GraphWeaver.extend_t_sig?
       out << "    sig { params(client: T.untyped).void }"
       out << "    attr_writer :client"
       out << ""
@@ -378,7 +422,8 @@ class GraphWeaver::Codegen
 
       # execute returns the full envelope; execute! is the strict shortcut for
       # `execute(...).data!` — the typed result, or a raised QueryError.
-      forward = (["client"] + params.map { |param| "#{kwarg_name(param)}: #{kwarg_name(param)}" }).join(", ")
+      # kwargs forward via hash shorthand (key == value)
+      forward = (["client"] + params.map { |param| "#{kwarg_name(param)}:" }).join(", ")
 
       if flatten
         out << "  # $#{variables.first.wire}'s fields, flattened into kwargs (single input-object variable)"

data/lib/graph_weaver/codegen/enum_type.rb

@@ -102,9 +102,38 @@ class GraphWeaver::Codegen
     #      end
     #
     # Additive: repeated registrations (and client-scoped ones) stack.
-    def extend_type(graphql_name, *mixins, requires: nil, &block)
-      entry = type_registry[graphql_name.to_s] ||= { mixins: [], requires: [] }
-      add_type_helpers(entry, graphql_name, mixins, requires, block)
+    #
+    # alias: projects a (possibly nested) selected field onto a flat, typed
+    # accessor on the struct — the one derivation codegen can type itself, so
+    # it's emitted into the struct body where the field is in scope:
+    #
+    #      GraphWeaver.extend_type("Widget", alias: { tag: "meta.tag" })
+    #      GraphWeaver.extend_type("Widget", alias: "meta.tag")        # accessor named `tag`
+    #      GraphWeaver.extend_type("Widget", alias: ["meta.tag", "meta.color"])
+    def extend_type(graphql_name, *mixins, requires: nil, **kw, &block)
+      aliases = take_aliases(kw)
+      entry = type_registry[graphql_name.to_s] ||= { mixins: [], requires: [], aliases: {} }
+      add_type_helpers(entry, graphql_name, mixins, requires, block, aliases)
+    end
+
+    # Pull alias: out of the keyword rest and normalize it; any other keyword
+    # is a typo worth flagging rather than silently dropping.
+    def take_aliases(kw)
+      aliases = normalize_aliases(kw.delete(:alias))
+      raise ArgumentError, "unknown keyword: #{kw.keys.first}" unless kw.empty?
+      aliases
+    end
+
+    # { accessor => [path, segments] } from a path string (accessor named
+    # after the last segment), an array of such, or an { accessor => path } hash.
+    def normalize_aliases(input)
+      case input
+      when nil then {}
+      when String then { input.split(".").last => input.split(".") }
+      when Array then input.to_h { |path| [path.split(".").last, path.split(".")] }
+      when Hash then input.to_h { |name, path| [name.to_s, path.to_s.split(".")] }
+      else raise ArgumentError, "alias: expects a String, Array, or Hash, got #{input.class}"
+      end
     end
 
     def type_registry
@@ -113,11 +142,13 @@ class GraphWeaver::Codegen
 
     # shared with Client#extend_type: build/validate the mixins and
     # append them to a registry entry
-    def add_type_helpers(entry, graphql_name, mixins, requires, block)
+    def add_type_helpers(entry, graphql_name, mixins, requires, block, aliases = {})
       mixins = mixins.dup
       mixins << helper_module(graphql_name, block) if block
 
-      raise ArgumentError, "pass one or more helper modules, or a block" if mixins.empty?
+      if mixins.empty? && aliases.empty?
+        raise ArgumentError, "pass one or more helper modules, a block, or alias:"
+      end
       mixins.each do |mixin|
         unless mixin.is_a?(Module) && mixin.name
           raise ArgumentError, "type helpers must be named modules, got #{mixin.inspect}"
@@ -126,6 +157,7 @@ class GraphWeaver::Codegen
 
       entry[:mixins].concat(mixins)
       entry[:requires].concat(Array(requires))
+      (entry[:aliases] ||= {}).merge!(aliases)
       entry
     end
 

data/lib/graph_weaver/codegen/nodes.rb

@@ -144,16 +144,20 @@ class GraphWeaver::Codegen
 
   class ObjectNode < Node
     Field = Struct.new(:prop, :key, :node)
+    # a resolved alias delegator (extend_type alias:): the accessor name, the
+    # Ruby path expression it reads (meta&.tag), and its Sorbet return type
+    Alias = Struct.new(:name, :expr, :type)
 
     attr_reader :class_name, :fields
-    # the GraphQL type this struct was generated from, and any registered
-    # helper modules to include (see Codegen.extend_type)
-    attr_accessor :graphql_type, :mixins
+    # the GraphQL type this struct was generated from, any registered helper
+    # modules to include, and any resolved alias delegators (see extend_type)
+    attr_accessor :graphql_type, :mixins, :aliases
 
     def initialize(class_name)
       @class_name = class_name
       @fields = []
       @mixins = []
+      @aliases = []
     end
 
     def bare_type = class_name
@@ -277,6 +281,26 @@ class GraphWeaver::Codegen
     def nested = self
   end
 
+  # A reference to a union hoisted into the shared unions module (a named
+  # shared fragment spread as a whole union field): the query references
+  # <Name>::Type and dispatches through <Name>.from_h, where <Name> is the
+  # alias the query module gives GraphQLUnions::<Name>. The type family lives
+  # once in the shared module, so the same union across queries is one Ruby
+  # type — nested is nil, nothing is emitted here.
+  class UnionRefNode < Node
+    attr_reader :class_name
+
+    def initialize(class_name)
+      @class_name = class_name
+    end
+
+    def bare_type = "#{class_name}::Type"
+
+    def cast(expr, _depth)
+      "#{class_name}.from_h(#{expr})"
+    end
+  end
+
   # An input-object variable: emitted as a module-level T::Struct whose
   # serialize produces the wire hash. Inputs never cast FROM the wire.
   # Joins the coerce protocol so execute kwargs accept plain hashes,

data/lib/graph_weaver/codegen.rb

@@ -49,8 +49,12 @@ class GraphWeaver::Codegen
   # 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).
   def initialize(schema:, query:, module_name: nil, client: nil, default_module_name: nil,
-    scalars: nil, enums: nil, types: nil, inputs_namespace: nil)
+    scalars: nil, enums: nil, types: nil, inputs_namespace: nil, unions_namespace: nil,
+    hoistable_unions: nil)
     @schema = schema
     @query = query.strip
     @module_name = module_name
@@ -59,6 +63,12 @@ class GraphWeaver::Codegen
     @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
+    @hoistable_unions = hoistable_unions || []
+    @used_unions = []
     @client_const = self.class.client_const(client)
 
     if client && @client_const.nil?
@@ -111,6 +121,11 @@ class GraphWeaver::Codegen
     { inputs: @variable_inputs.keys, enums: @variable_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.
+  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
@@ -138,6 +153,36 @@ class GraphWeaver::Codegen
     emit_inputs_files
   end
 
+  # 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)
+  end
+
+  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
+
+    @requires = []
+    @mapped_enums = {}
+    # nested spreads inside a shared fragment resolve through the whole table
+    @fragments = fragments
+
+    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
+
+    emit_unions_file(unions)
+  end
+
   VarDef = Struct.new(:kwarg, :wire, :node, :required)
 
   # Names that cannot appear bare in generated Ruby: keywords aren't
@@ -168,6 +213,7 @@ class GraphWeaver::Codegen
     @variable_enums = {}
     @variable_inputs = {}
     @mapped_enums = {}
+    @used_unions = []
     # requires the generated file needs (custom scalars, enum mappings,
     # type helpers all contribute)
     @requires = []
@@ -214,6 +260,14 @@ class GraphWeaver::Codegen
   # whose schema introspects lazily). Global registrations skip this:
   # they may target a different client's server.
   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.
+    if kind == "scalar" && name.include?(".")
+      return if scalar_field?(schema, name)
+
+      raise GraphWeaver::Error, "register_scalar(#{name.inspect}) matches no scalar field in this schema"
+    end
+
     return if schema.get_type(name)
 
     suggestion = defined?(DidYouMean::SpellChecker) &&
@@ -224,6 +278,81 @@ class GraphWeaver::Codegen
     raise GraphWeaver::Error, "#{method}(#{name.inspect}) matches no type in this schema#{hint}"
   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
+
+    field = schema.get_field(type_name, field_name)
+    !!field && field.type.unwrap.kind.name == "SCALAR"
+  rescue StandardError
+    false
+  end
+
+  # 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.
+  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))
+      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)
+        out[frag.name] = frag
+      end
+    end
+  end
+
+  # The shared fragments a query spreads (transitively), excluding any it
+  # 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)
+    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
+
+  # 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)
+    return query if used.empty?
+
+    "#{query.rstrip}\n\n#{used.sort.map { |name| shared.fetch(name).to_query_string }.join("\n\n")}\n"
+  end
+
+  # BFS over spreads, following shared fragments into their own spreads; a
+  # locally-defined or unknown spread is left for schema validation to judge.
+  def self.reachable_fragments(spreads, shared, local)
+    needed = []
+    queue = spreads.dup
+    until queue.empty?
+      name = queue.shift
+      next if needed.include?(name) || local.include?(name) || !shared.key?(name)
+
+      needed << name
+      queue.concat(fragment_spreads([shared.fetch(name)]))
+    end
+    needed
+  end
+  private_class_method :reachable_fragments
+
+  # Names of every fragment spread reachable in these AST nodes.
+  def self.fragment_spreads(nodes, acc = [])
+    nodes.each do |node|
+      acc << node.name if node.is_a?(GraphQL::Language::Nodes::FragmentSpread)
+      fragment_spreads(node.selections, acc) if node.respond_to?(:selections)
+    end
+    acc
+  end
+  private_class_method :fragment_spreads
+
   # Structured shape for a schema-validation error: message plus its first
   # source location, so ValidationError#errors is inspectable.
   def validation_detail(error)
@@ -251,6 +380,10 @@ class GraphWeaver::Codegen
     node.graphql_type = type.graphql_name
     node.mixins = type_mixins(type.graphql_name)
     taken = [class_name]
+    # 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`.
+    union_cache = {}
 
     gather(type, selections).each do |key, field_nodes|
       field_name = field_nodes.first.name
@@ -291,9 +424,20 @@ class GraphWeaver::Codegen
 
             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)) &&
+              @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
+            # 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
-            name = pick_name(core.graphql_name, key, taken)
-            type_ref(field_type) { union_node(core, sub_selections, name) }
+            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))
+            type_ref(field_type) { union }
           end
         when "ENUM"
           if (mapped = mapped_enum_node(core))
@@ -305,7 +449,8 @@ class GraphWeaver::Codegen
             type_ref(field_type) { EnumNode.new(name, core.values.keys.sort) }
           end
         when "SCALAR"
-          type_ref(field_type) { scalar_node(core.graphql_name) }
+          coordinate = "#{type.graphql_name}.#{field_name}"
+          type_ref(field_type) { scalar_node(core.graphql_name, coordinate) }
         else
           raise GraphWeaver::Error, "unsupported kind: #{core.kind.name}"
         end
@@ -320,9 +465,72 @@ class GraphWeaver::Codegen
       node.fields << ObjectNode::Field.new(prop, key, child)
     end
 
+    node.aliases = resolve_aliases(node)
     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)
+    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)
+      raise GraphWeaver::Error,
+        "alias #{name.inspect} on #{node.graphql_type} collides with an existing field or method"
+    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
+  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)
@@ -341,6 +549,17 @@ class GraphWeaver::Codegen
     selections.grep(GraphQL::Language::Nodes::Field).map { |field| field.alias || field.name }
   end
 
+  # The fragment name when a selection is exactly one bare fragment spread
+  # (`{ ...F }`) — the shape a union field must have to hoist into the shared
+  # unions module. A spread carrying directives (@skip/@include), or mixed with
+  # other fields, stays a locally-emitted union.
+  def lone_shared_spread(selections)
+    return unless selections.size == 1
+
+    spread = selections.first
+    spread.name if spread.is_a?(GraphQL::Language::Nodes::FragmentSpread) && spread.directives.empty?
+  end
+
   # does the flattened selection (as seen by member) include at least one
   # field guaranteed to be present in a matching response?
   def unconditional_field?(member, selections)
@@ -367,19 +586,45 @@ class GraphWeaver::Codegen
   # concrete type: one member struct per possible type; wire dispatch
   # reads __typename, so the query must select it. For interfaces, the
   # interface's own field selections gather into every member.
-  def union_node(type, selections, class_name)
+  # 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.
+  def union_members(type, selections)
     unless gather(type, selections).key?("__typename")
       raise ArgumentError,
-        "select __typename on #{type.graphql_name} so #{class_name} can dispatch — " \
+        "select __typename on #{type.graphql_name} so the union can dispatch — " \
         "or narrow to a single `... on Type` condition (no dispatch needed)"
     end
 
-    # sorted so output is deterministic across schema sources
-    members = @schema.possible_types(type).sort_by(&:graphql_name).to_h do |possible|
+    @schema.possible_types(type).sort_by(&:graphql_name).to_h do |possible|
       [possible.graphql_name, object_node(possible, selections, camelize(possible.graphql_name))]
     end
+  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(",")
+  end
 
-    UnionNode.new(class_name, members)
+  # Structural signature of a node — ignores the generated class name (which
+  # varies per occurrence), keying on GraphQL type, selection shape, and
+  # nullability so only genuinely-identical shapes collapse.
+  def signature(node)
+    case node
+    when NonNull then "!#{signature(node.of)}"
+    when List then "[#{signature(node.of)}]"
+    when NarrowedNode then "?#{signature(node.nested)}"
+    when Scalar then "s:#{node.bare_type}"
+    when EnumNode then "e:#{node.values.sort.join("|")}"
+    when MappedEnum then "m:#{node.graphql_name}"
+    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 UnionRefNode then "ur:#{node.class_name}" # hoisted — identity is its shared name
+    else "x:#{node.object_id}" # unknown node kind — never collapse
+    end
   end
 
   # Build a node from an AST type reference (variable definitions), where
@@ -462,9 +707,13 @@ 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: the client-scoped overlay first, then the global registry.
-  def scalar_node(name)
-    scalar = @scalars[name.to_s] || GraphWeaver::Codegen.scalar(name)
+  # Resolution, most specific first: a per-field override (`Type.field`), then
+  # the scalar-name registration — each checked client-scoped, then global.
+  def scalar_node(name, coordinate = nil)
+    scalar =
+      (coordinate && (@scalars[coordinate] || GraphWeaver::Codegen.scalar_registry[coordinate])) ||
+      @scalars[name.to_s] ||
+      GraphWeaver::Codegen.scalar(name)
     @requires.concat(scalar.requires)
     Scalar.new(scalar)
   end