graph_weaver 0.7.4 → 0.7.6

data/lib/graph_weaver/hints.rb

@@ -69,22 +69,37 @@ module GraphWeaver
     # neither that nor which values exist. Raised bare so the enclosing
     # Hints.field brands it with the field.
     # aliases (register_enum alias:) is wire spelling => the value it reads as.
-    def self.enum(type, value, aliases = nil)
+    # fallback is the Other member, when the registration asked for one.
+    def self.enum(type, value, aliases = nil, fallback: nil)
       value = aliases.fetch(value, value) if aliases
+      member = type.try_deserialize(value)
+      return member if member
+      return absorbed(type, value, fallback) if fallback
 
-      type.try_deserialize(value) || drifted!(type, value, type.values.map(&:serialize))
+      drifted!(type, value, type.values.map(&:serialize), "register_enum fallback: true")
     end
 
     # the same, for an enum mapped onto an app-owned T::Enum, where the wire
     # table rather than the type knows the accepted values
     def self.mapped_enum(type, table, value)
-      table.fetch(value) { drifted!(type, value, table.keys) }
+      table.fetch(value) { drifted!(type, value, table.keys, "register_enum fallback:") }
     end
 
-    def self.drifted!(type, value, values)
+    # A T::Enum member is a singleton, so Other can't carry the value it
+    # swallowed — this line is the only record that anything drifted.
+    def self.absorbed(type, value, fallback)
+      GraphWeaver::Internal::Log.log(:debug) do
+        # the member's bare constant name — a T::Enum member inspects as #<Type::Name>
+        "#{type} absorbed #{GraphWeaver::Internal::Redact.shown(value)} into #{fallback.inspect[/::(\w+)>\z/, 1]}"
+      end
+      fallback
+    end
+    private_class_method :absorbed
+
+    def self.drifted!(type, value, values, suggestion)
       raise KeyError, "#{GraphWeaver::Internal::Redact.shown(value)} is not a #{type} — expected one of: " \
         "#{values.sort.join(", ")}; a value the server added since you generated " \
-        "needs a regenerate, or register_enum fallback: to absorb them"
+        "needs a regenerate, or #{suggestion} to absorb them"
     end
     private_class_method :drifted!
 

data/lib/graph_weaver/in_process.rb

@@ -55,7 +55,7 @@ class GraphWeaver::InProcess
     payload = { url: nil, schema: schema_label, operation: operation_name, client: self.class,
                 kind: GraphWeaver::Internal::Wire.kind(query) }
 
-    GraphWeaver::Internal::Log.instrument(GraphWeaver::EXECUTE_EVENT, payload) do
+    GraphWeaver::Internal::Log.instrument_request(payload) do
       perform(query, variables, operation_name)
     end
   end
@@ -72,14 +72,12 @@ class GraphWeaver::InProcess
         "#{GraphWeaver::Internal::Wire.truncate_for_log(query)}"
     end
 
-    result = GraphWeaver::Internal::Log.log_timed(:debug, "in-process #{schema_label} #{tag} completed") do
+    GraphWeaver::Internal::Log.log_timed(:debug, "in-process #{schema_label} #{tag} completed") do
       # a copy per query: graphql-ruby writes a resolver's `context[...] =`
       # into the hash it is handed, and one client serves every request
       @schema.execute(query, variables:, operation_name:,
         context: GraphWeaver::Internal::Util.context!(@context).dup)
     end
-
-    result
   rescue GraphWeaver::Error
     raise
   rescue => e

data/lib/graph_weaver/input_struct.rb

@@ -24,19 +24,28 @@ 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
     # rather than T::Enum.deserialize / the wire table directly: both raise a
     # bare KeyError naming an anonymous module and none of the values they
     # would have taken.
-    def self.enum(type, value, aliases = nil)
-      return value if value.is_a?(type)
-
-      value = aliases.fetch(value, value) if aliases
-
-      type.try_deserialize(value) || invalid_enum!(type, value, type.values.map(&:serialize))
+    # fallback is the generated Other member (register_enum fallback: true).
+    # It is the one member input refuses: nothing on the wire means it, so a
+    # variable carrying it would send a value the server never declared.
+    def self.enum(type, value, aliases = nil, fallback: nil)
+      member = value.is_a?(type) ? value : type.try_deserialize(aliases ? aliases.fetch(value, value) : value)
+      return member if member && !member.equal?(fallback)
+
+      accepted = type.values.map(&:serialize) - [fallback&.serialize].compact
+      member ? unsendable_enum!(member, accepted) : invalid_enum!(type, value, accepted)
     end
 
     # A list element's index, prepended when something inside it refused —
@@ -67,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
@@ -80,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)
@@ -90,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:,
@@ -110,6 +138,18 @@ module GraphWeaver
     end
     private_class_method :invalid_enum!
 
+    # The fallback member is a landing pad for drift, not a value — so it is
+    # refused by name rather than listed among the ones you could have meant.
+    def self.unsendable_enum!(member, accepted)
+      # a T::Enum member inspects as #<Type::Name>
+      raise GraphWeaver::Internal::Refusal.brand(
+        KeyError.new("#{member.inspect[2..-2]} absorbs values the server added, so " \
+          "there is nothing to send for it — expected one of: #{accepted.sort.join(", ")}"),
+        :not_a_member, members: accepted.sort,
+      )
+    end
+    private_class_method :unsendable_enum!
+
     def self.included(base)
       base.extend(ClassMethods)
     end
@@ -269,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/subgraphs.rb

@@ -34,9 +34,6 @@ module GraphWeaver
     # goes through the same check *and refuses at construction* — a swapped
     # pair fails there rather than as a mystery three fetches later.
     module Subgraphs
-      # how many coordinates a message names before it says "and N more"
-      SAMPLE = 5
-
       # answer this subgraph with fabricated data rather than refusing
       FAKE = :fake
 
@@ -117,15 +114,9 @@ module GraphWeaver
           return schema if gaps.empty?
 
           raise GraphWeaver::ConfigurationError, "subgraphs[#{name.inspect}] is " \
-            "#{schema.name || schema.inspect}, which doesn't define #{sample(gaps)} — the supergraph " \
+            "#{schema.name || schema.inspect}, which doesn't define #{Util.sample(gaps)} — the supergraph " \
             "says #{name} resolves them. Did two entries get swapped?"
         end
-
-        def sample(list)
-          return list.join(", ") if list.size <= SAMPLE
-
-          "#{list.first(SAMPLE).join(", ")} and #{list.size - SAMPLE} more"
-        end
       end
     end
   end

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
@@ -47,6 +54,11 @@ module GraphWeaver
       # .json.erb's sibling JS — is a blind spot, and the footer says so.
       # .rake and .builder are Ruby too.
       EXTENSIONS = %w[.rb .rake .builder .erb .slim .haml .jbuilder].freeze
+      # Ruby that carries no extension to recognise it by. In a non-Rails
+      # project the entry points live here, so skipping them skipped the
+      # files that read the query.
+      SCRIPT_DIRS = Set["bin", "exe"].freeze
+      RUBY_SHEBANG = /\A#!.*\bruby\b/
       # Directories that hold no app source. "generated" covers both a graph's
       # own output under the convention and a spec/generated fixture dir; a
       # graph that writes somewhere else is pruned by #outputs.
@@ -60,8 +72,9 @@ module GraphWeaver
       # difference between a lint and a number somebody trusts.
       FOOTER = "This is a lint, not a proof — it matches prop names as text, so a common name reads " \
         "as\nused the moment anything says it. It can't see a prop reached by public_send, or a " \
-        "read\nin a file type it doesn't sweep (#{EXTENSIONS.join(", ")}). On a real app half to " \
-        "two\nthirds of genuinely unread selections go unreported; silence is the safe direction."
+        "read\nin a file type it doesn't sweep — #{EXTENSIONS.join(", ")},\nplus Ruby with no " \
+        "extension (any name under bin/ or exe/, a ruby shebang elsewhere). On\na real app half to " \
+        "two thirds of genuinely unread selections go unreported; silence is\nthe safe direction."
 
       # query: the .graphql that selected it. struct/prop: where it landed.
       # wire: how the query spells that prop, when it differs.
@@ -183,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
@@ -191,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)
 
@@ -215,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
@@ -244,19 +269,22 @@ module GraphWeaver
       end
 
       def files
-        @files ||= @roots.flat_map { |root| collect(root, []) }.uniq.sort
+        @files ||= @roots
+          .flat_map { |root| collect(root, [], SCRIPT_DIRS.include?(File.basename(root))) }
+          .uniq.sort
       end
 
       # Pruned as it walks rather than globbed and filtered: node_modules is
-      # the directory you most want never to descend into.
-      def collect(dir, found)
+      # the directory you most want never to descend into. scripts says we are
+      # inside bin/ or exe/, which the walk knows and a path doesn't.
+      def collect(dir, found, scripts)
         Dir.children(dir).sort.each do |entry|
           path = File.join(dir, entry)
           # lstat, so a symlinked directory can't loop the walk
           stat = File.lstat(path)
           if stat.directory?
-            collect(path, found) unless skip_dir?(entry, path)
-          elsif stat.file? && EXTENSIONS.include?(File.extname(entry))
+            collect(path, found, scripts || SCRIPT_DIRS.include?(entry)) unless skip_dir?(entry, path)
+          elsif stat.file? && ruby?(path, entry, scripts)
             found << path
           end
         end
@@ -265,6 +293,22 @@ module GraphWeaver
         found
       end
 
+      # An extension names most of it. A file with none is Ruby if it sits
+      # under bin/ or exe/ — that is what those directories are for — or if
+      # its first line says so.
+      def ruby?(path, entry, scripts)
+        return true if EXTENSIONS.include?(File.extname(entry))
+        return false unless File.extname(entry).empty?
+
+        scripts || shebang?(path)
+      end
+
+      def shebang?(path)
+        File.open(path) { |file| file.gets(chomp: true) }&.match?(RUBY_SHEBANG) || false
+      rescue SystemCallError, ArgumentError
+        false
+      end
+
       def skip_dir?(entry, path) = entry.start_with?(".") || SKIP.include?(entry) || outputs.include?(path)
 
       # The generated directories a name check can't catch: a graph that sets

data/lib/graph_weaver/internal/values.rb

@@ -57,6 +57,11 @@ class GraphWeaver::Internal::Values
   # registration says the server writes "12.5".
   WIRE = [NilClass, TrueClass, FalseClass, Integer, Float, String, Symbol, Array, Hash].freeze
 
+  # Whether a value is already one of those. At a leaf it means the registry's
+  # serializer has nothing to do; at a composite position (FakeClient) it means
+  # the pin stands as written.
+  def self.wire?(value) = WIRE.any? { |klass| value.is_a?(klass) }
+
   # The fallback, for a scalar nobody registered: its prop is T.untyped, so
   # anything holds and a plausible shape beats a placeholder.
   NAMED_SHAPES = {
@@ -83,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)
@@ -146,10 +156,10 @@ class GraphWeaver::Internal::Values
   # as written. Shared with the object-pin door, so both read a pin the same
   # way.
   def wire(type_name, value, coordinate = nil)
-    return value if WIRE.any? { |klass| value.is_a?(klass) }
+    return value if self.class.wire?(value)
 
     serialized = @registry.scalar(type_name, coordinate).serialize_value(value)
-    return serialized if WIRE.any? { |klass| serialized.is_a?(klass) }
+    return serialized if self.class.wire?(serialized)
 
     article = GraphWeaver::Internal::Util.article(value.class.to_s)
     raise GraphWeaver::Error, "the pin for #{type_name.inspect} is #{article} #{value.class}, and a pin " \
@@ -197,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