graph_weaver 0.4.6 → 0.5.1

data/lib/graph_weaver/codegen/enum_type.rb

@@ -22,6 +22,13 @@ class GraphWeaver::Codegen
 
     def initialize(graphql_name, type, map: nil, fallback: nil, requires: nil)
       @graphql_name = graphql_name.to_s
+      # A name, not the class, is what you write when the constant won't
+      # resolve yet — which in Rails means a config/initializers file, since
+      # autoloading is set up after those run. Say where it does resolve.
+      if type.is_a?(String)
+        raise ArgumentError, "type: is the T::Enum itself, not its name — " \
+          "register_enum(#{@graphql_name.inspect}, #{type}). #{GraphWeaver::Codegen::AUTOLOAD_HINT}"
+      end
       unless type.is_a?(Class) && type < T::Enum
         raise ArgumentError, "type: must be a T::Enum subclass, got #{type.inspect}"
       end
@@ -32,7 +39,7 @@ class GraphWeaver::Codegen
       @type = type
       @map = map || {}
       @fallback = fallback
-      @requires = Array(requires)
+      @requires = GraphWeaver::Codegen.normalize_requires!(requires, load: true)
 
       if fallback && !type.values.include?(fallback)
         raise ArgumentError, "fallback: must be a #{type} member, got #{fallback.inspect}"
@@ -72,136 +79,30 @@ class GraphWeaver::Codegen
   end
 
   class << self
-    # Map a GraphQL enum onto an app-owned T::Enum (see EnumType); the
-    # global default — client.register_enum scopes to one client.
-    def register_enum(graphql_name, type, map: nil, fallback: nil, requires: nil)
-      enum_registry[graphql_name.to_s] = EnumType.new(graphql_name, type, map:, fallback:, requires:)
-    end
-
-    # Bulk, inference-only form: register_enums("Species" => PetKind, ...)
-    def register_enums(mappings)
-      mappings.each { |graphql_name, type| register_enum(graphql_name, type) }
-    end
-
-    def enum_registry
-      @enum_registry ||= {}
-    end
-
-    # Attach app-owned helper modules to every struct generated from a
-    # GraphQL type — the logic stays in your code, generation wires it in:
-    #
-    #      GraphWeaver.extend_type("Pet", PetHelpers)
-    #
-    # Or build the mixin inline — the block is module_eval'd into a fresh
-    # module auto-named GraphWeaver::TypeHelpers::<Type>. Handy for quick
-    # decoration; srb tc can't see into block-defined methods, so prefer
-    # a named module where static checking matters:
-    #
-    #      GraphWeaver.extend_type("Pet") do
-    #        def display_name = "#{name} the pet"
-    #      end
-    #
-    # Additive: repeated registrations (and client-scoped ones) stack.
+    # Map a GraphQL enum onto an app-owned T::Enum (see EnumType). The one
+    # implementation — GraphWeaver.register_enum is a delegate, so the same
+    # call reaches it whichever door you came in by.
     #
-    # 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"])
-    #
-    # A path segment is a field, or `first`/`last` to pick one element out of a
-    # list hop (always nilable): `alias: { entity: "_entities.first" }`.
-    #
-    # optional: true makes the aliases lenient — a query whose selection doesn't
-    # 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.
-    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:/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
-
-    # 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
-    ALIAS_NAME = /\A[a-zA-Z_]\w*[?!]?\z/
-    ALIAS_SEGMENT = /\A[a-zA-Z_]\w*\z/
-
-    # { accessor => { segments:, optional: } } from a path string (accessor
-    # named after the last segment), an array of such, or an { accessor => path }
-    # hash. `optional:` marks every alias in this registration as lenient.
-    def normalize_aliases(input, optional:)
-      pairs = case input
-      when nil then []
-      when String then [[input.split(".").last, input.split(".")]]
-      when Array then input.map { |path| [path.split(".").last, path.split(".")] }
-      when Hash then input.map { |name, path| [name.to_s, path.to_s.split(".")] }
-      else raise ArgumentError, "alias: expects a String, Array, or Hash, got #{input.class}"
+    # A value map is a natural third *positional* guess, and Ruby's arity
+    # complaint ("given 3, expected 2") never mentions the keyword.
+    def register_enum(graphql_name, type, positional_map = nil, map: nil, fallback: nil, requires: nil)
+      if positional_map
+        raise GraphWeaver::Error, "register_enum: the value map is a keyword — " \
+          "register_enum(#{graphql_name.inspect}, #{type}, map: {...})"
       end
-      pairs.to_h do |name, segments|
-        unless name.to_s.match?(ALIAS_NAME)
-          raise ArgumentError, "alias name #{name.inspect} is not a valid method name"
-        end
-        raise ArgumentError, "alias #{name.inspect} has an empty path" if segments.empty?
-
-        bad = segments.reject { |seg| seg.match?(ALIAS_SEGMENT) }
-        raise ArgumentError, "alias #{name.inspect} has an invalid path segment: #{bad.first.inspect}" if bad.any?
 
-        [name, { segments:, optional: }]
-      end
-    end
-
-    def type_registry
-      @type_registry ||= {}
+      enum_registry[graphql_name.to_s] = EnumType.new(graphql_name, type, map:, fallback:, requires:)
     end
 
-    # 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, aliases = {})
-      mixins = mixins.dup
-      mixins << helper_module(graphql_name, block) if block
-
-      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}"
-        end
-      end
-
-      entry[:mixins].concat(mixins)
-      entry[:requires].concat(Array(requires))
-      (entry[:aliases] ||= {}).merge!(aliases)
-      entry
+    def enum_registry
+      @enum_registry ||= {}
     end
 
-    # a block-built mixin needs a name generated files can reference:
-    # GraphWeaver::TypeHelpers::Pet (suffixed on re-registration)
-    def helper_module(graphql_name, block)
-      base = GraphWeaver::Inflect.camelize(graphql_name.to_s)
-      name = base
-      count = 1
-      name = "#{base}V#{count += 1}" while GraphWeaver::TypeHelpers.const_defined?(name, false)
-      GraphWeaver::TypeHelpers.const_set(name, Module.new(&block))
+    # Drop every register_enum mapping. No pair with a clear_ twin the way
+    # scalars have one: there are no built-in enums to restore.
+    def reset_enums!
+      enum_registry.clear
+      self
     end
-    private :helper_module
   end
 end
-
-module GraphWeaver
-  # Home of block-built type helpers (extend_type with a block), which
-  # need constant names so generated files can reference them.
-  module TypeHelpers; end
-end

data/lib/graph_weaver/codegen/nodes.rb

@@ -56,9 +56,9 @@ class GraphWeaver::Codegen
       !@scalar.serialize?
     end
 
-    # coercion (opt-in per scalar): accept the value or its raw input and
-    # normalize before serializing — parse for a rich type (coerce: true),
-    # or a plain conversion for built-ins (coerce: :to_f). See ScalarType.
+    # coercion (coerce: per scalar, or GraphWeaver.auto_coerce for all):
+    # accept the value or its raw input and normalize before serializing.
+    # See ScalarType#coercion.
     def coerce? = @scalar.coerce?
     def coerce(expr) = @scalar.coerce_input(expr)
     def coerce_input_type = @scalar.coerce_type
@@ -127,6 +127,19 @@ class GraphWeaver::Codegen
 
     def serialize_identity? = @of.serialize_identity?
 
+    # A list coerces exactly as its elements do, per element: `sort: ["POPULARITY_DESC"]`
+    # has to accept a wire string the way `type: "ANIME"` does. Sorbet's runtime
+    # doesn't check element types, so without this a String reached .serialize
+    # and raised a NoMethodError naming neither the variable nor the enum.
+    def coerce? = !hash_coerce_identity?
+    def coerce(expr) = hash_coerce(expr, 1)
+
+    def coerce_input_type
+      element = @of.coerce? ? @of.coerce_input_type : @of.prop_type
+      element = "T.nilable(#{element})" if @of.coerce? && !@of.non_null? && element != "T.untyped"
+      "T::Array[#{element}]"
+    end
+
     def hash_coerce(expr, depth)
       var = "v#{depth}"
       inner = if @of.non_null? || @of.hash_coerce_identity?
@@ -246,30 +259,45 @@ class GraphWeaver::Codegen
 
   # A single-condition narrowing of an abstract field (`... on Pet { ... }`
   # and nothing else): the member struct when the runtime type matches,
-  # nil when it doesn't — a non-match's response object carries no
-  # matching fields, so the hash arrives empty. Always nilable, whatever
-  # the schema's nullability, because narrowing filters.
+  # nil when it doesn't. Always nilable, whatever the schema's nullability,
+  # because narrowing filters.
+  #
+  # typename: is the member's GraphQL name when the selection also carries an
+  # unconditional `__typename` — then the match is read off the tag. Without
+  # it there is nothing to read but the object's emptiness: a non-match
+  # carries none of the selected fields, so the hash arrives empty.
   class NarrowedNode < Node
-    def initialize(of)
+    def initialize(of, typename: nil)
       @of = of
+      @typename = typename
     end
 
     def class_name = @of.class_name
     def bare_type = @of.bare_type
 
     def cast(expr, depth)
-      "(#{expr}.empty? ? nil : #{@of.cast(expr, depth)})"
+      if @typename
+        "(#{expr}[\"__typename\"] == #{@typename.inspect} ? #{@of.cast(expr, depth)} : nil)"
+      else
+        "(#{expr}.empty? ? nil : #{@of.cast(expr, depth)})"
+      end
     end
 
     def nested = @of
   end
 
   class UnionNode < Node
-    attr_reader :class_name, :members # graphql type name => ObjectNode
-
-    def initialize(class_name, members)
+    # class_name is writable: fields sharing one collapsed union settle on the
+    # alphabetically first of their keys, which the walk may reach second
+    attr_accessor :class_name
+    attr_reader :members # graphql type name => ObjectNode
+    # the struct an unnamed (or newly-added) __typename deserializes into
+    attr_reader :catch_all
+
+    def initialize(class_name, members, catch_all = nil)
       @class_name = class_name
       @members = members
+      @catch_all = catch_all
     end
 
     def bare_type = "#{class_name}::Type"
@@ -281,10 +309,10 @@ class GraphWeaver::Codegen
     def nested = self
   end
 
-  # A reference to a union hoisted into the shared unions module (a named
+  # A reference to a union hoisted into the shared types 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
+  # alias the query module gives GraphQLTypes::<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
@@ -309,10 +337,15 @@ class GraphWeaver::Codegen
     Field = Struct.new(:prop, :wire, :node, :required)
 
     attr_reader :class_name, :fields
+    # @oneOf: exactly one field may be supplied. The schema can't say so — every
+    # @oneOf field is nullable — so the generated struct carries the flag and
+    # InputStruct#serialize enforces it.
+    attr_accessor :one_of
 
     def initialize(class_name)
       @class_name = class_name
       @fields = []
+      @one_of = false
     end
 
     def bare_type = class_name
@@ -332,4 +365,30 @@ class GraphWeaver::Codegen
     # building a struct field from a caller-supplied plain hash value
     def hash_coerce(expr, _depth) = "#{class_name}.coerce(#{expr})"
   end
+
+  # One entity's `Representations` builder: the typed constructor for the
+  # references an `_entities(representations:)` query takes. `key_sets` are
+  # the type's @key field sets as dotted paths ("organization.id"), in
+  # declaration order; `params` the union of their top-level fields, which
+  # is what the generated method takes as kwargs. Not part of the node
+  # protocol — nothing casts or serializes through it — it's a shape emit
+  # walks, sitting beside the result tree rather than inside it.
+  class RepresentationNode
+    # `wire` is the GraphQL field name, `value` the emitted expression that
+    # puts the kwarg on the wire (a registered scalar serializes here)
+    Param = Struct.new(:kwarg, :wire, :type, :value, :required)
+
+    attr_reader :method_name, :graphql_type, :key_fields, :key_sets, :params
+
+    # key_fields are the @key(fields:) strings as written, kept for the
+    # comment above the builder — "organization { id }" reads better there
+    # than the flattened path it becomes
+    def initialize(method_name, graphql_type, key_fields, key_sets, params)
+      @method_name = method_name
+      @graphql_type = graphql_type
+      @key_fields = key_fields
+      @key_sets = key_sets
+      @params = params
+    end
+  end
 end

data/lib/graph_weaver/codegen/scalar_type.rb

@@ -4,7 +4,6 @@
 require "date"
 
 class GraphWeaver::Codegen
-
   # How one GraphQL scalar maps to Ruby: the Sorbet prop type, the
   # (optional) code emitted to deserialize a wire value into a rich Ruby
   # object and serialize it back, and any requires the generated file
@@ -46,14 +45,13 @@ class GraphWeaver::Codegen
         ->(type, expr) { "#{type}.dump(#{expr})" }),
     ].freeze
 
-    # Accepted kwarg types for Symbol (instance-method) coercion — the
-    # looser inputs the conversion sensibly handles. #to_s is defined on
-    # every object, so it accepts anything; #to_f/#to_i only make sense for
-    # numerics and strings.
-    CONVERT_INPUTS = {
-      to_f: "T.any(Float, Integer, String)",
-      to_i: "T.any(Integer, Float, String)",
-      to_s: "T.anything",
+    # How a built-in converts a loose variable input, and the widened kwarg
+    # it then accepts. Only the numerics can: a String/ID/Boolean input is
+    # already its own Ruby type, so there is nothing to convert.
+    Conversion = Struct.new(:via, :input_type)
+    CONVERSIONS = {
+      "Int" => Conversion.new(:to_i, "T.any(Integer, Float, String)"),
+      "Float" => Conversion.new(:to_f, "T.any(Float, Integer, String)"),
     }.freeze
 
     attr_reader :graphql_name, :type, :requires
@@ -73,49 +71,43 @@ class GraphWeaver::Codegen
       validate_coerce!
     end
 
-    # conversions applied to the four convertible built-ins when the
-    # global GraphWeaver.auto_coerce is on and no explicit coerce: given
-    AUTO_CONVERSIONS = {
-      "ID" => :to_s, "String" => :to_s, "Int" => :to_i, "Float" => :to_f,
-    }.freeze
-
     def cast(expr) = @cast&.call(expr)
     def cast? = !@cast.nil?
     def serialize(expr) = @serialize&.call(expr)
     def serialize? = !@serialize.nil?
-    def coerce? = !!effective_coerce
+    def coerce? = !!coercion
 
-    # Explicit coerce: always wins (false means never). Left unset, the
-    # global GraphWeaver.auto_coerce decides — resolved HERE, at
-    # generation time, so registration order doesn't matter: convertible
-    # built-ins get their conversion, anything with a full cast/serialize
-    # pair gets parse-style coercion.
-    def effective_coerce
-      return @coerce unless @coerce.nil?
-      return false unless GraphWeaver.auto_coerce
+    # How this scalar coerces a variable input, or nil for not at all.
+    # coerce: says WHETHER (explicit always wins); left unset the global
+    # GraphWeaver.auto_coerce decides — resolved HERE, at generation time,
+    # so registration order doesn't matter. The scalar itself says HOW: a
+    # convertible built-in converts, anything with a full cast/serialize
+    # pair parses. Nothing left to try means it can't coerce.
+    def coercion
+      return if @coerce == false
+      return if @coerce.nil? && !GraphWeaver.auto_coerce
 
-      AUTO_CONVERSIONS.fetch(@graphql_name) { (cast? && serialize?) || nil }
+      CONVERSIONS[@graphql_name] || (:parse if cast? && serialize?)
     end
 
-    # The code that normalizes a variable input before it's serialized. Two
-    # shapes: coerce: true parses a raw value into the rich type via the cast
-    # (guarded so an already-typed value passes through); coerce: :to_f (a
-    # Symbol) calls that instance method, for built-ins where a plain
-    # conversion is the whole story (5, "5" -> 5.0). serialize still runs
-    # afterward, but is identity for the conversion built-ins, so the
-    # converted value goes on the wire natively (a Float, not "5.0").
+    # The code that normalizes a variable input before it's serialized.
+    # Parsing runs a raw value through the cast, guarded so an already-typed
+    # value passes through; a conversion just calls the method (5, "5" ->
+    # 5.0). serialize still runs afterward, but is identity for the
+    # convertible built-ins, so the converted value goes on the wire
+    # natively (a Float, not "5.0").
     def coerce_input(expr)
-      case effective_coerce
-      when true then "(#{expr}.is_a?(#{@type}) ? #{expr} : #{cast(expr)})"
-      when Symbol then "#{expr}.#{effective_coerce}"
+      case (how = coercion)
+      when :parse then "(#{expr}.is_a?(#{@type}) ? #{expr} : #{cast(expr)})"
+      when Conversion then "#{expr}.#{how.via}"
       end
     end
 
     # the accepted Sorbet type for a coercible variable kwarg
     def coerce_type
-      case effective_coerce
-      when true then "T.any(#{@type}, String)"
-      when Symbol then CONVERT_INPUTS.fetch(effective_coerce, "T.untyped")
+      case (how = coercion)
+      when :parse then "T.any(#{@type}, String)"
+      when Conversion then how.input_type
       end
     end
 
@@ -156,20 +148,44 @@ class GraphWeaver::Codegen
       end
     end
 
-    # requires: is a require path or list of them; each must be a non-empty
-    # String (it is emitted verbatim as `require "..."`), caught here rather
-    # than as a syntax error in the generated file. When a real class was
-    # given as type:, we're in a runtime with its deps loaded, so we also
-    # `require` each path to prove it resolves (a no-op for already-loaded
-    # libs, and it surfaces a typo now). With only a type-name string we
-    # can't assume the lib is installed at codegen time, so we don't try.
+    # With only a type-name string we can't assume the lib is installed at
+    # codegen time, so the paths aren't loaded — only shape-checked.
     def normalize_requires(requires)
+      GraphWeaver::Codegen.normalize_requires!(requires, load: !@klass.nil?)
+    end
+
+    # coerce: true asks for something the scalar has to know how to do, so
+    # refuse a pass-through one now rather than emit a silent no-op.
+    def validate_coerce!
+      case @coerce
+      when false, nil then nil
+      when true
+        return if coercion
+
+        raise ArgumentError,
+          "coerce: true needs a cast and a serialize (#{@graphql_name} has neither, " \
+          "so there is nothing to coerce)"
+      else
+        raise ArgumentError, "coerce: must be true or false, got #{@coerce.inspect}"
+      end
+    end
+  end
+
+  class << self
+    # requires: is a require path or list of them; each must be a non-empty
+    # String (it is emitted verbatim as `require "..."` atop the generated
+    # file), caught here rather than as a syntax error in the generated file.
+    # load: when the registration handed us live constants — a class, a T::Enum,
+    # a helper module — we're in a runtime with its deps loaded, so each path is
+    # required to prove it resolves: a typo fails now, not in the generated file
+    # (a no-op for already-loaded libs).
+    def normalize_requires!(requires, load:)
       Array(requires).each do |req|
         unless req.is_a?(String) && !req.empty?
           raise ArgumentError, "requires: must be a String or Array of Strings, got #{req.inspect}"
         end
 
-        next unless @klass
+        next unless load
 
         begin
           require req
@@ -179,23 +195,6 @@ class GraphWeaver::Codegen
       end
     end
 
-    # coerce: true round-trips through cast+serialize, so it needs both; a
-    # Symbol is a self-contained conversion and needs neither.
-    def validate_coerce!
-      case @coerce
-      when false, nil, Symbol then nil
-      when true
-        return if cast? && serialize?
-
-        raise ArgumentError,
-          "coerce: true needs both a cast and a serialize (#{@graphql_name} is missing one)"
-      else
-        raise ArgumentError, "coerce: must be true, false, or a Symbol method name, got #{@coerce.inspect}"
-      end
-    end
-  end
-
-  class << self
     # Register (or override) how a GraphQL custom scalar deserializes into
     # a Ruby object and serializes back onto the wire. See ScalarType for
     # the accepted cast:/serialize:/requires: forms. Later registrations
@@ -242,9 +241,8 @@ class GraphWeaver::Codegen
     # matches nothing and leaves them identity — which is exactly why we
     # can name them with the real class constants. Date deserializes via
     # ISO-8601 (it *does* define .parse, but we want iso8601 specifically,
-    # so it's explicit). Input coercion is a generation-time concern:
-    # GraphWeaver.auto_coerce gives the convertible built-ins their
-    # conversion (see ScalarType::AUTO_CONVERSIONS).
+    # so it's explicit). Whether a variable of one accepts loose input is a
+    # separate, generation-time question — see coercion.
     def register_builtin_scalars!
       register_scalar "ID", String
       register_scalar "String", String
@@ -256,4 +254,9 @@ class GraphWeaver::Codegen
   end
 
   register_builtin_scalars!
+
+  # Pre-registered rather than user intent, so generation doesn't hold a schema
+  # to them (validate_registration! skips these). Read off the registry the line
+  # above just filled: a seventh built-in shouldn't have to be named twice.
+  BUILTIN_SCALARS = scalar_registry.keys.freeze
 end

data/lib/graph_weaver/codegen/type_helpers.rb

@@ -0,0 +1,140 @@
+# typed: true
+# frozen_string_literal: true
+
+# What `extend_type` registers, and where its block-built mixins land.
+#
+# Three things ride on one call — helper modules mixed into every struct
+# generated from a GraphQL type, the requires those modules need, and
+# alias: paths that flatten a nested selection onto a typed accessor. They
+# share a registry entry because they share a registration, and codegen
+# reads all three off the same type name (see Codegen::Aliases for how a
+# path is resolved against an actual selection).
+
+class GraphWeaver::Codegen
+  class << self
+    # Attach app-owned helper modules to every struct generated from a
+    # GraphQL type — the logic stays in your code, generation wires it in:
+    #
+    #      GraphWeaver.extend_type("Pet", PetHelpers)
+    #
+    # Or build the mixin inline — the block is module_eval'd into a fresh
+    # module auto-named GraphWeaver::TypeHelpers::<Type>. Handy for quick
+    # decoration; srb tc can't see into block-defined methods, so prefer
+    # a named module where static checking matters:
+    #
+    #      GraphWeaver.extend_type("Pet") do
+    #        def display_name = "#{name} the pet"
+    #      end
+    #
+    # Additive: repeated registrations (and client-scoped ones) stack.
+    #
+    # 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"])
+    #
+    # A path segment is a field, or `first`/`last` to pick one element out of a
+    # list hop (always nilable): `alias: { entity: "_entities.first" }`.
+    #
+    # optional: true makes the aliases lenient — a query whose selection doesn't
+    # 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.
+    def extend_type(graphql_name, *mixins, requires: nil, **kw, &block)
+      aliases = take_aliases(kw)
+      mixins = mixins.dup
+      mixins << helper_module(graphql_name, block) if block
+
+      raise ArgumentError, "pass one or more helper modules, a block, or alias:" if mixins.empty? && aliases.empty?
+      mixins.each do |mixin|
+        # a name rather than the module is what you write when the constant
+        # won't resolve yet — see EnumType for why that's a Rails initializer
+        if mixin.is_a?(String)
+          raise ArgumentError, "type helpers are the modules themselves, not their names — " \
+            "extend_type(#{graphql_name.to_s.inspect}, #{mixin}). #{GraphWeaver::Codegen::AUTOLOAD_HINT}"
+        end
+        unless mixin.is_a?(Module) && mixin.name
+          raise ArgumentError, "type helpers must be named modules, got #{mixin.inspect}"
+        end
+      end
+
+      entry = type_registry[graphql_name.to_s] ||= { mixins: [], requires: [], aliases: {} }
+      entry[:mixins].concat(mixins)
+      entry[:requires].concat(GraphWeaver::Codegen.normalize_requires!(requires, load: true))
+      entry[:aliases].merge!(aliases)
+      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
+    ALIAS_NAME = /\A[a-zA-Z_]\w*[?!]?\z/
+    ALIAS_SEGMENT = /\A[a-zA-Z_]\w*\z/
+
+    # { accessor => { segments:, optional: } } from a path string (accessor
+    # named after the last segment), an array of such, or an { accessor => path }
+    # hash. `optional:` marks every alias in this registration as lenient.
+    def normalize_aliases(input, optional:)
+      pairs = case input
+      when nil then []
+      when String then [[input.split(".").last, input.split(".")]]
+      when Array then input.map { |path| [path.split(".").last, path.split(".")] }
+      when Hash then input.map { |name, path| [name.to_s, path.to_s.split(".")] }
+      else raise ArgumentError, "alias: expects a String, Array, or Hash, got #{input.class}"
+      end
+      pairs.to_h do |name, segments|
+        unless name.to_s.match?(ALIAS_NAME)
+          raise ArgumentError, "alias name #{name.inspect} is not a valid method name"
+        end
+        raise ArgumentError, "alias #{name.inspect} has an empty path" if segments.empty?
+
+        bad = segments.reject { |seg| seg.match?(ALIAS_SEGMENT) }
+        raise ArgumentError, "alias #{name.inspect} has an invalid path segment: #{bad.first.inspect}" if bad.any?
+
+        [name, { segments:, optional: }]
+      end
+    end
+    private :normalize_aliases
+
+    def type_registry
+      @type_registry ||= {}
+    end
+
+    # Drop every extend_type registration (mixins, requires, alias: paths).
+    # The block-built mixin constants under GraphWeaver::TypeHelpers stay —
+    # generated files may still name them.
+    def reset_type_helpers!
+      type_registry.clear
+      self
+    end
+
+    # a block-built mixin needs a name generated files can reference:
+    # GraphWeaver::TypeHelpers::Pet (suffixed on re-registration)
+    def helper_module(graphql_name, block)
+      base = GraphWeaver::Inflect.camelize(graphql_name.to_s)
+      name = base
+      count = 1
+      name = "#{base}V#{count += 1}" while GraphWeaver::TypeHelpers.const_defined?(name, false)
+      GraphWeaver::TypeHelpers.const_set(name, Module.new(&block))
+    end
+    private :helper_module
+  end
+end
+
+module GraphWeaver
+  # Home of block-built type helpers (extend_type with a block), which
+  # need constant names so generated files can reference them.
+  module TypeHelpers; end
+end