graph_weaver 0.0.1 → 0.2.0

data/lib/graph_weaver/schema_loader.rb

@@ -1,20 +1,220 @@
 # typed: true
 # frozen_string_literal: true
 
+require "fileutils"
 require "graphql"
 require "json"
+require_relative "errors"
 
 # Load a schema for codegen from either format a remote service can hand
-# you: an introspection dump (.json) or SDL (.graphql/.gql).
+# you — introspection JSON or SDL, as a file path or the content itself —
+# or fetch one straight from a live endpoint via introspect.
 module GraphWeaver::SchemaLoader
-  def self.load(path)
-    case File.extname(path)
-    when ".json"
-      GraphQL::Schema.from_introspection(JSON.parse(File.read(path)))
-    when ".graphql", ".gql"
-      GraphQL::Schema.from_definition(File.read(path))
+  # Accepts, and detects:
+  #   - a Hash (a parsed introspection result)
+  #   - a file path — .json (introspection) or .graphql/.gql (SDL)
+  #   - raw content — introspection JSON (starts with "{") or SDL
+  # so a cache round-trip is symmetrical with introspect:
+  #      SchemaLoader.load(cached_json)  # from Rails.cache/redis/...
+  def self.load(source)
+    return GraphQL::Schema.from_introspection(source) if source.is_a?(Hash)
+
+    if source.lstrip.start_with?("{") # introspection JSON content
+      GraphQL::Schema.from_introspection(JSON.parse(source))
+    elsif source.include?("\n") # multi-line: SDL content
+      unless source.match?(/^\s*(schema|type|interface|union|enum|scalar|directive|input|")/)
+        raise ArgumentError, "unsupported schema content: #{source.lstrip[0, 80].inspect}"
+      end
+
+      GraphQL::Schema.from_definition(source)
+    else # a file path
+      case File.extname(source)
+      when ".json"
+        GraphQL::Schema.from_introspection(JSON.parse(File.read(source)))
+      when ".graphql", ".gql"
+        GraphQL::Schema.from_definition(File.read(source))
+      else
+        raise ArgumentError, "unsupported schema format: #{source}"
+      end
+    end
+  end
+
+  # Run the standard introspection query through a transport and build a
+  # schema from the result:
+  #
+  #      transport = GraphWeaver::Transport::HTTP.new(url, headers: { ... })
+  #      schema = GraphWeaver::SchemaLoader.introspect(transport)
+  #
+  # Introspecting a large API takes seconds, so cache: dumps the schema
+  # to a file and reuses it until ttl: seconds elapse (no ttl = until the
+  # file is deleted). cache: takes
+  #   - true — GraphWeaver.schema_path, the file the generation workflow
+  #     reads (its extension picks the format)
+  #   - a path — the extension picks the format: .json is the verbatim
+  #     introspection result, .graphql/.gql is SDL (human-readable,
+  #     PR-reviewable diffs); both load back identically
+  #   - :json / :graphql / :gql — GraphWeaver.schema_path's location, in
+  #     that format
+  # Reading is format-agnostic: any fresh sibling dump counts, whatever
+  # its format — an existing schema.graphql is reused rather than
+  # re-introspecting to write schema.json.
+  # GraphQL has no standard schema-version signal to invalidate on — a
+  # stale cache surfaces as server-side validation errors (see
+  # QueryError#schema_stale?), so pick a ttl that matches how fast the
+  # API moves, or delete the file.
+  #
+  # To cache anywhere else (Rails.cache, redis, ...), serialize the schema
+  # itself — schemas round-trip through their introspection JSON:
+  #
+  #      json = Rails.cache.fetch("gh_schema", expires_in: 12.hours) do
+  #        GraphWeaver::SchemaLoader.introspect(transport).to_json
+  #      end
+  #      schema = GraphWeaver::SchemaLoader.load(json)
+  def self.introspect(transport, cache: nil, ttl: nil)
+    cache = cache_path(cache)
+
+    if cache
+      # reuse whatever fresh dump is present, regardless of format —
+      # don't re-introspect to write schema.json when a usable
+      # 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}" }
+        return load(existing)
+      end
+
+      GraphWeaver.log(:info) { "schema cache miss: #{cache}" }
+    end
+
+    result = GraphWeaver.log_timed(:info, "introspected #{transport.respond_to?(:url) ? transport.url : transport.class}") do
+      transport.execute(GraphQL::Introspection.query, variables: {}).to_h
+    end
+    if (errors = result["errors"])
+      raise GraphWeaver::Error, "introspection failed: #{errors.inspect}"
+    end
+
+    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)
+      meta = stamp(transport)
+      content = if cache.end_with?(".json")
+        JSON.generate(meta ? result.merge("graph_weaver" => meta) : result)
+      else
+        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)" }
+    end
+
+    schema
+  end
+
+  # The conventional schema dump, whatever its format: schema_path or the
+  # first sibling extension that exists. nil when none is on disk.
+  def self.locate_path(path = GraphWeaver.schema_path)
+    cache_candidates(path).find { |candidate| File.exist?(candidate) }
+  end
+
+  # locate_path, loaded.
+  def self.locate(path = GraphWeaver.schema_path)
+    found = locate_path(path)
+    found && load(found)
+  end
+
+  # The provenance recorded in a dump ({"url" => ..., "introspected_at"
+  # => ...}), whichever format holds it; nil for local/unannotated dumps.
+  def self.provenance(path)
+    content = File.read(path)
+    if path.end_with?(".json")
+      JSON.parse(content)["graph_weaver"]
+    elsif (meta = content[/\A# graph_weaver: (\{.*\})$/, 1])
+      JSON.parse(meta)
+    end
+  end
+
+  # 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:verify` / `:refresh`.
+  def self.stale?(path, transport: nil)
+    transport ||= source_transport(path)
+    fresh = introspect(transport)
+
+    fresh.to_definition != load(path).to_definition
+  end
+
+  # a transport to the dump's recorded url (GRAPHWEAVER_AUTH supplies a
+  # token when set)
+  def self.source_transport(path)
+    meta = provenance(path)
+    unless meta&.key?("url")
+      raise GraphWeaver::Error, "#{path} records no source url — pass transport:"
+    end
+
+    GraphWeaver.new(meta["url"], auth: ENV["GRAPHWEAVER_AUTH"]).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
+  # "graph_weaver" sibling key in introspection JSON (from_introspection
+  # reads only "data"). nil when the transport has no url (schema
+  # classes, fakes).
+  def self.stamp(transport)
+    return unless transport.respond_to?(:url) && transport.url
+
+    require "time"
+    { "url" => transport.url, "introspected_at" => Time.now.utc.iso8601 }
+  end
+  private_class_method :stamp
+
+  CACHE_EXTENSIONS = %w[.json .graphql .gql].freeze
+
+  # 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
+    when nil, false
+      nil
+    when true
+      GraphWeaver.schema_path
+    when Symbol
+      unless CACHE_EXTENSIONS.include?(".#{cache}")
+        raise ArgumentError, "cache: format must be :json, :graphql, or :gql, got #{cache.inspect}"
+      end
+
+      "#{strip_extension(GraphWeaver.schema_path)}.#{cache}"
     else
-      raise ArgumentError, "unsupported schema format: #{path}"
+      unless cache.end_with?(*CACHE_EXTENSIONS)
+        raise ArgumentError, "cache: must be a .json or .graphql/.gql path, got #{cache}"
+      end
+
+      cache
     end
   end
+  private_class_method :cache_path
+
+  # the requested path first, then its siblings in the other formats
+  def self.cache_candidates(path)
+    base = strip_extension(path)
+    [path, *CACHE_EXTENSIONS.map { |ext| base + ext }].uniq
+  end
+  private_class_method :cache_candidates
+
+  def self.strip_extension(path)
+    path.delete_suffix(File.extname(path))
+  end
+  private_class_method :strip_extension
+
+  def self.fresh?(path, ttl)
+    File.exist?(path) && (ttl.nil? || Time.now - File.mtime(path) < ttl)
+  end
+  private_class_method :fresh?
 end

data/lib/graph_weaver/selection.rb

@@ -0,0 +1,68 @@
+# typed: true
+# frozen_string_literal: true
+
+require "graphql"
+
+module GraphWeaver
+  # Shared query-selection walking — the rules Codegen, FakeClient, and
+  # the cassette Anonymizer all follow, in one place so they can't drift:
+  # how fragments flatten into selections, and when a type condition
+  # applies. Hosts set @schema and call load_operation before walking.
+  module Selection
+    include Kernel # for sorbet: hosts are Objects
+
+    # Parse a query, stash its fragment definitions for the walk, and
+    # return the operation.
+    def load_operation(query)
+      doc = GraphQL.parse(query)
+      @fragments = doc.definitions
+        .grep(GraphQL::Language::Nodes::FragmentDefinition)
+        .to_h { |fragment| [fragment.name, fragment] }
+
+      doc.definitions.grep(GraphQL::Language::Nodes::OperationDefinition).first
+    end
+
+    # The schema type an operation's selections start from.
+    def operation_root_type(operation)
+      case operation&.operation_type
+      when "query", nil then @schema.query
+      when "mutation" then @schema.mutation
+      else raise GraphWeaver::Error, "unsupported operation: #{operation.operation_type}"
+      end
+    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)
+      selections.each do |selection|
+        case selection
+        when GraphQL::Language::Nodes::Field
+          yield(selection.alias || selection.name, selection)
+        when GraphQL::Language::Nodes::InlineFragment
+          each_field(type, selection.selections, &block) if applies?(selection.type&.name, type)
+        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)
+        else
+          raise GraphWeaver::Error, "unsupported selection: #{selection.class}"
+        end
+      end
+    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)
+      return true if condition.nil? || condition == type.graphql_name
+
+      condition_type = @schema.get_type(condition)
+      return false unless condition_type
+
+      kind = condition_type.kind.name
+      (kind == "INTERFACE" || kind == "UNION") &&
+        @schema.possible_types(condition_type).include?(type)
+    end
+  end
+end

data/lib/graph_weaver/tasks.rb

@@ -0,0 +1,71 @@
+# typed: ignore — Rake DSL at top level, loaded from Rakefiles
+# frozen_string_literal: true
+
+# Rake tasks — add to your Rakefile:
+#
+#      require "graph_weaver/tasks"
+#
+# The tasks use the conventional paths (GraphWeaver.queries_path /
+# generated_path / 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)
+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
+    # schema auto-located at GraphWeaver.schema_path, any supported extension
+    GraphWeaver.generate!.each { |path| puts "wrote #{path}" }
+  end
+
+  desc "Verify generated query modules are up to date"
+  task verify: GRAPH_WEAVER_DEPS do
+    GraphWeaver.verify_generated!
+    puts "generated queries up to date"
+  end
+
+  namespace :schema do
+    # both tasks 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
+      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"
+    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"
+
+      transport = GraphWeaver.new(meta["url"], auth: ENV["GRAPHWEAVER_AUTH"]).transport
+      GraphWeaver::SchemaLoader.introspect(transport, cache: path, ttl: 0)
+      puts "refreshed #{path} from #{meta["url"]}"
+    end
+  end
+
+  namespace :cassettes do
+    desc "Anonymize every cassette in Testing.config.cassette_dir (PII-safe to commit)"
+    task :anonymize 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|
+        GraphWeaver::Testing::Cassette.new(path).anonymize!(schema:)
+        puts "anonymized #{path}"
+      end
+    end
+  end
+end

data/lib/graph_weaver/testing/cassette.rb

@@ -0,0 +1,224 @@
+# typed: true
+# frozen_string_literal: true
+
+require "fileutils"
+require "graphql"
+require "yaml"
+
+module GraphWeaver
+  module Testing
+    # Raised by Replayer when a request has no recording.
+    class MissingRecording < GraphWeaver::Error
+      def initialize(path:, query:)
+        super(<<~MSG.strip)
+          no recording for this request in #{path} — re-record it
+          (Recorder / Cassette.use with a live client, or delete
+          the cassette to start over). Query:
+          #{query.strip[0, 200]}
+        MSG
+      end
+    end
+
+    # Capture/replay above the transport (no HTTP interception): a
+    # cassette is a YAML file of {query, variables, response} entries,
+    # keyed on the normalized query + variables.
+    #
+    #      # record against a real client, replay when the file exists:
+    #      client = GraphWeaver::Testing::Cassette.use("github", client: real)
+    #
+    # Cassettes hold real responses — anonymize before committing:
+    #
+    #      Cassette.new("spec/cassettes/github.yml").anonymize!(schema:)
+    #
+    # keeps every shape (list lengths, null positions, enums, __typename,
+    # id relationships via a consistent mapping) while replacing values
+    # with fakes, semantically matched where field names allow.
+    class Cassette
+      attr_reader :path
+
+      def initialize(path)
+        @path = Testing.cassette_path(path)
+        @entries = File.exist?(@path) ? YAML.safe_load_file(@path, aliases: true) : []
+      end
+
+      def exist? = File.exist?(@path)
+      def size = @entries.size
+
+      # Replay when recorded, record when not (VCR's once mode).
+      # client: is required to record; omit it to replay-or-raise.
+      # With Testing.config.record on (or GRAPHWEAVER_RECORD=1), always
+      # records — the "just re-record everything" switch.
+      def self.use(path, client: nil)
+        cassette = new(path)
+        if Testing.config.record && client
+          Recorder.new(client, cassette)
+        elsif cassette.exist?
+          Replayer.new(cassette)
+        elsif client
+          Recorder.new(client, cassette)
+        else
+          raise MissingRecording.new(path: cassette.path, query: "(no client to record with)")
+        end
+      end
+
+      def lookup(query, variables)
+        wanted = self.class.key(query, variables)
+      @entries.find { |entry| entry["key"] == wanted }
+      end
+
+      def record(query, variables, response)
+        entry = {
+          "key" => self.class.key(query, variables),
+          "query" => query,
+          "variables" => variables,
+          "response" => response,
+        }
+        @entries.reject! { |existing| existing["key"] == entry["key"] }
+        @entries << entry
+        save
+      end
+
+      # Replace recorded response values with fakes, preserving structure.
+      # Walks each entry's query against the schema (like FakeClient,
+      # but transforming what's there instead of generating from scratch).
+      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
+        end
+        save
+        self
+      end
+
+      def self.key(query, variables)
+        { "query" => query.gsub(/\s+/, " ").strip, "variables" => variables || {} }
+      end
+
+      private
+
+      def save
+        FileUtils.mkdir_p(File.dirname(@path))
+        File.write(@path, YAML.dump(@entries))
+      end
+    end
+
+    # Tees requests through a live client and records every response.
+    # With Testing.config.anonymize (or anonymize: true), responses are
+    # anonymized as they're recorded — and the anonymized version is what
+    # the caller sees too, so assertions written now hold on replay.
+    class Recorder
+      def initialize(client, cassette, anonymize: nil)
+        @client = client
+        @cassette = cassette.is_a?(Cassette) ? cassette : Cassette.new(cassette)
+
+        config = Testing.config
+        if anonymize.nil? ? config.anonymize : anonymize
+          unless config.schema
+            raise ArgumentError, "anonymizing recordings needs GraphWeaver::Testing.config.schema"
+          end
+
+          @anonymizer = Anonymizer.new(schema: config.schema, seed: config.seed)
+        end
+      end
+
+      def execute(query, variables: {})
+        response = @client.execute(query, variables:).to_h
+        if @anonymizer && (data = response["data"])
+          response = response.merge("data" => @anonymizer.anonymize(query, data))
+        end
+
+        @cassette.record(query, variables, response)
+        response
+      end
+    end
+
+    # Serves recorded responses; raises MissingRecording on unknown
+    # requests rather than silently faking.
+    class Replayer
+      def initialize(cassette)
+        @cassette = cassette.is_a?(Cassette) ? cassette : Cassette.new(cassette)
+      end
+
+      def execute(query, variables: {})
+        entry = @cassette.lookup(query, variables)
+        raise MissingRecording.new(path: @cassette.path, query:) unless entry
+
+        entry["response"]
+      end
+    end
+
+    # Rewrites a recorded response through the Values engine: same shape,
+    # fake values. Enums, booleans, __typename, and null positions are
+    # preserved; ids map consistently so relationships survive.
+    class Anonymizer
+      include GraphWeaver::Selection
+
+      def initialize(schema:, seed: nil, mode: nil)
+        @schema = schema
+        @values = Values.new(seed:, mode:)
+      end
+
+      def anonymize(query, data)
+        operation = load_operation(query)
+
+        object_value(operation_root_type(operation), operation.selections, data)
+      end
+
+      private
+
+      def object_value(type, selections, data)
+        return data if data.nil?
+
+        # abstract types anonymize as the member the response says it was
+        if (typename = data["__typename"]) && type.graphql_name != typename
+          type = @schema.get_type(typename) || type
+        end
+
+        result = {}
+        each_field(type, selections) do |key, node|
+          next unless data.key?(key)
+
+          result[key] = if node.name == "__typename"
+            data[key]
+          else
+            field_value(type, node, data[key])
+          end
+        end
+
+        result
+      end
+
+      def field_value(parent_type, node, value)
+        type_value(@schema.get_field(parent_type.graphql_name, node.name).type, node, value)
+      end
+
+      def type_value(type, node, value)
+        return if value.nil? # preserve null positions
+
+        case type.kind.name
+        when "NON_NULL"
+          type_value(type.of_type, node, value)
+        when "LIST"
+          value.map { |element| type_value(type.of_type, node, element) }
+        when "SCALAR"
+          scalar_value(type.graphql_name, node.name, value)
+        when "ENUM"
+          value # enums aren't PII; preserving them keeps semantics
+        when "OBJECT", "UNION", "INTERFACE"
+          object_value(type, node.selections, value)
+        else
+          value
+        end
+      end
+
+      def scalar_value(type_name, field_name, value)
+        case type_name
+        when "ID" then @values.mapped_id(value)
+        when "Boolean" then value # not PII; preserves branching behavior
+        else @values.scalar(type_name, field_name)
+        end
+      end
+    end
+  end
+end