graph_weaver 0.7.5 → 0.7.7

data/lib/graph_weaver/input_struct.rb

@@ -24,7 +24,13 @@ module GraphWeaver
     # is the schema's name for the slot ("PetFilter.species") and type its
     # spelling of what goes there ("[Float!]!"), so a refusal can say where
     # it happened, and in whose vocabulary, without reflecting at runtime.
-    Field = Data.define(:prop, :wire, :required, :serializer, :coercer, :coordinate, :type)
+    Field = Data.define(:prop, :wire, :required, :serializer, :coercer, :coordinate, :type) do
+      # How a message names this field. The prop is what you type in Ruby, so
+      # it leads; the wire name is what you grep the .graphql for, so it comes
+      # along where the two differ. Nothing structured reads this — #path,
+      # #field and #coordinate are the schema's spelling either way.
+      def label = (wire == prop.to_s) ? prop.to_s : "#{prop} (#{wire})"
+    end
 
     # An enum reaching the library as input — an execute kwarg or an input
     # field — as the member or its wire value. Generated code calls these
@@ -70,6 +76,25 @@ module GraphWeaver
       table.fetch(value) { invalid_enum!(type, value, table.keys) }
     end
 
+    # The way back out: a member => the wire value it sends as. Generation
+    # makes that table total, so a miss is a T::Enum that grew a member since
+    # — and Hash#fetch's KeyError named the anonymous table rather than the
+    # member or anything it could have sent. Also the result side's `as_json`,
+    # where nothing wraps a raised KeyError into a GraphWeaver error at all.
+    def self.enum_wire(graphql_name, table, member)
+      table.fetch(member) do
+        raise GraphWeaver::Internal::Refusal.brand(
+          GraphWeaver::Error.new(
+            # a T::Enum member inspects as #<Type::Name>
+            "#{member.inspect[2..-2]} maps onto no #{graphql_name} value, so there is nothing to " \
+            "send for it — expected one of: #{table.values.sort.join(", ")}; a member added since " \
+            "you generated needs a regenerate",
+          ),
+          :not_a_member, members: table.values.sort,
+        )
+      end
+    end
+
     # Names the input field a coercion refused — a scalar's coercer, an
     # enum's, or a nested input's — since the complaint underneath is about
     # the value alone. A nested error that already named a field keeps its
@@ -83,7 +108,7 @@ module GraphWeaver
       raise e.within(field.wire, prop:) if e.field && !redact.filtered?(prop)
 
       raise GraphWeaver::InputError.new(
-        "#{prop}: #{redact.detail(prop, e.message)}",
+        "#{field.label}: #{redact.detail(prop, e.message)}",
         kind: e.kind, path: [field.wire, *e.path], coordinate: e.coordinate || field.coordinate,
         # #value is the value AT #path: this layer owns it only when nothing
         # inner named a field (so a missing one stays valueless, as it is)
@@ -93,7 +118,7 @@ module GraphWeaver
     rescue StandardError => e
       redact = GraphWeaver::Internal::Redact
       raise GraphWeaver::InputError.new(
-        "#{prop}: #{redact.detail(prop, e.message)}",
+        "#{field.label}: #{redact.detail(prop, e.message)}",
         kind: GraphWeaver::Internal::Refusal.kind_of(e), path: [field.wire],
         coordinate: field.coordinate, value: redact.value(prop, raw),
         details: GraphWeaver::Internal::Refusal.details_of(e), struct:,
@@ -284,7 +309,7 @@ module GraphWeaver
           field = T.unsafe(self).const_get(:FIELDS).find { |f| f.prop == prop }
           type = field&.type || T::Utils.coerce(info[:type]).to_s
           return GraphWeaver::InputError.new(
-            "#{prop}: expected #{type}, got #{GraphWeaver::Internal::Redact.shown(value, prop)}",
+            "#{field&.label || prop}: expected #{type}, got #{GraphWeaver::Internal::Redact.shown(value, prop)}",
             kind: :type_mismatch, path: [prop.to_s], coordinate: field&.coordinate,
             value: GraphWeaver::Internal::Redact.value(prop, value),
             details: { type: }, struct: self,

data/lib/graph_weaver/internal/overrides.rb

@@ -10,9 +10,9 @@ module GraphWeaver
     # suite-wide ones while the block that set them is still on the stack,
     # and a fake built with its own checks them then.
     module Overrides
-      # The key a Hash `list_size:` says its fallback under — every list it
-      # doesn't name.
-      LIST_SIZE_DEFAULT = "default"
+      # The key a per-field Hash (`list_size:`, `null_chance:`) says its
+      # fallback under — everything it doesn't name.
+      DEFAULT_KEY = "default"
 
       class << self
         # A pin key names something in the schema: a type ("Money",
@@ -51,16 +51,22 @@ module GraphWeaver
         # minus the bare type name: a type says nothing about how long any one
         # of its fields is.
         def validate_list_size!(schema, list_size)
-          return unless list_size.is_a?(Hash)
-
-          list_size.each do |key, value|
-            unless value.is_a?(Integer) || value.is_a?(Range)
-              raise GraphWeaver::Error, "list_size: #{key.to_s.inspect} must be an Integer or a " \
-                "Range — how long an unbounded list is — got #{value.inspect}"
-            end
-            next if key.to_s == LIST_SIZE_DEFAULT
+          reaches = ->(type) { type.list? }
+          validate_per_field!(schema, list_size, "list_size",
+            reaches:, unreached: "is not a list and has no length to set — name a list field") do |value|
+            "an Integer or a Range of them, neither negative — how long an unbounded list is" unless
+              length?(value)
+          end
+        end
 
-            validate_field_key!(schema, key.to_s, "list_size: key")
+        # A Hash `null_chance:` is keyed the same way, one nullable field at a
+        # time.
+        def validate_null_chance!(schema, null_chance)
+          reaches = method(:nullable_anywhere?)
+          validate_per_field!(schema, null_chance, "null_chance",
+            reaches:, unreached: "can never come back null — name a nullable field") do |value|
+            "a number from 0 to 1 — how often a nullable field comes back null" unless
+              value.is_a?(Numeric) && (0..1).cover?(value)
           end
         end
 
@@ -75,6 +81,83 @@ module GraphWeaver
 
         private
 
+        # The two shapes both per-field options take: one value for every
+        # field, or a Hash keyed by field — a "Type.field" coordinate or a
+        # bare field name — with DEFAULT_KEY for the rest. The block says
+        # what a value has to be, in the words the refusal uses, and says it
+        # of both shapes: a plain `null_chance: 7` used to sail through and
+        # null everything, a plain `list_size: "3"` to die inside the
+        # fabricator.
+        def validate_per_field!(schema, option, name, reaches:, unreached:)
+          unless option.is_a?(Hash)
+            refuse_value!(name, nil, option, yield(option))
+            return
+          end
+
+          option.each do |key, value|
+            refuse_value!(name, key, value, yield(value))
+            next if key.to_s == DEFAULT_KEY
+
+            label = "#{name}: key"
+            validate_field_key!(schema, key.to_s, label)
+            reaches!(schema, key.to_s, label, reaches, unreached)
+          end
+        end
+
+        # A key naming a field the option can never reach is inert, which is
+        # the silent green every other key check exists to stop: the
+        # fabricator asks `null_chance` at nullable positions only and
+        # `list_size` at lists only, so it never looks this key up.
+        def reaches!(schema, key, label, reaches, unreached)
+          types = field_types(schema, key)
+          return if types.empty? || types.any? { |type| reaches.call(type) }
+
+          spelled = types.map(&:to_type_signature).uniq.sort.join(", ")
+          raise GraphWeaver::Error, "#{label} #{key.inspect} (#{spelled}) #{unreached}, " \
+            "or drop the key"
+        end
+
+        # Every field a per-field key names: the one a coordinate points at,
+        # or every field of that name in the schema for a bare one.
+        def field_types(schema, key)
+          type_name, field_name = key.split(".", 2)
+          # introspection fields (__typename) are real but absent from #fields
+          return [] if (field_name || type_name).start_with?("__")
+          return [schema.get_type(type_name).fields.fetch(field_name).type] if field_name
+
+          schema.types.each_value.filter_map do |type|
+            type.fields[type_name]&.type if type.respond_to?(:fields)
+          end
+        end
+
+        # Whether null_chance has a position in this type to reach. The outer
+        # wrapper isn't the whole answer: `[Pet]!` is non-null and its ELEMENTS
+        # are nullable, which is where the fabricator puts the nulls.
+        def nullable_anywhere?(type)
+          return true unless type.non_null?
+
+          inner = type.of_type
+          inner.list? && nullable_anywhere?(inner.of_type)
+        end
+
+        def refuse_value!(name, key, value, wanted)
+          return unless wanted
+
+          raise GraphWeaver::Error, "#{name}:#{" #{key.to_s.inspect}" if key} must be #{wanted} — " \
+            "got #{value.inspect}"
+        end
+
+        # A length is a count the fabricator can build an Array of: Array.new(-1)
+        # is "negative array size" out of its guts, and a Range the seeded rng
+        # can't sample (endless, or beginless) is worse.
+        def length?(value)
+          case value
+          when Integer then !value.negative?
+          when Range then [value.begin, value.end].all? { |edge| edge.is_a?(Integer) && !edge.negative? }
+          else false
+          end
+        end
+
         # A proc taking anything else can't be called at fabrication time,
         # and the ArgumentError it would raise there names no pin.
         def validate_arity!(key, value)
@@ -113,20 +196,49 @@ module GraphWeaver
             known = field_names(schema)
             return if known.include?(type_name)
 
+            # a type name reads like a reasonable key here — `null_chance: {
+            # "Person" => 1.0 }` looks like "null the whole subtree" — and
+            # did_you_mean sent it to the nearest FIELD ('person') instead of
+            # saying these options are keyed by field
+            named = schema.get_type(type_name)
+            type_key!(label, key, named) if named
             bad!(label, key, "matches no field in this schema", known, type_name)
           end
 
           coordinate!(schema, label, key, type_name, field_name)
         end
 
+        def type_key!(label, key, type)
+          reach = type.respond_to?(:fields) ? "#{type.graphql_name}.<field>".inspect : "a \"Type.field\" coordinate"
+          raise GraphWeaver::Error, "#{label} #{key.inspect} names " \
+            "#{type.kind.name.downcase.tr("_", " ")} #{type.graphql_name}, and a key here names " \
+            "one field — #{reach}, or a bare field name"
+        end
+
         def coordinate!(schema, label, key, type_name, field_name)
           type = schema.get_type(type_name)
           unless type.respond_to?(:fields)
             bad!(label, key, "names no object type in this schema", schema.types.keys, type_name)
           end
-          return if type.fields.key?(field_name)
+          unless type.fields.key?(field_name)
+            bad!(label, key, "is not a field of #{type_name}", type.fields.keys, field_name)
+          end
+
+          concrete!(schema, label, key, type, field_name)
+        end
+
+        # The abstract-type refusal, in the coordinate form. An interface
+        # declares the field, so "Named.name" reads as a key that must work
+        # — and it matches nothing: the walk picks a member before it builds
+        # a coordinate, so every key it looks up is "Person.name".
+        def concrete!(schema, label, key, type, field_name)
+          return unless type.kind.abstract?
 
-          bad!(label, key, "is not a field of #{type_name}", type.fields.keys, field_name)
+          members = schema.possible_types(type)
+            .map { |member| "#{member.graphql_name}.#{field_name}".inspect }.sort
+          raise GraphWeaver::Error, "#{label} #{key.inspect} names #{type.kind.name.downcase} " \
+            "#{type.graphql_name}, and a fake only ever holds a concrete type: name the " \
+            "concrete type — #{members.join(", ")}"
         end
 
         # A type pin says what every value of that type is, and the fake only

data/lib/graph_weaver/internal/test_clients.rb

@@ -97,15 +97,20 @@ module GraphWeaver
           # :wire takes no client slot: it serves the resolvers at the
           # endpoint each client already posts to — the transport you ship,
           # running unchanged, is the whole point
-          return if @mode == :wire
+          return if @mode == :wire && GraphWeaver.graphs.all?(&:client_url)
           # :live is the app's own clients, untouched — so with nothing
           # standing in there is nothing to look up
           return if @mode == :live && !built?
 
+          graph = graph_for!(mod)
+          # a graph whose client posts to no url has no wire to be served at,
+          # so :wire serves it here instead — the same pick, one hop shorter
+          return if @mode == :wire && graph&.client_url
+
           # a helper's entry wins whatever the example's mode is, and :live
           # builds nothing of its own, so an untagged example's other graphs
           # still resolve their own clients
-          standin(graph_for!(mod))
+          standin(graph)
         end
 
         # The stand-in `graph`'s modules run against under the installed mode,
@@ -165,12 +170,29 @@ module GraphWeaver
           return :in_process if config.schema_class?(graph)
           return :fake if config.schema || graph&.named_schema?
 
-          raise GraphWeaver::Error, ":wire serves your schema at the endpoint your client posts " \
-            "to, and #{graph&.name ? "graph #{graph.name.inspect}" : "this app"} has none to " \
-            "serve — no live GraphQL::Schema class, no composed supergraph, and no type " \
+          raise GraphWeaver::Error, nothing_to_serve(graph)
+        end
+
+        # Two graphs are in different states here, and the served one's
+        # sentences are all false for the other: a graph whose client posts
+        # nowhere has no endpoint to stub, no stub of ours to introspect, and
+        # no url to refresh a dump from — what it is missing is a schema.
+        def nothing_to_serve(graph)
+          missing = "no live GraphQL::Schema class, no composed supergraph, and no type " \
             "information (nothing at #{GraphWeaver.schema_path}, and " \
-            "GraphWeaver::Testing.config.schema is unset). Your client's own schema can't stand " \
-            "in here: reading it introspects the endpoint :wire has stubbed. Commit a dump " \
+            "GraphWeaver::Testing.config.schema is unset)"
+          if graph&.name && !graph.client_url
+            return ":wire has no endpoint for graph #{graph.name.inspect} — its client posts to " \
+              "none, so its modules run above the wire, against the most faithful stand-in the " \
+              "graph has. It has #{missing}. Name one where the graph is declared: " \
+              "GraphWeaver.graph(#{graph.name.inspect}) { schema -> { MySchema } }, or a dump " \
+              "(schema \"schema.graphql\"). Or tag the example graphql: :live."
+          end
+
+          ":wire serves your schema at the endpoint your client posts to, and " \
+            "#{graph&.name ? "graph #{graph.name.inspect}" : "this app"} has none to serve — " \
+            "#{missing}. Your client's own schema can't stand in here: reading it introspects " \
+            "the endpoint :wire has stubbed. Commit a dump " \
             "(rake graph_weaver:schema:refresh URL=…), or tag the example graphql: :live."
         end
 

data/lib/graph_weaver/internal/unused.rb

@@ -26,10 +26,17 @@ module GraphWeaver
       # call that names none of them. Caught where the sink line carries the
       # module's own name, or a local a line above assigned from it.
       SINKS = /\b(?:to_h|to_json|as_json|serialize|deconstruct_keys)\b|render\s+json:/
-      # `result = PersonQuery.execute!(...)` — the local a response lands in.
+      # `result = PersonQuery.execute!(...)` — the name a response lands in.
       # Following one is what lets the sink be on the NEXT line, which is how
-      # anyone actually writes a controller. Excludes == and =~.
-      ASSIGN = /\b([a-z_]\w*)\s*=[^=~]/
+      # anyone actually writes a controller. The `@` is part of the capture:
+      # it is what says the name outlives the method. Excludes == and =~.
+      ASSIGN = /(@?\b[a-z_]\w*)\s*=[^=~]/
+      # Where a plain local stops standing for the module it was assigned
+      # from: the next method is a new scope, and a block param there that
+      # happens to share the name holds someone else's value. An ivar crosses
+      # it — `before_action` loading `@result` for the action to render is
+      # the shape every Rails controller has.
+      SCOPE = /^[ \t]*def\s/
       # A graphql-ruby TYPE class NAMES every field the server offers, as
       # `field :sku` and as a resolver method — which is the server answering,
       # not this app reading a prop back. Without this an app that serves the
@@ -189,6 +196,7 @@ module GraphWeaver
             # `result = Q.execute!(...)`, then `render json: result.person`.
             locals = Hash.new { |hash, key| hash[key] = [] }
             body.each_line.with_index(1) do |line, number|
+              locals.each_value { |names| names.select! { |n| n.start_with?("@") } } if SCOPE.match?(line)
               candidates.each do |name, base|
                 locals[name] << Regexp.last_match(1) if line.include?(base) && ASSIGN.match(line)
               end
@@ -197,7 +205,7 @@ module GraphWeaver
               candidates.each do |name, base|
                 # the line naming the module is the better evidence; the local
                 # is what it falls back to
-                via = locals[name].find { |local| line.match?(/\b#{Regexp.escape(local)}\b/) } \
+                via = locals[name].find { |local| line.match?(/(?<![\w@])#{Regexp.escape(local)}\b/) } \
                   unless line.include?(base)
                 next unless via || line.include?(base)
 
@@ -221,20 +229,31 @@ module GraphWeaver
             result = Object.const_get(name)
             next [] unless result.const_defined?(:Result, false)
 
-            words = source.scan(/[A-Za-z_]\w*/).uniq
+            keys = response_keys(GraphQL.parse(source).definitions)
             props(result.const_get(:Result, false))
-              .map { |struct, prop| Selection.new(path, name, struct, prop, wire_word(words, prop)) }
+              .map { |struct, prop| Selection.new(path, name, struct, prop, wire_word(keys, prop)) }
           end
         end
       end
 
       # How the query spells a prop, when that isn't the prop's own name — a
       # camelCase field, an alias, a reserved rename. Read back off the query
-      # text rather than derived from the prop, since no rule inverts an
-      # alias; nil when the query spells it the same way, which is most of
-      # the time.
-      def wire_word(words, prop)
-        words.find { |word| word != prop.to_s && GraphWeaver::Codegen.prop_name(word) == prop.to_s }
+      # rather than derived from the prop, since no rule inverts an alias; nil
+      # when the query spells it the same way, which is most of the time.
+      def wire_word(keys, prop)
+        keys.find { |key| key != prop.to_s && GraphWeaver::Codegen.prop_name(key) == prop.to_s }
+      end
+
+      # Every response key the document asks for. The coordinate is the
+      # selection to go and delete, so it can only be one of these: scanning
+      # the file's text let `$id: ID!` — or a comment — name a field the query
+      # never selected.
+      def response_keys(nodes, found = [])
+        nodes.each do |node|
+          found << (node.alias || node.name) if node.is_a?(GraphQL::Language::Nodes::Field)
+          response_keys(node.selections, found) if node.respond_to?(:selections)
+        end
+        found
       end
 
       # Nested structs are nested constants, so the props of a whole response

data/lib/graph_weaver/internal/values.rb

@@ -88,7 +88,12 @@ class GraphWeaver::Internal::Values
   # for the next, and only a caller holding the graph can say which. Left
   # unsaid they are read back off the schema, which is the answer for every
   # app with one graph running a live class.
-  def initialize(seed: nil, values: nil, pins: nil, schema: nil, registry: nil)
+  # pin_advice: how to pin, in the words of the door the caller came in by —
+  # a callable taking the scalar's name. Left unsaid it is the three doors
+  # onto a fake, which is where this is reached from unless something says
+  # otherwise (check_scalars! runs outside all three).
+  def initialize(seed: nil, values: nil, pins: nil, schema: nil, registry: nil, pin_advice: nil)
+    @pin_advice = pin_advice
     @registry = registry || GraphWeaver::Internal::Util.registry_for(schema)
     @rng = Random.new(seed || GraphWeaver::Testing.config.seed || Random.new_seed)
     @pins = (pins || GraphWeaver::Testing.config.overrides).transform_keys(&:to_s)
@@ -202,12 +207,19 @@ class GraphWeaver::Internal::Values
   # for — `Money.parse` accepts what its author decided it accepts — and
   # guessing hands the generated cast a placeholder, which fails deep inside
   # from_h blaming the codec.
+  #
+  # Each door onto a fake spells a pin differently and this can't know which
+  # you came in by, so the advice names all three — unless the caller said,
+  # in which case it is the one that works there.
   def unfakeable!(type_name, field_name, registered, coordinate, at)
+    type = type_name.inspect
+    advice = @pin_advice&.call(type_name) ||
+      "Pin the type (#{type}) or just this field (#{(coordinate || field_name).inspect}), " \
+      "wherever the fake is built — graphql_fake(#{type} => ...) in an rspec example, " \
+      "FakeClient.new(#{type} => ...) outside one, or GraphWeaver::Testing.config.overrides " \
+      "for the whole suite."
     raise GraphWeaver::Error, "can't fabricate a #{type_name} #{at ? "at #{at}" : "for #{field_name.inspect}"}: " \
-      "it deserializes into #{registered.type}, and only you know what wire value that accepts. " \
-      "Pin the type — overrides: { #{type_name.inspect} => ... } — or this one field: " \
-      "overrides: { #{(coordinate || field_name).inspect} => ... }. Suite-wide, that's " \
-      "GraphWeaver::Testing.config.overrides."
+      "it deserializes into #{registered.type}, and only you know what wire value that accepts. #{advice}"
   end
 
   # :faker is an explicit ask — fail loudly when the gem is missing; auto

data/lib/graph_weaver/internal.rb

@@ -192,6 +192,23 @@ module GraphWeaver
           GraphWeaver.generated_paths | extra
         end
 
+        # The generated directories this process has to require ITSELF:
+        # generated_dirs, less any tree the Railtie left to Zeitwerk. Those
+        # load on first reference and reload with the app, and requiring them
+        # is the one thing an autoloadable layout exists to avoid.
+        def required_dirs
+          generated_dirs.reject { |dir| left_to_zeitwerk?(dir) }
+        end
+
+        # by name, not spelled: the railtie is Rails-only and `typed: ignore`,
+        # so sorbet has no constant to resolve. Outside Rails there is no
+        # autoloader and the answer is always no.
+        def left_to_zeitwerk?(path)
+          return false unless GraphWeaver.const_defined?(:Railtie, false)
+
+          GraphWeaver.const_get(:Railtie, false).left_to_zeitwerk?(path)
+        end
+
         # Every query document under these directories, sorted — the files
         # generate!, verify_generated!, check_queries and load_queries! read.
         def query_files(paths = GraphWeaver.queries_paths)
@@ -243,14 +260,14 @@ module GraphWeaver
             "or cache one: GraphWeaver.new(url, cache: true).schema"
         end
 
-        # The graphql-ruby schema class the app default executes against,
-        # when it runs in-process — a Client wrapping one, or the class in
-        # the slot bare. nil for every network client. Not memoized: in dev
-        # the class object is replaced on reload.
-        def live_schema
+        # The graphql-ruby schema class a client executes against, when it
+        # runs in-process — a Client wrapping one, or the class in the slot
+        # bare. nil for every network client. Defaults to the app's own, and
+        # a graph passes its client. Not memoized: in dev the class object is
+        # replaced on reload.
+        def live_schema(client = GraphWeaver.client)
           # through #transport, not #schema: a url client's #schema
           # introspects, so asking it would answer over the network
-          client = GraphWeaver.client
           target = client.is_a?(Client) ? client.transport : client
           target = target.schema if target.is_a?(InProcess)
           target if target.is_a?(Class) && target <= GraphQL::Schema

data/lib/graph_weaver/log_subscriber.rb

@@ -14,17 +14,20 @@ module GraphWeaver
   #      GraphWeaver PersonQuery (12.3ms) ok
   #      GraphWeaver PersonQuery (8.1ms) errors [THROTTLED]
   #      GraphWeaver PersonQuery (31.2ms) failed GraphWeaver::TransportError
+  #      GraphWeaver PersonQuery (44.0ms) failed GraphWeaver::CastError
   #      GraphWeaver billing/InvoicesQuery (12.3ms) ok
   #
   # Attached by the railtie wherever ActiveSupport is, and fed by the
   # instrumenter it sets. Requires ActiveSupport — `require` this yourself
   # only if you subscribe by hand.
   #
-  # **One rule decides which line you get: the summary is info, the wire is
-  # debug.** This is the only GraphWeaver line at info, so a production log
-  # gets one per operation and nothing that could carry PII; turning
-  # GraphWeaver.logger up to debug adds the query, the variables and the
-  # response *beneath* it rather than repeating it.
+  # **One rule decides which line you get: the operation is info, the
+  # attempt is debug.** The info line is one CALL of a generated module, so
+  # it says what the caller got — a cast that raised reads `failed`, and a
+  # test mode's stand-in gets a line like every other client. A production
+  # log gets one per operation and nothing that could carry PII; turning
+  # GraphWeaver.logger up to debug adds each attempt, with the url, the HTTP
+  # status and which retry it was, beneath it.
   #
   # It writes through GraphWeaver.logger rather than Rails.logger, so
   # `GraphWeaver.logger = nil` — the documented way to silence the gem —
@@ -33,17 +36,10 @@ module GraphWeaver
   class LogSubscriber < ActiveSupport::LogSubscriber
     # attach_to(:graph_weaver) subscribes "#{method}.graph_weaver" and
     # ActiveSupport::Subscriber#call dispatches on the name up to the first
-    # dot — so this method name is EXECUTE_EVENT's first half, both ways.
-    def execute(event)
-      payload = event.payload
+    # dot — so these method names are the events' first halves, both ways.
+    def operation(event) = write(:info, event)
 
-      GraphWeaver::Internal::Log.log(:info) do
-        # duration_ms is the instrumenter's own measurement; event.duration
-        # covers a subscriber attached to something that didn't set it
-        ms = payload[:duration_ms] || event.duration
-        "GraphWeaver #{subject(payload)} (#{format("%.1f", ms)}ms) #{outcome(payload)}"
-      end
-    end
+    def execute(event) = write(:debug, event)
 
     # GraphWeaver's logger, not Rails' — LogSubscriber#call skips a
     # subscriber whose logger is nil, which is what makes the gem's own
@@ -52,7 +48,20 @@ module GraphWeaver
 
     private
 
-    # What ran: the operation, prefixed by its graph when the request carried
+    # One shape for both, so the attempt beneath an operation reads as the
+    # same line rather than a second format to learn.
+    def write(level, event)
+      payload = event.payload
+
+      GraphWeaver::Internal::Log.log(level) do
+        # duration_ms is the instrumenter's own measurement; event.duration
+        # covers a subscriber attached to something that didn't set it
+        ms = payload[:duration_ms] || event.duration
+        "GraphWeaver #{subject(payload)} (#{format("%.1f", ms)}ms) #{outcome(payload)}"
+      end
+    end
+
+    # What ran: the operation, prefixed by its graph when the payload names
     # one — an app with several graphs reads `billing/InvoicesQuery` without
     # a second line shape to learn, and one with a single graph never sees it.
     def subject(payload)
@@ -61,7 +70,8 @@ module GraphWeaver
     end
 
     # status, then whatever narrows it: the error class, the reason an alert
-    # groups by, and which attempt this was when a Retry is in the stack.
+    # groups by, and — on a debug attempt line — which try this was. The last
+    # two are attempt facts, so only the debug line ever carries them.
     def outcome(payload)
       parts = [payload[:status], payload[:error]]
       # the GraphQL code, or the HTTP status where the request never got one