graph_weaver 0.4.4 → 0.5.0

data/lib/graph_weaver/schemas.rb

@@ -0,0 +1,46 @@
+# typed: true
+# frozen_string_literal: true
+
+require "graphql"
+
+module GraphWeaver
+  # The graphql-ruby schema classes already in this process, and what each
+  # one defines. Where {SchemaLoader} *builds* a schema from a source — a
+  # path, SDL, an introspection dump — this reads classes the app loaded
+  # itself.
+  #
+  # Two features ask exactly these two questions, and match a schema on the
+  # coordinates it defines rather than on its class name: {Testing::Subgraphs}
+  # (which schema serves which subgraph) and {Federation::Drift} (has a
+  # subgraph changed without a recompose). They share the answers so the two
+  # can't drift apart.
+  module Schemas
+    class << self
+      # Every named GraphQL::Schema in the process. An anonymous one is
+      # graphql-ruby building from SDL — the router's own view of the
+      # supergraph is one — and never an app's subgraph.
+      def loaded
+        descendants(GraphQL::Schema).select(&:name)
+      end
+
+      # Does this schema carry the coordinate — "Type", or "Type.field"?
+      def defines?(schema, coordinate)
+        type_name, field_name = coordinate.split(".", 2)
+        type = schema.get_type(type_name) or return false
+        return true unless field_name
+
+        return type.fields.key?(field_name) if type.respond_to?(:fields)
+        # an input object's members are arguments, not fields
+        return type.arguments.key?(field_name) if type.respond_to?(:arguments)
+
+        false
+      end
+
+      private
+
+      def descendants(klass)
+        klass.subclasses.flat_map { |subclass| [subclass] + descendants(subclass) }
+      end
+    end
+  end
+end

data/lib/graph_weaver/selection.rb

@@ -19,7 +19,19 @@ module GraphWeaver
         .grep(GraphQL::Language::Nodes::FragmentDefinition)
         .to_h { |fragment| [fragment.name, fragment] }
 
-      doc.definitions.grep(GraphQL::Language::Nodes::OperationDefinition).first
+      operations = doc.definitions.grep(GraphQL::Language::Nodes::OperationDefinition)
+      # One file, one operation. Requests do carry operationName now, so a
+      # second operation would run fine on the wire — what has no answer is
+      # naming: a module is named after its FILE (person.graphql =>
+      # PersonQuery), and one file can't name two. A convention, not a limit.
+      if operations.size > 1
+        names = operations.map { |op| op.name ? "'#{op.name}'" : "an anonymous operation" }
+        raise GraphWeaver::Error,
+          "document defines #{operations.size} operations (#{names.join(", ")}) — " \
+          "split them into one file each, since a module is named after its file"
+      end
+
+      operations.first
     end
 
     # The schema type an operation's selections start from.
@@ -32,26 +44,66 @@ module GraphWeaver
     end
 
     # Flatten a selection set as seen by `type`, yielding (result_key,
-    # field_node) per field: plain fields yield directly; inline fragments
-    # and named spreads recurse when their type condition applies.
-    def each_field(type, selections, &block)
+    # field_node, conditional) per field: plain fields yield directly; inline
+    # fragments and named spreads recurse when their type condition applies.
+    # `conditional` is true when any fragment on the way down carried
+    # @skip/@include — the whole block may be absent from the response, so
+    # everything under it is as optional as a directly-skipped field.
+    def each_field(type, selections, visiting = Set.new, conditional: false, &block)
       selections.each do |selection|
         case selection
         when GraphQL::Language::Nodes::Field
-          yield(selection.alias || selection.name, selection)
+          yield(selection.alias || selection.name, selection, conditional)
         when GraphQL::Language::Nodes::InlineFragment
-          each_field(type, selection.selections, &block) if applies?(selection.type&.name, type)
+          next unless applies?(selection.type&.name, type)
+
+          each_field(type, selection.selections, visiting,
+            conditional: conditional || conditional?(selection), &block)
         when GraphQL::Language::Nodes::FragmentSpread
           fragment = @fragments.fetch(selection.name) do
             raise ArgumentError, "unknown fragment: #{selection.name}"
           end
-          each_field(type, fragment.selections, &block) if applies?(fragment.type.name, type)
+          if visiting.include?(selection.name)
+            raise GraphWeaver::Error, "fragment cycle through #{selection.name}"
+          end
+
+          if applies?(fragment.type.name, type)
+            # the directive rides on the SPREAD, not the definition it names
+            each_field(type, fragment.selections, visiting | [selection.name],
+              conditional: conditional || conditional?(selection), &block)
+          end
         else
           raise GraphWeaver::Error, "unsupported selection: #{selection.class}"
         end
       end
     end
 
+    # each_field grouped by result key: repeated selections of one field
+    # (`a { x } a { y }`, or the same field reached through two fragments)
+    # collect together, so callers MERGE their sub-selections rather than
+    # last-writer-wins. Codegen relies on this; FakeClient/Anonymizer must too,
+    # or they'd fabricate/keep a shape the generated struct can't cast.
+    def gather(type, selections)
+      gather_conditional(type, selections).transform_values { |occurrences| occurrences.map(&:first) }
+    end
+
+    # gather, keeping each occurrence's [field_node, conditional] — the wire
+    # key is guaranteed only when SOME occurrence is unconditional.
+    def gather_conditional(type, selections)
+      out = {}
+      each_field(type, selections) { |key, node, conditional| (out[key] ||= []) << [node, conditional] }
+      out
+    end
+
+    # Directives that can drop a selection from the response whatever the
+    # schema says — the reason a conditional field's generated type is nilable.
+    CONDITIONAL_DIRECTIVES = %w[skip include].freeze
+
+    # Is this AST node (field, inline fragment, or spread) behind @skip/@include?
+    def conditional?(node)
+      node.directives.any? { |directive| CONDITIONAL_DIRECTIVES.include?(directive.name) }
+    end
+
     # A fragment's type condition applies when it names this type exactly,
     # or an interface/union this type belongs to (`... on Named { ... }`).
     def applies?(condition, type)

data/lib/graph_weaver/tasks.rb

@@ -5,60 +5,255 @@
 #
 #      require "graph_weaver/tasks"
 #
-# The tasks use the conventional paths (GraphWeaver.queries_path /
-# generated_path / schema_path — override in your Rakefile or an
+# The tasks use the conventional paths (GraphWeaver.queries_paths /
+# generated_paths / schema_path — override in your Rakefile or an
 # initializer). Register custom scalars before the tasks run — they're
 # baked into generated source.
 #
-#      rake graph_weaver:generate   # queries_path -> generated_path
-#      rake graph_weaver:verify     # fail if generated files are stale (CI)
+# Each task names its own subject — generated code, the schema dump, the
+# queries — so which question you're asking is the task name:
+#
+#      rake graph_weaver:generate        # queries_paths -> generated_paths.first
+#      rake graph_weaver:verify          # fail if generated files are stale (CI)
+#      rake graph_weaver:queries:check   # fail if a query no longer validates (CI)
+#      rake graph_weaver:schema:diff     # fail if the server has drifted from the dump
+#      rake graph_weaver:schema:refresh  # re-introspect and rewrite the dump
+#      rake graph_weaver:federation:diff       # fail if the supergraph wasn't recomposed
+#      rake graph_weaver:federation:coverage   # what the local test router can plan
+#      rake graph_weaver:federation:subgraphs  # which schema serves which subgraph
+#      rake graph_weaver:cassettes:check       # fail if a recording no longer casts
 require_relative "../graph_weaver"
 
-# in Rails, run app config first (initializers register scalars/enums/
-# helpers, and they're baked into generated source)
-GRAPH_WEAVER_DEPS = Rake::Task.task_defined?("environment") ? ["environment"] : []
-
 namespace :graph_weaver do
-  desc "Generate typed query modules (#{GraphWeaver.queries_path} -> #{GraphWeaver.generated_path})"
-  task generate: GRAPH_WEAVER_DEPS do
+  # In Rails, boot the app first — initializers register scalars/enums/
+  # helpers and they're baked into generated source. Rails defines
+  # :environment *after* every railtie's rake_tasks block (see
+  # Rails::Application#run_tasks_blocks), so whether it exists can only be
+  # asked when the task runs, not when this file loads.
+  task :environment do
+    # These tasks read queries, the schema and the registrations, not a
+    # generated module. Saying so lets the railtie skip loading them, so a
+    # stale generated file can't block the task that repairs it. It's reset
+    # below, so cassettes:check — which does read them — loads them itself.
+    GraphWeaver.skip_generated_load = true
+    Rake::Task["environment"].invoke if Rake::Task.task_defined?("environment")
+  ensure
+    # only meaningful while booting — leaving it set would silently disable
+    # loading for anything that boots later in the same process
+    GraphWeaver.skip_generated_load = false
+  end
+
+  desc "Generate typed query modules (#{GraphWeaver.queries_paths.first} -> #{GraphWeaver.generated_paths.first})"
+  task generate: :environment do
     # schema auto-located at GraphWeaver.schema_path, any supported extension
     GraphWeaver.generate!.each { |path| puts "wrote #{path}" }
+  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
+    abort e.message
   end
 
   desc "Verify generated query modules are up to date"
-  task verify: GRAPH_WEAVER_DEPS do
+  task verify: :environment do
     GraphWeaver.verify_generated!
     puts "generated queries up to date"
+  rescue GraphWeaver::Error => e
+    abort e.message
   end
 
   namespace :schema do
-    # both tasks re-introspect from the url recorded in the dump
+    # both re-introspect from the url recorded in the dump
     # (GRAPHWEAVER_AUTH supplies a token for private APIs)
 
     desc "Fail when the server's schema has drifted from the local dump"
-    task :verify do
+    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)"
       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
     end
 
-    desc "Re-introspect the recorded url and rewrite the local dump"
-    task :refresh do
-      path = GraphWeaver::SchemaLoader.locate_path or abort "no schema dump at #{GraphWeaver.schema_path}"
-      meta = GraphWeaver::SchemaLoader.provenance(path) or abort "#{path} records no source url"
+    desc "Re-introspect and rewrite the local dump (URL= to bootstrap the first one)"
+    task refresh: :environment do
+      path, url = GraphWeaver::SchemaLoader.refresh!(url: ENV["URL"])
+      puts "refreshed #{path} from #{url}"
+    rescue GraphWeaver::Error => e
+      abort e.message
+    end
+  end
+
+  namespace :queries do
+    desc "Report checked-in queries that no longer validate against the server's schema"
+    task check: :environment do
+      failures = GraphWeaver.check_queries
+      failures.each do |path, errors|
+        puts path
+        errors.each do |error|
+          position = [error["line"], error["column"]].compact.join(":")
+          puts "  #{position.empty? ? "" : "#{position}  "}#{error["message"]}"
+        end
+        puts
+      end
 
-      transport = GraphWeaver.new(meta["url"], auth: ENV["GRAPHWEAVER_AUTH"]).transport
-      GraphWeaver::SchemaLoader.introspect(transport, cache: path, ttl: 0)
-      puts "refreshed #{path} from #{meta["url"]}"
+      # abort writes to unbuffered stderr; the detail above went to
+      # block-buffered stdout, so a piped CI log shows the verdict first
+      $stdout.flush
+      abort "#{failures.size} invalid #{(failures.size == 1) ? "query" : "queries"}" if failures.any?
+      puts "every query validates against the schema"
+    end
+  end
+
+  namespace :federation do
+    # Every task here answers "which loaded schema serves which subgraph",
+    # and Rails leaves config.rake_eager_load false in every environment —
+    # so without this each of them reports on zero subgraphs, and :diff
+    # exits 0 having compared nothing. Asked when the task runs, not when
+    # this file loads: :environment doesn't exist yet at load time.
+    task loaded: :environment do
+      Rails.application.eager_load! if defined?(Rails) && Rails.respond_to?(:application) && Rails.application
+    end
+
+    # needs no network, so it gates a PR the way verify does
+    desc "Fail when a subgraph here changed and the supergraph wasn't recomposed (SUPERGRAPH=)"
+    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
+
+      drift = GraphWeaver::Federation::Drift.new(supergraph:)
+      puts drift.report
+
+      # A partly-local supergraph is a supported setup, so a subgraph this
+      # process doesn't serve isn't a failure — but comparing against NONE
+      # of them is: the gate passes whatever the subgraphs say, which is
+      # worse than failing.
+      $stdout.flush
+      abort "the supergraph is out of date — recompose it and commit the result" if drift.drift?
+      if drift.vacuous?
+        abort "this checked nothing, so it proved nothing. No schema in this process defines what " \
+          "the supergraph says any of its subgraphs resolves — load them (in Rails, that is " \
+          "config.eager_load / config.rake_eager_load), or, if they all run elsewhere, drop this " \
+          "task from CI: there is nothing here for it to gate."
+      end
+    rescue GraphWeaver::Error => e
+      abort e.message
+    end
+
+    desc "Show which loaded schema serves each subgraph, as a paste-ready map (SUPERGRAPH=)"
+    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
+
+      # 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)
+        [name, found, sought]
+      end
+      width = rows.map { |name, found, _| %("#{name}" => #{found.first&.name || "nil"},).length }.max
+
+      puts "subgraphs: {"
+      rows.each do |name, found, sought|
+        entry = %(  "#{name}" => #{found.one? ? found.first.name : "nil"},).ljust(width + 2)
+        # fields first: every schema has a Query, so only the fields say why
+        evidence = (sought.grep(/\./) | sought).first(3).join(", ")
+        note = if found.one?
+          "# matched: defines #{evidence}"
+        elsif found.any?
+          "# AMBIGUOUS: #{found.map(&:name).sort.join(", ")} all match — pick one"
+        else
+          "# no loaded schema defines #{evidence} — fill this in"
+        end
+        puts "#{entry}  #{note}"
+      end
+      puts "}"
+    rescue GraphWeaver::Error => e
+      abort e.message
+    end
+
+    desc "Report how many queries the local test router can plan (SUPERGRAPH=, QUERIES=)"
+    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:,
+        queries: ENV["QUERIES"] || GraphWeaver.queries_paths,
+      ).report
+    rescue GraphWeaver::Error => e
+      # a supergraph the routing table can't read fully is itself the answer:
+      # nothing is plannable, and the message says which construct
+      abort e.message
     end
   end
 
   namespace :cassettes do
+    # The drift the other checks structurally can't see. verify, queries:check
+    # and schema:diff all ask about the local side; a cassette is the one
+    # artifact recorded from someone else's server, and when that server's
+    # answers stop fitting the generated structs the failure surfaces mid-spec
+    # as a cast error naming a struct and a sorbet frame — nothing points at
+    # the stale file.
+    desc "Fail when a recorded response no longer casts into the generated structs"
+    task check: :environment do
+      require "graph_weaver/testing"
+
+      # 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))
+        Object.const_get(name) if Object.const_defined?(name)
+      end
+
+      dir = GraphWeaver::Testing.config.cassette_dir
+      checks = Dir[File.join(dir, "*.yml")].sort.map do |path|
+        GraphWeaver::Testing::Cassette.new(path).check(modules)
+      end
+      checks.each { |check| puts check.report }
+
+      stale = checks.sum { |check| check.stale.size }
+      $stdout.flush
+      if stale.positive?
+        abort "#{stale} stale #{(stale == 1) ? "recording" : "recordings"} — the recorded server's " \
+          "answers no longer fit the structs generated from your schema. Re-record " \
+          "(GRAPHWEAVER_RECORD=1, with a live client:), or regenerate if it was the schema dump " \
+          "that moved: rake graph_weaver:generate."
+      end
+      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 " \
+          "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."
+      end
+
+      puts "every recording still casts"
+    end
+
     desc "Anonymize every cassette in Testing.config.cassette_dir (PII-safe to commit)"
-    task :anonymize do
+    task anonymize: :environment do
       require "graph_weaver/testing"
 
       schema = GraphWeaver::SchemaLoader.load(GraphWeaver.schema_path)