graph_weaver 0.0.1 → 0.1.0

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, FakeExecutor, 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 NotImplementedError, "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 NotImplementedError, "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/testing/cassette.rb

@@ -0,0 +1,203 @@
+# typed: true
+# frozen_string_literal: true
+
+require "fileutils"
+require "graphql"
+require "yaml"
+
+module GraphWeaver
+  module Testing
+    # Raised by ReplayExecutor 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
+          (RecordingExecutor / Cassette.use with a live executor, 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 executor, replay when the file exists:
+    #   executor = GraphWeaver::Testing::Cassette.use("github", executor: 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).
+      # executor: is required to record; omit it to replay-or-raise.
+      def self.use(path, executor: nil)
+        cassette = new(path)
+        if cassette.exist?
+          ReplayExecutor.new(cassette)
+        elsif executor
+          RecordingExecutor.new(executor, cassette)
+        else
+          raise MissingRecording.new(path: cassette.path, query: "(no executor to record with)")
+        end
+      end
+
+      def lookup(query, variables)
+        @entries.find { |entry| entry["key"] == self.class.key(query, variables) }
+      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 FakeExecutor,
+      # 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 executor and records every response.
+    class RecordingExecutor
+      def initialize(executor, cassette)
+        @executor = executor
+        @cassette = cassette.is_a?(Cassette) ? cassette : Cassette.new(cassette)
+      end
+
+      def execute(query, variables: {})
+        response = @executor.execute(query, variables:).to_h
+        @cassette.record(query, variables, response)
+        response
+      end
+    end
+
+    # Serves recorded responses; raises MissingRecording on unknown
+    # requests rather than silently faking.
+    class ReplayExecutor
+      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

data/lib/graph_weaver/testing/failure.rb

@@ -0,0 +1,109 @@
+# typed: true
+# frozen_string_literal: true
+
+require "json"
+
+module GraphWeaver
+  module Testing
+    # Canned failure executors — each produces exactly what the real
+    # transports produce, so error-handling paths are testable without a
+    # server that misbehaves on cue:
+    #
+    #   PersonQuery.execute(id: "1", executor: Failure.transport)   # TransportError
+    #   PersonQuery.execute(id: "1", executor: Failure.server(status: 502))
+    #   PersonQuery.execute(id: "1", executor: Failure.throttled)   # QueryError, code THROTTLED
+    #   PersonQuery.execute(id: "1", executor: Failure.stale_schema) # schema_stale? => true
+    #
+    # For type mismatches, corrupt the wire with a FakeExecutor override:
+    #   FakeExecutor.new(schema:, overrides: { "Person.birthday" => 123 })
+    # casting then raises GraphWeaver::TypeError, exactly as a bad server
+    # payload would. For partial failures, see FakeExecutor's fail_at:.
+    module Failure
+      include Kernel # for sorbet
+      module_function
+
+      # the request never reaches the server — cause preserved, like the
+      # bundled transports do
+      def transport(message = "simulated network failure", cause: SocketError)
+        FailureExecutor.new do
+          raise cause, message
+        rescue cause => e
+          raise GraphWeaver::TransportError, e.message
+        end
+      end
+
+      # the server answered non-2xx
+      def server(status: 500, body: "simulated server error")
+        FailureExecutor.new { raise GraphWeaver::ServerError.new(status:, body:) }
+      end
+
+      # top-level GraphQL errors: strings, or hashes with message/path/
+      # extensions; data: rides along for partial-failure envelopes
+      def graphql(*errors, data: nil, extensions: {})
+        normalized = errors.flatten.map do |error|
+          error.is_a?(String) ? { "message" => error } : JSON.parse(JSON.generate(error))
+        end
+
+        response = { "errors" => normalized }
+        response["data"] = data if data
+        response["extensions"] = JSON.parse(JSON.generate(extensions)) unless extensions.empty?
+        FailureExecutor.new { response }
+      end
+
+      def throttled
+        # array-wrapped so the hash can't parse as kwargs
+        graphql([{ message: "rate limited", extensions: { code: "THROTTLED" } }])
+      end
+
+      # A validation-shaped rejection — trips schema_stale? and its
+      # regenerate hint, as if the schema changed under the module. Name
+      # the casualty explicitly, or pass schema: to sample a real
+      # type/field (as if the server just dropped it):
+      #
+      #   Failure.stale_schema(type: "Person", field: "name")
+      #   Failure.stale_schema(schema: MySchema)             # random real field
+      #   Failure.stale_schema(schema: MySchema, seed: 42)   # reproducibly random
+      def stale_schema(field: nil, type: nil, schema: nil, seed: nil)
+        if schema && (field.nil? || type.nil?)
+          rng = Random.new(seed || GraphWeaver::Testing.config.seed || Random.new_seed)
+          candidates = schema.types.values.select do |candidate|
+            candidate.kind.name == "OBJECT" && !candidate.graphql_name.start_with?("__")
+          end
+          chosen = candidates.sort_by(&:graphql_name).sample(random: rng)
+          type ||= chosen.graphql_name
+          field ||= chosen.fields.keys.sort.sample(random: rng)
+        end
+
+        graphql("Field '#{field || "someField"}' doesn't exist on type '#{type || "SomeType"}'")
+      end
+    end
+
+    # runs the block per request — raise or return an envelope
+    class FailureExecutor
+      def initialize(&response)
+        @response = response
+      end
+
+      def execute(_query, variables: {})
+        @response.call
+      end
+    end
+
+    # Delegates each call to the next executor in line (the last one
+    # repeats) — fail N times, then succeed, for retry/backoff testing:
+    #
+    #   SequenceExecutor.new(Failure.transport, Failure.transport, fake)
+    class SequenceExecutor
+      def initialize(*executors)
+        @executors = executors.flatten
+        @calls = 0
+      end
+
+      def execute(query, variables: {})
+        executor = @executors[[@calls, @executors.size - 1].min]
+        @calls += 1
+        executor.execute(query, variables:)
+      end
+    end
+  end
+end

data/lib/graph_weaver/testing/fake_executor.rb

@@ -0,0 +1,228 @@
+# typed: true
+# frozen_string_literal: true
+
+require "graphql"
+require "json"
+
+# An executor that fabricates schema-correct responses for whatever query
+# arrives — the zero-setup way to test code built on generated modules:
+#
+#   fake = GraphWeaver::Testing::FakeExecutor.new(schema:)
+#   result = PersonQuery.execute!(id: "1", executor: fake)
+#   result.person.name  # => a plausible String, typed and castable
+#
+# Values are type-correct by construction (real enum values, valid
+# __typename members for unions/interfaces, iso8601 for date scalars), so
+# every fake response casts cleanly through the generated structs. See
+# Values for value fabrication (mode: :faker / :literal).
+#
+# overrides: pin fields by GraphQL name — schema vocabulary, so keys
+# survive query refactors. "Type.field" beats "field"; values are
+# literals or zero-arg procs. (An override with a wrong-typed value is
+# also the way to simulate a corrupt payload — casting raises
+# GraphWeaver::TypeError.)
+#
+#   FakeExecutor.new(schema:, overrides: {
+#     "Person.name" => "Daniel",
+#     "email" => -> { "test@example.com" },
+#   })
+#
+# Partial failures: fail_at simulates a field-level error with
+# spec-correct null propagation — the field's error lands in the errors
+# array (with its concrete path), the field becomes null, and nulls
+# bubble past non-null positions to the nearest nullable ancestor, just
+# like a real server:
+#
+#   FakeExecutor.new(schema:, fail_at: "person.pets.name")
+#   FakeExecutor.new(schema:, fail_at: { path: "person.email", message: "hidden", code: "PRIVATE" })
+#
+# errors: appends verbatim top-level errors alongside the fake data.
+#
+# Type mismatches: corrupt: names fields ("Type.field") that should
+# arrive wire-corrupted — a wrong-typed value derived from the schema,
+# so casting raises GraphWeaver::TypeError. One spec checks the failure
+# path; every other spec gets working data:
+#
+#   FakeExecutor.new(schema:, corrupt: "Person.birthday")
+#
+# seed: makes a run reproducible (also seeds faker). Per-executor options
+# fall back to GraphWeaver::Testing.config.
+class GraphWeaver::Testing::FakeExecutor
+  include GraphWeaver::Selection
+
+  # sentinel: a simulated failure bubbling up to the nearest nullable spot
+  NULL_BUBBLE = Object.new.freeze
+
+  def initialize(schema:, overrides: {}, seed: nil, mode: nil, list_size: nil, null_chance: nil,
+    errors: nil, fail_at: nil, corrupt: nil)
+    config = GraphWeaver::Testing.config
+    @schema = schema
+    @overrides = config.overrides.merge(overrides)
+    @values = GraphWeaver::Testing::Values.new(seed:, mode:)
+    @list_size = list_size || config.list_size
+    @null_chance = null_chance || config.null_chance
+    # NOT Array(): it would explode a bare Hash into key/value pairs
+    @extra_errors = wrap(errors).map { |error| normalize_error(error) }
+    @fail_at = wrap(fail_at).map { |spec| normalize_fail_spec(spec) }
+    @corrupt = wrap(corrupt)
+  end
+
+  def execute(query, variables: {})
+    operation = load_operation(query)
+    root_type = operation_root_type(operation)
+
+    @path = []
+    @failures = []
+    data = object_value(root_type, operation.selections)
+    data = nil if data.equal?(NULL_BUBBLE) # total propagation, like a real server
+
+    response = { "data" => data }
+    errors = @failures + @extra_errors
+    response["errors"] = errors unless errors.empty?
+    response
+  end
+
+  private
+
+  def rng = @values.rng
+
+  def wrap(value)
+    case value
+    when nil then []
+    when Array then value
+    else [value]
+    end
+  end
+
+  def normalize_error(error)
+    error.is_a?(String) ? { "message" => error } : JSON.parse(JSON.generate(error))
+  end
+
+  def normalize_fail_spec(spec)
+    spec.is_a?(String) ? { "path" => spec } : JSON.parse(JSON.generate(spec))
+  end
+
+  def object_value(type, selections)
+    result = {}
+    each_field(type, selections) do |key, node|
+      @path.push(key)
+      value = node.name == "__typename" ? type.graphql_name : field_value(type, node)
+      @path.pop
+
+      if value.equal?(NULL_BUBBLE)
+        # bubble past non-null fields to the nearest nullable ancestor
+        return NULL_BUBBLE if non_null_field?(type, node)
+
+        value = nil
+      end
+      result[key] = value
+    end
+
+    result
+  end
+
+  def non_null_field?(type, node)
+    return false if node.name == "__typename"
+
+    @schema.get_field(type.graphql_name, node.name).type.kind.name == "NON_NULL"
+  end
+
+  def field_value(parent_type, node)
+    if (spec = matching_failure)
+      @failures << {
+        "message" => spec["message"] || "simulated failure",
+        "path" => @path.dup,
+      }.merge(spec["code"] ? { "extensions" => { "code" => spec["code"] } } : {})
+      spec["triggered"] = true
+
+      return NULL_BUBBLE
+    end
+
+    override = @overrides.fetch("#{parent_type.graphql_name}.#{node.name}") do
+      @overrides[node.name]
+    end
+    return override.is_a?(Proc) ? override.call : override unless override.nil?
+
+    field_type = @schema.get_field(parent_type.graphql_name, node.name).type
+    if @corrupt.include?("#{parent_type.graphql_name}.#{node.name}")
+      return corrupt_value(field_type)
+    end
+
+    type_value(field_type, node)
+  end
+
+  # a value casting can't accept, derived from the field's own type — and
+  # wrapped per list layer so the corruption lands on the element cast
+  def corrupt_value(type)
+    case type.kind.name
+    when "NON_NULL" then corrupt_value(type.of_type)
+    when "LIST" then [corrupt_value(type.of_type)]
+    when "SCALAR"
+      case type.graphql_name
+      when "Int", "Float" then "not-a-number"
+      when "Boolean" then "not-a-boolean"
+      else 123 # breaks String/ID props and every string-wire custom scalar
+      end
+    when "ENUM" then "__NOT_A_REAL_VALUE__"
+    else [] # objects/unions: an Array fails Hash-shaped casting loudly
+    end
+  end
+
+  # first untriggered fail_at spec whose field chain (indices stripped)
+  # matches where we are
+  def matching_failure
+    chain = @path.reject { |segment| segment.is_a?(Integer) }.join(".")
+    @fail_at.find { |spec| !spec["triggered"] && spec["path"] == chain }
+  end
+
+  # honor pagination-ish arg semantics: first/last/limit with a literal
+  # int caps the fabricated list length
+  def list_length(node)
+    argument = node.arguments.find { |arg| %w[first last limit].include?(arg.name) }
+    return argument.value if argument && argument.value.is_a?(Integer)
+
+    rng.rand(@list_size)
+  end
+
+  def type_value(type, node, non_null: false)
+    case type.kind.name
+    when "NON_NULL"
+      type_value(type.of_type, node, non_null: true)
+    when "LIST"
+      elements = Array.new(list_length(node)) do |index|
+        @path.push(index)
+        element = type_value(type.of_type, node)
+        @path.pop
+        element
+      end
+
+      if elements.any? { |element| element.equal?(NULL_BUBBLE) }
+        # non-null elements bubble the whole list; nullable ones go nil
+        return NULL_BUBBLE if type.of_type.kind.name == "NON_NULL"
+
+        elements.map! { |element| element.equal?(NULL_BUBBLE) ? nil : element }
+      end
+      elements
+    else
+      return if !non_null && rng.rand < @null_chance
+
+      core_value(type, node)
+    end
+  end
+
+  def core_value(type, node)
+    case type.kind.name
+    when "SCALAR"
+      @values.scalar(type.graphql_name, node.name)
+    when "ENUM"
+      type.values.keys.sort.sample(random: rng)
+    when "OBJECT"
+      object_value(type, node.selections)
+    when "UNION", "INTERFACE"
+      member = @schema.possible_types(type).sort_by(&:graphql_name).sample(random: rng)
+      object_value(member, node.selections)
+    else
+      raise NotImplementedError, "cannot fake kind: #{type.kind.name}"
+    end
+  end
+end

data/lib/graph_weaver/testing/rspec.rb

@@ -0,0 +1,5 @@
+# typed: true
+# frozen_string_literal: true
+
+# moved — the canonical entry point is:
+require_relative "../rspec"