graph_weaver 0.6.1 → 0.7.1

data/lib/graph_weaver/codegen/emit.rb

@@ -111,6 +111,15 @@ class GraphWeaver::Codegen
       }.uniq
     end
 
+    # `module A::B` does not define A, so a namespaced graph's file opens each
+    # outer segment first. A line apiece rather than nesting the whole body:
+    # the generated Ruby is then identical but for these, so adding a
+    # namespace: later diffs as additions.
+    def emit_namespace(out)
+      parts = @name.split("::")
+      (1...parts.size).each { |i| out << "module #{parts.first(i).join("::")}; end" }
+    end
+
     def emit_shared_aliases(out, names, namespace)
       return if names.empty?
 
@@ -148,6 +157,7 @@ class GraphWeaver::Codegen
         requires.each { |req| out << "require #{req.inspect}" }
         out << ""
       end
+      emit_namespace(out)
       out << "module #{@name}; end"
       out << ""
       if inputs.any?
@@ -184,6 +194,7 @@ class GraphWeaver::Codegen
       out << ""
       out << "# Generated by GraphWeaver #{GraphWeaver::VERSION} — do not edit."
       out << ""
+      emit_namespace(out)
       out << "module #{@name}"
       yield(out)
       out << "end"
@@ -225,6 +236,7 @@ class GraphWeaver::Codegen
         out << "require_relative \"types\""
         out << ""
       end
+      emit_namespace(out)
       out << "module #{@name}"
       out << "  extend T::Sig" << "" if GraphWeaver.extend_t_sig?
       # a GraphQL block string could contain a bare GRAPHQL line, which
@@ -233,7 +245,13 @@ class GraphWeaver::Codegen
       delimiter = "GRAPHQL"
       delimiter += "_" while @query.match?(/^\s*#{delimiter}\s*$/)
       out << "  QUERY = T.let(<<~'#{delimiter}', String)"
-      @query.each_line { |line| out << "    #{line}".rstrip }
+      # only the line's own newline comes off: trailing whitespace is part of a
+      # block-string argument's value, and <<~ takes the indent back off again.
+      # An empty line has no content to indent, so it stays empty.
+      @query.each_line do |line|
+        content = line.chomp
+        out << (content.empty? ? "" : "    #{content}")
+      end
       out << "  #{delimiter}"
       out << ""
       out << "  # sent as the request's operationName — what an APM keys traces on"
@@ -345,6 +363,7 @@ class GraphWeaver::Codegen
       out << "#{pad}class #{node.class_name} < T::Struct"
       out << "#{pad}  extend T::Sig" if GraphWeaver.extend_t_sig?
       out << "#{pad}  include GraphWeaver::Hints"
+      out << "#{pad}  include GraphWeaver::ResultStruct"
       node.mixins.each do |mixin|
         out << "#{pad}  include #{mixin} # registered for #{node.graphql_type}"
       end
@@ -362,6 +381,8 @@ class GraphWeaver::Codegen
       end
 
       node.fields.each do |field|
+        note = renamed_note(field.prop, field.key)
+        out << "#{pad}  #{note}" if note
         out << "#{pad}  const :#{field.prop}, #{field.node.prop_type}"
       end
 
@@ -376,10 +397,23 @@ class GraphWeaver::Codegen
       out << "#{pad}  rescue GraphWeaver::Error"
       out << "#{pad}    raise # already branded by a nested struct or leaf — keep the innermost context"
       out << "#{pad}  rescue StandardError => e" # sorbet's prop check, mostly
-      out << "#{pad}    raise GraphWeaver::TypeError.new(struct: self, " \
+      out << "#{pad}    raise GraphWeaver::CastError.new(struct: self, " \
         "message: GraphWeaver::Hints.cast_message(self, data, e))"
       out << "#{pad}  end"
 
+      # the mirror of from_h: the response keys, each leaf back through its
+      # scalar's serialize:, so from_h reads what as_json wrote. Rails calls
+      # it for `render json:`, and ResultStruct#to_json goes through it.
+      out << ""
+      out << "#{pad}  sig { params(_options: T.untyped).returns(T::Hash[String, T.untyped]) }"
+      out << "#{pad}  def as_json(*_options)"
+      out << "#{pad}    {"
+      node.fields.each do |field|
+        out << "#{pad}      #{field.key.inspect} => #{field_json(field)},"
+      end
+      out << "#{pad}    }"
+      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|
@@ -396,7 +430,7 @@ class GraphWeaver::Codegen
       out << "#{pad}module #{node.class_name}"
       out << "#{pad}  extend T::Sig" << "" if GraphWeaver.extend_t_sig?
 
-      structs = node.members.values + [node.catch_all].compact
+      structs = node.members.values + [node.catch_all]
       structs.each do |member|
         emit_object(member, out, indent + 1)
         out << ""
@@ -408,21 +442,14 @@ class GraphWeaver::Codegen
       out << ""
       out << "#{pad}  sig { params(data: T::Hash[String, T.untyped]).returns(Type) }"
       out << "#{pad}  def self.from_h(data)"
-      if node.catch_all
-        out << "#{pad}    case data.fetch(\"__typename\")"
-      else
-        out << "#{pad}    case (typename = data.fetch(\"__typename\"))"
-      end
+      out << "#{pad}    case data.fetch(\"__typename\")"
       node.members.each do |graphql_name, member|
         out << "#{pad}    when #{graphql_name.inspect} then #{member.class_name}.from_h(data)"
       end
-      if node.catch_all
-        out << "#{pad}    # a member this query names no fields on — including one the"
-        out << "#{pad}    # schema grew since generation"
-        out << "#{pad}    else #{node.catch_all.class_name}.from_h(data)"
-      else
-        out << "#{pad}    else raise GraphWeaver::TypeError.new(struct: self, message: \"unexpected __typename: \#{typename}\")"
-      end
+      # every dispatch has a catch-all, so no __typename is unexpected
+      out << "#{pad}    # a member this query names no fields on — including one the"
+      out << "#{pad}    # schema grew since generation"
+      out << "#{pad}    else #{node.catch_all.class_name}.from_h(data)"
       out << "#{pad}    end"
       out << "#{pad}  end"
       out << "#{pad}end"
@@ -432,6 +459,13 @@ class GraphWeaver::Codegen
       # client/client= carry no per-query types, so they live in the gem
       out << "  # client / client= — see GraphWeaver::QueryModule"
       out << "  extend GraphWeaver::QueryModule"
+      if @graph_name
+        out << ""
+        out << "  # the graph this module was generated from — what a test mode builds"
+        out << "  # its stand-in client from"
+        out << "  GRAPH = T.let(#{@graph_name.inspect}, Symbol)"
+        out << "  private_constant :GRAPH"
+      end
       if @client_const
         out << ""
         out << "  # the baked default client, resolved on first use"
@@ -474,12 +508,15 @@ class GraphWeaver::Codegen
           flag ? "#{var.kwarg}: (#{flag} = true; nil)" : "#{var.kwarg}: nil"
         } + ["client: nil"]
 
-      call = "client_for(client).execute(QUERY, variables:, operation_name: OPERATION_NAME)"
+      # QueryModule#dispatch reads QUERY/OPERATION_NAME/GRAPH off the module,
+      # so the gem gets to bracket every request without a line of it landing
+      # in every generated file
+      call = "dispatch(variables, client:)"
 
       # execute returns the full envelope; execute! is the strict shortcut for
       # the typed result, or a raised QueryError.
-      out << "  # .checked(:never): an untyped value (a Rails param) reaches the coercion below"
-      out << "  # instead of sorbet-runtime's argument check; srb tc still holds typed call sites."
+      out << "  # .checked(:never): an untyped value (a Rails param) reaches the coercion"
+      out << "  # below instead of being rejected by sorbet-runtime's argument check."
       out << "  sig { params(#{sig_params.join(", ")}).returns(GraphWeaver::Response[Result]).checked(:never) }"
       out << "  def self.execute(#{kwargs.join(", ")})"
       emit_variables(out, required, optional, omitted)
@@ -558,16 +595,16 @@ class GraphWeaver::Codegen
 
     # A kwarg's trip onto the wire: normalize whatever arrived into the type
     # the sig promises — the sig itself is `.checked(:never)`, so this is the
-    # check — then serialize. Coercion is wrapped so a refusal names the
-    # variable and the operation; the value alone locates nothing.
+    # check — then serialize. The whole trip runs inside Coerce.variable, so a
+    # refusal from either half names the variable and the operation; the value
+    # alone locates nothing. (A serializer raising used to escape bare: a cast
+    # that answers nil hands `nil.upcase` to whatever called execute.)
     def variable_serialize(var)
-      value = if var.node.coerce?
-        "GraphWeaver::Coerce.variable(#{var.wire.inspect}, OPERATION_NAME, #{var.kwarg}) " \
-          "{ |v| #{var.node.coerce("v")} }"
-      else
-        var.kwarg
-      end
-      var.node.serialize_identity? ? value : var.node.serialize(value, 1)
+      return var.kwarg if !var.node.coerce? && var.node.serialize_identity?
+
+      value = var.node.coerce? ? var.node.coerce("v") : "v"
+      value = var.node.serialize(value, 1) unless var.node.serialize_identity?
+      "GraphWeaver::Coerce.variable(#{var.wire.inspect}, OPERATION_NAME, #{var.kwarg}) { |v| #{value} }"
     end
 
     def field_cast(field)
@@ -588,6 +625,30 @@ class GraphWeaver::Codegen
       "GraphWeaver::Hints.field(self, #{field.key.inspect}) { #{cast} }"
     end
 
+    # One prop written back the way the server spelled it. The inverse of
+    # field_cast, minus its branding: rendering a value the library already
+    # cast can't fail on the value, only on a registration whose serialize:
+    # raises — which is the app's own code and says so.
+    def field_json(field)
+      node = field.node
+      # a prop is only ever read off a receiver, which is what lets `next` and
+      # `end` be props at all (see RUBY_KEYWORDS) — so here the receiver is us
+      prop = RUBY_KEYWORDS.include?(field.prop) ? "self.#{field.prop}" : field.prop
+      return prop if node.serialize_identity?
+      return node.serialize(prop, 1) if node.non_null?
+
+      "#{prop}&.then { |v1| #{node.serialize("v1", 2)} }"
+    end
+
+    # Why a prop is spelled unlike its wire name, for the one case a reader
+    # can't infer: a reserved name took a trailing underscore. camelCase →
+    # snake_case is the rule the whole file follows, and the wire key is
+    # already spelled out beside it (from_h's `data[...]`, a FIELDS row), so
+    # noting every prop would be noise.
+    def renamed_note(prop, wire)
+      "# wire: #{wire} — reserved as a prop name" if prop == "#{underscore(wire)}_"
+    end
+
     # A module-level T::Struct per input type: typed consts plus a FIELDS
     # table the GraphWeaver::InputStruct runtime drives — serialize/to_h/
     # coerce live once in the gem, not unrolled per struct (bool_exp
@@ -599,6 +660,11 @@ class GraphWeaver::Codegen
       out << "#{pad}  include GraphWeaver::InputStruct"
       out << "#{pad}  extend GraphWeaver::InputStruct::ClassMethods"
       out << ""
+      # the schema's name for this type, so a refusal reports GraphQL
+      # vocabulary rather than the Ruby class generation happened to pick
+      out << "#{pad}  GRAPHQL_NAME = T.let(#{node.graphql_name.inspect}, String)"
+      out << "#{pad}  private_constant :GRAPHQL_NAME"
+      out << ""
       if node.one_of
         out << "#{pad}  # @oneOf: every field is nullable, so exactly-one is checked at runtime"
         out << "#{pad}  ONE_OF = T.let(true, T::Boolean)"
@@ -612,15 +678,18 @@ class GraphWeaver::Codegen
         type = field.node.prop_type
         type = "T.nilable(#{type})" if !field.required && field.node.non_null? && type != "T.untyped"
         default = field.required ? "" : ", default: nil"
+        note = renamed_note(field.prop, field.wire)
+        out << "#{pad}  #{note}" if note
         out << "#{pad}  const :#{field.prop}, #{type}#{default}"
       end
       out << ""
-      out << "#{pad}  # (prop, wire, required, serializer, coercer) per field"
+      out << "#{pad}  # (prop, wire, required, serializer, coercer, coordinate) per field"
       out << "#{pad}  FIELDS = T.let(["
       node.fields.each do |field|
         serializer = field.node.serialize_identity? ? "nil" : "->(v) { #{field.node.serialize("v", 1)} }"
         coercer = field.node.hash_coerce_identity? ? "nil" : "->(v) { #{field.node.hash_coerce("v", 1)} }"
-        out << "#{pad}    GraphWeaver::InputStruct::Field.new(:#{field.prop}, #{field.wire.inspect}, #{field.required}, #{serializer}, #{coercer}),"
+        coordinate = "#{node.graphql_name}.#{field.wire}"
+        out << "#{pad}    GraphWeaver::InputStruct::Field.new(:#{field.prop}, #{field.wire.inspect}, #{field.required}, #{serializer}, #{coercer}, #{coordinate.inspect}),"
       end
       out << "#{pad}  ].freeze, T::Array[GraphWeaver::InputStruct::Field])"
       # InputStruct reads it with const_get, which privacy doesn't block

data/lib/graph_weaver/codegen/enum_type.rb

@@ -78,7 +78,8 @@ class GraphWeaver::Codegen
     end
   end
 
-  class << self
+  # The enum half of one graph's registrations — see Codegen::Registry.
+  class Registry
     # 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.

data/lib/graph_weaver/codegen/nodes.rb

@@ -158,8 +158,12 @@ class GraphWeaver::Codegen
       else
         "#{var}&.then { |v#{depth + 1}| #{@of.hash_coerce("v#{depth + 1}", depth + 2)} }"
       end
+      return "#{expr}.map { |#{var}| #{inner} }" if hash_coerce_identity?
 
-      "#{expr}.map { |#{var}| #{inner} }"
+      # the index is a path segment — `where._and.0._not.species` needs the 0
+      # to name one form field
+      idx = "i#{depth}"
+      "#{expr}.map.with_index { |#{var}, #{idx}| GraphWeaver::InputStruct.element(#{idx}, #{var}) { #{inner} } }"
     end
 
     def hash_coerce_identity? = @of.hash_coerce_identity?
@@ -190,6 +194,11 @@ class GraphWeaver::Codegen
       "#{class_name}.from_h(#{expr})"
     end
 
+    # a composite renders itself — #as_json is the mirror of .from_h
+    def serialize(expr, _depth)
+      "#{expr}.as_json"
+    end
+
     def nested = self
   end
 
@@ -253,8 +262,16 @@ class GraphWeaver::Codegen
       end
     end
 
+    # The fallback member is in no wire table — several wire values collapse
+    # into it, so `invert` keeps none — and it is exactly the member a drifted
+    # response casts to. Its own #serialize is the only spelling left, and it
+    # casts back to the fallback, so a result still round-trips through
+    # #as_json. Without a fallback the table is total and a miss is a real
+    # mistake, so it still raises.
     def serialize(expr, _depth)
-      "#{const_prefix}_TO_WIRE.fetch(#{expr})"
+      return "#{const_prefix}_TO_WIRE.fetch(#{expr})" unless @fallback
+
+      "#{const_prefix}_TO_WIRE.fetch(#{expr}) { |member| member.serialize }"
     end
 
     def leaf? = true
@@ -298,6 +315,8 @@ class GraphWeaver::Codegen
       end
     end
 
+    def serialize(expr, depth) = @of.serialize(expr, depth)
+    def serialize_identity? = @of.serialize_identity?
     def nested = @of
   end
 
@@ -306,10 +325,13 @@ class GraphWeaver::Codegen
     # 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
+    # The struct an unnamed (or newly-added) __typename deserializes into.
+    # Required, not defaulted: a dispatch without one has to refuse a member
+    # the schema grew, and "the query named every member today" is not a
+    # reason to break tomorrow's response.
     attr_reader :catch_all
 
-    def initialize(class_name, members, catch_all = nil)
+    def initialize(class_name, members, catch_all)
       @class_name = class_name
       @members = members
       @catch_all = catch_all
@@ -321,6 +343,10 @@ class GraphWeaver::Codegen
       "#{class_name}.from_h(#{expr})"
     end
 
+    def serialize(expr, _depth)
+      "#{expr}.as_json"
+    end
+
     def nested = self
   end
 
@@ -342,6 +368,10 @@ class GraphWeaver::Codegen
     def cast(expr, _depth)
       "#{class_name}.from_h(#{expr})"
     end
+
+    def serialize(expr, _depth)
+      "#{expr}.as_json"
+    end
   end
 
   # An input-object variable: emitted as a module-level T::Struct whose
@@ -351,14 +381,17 @@ class GraphWeaver::Codegen
   class InputNode < Node
     Field = Struct.new(:prop, :wire, :node, :required)
 
-    attr_reader :class_name, :fields
+    # graphql_name as well as class_name: a schema coordinate is spelled the
+    # schema's way (pokemon_bool_exp.name), which camelize has already lost.
+    attr_reader :class_name, :graphql_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)
+    def initialize(class_name, graphql_name = class_name)
       @class_name = class_name
+      @graphql_name = graphql_name
       @fields = []
       @one_of = false
     end

data/lib/graph_weaver/codegen/registry.rb

@@ -0,0 +1,175 @@
+# typed: true
+# frozen_string_literal: true
+
+# One graph's registrations: the scalar codecs, the enum mappings, and the
+# type helpers a generation reads. The three tables move together because a
+# registration is scoped to the schema it describes — an app with two schemas
+# registers `Money` for each, or for only one, and neither answer is the
+# other's (see GraphWeaver.graph).
+#
+# The methods themselves live in Registrations, which the three codegen/*.rb
+# files fill in; this is where they get somewhere to write. Codegen's class
+# methods (GraphWeaver.register_scalar and friends) delegate here, to the
+# default graph's registry — so a single-schema app never meets this class.
+
+class GraphWeaver::Codegen
+  # The registrations one graph generates with: the scalar codecs, the enum
+  # mappings and the type helpers, plus what a schema can say about them.
+  # Not API (private_constant below) — an app writes register_scalar/
+  # register_enum/extend_type, at the top level (the default graph) or in a
+  # graph block, and never names the object holding them.
+  # codegen/{scalar,enum,type_helpers}.rb fill in the registering half.
+  class Registry
+    # What a registry's names must be in the schema. extend_type decorates
+    # whatever composite a query reaches, so it demands no particular kind.
+    REGISTERED_KIND = { "scalar" => "SCALAR", "enum" => "ENUM" }.freeze
+    # the type registry is reached via extend_type; scalars/enums via register_*
+    REGISTRATION_METHOD = { "type" => "extend_type", "scalar" => "register_scalar", "enum" => "register_enum" }.freeze
+    private_constant :REGISTERED_KIND, :REGISTRATION_METHOD
+
+    # Every registration this schema can't match, one sentence each. The answer
+    # depends on the schema and the registry alone, not on any one document, so
+    # a whole generate! run gets the same list — which is what lets the build
+    # report it once (see GraphWeaver.unmatched_registrations).
+    #
+    # The built-in scalars are pre-registered entries in the same table rather
+    # than user intent, so they're exempt — a schema with no Date scalar is not
+    # a mistake.
+    def unmatched_registrations(schema)
+      {
+        "enum" => enum_registry,
+        "scalar" => scalar_registry.except(*BUILTIN_SCALARS),
+        "type" => type_registry,
+      }.flat_map do |kind, registry|
+        registry.keys.filter_map { |name| validate_registration!(schema, kind, name) }
+      end
+    end
+
+    # A registry serves one graph, but a generation sees one schema — so a
+    # registration fails generation only where THIS schema can disprove it: a
+    # name it declares as something else, or a coordinate whose field it declares
+    # as a composite. A name it can't match at all proves nothing, because an
+    # entity type is declared by every subgraph that references it while its
+    # fields are split among them; that returns the sentence to say instead.
+    def validate_registration!(schema, kind, name)
+      method = REGISTRATION_METHOD.fetch(kind)
+      # register_scalar("Type.field", ...) overrides one field's scalar — validate
+      # the field, not that a type named "Type.field" exists.
+      return validate_scalar_field!(schema, name, method) if kind == "scalar" && name.include?(".")
+
+      type = schema.get_type(name)
+      unless type
+        return unmatched(schema, method, name, kind, GraphWeaver::Internal::Util.did_you_mean(schema.types.keys, name))
+      end
+
+      expected = REGISTERED_KIND[kind]
+      return if expected.nil? || type.kind.name == expected
+
+      found = type.kind.name.downcase.tr("_", " ")
+      # a leaf registered as the other kind has a method that would have worked
+      other = REGISTERED_KIND.key(type.kind.name)
+      raise GraphWeaver::Error,
+        "#{method}(#{name.inspect}) names #{article(found)} #{found}, not #{article(kind)} " \
+        "#{kind}#{other ? " — use #{REGISTRATION_METHOD.fetch(other)}" : ""}"
+    end
+    private :validate_registration!
+
+    # A per-field override, register_scalar("Type.field", ...). Neither an absent
+    # type nor an absent field is disprovable here; what is, is a field this
+    # schema declares as something a scalar codec could never read.
+    def validate_scalar_field!(schema, name, method)
+      type_name, field_name = name.split(".", 2)
+      type = schema.get_type(type_name)
+      unless type
+        near = GraphWeaver::Internal::Util.did_you_mean(schema.types.keys, type_name)
+        return unmatched(schema, method, name, "scalar field", near && "#{near}.#{field_name}")
+      end
+
+      fields = type.respond_to?(:fields) ? type.fields : {}
+      field = fields[field_name]
+      unless field
+        near = GraphWeaver::Internal::Util.did_you_mean(fields.keys, field_name)
+        return unmatched(schema, method, name, "scalar field", near && "#{type_name}.#{near}")
+      end
+      return if field.type.unwrap.kind.name == "SCALAR"
+
+      raise GraphWeaver::Error,
+        "#{method}(#{name.inspect}): #{name} isn't a scalar field (it's #{field.type.unwrap.kind.name.downcase})"
+    end
+    private :validate_scalar_field!
+
+    # What to say about a name this schema has nothing for. Registrations are
+    # graph-scoped — federation composes by name, so one `Money` codec serves
+    # every subgraph that declares it — which is exactly why this schema can't
+    # tell a typo from a registration for the subgraph next door. Say both.
+    def unmatched(schema, method, name, what, suggestion)
+      hint = suggestion ? " (did you mean '#{suggestion}'?)" : ""
+      "#{method}(#{name.inspect}) matches no #{what} in #{schema.name || "this schema"} " \
+        "— a typo#{hint}, or a registration for another schema"
+    end
+    private :unmatched
+
+    def article(word) = GraphWeaver::Internal::Util.article(word)
+    private :article
+
+    # Every table back to its starting state — scalars (built-ins restored),
+    # enum mappings, and type helpers. The clean slate between tests, and the
+    # one call that stays right when a fourth kind of registration shows up.
+    def reset_registrations!
+      reset_scalars!
+      reset_enums!
+      reset_type_helpers!
+      self
+    end
+
+    def initialize = register_builtin_scalars!
+
+    # A graph starts from the top-level registrations and adds its own, so the
+    # three tables are copied rather than shared — an app that registered Money
+    # before it had a second schema keeps it, and a graph block can't reach back.
+    def initialize_copy(other)
+      super
+      @scalar_registry = other.scalar_registry.dup
+      @enum_registry = other.enum_registry.dup
+      # the entry is a hash of mutable arrays, so each one is copied too
+      @type_registry = other.type_registry.transform_values { |e| e.transform_values(&:dup) }
+      @helper_counts = other.send(:helper_counts).dup
+    end
+  end
+
+  # The default graph's registrations — where a top-level
+  # GraphWeaver.register_scalar writes, and what a generation uses unless a
+  # graph hands it its own.
+  def self.registry = @registry ||= Registry.new
+
+  # Pre-registered rather than user intent, so generation doesn't hold a schema
+  # to them (validate_registration! skips these). Read off a fresh registry: a
+  # seventh built-in shouldn't have to be named twice.
+  BUILTIN_SCALARS = Registry.new.scalar_registry.keys.freeze
+
+  class << self
+    # The default graph's registry answers every one of these — the surface an
+    # app has used since before graphs existed, unchanged.
+    def register_scalar(...) = registry.register_scalar(...)
+    def register_enum(...) = registry.register_enum(...)
+    def extend_type(...) = registry.extend_type(...)
+    def scalar(...) = registry.scalar(...)
+    def scalar_registry = registry.scalar_registry
+    def enum_registry = registry.enum_registry
+    def type_registry = registry.type_registry
+    def unmatched_registrations(...) = registry.unmatched_registrations(...)
+    def clear_scalars! = registry.clear_scalars! && self
+    def reset_scalars! = registry.reset_scalars! && self
+    def reset_enums! = registry.reset_enums! && self
+    def reset_type_helpers! = registry.reset_type_helpers! && self
+
+    # Returns Codegen, not the registry: these are the documented calls, and
+    # their value has always been something you can keep chaining off.
+    def reset_registrations! = registry.reset_registrations! && self
+  end
+
+  # Nothing outside the gem names it, and it can't move under Internal either:
+  # its methods build a ScalarType and an EnumType, which are private here.
+  # Private at load, not in a method body — see spec/registry_spec.rb.
+  private_constant :Registry
+end