graph_weaver 0.7.5 → 0.7.7

data/lib/graph_weaver/railtie.rb

@@ -85,6 +85,12 @@ class GraphWeaver::Railtie < Rails::Railtie
     # calling ignore again — check_generated_ignored! refuses instead.
     attr_accessor :ignored_dirs
 
+    # The outputs left to Zeitwerk, resolved — the trees whose every module is
+    # the constant Zeitwerk infers from its path, so hiding them would be
+    # hiding code that already works. Decided beside the sweep, because it is
+    # what the sweep must not hide.
+    attr_accessor :autoloaded_dirs
+
     # Whether hiding an output right now would actually hide it: false until
     # the initializer below has swept (it picks up anything declared so far),
     # and false again from the moment Zeitwerk sets the main autoloader up.
@@ -108,14 +114,24 @@ class GraphWeaver::Railtie < Rails::Railtie
     GraphWeaver::Railtie.hide_generated!
   end
 
+  # ONE rule: a generated tree Zeitwerk would name correctly is left to
+  # Zeitwerk; any other is hidden from it and required at boot.
+  #
   # generated/person_query.rb defines ::PersonQuery, but Zeitwerk infers
   # Generated::PersonQuery from the path — and app/graphql/generated is inside
   # an autoload root by default, so eager loading raised "uninitialized
   # constant Generated::PersonQuery" in production while development (lazy) was
-  # fine. prepare_generated! requires them instead.
+  # fine. prepare_generated! requires those instead. A graph whose `namespace:`
+  # is the constant its output path spells has no such mismatch, and requiring
+  # it at boot would define its whole parent chain before a query is ever used.
   def self.hide_generated!
     self.ignored_dirs = []
+    self.autoloaded_dirs = []
     self.hiding_outputs = true
+    # the aligned trees first: they are what the sweep must NOT hide, and
+    # generated_paths' own globs cover a graph's output (app/graphql/*/generated
+    # matches app/graphql/billing/generated)
+    GraphWeaver.graphs.each { |graph| consider_output!(graph) }
     GraphWeaver::Internal::Util.generated_dirs.each { |path| ignore_output!(path) }
 
     # Zeitwerk reads its ignore list once, at setup, and nothing in Rails
@@ -124,12 +140,189 @@ class GraphWeaver::Railtie < Rails::Railtie
     # check_generated_ignored! has to be the one to say so.
     main = Rails.autoloaders.main if Rails.autoloaders.respond_to?(:main)
     if main.respond_to?(:on_setup)
-      main.on_setup { GraphWeaver::Railtie.hiding_outputs = false }
+      main.on_setup do
+        GraphWeaver::Railtie.hiding_outputs = false
+        GraphWeaver::Railtie.check_alignment!
+      end
     else
       self.hiding_outputs = false
     end
   end
 
+  # Which side of the rule one graph's output falls, and say so in a line at
+  # debug: a user who set `namespace:` and expected laziness learns here why
+  # they didn't get it. True when the tree is Zeitwerk's to load.
+  def self.consider_output!(graph)
+    dir = autoload_path(graph.output)
+    return true if autoloaded_dirs.include?(dir)
+    # already hidden by an earlier pass, and an ignore can't be taken back
+    return false if ignored_dirs.include?(dir)
+
+    reason = misalignment(graph, dir)
+    subject, = describe_output(dir)
+    if reason
+      GraphWeaver::Internal::Log.log(:debug) do
+        "#{subject} is hidden from Zeitwerk and required at boot — #{reason}"
+      end
+      # here rather than back in ignore_output!, so the decision is recorded
+      # the moment it is made and the sweep doesn't reach it a second time
+      hide!(dir)
+      return false
+    end
+
+    autoloaded_dirs << dir
+    # types.rb requires its own directory — one file per type, in the order the
+    # runtime needs — so Zeitwerk never autoloads those files one at a time.
+    # Only eager loading walks them, and it would want a constant name for each
+    # that the generator's own inflection doesn't promise: HTTPHeaderInput
+    # writes httpheader_input.rb, which Zeitwerk reads as HttpheaderInput.
+    # Loading types.rb is what loads them, and types.rb is eager loaded.
+    Rails.autoloaders.each { |loader| loader.do_not_eager_load(File.join(dir, "types")) }
+    GraphWeaver::Internal::Log.log(:debug) do
+      "#{subject} is left to Zeitwerk — every module it generates is the constant Zeitwerk reads " \
+        "off the path, so it autoloads on first reference and reloads with the app"
+    end
+    true
+  end
+
+  # Why Zeitwerk would NOT name what this graph generates the way its files do
+  # — nil when it would, which is the aligned case. The first disagreement is
+  # the whole answer: one namespace settles every file, so the fix for one is
+  # the fix for all of them.
+  def self.misalignment(graph, dir)
+    main = Rails.autoloaders.main if Rails.respond_to?(:autoloaders) && Rails.autoloaders.respond_to?(:main)
+    # 2.6.2 is where cpath_expected_at arrives, and with it the only answer
+    # that can confirm this one at setup — without it nothing is left to
+    # Zeitwerk, which is what every app got before.
+    unless main.respond_to?(:cpath_expected_at)
+      return "no autoloader here answers cpath_expected_at (Zeitwerk 2.6.2 and up does)"
+    end
+
+    if ignored_by_app?(dir)
+      return "it is already hidden from autoloading — a GraphWeaver.generated_paths pattern reaches " \
+        "it, or the app ignored it itself"
+    end
+
+    namespace = expected_cpath(dir)
+    return "it is not under an autoload path, so nothing but this would load it" unless namespace
+    unless namespace == graph.namespace
+      return "Zeitwerk reads that directory as #{namespace}, and this graph's constants are " \
+        "#{graph.namespace || "top-level"} (namespace #{namespace.inspect} makes them agree)"
+    end
+
+    types = expected_cpath(File.join(dir, "types.rb"))
+    return "types.rb defines #{graph.types_module}, Zeitwerk expects #{types}" unless types == graph.types_module
+
+    first_mismatch(graph, dir)
+  end
+
+  # The first query module whose name isn't the one Zeitwerk reads off its
+  # file. Only reached once the namespace agrees, so what is left is a file
+  # name the app's inflector camelizes differently from the generator.
+  def self.first_mismatch(graph, dir)
+    GraphWeaver::Internal::Util.query_files(graph.queries).each do |query|
+      name, filename = graph.generated_names(query, File.read(query))
+      expected = expected_cpath(File.join(dir, filename))
+      next if expected == name
+
+      return "#{filename} defines #{name}, Zeitwerk expects #{expected}"
+    end
+    nil
+  end
+
+  # The constant Zeitwerk will expect at an absolute path, or nil when nothing
+  # will autoload it.
+  #
+  # Zeitwerk answers this itself, with cpath_expected_at — but only once Rails
+  # has pushed the main loader's roots, and Rails does that INSIDE
+  # :setup_main_autoloader, whose start is the deadline for `ignore`. So the
+  # roots here are the list Rails is about to push, and every constant name
+  # comes from the loader's own inflector, which an app's `inflect`/`acronym`
+  # is already on. check_alignment! re-asks Zeitwerk the moment it can answer.
+  def self.expected_cpath(path)
+    main = Rails.autoloaders.main
+    roots = autoload_roots
+    cnames = []
+    dir = path
+    if path.end_with?(".rb")
+      cnames << main.inflector.camelize(File.basename(path, ".rb"), path)
+      dir = File.dirname(path)
+    end
+    until roots.key?(dir)
+      parent = File.dirname(dir)
+      return if parent == dir || ignored_by_app?(dir)
+
+      cnames << main.inflector.camelize(File.basename(dir), dir)
+      dir = parent
+    end
+    return if ignored_by_app?(dir)
+
+    [roots[dir], *cnames.reverse].compact.join("::")
+  end
+
+  # Every directory the main autoloader will have as a root, and the name of
+  # the namespace each sits under (nil for Object): the paths Rails is about to
+  # push, plus any the app pushed itself — which is the only way a root gets a
+  # namespace, and the one thing Rails leaves alone when it pushes the rest.
+  def self.autoload_roots
+    roots = {}
+    if defined?(ActiveSupport::Dependencies) && ActiveSupport::Dependencies.respond_to?(:autoload_paths)
+      once = Rails.autoloaders.respond_to?(:once) ? Rails.autoloaders.once.dirs : []
+      ActiveSupport::Dependencies.autoload_paths.each do |path|
+        path = path.to_s
+        # through autoload_path, so a root and an output under it are spelled
+        # the same way — a symlinked checkout (Capistrano's current/) otherwise
+        # has the root as Rails wrote it and the output as realpath saw it
+        roots[autoload_path(path)] = nil unless once.include?(path)
+      end
+    end
+    Rails.autoloaders.main.dirs(namespaces: true).each do |dir, namespace|
+      roots[autoload_path(dir)] = (namespace == Object) ? nil : namespace.name
+    end
+    roots
+  end
+
+  # An app that hid the directory itself has a tree Zeitwerk will not load
+  # however it is named — so it is one to require at boot, exactly as before.
+  def self.ignored_by_app?(dir)
+    asked = IGNORES.find { |name| Rails.autoloaders.main.respond_to?(name) }
+    asked && Rails.autoloaders.main.public_send(asked, dir)
+  end
+
+  # The prediction above, against the one answer that is authoritative. A
+  # `collapse` between the autoload root and the output, or a root pushed under
+  # its own namespace after this railtie looked, changes the name — and neither
+  # is readable before setup. Left unsaid, that surfaces as Zeitwerk's own
+  # error on the first eager load in production.
+  def self.check_alignment!
+    main = Rails.autoloaders.main
+    Array(autoloaded_dirs).each do |dir|
+      # the top level only: types/ is excluded from eager loading, so what
+      # Zeitwerk reads off those files never comes up
+      Dir[File.join(dir, "*.rb")].sort.each do |file|
+        expected = main.cpath_expected_at(file)
+        # nil is "I don't see that file" — which is what Zeitwerk answers for a
+        # path spelled through a symlink its own roots aren't, so it is not an
+        # answer to compare against
+        next if expected.nil? || expected == expected_cpath(file)
+
+        subject, short = describe_output(dir)
+        raise GraphWeaver::Error,
+          "#{subject} was left to Zeitwerk because the constants it generates are the ones its path " \
+          "spells — but Zeitwerk reads #{GraphWeaver::Internal::Util.relative(file)} as " \
+          "#{expected.inspect}, not #{expected_cpath(file).inspect}. A `collapse`, or an autoload root " \
+          "pushed under its own namespace, over #{short} changes that name: move the output out from " \
+          "under it, or set namespace: to what Zeitwerk reads."
+      end
+    end
+  end
+
+  # Whether this generated directory is one Zeitwerk is loading — what
+  # Internal::Util.required_dirs asks, so the boot-time require skips it.
+  def self.left_to_zeitwerk?(path)
+    Array(autoloaded_dirs).include?(autoload_path(path))
+  end
+
   # Hide one output from Zeitwerk, the moment it is named — a graph declared in
   # config/initializers says where it writes long after the sweep above ran.
   # Waiting for it instead is what `after: :load_config_initializers` used to
@@ -141,9 +334,17 @@ class GraphWeaver::Railtie < Rails::Railtie
   def self.ignore_output!(path)
     return unless hiding_outputs
 
-    # patterns, not paths — generated_paths may be globs, and Zeitwerk expands
-    # its own at setup, which is what the window stays open until
-    dir = autoload_path(path)
+    # a graph saying where it writes is also the moment the rule can be applied
+    # to it: config/initializers is later than the sweep above, so this is
+    # where an app's second graph is first heard of
+    graph = GraphWeaver.graphs.find { |candidate| autoload_path(candidate.output) == autoload_path(path) }
+    return if graph && consider_output!(graph)
+
+    hidden_for(path).each { |dir| hide!(dir) }
+  end
+
+  # Hide one resolved directory, once.
+  def self.hide!(dir)
     return if ignored_dirs.include?(dir)
 
     check_autoload_once!([dir])
@@ -151,6 +352,25 @@ class GraphWeaver::Railtie < Rails::Railtie
     Rails.autoloaders.each { |loader| loader.ignore(dir) }
   end
 
+  # What hiding one generated path means. Normally the pattern itself —
+  # generated_paths may be globs, and Zeitwerk expands its own at setup, so a
+  # directory a pattern will match is hidden however late it appears; that is
+  # what the window stays open until. The exception is a pattern that also
+  # covers a tree Zeitwerk is keeping (app/graphql/*/generated matches a
+  # namespaced graph's own output), since a glob can't say "all but this one":
+  # then it is expanded here and the aligned directories left out.
+  def self.hidden_for(path)
+    dir = autoload_path(path)
+    kept = Array(autoloaded_dirs)
+    return [dir] if kept.empty?
+
+    expanded = Dir[GraphWeaver::Internal::Util.resolve(path)]
+      .select { |found| File.directory?(found) }.map { |found| autoload_path(found) }
+    return [dir] if (expanded & kept).empty?
+
+    expanded - kept
+  end
+
   # The `once` autoloader is set up in bootstrap, before any of this — and
   # Zeitwerk reads its ignore list only at setup, so `loader.ignore` hides
   # nothing from it however the output is spelled. The generic advice ("name it
@@ -211,7 +431,9 @@ class GraphWeaver::Railtie < Rails::Railtie
   def self.describe_output(dir)
     graph = GraphWeaver.graphs.find { autoload_path(_1.output) == dir }
     short = GraphWeaver::Internal::Util.relative(GraphWeaver::Internal::Util.resolve(graph&.output || dir))
-    ["#{graph ? "graph :#{graph.name}'s output" : "generated path"} #{short}", short]
+    # the default graph has no name to say, and "graph :'s output" is worse
+    # than the path on its own
+    ["#{graph&.name ? "graph #{graph.name.inspect}'s output" : "generated path"} #{short}", short]
   end
 
   # A graph declared from to_prepare — what the docs say to do when its block
@@ -219,16 +441,20 @@ class GraphWeaver::Railtie < Rails::Railtie
   # Zeitwerk reads its ignore list only then. So an output that arrives that
   # late can't be hidden: its files load as ordinary autoloads and raise on the
   # constant they don't define, in a Zeitwerk error that blames a dropped
-  # extend_type. Refuse, and name what actually happened.
+  # extend_type. Refuse, and name what actually happened — unless the tree is
+  # one Zeitwerk names correctly, which needed no hiding at any point and is as
+  # true declared late as declared early.
   def self.check_generated_ignored!
     # no autoloaders, no Zeitwerk, nothing to refuse
     return unless Rails.respond_to?(:autoloaders)
 
-    late = GraphWeaver::Internal::Util.generated_dirs.map { autoload_path(_1) } - Array(ignored_dirs)
+    late = GraphWeaver::Internal::Util.generated_dirs.map { autoload_path(_1) } -
+      Array(ignored_dirs) - Array(autoloaded_dirs)
     return if late.empty?
 
     late.each do |dir|
       next unless Rails.autoloaders.any? { |loader| autoloaded?(loader, dir) }
+      next if aligned_late?(dir)
 
       subject, short = describe_output(dir)
       raise GraphWeaver::Error,
@@ -239,6 +465,17 @@ class GraphWeaver::Railtie < Rails::Railtie
     end
   end
 
+  # A graph declared after setup, whose tree Zeitwerk already names correctly:
+  # nothing had to be hidden, so nothing was missed. Recorded on the way past,
+  # so the boot-time require skips it too.
+  def self.aligned_late?(dir)
+    graph = GraphWeaver.graphs.find { autoload_path(_1.output) == dir }
+    return false unless graph && misalignment(graph, dir).nil?
+
+    self.autoloaded_dirs = Array(autoloaded_dirs) | [dir]
+    true
+  end
+
   # The two auto-wires an app gets for free, and the only two it can turn off
   # by assigning nil.
   #
@@ -408,8 +645,10 @@ class GraphWeaver::Railtie < Rails::Railtie
     # reloaded what it wrote.
     return if watcher&.execute_if_updated
 
-    # entries may be globs, so Dir[] rather than Dir.exist?
-    generated = GraphWeaver::Internal::Util.generated_dirs.any? do |dir|
+    # entries may be globs, so Dir[] rather than Dir.exist?. required_dirs, not
+    # generated_dirs: a tree left to Zeitwerk loads on first reference, and not
+    # requiring its whole parent chain here is the point of leaving it there.
+    generated = GraphWeaver::Internal::Util.required_dirs.any? do |dir|
       Dir[GraphWeaver::Internal::Util.resolve(dir)].any?
     end
     return unless generated
@@ -422,7 +661,7 @@ class GraphWeaver::Railtie < Rails::Railtie
     # request 500s on "uninitialized constant Accounts::PersonQuery" until a
     # .graphql edit happens to trigger the watcher. An un-namespaced module
     # defines a top-level constant Zeitwerk never manages, so it survives.
-    if GraphWeaver.graphs.any?(&:namespace)
+    if GraphWeaver.graphs.any? { |graph| graph.namespace && !left_to_zeitwerk?(graph.output) }
       GraphWeaver.reload_generated!
     else
       GraphWeaver.load_generated!

data/lib/graph_weaver/rspec.rb

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

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