graph_weaver 0.7.4 → 0.7.6

data/lib/graph_weaver/rspec.rb

@@ -161,7 +161,9 @@ module GraphWeaver
       # suite's WebMock setup is touched.
       def self.serve!
         webmock!
-        wire_targets.map do |url, graph|
+        targets, above = wire_targets
+        above.each { |graph| disclose_above!(graph) }
+        targets.map do |url, graph|
           # built here, so a graph with nothing to serve refuses before the
           # example runs rather than from inside its first request
           disclose!(GraphWeaver::Internal::TestClients.standin(graph), url, graph)
@@ -210,6 +212,17 @@ module GraphWeaver
         end
       end
 
+      # Say which graph ran above the wire. Its stand-in is built when one of
+      # its modules first runs, not here — a graph the example never touches
+      # must not refuse it — so this names the graph rather than what is
+      # behind it.
+      def self.disclose_above!(graph)
+        GraphWeaver::Internal::Log.log(:info) do
+          ":wire has no endpoint for #{graph.name ? "graph #{graph.name.inspect}" : "this app"} — " \
+            "its client posts to none, so its modules run above the wire, as #{TAG}: :in_process would"
+        end
+      end
+
       # What the stand-in IS, read off the object rather than re-deciding —
       # one answer, and it can't drift from what was built. A fake of a dump
       # has no name to give: the dump loads as an anonymous class, and
@@ -254,21 +267,24 @@ module GraphWeaver
       # inside the cleanup.
       def self.unserve!(stub) = WebMock::StubRegistry.instance.request_stubs.delete(stub)
 
-      # Every endpoint an example's modules can post to, each with the graph
-      # whose resolvers belong behind it: the client each graph names, or
-      # GraphWeaver.client for a graph naming none. One graph per endpoint —
-      # an app whose graphs all name clients needs no app default at all.
+      # What :wire does with each graph, in two lists: the endpoints to stub,
+      # each with the graph whose resolvers belong behind it, and the graphs
+      # there is no endpoint for. One graph per endpoint — an app whose graphs
+      # all name clients needs no app default at all.
+      #
+      # A graph whose client posts to no url has no wire to be served at, so
+      # it runs above one instead of refusing the example — including the
+      # examples that never touch it. An example where NO graph posts anywhere
+      # is refused, since a :wire that serves nothing tests no transport.
       def self.wire_targets
-        targets = GraphWeaver.graphs.filter_map do |graph|
-          client = graph.client || GraphWeaver.client
-          [endpoint!(client, graph), graph] if client
-        end
+        targets, above = GraphWeaver.graphs.map { |graph| [graph.client_url, graph] }.partition(&:first)
         refuse_shared_endpoint!(targets)
-        return targets if targets.any?
+        return [targets, above.map(&:last)] if targets.any?
 
-        # nothing bakes a client and the app has none: the endpoint refusal
-        # names the empty slot, which is the thing to fix
-        endpoint!(GraphWeaver.client)
+        # the endpoint refusal names the client that posts to none, which is
+        # the thing to fix
+        graph = GraphWeaver.graphs.first
+        endpoint!(graph&.client || GraphWeaver.client, graph)
       end
 
       # One stub per url, so two graphs on one endpoint used to mean the
@@ -343,7 +359,8 @@ module GraphWeaver
       end
 
       private_class_method :wire_targets, :refuse_shared_endpoint!, :whose_client,
-        :webmock!, :webmock_enabled?, :disclose!, :served, :unnamed_schemas, :loaded_schemas
+        :webmock!, :webmock_enabled?, :disclose!, :disclose_above!, :served, :unnamed_schemas,
+        :loaded_schemas
 
       # Included into every example group, so graphql_context is there
       # whether or not this example took a client from the hook.
@@ -570,10 +587,17 @@ module GraphWeaver
           raise GraphWeaver::Error, "graphql_context needs resolvers to receive it, and a " \
             "#{TAG}: :fake example runs against fabricated data — tag it #{TAG}: :in_process or " \
             "#{TAG}: :router (or pin the data itself: " \
-            "graphql_fake(overrides: { \"Person.name\" => \"Ada\" }))"
+            "graphql_fake(\"Person.name\" => \"Ada\"))"
         else
-          raise GraphWeaver::Error, "graphql_context needs an example running against your " \
-            "resolvers — tag it #{TAG}: :in_process or #{TAG}: :router"
+          # :live, which is what an untagged example is. The app's own client
+          # stays in the slot holding the context it was built with, so there
+          # is nothing here to merge onto — and saying "you need resolvers"
+          # reads as false to an app whose own client is an InProcess, which
+          # is running them
+          raise GraphWeaver::Error, "graphql_context says what THIS example's resolvers see, " \
+            "and #{TAG}: :live leaves your app's own client exactly as it is — carrying the " \
+            "context it was built with. Tag the example #{TAG}: :in_process or #{TAG}: :router, " \
+            "which build a client per example."
         end
       end
 
@@ -592,7 +616,6 @@ module GraphWeaver
           "may itself be a proc, so it can vary per request."
       end
       private_class_method :wire_context!
-
     end
   end
 end

data/lib/graph_weaver/schema_diff.rb

@@ -122,6 +122,8 @@ module GraphWeaver
         return change(name, "#{kind(old)} -> #{kind(new)}", breaking: true)
       end
 
+      compare_description(name, old, new)
+
       case new.kind.name
       when "OBJECT", "INTERFACE"
         compare_fields(name, old, new)
@@ -151,6 +153,7 @@ module GraphWeaver
           breaking: breaks_output?(old.type, new.type))
       end
       compare_deprecation(coordinate, old, new)
+      compare_description(coordinate, old, new)
       compare_arguments(coordinate, old.arguments, new.arguments)
     end
 
@@ -192,6 +195,7 @@ module GraphWeaver
         change(coordinate, "#{prefix}#{signature(old)} -> #{signature(new)}", breaking:)
       end
       compare_deprecation(coordinate, old, new)
+      compare_description(coordinate, old, new)
     end
 
     def compare_enum(name, old, new)
@@ -200,7 +204,10 @@ module GraphWeaver
 
       (before.keys - after.keys).each { |value| change("#{name}.#{value}", "enum value removed", breaking: true) }
       (after.keys - before.keys).each { |value| change("#{name}.#{value}", "enum value added") }
-      (before.keys & after.keys).each { |value| compare_deprecation("#{name}.#{value}", before[value], after[value]) }
+      (before.keys & after.keys).each do |value|
+        compare_deprecation("#{name}.#{value}", before[value], after[value])
+        compare_description("#{name}.#{value}", before[value], after[value])
+      end
     end
 
     # A dropped member silently stops matching a `... on X` fragment, which
@@ -233,10 +240,22 @@ module GraphWeaver
       change(coordinate, now ? "deprecated: #{now}" : "no longer deprecated")
     end
 
-    # The walk names what a client breaks on. A description, a directive
-    # definition, an argument default moves the SDL without appearing
-    # above — still drift, and a gate that went green on it would be worse
-    # than one that admits it can't name it.
+    # A description breaks nothing and reaches no generated code, but it is
+    # the likeliest thing to differ between a hand-maintained dump and the
+    # server — and unnamed it fell through to note_unnamed_drift, which is a
+    # permanent red with nothing to act on. The text itself isn't printed: it
+    # can be paragraphs, and the coordinate is what you go and look at.
+    def compare_description(coordinate, old, new)
+      return unless old.respond_to?(:description)
+      return if old.description == new.description
+
+      change(coordinate, "description changed")
+    end
+
+    # The walk names what a client breaks on. A directive definition or an
+    # argument default moves the SDL without appearing above — still drift,
+    # and a gate that went green on it would be worse than one that admits
+    # it can't name it.
     def note_unnamed_drift(before, after)
       return unless @changes.empty?
       return if before.to_definition == after.to_definition

data/lib/graph_weaver/schema_loader.rb

@@ -199,10 +199,21 @@ module GraphWeaver::SchemaLoader
   COMPOSITION_SPEC = %r{@(?:link\s*\(\s*url|core\s*\(\s*feature):\s*"https://specs\.apollo\.dev/(?:join|core)/}
   private_constant :COMPOSITION_SPEC
 
-  # A composed Fed2 supergraph is marked by @join__* directives (every merged
-  # type carries them); a plain schema has none.
+  # A composed Fed2 supergraph is marked by @join__* directives APPLIED to
+  # its types (every merged type carries them); a plain schema applies none.
+  #
+  # Applied, not merely declared: introspect a router and graphql-ruby hands
+  # back the API schema with the @join__* directive DEFINITIONS still in it
+  # and every application gone — so a bare substring test answers "composed"
+  # about the one artifact whose routing table has been removed.
+  JOIN_DEFINITION = /\bdirective\s+@join__\w+/
+  private_constant :JOIN_DEFINITION
+
   def self.federation_sdl?(sdl)
-    sdl.match?(/@join__\w/) || sdl.match?(COMPOSITION_SPEC)
+    return true if sdl.match?(COMPOSITION_SPEC)
+    return false unless sdl.match?(/@join__\w/)
+
+    sdl.gsub(JOIN_DEFINITION, "").match?(/@join__\w/)
   end
 
   # The federation spec a fed-2 subgraph @links, and the directives a fed-1
@@ -720,12 +731,13 @@ module GraphWeaver::SchemaLoader
     schema = build_introspection(result)
 
     if cache
-      # the extension picks the format: .json is the verbatim wire
-      # artifact; .graphql/.gql is SDL — human-readable, PR-reviewable
-      # diffs (both generate byte-identical code)
+      # the extension picks the format: .json is the wire artifact, pretty-
+      # printed so a refresh diffs line by line (graphql-client's dump is
+      # too); .graphql/.gql is SDL — human-readable, PR-reviewable diffs
+      # (both generate byte-identical code)
       meta = stamp(transport, auth_env)
       content = if cache.end_with?(".json")
-        JSON.generate(meta ? result.merge("graph_weaver" => meta) : result)
+        JSON.pretty_generate(meta ? result.merge("graph_weaver" => meta) : result)
       else
         header = meta && "# graph_weaver: #{JSON.generate(meta)}\n\n"
         "#{header}#{schema.to_definition}"
@@ -887,9 +899,10 @@ module GraphWeaver::SchemaLoader
     return recompose_hint(path) if composed_dump?(path)
 
     missing = path ? "#{path} records no source url" : "no schema dump at #{GraphWeaver.schema_path}"
-    "#{missing} — pass one: rake graph_weaver:schema:refresh URL=https://api.example.com/graphql " \
-      "(if this app serves the schema itself, point GraphWeaver.client at the class and the dump is " \
-      "rebuilt from it — see docs/getting_started.md#your-apps-own-schema-in-process)"
+    "#{missing} — pass one: rake graph_weaver:schema:refresh " \
+      "URL=https://api.example.com/graphql, or point the graph's client at the server — an app " \
+      "that serves the schema itself points GraphWeaver.client at the class and the dump is built " \
+      "from that (docs/getting_started.md#your-apps-own-schema-in-process)"
   end
   private_class_method :refresh_hint
 
@@ -908,13 +921,14 @@ module GraphWeaver::SchemaLoader
   # Composition is the only thing that rebuilds a supergraph: introspection
   # answers with the API schema, which is the merged shape minus the routing
   # table, so refreshing one from a url replaces the contract with a strictly
-  # smaller artifact and reports success.
+  # smaller artifact and reports success. Public so `schema:refresh` can step
+  # over such a graph in these words rather than reaching the overwrite and
+  # relying on the guard to catch it.
   def self.recompose_hint(path)
     "#{GraphWeaver::Internal::Util.relative(path)} is a composed supergraph; introspection returns " \
       "the API schema, not the @join__* routing table — recompose it (rover supergraph compose) " \
       "and check the result in, instead of refreshing it"
   end
-  private_class_method :recompose_hint
 
   # A transport to the dump's recorded url, authenticated from whichever ENV
   # var the dump named (else DEFAULT_AUTH_ENV). The single way to reach a
@@ -922,11 +936,9 @@ module GraphWeaver::SchemaLoader
   # ends up honoured in some places and not others.
   def self.source_transport(path)
     meta = provenance(path)
-    unless meta&.key?("url")
-      raise GraphWeaver::Error,
-        "#{path} records no source url — it wasn't introspected from one. Pass transport:, " \
-        "or rebuild it from the schema class that produced it."
-    end
+    # the same sentence refresh! gives: this is reached by typing a rake task
+    # (schema:diff), and `transport:` is not something a rake user can pass
+    raise GraphWeaver::Error, refresh_hint(path) unless meta&.key?("url")
 
     GraphWeaver.new(meta["url"], auth: ENV[auth_env(path)]).transport
   end

data/lib/graph_weaver/tasks.rb

@@ -170,6 +170,27 @@ module GraphWeaver
         }.filter_map { |kind, names| "  #{kind}: #{names.sort.join(", ")}" if names.any? }
       end
 
+      # What `queries:check` just answered. It re-introspects the source behind
+      # a dump and asks a live class directly; a graph with neither it checks
+      # as it stands on disk, which is `verify`'s question — and both exited 0
+      # saying "against the schema".
+      def self.validated
+        dumps = GraphWeaver.graphs.filter_map { |graph| as_committed(graph) }
+        return "every query validates against the schema" if dumps.empty?
+
+        "every query validates against #{dumps.join(", ")} as committed — not the server " \
+          "(rake graph_weaver:schema:diff asks whether the server moved)"
+      end
+
+      # A graph whose queries were checked against the file rather than the
+      # server: nothing behind the dump to re-read, which is what a nil
+      # Graph#source says.
+      def self.as_committed(graph)
+        path = graph.dump_path
+        GraphWeaver::Internal::Util.relative(path) if path && graph.source.nil?
+      end
+      private_class_method :as_committed
+
       # Neither task that needs the committed dump can take one itself, so both
       # say which task can — the same sentence SchemaLoader gives on refresh.
       def self.no_dump
@@ -184,7 +205,25 @@ module GraphWeaver
       # rewrites it from the graph's source, `diff` says how far that source
       # has drifted from it, whichever the source is. A graph whose schema IS
       # a live class reads no dump at all, so it has neither.
-      def self.dumps = GraphWeaver.graphs.map { |graph| [graph, graph.dump_path, graph.dump_source] }
+      #
+      # The dump's own record of where it came from first, then the client the
+      # graph's modules already call: a dump inherited with no provenance, or a
+      # schema kept by hand, still has a server behind it, and refusing one
+      # took every other graph's refresh down with it.
+      def self.dumps
+        GraphWeaver.graphs.map { |graph| [graph, graph.dump_path, graph.source] }
+      end
+
+      # A dump with no recorded url whose graph names no server: nothing
+      # behind the file to re-read, so the file is the schema. One shape, one
+      # diagnosis — :refresh steps over it and :diff can't assert anything
+      # about it, and they used to describe it in two different sentences and
+      # disagree about whose whole run it ended.
+      def self.no_source(path)
+        "#{GraphWeaver::Internal::Util.relative(path)} records no source url and the graph names " \
+          "no server behind it — no client posting to one, and no graphql-ruby schema class in " \
+          "this process — so the file is the schema and nothing here can re-read it"
+      end
 
       # A graph that generates straight from a schema class has no dump
       # between the code and the output — so there is nothing here to
@@ -340,19 +379,31 @@ namespace :graph_weaver do
 
     desc "Fail when the schema behind the dump has drifted from it"
     task diff: :own_schema do
-      subjects = GraphWeaver::Internal::Tasks.dumps
-      abort GraphWeaver::Internal::Tasks.no_dump if subjects.none? { |_, path, _| path }
-
-      stale = subjects.filter_map do |graph, path, source|
+      # One rule per graph, and no graph's verdict depends on what the others
+      # have: the "no dump anywhere" abort used to run before the loop, so a
+      # lone live-class graph was refused naming a path it never mentions
+      # while the same graph passed as soon as a sibling had a dump.
+      ungated = []
+      stale = GraphWeaver::Internal::Tasks.dumps.filter_map do |graph, path, source|
         heading = GraphWeaver::Internal::Tasks.heading(graph)
         puts heading if heading
-        # a graph that names a live class generates straight from it: no
-        # dump between the code and the output, so nothing can be stale
-        next puts GraphWeaver::Internal::Tasks.no_dump_needed(graph, source) unless path
+        unless path
+          # a graph that names a live class generates straight from it: no
+          # dump between the code and the output, so nothing can be stale.
+          # One whose dump is merely missing has something this gate can't see.
+          puts GraphWeaver::Internal::Tasks.no_dump_needed(graph, source)
+          ungated << graph if graph.named_dump_path || !source
+          next
+        end
+        unless source
+          # the shape :refresh steps over, in :refresh's own words — this task
+          # still fails on it, because a gate cannot assert nothing
+          puts GraphWeaver::Internal::Tasks.no_source(path)
+          ungated << graph
+          next
+        end
 
-        # a schema class answers introspection itself; left nil, diff builds
-        # the dump's own transport, auth and all
-        diff = GraphWeaver::SchemaLoader.diff(path, transport: (source if source.is_a?(Module)))
+        diff = GraphWeaver::SchemaLoader.diff(path, transport: graph.source_transport)
         dump = GraphWeaver::Internal::Util.relative(path)
         next puts "#{dump} matches #{GraphWeaver::Internal::Tasks.source_name(source)}" if diff.empty?
 
@@ -367,6 +418,12 @@ namespace :graph_weaver do
         abort "#{stale.join(", ")} is stale — the schema behind it has drifted " \
           "(rake graph_weaver:schema:refresh)"
       end
+      # a gate that passes on having compared nothing is worse than one that
+      # admits it: the sentence above says which graph and why
+      unless ungated.empty?
+        abort "#{GraphWeaver::Internal::Tasks.whose(ungated)}nothing here could be compared — " \
+          "this run gated nothing"
+      end
     rescue GraphWeaver::Error => e
       # e.g. a dump that is its own source — same clean exit as :refresh
       abort e.message
@@ -387,7 +444,10 @@ namespace :graph_weaver do
         next puts "refreshed #{GraphWeaver::Internal::Util.relative(path)} from #{source}"
       end
 
-      GraphWeaver::Internal::Tasks.dumps.each do |graph, path, source|
+      # Every graph is its own job: one unreachable server used to end the run
+      # with the graphs after it never attempted, so an app learned about them
+      # one per run. The exit code is the only thing they share.
+      failed = GraphWeaver::Internal::Tasks.dumps.filter_map do |graph, path, source|
         heading = GraphWeaver::Internal::Tasks.heading(graph)
         puts heading if heading
         # a graph that names a live class generates straight from it — no
@@ -398,10 +458,28 @@ namespace :graph_weaver do
         # below and refresh! bootstraps its first dump (or says how).
         path ||= graph.named_dump_path
         next puts GraphWeaver::Internal::Tasks.no_dump_needed(graph, source) if !path && graph.named_schema?
+        # composition is the only thing that rebuilds a supergraph, so this
+        # graph is one to step over however good its client is — introspecting
+        # the router answers with the API schema, which routes nothing
+        next puts GraphWeaver::SchemaLoader.recompose_hint(path) if graph.supergraph
+        next puts GraphWeaver::Internal::Tasks.no_source(path) if path && !source
+
+        begin
+          written, from = GraphWeaver::SchemaLoader.refresh!(url: (source unless source.is_a?(Module)),
+            schema: (source if source.is_a?(Module)), path:)
+          puts "refreshed #{GraphWeaver::Internal::Util.relative(written)} from #{from}"
+          nil
+        rescue GraphWeaver::Error => e
+          puts e.message
+          graph
+        end
+      end
 
-        written, from = GraphWeaver::SchemaLoader.refresh!(url: (source unless source.is_a?(Module)),
-          schema: (source if source.is_a?(Module)), path:)
-        puts "refreshed #{GraphWeaver::Internal::Util.relative(written)} from #{from}"
+      # abort writes to unbuffered stderr; the reports above went to
+      # block-buffered stdout, so a piped CI log shows them first
+      $stdout.flush
+      unless failed.empty?
+        abort "#{GraphWeaver::Internal::Tasks.whose(failed)}not refreshed — the dump on disk is unchanged"
       end
     rescue GraphWeaver::Error => e
       abort e.message
@@ -425,7 +503,11 @@ namespace :graph_weaver do
       # block-buffered stdout, so a piped CI log shows the verdict first
       $stdout.flush
       abort "#{failures.size} invalid #{(failures.size == 1) ? "query" : "queries"}" if failures.any?
-      puts "every query validates against the schema"
+      puts GraphWeaver::Internal::Tasks.validated
+    rescue GraphWeaver::Error => e
+      # this task reaches a server now, so an unreachable one is a condition to
+      # report — the same clean exit :diff and :refresh give
+      abort e.message
     end
   end
 

data/lib/graph_weaver/testing/fake_client.rb

@@ -86,12 +86,14 @@ require_relative "../parsing"
 #
 #      FakeClient.new(schema:, corrupt: "Person.birthday")
 #
-# null_chance: how often a nullable field comes back null — 0 by default,
-# and per fake only: "does this render with no email" is one example's
-# question, and a suite-wide answer would sprinkle nils through every other
-# example instead.
+# null_chance: how often a nullable field comes back null — a number from 0
+# to 1 for all of them, or a Hash per field keyed the way list_size: is. 0
+# by default, and per fake only: "does this render with no email" is one
+# example's question, and a suite-wide answer would sprinkle nils through
+# every other example instead.
 #
 #      FakeClient.new(schema:, null_chance: 1.0)   # everything nullable, null
+#      FakeClient.new(schema:, null_chance: { "Person.nickname" => 1.0, default: 0 })
 #
 # list_size: how long an unbounded list is — an Integer exactly, a Range
 # randomized within it, and a Hash per list, keyed the way a pin is (a
@@ -137,12 +139,6 @@ class GraphWeaver::Testing::FakeClient
     null_chance: nil, errors: nil, fail_at: nil, corrupt: nil,
   }.freeze
 
-  # JSON's own types are already on the wire: at a leaf they skip the
-  # registry's serializer (Values#wire), and at a composite position (a Hash
-  # aside, which is response keys) they pin the field as written — nil is
-  # null, the rest is the corrupt payload the example asked for.
-  WIRE = GraphWeaver::Internal::Values::WIRE
-
   # Methods every Ruby object answers aren't fields: a schema does have a
   # `hash` or a `count`, and a Struct answers both with plausible nonsense
   # where fabricating is right.
@@ -151,7 +147,7 @@ class GraphWeaver::Testing::FakeClient
   # The scalars the GraphQL spec serializes as JSON strings, whatever Ruby
   # holds them.
   STRING_SCALARS = %w[ID String].freeze
-  private_constant :OPTIONS, :WIRE, :RUBY_OWN, :STRING_SCALARS
+  private_constant :OPTIONS, :RUBY_OWN, :STRING_SCALARS
 
   def initialize(pins = {}, **options)
     config = GraphWeaver::Testing.config
@@ -173,10 +169,10 @@ class GraphWeaver::Testing::FakeClient
     @registry = options[:registry] || GraphWeaver::Internal::Util.registry_for(@schema)
     @values = GraphWeaver::Internal::Values.new(seed: options[:seed], values: options[:values],
       pins: @overrides, schema: @schema, registry: @registry)
-    @list_size = options[:list_size] || config.list_size
-    @list_size = @list_size.transform_keys(&:to_s) if @list_size.is_a?(Hash)
+    @list_size = stringify(options[:list_size] || config.list_size)
     GraphWeaver::Internal::Overrides.validate_list_size!(@schema, @list_size)
-    @null_chance = options[:null_chance] || 0.0
+    @null_chance = stringify(options[:null_chance] || 0.0)
+    GraphWeaver::Internal::Overrides.validate_null_chance!(@schema, @null_chance)
     # NOT Array(): it would explode a bare Hash into key/value pairs
     @extra_errors = wrap(options[:errors]).map { |error| normalize_error(error) }
     @fail_at = wrap(options[:fail_at]).map { |spec| normalize_fail_spec(spec) }
@@ -467,7 +463,9 @@ class GraphWeaver::Testing::FakeClient
   # reads them off — a FactoryBot build, a model, a Struct. Either way it
   # MERGES: what it doesn't answer is fabricated.
   def pinned_object(type, selections, value, source)
-    return value if !value.is_a?(Hash) && wire?(value)
+    # what JSON already holds is the pin as written — nil is null, and the rest
+    # is the corrupt payload the example asked for (a Hash is response keys)
+    return value if !value.is_a?(Hash) && GraphWeaver::Internal::Values.wire?(value)
 
     concrete = pinned_type(type, value, source)
     pins = value.is_a?(Hash) ? value : read_fields(concrete, selections, value)
@@ -497,8 +495,6 @@ class GraphWeaver::Testing::FakeClient
     object.respond_to?(name) && !RUBY_OWN.include?(object.method(name).owner)
   end
 
-  def wire?(value) = WIRE.any? { |klass| value.is_a?(klass) }
-
   # An object pin holds Ruby values — a Time, a Money, a T::Enum — where the
   # wire holds what the registration says they serialize to. A value that
   # is already wire-shaped is taken as written.
@@ -618,7 +614,7 @@ class GraphWeaver::Testing::FakeClient
     return [capped, 0].max if capped.is_a?(Integer)
     return 0 if errors_list?(node.name)
 
-    size = list_size_for(coordinate, node.name)
+    size = per_field(@list_size, coordinate, node.name, GraphWeaver::Testing::Config::DEFAULT_LIST_SIZE)
     # an Integer list_size means exactly that many; a Range randomizes within it
     size.is_a?(Range) ? rng.rand(size) : size
   end
@@ -630,28 +626,29 @@ class GraphWeaver::Testing::FakeClient
   # until it is pinned. Pin it to fabricate the failure path.
   def errors_list?(name) = name.downcase.end_with?("errors")
 
-  # How long an unbounded list is. A Hash says it per list, read most
-  # specific first like a pin — which is what keeps nested lists from
-  # multiplying: every list the walk reaches re-reads this, so one number
-  # for all of them is n rows x n tags.
-  def list_size_for(coordinate, name)
-    return @list_size unless @list_size.is_a?(Hash)
-
-    @list_size.fetch(coordinate) do
-      @list_size.fetch(name) do
-        @list_size.fetch(GraphWeaver::Internal::Overrides::LIST_SIZE_DEFAULT,
-          GraphWeaver::Testing::Config::DEFAULT_LIST_SIZE)
-      end
+  # What a per-field option (list_size:, null_chance:) says here. A Hash says
+  # it per field, read most specific first like a pin — which is what keeps
+  # nested lists from multiplying: every list the walk reaches re-reads
+  # list_size, so one number for all of them is n rows x n tags.
+  def per_field(option, coordinate, name, fallback)
+    return option unless option.is_a?(Hash)
+
+    option.fetch(coordinate) do
+      option.fetch(name) { option.fetch(GraphWeaver::Internal::Overrides::DEFAULT_KEY, fallback) }
     end
   end
 
+  # A per-field option's keys are GraphQL names, written as either a String
+  # or a Symbol (`default:` most of all).
+  def stringify(option) = option.is_a?(Hash) ? option.transform_keys(&:to_s) : option
+
   def type_value(type, node, selections, coordinate: nil, non_null: false)
     if type.kind.name == "NON_NULL"
       return type_value(type.of_type, node, selections, coordinate:, non_null: true)
     end
     # every nullable position, a list included — null_chance is about the
     # nilable props codegen emitted, and it emits one for `[Thing!]` too
-    return if !non_null && rng.rand < @null_chance
+    return if !non_null && rng.rand < per_field(@null_chance, coordinate, node.name, 0.0)
 
     case type.kind.name
     when "LIST"