graph_weaver 0.1.0 → 0.2.1

data/lib/graph_weaver/schema_loader.rb

@@ -15,7 +15,7 @@ module GraphWeaver::SchemaLoader
   #   - 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/...
+  #      SchemaLoader.load(cached_json)  # from Rails.cache/redis/...
   def self.load(source)
     return GraphQL::Schema.from_introspection(source) if source.is_a?(Hash)
 
@@ -39,43 +39,179 @@ module GraphWeaver::SchemaLoader
     end
   end
 
-  # Run the standard introspection query through an executor and build a
+  # Run the standard introspection query through a transport and build a
   # schema from the result:
   #
-  #   executor = GraphWeaver::HttpExecutor.new(url, headers: { ... })
-  #   schema = GraphWeaver::SchemaLoader.introspect(executor)
+  #      transport = GraphWeaver::Transport::HTTP.new(url, headers: { ... })
+  #      schema = GraphWeaver::SchemaLoader.introspect(transport)
   #
-  # Introspecting a large API takes seconds, so cache: (a file path)
-  # stores the raw introspection JSON and reuses it until ttl: seconds
-  # elapse (no ttl = until the file is deleted). 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.
+  # 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(executor).to_json
-  #   end
-  #   schema = GraphWeaver::SchemaLoader.load(json)
-  def self.introspect(executor, cache: nil, ttl: nil)
-    if cache && fresh?(cache, ttl)
-      return GraphQL::Schema.from_introspection(JSON.parse(File.read(cache)))
+  #      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 = executor.execute(GraphQL::Introspection.query, variables: {}).to_h
+    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))
-      File.write(cache, JSON.generate(result))
+      # 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
 
-    GraphQL::Schema.from_introspection(result)
+    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
+      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)

data/lib/graph_weaver/selection.rb

@@ -4,7 +4,7 @@
 require "graphql"
 
 module GraphWeaver
-  # Shared query-selection walking — the rules Codegen, FakeExecutor, and
+  # 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.
@@ -27,7 +27,7 @@ module GraphWeaver
       case operation&.operation_type
       when "query", nil then @schema.query
       when "mutation" then @schema.mutation
-      else raise NotImplementedError, "unsupported operation: #{operation.operation_type}"
+      else raise GraphWeaver::Error, "unsupported operation: #{operation.operation_type}"
       end
     end
 
@@ -47,7 +47,7 @@ module GraphWeaver
           end
           each_field(type, fragment.selections, &block) if applies?(fragment.type.name, type)
         else
-          raise NotImplementedError, "unsupported selection: #{selection.class}"
+          raise GraphWeaver::Error, "unsupported selection: #{selection.class}"
         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

@@ -7,12 +7,12 @@ require "yaml"
 
 module GraphWeaver
   module Testing
-    # Raised by ReplayExecutor when a request has no recording.
+    # 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
-          (RecordingExecutor / Cassette.use with a live executor, or delete
+          (Recorder / Cassette.use with a live client, or delete
           the cassette to start over). Query:
           #{query.strip[0, 200]}
         MSG
@@ -23,12 +23,12 @@ module GraphWeaver
     # 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)
+    #      # 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:)
+    #      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
@@ -44,21 +44,26 @@ module GraphWeaver
       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)
+      # 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 cassette.exist?
-          ReplayExecutor.new(cassette)
-        elsif executor
-          RecordingExecutor.new(executor, cassette)
+        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 executor to record with)")
+          raise MissingRecording.new(path: cassette.path, query: "(no client to record with)")
         end
       end
 
       def lookup(query, variables)
-        @entries.find { |entry| entry["key"] == self.class.key(query, variables) }
+        wanted = self.class.key(query, variables)
+      @entries.find { |entry| entry["key"] == wanted }
       end
 
       def record(query, variables, response)
@@ -74,7 +79,7 @@ module GraphWeaver
       end
 
       # Replace recorded response values with fakes, preserving structure.
-      # Walks each entry's query against the schema (like FakeExecutor,
+      # 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:)
@@ -98,15 +103,31 @@ module GraphWeaver
       end
     end
 
-    # Tees requests through a live executor and records every response.
-    class RecordingExecutor
-      def initialize(executor, cassette)
-        @executor = executor
+    # 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 = @executor.execute(query, variables:).to_h
+        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
@@ -114,7 +135,7 @@ module GraphWeaver
 
     # Serves recorded responses; raises MissingRecording on unknown
     # requests rather than silently faking.
-    class ReplayExecutor
+    class Replayer
       def initialize(cassette)
         @cassette = cassette.is_a?(Cassette) ? cassette : Cassette.new(cassette)
       end

data/lib/graph_weaver/testing/failure.rb

@@ -5,19 +5,19 @@ require "json"
 
 module GraphWeaver
   module Testing
-    # Canned failure executors — each produces exactly what the real
+    # Canned failure clients — 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
+    #      PersonQuery.execute(id: "1", Failure.transport)   # TransportError
+    #      PersonQuery.execute(id: "1", Failure.server(status: 502))
+    #      PersonQuery.execute(id: "1", Failure.throttled)   # QueryError, code THROTTLED
+    #      PersonQuery.execute(id: "1", Failure.stale_schema) # schema_stale? => true
     #
-    # For type mismatches, corrupt the wire with a FakeExecutor override:
-    #   FakeExecutor.new(schema:, overrides: { "Person.birthday" => 123 })
+    # For type mismatches, corrupt the wire with a FakeClient override:
+    #      FakeClient.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:.
+    # payload would. For partial failures, see FakeClient's fail_at:.
     module Failure
       include Kernel # for sorbet
       module_function
@@ -25,7 +25,7 @@ module GraphWeaver
       # the request never reaches the server — cause preserved, like the
       # bundled transports do
       def transport(message = "simulated network failure", cause: SocketError)
-        FailureExecutor.new do
+        FailureClient.new do
           raise cause, message
         rescue cause => e
           raise GraphWeaver::TransportError, e.message
@@ -34,7 +34,7 @@ module GraphWeaver
 
       # the server answered non-2xx
       def server(status: 500, body: "simulated server error")
-        FailureExecutor.new { raise GraphWeaver::ServerError.new(status:, body:) }
+        FailureClient.new { raise GraphWeaver::ServerError.new(status:, body:) }
       end
 
       # top-level GraphQL errors: strings, or hashes with message/path/
@@ -47,7 +47,7 @@ module GraphWeaver
         response = { "errors" => normalized }
         response["data"] = data if data
         response["extensions"] = JSON.parse(JSON.generate(extensions)) unless extensions.empty?
-        FailureExecutor.new { response }
+        FailureClient.new { response }
       end
 
       def throttled
@@ -60,9 +60,9 @@ module GraphWeaver
       # 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
+      #      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)
@@ -79,7 +79,7 @@ module GraphWeaver
     end
 
     # runs the block per request — raise or return an envelope
-    class FailureExecutor
+    class FailureClient
       def initialize(&response)
         @response = response
       end
@@ -89,20 +89,20 @@ module GraphWeaver
       end
     end
 
-    # Delegates each call to the next executor in line (the last one
+    # Delegates each call to the next client 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
+    #      Sequence.new(Failure.transport, Failure.transport, fake)
+    class Sequence
+      def initialize(*clients)
+        @clients = clients.flatten
         @calls = 0
       end
 
       def execute(query, variables: {})
-        executor = @executors[[@calls, @executors.size - 1].min]
+        client = @clients[[@calls, @clients.size - 1].min]
         @calls += 1
-        executor.execute(query, variables:)
+        client.execute(query, variables:)
       end
     end
   end

data/lib/graph_weaver/testing/{fake_executor.rb → fake_client.rb}

@@ -4,12 +4,12 @@
 require "graphql"
 require "json"
 
-# An executor that fabricates schema-correct responses for whatever query
+# A fake client 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
+#      fake = GraphWeaver::Testing::FakeClient.new(schema:)
+#      result = PersonQuery.execute!(id: "1", fake — positionally)
+#      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
@@ -22,10 +22,10 @@ require "json"
 # also the way to simulate a corrupt payload — casting raises
 # GraphWeaver::TypeError.)
 #
-#   FakeExecutor.new(schema:, overrides: {
-#     "Person.name" => "Daniel",
-#     "email" => -> { "test@example.com" },
-#   })
+#      FakeClient.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
@@ -33,8 +33,8 @@ require "json"
 # 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" })
+#      FakeClient.new(schema:, fail_at: "person.pets.name")
+#      FakeClient.new(schema:, fail_at: { path: "person.email", message: "hidden", code: "PRIVATE" })
 #
 # errors: appends verbatim top-level errors alongside the fake data.
 #
@@ -43,11 +43,11 @@ require "json"
 # so casting raises GraphWeaver::TypeError. One spec checks the failure
 # path; every other spec gets working data:
 #
-#   FakeExecutor.new(schema:, corrupt: "Person.birthday")
+#      FakeClient.new(schema:, corrupt: "Person.birthday")
 #
-# seed: makes a run reproducible (also seeds faker). Per-executor options
+# seed: makes a run reproducible (also seeds faker). Per-instance options
 # fall back to GraphWeaver::Testing.config.
-class GraphWeaver::Testing::FakeExecutor
+class GraphWeaver::Testing::FakeClient
   include GraphWeaver::Selection
 
   # sentinel: a simulated failure bubbling up to the nearest nullable spot

data/lib/graph_weaver/testing/values.rb

@@ -3,7 +3,7 @@
 
 require "date"
 
-# The value engine behind FakeExecutor and Cassette#anonymize!: seeded,
+# The value engine behind FakeClient and Cassette#anonymize!: seeded,
 # type-correct scalar generation with optional faker-backed semantics
 # matched on field names — strings (name/email/url/...) and numbers
 # (age/price/count/latitude/...) alike. Keeps a consistent id mapping so
@@ -47,7 +47,7 @@ class GraphWeaver::Testing::Values
 
     if @mode == :faker
       # rebind per call: several Values instances may interleave (e.g. two
-      # seeded executors), and faker's rng is global
+      # seeded fakes), and faker's rng is global
       ::Faker::Config.random = @rng
       case type_name
       when "String"