graph_weaver 0.6.0 → 0.7.0

data/lib/generators/graph_weaver/install_generator.rb

@@ -69,10 +69,86 @@ module GraphWeaver
         create_file "graphql.config.yml", editor_config
       end
 
+      # Generated files are machine-written and say "do not edit", but plain
+      # `rubocop` still fires Style/Documentation, Style/ClassAndModuleChildren
+      # and Metrics/* on every one of them. Only an app that already lints is
+      # touched: writing a .rubocop.yml would turn rubocop on for a project
+      # that never asked for it.
+      def exclude_generated_from_rubocop
+        return unless File.exist?(rubocop_config)
+
+        body = File.read(rubocop_config)
+        # already excluded — a re-run, or done by hand
+        globs = generated_globs.reject { |glob| body.include?(glob) }
+        return if globs.empty?
+
+        entries = globs.map { |glob| "    - #{glob.inspect}" }.join("\n")
+        reason =
+          if body.match?(/^AllCops:/)
+            # rubocop takes the LAST of two duplicate keys, so appending a second
+            # AllCops: would replace the app's own rather than add to it
+            "sets AllCops already, and a second one would replace it rather than merge"
+          elsif yaml_documents(body) > 1
+            # rubocop reads only the first document, so the append lands where
+            # nothing will ever read it
+            "holds more than one YAML document, and rubocop reads only the first"
+          end
+
+        # Name the lines instead of guessing where inside theirs they belong.
+        if reason
+          say <<~TEXT
+
+            #{RUBOCOP_CONFIG} #{reason} — so add this under AllCops/Exclude:
+
+            #{entries}
+          TEXT
+        else
+          # inherit_mode is what makes this an addition: rubocop REPLACES an
+          # Exclude array on merge, so without it the block below wipes the
+          # effective list — rubocop's own vendor/node_modules/tmp defaults
+          # included, along with any Exclude reaching here through inherit_from.
+          append_to_file RUBOCOP_CONFIG, <<~YAML + entries + "\n"
+
+            # Machine-written by `rake graph_weaver:generate` — not yours to style.
+            AllCops:
+              inherit_mode:
+                merge:
+                  - Exclude
+              Exclude:
+          YAML
+        end
+      end
+
+      # The `graphql:` tags need this require, and it has to be somewhere
+      # rspec actually loads. A spec/support file is not: rspec-rails ships
+      # the spec/support glob commented out, so the require sat there doing
+      # nothing and a tagged example silently ran against the real client.
+      def wire_rspec
+        helper = RSPEC_HELPERS.find { |path| File.exist?(File.join(GraphWeaver.root, path)) }
+
+        unless helper
+          say "\nTesting: add `#{RSPEC_REQUIRE}` to your spec helper for the " \
+            "`graphql:` tags (docs/testing.md)."
+          return
+        end
+
+        body = File.read(File.join(GraphWeaver.root, helper))
+        return if body.match?(REQUIRED_ALREADY) # a re-run, or done by hand
+
+        # after rspec-rails' own require where there is one, at the end
+        # otherwise — either way top-level in a file every spec loads
+        if (anchor = body[RSPEC_RAILS_REQUIRE])
+          insert_into_file helper, "#{RSPEC_REQUIRE}\n", after: anchor
+        else
+          append_to_file helper, "\n#{RSPEC_REQUIRE}\n"
+        end
+      end
+
       # A url is introspected and a schema class dumped; a dump the app
       # already has is left where it is (schema_path points at it instead).
       def fetch_schema
         return unless options[:schema] && form != :path
+        return if keep_existing_dump
 
         if form == :url
           # pass the var name, not just the token — it lands in the dump's
@@ -114,6 +190,33 @@ module GraphWeaver
 
       private
 
+      RUBOCOP_CONFIG = ".rubocop.yml"
+
+      # rails_helper first: rspec-rails writes both, and only rails_helper
+      # has Rails booted by the time the require runs.
+      RSPEC_HELPERS = ["spec/rails_helper.rb", "spec/spec_helper.rb"].freeze
+      RSPEC_REQUIRE = 'require "graph_weaver/rspec"'
+      # the newline is part of the anchor: Thor inserts directly after the
+      # match, so without it the require lands on the end of that line
+      RSPEC_RAILS_REQUIRE = %r{^require ["']rspec/rails["'].*\n}
+      REQUIRED_ALREADY = %r{^\s*require ["']graph_weaver/rspec["']}
+
+      def rubocop_config = File.join(GraphWeaver.root, RUBOCOP_CONFIG)
+
+      # Parsed, not counted: a `---` can also be a line inside a block scalar.
+      # A file rubocop itself can't read is left to rubocop to complain about.
+      def yaml_documents(body)
+        YAML.parse_stream(body).children.size
+      rescue Psych::SyntaxError
+        1
+      end
+
+      # Every graph's output directory, so a multi-schema app is covered by
+      # the same run — read off the graphs rather than restated here.
+      def generated_globs
+        GraphWeaver.graphs.map { |graph| File.join(graph.output, "**/*") }.uniq
+      end
+
       # This install run is the one moment the user is guaranteed to be
       # reading, and a composed supergraph changes what the next steps are:
       # the test client is the interesting one, and there's a CI gate to add.
@@ -141,9 +244,13 @@ module GraphWeaver
 
         @subgraphs =
           begin
-            (GraphWeaver::SchemaLoader.routing_table(source).subgraphs if form == :path)
+            # asked, not rescued: the refusal writes a warn line as it is
+            # built, and "this isn't a supergraph" is the ordinary answer
+            if form == :path && GraphWeaver::SchemaLoader.routing_table?(source)
+              GraphWeaver::SchemaLoader.routing_table(source).subgraphs
+            end
           rescue StandardError
-            # not a supergraph, or not readable — nothing to say either way
+            # not readable — nothing to say either way
             nil
           end
       end
@@ -186,6 +293,33 @@ module GraphWeaver
 
       def auth_var = options[:auth] || GraphWeaver::SchemaLoader::DEFAULT_AUTH_ENV
 
+      # The dump is the one file the generator doesn't write through
+      # create_file, so Thor can't prompt on it — declining every conflict on
+      # a re-run still replaced it, and with it the source url it records.
+      # It is never overwritten here: `schema:refresh` is the command for
+      # that, and it re-fetches in place without touching anything else.
+      # True when there is one, having said so.
+      def keep_existing_dump
+        path = GraphWeaver::SchemaLoader.locate_path or return false
+
+        recorded = GraphWeaver::SchemaLoader.provenance(path)&.dig("url")
+        # a re-run naming a different endpoint would otherwise be answered
+        # silently by the dump the old one left
+        from = " (introspected from #{recorded})" if recorded && recorded != source
+        say_status :keep, "#{GraphWeaver::Internal::Util.relative(path)}#{from} — " \
+          "delete it and re-run to re-introspect", :yellow
+        true
+      end
+
+      # --auth is what says this API takes a token. Without it the line is
+      # shown rather than wired: a public API's initializer shouldn't read an
+      # ENV var nobody set, and the commented line is how you add one later.
+      def auth_setting
+        return %(auth: ENV["#{auth_var}"],) if options[:auth]
+
+        %(# auth: ENV["#{auth_var}"],  # uncomment when the API needs a token)
+      end
+
       # The command just typed, retyped. One rule for every source form, and
       # the only one that always works: the files already written come back
       # "identical", and --auth rides along — where schema:refresh has no flag
@@ -202,7 +336,7 @@ module GraphWeaver
           # Custom scalars, enums and type mixins go here — `rake graph_weaver:generate`
           # bakes them into the generated source, so they must be registered first:
           #
-          #   GraphWeaver.register_scalar("DateTime", Time, serialize: :iso8601, requires: "time")
+          #   GraphWeaver.register_scalar("Money", BigDecimal)
           #   GraphWeaver.extend_type("Person", Greetable)
         RUBY
       end
@@ -215,7 +349,7 @@ module GraphWeaver
           <<~RUBY
             GraphWeaver.client = GraphWeaver.new(
               "#{source}",
-              auth: ENV["#{auth_var}"],
+              #{auth_setting}
               cache: true, # reuse the committed dump; delete it to re-introspect
             )
           RUBY

data/lib/graph_weaver/client.rb

@@ -45,7 +45,7 @@ class GraphWeaver::Client
   private_constant :CONTEXT_IN_PROCESS, :RETRY_RULE
 
   def initialize(source, auth: nil, headers: {}, transport: nil, cache: nil, ttl: nil,
-    open_timeout: nil, read_timeout: nil, context: nil,
+    open_timeout: nil, read_timeout: nil, pool_size: nil, context: nil,
     retries: false, backoff: nil, base_delay: nil, max_delay: nil, jitter: nil, retry_on: nil,
     retry_if: nil, retry_codes: nil, retry_mutations: nil, sleeper: nil, &middleware)
     check_source!(source)
@@ -58,10 +58,11 @@ class GraphWeaver::Client
     if source.is_a?(String) && source.match?(URL)
       raise ArgumentError, CONTEXT_IN_PROCESS if context
 
-      built = build_transport(source, auth:, headers:, kind: transport, open_timeout:, read_timeout:, &middleware)
+      built = build_transport(source, auth:, headers:, kind: transport, open_timeout:, read_timeout:, pool_size:,
+        &middleware)
       @transport = wrap_retries(built, retries, retry_options)
     else
-      if auth || middleware || retries || open_timeout || read_timeout || !retry_options.empty?
+      if auth || middleware || retries || open_timeout || read_timeout || pool_size || !retry_options.empty?
         raise ArgumentError, "auth:/retries:/timeouts/middleware apply to a url — got a schema source"
       end
       if transport.is_a?(Symbol)
@@ -94,6 +95,27 @@ class GraphWeaver::Client
     @schema_lock = Mutex.new
   end
 
+  # Called by generated code — not semver'd for direct use.
+  #
+  # What actually runs a request, for anything in a client slot. A bare
+  # graphql-ruby schema class satisfies the execute contract on its own, so
+  # `client "Billing::Schema"`, `GraphWeaver.client = MyApp::Schema` and
+  # `execute!(client: MyApp::Schema)` all worked — and every one of them ran
+  # with no instrumentation seam at all: Schema.execute is not ours to
+  # bracket, so there was no APM event and no log line, not even at debug.
+  # One rule, applied wherever a client is read: a schema class gets the same
+  # InProcess wrapper GraphWeaver.new(Schema) builds. Everything else — a
+  # Client, a transport, a Retry, a fake — passes through untouched.
+  #
+  # Not memoized: the wrapper is two ivars beside a whole GraphQL execution,
+  # and in dev the class object is replaced on reload, so anything held onto
+  # would be the stale one.
+  def self.instrumented(client)
+    return client unless client.is_a?(Class) && client <= GraphQL::Schema
+
+    GraphWeaver::InProcess.new(client)
+  end
+
   # The transport queries run through: a url-built transport, an
   # explicit transport:, or the live schema class executing in-process.
   # Clients are self-contained — the app default never leaks in; nil for
@@ -165,15 +187,18 @@ class GraphWeaver::Client
   # it lets an unrelated gem swap your transport — along with its
   # timeouts and, since Faraday's default net_http adapter reconnects
   # per request, your connection reuse. Same code, same transport.
-  def build_transport(url, auth:, headers:, kind:, open_timeout: nil, read_timeout: nil, &middleware)
+  def build_transport(url, auth:, headers:, kind:, open_timeout: nil, read_timeout: nil, pool_size: nil, &middleware)
     headers = headers.dup
     if auth
-      unless auth.is_a?(String)
-        raise ArgumentError, "auth: takes a token string, got #{auth.class} — other headers go in " \
-          "headers:, and a token that rotates goes in the Faraday middleware block"
+      unless auth.is_a?(String) || auth.respond_to?(:call)
+        raise ArgumentError, "auth: takes a token string, or something answering #call that returns " \
+          "one per request, got #{auth.class} — other headers go in headers:"
       end
 
-      headers["Authorization"] ||= auth.include?(" ") ? auth : "Bearer #{auth}"
+      # a callable stays callable: both transports resolve a header value per
+      # request, which is what a token that expires needs
+      headers["Authorization"] ||=
+        auth.respond_to?(:call) ? -> { bearer(auth.call) } : bearer(auth)
     end
 
     # nil means "the transport's default" — both bundled ones agree on it
@@ -181,15 +206,27 @@ class GraphWeaver::Client
 
     transport =
       if transport_kind(kind, middleware) == :faraday
+        # Faraday's adapter owns its connections; a pool ceiling here would be
+        # a number nothing reads, so say so instead of dropping it
+        raise ArgumentError, "pool_size: sizes the bundled HTTP transport's pool — Faraday's adapter " \
+          "manages its own connections, so configure it there" if pool_size
         build_faraday(url, headers:, timeouts:, &middleware)
       else
-        GraphWeaver::Transport::HTTP.new(url, headers:, **timeouts)
+        GraphWeaver::Transport::HTTP.new(url, headers:, pool_size:, **timeouts)
       end
 
-    GraphWeaver::Internal::Log.log(:info) { "transport: #{transport.class} -> #{url}" }
+    GraphWeaver::Internal::Log.log(:info) { "transport: #{transport.class} -> #{transport.safe_url}" }
     transport
   end
 
+  # "Bearer" is assumed unless the token carries its own scheme; nil is a
+  # token the caller declined to produce, and drops the header.
+  def bearer(token)
+    return if token.nil?
+
+    token.to_s.include?(" ") ? token.to_s : "Bearer #{token}"
+  end
+
   # Which bundled transport a url client builds: the explicit
   # transport:, else Faraday when a middleware block asks for it.
   def transport_kind(kind, middleware)

data/lib/graph_weaver/codegen/aliases.rb

@@ -62,7 +62,7 @@ class GraphWeaver::Codegen
     # than the file.
     def check_alias_name!(node, name)
       taken = node.fields.any? { |f| f.prop == name } ||
-        STRUCT_METHODS.include?(name) || ALIAS_RESERVED.include?(name) ||
+        RESERVED_PROPS.include?(name) || ALIAS_RESERVED.include?(name) ||
         RUBY_KEYWORDS.include?(name)
       return unless taken
 
@@ -72,10 +72,10 @@ class GraphWeaver::Codegen
 
     # Registered aliases for a GraphQL type (see extend_type alias:).
     def type_aliases(graphql_name)
-      GraphWeaver::Codegen.type_registry[graphql_name]&.dig(:aliases) || {}
+      @registry.type_registry[graphql_name]&.dig(:aliases) || {}
     end
 
-    # The CLASS methods a generated struct defines; STRUCT_METHODS covers the
+    # The CLASS methods a generated struct defines; RESERVED_PROPS covers the
     # instance side, and both are checked with RUBY_KEYWORDS alongside (all
     # three are defined by the class this mixes into).
     ALIAS_RESERVED = %w[from_h].to_set.freeze
@@ -163,10 +163,12 @@ class GraphWeaver::Codegen
       type = obj.graphql_type && @schema.get_type(obj.graphql_type)
       return unless type.respond_to?(:fields)
 
-      known = type.fields.keys.map { |field| GraphWeaver::Inflect.underscore(field) }
+      # prop_name, not underscore: a path hops through PROPS, so a reserved
+      # field is spelled with its trailing underscore here too
+      known = type.fields.keys.map { |field| GraphWeaver::Codegen.prop_name(field) }
       return if seg == "__typename" || known.include?(seg)
 
-      prop = GraphWeaver::Inflect.underscore(seg)
+      prop = GraphWeaver::Codegen.prop_name(seg)
       hint = if prop != seg && known.include?(prop)
         # paths are the Ruby prop chain, not the GraphQL one — the classic miss
         " — GraphQL fields generate snake_case props; use '#{prop}'"

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.