graph_weaver 0.7.3 → 0.7.5

data/lib/graph_weaver/codegen/type_helpers.rb

@@ -45,10 +45,21 @@ class GraphWeaver::Codegen
     # fit the path just omits the accessor instead of failing generation. Use it
     # for a root-type accessor (a Query alias every query would otherwise have to
     # satisfy) or one that only fits some selections.
+    #
+    # Inside the block, `alias_field` is the same keyword said next to the
+    # methods that use it — one alias per line, always strict:
+    #
+    #      GraphWeaver.extend_type("Widget") do
+    #        alias_field :tag, "meta.tag"
+    #        def shout = tag&.upcase
+    #      end
     def extend_type(graphql_name, *mixins, requires: nil, **kw, &block)
-      aliases = take_aliases(kw)
+      optional = !!kw.delete(:optional)
+      aliases = normalize_aliases(kw.delete(:alias), optional:)
+      raise ArgumentError, "unknown keyword: #{kw.keys.first}" unless kw.empty?
+
       mixins = mixins.dup
-      mixins << helper_module(graphql_name, block) if block
+      mixins << helper_module(graphql_name, block, aliases) if block
 
       raise ArgumentError, "pass one or more helper modules, a block, or alias:" if mixins.empty? && aliases.empty?
       mixins.each do |mixin|
@@ -70,15 +81,6 @@ class GraphWeaver::Codegen
       entry
     end
 
-    # Pull alias:/optional: out of the keyword rest and normalize; any other
-    # keyword is a typo worth flagging rather than silently dropping.
-    def take_aliases(kw)
-      aliases = normalize_aliases(kw.delete(:alias), optional: !!kw.delete(:optional))
-      raise ArgumentError, "unknown keyword: #{kw.keys.first}" unless kw.empty?
-      aliases
-    end
-    private :take_aliases
-
     # accessor names and path segments are interpolated verbatim into generated
     # source, so — like module_name — they must be plain identifiers, never
     # arbitrary text that could inject code
@@ -138,7 +140,7 @@ class GraphWeaver::Codegen
     # naming it after whichever constants happened to exist made it a function
     # of how many times THIS process had read the registry, and `generate`
     # wrote a name a plain boot never creates.
-    def helper_module(graphql_name, block)
+    def helper_module(graphql_name, block, aliases)
       namespace = helper_namespace
       type = GraphWeaver::Inflect.camelize(graphql_name.to_s)
       index = (helper_counts[[namespace.name, type]] += 1)
@@ -146,11 +148,67 @@ class GraphWeaver::Codegen
       # reused rather than replaced, so re-declaring the same source (a Rails
       # to_prepare reload) keeps the module already-loaded structs include
       mod = const_under(namespace, name) { Module.new }
-      mod.module_eval(&block)
+      aliases.merge!(collect_aliases(graphql_name, mod, aliases, &block))
       mod
     end
     private :helper_module
 
+    # Run the block with `alias_field` available — the alias: keyword said one
+    # line at a time — and hand back what it collected.
+    #
+    # It lives on the module's singleton for the length of the block and is
+    # removed after: a generated struct includes this module, and an
+    # `alias_field` left behind would be an instance method the wire never named.
+    def collect_aliases(graphql_name, mod, keyword_aliases, &block)
+      registry, collected = self, {}
+      mod.define_singleton_method(:alias_field) do |name, path = nil, **kw|
+        collected.merge!(registry.send(:one_alias, graphql_name, name, path, kw))
+      end
+      mod.module_eval(&block)
+
+      twice = keyword_aliases.keys & collected.keys
+      unless twice.empty?
+        raise ArgumentError, "extend_type(#{graphql_name.to_s.inspect}) declares alias " \
+          "#{twice.first.inspect} twice — once as alias:, once as alias_field; keep one"
+      end
+      collected
+    ensure
+      mod.singleton_class.send(:remove_method, :alias_field)
+    end
+    private :collect_aliases
+
+    ALIAS_FIELD_FORMS = %(one alias per line — alias_field "meta.tag", or alias_field :tag, "meta.tag"; ) +
+      %(a Hash or Array of paths goes on the alias: keyword)
+    private_constant :ALIAS_FIELD_FORMS
+
+    # One `alias_field` line, normalized the way the keyword's own paths are.
+    # The block takes no optional: — leniency has one spelling, on the keyword,
+    # because it is a property of the registration and not of one accessor.
+    def one_alias(graphql_name, name, path, kw)
+      if kw.key?(:optional)
+        keyword = path ? "alias: { #{name}: #{path.inspect} }" : "alias: #{name.inspect}"
+        raise ArgumentError, "alias_field is always strict — for a lenient alias use the keyword: " \
+          "extend_type(#{graphql_name.to_s.inspect}, #{keyword}, optional: true)"
+      end
+      raise ArgumentError, "unknown keyword: #{kw.keys.first}" unless kw.empty?
+
+      input = if path.nil? && name.is_a?(String)
+        name
+      elsif path.is_a?(String) && (name.is_a?(String) || name.is_a?(Symbol))
+        { name => path }
+      end
+      if input.nil?
+        # spelled as a caller writes it — Hash#inspect changed between Ruby 3.3 and 3.4
+        given = [name, path].compact.map do |arg|
+          arg.is_a?(Hash) ? "{#{arg.map { |k, v| "#{k}: #{v.inspect}" }.join(", ")}}" : arg.inspect
+        end.join(", ")
+        raise ArgumentError, "alias_field #{given}: #{ALIAS_FIELD_FORMS}"
+      end
+
+      normalize_aliases(input, optional: false)
+    end
+    private :one_alias
+
     # Where this registry's block-built helpers live: under a module named for
     # the graph, so two graphs extending the same type get two constants and
     # neither has to know the other exists.

data/lib/graph_weaver/codegen.rb

@@ -66,15 +66,15 @@ class GraphWeaver::Codegen
   # 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
-  # may hoist (spreads it inlined, minus any it shadows locally) — a
-  # whole-union field spread as one of them resolves to a canonical type in the
-  # shared module (see used_union_names). path: is the file the query was read
+  # GraphWeaver.generate!): input types, schema enums, and the types hoisted out
+  # of shared fragments live once in that module and the query module aliases
+  # what it uses. hoistable_fragments: is the set of shared fragment names this
+  # query may hoist (spreads it inlined, minus any it shadows locally) — a whole
+  # field spread as one of them resolves to a canonical type in the shared
+  # module (see used_fragment_names). path: is the file the query was read
   # from, named alongside line and column in validation errors.
   def initialize(schema:, query:, name: nil, default_name: nil,
-    types_namespace: nil, hoistable_unions: nil, path: nil, module_name: nil,
+    types_namespace: nil, hoistable_fragments: nil, path: nil, module_name: nil,
     graph_name: nil, registry: GraphWeaver::Codegen.registry)
     renamed!(module_name)
     @schema = schema
@@ -87,8 +87,8 @@ class GraphWeaver::Codegen
     @name = name
     @default_name = default_name
     @types_namespace = types_namespace
-    @hoistable_unions = hoistable_unions || []
-    @used_unions = []
+    @hoistable_fragments = hoistable_fragments || []
+    @used_fragments = []
     # scalars this generation had no registration for (see report_untyped_scalars)
     @untyped_scalars = []
     # the graph this module belongs to: its client and, under a test mode,
@@ -144,16 +144,22 @@ class GraphWeaver::Codegen
     { inputs: @variable_inputs.keys, enums: @enums.keys, mapped: @mapped_enums.keys }
   end
 
-  # The shared union fragments this query hoisted, by name — the generate!
-  # workflow unions these across queries to decide what the shared types module
-  # must contain.
-  def used_union_names = @used_unions.dup
+  # The shared fragments this query hoisted, by name — the generate! workflow
+  # unions these across queries to decide what the shared types module must
+  # contain.
+  def used_fragment_names = @used_fragments.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 block-built type helpers this walk included, by constant name. They are
+  # minted at registration, so no source file declares them and an app's
+  # `srb tc` can't resolve the include this emitted — the generate! workflow
+  # unions these across queries and declares them in an .rbi.
+  def block_helpers = @block_helpers.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
@@ -166,26 +172,29 @@ class GraphWeaver::Codegen
   #   T::Enum, or the wire tables for one mapped onto an app enum
   #   (register_enum) — so a value read out of one query's result hands
   #   straight back into another's variable;
-  # - unions: each named shared fragment a query spread as a whole union field,
-  #   so the same union across queries is one Ruby type family. `fragments` is
-  #   the loaded shared-fragment table (nested spreads resolve through it).
+  # - hoisted: each named shared fragment a query spread as a whole field, so
+  #   the same shape across queries is one Ruby type. `fragments` is the loaded
+  #   shared-fragment table (nested spreads resolve through it).
   #
-  # Unions are built first: a hoisted fragment's own selections are the one
-  # place a query walk never reaches, so the enums they touch are only known
-  # once the fragments are built.
-  def generate_types(inputs:, enums:, unions:, fragments:)
+  # Hoisted fragments are built first: their own selections are the one place a
+  # query walk never reaches, so the enums they touch are only known once the
+  # fragments are built.
+  def generate_types(inputs:, enums:, hoisted:, fragments:)
     validate_module_name!("types module name")
     reset_walk_state!
     # nested spreads inside a shared fragment resolve through the whole table
     @fragments = fragments
 
-    union_nodes = unions.uniq.sort.map { |name| hoisted_union(fragments, name) }
+    nodes = hoisted.uniq.sort.map { |name| hoisted_fragment(fragments, name) }
     inputs.sort.each { |name| input_node(@schema.get_type(name)) }
     enums.uniq.sort.each { |name| variable_core(@schema.get_type(name)) }
-    check_shared_collisions!(unions)
-    union_nodes.each { |union| check_shadowing!(union) }
+    check_shared_collisions!(hoisted)
+    nodes.each do |node|
+      check_shadowing!(node)
+      check_abstract_mixins!(node)
+    end
 
-    emit_types_files(union_nodes).tap { report_untyped_scalars }
+    emit_types_files(nodes).tap { report_untyped_scalars }
   end
 
   # module-level constants every generated query module defines — a shared
@@ -195,7 +204,7 @@ class GraphWeaver::Codegen
 
   # One hoisted shared fragment, built against the schema and named for the
   # fragment rather than the field that spread it.
-  def hoisted_union(fragments, name)
+  def hoisted_fragment(fragments, name)
     class_name = camelize(name)
     # the query module aliases <class_name> = <shared module>::<class_name>; a
     # name that camelizes to a generated module-level constant (the Result
@@ -207,13 +216,15 @@ class GraphWeaver::Codegen
 
     fragment = fragments.fetch(name)
     type = @schema.get_type(fragment.type.name)
+    return object_node(type, fragment.selections, class_name) if type.kind.object?
+
     members = union_members(type, fragment.selections)
     UnionNode.new(class_name, members, catch_all_member(type, fragment.selections, members))
   end
-  private :hoisted_union
+  private :hoisted_fragment
 
   # Schema type names are unique, so an input and an enum can never land on the
-  # same name — but a hoisted union is named for its FRAGMENT, which the schema
+  # same name — but a hoisted type is named for its FRAGMENT, which the schema
   # knows nothing about. One shared module means one namespace, so a fragment
   # named after a type it doesn't describe has to refuse rather than overwrite.
   def check_shared_collisions!(names)
@@ -244,7 +255,9 @@ class GraphWeaver::Codegen
     @input_list = false
     @input_hops = []
     @mapped_enums = {}
-    @used_unions = []
+    @used_fragments = []
+    # block-built type helpers this walk included — see #block_helpers
+    @block_helpers = []
     # requires the generated file needs (custom scalars, enum mappings,
     # type helpers all contribute)
     @requires = []
@@ -400,6 +413,7 @@ class GraphWeaver::Codegen
     variables = build_variables(operation)
     root = object_node(root_type, operation.selections, "Result")
     check_shadowing!(root)
+    check_abstract_mixins!(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
@@ -711,7 +725,7 @@ class GraphWeaver::Codegen
   # 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.
+  # when they are a field's whole selection.
   def self.shared_fragment_spreads(query, shared, path = nil)
     # parsed even with nothing to spread: this is the first look at the document
     # on the generate! path, so it's where a syntax error gets branded and
@@ -840,6 +854,7 @@ class GraphWeaver::Codegen
     node = ObjectNode.new(class_name)
     node.graphql_type = type.graphql_name
     node.mixins = type_mixins(type.graphql_name)
+    node.overrides = abstract_mixin_members(type.graphql_name)
     # class name => the result key that claimed it; the struct itself first,
     # claimed by nothing (see pick_name)
     taken = { class_name => nil }
@@ -863,59 +878,16 @@ class GraphWeaver::Codegen
 
         case (core = field_type.unwrap).kind.name
         when "OBJECT"
-          name = pick_name(key, taken)
-          type_ref(field_type) { object_node(core, sub_selections, name) }
-        when "UNION", "INTERFACE"
-          conditions = concrete_conditions(core, sub_selections)
-          shared = abstract_level_fields(core, sub_selections)
-
-          if conditions.empty?
-            # abstract-level fields only — every member shares them, so one
-            # struct suffices and no __typename dispatch is needed (for a
-            # union that selection can only be __typename)
+          if (frag = hoistable_spread(core, sub_selections))
+            hoisted_ref(field_type, frag)
+          else
             name = pick_name(key, taken)
             type_ref(field_type) { object_node(core, sub_selections, name) }
-          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).
-            # With `__typename` selected the match is read off the tag;
-            # without one there is nothing to read but emptiness, and a
-            # fragment whose every field hides behind @skip/@include would
-            # make a real match indistinguishable from a miss ({} either
-            # way) — refuse rather than guess.
-            tag = member.graphql_name if dispatchable_typename?(core, sub_selections)
-            unless tag || unconditional_field?(member, sub_selections)
-              raise GraphWeaver::Error,
-                "narrowed `... on #{member.graphql_name}` needs at least one field not under " \
-                "@skip/@include (or a `__typename` to match on) — an all-conditional selection " \
-                "makes a match indistinguishable from nil"
-            end
-
-            name = pick_name(key, taken)
-            nilable_type_ref(field_type) { NarrowedNode.new(object_node(member, sub_selections, name), typename: tag) }
-          elsif @types_namespace && (frag = lone_shared_spread(sub_selections)) &&
-              @hoistable_unions.include?(frag)
-            # a whole-union field spread as a named shared fragment: hoist to
-            # the shared types module so the same union across queries is one
-            # Ruby type family (one exhaustive `case ... T.absurd`).
-            @used_unions << frag unless @used_unions.include?(frag)
-            ref = UnionRefNode.new(camelize(frag))
-            type_ref(field_type) { ref }
-          else
-            members = union_members(core, sub_selections)
-            catch_all = catch_all_member(core, sub_selections, members)
-            # reuse an identical sibling union — the shared type takes the
-            # first of the sharing keys alphabetically, not in walk order
-            signature = union_signature(members, catch_all)
-            union = union_cache[signature]
-            if union
-              rename_union(union, key, taken) if camelize(key) < union.class_name
-            else
-              union = union_cache[signature] = UnionNode.new(pick_name(key, taken), members, catch_all)
-            end
-            type_ref(field_type) { union }
           end
+        when "UNION", "INTERFACE"
+          abstract_field(AbstractField.new(
+            type: field_type, selections: sub_selections, key:, taken:, union_cache:,
+          ))
         when "ENUM"
           # one schema enum is one Ruby type: module-level, named for the enum,
           # shared by every result field and variable that reaches it (and, on
@@ -944,6 +916,88 @@ class GraphWeaver::Codegen
     node
   end
 
+  # An abstract-typed (union or interface) field: what was selected through it,
+  # and the two ledgers the struct being built keeps — the names already claimed
+  # in its scope, and the unions it has already emitted.
+  AbstractField = Data.define(:type, :selections, :key, :taken, :union_cache) do
+    def core = type.unwrap
+  end
+  private_constant :AbstractField
+
+  # Which of four shapes an abstract-typed field generates. The selection
+  # decides, not the schema: what it narrows to, and how it was spread.
+  def abstract_field(field)
+    conditions = concrete_conditions(field.core, field.selections)
+    shared = abstract_level_fields(field.core, field.selections)
+
+    if conditions.empty?
+      abstract_level_struct(field)
+    elsif conditions.size == 1 && shared.empty? &&
+        (member = @schema.get_type(conditions.first)).kind.name == "OBJECT"
+      narrowed_struct(field, member)
+    elsif (frag = hoistable_spread(field.core, field.selections))
+      hoisted_ref(field.type, frag)
+    else
+      dispatch_union(field)
+    end
+  end
+
+  # Every member carries the abstract-level fields, so one struct answers for
+  # all of them and there is nothing to dispatch on — for a union, the only
+  # selection that can get here is __typename.
+  def abstract_level_struct(field)
+    name = pick_name(field.key, field.taken)
+    type_ref(field.type) { object_node(field.core, field.selections, name) }
+  end
+
+  # Narrowing to the one member a `... on X` names filters: the field is nil
+  # whenever the runtime type doesn't match. With `__typename` selected the
+  # match is read off the tag; without one there is nothing to read but
+  # emptiness, and a fragment whose every field hides behind @skip/@include
+  # would make a real match indistinguishable from a miss ({} either way) —
+  # refuse rather than guess.
+  def narrowed_struct(field, member)
+    tag = member.graphql_name if dispatchable_typename?(field.core, field.selections)
+    unless tag || unconditional_field?(member, field.selections)
+      raise GraphWeaver::Error,
+        "narrowed `... on #{member.graphql_name}` needs at least one field not under " \
+        "@skip/@include (or a `__typename` to match on) — an all-conditional selection " \
+        "makes a match indistinguishable from nil"
+    end
+
+    name = pick_name(field.key, field.taken)
+    nilable_type_ref(field.type) { NarrowedNode.new(object_node(member, field.selections, name), typename: tag) }
+  end
+
+  # A whole field spread as one named shared fragment points at the type
+  # hoisted into the shared types module, so the same shape across queries is
+  # one Ruby type — for a union, one exhaustive `case ... T.absurd`.
+  def hoisted_ref(field_type, frag)
+    @used_fragments << frag unless @used_fragments.include?(frag)
+    # an abstract type hoists to a dispatch module, an object type to a struct
+    core = field_type.unwrap
+    node_class = core.kind.object? ? HoistedRefNode : UnionRefNode
+    ref = node_class.new(camelize(frag), core.graphql_name)
+    type_ref(field_type) { ref }
+  end
+
+  # One member struct per type the selection names, chosen at runtime off
+  # __typename. Structurally identical sibling unions share one Ruby type,
+  # named for the first of the sharing keys alphabetically so that which one
+  # the walk reached first doesn't decide.
+  def dispatch_union(field)
+    members = union_members(field.core, field.selections)
+    catch_all = catch_all_member(field.core, field.selections, members)
+    signature = union_signature(members, catch_all)
+    union = field.union_cache[signature]
+    if union
+      rename_union(union, field.key, field.taken) if camelize(field.key) < union.class_name
+    else
+      union = field.union_cache[signature] = UnionNode.new(pick_name(field.key, field.taken), members, catch_all)
+    end
+    type_ref(field.type) { union }
+  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
@@ -1057,10 +1111,26 @@ class GraphWeaver::Codegen
     dispatchable_typename?(core, selections) ? keys - ["__typename"] : keys
   end
 
+  # The name a field's whole selection hoists under: exactly one bare spread of
+  # a fragment this query may hoist, written on the field's own type. Only the
+  # generate! workflow has a shared module to hoist into — dynamic `parse`
+  # inlines.
+  def hoistable_spread(core, selections)
+    return unless @types_namespace
+
+    frag = lone_shared_spread(selections)
+    return unless frag && @hoistable_fragments.include?(frag)
+
+    # the shared type is built from the fragment's own type condition, so it is
+    # this field's type only when the two agree — a fragment on a narrower (or
+    # wider) type stays a locally-emitted struct
+    frag if @fragments.fetch(frag).type.name == core.graphql_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.
+  # (`{ ...F }`) — the shape a field must have to hoist into the shared types
+  # module. A spread carrying directives (@skip/@include), or mixed with other
+  # fields, stays locally emitted.
   def lone_shared_spread(selections)
     return unless selections.size == 1
 
@@ -1163,7 +1233,7 @@ class GraphWeaver::Codegen
   # it. It carries what the abstract type itself guarantees, plus anything a
   # `... on SomeInterface` asked for, since an unnamed member may implement it.
   def catch_all_member(type, selections, members)
-    node = object_node(type, selections, catch_all_name(members))
+    node = object_node(type, selections, catch_all_name(members.each_value.map(&:class_name)))
     taken = node.fields.map(&:key)
 
     # These are nilable whatever the schema promises: the member that arrives
@@ -1213,9 +1283,9 @@ class GraphWeaver::Codegen
     sibling_conditions(condition, selections, visiting, out)
   end
 
-  # "Other", unless a real member already claims that name.
-  def catch_all_name(members)
-    taken = members.each_value.map(&:class_name)
+  # "Other", unless a real member already claims that name — one rule for a
+  # union's catch-all struct and a generated enum's fallback member.
+  def catch_all_name(taken)
     name = "Other"
     suffix = 2
     while taken.include?(name)
@@ -1242,13 +1312,13 @@ class GraphWeaver::Codegen
     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 EnumNode then "e:#{node.values.sort.join("|")}#{"+" if node.fallback?}"
     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, node.catch_all)})"
-    when UnionRefNode then "ur:#{node.class_name}" # hoisted — identity is its shared name
+    when HoistedRefNode then "hr:#{node.class_name}" # hoisted — identity is its shared name
     else "x:#{node.object_id}" # unknown node kind — never collapse
     end
   end
@@ -1315,7 +1385,8 @@ class GraphWeaver::Codegen
       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)
+      node.fields << InputNode::Field.new(prop, argument.graphql_name, child, required,
+        argument.type.to_type_signature)
     end
     check_input_props!(core, node)
     node
@@ -1396,15 +1467,22 @@ class GraphWeaver::Codegen
         "constant — map it onto one of yours: register_enum(#{core.graphql_name.inspect}, YourEnum)"
     end
 
-    EnumNode.new(class_name, enum_values(core))
-  end
-
-  # A schema enum's wire values, sorted so output is deterministic across schema
-  # sources (SDL round-trips reorder values alphabetically). Values that differ
-  # only in case name the same T::Enum constant, which raises at LOAD time
-  # ("Enum values must be assigned to constants") — catch it here instead.
-  def enum_values(core)
-    values = core.values.keys.sort
+    entry = @registry.enum_registry[core.graphql_name]
+    aliases = entry&.aliases_for(core.values.keys.sort) || {}
+    values = enum_values(core, aliases)
+    # named the way a union's catch-all is: Other, or Other2 past a declared OTHER
+    fallback = catch_all_name(values.map { |value| camelize(value.downcase) }) if entry&.generated_fallback?
+    EnumNode.new(class_name, values, aliases, fallback:)
+  end
+
+  # A schema enum's constant-bearing wire values, sorted so output is
+  # deterministic across schema sources (SDL round-trips reorder values
+  # alphabetically). An aliased spelling is read as another of the values, so
+  # it gets no constant. Values that differ only in case name the same T::Enum
+  # constant, which raises at LOAD time ("Enum values must be assigned to
+  # constants") — catch it here instead.
+  def enum_values(core, aliases = {})
+    values = core.values.keys.sort - aliases.keys
     # `_` 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
@@ -1415,12 +1493,18 @@ class GraphWeaver::Codegen
         "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
+    # A schema mid-rename declares every value twice, so every pair collides:
+    # name one, count the rest, and print the registration that fixes them all.
+    collisions = values.group_by { |value| camelize(value.downcase) }.select { |_, group| group.size > 1 }
+    if collisions.any?
+      constant, group = collisions.first
+      more = collisions.size - 1
       raise GraphWeaver::Error,
-        "enum #{core.graphql_name} values #{collision.last.join(" and ")} both become the constant " \
-        "#{collision.first} — map the enum onto one of yours: " \
-        "register_enum(#{core.graphql_name.inspect}, YourEnum)"
+        "enum #{core.graphql_name} values #{group.join(" and ")} both become the constant #{constant}" \
+        "#{" (and #{more} more colliding pair#{"s" if more > 1})" unless more.zero?} — if each pair is one " \
+        "value, say which spelling goes on the wire:\n  " \
+        "#{EnumType.alias_suggestion(core.graphql_name, collisions.values)}\n" \
+        "or map the enum onto one of yours: register_enum(#{core.graphql_name.inspect}, YourEnum)"
     end
 
     values
@@ -1432,14 +1516,83 @@ class GraphWeaver::Codegen
     return [] unless entry
 
     @requires.concat(entry[:requires])
-    entry[:mixins].map(&:name)
+    names = entry[:mixins].map(&:name)
+    # GraphWeaver::TypeHelpers is where extend_type mints a block's mixin, and
+    # a module there exists in no source file — so generation has to declare it
+    @block_helpers.concat(names.grep(BLOCK_HELPER))
+    names
+  end
+
+  # A block-built mixin's constant, by the namespace extend_type mints it under.
+  BLOCK_HELPER = /\AGraphWeaver::TypeHelpers::/
+  private_constant :BLOCK_HELPER
+
+  # Struct members a registered mixin declares abstract (docs/generated_modules.md
+  # recommends that shape so a named helper carries sigs srb tc can check).
+  # Sorbet demands the override be declared on whatever satisfies an abstract
+  # sig, and nothing generation writes can be corrected by hand — a `const` has
+  # no sig to insert `override.` into — so codegen derives it, the same way it
+  # derives an alias's type. Mixin ancestors count: an inherited abstract sig is
+  # one Sorbet demands the override for just the same.
+  def abstract_mixin_members(graphql_name)
+    entry = @registry.type_registry[graphql_name]
+    return [] unless entry
+
+    entry[:mixins].flat_map { |mixin|
+      T::AbstractUtils.declared_abstract_methods_for(mixin).map { |method| method.name.to_s }
+    }.uniq
+  end
+  private :abstract_mixin_members
+
+  # An `abstract!` mixin goes into EVERY struct generated from its type, but
+  # only a struct that selected the members it declares can satisfy them — so a
+  # query selecting a subset generated fine and failed in the app's own
+  # `srb tc`, two tools from the query that fell short. Walked from the root the
+  # way shadowing is, so the refusal can name the struct by its path.
+  def check_abstract_mixins!(node, path = [])
+    case node
+    when UnionNode
+      inner = path + [node.class_name]
+      (node.members.each_value.to_a + [node.catch_all]).each { |member| check_abstract_mixins!(member, inner) }
+    when ObjectNode
+      inner = path + [node.class_name]
+      refuse_unsatisfiable_mixin!(node, inner)
+      node.fields.each { |field| check_abstract_mixins!(field.node.nested, inner) if field.node.nested }
+    end
+  end
+
+  def refuse_unsatisfiable_mixin!(node, path)
+    return if node.overrides.empty?
+
+    mixins = @registry.type_registry.dig(node.graphql_type, :mixins) || []
+    provided = (node.fields.map(&:prop) + node.aliases.map(&:name)).to_set
+    # what is still abstract with every registered mixin included: a member one
+    # of them implements for another is already answered
+    probe = Module.new
+    mixins.each { |mixin| probe.include(mixin) }
+    missing = T::AbstractUtils.abstract_methods_for(probe)
+      .map { |method| method.name.to_s }.reject { |member| provided.include?(member) }.sort
+    return if missing.empty?
+
+    mixin = mixins.find { |m|
+      T::AbstractUtils.declared_abstract_methods_for(m).any? { |method| missing.include?(method.name.to_s) }
+    }
+    raise GraphWeaver::Error,
+      "#{[@name, *path].join("::")} includes #{mixin.name}, which declares " \
+      "#{GraphWeaver::Internal::Util.sample(missing.map(&:inspect))} abstract — this selection does " \
+      "not provide #{missing.one? ? "it" : "them"}, and every struct generated from " \
+      "#{node.graphql_type} includes the mixin, so `srb tc` fails on this one. Select " \
+      "#{missing.one? ? "it" : "them"} here, or select #{node.graphql_type} through one shared " \
+      "fragment (`{ ...Frag }`), which hoists one struct for every query to share."
   end
+  private :check_abstract_mixins!, :refuse_unsatisfiable_mixin!
 
   # The MappedEnum node for a schema enum with a registered app-enum
-  # mapping; nil when unregistered, falling back to a generated T::Enum.
+  # mapping; nil when unregistered — or registered for alias: alone, which
+  # says nothing about the Ruby type — falling back to a generated T::Enum.
   def mapped_enum_node(core)
     enum_type = @registry.enum_registry[core.graphql_name]
-    return unless enum_type
+    return unless enum_type&.type
 
     @requires.concat(enum_type.requires)
     @mapped_enums[core.graphql_name] ||= MappedEnum.new(enum_type, core.values.keys.sort)