graph_weaver 0.0.1 → 0.1.0

data/lib/graph_weaver/testing/values.rb

@@ -0,0 +1,98 @@
+# typed: true
+# frozen_string_literal: true
+
+require "date"
+
+# The value engine behind FakeExecutor 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
+# the same original id always anonymizes to the same fake id.
+class GraphWeaver::Testing::Values
+  include GraphWeaver::Inflect
+
+  STRING_SEMANTICS = {
+    /email/ => -> { ::Faker::Internet.email },
+    /(^|_)first_name$/ => -> { ::Faker::Name.first_name },
+    /(^|_)last_name$/ => -> { ::Faker::Name.last_name },
+    /(^|_)(full_)?name$/ => -> { ::Faker::Name.name },
+    /(^|_)(url|website|link)$/ => -> { ::Faker::Internet.url },
+    /phone/ => -> { ::Faker::PhoneNumber.phone_number },
+    /(^|_)address$/ => -> { ::Faker::Address.full_address },
+    /(^|_)(city)$/ => -> { ::Faker::Address.city },
+    /(^|_)(title|description)$/ => -> { ::Faker::Lorem.sentence(word_count: 3) },
+  }.freeze
+
+  NUMBER_SEMANTICS = {
+    /(^|_)age$/ => ->(rng) { rng.rand(1..99) },
+    /(^|_)(price|amount|cost|total)(_cents)?$/ => ->(rng) { (rng.rand(1.0..10_000.0) * 100).round / 100.0 },
+    /(^|_)(count|quantity|size)$/ => ->(rng) { rng.rand(0..100) },
+    /latitude/ => ->(rng) { rng.rand(-90.0..90.0).round(6) },
+    /longitude/ => ->(rng) { rng.rand(-180.0..180.0).round(6) },
+    /(^|_)year$/ => ->(rng) { rng.rand(1970..2030) },
+  }.freeze
+
+  attr_reader :rng
+
+  def initialize(seed: nil, mode: nil)
+    config = GraphWeaver::Testing.config
+    @rng = Random.new(seed || config.seed || Random.new_seed)
+    @mode = resolve_mode(mode || config.mode)
+    @sequence = 0
+    @id_map = {}
+  end
+
+  def scalar(type_name, field_name)
+    prop = underscore(field_name)
+
+    if @mode == :faker
+      # rebind per call: several Values instances may interleave (e.g. two
+      # seeded executors), and faker's rng is global
+      ::Faker::Config.random = @rng
+      case type_name
+      when "String"
+        STRING_SEMANTICS.each { |pattern, faker| return faker.call if pattern.match?(prop) }
+      when "Int", "Float"
+        NUMBER_SEMANTICS.each do |pattern, gen|
+          next unless pattern.match?(prop)
+
+          value = gen.call(@rng)
+          return type_name == "Int" ? value.to_i : value.to_f
+        end
+      end
+    end
+
+    case type_name
+    when "ID" then (@sequence += 1).to_s
+    when "String" then "#{field_name}-#{@sequence += 1}"
+    when "Int" then @rng.rand(0..1_000)
+    when "Float" then @rng.rand(0.0..1_000.0).round(2)
+    when "Boolean" then [true, false].sample(random: @rng)
+    when "Date" then (Date.new(2020, 1, 1) + @rng.rand(0..2_000)).iso8601
+    when "DateTime", "Time", "ISO8601DateTime" then Time.at(1_600_000_000 + @rng.rand(0..100_000_000)).utc.iso8601
+    else "#{type_name}-#{@sequence += 1}" # unknown custom scalar: override it
+    end
+  end
+
+  # same original id => same fake id, so relationships survive anonymization
+  def mapped_id(original)
+    @id_map[original] ||= (@sequence += 1).to_s
+  end
+
+  private
+
+  # :faker is an explicit ask — fail loudly when the gem is missing; auto
+  # (nil) quietly falls back to :literal
+  def resolve_mode(mode)
+    case mode
+    when :faker
+      raise ArgumentError, "mode: :faker requires the faker gem (add it to your Gemfile's test group)" unless defined?(::Faker)
+
+      :faker
+    when :literal then :literal
+    when nil then defined?(::Faker) ? :faker : :literal
+    else
+      raise ArgumentError, "mode: must be one of #{GraphWeaver::Testing::MODES.inspect} (or nil for auto), got #{mode.inspect}"
+    end
+  end
+end

data/lib/graph_weaver/testing.rb

@@ -0,0 +1,90 @@
+# typed: true
+# frozen_string_literal: true
+
+require_relative "../graph_weaver"
+
+# faker is optional — semantic values (name/email/age/price/...) when
+# present, type-based values when not
+begin
+  require "faker"
+rescue LoadError
+  # fall back to type-based generation
+end
+
+# Opt-in test tooling: require "graph_weaver/testing" from your spec
+# helper (never from production code). Configure once, initializer-style:
+#
+#   GraphWeaver::Testing.configure do |config|
+#     config.schema = MySchema                  # for auto_fake / cassettes
+#     config.seed = 42                          # reproducible fakes
+#     config.mode = :faker                      # or :literal; nil = auto
+#     config.overrides = { "Person.name" => "Daniel" }
+#     config.list_size = 2..4
+#     config.null_chance = 0.1                  # nullable fields go nil sometimes
+#     config.cassette_dir = "spec/cassettes"
+#   end
+#
+# mode picks how values are fabricated:
+#   :faker   — semantic, field-name matched (requires the faker gem)
+#   :literal — plain type-derived values ("name-1", seeded numbers)
+#   nil      — auto: :faker when the gem is loaded, else :literal
+#
+# rspec users: require "graph_weaver/rspec" instead — it hooks the suite
+# (seed from rspec, optional auto-faked executor per example).
+module GraphWeaver
+  module Testing
+    MODES = [:faker, :literal].freeze
+
+    class Config
+      attr_accessor :overrides, :seed, :list_size, :null_chance, :schema, :cassette_dir, :auto_fake
+      attr_reader :mode
+
+      def initialize
+        @overrides = {}
+        @seed = nil
+        @list_size = 1..3
+        @null_chance = 0.0
+        @mode = nil # auto
+        @schema = nil
+        @cassette_dir = "spec/cassettes"
+        @auto_fake = false
+      end
+
+      def mode=(mode)
+        unless mode.nil? || MODES.include?(mode)
+          raise ArgumentError, "mode: must be one of #{MODES.inspect} (or nil for auto), got #{mode.inspect}"
+        end
+
+        @mode = mode
+      end
+    end
+
+    class << self
+      def config
+        @config ||= Config.new
+      end
+
+      def configure
+        yield config
+      end
+
+      # back to defaults — between tests, or to undo an experiment
+      def reset!
+        @config = nil
+      end
+
+      # resolve a cassette name ("github") against cassette_dir; paths
+      # with separators or extensions pass through
+      def cassette_path(name)
+        return name if name.include?("/") || name.end_with?(".yml", ".yaml")
+
+        File.join(config.cassette_dir, "#{name}.yml")
+      end
+    end
+  end
+end
+
+require_relative "testing/values"
+require_relative "testing/fake_executor"
+require_relative "testing/failure"
+require_relative "testing/cassette"

data/lib/graph_weaver/version.rb

@@ -1,3 +1,3 @@
 module GraphWeaver
-  VERSION = "0.0.1"
+  VERSION = "0.1.0"
 end

data/lib/graph_weaver.rb

@@ -1,11 +1,105 @@
 require "graphql"
 require "sorbet-runtime"
 
+require_relative "graph_weaver/errors"
+require_relative "graph_weaver/response"
+require_relative "graph_weaver/inflect"
 require_relative "graph_weaver/codegen"
 require_relative "graph_weaver/http_executor"
 require_relative "graph_weaver/schema_loader"
 require_relative "graph_weaver/version"
 
-# opt-in: require "graph_weaver/directive_defaults_patch" to fix
-# graphql-ruby dropping directive argument defaults when loading SDL
-# (needed for Apollo supergraph SDL until rmosolgo/graphql-ruby#5659 ships)
+# opt-in extras:
+#   require "graph_weaver/faraday_executor"        # Faraday transport
+#   require "graph_weaver/directive_defaults_patch" # fix graphql-ruby
+#     dropping directive argument defaults when loading SDL (needed for
+#     Apollo supergraph SDL until rmosolgo/graphql-ruby#5659 ships)
+module GraphWeaver
+  class << self
+    # global default transport; generated modules fall back to this
+    # (override per module with MyQuery.executor=, or per call with
+    # execute(executor:))
+    attr_writer :executor
+
+    def executor
+      @executor or raise Error, "no executor configured — set GraphWeaver.executor= or pass executor:"
+    end
+
+    # Teach the generator how a GraphQL custom scalar deserializes into a
+    # rich Ruby object (and serializes back onto the wire when used as a
+    # variable):
+    #
+    #   GraphWeaver.register_scalar("Money", type: Money, requires: "bigdecimal")
+    #
+    # A field typed `Money` then generates `const :price, T.nilable(Money)`
+    # and casts with `Money.parse(...)` in from_h. Pass a real class as
+    # type: and cast:/serialize: are inferred from it — .parse/#to_s, or
+    # .load/.dump — by probing the deserialize side (see ScalarType::CODECS).
+    # Override with a Symbol method name (safest — no string to misspell), a
+    # Proc(expr) => code string, or :itself to force pass-through. requires:
+    # (a String or Array) names files the generated code needs — validated,
+    # and actually required to confirm it resolves when type: is a real class.
+    # coerce: true makes a variable of this scalar accept the value OR its
+    # raw input (e.g. "12.00"), running the latter through the cast before
+    # serializing — it raises on bad input, so some safety survives. Built-in
+    # scalars are pre-registered the same way, so this also overrides them.
+    # Call before generating.
+    def register_scalar(graphql_name, type:, cast: nil, serialize: nil, requires: nil, coerce: false)
+      Codegen.register_scalar(graphql_name, type:, cast:, serialize:, requires:, coerce:)
+    end
+
+    # Restore the built-in scalars, dropping every custom registration —
+    # the clean slate to reach for between tests or to undo overrides. Pass
+    # coerce: true to reload the built-ins with input coercion enabled
+    # (Float accepts 5/"5", etc.), then register your own scalars on top.
+    def reset_scalars!(coerce: false)
+      Codegen.reset_scalars!(coerce:)
+    end
+
+    # Empty the scalar registry entirely, built-ins included (see
+    # reset_scalars! to restore the defaults).
+    def clear_scalars!
+      Codegen.clear_scalars!
+    end
+
+    # Parse a query into a typed query module:
+    #
+    #   PersonQuery = GraphWeaver.parse(schema:, query: "queries/person.graphql")
+    #
+    # query is a .graphql/.gql path (module name derived from the file
+    # name) or a raw query string (name derived from the operation name,
+    # falling back to "Query" for anonymous operations — collisions are
+    # impossible since each parse gets its own container). Pass name: to
+    # override, executor: to set the module's transport.
+    def parse(schema:, query:, name: nil, executor: nil)
+      if query.end_with?(".graphql", ".gql")
+        name ||= "#{Inflect.camelize(File.basename(query, ".*"))}Query"
+        query = File.read(query)
+      end
+
+      Codegen.parse(schema:, query:, module_name: name, executor:)
+    end
+
+    # One-shot dynamic execution — no module handling, no build step:
+    #
+    #   GraphWeaver.execute(schema:, query:, variables: { id: "1" })   # => Response
+    #   GraphWeaver.execute!(schema:, query:, variables: { id: "1" })  # => Result (or raise)
+    #
+    # Mirrors a generated module: execute returns the Response envelope,
+    # execute! returns the typed result directly and raises QueryError on
+    # top-level errors. Transport precedence: executor: param, then
+    # GraphWeaver.executor, then in-process execution against schema.
+    # Variable keys may be graphql-cased strings or ruby symbols.
+    def execute(schema:, query:, variables: {}, executor: nil)
+      executor ||= @executor || schema
+      mod = parse(schema:, query:, executor:)
+      kwargs = variables.to_h { |key, value| [Inflect.underscore(key.to_s).to_sym, value] }
+      mod.execute(**kwargs)
+    end
+
+    # execute + data! — the typed result, or a raised QueryError. See execute.
+    def execute!(schema:, query:, variables: {}, executor: nil)
+      execute(schema:, query:, variables:, executor:).data!
+    end
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: graph_weaver
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.1.0
 platform: ruby
 authors:
 - Daniel Pepper
@@ -37,6 +37,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: bigdecimal
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: debug
   requirement: !ruby/object:Gem::Requirement
@@ -51,6 +65,34 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: faker
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: faraday
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
@@ -135,12 +177,32 @@ files:
 - NOTES.md
 - PLAN.md
 - README.md
+- docs/errors.md
+- docs/generated_modules.md
+- docs/real_world.md
+- docs/scalars.md
+- docs/testing.md
 - graph_weaver.gemspec
 - lib/graph_weaver.rb
 - lib/graph_weaver/codegen.rb
+- lib/graph_weaver/codegen/emit.rb
+- lib/graph_weaver/codegen/nodes.rb
+- lib/graph_weaver/codegen/scalar_type.rb
 - lib/graph_weaver/directive_defaults_patch.rb
+- lib/graph_weaver/errors.rb
+- lib/graph_weaver/faraday_executor.rb
 - lib/graph_weaver/http_executor.rb
+- lib/graph_weaver/inflect.rb
+- lib/graph_weaver/response.rb
+- lib/graph_weaver/rspec.rb
 - lib/graph_weaver/schema_loader.rb
+- lib/graph_weaver/selection.rb
+- lib/graph_weaver/testing.rb
+- lib/graph_weaver/testing/cassette.rb
+- lib/graph_weaver/testing/failure.rb
+- lib/graph_weaver/testing/fake_executor.rb
+- lib/graph_weaver/testing/rspec.rb
+- lib/graph_weaver/testing/values.rb
 - lib/graph_weaver/version.rb
 homepage: https://github.com/dpep/graph_weaver
 licenses: