graph_weaver 0.5.0 → 0.6.0

data/lib/graph_weaver/schema_loader.rb

@@ -5,6 +5,8 @@ require "fileutils"
 require "graphql"
 require "json"
 require_relative "errors"
+require_relative "internal"
+require_relative "schema_diff"
 
 # Load a schema for codegen from either format a remote service can hand
 # you — introspection JSON or SDL, as a file path or the content itself —
@@ -25,7 +27,7 @@ module GraphWeaver::SchemaLoader
     source = source.to_path if source.respond_to?(:to_path)
 
     if source.lstrip.start_with?("{") # introspection JSON content
-      build_introspection(JSON.parse(source))
+      build_introspection(parse_json(source, "the schema content"))
     elsif sdl_content?(source) # SDL content, one line or many
       build_sdl(source)
     elsif source.include?("\n") # content, but nothing we recognize
@@ -40,48 +42,70 @@ module GraphWeaver::SchemaLoader
   # `type` definition — and a one-line `type Query { hi: String }`, the shape
   # you'd type in a console, still is.
   SDL_CONTENT = /\A\s*(?:\#|"|(?:schema|type|interface|union|enum|scalar|directive|input|extend)\b[\s{(@])/
+  private_constant :SDL_CONTENT
 
   def self.sdl_content?(source)
     source.match?(SDL_CONTENT)
   end
-  private_class_method :sdl_content?
 
   def self.load_path(path)
     case File.extname(path)
     when ".json"
-      build_introspection(JSON.parse(read_schema(path)))
+      build_introspection(parse_json(read_schema(path), path))
     when ".graphql", ".gql"
       build_sdl(read_schema(path))
     else
-      raise GraphWeaver::Error,
-        "unsupported schema format: #{path} — expected a .json (introspection) or " \
-        ".graphql/.gql (SDL) path, or the content itself#{url_hint(path)}"
+      raise GraphWeaver::Error, url_error(path) ||
+        "unsupported schema format: #{truncate(path)} — expected a .json (introspection) or " \
+        ".graphql/.gql (SDL) path, or the content itself"
     end
   end
   private_class_method :load_path
 
   def self.read_schema(path)
-    File.read(path)
+    File.read(GraphWeaver::Internal::Util.resolve(path))
   rescue SystemCallError => e
     raise GraphWeaver::Error, "can't read the schema at #{path}: #{e.message}"
   end
   private_class_method :read_schema
 
-  # A bare host is the near miss worth naming: "unsupported schema format"
-  # sends you looking at the filesystem when the cause is the missing scheme.
-  HOST_LIKE = %r{\A[a-z0-9-]+(?:\.[a-z0-9-]+)+(?::\d+)?(?:/\S*)?\z}i
+  # A .json that isn't JSON is the corrupt-dump case — a truncated download,
+  # an interrupted write, a login page saved over it. JSON::ParserError names
+  # neither the file nor what it holds, and isn't under the Error umbrella.
+  def self.parse_json(text, source)
+    JSON.parse(text)
+  rescue JSON::ParserError => e
+    holds = text.strip.empty? ? "it is empty" : "it starts #{text.lstrip[0, 60].inspect}"
+    raise GraphWeaver::Error,
+      "#{source} isn't JSON (#{e.message}) — an introspection dump is the whole envelope, " \
+      "{\"data\": {\"__schema\": …}}, and #{holds}"
+  end
+  private_class_method :parse_json
+
+  # A url with its scheme left off is the near miss worth leading with:
+  # "unsupported schema format" sends you looking at the filesystem when what
+  # you have is an endpoint. A dotted host, or any host carrying a port —
+  # localhost:4000 is the likeliest one to type and has no dot at all.
+  HOST_LIKE = %r{\A[a-z0-9-]+(?:(?:\.[a-z0-9-]+)+(?::\d+)?|:\d+)(?:/\S*)?\z}i
   # dotted-but-not-a-host: a file whose extension we simply don't read
   FILE_SUFFIXES = %w[yaml yml txt xml sdl md rb erb].freeze
+  private_constant :HOST_LIKE, :FILE_SUFFIXES
 
-  def self.url_hint(source)
+  def self.url_error(source)
     return unless source.match?(HOST_LIKE)
 
     suffix = source[%r{\A[^/:]+}].to_s[/[^.]+\z/].to_s
     return if FILE_SUFFIXES.include?(suffix.downcase)
 
-    %( — "#{source}" looks like a host; did you mean "https://#{source}"?)
+    %("#{source}" looks like a url, not a path — did you mean "https://#{source}"? ) +
+      "A schema source is a .json (introspection) or .graphql/.gql (SDL) dump, or the content itself"
   end
-  private_class_method :url_hint
+  private_class_method :url_error
+
+  # a source we can't read is quoted back so it's recognizable, not reprinted
+  # — an unrecognized 3 MB dump would otherwise BE the error message
+  def self.truncate(source) = (source.length > 120) ? "#{source[0, 120]}…" : source
+  private_class_method :truncate
 
   # Build a schema from SDL, first normalizing whichever federation artifact
   # it is: a composed supergraph gets its composition machinery stripped (so
@@ -129,6 +153,7 @@ module GraphWeaver::SchemaLoader
       "specs it declares, a subgraph by applied-but-undeclared @key/@shareable/…",
     introspection: 'an introspection result — it should be the whole envelope, {"data": {"__schema": …}}',
   }.freeze
+  private_constant :SOURCE_KINDS
 
   # graphql-ruby reports a schema it can't build with whatever its internals
   # happen to raise — NoMethodError, ParseError, a bare RuntimeError — often
@@ -151,6 +176,7 @@ module GraphWeaver::SchemaLoader
   # @join__ marker misses: one that renamed join (`as: "j"`), and a core
   # schema that merged nothing but still carries core__Purpose.
   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.
@@ -164,6 +190,7 @@ module GraphWeaver::SchemaLoader
   # defines everything it applies (and federation_sdl? catches it first).
   SUBGRAPH_LINK = %r{@link\s*\(\s*url:\s*"https://specs\.apollo\.dev/federation/}
   SUBGRAPH_MARKERS = %w[key external extends provides requires shareable override interfaceObject].freeze
+  private_constant :SUBGRAPH_LINK, :SUBGRAPH_MARKERS
 
   # A raw subgraph SDL — `rover subgraph fetch`, `_service { sdl }`, or the
   # .graphql in a service repo — rather than a composed graph.
@@ -173,6 +200,7 @@ module GraphWeaver::SchemaLoader
 
     SUBGRAPH_MARKERS.any? { |name| sdl.match?(/@#{name}\b/) && !sdl.match?(/\bdirective\s+@#{name}\b/) }
   end
+  private_class_method :subgraph_sdl?
 
   # The subgraph spec's directives and the types they reference, keyed by
   # what a definition in the SDL would be named ("@key" for a directive).
@@ -209,6 +237,7 @@ module GraphWeaver::SchemaLoader
     "link__Import" => "scalar link__Import",
     "link__Purpose" => "enum link__Purpose { SECURITY EXECUTION }",
   }.freeze
+  private_constant :SUBGRAPH_DIRECTIVE_DEFS, :SUBGRAPH_HELPER_TYPES
 
   # A fed-2 subgraph that @links the spec under a namespace — `as: "fed"`,
   # and "federation" is the default — applies every non-imported directive
@@ -308,6 +337,7 @@ module GraphWeaver::SchemaLoader
   # only ever adds to this.
   DEFAULT_PREFIXES = %w[join__ link__ core__].freeze
   DEFAULT_DIRECTIVES = %w[link core inaccessible].freeze
+  private_constant :LINK_DIRECTIVES, :DEFAULT_PREFIXES, :DEFAULT_DIRECTIVES
 
   # What THIS document calls federation's machinery — type-name prefixes,
   # directive names, and the local names @inaccessible answers to — read off
@@ -375,6 +405,7 @@ module GraphWeaver::SchemaLoader
 
   VERSION_TAG = /\Av\d+\.\d+\z/
   GRAPHQL_NAME = /\A[A-Za-z][A-Za-z0-9_]*\z/
+  private_constant :VERSION_TAG, :GRAPHQL_NAME
 
   # The name a linked spec's elements are namespaced under: the URL's
   # penultimate path segment when the last is a version tag, else the last one.
@@ -427,6 +458,7 @@ module GraphWeaver::SchemaLoader
 
     GraphQL::Language::Nodes::Document.new(definitions: defs).to_query_string
   end
+  private_class_method :strip_federation
 
   # a synthetic composition definition to drop: a federation directive
   # definition (by name), or a synthetic join__*/link__* type (by prefix)
@@ -591,14 +623,14 @@ module GraphWeaver::SchemaLoader
       # schema.graphql already sits there
       existing = cache_candidates(cache).find { |candidate| fresh?(candidate, ttl) }
       if existing
-        GraphWeaver.log(:info) { "schema cache hit: #{existing}#{" (ttl #{ttl}s)" if ttl}" }
+        GraphWeaver::Internal::Log.log(:info) { "schema cache hit: #{existing}#{" (ttl #{ttl}s)" if ttl}" }
         return load(existing)
       end
 
-      GraphWeaver.log(:info) { "schema cache miss: #{cache}" }
+      GraphWeaver::Internal::Log.log(:info) { "schema cache miss: #{cache}" }
     end
 
-    result = GraphWeaver.log_timed(:info, "introspected #{endpoint(transport)}") do
+    result = GraphWeaver::Internal::Log.log_timed(:info, "introspected #{endpoint(transport)}") do
       transport.execute(GraphQL::Introspection.query, variables: {}).to_h
     end
     if (errors = result["errors"])
@@ -617,7 +649,6 @@ module GraphWeaver::SchemaLoader
     schema = GraphQL::Schema.from_introspection(result)
 
     if cache
-      FileUtils.mkdir_p(File.dirname(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)
@@ -628,8 +659,17 @@ module GraphWeaver::SchemaLoader
         header = meta && "# graph_weaver: #{JSON.generate(meta)}\n\n"
         "#{header}#{schema.to_definition}"
       end
-      File.write(cache, content)
-      GraphWeaver.log(:info) { "wrote schema cache: #{cache} (#{content.bytesize} bytes)" }
+      begin
+        FileUtils.mkdir_p(File.dirname(cache))
+        GraphWeaver::Internal::Util.atomic_write(cache, content)
+      rescue SystemCallError => e
+        # the introspection worked and the write didn't, which a bare Errno
+        # says neither of — and cache: is the argument to change
+        raise GraphWeaver::Error,
+          "introspected #{endpoint(transport)} but couldn't write the schema cache " \
+          "to #{cache}: #{e.message}"
+      end
+      GraphWeaver::Internal::Log.log(:info) { "wrote schema cache: #{cache} (#{content.bytesize} bytes)" }
     end
 
     schema
@@ -661,13 +701,18 @@ module GraphWeaver::SchemaLoader
   # The provenance recorded in a dump ({"url" => ..., "introspected_at"
   # => ..., "auth_env" => ...}), whichever format holds it; nil for
   # local/unannotated dumps.
+  # A corrupt dump records nothing readable, which is what nil says — and
+  # `schema:refresh` is the fix for one, so it must not be the thing that
+  # trips over it.
   def self.provenance(path)
-    content = File.read(path)
+    content = File.read(GraphWeaver::Internal::Util.resolve(path))
     if path.end_with?(".json")
       JSON.parse(content)["graph_weaver"]
     elsif (meta = content[/\A# graph_weaver: (\{.*\})$/, 1])
       JSON.parse(meta)
     end
+  rescue JSON::ParserError
+    nil
   end
 
   # The ENV var a dump's token lives in — whichever the generator recorded,
@@ -675,19 +720,20 @@ module GraphWeaver::SchemaLoader
   # that authenticates and rake tasks that 401.
   def self.auth_env(path = nil)
     # the first refresh names a dump that doesn't exist yet
-    recorded = provenance(path)&.dig("auth_env") if path && File.exist?(path)
+    recorded = provenance(path)&.dig("auth_env") if path && File.exist?(GraphWeaver::Internal::Util.resolve(path))
     recorded || DEFAULT_AUTH_ENV
   end
+  private_class_method :auth_env
 
-  # Re-introspect a dump's source and compare — true when the server has
-  # drifted from what's on disk. transport: overrides the transport (auth
-  # etc); by default one is built from the dump's recorded url. Wired up
-  # as `rake graph_weaver:schema:diff` / `:refresh`.
-  def self.stale?(path, transport: nil)
+  # Re-introspect a dump's source and compare — a {SchemaDiff} naming what
+  # moved, empty when the server still matches what's on disk. transport:
+  # overrides the transport (auth etc); by default one is built from the
+  # dump's recorded url. Wired up as `rake graph_weaver:schema:diff`.
+  def self.diff(path, transport: nil)
     transport ||= source_transport(path)
     fresh = introspect(transport)
 
-    fresh.to_definition != load(path).to_definition
+    GraphWeaver::SchemaDiff.new(load(path), fresh, source: path, target: endpoint(transport).to_s)
   end
 
   # Re-introspect and rewrite the local dump, returning [path, url].
@@ -718,8 +764,10 @@ module GraphWeaver::SchemaLoader
   end
   private_class_method :refresh_hint
 
-  # a transport to the dump's recorded url, authenticated from whichever
-  # ENV var the dump named (else GRAPHWEAVER_AUTH)
+  # 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
+  # dump's own server — building one at a call site is how `--auth MY_TOKEN`
+  # ends up honoured in some places and not others.
   def self.source_transport(path)
     meta = provenance(path)
     unless meta&.key?("url")
@@ -730,7 +778,6 @@ module GraphWeaver::SchemaLoader
 
     GraphWeaver.new(meta["url"], auth: ENV[auth_env(path)]).transport
   end
-  private_class_method :source_transport
 
   # Where a dump came from, recorded into the file so it can be
   # re-verified later — a parsable header comment in SDL, a
@@ -750,13 +797,16 @@ module GraphWeaver::SchemaLoader
   private_class_method :stamp
 
   CACHE_EXTENSIONS = %w[.json .graphql .gql].freeze
+  private_constant :CACHE_EXTENSIONS
 
   # cache: true / :json / :graphql / :gql / a path => the file to write
   # (nil for no caching). Symbols and true anchor at GraphWeaver.schema_path —
   # the schema dump the generation workflow reads, so one file serves both
   # (introspect caches it, rake generate loads it).
   def self.cache_path(cache)
-    case cache
+    # Rails.root.join(...) hands you a Pathname, as schema: and query: already take
+    cache = cache.to_path if cache.respond_to?(:to_path)
+    path = case cache
     when nil, false
       nil
     when true
@@ -774,11 +824,13 @@ module GraphWeaver::SchemaLoader
 
       cache
     end
+    path && GraphWeaver::Internal::Util.resolve(path)
   end
   private_class_method :cache_path
 
   # the requested path first, then its siblings in the other formats
   def self.cache_candidates(path)
+    path = GraphWeaver::Internal::Util.resolve(path)
     base = strip_extension(path)
     [path, *CACHE_EXTENSIONS.map { |ext| base + ext }].uniq
   end
@@ -839,8 +891,10 @@ module GraphWeaver::SchemaLoader
     # One field's routing: `graphs` resolve it, `external` declare it without
     # resolving it (an @external copy exists so that subgraph can @key or
     # @requires on it), and requires/provides/override carry the field sets and
-    # the migration marker verbatim.
-    Field = Struct.new(:graphs, :external, :requires, :provides, :override)
+    # the migration marker verbatim. `contextual` names the arguments a
+    # @fromContext fills from an ancestor selection (federation 2.8) — a fetch
+    # has to supply them, so whoever plans one needs to know they exist.
+    Field = Struct.new(:graphs, :external, :requires, :provides, :override, :contextual)
 
     # Every @join__ directive this table understands. One it doesn't is a
     # federation construct nobody has taught it to read, and it lands in
@@ -850,6 +904,7 @@ module GraphWeaver::SchemaLoader
       join__type join__field join__graph join__implements
       join__unionMember join__enumValue join__owner
     ].to_set.freeze
+    private_constant :Field, :KNOWN
 
     # every subgraph in the graph, in the order the supergraph declares them
     attr_reader :subgraphs
@@ -938,6 +993,19 @@ module GraphWeaver::SchemaLoader
       owners(type_name, field_name)
     end
 
+    # A `subgraphs:` map with string keys, refusing a name this supergraph
+    # doesn't have — a typo'd key would otherwise silently configure nothing.
+    # Lives here so the test router and the drift check refuse identically:
+    # two copies of this drifted apart once already.
+    def named_subgraphs(given)
+      map = (given || {}).to_h { |name, schema| [name.to_s, schema] }
+      unknown = map.keys - subgraphs
+      return map if unknown.empty?
+
+      raise GraphWeaver::ConfigurationError, "subgraphs: names #{unknown.join(", ")}, which " \
+        "this supergraph doesn't have (its subgraphs are #{subgraphs.join(", ")})"
+    end
+
     # The @key field sets a subgraph will answer an `_entities` fetch on, each
     # as a list of dotted paths ("id organization { id }" => ["id",
     # "organization.id"]). A `resolvable: false` key declares a shape this
@@ -994,16 +1062,27 @@ module GraphWeaver::SchemaLoader
 
     # join__Graph's enum values ARE the subgraphs: ACCOUNTS
     # @join__graph(name: "accounts", url: "...").
+    #
+    # This table reads the join spec under its default name, and only that —
+    # a supergraph that renamed it (`@link(url: ".../join/v0.3", as: "j")`)
+    # spells every marker `j__` and lands here with nothing found. Being told
+    # a composed graph has no subgraphs is worse than being refused, so an
+    # empty read is `unsupported` rather than an answer.
     def read_graphs
       enum = @document.definitions.find do |defn|
         defn.is_a?(GraphQL::Language::Nodes::EnumTypeDefinition) && defn.name == "join__Graph"
       end
-      return unless enum
 
-      enum.values.each do |value|
+      enum&.values&.each do |value|
         name = argument(value.directives.find { |d| d.name == "join__graph" }, "name")
         @names[value.name] = name if name
       end
+
+      return if @names.any?
+
+      @unsupported << "no join__Graph enum names the subgraphs — this schema declares a " \
+        "composition spec, so either it merged nothing, or it renamed the join spec " \
+        "(@link(url: \".../join/v0.3\", as: \"...\")), which this table doesn't follow"
     end
 
     # What each abstract type can be, from the SDL alone — a union's members,
@@ -1087,6 +1166,7 @@ module GraphWeaver::SchemaLoader
           resolvable.filter_map { |d| argument(d, "requires") }.first,
           resolvable.filter_map { |d| argument(d, "provides") }.first,
           applied.filter_map { |d| argument(d, "override") }.first,
+          applied.flat_map { |d| context_arguments(d) },
         )]
       end.to_h
     end
@@ -1102,6 +1182,17 @@ module GraphWeaver::SchemaLoader
       end
     end
 
+    # The argument names a @join__field says come from a @context. The rest of
+    # each entry (the context's name, and the selection read out of it) is the
+    # gateway's business; what a planner needs is that the fetch it builds
+    # would leave these unset.
+    def context_arguments(directive)
+      entries = argument(directive, "contextArguments")
+      return [] unless entries.is_a?(Array)
+
+      entries.filter_map { |entry| argument(entry, "name") }
+    end
+
     # the subgraph NAME a directive's graph: argument points at
     def subgraph(directive) = @names[argument(directive, "graph")]
 

data/lib/graph_weaver/tasks.rb

@@ -24,6 +24,36 @@
 #      rake graph_weaver:cassettes:check       # fail if a recording no longer casts
 require_relative "../graph_weaver"
 
+module GraphWeaver
+  module Internal
+    # helpers the rake tasks share
+    module Tasks
+      # The composed supergraph a federation task reads: SUPERGRAPH=, else the
+      # conventional dump when that is what it is. Aborts naming the task, so
+      # the message says the command to retype.
+      def self.supergraph!(task)
+        ENV["SUPERGRAPH"] || GraphWeaver::SchemaLoader.locate_path ||
+          abort("pass the composed supergraph: rake graph_weaver:federation:#{task} " \
+            "SUPERGRAPH=supergraph.graphql")
+      end
+
+      # Registrations the run couldn't match, once each. The logger is the
+      # runtime channel and is silent by default; this task's own output is the
+      # build channel, and the build is where someone regenerating is looking.
+      def self.report_unmatched
+        GraphWeaver.unmatched_registrations.each { |message| puts message }
+      end
+
+      # Neither task that needs the committed dump can take one itself, so both
+      # say which task can — the same sentence SchemaLoader gives on refresh.
+      def self.no_dump
+        "no schema dump at #{GraphWeaver.schema_path} — take one: " \
+          "rake graph_weaver:schema:refresh URL=https://api.example.com/graphql"
+      end
+    end
+  end
+end
+
 namespace :graph_weaver do
   # In Rails, boot the app first — initializers register scalars/enums/
   # helpers and they're baked into generated source. Rails defines
@@ -43,10 +73,24 @@ namespace :graph_weaver do
     GraphWeaver.skip_generated_load = false
   end
 
-  desc "Generate typed query modules (#{GraphWeaver.queries_paths.first} -> #{GraphWeaver.generated_paths.first})"
+  # the default, not GraphWeaver.queries_paths: a desc is baked when this file
+  # loads, which in Rails is before :environment has run an initializer that
+  # moves it — interpolating would print the default as though it were the setting
+  desc "Generate typed query modules (default app/graphql/queries -> app/graphql/generated)"
   task generate: :environment do
+    glob = File.join(GraphWeaver::Internal::Util.resolve(GraphWeaver.generated_paths.first), "**/*.rb")
+    before = Dir[glob]
+
     # schema auto-located at GraphWeaver.schema_path, any supported extension
-    GraphWeaver.generate!.each { |path| puts "wrote #{path}" }
+    written = GraphWeaver.generate!
+    changed = GraphWeaver.changed_files
+    changed.each { |path| puts "wrote #{path}" }
+    puts "#{written.size - changed.size} already up to date" if changed.size < written.size
+    # generated files are checked in, so a delete this task made is a diff the
+    # user is about to find; a run that printed nothing at all had done both
+    (before - Dir[glob]).each { |path| puts "pruned #{GraphWeaver::Internal::Util.relative(path)}" }
+    puts "no queries in #{GraphWeaver.queries_paths.join(", ")}" if written.empty?
+    GraphWeaver::Internal::Tasks.report_unmatched
   rescue GraphWeaver::Error => e
     # a typo'd query is a user error — the message names file, position and
     # fix, and a rake backtrace through codegen only buries it
@@ -57,6 +101,7 @@ namespace :graph_weaver do
   task verify: :environment do
     GraphWeaver.verify_generated!
     puts "generated queries up to date"
+    GraphWeaver::Internal::Tasks.report_unmatched
   rescue GraphWeaver::Error => e
     abort e.message
   end
@@ -67,12 +112,18 @@ namespace :graph_weaver do
 
     desc "Fail when the server's schema has drifted from the local dump"
     task diff: :environment do
-      path = GraphWeaver::SchemaLoader.locate_path or abort "no schema dump at #{GraphWeaver.schema_path}"
-      if GraphWeaver::SchemaLoader.stale?(path)
-        abort "#{path} is stale — the server's schema has drifted (rake graph_weaver:schema:refresh)"
+      path = GraphWeaver::SchemaLoader.locate_path or abort GraphWeaver::Internal::Tasks.no_dump
+      diff = GraphWeaver::SchemaLoader.diff(path)
+      dump = GraphWeaver::Internal::Util.relative(path)
+      if diff.empty?
+        puts "#{dump} matches the server"
+      else
+        puts diff.report
+        # abort writes to unbuffered stderr; the summary above went to
+        # block-buffered stdout, so a piped CI log shows it first
+        $stdout.flush
+        abort "#{dump} is stale — the server's schema has drifted (rake graph_weaver:schema:refresh)"
       end
-
-      puts "#{path} matches the server"
     rescue GraphWeaver::Error => e
       # e.g. a dump with no recorded url — same clean exit as :refresh
       abort e.message
@@ -80,8 +131,14 @@ namespace :graph_weaver do
 
     desc "Re-introspect and rewrite the local dump (URL= to bootstrap the first one)"
     task refresh: :environment do
+      # anything else in URL= reaches introspection as a schema *source*, and
+      # fails talking about file extensions rather than the flag just typed
+      if ENV["URL"] && !ENV["URL"].match?(GraphWeaver::Client::URL)
+        abort "URL= takes an endpoint: rake graph_weaver:schema:refresh URL=https://api.example.com/graphql"
+      end
+
       path, url = GraphWeaver::SchemaLoader.refresh!(url: ENV["URL"])
-      puts "refreshed #{path} from #{url}"
+      puts "refreshed #{GraphWeaver::Internal::Util.relative(path)} from #{url}"
     rescue GraphWeaver::Error => e
       abort e.message
     end
@@ -123,12 +180,7 @@ namespace :graph_weaver do
     task diff: :loaded do
       require "graph_weaver/federation"
 
-      supergraph = ENV["SUPERGRAPH"] || GraphWeaver::SchemaLoader.locate_path
-      unless supergraph
-        abort "pass the composed supergraph: rake graph_weaver:federation:diff " \
-          "SUPERGRAPH=supergraph.graphql"
-      end
-
+      supergraph = GraphWeaver::Internal::Tasks.supergraph!("diff")
       drift = GraphWeaver::Federation::Drift.new(supergraph:)
       puts drift.report
 
@@ -152,18 +204,14 @@ namespace :graph_weaver do
     task subgraphs: :loaded do
       require "graph_weaver/testing"
 
-      supergraph = ENV["SUPERGRAPH"] || GraphWeaver::SchemaLoader.locate_path
-      unless supergraph
-        abort "pass the composed supergraph: rake graph_weaver:federation:subgraphs " \
-          "SUPERGRAPH=supergraph.graphql"
-      end
+      supergraph = GraphWeaver::Internal::Tasks.supergraph!("subgraphs")
 
       # Testing::Router derives this map itself; this is for reading what
       # detection sees when it refuses, and for committing the map instead.
       table = GraphWeaver::SchemaLoader.routing_table(supergraph)
       rows = table.subgraphs.map do |name|
-        found = GraphWeaver::Testing::Subgraphs.candidates(table, name)
-        sought = GraphWeaver::Testing::Subgraphs.expected(table, name)
+        found = GraphWeaver::Internal::Subgraphs.candidates(table, name)
+        sought = GraphWeaver::Internal::Subgraphs.expected(table, name)
         [name, found, sought]
       end
       width = rows.map { |name, found, _| %("#{name}" => #{found.first&.name || "nil"},).length }.max
@@ -191,14 +239,8 @@ namespace :graph_weaver do
     task coverage: :loaded do
       require "graph_weaver/testing"
 
-      supergraph = ENV["SUPERGRAPH"] || GraphWeaver::SchemaLoader.locate_path
-      unless supergraph
-        abort "pass the composed supergraph: rake graph_weaver:federation:coverage " \
-          "SUPERGRAPH=supergraph.graphql"
-      end
-
       puts GraphWeaver::Testing::Coverage.new(
-        supergraph:,
+        supergraph: GraphWeaver::Internal::Tasks.supergraph!("coverage"),
         queries: ENV["QUERIES"] || GraphWeaver.queries_paths,
       ).report
     rescue GraphWeaver::Error => e
@@ -222,12 +264,15 @@ namespace :graph_weaver do
       # unlike its siblings this task reads generated modules — they are what
       # a recording is checked against
       GraphWeaver.load_generated!
-      modules = GraphWeaver.query_files.filter_map do |path|
-        name = GraphWeaver.module_name(path, File.read(path))
+      modules = GraphWeaver::Internal::Util.query_files.filter_map do |path|
+        name = GraphWeaver::Internal::Util.module_name(path, File.read(path))
         Object.const_get(name) if Object.const_defined?(name)
       end
 
-      dir = GraphWeaver::Testing.config.cassette_dir
+      # Testing.cassette_dir, not config.cassette_dir: the configured path is
+      # relative by default and rake runs from wherever it runs from
+      dir = GraphWeaver::Testing.cassette_dir
+      shown = GraphWeaver::Internal::Util.relative(dir)
       checks = Dir[File.join(dir, "*.yml")].sort.map do |path|
         GraphWeaver::Testing::Cassette.new(path).check(modules)
       end
@@ -244,9 +289,9 @@ namespace :graph_weaver do
       if checks.sum(&:checked).zero?
         # a green run that compared nothing is worse than a failure: it would
         # pass whatever the recordings said (see federation:diff)
-        abort "this checked nothing, so it proved nothing: no recording in #{dir} carries a query " \
+        abort "this checked nothing, so it proved nothing: no recording in #{shown} carries a query " \
           "any of the #{modules.size} generated modules sends. Drop this task from CI if you " \
-          "don't record cassettes, or check that #{dir} is where yours live."
+          "don't record cassettes, or check that #{shown} is where yours live."
       end
 
       puts "every recording still casts"
@@ -256,11 +301,18 @@ namespace :graph_weaver do
     task anonymize: :environment do
       require "graph_weaver/testing"
 
-      schema = GraphWeaver::SchemaLoader.load(GraphWeaver.schema_path)
-      Dir[File.join(GraphWeaver::Testing.config.cassette_dir, "*.yml")].sort.each do |path|
+      # locate, not schema_path: the dump is whichever supported extension is
+      # actually on disk, and every sibling task asks the same way
+      schema = GraphWeaver::SchemaLoader.locate or abort GraphWeaver::Internal::Tasks.no_dump
+      dir = GraphWeaver::Testing.cassette_dir
+      paths = Dir[File.join(dir, "*.yml")].sort
+      paths.each do |path|
         GraphWeaver::Testing::Cassette.new(path).anonymize!(schema:)
-        puts "anonymized #{path}"
+        puts "anonymized #{GraphWeaver::Internal::Util.relative(path)}"
       end
+      # silence and exit 0 read as "done" — say where we looked, the way every
+      # sibling task does
+      puts "no recordings in #{GraphWeaver::Internal::Util.relative(dir)}" if paths.empty?
     end
   end
 end