graph_weaver 0.7.5 → 0.7.6

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}"
@@ -909,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

data/lib/graph_weaver/tasks.rb

@@ -170,9 +170,9 @@ module GraphWeaver
         }.filter_map { |kind, names| "  #{kind}: #{names.sort.join(", ")}" if names.any? }
       end
 
-      # What `queries:check` just answered. It re-introspects the url a dump
-      # records and asks a live class directly; anything else it checks as it
-      # stands on disk, which is `verify`'s question — and both exited 0
+      # 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) }
@@ -183,14 +183,11 @@ module GraphWeaver
       end
 
       # A graph whose queries were checked against the file rather than the
-      # server: a graph that names its own schema is checked against exactly
-      # that, and a dump with no recorded url has nothing to re-read.
+      # 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
-        return unless path && graph.live_schema.nil?
-        return if !graph.named_schema? && GraphWeaver::SchemaLoader.provenance(path)&.key?("url")
-
-        GraphWeaver::Internal::Util.relative(path)
+        GraphWeaver::Internal::Util.relative(path) if path && graph.source.nil?
       end
       private_class_method :as_committed
 
@@ -214,16 +211,18 @@ module GraphWeaver
       # 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.dump_source || graph.client_url] }
+        GraphWeaver.graphs.map { |graph| [graph, graph.dump_path, graph.source] }
       end
 
-      # A dump with no recorded url whose graph names no client: nothing
-      # behind the file to re-read, so the file is the schema. Said and
-      # stepped over rather than refused — the task's job is the graphs it
-      # CAN refresh.
+      # 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 client — left as checked in"
+          "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
@@ -242,19 +241,6 @@ module GraphWeaver
         "#{whose} generates from #{source_name(source)} directly — no dump to keep in step"
       end
 
-      # What `diff` re-introspects for one graph. A schema class answers
-      # introspection itself. A url the dump recorded is left to
-      # SchemaLoader.diff, which builds the transport and so honours the
-      # auth_env the dump named. A source that came from the graph's client
-      # instead is that client's own transport — headers, auth and all.
-      def self.diff_transport(graph, source)
-        return source if source.is_a?(Module)
-        return if graph.dump_source
-
-        client = graph.client || GraphWeaver.client
-        client.respond_to?(:transport) ? client.transport : client
-      end
-
       # How a dump's source reads in a report: a url as itself, a schema
       # class by name.
       def self.source_name(source) = source.is_a?(Module) ? GraphWeaver::SchemaLoader.endpoint(source) : source
@@ -393,18 +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
 
-        diff = GraphWeaver::SchemaLoader.diff(path,
-          transport: GraphWeaver::Internal::Tasks.diff_transport(graph, source))
+        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?
 
@@ -419,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
@@ -439,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
@@ -450,13 +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?
-        # a supergraph has no source by construction — nothing serves one —
-        # and refresh! answers that with "recompose", which is not a skip
-        next puts GraphWeaver::Internal::Tasks.no_source(path) if path && !source && !graph.supergraph
+        # 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
@@ -481,6 +504,10 @@ namespace :graph_weaver do
       $stdout.flush
       abort "#{failures.size} invalid #{(failures.size == 1) ? "query" : "queries"}" if failures.any?
       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
@@ -167,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) }
@@ -612,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
@@ -624,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"

data/lib/graph_weaver/testing.rb

@@ -340,10 +340,14 @@ module GraphWeaver
             "Declare it with the class: GraphWeaver.graph(#{graph.name.inspect}) " \
             "{ schema -> { MySchema } }."
         else
+          # the helper needs no tag, which is what makes it reachable from
+          # BOTH paths into here: a tagged example is already past its own
+          # before hook, so "name it in the example" only works if the tag goes
           "GraphWeaver.client isn't running one in-process to borrow. Name it in the example — " \
-            "graphql_in_process(MySchema) — or set GraphWeaver::Testing.config.schema = MySchema " \
-            "for the whole suite. A federated app names the subgraph it means, per example; " \
-            "graphql: :router runs the graph stitched."
+            "graphql_in_process(MySchema) — instead of the graphql: :in_process tag, which " \
+            "builds this client in a `before` hook of its own and so is already past. Or set " \
+            "GraphWeaver::Testing.config.schema = MySchema for the whole suite. A federated app " \
+            "names the subgraph it means, per example; graphql: :router runs the graph stitched."
         end
       end
 
@@ -411,7 +415,7 @@ module GraphWeaver
       # the precision case gets exercised at all.
       def check_scalars!(schema)
         registry = Internal::Util.registry_for(schema)
-        values = Internal::Values.new(seed: 0, schema:, registry:)
+        values = Internal::Values.new(seed: 0, schema:, registry:, pin_advice: method(:pin_for_check))
         context = GraphQL::Query.new(schema, "{ __typename }").context
 
         disagreed = schema.types.values.sort_by(&:graphql_name).filter_map do |type|
@@ -431,6 +435,14 @@ module GraphWeaver
 
       private
 
+      # check_scalars! takes the schema and nothing else, and runs outside
+      # every fake — so of the doors onto a pin only the suite-wide one is a
+      # door here. graphql_fake is a no-op, and there is no second argument.
+      def pin_for_check(name)
+        "Pin the form this server sends: GraphWeaver::Testing.config.overrides = " \
+          "{ #{name.inspect} => ... }."
+      end
+
       # One scalar's verdict, or nil when the two halves agree. Each step is
       # a different mistake, so each says which.
       def disagreement(scalar, type, values, context)
@@ -448,8 +460,8 @@ module GraphWeaver
         begin
           sample = cast.call(wire)
         rescue StandardError => e
-          return "#{name}: cast: can't read #{wire.inspect}, the value fabricated for it (#{e.message}) " \
-            "— pin the form this server sends: overrides: { #{name.inspect} => ... }"
+          return "#{name}: cast: can't read #{wire.inspect}, the value fabricated for it " \
+            "(#{e.message}). #{pin_for_check(name)}"
         end
 
         if scalar.serialize? && !scalar.serialize_value?
@@ -475,7 +487,15 @@ module GraphWeaver
         end
         return if back == sample
 
-        "#{name}: round-trips lossily — sent #{Internal::Redact.spell(sample)}, got back #{Internal::Redact.spell(back)}"
+        sent = Internal::Redact.spell(sample)
+        got = Internal::Redact.spell(back)
+        return "#{name}: round-trips lossily — sent #{sent}, got back #{got}" unless sent == got
+
+        # two identical spellings for two unequal values: the class inherits
+        # Object#==, which is identity, so this can't tell a lossy round trip
+        # from a faithful one and must not claim either
+        "#{name}: #{sample.class} defines no ==, so a round trip can't be checked — sent " \
+          "#{sent} and got back #{got}, and nothing here can tell those apart"
       end
 
       # The registration's `cast:`, RUN rather than emitted. A cast builds

data/lib/graph_weaver/transport.rb

@@ -99,7 +99,7 @@ class GraphWeaver::Transport
     payload = { url: safe_url, 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, payload)
     end
   end

data/lib/graph_weaver/version.rb

@@ -1,3 +1,3 @@
 module GraphWeaver
-  VERSION = "0.7.5"
+  VERSION = "0.7.6"
 end

data/lib/graph_weaver.rb

@@ -614,8 +614,8 @@ module GraphWeaver
     #      #         "line" => 4, "column" => 5 }] }
     #
     # Empty means every query validates. schema: defaults to the server as
-    # it is now — a FRESH introspection of the url the dump records, or the
-    # live schema class when the app default runs in-process — and the dump
+    # it is now — a FRESH introspection of the source behind each graph's
+    # dump, or the live schema class where that source IS one — and the dump
     # is left alone; pass schema: and nothing touches the network.
     #
     # When that dump is a composed supergraph, an error naming a type is
@@ -623,17 +623,25 @@ module GraphWeaver
     # (products, reviews)", plus a "subgraphs" key — since knowing whose
     # code to look at is half the answer. A plain schema is unaffected.
     #
-    # One query you have as a *string* is Client#check_query — the same
-    # entries, against that client's own schema.
+    # One query you have as a *string* is #check_query, which every client
+    # holding a schema answers — the same entries, against that schema.
     #
     # A different question from verify_generated!, which asks whether the
     # committed Ruby matches the committed schema. `rake
     # graph_weaver:queries:check` prints this and exits non-zero.
     def check_queries(schema: nil, queries: nil, fragments: fragments_paths)
       shared = Codegen.load_fragments(fragments)
-
-      graphs_for(schema:, queries:).each_with_object({}) do |graph, failures|
-        checked = checked_schema(graph)
+      # one graph's server being down is that graph's verdict: every graph is
+      # attempted, so a run names every server it couldn't reach rather than
+      # ending at the first
+      unreachable = []
+
+      failures = graphs_for(schema:, queries:).each_with_object({}) do |graph, failures|
+        begin
+          checked = checked_schema(graph)
+        rescue Error => e
+          next unreachable << unreachable_source(graph, e)
+        end
         table = checked_routing_table(graph)
         Internal::Util.query_files(graph.queries).each do |path|
           errors = Internal::QueryCheck.errors(checked, File.read(path), shared, table)
@@ -646,13 +654,39 @@ module GraphWeaver
           failures[key] = failures.key?(key) ? failures[key] | errors : errors
         end
       end
+
+      raise Error, unreachable.join("\n") unless unreachable.empty?
+
+      failures
     end
 
-    # What this graph is checked against. A graph that names its schema is
-    # checked against exactly that, so nothing touches the network; the default
-    # graph names none, so its dump is re-introspected first (see
-    # refreshed_schema).
-    def checked_schema(graph) = graph.named_schema? ? graph.schema : refreshed_schema
+    # Which graph couldn't be checked, and against what. The bare socket error
+    # named neither — in a multi-graph app it was the entire output, and the
+    # reader could not tell which of their servers was down.
+    def unreachable_source(graph, error)
+      whose = graph.name ? "graph #{graph.name.inspect}" : "this app"
+      dump = graph.dump_path || graph.named_dump_path
+      subject = dump ? Internal::Util.relative(dump) : "these queries"
+      "#{whose}: couldn't reach the schema behind #{subject} — #{error.message}"
+    end
+    private :unreachable_source
+
+    # What this graph is checked against: Graph#source, the rule `schema:refresh`
+    # and `schema:diff` follow too. A live class is asked directly — for an app
+    # that IS the server, a dump is a snapshot of its own code, and checking
+    # against it reports phantom errors about a field just added. A url is
+    # re-introspected, so no refresh step (and no rewritten dump) is needed
+    # first. A graph with neither — hand-written SDL nothing serves, a composed
+    # supergraph — has nothing to re-read, so it is checked as committed.
+    def checked_schema(graph)
+      source = graph.source
+      return source if source.is_a?(Module)
+      # Internal::Util.locate_schema! raises the conventional "no schema dump"
+      # message when the default graph has no dump either
+      return graph.schema unless source
+
+      SchemaLoader.introspect(graph.source_transport)
+    end
     private :checked_schema
 
     # The routing table behind the schema check_queries is about to use, when
@@ -663,28 +697,6 @@ module GraphWeaver
     end
     private :checked_routing_table
 
-    # The schema check_queries defaults to: the server as it is now. Over a
-    # socket that's a fresh introspection of the url the local dump recorded,
-    # so no refresh step (and no rewritten dump) is needed first. In-process
-    # it's the live schema class — for an app that IS the server, a dump is a
-    # snapshot of its own code, and checking against it reports phantom
-    # errors about a field you just added. Dumps with no url and no live
-    # class — hand-written SDL, a composed supergraph — have nothing to
-    # re-read, so they're checked as they are.
-    def refreshed_schema
-      live = Internal::Util.live_schema
-      return live if live
-
-      # Internal::Util.locate_schema! raises the conventional "no schema dump" message
-      path = SchemaLoader.locate_path or Internal::Util.locate_schema!
-      return SchemaLoader.load(path) unless SchemaLoader.provenance(path)&.key?("url")
-
-      # source_transport rather than one built here: it reads the auth ENV var
-      # the dump named, so `--auth MY_TOKEN` reaches this path too
-      SchemaLoader.introspect(SchemaLoader.source_transport(path))
-    end
-    private :refreshed_schema
-
     # Load the generated modules — one line in an initializer or spec
     # helper (loading happens only when you call this; skip it and
     # require files yourself if you'd rather):
@@ -844,7 +856,7 @@ module GraphWeaver
       rescue GraphWeaver::Error => e
         # collected, not raised: nothing is written either way, and an adopter
         # aiming generate! at an existing query directory wants the list
-        refusals << e
+        refusals << name_query_file(e, path)
         nil
       end
       refuse_all!(refusals, paths.size)
@@ -907,6 +919,18 @@ module GraphWeaver
     # itself, so a single bad file reads exactly as it always has — class,
     # message and all; several become one list, because clearing them a file
     # per run is the slowest way there is to adopt this.
+    # Almost every codegen refusal is about the query in front of it and never
+    # says which file that was — so a list of them named nothing, which is the
+    # one thing a list is for. This rescue is the only place holding both.
+    # #exception keeps the class and its fields and swaps only the message.
+    def name_query_file(error, path)
+      reported = Internal::Util.relative(path)
+      return error if error.message.include?(reported)
+
+      error.exception("#{reported}: #{error.message}")
+    end
+    private :name_query_file
+
     def refuse_all!(refusals, considered)
       return if refusals.empty?
       raise refusals.first if refusals.one?

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: graph_weaver
 version: !ruby/object:Gem::Version
-  version: 0.7.5
+  version: 0.7.6
 platform: ruby
 authors:
 - Daniel Pepper
@@ -364,7 +364,7 @@ licenses:
 - MIT
 metadata:
   bug_tracker_uri: https://github.com/dpep/graph_weaver/issues
-  changelog_uri: https://github.com/dpep/graph_weaver/blob/v0.7.5/CHANGELOG.md
+  changelog_uri: https://github.com/dpep/graph_weaver/blob/v0.7.6/CHANGELOG.md
   documentation_uri: https://github.com/dpep/graph_weaver/tree/main/docs
   rubygems_mfa_required: 'true'
   source_code_uri: https://github.com/dpep/graph_weaver