graph_weaver 0.5.0 → 0.5.1

data/lib/graph_weaver/testing/cassette.rb

@@ -89,11 +89,29 @@ module GraphWeaver
       # One recording the generated structs can no longer read.
       Stale = Struct.new(:module_name, :variables, :message, keyword_init: true)
 
+      # Shapes that are a credential whatever the field around them is
+      # called. Anonymization can't cover everything a cassette holds — the
+      # variables ARE the replay key, so they're written verbatim — so the
+      # bytes that reach disk get one look before anyone commits them.
+      # Deliberately narrow: a false alarm costs a glance, while a password
+      # like "hunter2" has no shape at all, so a quiet run is not a clean
+      # bill of health.
+      CREDENTIAL_SHAPES = {
+        "a JWT" => /\beyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\./,
+        "an AWS access key" => /\b(?:AKIA|ASIA)[0-9A-Z]{16}\b/,
+        "a GitHub token" => /\b(?:gh[opusr]|github_pat)_[A-Za-z0-9_]{20,}/,
+        "a Slack token" => /\bxox[baprs]-[A-Za-z0-9-]{10,}/,
+        "a Stripe key" => /\bsk_(?:live|test)_[A-Za-z0-9]{10,}/,
+        "a private key" => /-----BEGIN [A-Z ]*PRIVATE KEY-----/,
+        "an Authorization header" => /\bBearer\s+\S{16,}/,
+      }.freeze
+
       attr_reader :path
 
       def initialize(path)
         @path = Testing.cassette_path(path)
         @entries = File.exist?(@path) ? YAML.safe_load_file(@path, aliases: true) : []
+        @flagged = []
       end
 
       def exist? = File.exist?(@path)
@@ -161,8 +179,7 @@ module GraphWeaver
       def anonymize!(schema:, seed: nil, mode: nil)
         anonymizer = Anonymizer.new(schema:, seed:, mode:)
         @entries.each do |entry|
-          data = entry.dig("response", "data")
-          entry["response"]["data"] = anonymizer.anonymize(entry["query"], data) if data
+          entry["response"] = anonymizer.anonymize(entry["query"], entry["response"]) if entry["response"]
         end
         save
         self
@@ -201,8 +218,25 @@ module GraphWeaver
       private
 
       def save
+        yaml = YAML.dump(@entries)
         FileUtils.mkdir_p(File.dirname(@path))
-        File.write(@path, YAML.dump(@entries))
+        File.write(@path, yaml)
+        flag_credentials(yaml)
+      end
+
+      # Once per shape per cassette: a recording run saves after every
+      # request, and one line is a warning where forty is noise. On stderr
+      # rather than GraphWeaver.logger — the logger is silent by default,
+      # and this has to reach whoever is about to commit the file.
+      def flag_credentials(yaml)
+        found = CREDENTIAL_SHAPES.reject { |name, _| @flagged.include?(name) }
+          .select { |_, pattern| pattern.match?(yaml) }.keys
+        return if found.empty?
+
+        @flagged.concat(found)
+        warn "graph_weaver: #{@path} contains #{found.join(", ")} — a cassette is committed as " \
+          "written, so review this one first. Testing.config.anonymize scrubs the response; the " \
+          "query and variables are the replay key and are recorded verbatim."
       end
     end
 
@@ -227,9 +261,7 @@ module GraphWeaver
 
       def execute(query, variables: {}, operation_name: nil)
         response = @client.execute(query, variables:, operation_name:).to_h
-        if @anonymizer && (data = response["data"])
-          response = response.merge("data" => @anonymizer.anonymize(query, data))
-        end
+        response = @anonymizer.anonymize(query, response) if @anonymizer
 
         @cassette.record(query, variables, response, operation_name)
         response
@@ -260,18 +292,52 @@ module GraphWeaver
     class Anonymizer
       include GraphWeaver::Selection
 
+      # Keys under `errors`/`extensions` whose value describes the request
+      # rather than carrying data: `path` and `locations` point into the
+      # document, and `code` is the errors-world enum — call sites branch on
+      # it exactly as they branch on an enum in `data`, which is preserved
+      # for the same reason.
+      VERBATIM_KEYS = %w[path locations code].freeze
+
       def initialize(schema:, seed: nil, mode: nil)
         @schema = schema
         @values = Values.new(seed:, mode:)
       end
 
-      def anonymize(query, data)
-        operation = load_operation(query)
+      # The whole response, not just `data`: an error message routinely
+      # quotes the input that caused it, and `extensions` is whatever the
+      # server felt like attaching. One rule — `data` is walked against the
+      # schema, everything else by shape.
+      def anonymize(query, response)
+        response.to_h do |key, value|
+          [key, (key == "data") ? data_value(query, value) : untyped_value(key, value)]
+        end
+      end
 
+      private
+
+      def data_value(query, data)
+        return if data.nil?
+
+        operation = load_operation(query)
         object_value(operation_root_type(operation), operation.selections, data)
       end
 
-      private
+      # No schema stands behind errors or extensions, so shape is all there
+      # is to preserve: keys, nesting, list lengths, nulls and booleans
+      # survive; every string and number is replaced.
+      def untyped_value(key, value)
+        return value if VERBATIM_KEYS.include?(key)
+
+        case value
+        when Hash then value.to_h { |name, nested| [name, untyped_value(name, nested)] }
+        when Array then value.map { |element| untyped_value(key, element) }
+        when String then @values.scalar("String", key)
+        when Integer then @values.scalar("Int", key)
+        when Float then @values.scalar("Float", key)
+        else value
+        end
+      end
 
       # Anonymization walks recorded data, not a live dispatch. When the query
       # narrows an abstract type without selecting __typename (`named { name
@@ -295,42 +361,45 @@ module GraphWeaver
         end
 
         result = {}
-        each_field(type, selections) do |key, node|
+        # gather (not each_field) so a key selected twice — `a { x } a { y }` —
+        # keeps the MERGED shape codegen's struct expects, not last-writer-wins
+        gather(type, selections).each do |key, nodes|
           next unless data.key?(key)
 
+          node = nodes.first
           result[key] = if node.name == "__typename"
             data[key]
           else
-            field_value(type, node, data[key])
+            field_value(type, node.name, nodes.flat_map(&:selections), data[key])
           end
         end
 
         result
       end
 
-      def field_value(parent_type, node, value)
+      def field_value(parent_type, name, selections, value)
         # a field from a `... on Member` fragment lives on the member, not the
         # abstract type we're walking (no __typename to narrow by), so fall back
         # to whichever possible type declares it
-        field = @schema.get_field(parent_type.graphql_name, node.name) ||
-          @schema.possible_types(parent_type).filter_map { |t| @schema.get_field(t.graphql_name, node.name) }.first
-        type_value(field.type, node, value)
+        field = @schema.get_field(parent_type.graphql_name, name) ||
+          @schema.possible_types(parent_type).filter_map { |t| @schema.get_field(t.graphql_name, name) }.first
+        type_value(field.type, name, selections, value)
       end
 
-      def type_value(type, node, value)
+      def type_value(type, name, selections, value)
         return if value.nil? # preserve null positions
 
         case type.kind.name
         when "NON_NULL"
-          type_value(type.of_type, node, value)
+          type_value(type.of_type, name, selections, value)
         when "LIST"
-          value.map { |element| type_value(type.of_type, node, element) }
+          value.map { |element| type_value(type.of_type, name, selections, element) }
         when "SCALAR"
-          scalar_value(type.graphql_name, node.name, value)
+          scalar_value(type.graphql_name, name, value)
         when "ENUM"
           value # enums aren't PII; preserving them keeps semantics
         when "OBJECT", "UNION", "INTERFACE"
-          object_value(type, node.selections, value)
+          object_value(type, selections, value)
         else
           value
         end

data/lib/graph_weaver/testing/coverage.rb

@@ -41,15 +41,8 @@ module GraphWeaver
       def initialize(supergraph:, queries: GraphWeaver.queries_paths, fragments: GraphWeaver.fragments_paths)
         source = supergraph.to_s
         table = GraphWeaver::SchemaLoader.routing_table(source)
-        unless table.unsupported.empty?
-          # the same refusal the Router makes at construction: with the table
-          # incomplete, every number this would report is a guess
-          raise Unplannable.new(
-            "this supergraph uses federation constructs the local router doesn't read: " +
-              table.unsupported.join("; "),
-            category: :unsupported_federation,
-          )
-        end
+        # with the table incomplete, every number this would report is a guess
+        Unplannable.unsupported!(table)
 
         # Planning still runs with `absent` empty — a query is plannable or
         # not whoever is serving. Which subgraphs are *here* is asked
@@ -57,7 +50,7 @@ module GraphWeaver
         # says one resolves), and never refuses: with nothing loaded the
         # answer is simply "none", which is the SDL-alone CI run.
         @planner = Router::Planner.new(table:, schema: GraphWeaver::SchemaLoader.load(source))
-        @absent = table.subgraphs.reject { |name| Subgraphs.candidates(table, name).any? }
+        @absent = table.subgraphs.reject { |name| Subgraphs.served?(table, name) }
         @local = @absent.size < table.subgraphs.size
         @shared = GraphWeaver::Codegen.load_fragments(fragments)
         @results = GraphWeaver.query_files(queries).map { |path| measure(path) }
@@ -144,8 +137,10 @@ module GraphWeaver
       # the directory every query came from, so the report's file column is
       # filenames rather than the same path repeated
       def shared_dir
-        dirs = @results.map { |result| File.dirname(result.path) }.uniq
-        dirs.one? ? "#{dirs.first}/" : ""
+        @shared_dir ||= begin
+          dirs = @results.map { |result| File.dirname(result.path) }.uniq
+          dirs.one? ? "#{dirs.first}/" : ""
+        end
       end
 
       def measure(path)

data/lib/graph_weaver/testing/failure.rb

@@ -51,8 +51,10 @@ module GraphWeaver
       end
 
       def throttled
-        # array-wrapped so the hash can't parse as kwargs
-        graphql([{ message: "rate limited", extensions: { code: "THROTTLED" } }])
+        # a code from the list #throttled? recognizes, not one spelled here —
+        # a fake that doesn't trip the predicate it exists to exercise is worse
+        # than no fake. (array-wrapped so the hash can't parse as kwargs)
+        graphql([{ message: "rate limited", extensions: { code: GraphWeaver::GraphQLError::THROTTLE_CODES.first } }])
       end
 
       # A validation-shaped rejection — trips schema_stale? and its

data/lib/graph_weaver/testing/fake_client.rb

@@ -96,7 +96,7 @@ class GraphWeaver::Testing::FakeClient
     @schema = schema || config.schema || raise(GraphWeaver::Error,
       "no schema to fake against — set GraphWeaver::Testing.config.schema, pass schema:, " \
       "or commit a schema dump at #{GraphWeaver.schema_path}")
-    @overrides = config.overrides.merge(overrides)
+    @overrides = config.overrides.merge(overrides).transform_keys(&:to_s)
     GraphWeaver::Testing.validate_overrides!(@schema, @overrides)
     @values = GraphWeaver::Testing::Values.new(seed:, mode:)
     @list_size = list_size || config.list_size

data/lib/graph_weaver/testing/router.rb

@@ -6,6 +6,7 @@ require "json"
 
 require_relative "../parsing"
 require_relative "../schema_loader"
+require_relative "../selection"
 require_relative "../transport"
 require_relative "subgraphs"
 
@@ -116,6 +117,21 @@ module GraphWeaver
       # the short label a report groups this refusal under
       def label = CATEGORIES.fetch(category).first
 
+      # Refuse a supergraph the routing table couldn't read whole. An unread
+      # @join__ construct leaves the table incomplete, so every answer drawn
+      # from it is a guess — including which schema serves which subgraph, so
+      # this comes before resolving those. Router and Coverage both refuse at
+      # construction, before any query, and say it the same way.
+      def self.unsupported!(table)
+        return if table.unsupported.empty?
+
+        raise new(
+          "this supergraph uses federation constructs the local router doesn't read: " +
+            table.unsupported.join("; "),
+          category: :unsupported_federation,
+        )
+      end
+
       def to_h = super.merge("category" => category.to_s, "detail" => detail)
     end
 
@@ -146,12 +162,12 @@ module GraphWeaver
     # the object the SDL spells rather than as a flattened path; and a union
     # or interface at a boundary, planned per concrete type and bucketed on
     # the `__typename` the data comes back with.
-    # Everything it can't plan
-    # *faithfully* raises {Unplannable}, before any subgraph runs, so a
-    # refusal can never be a half-executed query. Apollo's planner is twenty
-    # thousand lines; a double that approximated the rest of it would let a
-    # test pass on an answer production disagrees with, which is the most
-    # expensive thing this library can produce.
+    #
+    # Everything it can't plan *faithfully* raises {Unplannable}, before any
+    # subgraph runs, so a refusal can never be a half-executed query. Apollo's
+    # planner is twenty thousand lines; a double that approximated the rest of
+    # it would let a test pass on an answer production disagrees with, which is
+    # the most expensive thing this library can produce.
     #
     # Introspection is answered from the composed API schema — never from a
     # subgraph, which would reply with its own slice. That is the one split a
@@ -224,6 +240,12 @@ module GraphWeaver
         end
       end
 
+      # one error in the shape a GraphQL response carries them — a class
+      # method because the Planner refuses documents before a Router exists
+      def self.graphql_error(message, code)
+        { "message" => message, "extensions" => { "code" => code } }
+      end
+
       # subgraphs: names the Ruby schema serving each subgraph. Omit it (or
       # any of its entries) and the rest are derived from what each loaded
       # schema defines — see {Subgraphs}, which also checks the ones you name.
@@ -236,17 +258,7 @@ module GraphWeaver
         @context = context
         @trace = []
 
-        # refuse at construction, not per query: an unread @join__ construct
-        # means the routing table is incomplete, and every answer it gives
-        # about this supergraph is a guess — including which schema serves
-        # which subgraph, so this comes before resolving those
-        unless @table.unsupported.empty?
-          raise Unplannable.new(
-            "this supergraph uses federation constructs the local router doesn't read: " +
-              @table.unsupported.join("; "),
-            category: :unsupported_federation,
-          )
-        end
+        Unplannable.unsupported!(@table)
 
         served = Subgraphs.resolve(@table, subgraphs)
         @faked = served.select { |_name, schema| schema == Subgraphs::FAKE }.keys.freeze
@@ -257,19 +269,30 @@ module GraphWeaver
         @planner = Planner.new(table: @table, schema: @schema, absent: @absent)
       end
 
-      # Drop the fetches recorded so far. A router is built once and reused
-      # (the rspec tag builds one per suite), so without this #trace answers
-      # about whatever ran before as well.
+      # Drop the fetches recorded so far, so #trace answers about what runs
+      # next. For counting fetches across part of a run — the whole example
+      # boundary is #reset!.
       def reset_trace
         @trace = []
         self
       end
 
+      # An example boundary. A router is built once and reused (the rspec tag
+      # builds one per suite), so a faked subgraph would otherwise keep
+      # fabricating from wherever the previous example left its sequence —
+      # making the same example give different data alone than in a full run,
+      # which is exactly what `rspec --seed` promises it won't.
+      def reset!
+        reset_trace
+        @faked.each { |name| @subgraphs[name] = FakeSubgraph.new(name, @schema) }
+        self
+      end
+
       def execute(query, variables: {}, operation_name: nil)
         document = begin
           GraphQL.parse(query)
         rescue GraphQL::ParseError => e
-          return { "data" => nil, "errors" => [graphql_error(e.message, "GRAPHQL_PARSE_FAILED")] }
+          return { "data" => nil, "errors" => [Router.graphql_error(e.message, "GRAPHQL_PARSE_FAILED")] }
         end
 
         # validate the way a router does, so a stale query fails as it fails
@@ -341,13 +364,16 @@ module GraphWeaver
         response
       end
 
-      # Everything the plan applies at this level: one _entities fetch per
-      # subgraph the level defers to (all nodes at once — _entities answers
-      # in representation order), then the same again one level down.
+      # Only for evaluating @skip/@include, which read Booleans — so only the
+      # scalar defaults the parser hands back as Ruby values are wanted. An
+      # enum or input-object default is an AST node; sending one to a subgraph
+      # puts a parser back-pointer on the wire, or raises inside JSON. The
+      # subgraph applies those itself: used_variables copies each declaration
+      # verbatim, defaults and all.
       def variable_defaults(operation)
         operation.variables.each_with_object({}) do |definition, defaults|
           value = definition.default_value
-          next if value.nil? || value.is_a?(GraphQL::Language::Nodes::NullValue)
+          next unless value == true || value == false
 
           defaults[definition.name] = value
         end
@@ -358,7 +384,7 @@ module GraphWeaver
       # and includes under @skip — the same way graphql-ruby resolves it.
       def included?(node, variables)
         node.directives.all? do |directive|
-          next true unless %w[skip include].include?(directive.name)
+          next true unless GraphWeaver::Selection::CONDITIONAL_DIRECTIVES.include?(directive.name)
 
           argument = directive.arguments.find { |arg| arg.name == "if" } or next true
           value = argument.value
@@ -368,6 +394,9 @@ module GraphWeaver
         end
       end
 
+      # Everything the plan applies at this level: one _entities fetch per
+      # subgraph the level defers to (all nodes at once — _entities answers
+      # in representation order), then the same again one level down.
       def stitch(step, nodes, operation, variables, errors)
         return if nodes.empty?
 
@@ -386,14 +415,14 @@ module GraphWeaver
 
         blocked = prefetch(step, nodes, operation, variables, errors)
 
-        # a @requires fetch and a plain one need different node sets, so they
-        # can't share a call even into the same subgraph — which is the split
-        # a real router makes too
         # A fetch for a selection the operation excluded is a fetch a real
         # router never makes, and `trace` is something specs assert on. The
         # plan is built once and reused, so only here are the variables known.
         wanted = step.deferrals.select { |d| included?(d.node, variables) }
 
+        # a @requires fetch and a plain one need different node sets, so they
+        # can't share a call even into the same subgraph — which is the split
+        # a real router makes too
         wanted.group_by { |d| [d.subgraph, d.requires.any?] }.each do |(target, chained), deferrals|
           fetched = chained ? nodes.reject { |(node, _)| blocked.include?(node.object_id) } : nodes
           tree = Router.field_tree(deferrals.flat_map(&:representation).uniq)
@@ -609,10 +638,6 @@ module GraphWeaver
         end
       end
 
-      def graphql_error(message, code)
-        { "message" => message, "extensions" => { "code" => code } }
-      end
-
       # ---- null propagation ---------------------------------------------
 
       # a position whose type forbids null but whose value is null: the
@@ -634,7 +659,10 @@ module GraphWeaver
           # __typename the fetch bucketed by says what this object is. Without
           # one the subtree ran whole in one subgraph, which already applied
           # its own propagation — there is nothing to redo.
-          concrete = value.is_a?(Hash) ? @schema.types[value[TYPENAME] || value["__typename"]] : nil
+          # get_type, not types[]: the latter merges every type through a
+          # visibility filter into a fresh hash, and this runs once per
+          # response row — so it would cost rows x schema size
+          concrete = value.is_a?(Hash) ? @schema.get_type(value[TYPENAME] || value["__typename"]) : nil
           return value unless concrete&.kind&.fields?
 
           propagate_object(value, concrete, @planner.narrow(concrete.graphql_name, selections, fragments), fragments)
@@ -782,9 +810,8 @@ module GraphWeaver
 
         # the operation's validation errors, GraphQL-wire shaped
         def validate(document)
-          @schema.validate(document).map do |error|
-            { "message" => error.message, "extensions" => { "code" => "GRAPHQL_VALIDATION_FAILED" } }
-          end
+          @schema.validate(document)
+            .map { |error| Router.graphql_error(error.message, "GRAPHQL_VALIDATION_FAILED") }
         end
 
         def plan(document, operation_name: nil)
@@ -897,7 +924,7 @@ module GraphWeaver
         def applies?(condition, concrete)
           return true if condition.nil? || condition == concrete
 
-          type = @schema.types[condition]
+          type = @schema.get_type(condition)
           !!type&.kind&.abstract? && @schema.possible_types(type).any? { |t| t.graphql_name == concrete }
         end
 
@@ -1028,7 +1055,7 @@ module GraphWeaver
         def plan_child(type_name, node, subgraph, field, fragments, depth)
           child_type = child_type_name(type_name, node.name)
           return plan_branches(type_name, node, child_type, subgraph, field, fragments, depth) if
-            @schema.types[child_type]&.kind&.abstract?
+            @schema.get_type(child_type)&.kind&.abstract?
 
           plan_step(child_type, narrow(child_type, node.selections, fragments), subgraph, fragments,
             provides(field), depth + 1)
@@ -1206,13 +1233,7 @@ module GraphWeaver
         # Dotted paths back to the selection set they were parsed from — the
         # inverse of RoutingTable.parse_field_set, so a refusal spells the
         # field set the way the schema does and is greppable against it.
-        def field_set(paths)
-          tree = {}
-          paths.each do |path|
-            path.split(".").reduce(tree) { |node, segment| node[segment] ||= {} }
-          end
-          render_field_set(tree)
-        end
+        def field_set(paths) = render_field_set(Router.field_tree(paths))
 
         def render_field_set(tree)
           tree.map { |name, children|
@@ -1415,7 +1436,7 @@ module GraphWeaver
         end
 
         def raw_child_type(type_name, field_name)
-          type = @schema.types[type_name]
+          type = @schema.get_type(type_name)
           return unless type.respond_to?(:fields)
 
           field = type.fields[field_name] or return

data/lib/graph_weaver/testing/subgraphs.rb

@@ -45,13 +45,7 @@ module GraphWeaver
         # Names in `given` skip detection (:fake included); the rest are
         # derived, and both go through the same check.
         def resolve(table, given = nil, schemas: nil)
-          named = (given || {}).to_h { |name, schema| [name.to_s, schema] }
-          unknown = named.keys - table.subgraphs
-          if unknown.any?
-            raise GraphWeaver::ConfigurationError, "subgraphs: names #{unknown.join(", ")}, which " \
-              "this supergraph doesn't have (its subgraphs are #{table.subgraphs.join(", ")})"
-          end
-
+          named = table.named_subgraphs(given)
           searched = schemas || GraphWeaver::Schemas.loaded
           table.subgraphs.filter_map do |name|
             served = named.key?(name) ? check!(table, name, named[name]) : detect(table, name, searched)
@@ -81,6 +75,16 @@ module GraphWeaver
           expected(table, name).reject { |coordinate| GraphWeaver::Schemas.defines?(schema, coordinate) }
         end
 
+        # Is this subgraph served in this process? Exactly one candidate is
+        # what that means: none is somebody else's service, and several is a
+        # question only the caller can answer, so neither is something a suite
+        # can run against. `detect` turns the several into a refusal at
+        # construction; a report counts it as not served here, which is the
+        # same verdict phrased for something that never raises.
+        def served?(table, name, schemas = GraphWeaver::Schemas.loaded)
+          candidates(table, name, schemas).one?
+        end
+
         private
 
         # The schema serving `name`, or nil when nothing here does — the

data/lib/graph_weaver/testing.rb

@@ -50,8 +50,11 @@ module GraphWeaver
     CLIENT_MODES = %i[fake in_process router].freeze
 
     class Config
-      attr_accessor :schema, :overrides, :seed, :list_size, :null_chance, :cassette_dir, :context,
+      attr_accessor :overrides, :seed, :list_size, :null_chance, :cassette_dir, :context,
         :record, :anonymize
+      # #schema is written plainly and read with a fallback (below), the way
+      # #mode, #router and #default_mode are read plainly and written with a check
+      attr_writer :schema
       attr_reader :mode, :router, :default_mode
 
       def initialize
@@ -169,7 +172,10 @@ module GraphWeaver
       # client already runs in-process. Only a live class has resolvers, so
       # there is nothing else to fall back to: a dump is type information.
       def schema_class!
-        runnable(schema) || GraphWeaver.live_schema ||
+        # explicit_schema, not schema: the latter falls back to the committed
+        # dump, which loads as an anonymous GraphQL::Schema subclass — runnable
+        # by every test that matters, and holding not one resolver.
+        runnable(explicit_schema) || GraphWeaver.live_schema ||
           raise(GraphWeaver::Error, ":in_process runs your resolvers, so it needs the live " \
             "GraphQL::Schema class — and GraphWeaver.client isn't running one in-process to " \
             "borrow. Name it in the example — graphql_in_process(MySchema) — or set " \

data/lib/graph_weaver/version.rb

@@ -1,3 +1,3 @@
 module GraphWeaver
-  VERSION = "0.5.0"
+  VERSION = "0.5.1"
 end

data/lib/graph_weaver.rb

@@ -68,6 +68,27 @@ module GraphWeaver
     # body has to brand rather than escape as a raw Sorbet TypeError from a sig
     # (which fires before the struct's own rescue can see it). Lives here rather
     # than unrolled into every generated module.
+    # Cast a response's data, keeping the server's own errors on a failure.
+    # The common cause of a cast failure is a field that came back null *with
+    # a reason attached* — a permission rule, a partial outage — and raising
+    # only Sorbet's nil complaint throws that reason away, leaving whoever is
+    # on call with a type error and no explanation.
+    sig do
+      params(struct: T.untyped, data: T.untyped, errors: T::Array[GraphWeaver::GraphQLError])
+        .returns(T.untyped)
+    end
+    def cast_data(struct, data, errors)
+      struct.from_h(data)
+    rescue GraphWeaver::TypeError => e
+      raise if errors.empty?
+
+      detail = e.message.delete_prefix("failed to cast response into #{struct}: ")
+      raise GraphWeaver::TypeError.new(
+        struct:,
+        message: "#{detail} — the server also reported: #{errors.map(&:message).join("; ")}",
+      )
+    end
+
     def check_envelope!(raw, struct)
       unless raw.is_a?(Hash)
         raise GraphWeaver::TypeError.new(struct:, message: "response must be an object, got #{raw.class}")
@@ -131,11 +152,6 @@ module GraphWeaver
     # read. A second schema is a second generate! (schema: names it).
     attr_writer :schema_path
 
-    # Set by every graph_weaver rake task: those tasks WRITE the generated
-    # files, so loading them first lets a stale one block its own repair.
-    # None of them needs the modules loaded.
-    attr_accessor :skip_generated_load
-
     def queries_paths = @queries_paths ||= ["app/graphql/queries"]
     def generated_paths = @generated_paths ||= ["app/graphql/generated", "app/graphql/*/generated"]
 
@@ -159,6 +175,11 @@ module GraphWeaver
 
     def schema_path = @schema_path || "app/graphql/schema.json"
 
+    # Set by every graph_weaver rake task: those tasks WRITE the generated
+    # files, so loading them first lets a stale one block its own repair.
+    # None of them needs the modules loaded.
+    attr_accessor :skip_generated_load
+
     # Every query document under these directories, sorted — the files
     # generate!, verify_generated!, check_queries and load_queries! all read.
     def query_files(paths = queries_paths)
@@ -324,10 +345,11 @@ module GraphWeaver
 
       # locate_schema! raises the conventional "no schema dump" message
       path = SchemaLoader.locate_path or locate_schema!
-      meta = SchemaLoader.provenance(path)
-      return SchemaLoader.load(path) unless meta&.key?("url")
+      return SchemaLoader.load(path) unless SchemaLoader.provenance(path)&.key?("url")
 
-      SchemaLoader.introspect(new(meta["url"], auth: ENV["GRAPHWEAVER_AUTH"]).transport)
+      # 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
 
@@ -607,15 +629,18 @@ module GraphWeaver
     #
     # schema: is a graphql-ruby schema or a Client (its schema, and its
     # transport as the module's default). query is a .graphql/.gql path (module
-    # name derived from the file name
-    # and the operation — see #module_name) or a raw query string (name
-    # derived from the operation name,
-    # falling back to "Query" for anonymous operations — collisions are
-    # impossible since each parse gets its own container). Pass name: to
-    # override, client: to bake the module's default client/transport.
+    # name derived from the file name and the operation — see #module_name) or
+    # a raw query string (name derived from the operation name, falling back to
+    # "Query" for anonymous operations — collisions are impossible since each
+    # parse gets its own container). Pass name: to override, client: to bake
+    # the module's default client/transport.
     def parse(schema:, query:, name: nil, client: nil, fragments: fragments_paths)
       client ||= schema if schema.is_a?(Client)
       schema = schema_for(schema)
+      # Rails.root.join(...) hands you a Pathname, and to_path is the
+      # ecosystem's "I am a path" — the same conversion schema: gets through
+      # SchemaLoader.load. Without it end_with? below is a NoMethodError.
+      query = query.to_path if query.respond_to?(:to_path)
       path = query if query.end_with?(".graphql", ".gql")
       if path
         query = File.read(path)