graph_weaver 0.6.1 → 0.7.1

data/examples/github/queries/stargazers.graphql

@@ -0,0 +1,22 @@
+query($owner: String!, $name: String!, $first: Int!) {
+  repository(owner: $owner, name: $name) {
+    id
+    nameWithOwner
+    stargazerCount
+    stargazers(first: $first, orderBy: { field: STARRED_AT, direction: DESC }) {
+      edges {
+        starredAt
+        node {
+          login
+          name
+          repositories(first: 2, orderBy: { field: STARGAZERS, direction: DESC }) {
+            nodes {
+              nameWithOwner
+              stargazerCount
+            }
+          }
+        }
+      }
+    }
+  }
+}

data/examples/github/queries/starred.graphql

@@ -0,0 +1,11 @@
+query($login: String!, $first: Int!) {
+  user(login: $login) {
+    starredRepositories(first: $first, orderBy: { field: STARRED_AT, direction: DESC }) {
+      totalCount
+      nodes {
+        nameWithOwner
+        stargazerCount
+      }
+    }
+  }
+}

data/examples/github/run.rb

@@ -0,0 +1,43 @@
+#!/usr/bin/env ruby
+# typed: false
+# frozen_string_literal: true
+
+# Star graph_weaver ⭐ (thanks!), then meet your fellow stargazers —
+# who they are, their biggest repos, and what else they've starred:
+#
+#      examples/github/run.rb
+require_relative "setup"
+
+# the checked-in typed modules (regenerate: examples/github/generate.rb)
+Dir[File.join(__dir__, "generated", "*.rb")].sort.each { |file| require file }
+
+OWNER = "dpep"
+NAME = "graph_weaver"
+
+repo = StargazersQuery.execute!(owner: OWNER, name: NAME, first: 1).repository
+abort "repository not found" unless repo
+
+# join the club (idempotent — starring twice is fine)
+starrable = StarMutation.execute!(id: repo.id).add_star&.starrable
+puts "⭐ starred #{repo.name_with_owner} — #{starrable&.stargazer_count} star(s). Thanks!"
+
+# refreshed, so the list includes you
+repo = StargazersQuery.execute!(owner: OWNER, name: NAME, first: 10).repository
+
+puts "\nThe stargazers:"
+repo.stargazers.edges&.each do |edge|
+  gazer = edge&.node
+  next unless gazer
+
+  who = gazer.name ? "#{gazer.login} (#{gazer.name})" : gazer.login
+  top = gazer.repositories.nodes&.compact&.map { |r| "#{r.name_with_owner} ⭐#{r.stargazer_count}" }
+  puts "  #{who} — starred #{edge.starred_at&.strftime("%Y-%m-%d")}"
+  puts "    top repos: #{top.join(", ")}" if top&.any?
+
+  # drill down: what else have they starred lately?
+  starred = StarredQuery.execute!(login: gazer.login, first: 3).user&.starred_repositories
+  next unless starred
+
+  also = starred.nodes&.compact&.reject { |r| r.name_with_owner == repo.name_with_owner }
+  puts "    also starred (#{starred.total_count} total): #{also.map(&:name_with_owner).join(", ")}" if also&.any?
+end

data/examples/github/setup.rb

@@ -0,0 +1,18 @@
+# typed: false
+# frozen_string_literal: true
+
+# Shared wiring for the GitHub example: auth and the client.
+require_relative "../../lib/graph_weaver"
+
+token = ENV["GITHUB_TOKEN"] || `gh auth token 2>/dev/null`.strip
+abort "need a token: `gh auth login`, or GITHUB_TOKEN=..." if token.empty?
+
+GraphWeaver.client = GraphWeaver.new(
+  "https://api.github.com/graphql",
+  auth: token,
+  # used by generate.rb (and any dynamic parse): the first introspection
+  # of GitHub's large schema dumps here — gitignored, a few seconds once,
+  # instant after. run.rb's checked-in generated modules never introspect,
+  # so running it alone won't create this file.
+  cache: File.join(__dir__, "schema.json"),
+)

data/examples/rick_and_morty.rb

@@ -0,0 +1,57 @@
+#!/usr/bin/env ruby
+# typed: false
+# frozen_string_literal: true
+
+# One notch up from countries.rb: filtered search, pagination, an aliased
+# field, and a block-built type helper — against the Rick and Morty API
+# (free, no auth, wubba lubba dub dub):
+#
+#      examples/rick_and_morty.rb [NAME]
+#      examples/rick_and_morty.rb morty
+require_relative "../lib/graph_weaver"
+
+api = GraphWeaver.new("https://rickandmortyapi.com/graphql")
+
+# decorate every Character struct generated from this type — derived values
+# live as methods, the wire data stays honest
+GraphWeaver.extend_type("Character") do
+  def emoji
+    { "Alive" => "🟢", "Dead" => "💀" }.fetch(status, "❓")
+  end
+end
+
+CharacterQuery = api.parse(<<~GRAPHQL)
+  query($name: String, $page: Int) {
+    characters(page: $page, filter: { name: $name }) {
+      # a GraphQL alias names the prop: `info.next_page`, not `info.next`
+      info { count pages nextPage: next }
+      results {
+        name
+        status
+        species
+        origin { name }
+        episode { name }
+      }
+    }
+  }
+GRAPHQL
+
+name = ARGV.first || "smith"
+page = 1
+total = nil
+
+loop do
+  characters = CharacterQuery.execute!(name:, page:).characters
+  abort "no characters match #{name.inspect}" if characters&.results.to_a.empty?
+
+  total ||= characters.info&.count
+  characters.results.compact.each do |character|
+    debut = character.episode.compact.first&.name
+    puts "#{character.emoji} #{character.name} — #{character.species} from #{character.origin&.name}, debuted in #{debut.inspect}"
+  end
+
+  page = characters.info&.next_page
+  break unless page
+end
+
+puts "\n#{total} character(s) matched #{name.inspect}"

data/graph_weaver.gemspec

@@ -10,9 +10,14 @@ Gem::Specification.new do |s|
   # CLAUDE.md/PLAN.md/REVIEW.md/NOTES.md/DECISIONS.md are written for whoever
   # works on the gem, not whoever installs it — and REVIEW.md carries examples
   # from before the API it describes was rewritten
-  s.files       = `git ls-files * ':!:spec' ':!:sorbet' ':!:bin' ':!:examples' \
+  # examples/ ships (small plain text) so the README's links to it resolve for
+  # someone who only has the installed gem, not a checkout
+  # CHANGELOG.md doesn't (259 KB, ~16% of the package) — changelog_uri below
+  # points at the GitHub copy instead
+  s.files       = `git ls-files * ':!:spec' ':!:sorbet' ':!:bin' \
                      ':!:CLAUDE.md' ':!:PLAN.md' ':!:REVIEW.md' ':!:NOTES.md' \
-                     ':!:DECISIONS.md' ':!:Makefile' ':!:design'`.split("\n") + [".yardopts"]
+                     ':!:DECISIONS.md' ':!:CHANGELOG.md' ':!:Makefile' ':!:design' \
+                     ':!:research'`.split("\n") + [".yardopts"]
   s.homepage    = "https://github.com/dpep/graph_weaver"
   s.license     = "MIT"
   s.name        = "graph_weaver"
@@ -22,8 +27,12 @@ Gem::Specification.new do |s|
 
   s.metadata = {
     "bug_tracker_uri" => "#{s.homepage}/issues",
-    "changelog_uri" => "#{s.homepage}/blob/main/CHANGELOG.md",
+    # pinned to the release tag, not main — CHANGELOG.md isn't packaged, and
+    # main drifts ahead of whatever version this metadata shipped with
+    "changelog_uri" => "#{s.homepage}/blob/v#{s.version}/CHANGELOG.md",
     "documentation_uri" => "#{s.homepage}/tree/main/docs",
+    # no separate homepage_uri: identical to s.homepage, and `gem build` warns
+    # that rubygems.org only shows one of two metadata keys with the same uri
     "rubygems_mfa_required" => "true",
     "source_code_uri" => s.homepage,
   }
@@ -40,12 +49,19 @@ Gem::Specification.new do |s|
   s.add_development_dependency "debug"
   s.add_development_dependency "faker"
   s.add_development_dependency "faraday"
+  s.add_development_dependency "rack" # WebMock's to_rack needs it; webmock doesn't depend on it
   s.add_development_dependency "rake"
+  # spec/railtie_spec.rb boots a real Rails application: the railtie's bug of
+  # record was Rails' initializer TSort putting graph_weaver.logger after
+  # config/initializers, which a stand-in cannot model. Brings activesupport,
+  # which LogSubscriber is checked against for the same reason.
+  s.add_development_dependency "railties"
   s.add_development_dependency "redcarpet" # yard --markup markdown
   s.add_development_dependency "rspec"
   s.add_development_dependency "simplecov"
   s.add_development_dependency "sorbet"
   s.add_development_dependency "tapioca"
+  s.add_development_dependency "webmock" # graphql: :wire serves its Rack app through it
   s.add_development_dependency "webrick"
   s.add_development_dependency "yard"
 end

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
@@ -106,6 +128,17 @@ class GraphWeaver::Client
       "this client has no transport (built from a schema dump) — pass a url or transport:"
   end
 
+  # How long a failed introspection answers for the threads behind it. The
+  # lock makes a cold schema one round trip at a time, so against a hung
+  # upstream every queued thread used to pay its own read_timeout in turn —
+  # 8 threads at the 30s default is four minutes of occupied worker, and the
+  # next wave paid it again. A second is enough to collapse a wave and the
+  # retry right behind it, and short enough that an upstream which comes back
+  # is tried again on the next request. Deliberately not a circuit breaker:
+  # nothing here counts failures or stays open.
+  FAILURE_TTL = 1.0
+  private_constant :FAILURE_TTL
+
   # The schema, introspecting through the transport on first use (cached
   # per the client's cache:/ttl:) unless one was given up front.
   #
@@ -114,7 +147,17 @@ class GraphWeaver::Client
   # in-flight thread, each of them also writing the cache file.
   def schema
     @schema_lock.synchronize do
-      @schema ||= GraphWeaver::SchemaLoader.introspect(transport!, cache: @cache, ttl: @ttl)
+      next @schema if @schema
+      raise @schema_error if @schema_error && Process.clock_gettime(Process::CLOCK_MONOTONIC) < @schema_error_until
+
+      begin
+        @schema_error = nil
+        @schema = GraphWeaver::SchemaLoader.introspect(transport!, cache: @cache, ttl: @ttl)
+      rescue GraphWeaver::Error => e
+        @schema_error = e
+        @schema_error_until = Process.clock_gettime(Process::CLOCK_MONOTONIC) + FAILURE_TTL
+        raise
+      end
     end
   end
 
@@ -165,15 +208,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 +227,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}'"