graph_weaver 0.0.1 → 0.1.0

data/docs/generated_modules.md

@@ -0,0 +1,119 @@
+# Generated modules
+
+`GraphWeaver::Codegen` turns one GraphQL operation into one `# typed: strict`
+Ruby module. Everything `srb tc` knows about your query results comes from this
+file — there is no runtime schema, no lazy wrapper, no reflection.
+
+## Anatomy
+
+```ruby
+module PersonQuery
+  QUERY = "..."                  # the operation, verbatim
+
+  class Result < T::Struct       # the response shape, exactly as selected
+    class Person < T::Struct
+      const :name, String        # non-null in the schema
+      const :birthday, T.nilable(Date)
+
+      def self.from_h(data) ...  # generated casting — no reflection
+    end
+
+    const :person, T.nilable(Person)
+  end
+
+  def self.executor ...          # default transport (see below)
+  def self.execute(id:, executor: self.executor)   # -> GraphWeaver::Response[Result]
+  def self.execute!(id:, executor: self.executor)  # -> Result, or raises QueryError
+end
+```
+
+- `execute` returns the **envelope** — `GraphWeaver::Response[Result]` with
+  `#data`, `#data!`, `#errors`, `#extensions` — so partial data and
+  cost/throttle metadata survive.
+- `execute!` is the shortcut: the typed result or a raised
+  `GraphWeaver::QueryError`.
+
+## Variables become typed kwargs
+
+```graphql
+mutation($name: String!, $species: Species!, $note: String) { ... }
+```
+
+```ruby
+AddPetQuery.execute!(name: "Rex", species: AddPetQuery::Species::Dog)
+```
+
+- required vs optional falls out of nullability and defaults: nullable or
+  defaulted variables become optional kwargs (nil is omitted from the wire,
+  so server-side defaults apply)
+- enum variables generate module-level `T::Enum`s and serialize themselves
+- custom scalars serialize through the [scalar registry](scalars.md)
+
+**Input objects** generate module-level `T::Struct`s with `serialize`
+(aliased as `to_h`) producing the wire hash — optional fields default nil and
+stay off the wire:
+
+```ruby
+input = AdoptQuery::AdoptionInput.new(name: "Rex", species: AdoptQuery::Species::Dog)
+AdoptQuery.execute!(input:)
+
+# or pass a plain hash straight to execute — .coerce normalizes and type-checks it at
+# the boundary (underscored Symbol/String keys; enums accept wire values;
+# nested inputs accept hashes)
+AdoptQuery.execute!(input: { name: "Rex", species: "DOG" })
+```
+
+Nested inputs work (dependencies emit first); recursive input types are not
+yet supported.
+
+## Selections
+
+- **Fragments** — inline fragments and named spreads flatten into the
+  selection; type conditions match exact names or interfaces/unions the type
+  belongs to.
+- **Unions and interfaces** — each abstract selection site emits a module:
+  one member struct per possible type, `Type = T.type_alias { T.any(...) }`,
+  and a `from_h` dispatching on `__typename`. Generation *requires*
+  `__typename` in the selection so dispatch is possible.
+- **`@skip` / `@include`** — a directive-conditional field may be absent from
+  the response regardless of schema nullability, so its generated type is
+  always nilable.
+- **Aliases** — result keys follow aliases; props are the underscored alias.
+
+## Naming
+
+Module names derive from the operation name (`query GetPerson` → `GetPerson`);
+`GraphWeaver.parse` on a `.graphql` file derives from the file name
+(`person.graphql` → `PersonQuery`). Pass `module_name:`/`name:` to override.
+`Codegen.generate` requires a deliberate name for anonymous operations; dynamic
+`parse` defaults to `Query` (its constants are container-scoped, so collisions
+are impossible).
+
+Nested struct names come from GraphQL type names, disambiguated one level by
+field name on collision.
+
+## Executors
+
+An executor is anything with `execute(query, variables:)` whose result `to_h`s
+into `{"data" => ..., "errors" => ...}`. Resolution order:
+
+1. per call: `execute(..., executor: something)`
+2. per module: `PersonQuery.executor = something`
+3. baked constant: `Codegen.generate(..., executor: MyApi::Executor)`
+4. global: `GraphWeaver.executor` (raises helpfully when unconfigured)
+
+Generate *without* a baked constant when you want modules to follow the
+global — that's also what lets [testing's auto_fake](testing.md) swap in a
+fake per example.
+
+## Dynamic mode
+
+`GraphWeaver.parse` generates + evals in one step (no build artifact, evaled
+into an anonymous container — no global constants leak). Same runtime
+semantics; invisible to `srb tc`, so prefer the build step where static
+checking matters. `GraphWeaver.execute(schema:, query:, variables: {})` is
+the one-shot form.
+
+Generated source is eval'd, so inputs are validated: module names must be
+constant names, and query heredocs can't be terminated early. Still: queries
+are code — don't feed untrusted strings to parse.

data/docs/real_world.md

@@ -0,0 +1,46 @@
+# Against a real API
+
+Everything composes for a remote endpoint — introspect the schema
+straight off the wire, then query with typed results. GitHub's API,
+end to end:
+
+```ruby
+require "graph_weaver"
+
+executor = GraphWeaver::HttpExecutor.new(
+  "https://api.github.com/graphql",
+  headers: { "Authorization" => "Bearer #{`gh auth token`.strip}" },
+)
+
+# introspecting a big API takes seconds — cache: stores the introspection
+# JSON in a file and reuses it for ttl: seconds. For Rails.cache/redis,
+# cache SchemaLoader.introspection_result(executor) (a plain Hash) instead.
+schema = GraphWeaver::SchemaLoader.introspect(
+  executor,
+  cache: "tmp/github-schema.json",
+  ttl: 24 * 60 * 60,
+)
+
+# map GitHub's DateTime scalar onto Time (cast inferred from Time.parse)
+GraphWeaver.register_scalar("DateTime", type: Time, serialize: :iso8601, requires: "time")
+
+RepoQuery = GraphWeaver.parse(schema:, executor:, query: <<~GRAPHQL)
+  query($owner: String!, $name: String!) {
+    repository(owner: $owner, name: $name) {
+      nameWithOwner
+      createdAt
+      stargazerCount
+    }
+  }
+GRAPHQL
+
+repo = RepoQuery.execute!(owner: "dpep", name: "graph_weaver").repository
+repo&.name_with_owner   # => "dpep/graph_weaver"
+repo&.created_at        # => 2026-07-07 ... (a real Time)
+repo&.stargazer_count   # => Integer
+```
+
+The same flow runs as one-off integration specs against the live GitHub
+and Countries APIs — `make integration` (network; GitHub auth via
+`gh auth token` or `GITHUB_TOKEN`).
+

data/docs/scalars.md

@@ -0,0 +1,69 @@
+# Custom scalars
+
+Teach the generator how a GraphQL custom scalar deserializes into a rich
+Ruby object (and serializes back when used as a variable). A field typed
+`Money` then generates `const :price, T.nilable(Money)` and casts with
+`Money.parse(...)` inline — no runtime reflection:
+
+```ruby
+GraphWeaver.register_scalar("Money", type: Money, requires: "bigdecimal")
+```
+
+Pass a real class as `type:` and the cast/serialize are **inferred** from it by
+probing the deserialize side and pairing its serializer:
+
+| the class defines | cast          | serialize      |
+|-------------------|---------------|----------------|
+| `.parse`          | `Type.parse(v)` | `v.to_s`     |
+| `.load`           | `Type.load(v)`  | `Type.dump(v)` |
+
+so the common case needs nothing more. Probing the *deserialize* side is
+deliberate — every object has `#to_s`, so inferring off it would wrongly wrap
+plain types like `String`/`Integer`; requiring a `.parse`/`.load` the type
+actually defines avoids that (and is why the built-ins can be registered with
+their real class constants). Override explicitly when you need to:
+
+- a `Symbol` method name, nothing to misspell: `cast: :load` → `Money.load(expr)`,
+  `serialize: :to_json` → `expr.to_json`
+- a `Proc` for anything a method name can't express: `cast: ->(expr) { "Money.new(#{expr})" }`
+- `:itself` to force pass-through, opting out of inference (rare)
+
+`type:` also accepts a plain string (`"BigDecimal"`) when you'd rather not
+reference the class. `requires:` (a string or array) names files emitted as
+`require`s atop the generated source so the cast/type resolve. When `type:` is
+a real class (so the runtime is loaded), each path is also `require`d at
+registration — a typo fails now, not in the generated file.
+
+Pass `coerce: true` to let a variable of this scalar accept **either** the value
+object **or** its raw input, normalizing the latter through the cast:
+
+```ruby
+GraphWeaver.register_scalar("Money", type: Money, coerce: true)
+# generated execute now takes T.any(Money, String); "12.00" is parsed
+StoreQuery.execute(budget: "12.00")          # Money.parse("12.00") under the hood
+StoreQuery.execute(budget: Money.new(1200))  # passed straight through
+```
+
+Bad input still explodes (the cast raises), so some safety survives; coercion
+needs both a cast and a serialize. Off by default — the strict typed kwarg is the norm.
+
+`coerce:` also takes a **Symbol** naming a conversion method, for built-ins where
+a plain method is the whole story — `coerce: :to_f` makes a variable accept
+`5`/`"5"` and `.to_f` it, sending a native number (not `"5.0"`) on the wire. The
+convertible built-ins already know theirs (`Float`→`:to_f`, `Int`→`:to_i`,
+`ID`/`String`→`:to_s`), so rather than re-registering each, flip them all on at
+once:
+
+```ruby
+GraphWeaver.reset_scalars!(coerce: true)   # reload built-ins as coercible
+GraphWeaver.register_scalar("Money", ...)  # then add your own
+```
+
+`Boolean` and `Date` have no lossless one-method conversion, so they stay strict.
+
+The built-in scalars (`Date`, `ID`, `Int`, …) are pre-registered through the
+same path (`Date` even carries its own `require "date"`), so a later
+`register_scalar` overrides them; `GraphWeaver.reset_scalars!` restores the
+defaults (`reset_scalars!(coerce: true)` restores them coercible) and
+`clear_scalars!` empties the registry. Register before generating — it's a
+codegen-time concern, baked into the emitted source.

data/docs/testing.md

@@ -0,0 +1,93 @@
+# Testing
+
+`require "graph_weaver/rspec"` from your spec helper (or
+`graph_weaver/testing` outside rspec — never production code) for a
+zero-setup fake backend. `FakeExecutor` fabricates
+schema-correct responses for whatever query arrives: real enum values,
+valid `__typename` members, iso8601 date scalars — every fake casts
+cleanly through your generated structs.
+
+```ruby
+fake = GraphWeaver::Testing::FakeExecutor.new(schema:)
+
+person = PersonQuery.execute!(id: "1", executor: fake).person
+person.name       # => "Eliza Kertzmann" (faker-matched on field name, when faker is loaded)
+person.birthday   # => a real Date
+```
+
+Pin what matters, keyed by GraphQL names (schema vocabulary — keys
+survive query refactors); `"Type.field"` beats `"field"`:
+
+```ruby
+GraphWeaver::Testing::FakeExecutor.new(schema:, overrides: {
+  "Person.name" => "Daniel",
+  "email" => -> { "test@example.com" },
+})
+```
+
+Or configure once, initializer-style (e.g. in `spec/support/graph_weaver.rb`):
+
+```ruby
+require "graph_weaver/rspec"   # rspec: seed follows --seed
+
+GraphWeaver::Testing.configure do |config|
+  config.schema = MySchema
+  config.auto_fake = true              # every example runs against a fresh FakeExecutor
+  config.mode = :faker                 # or :literal (plain typed values); nil = auto
+  config.overrides = { "Person.name" => "Daniel" }
+  config.list_size = 1..3
+  config.null_chance = 0.1             # nullable fields go nil sometimes
+end
+```
+
+With the rspec integration, `rspec --seed 1234` reproduces fake data
+along with test order, and `auto_fake` installs a seeded executor per
+example (generate modules *without* a baked `executor:` so they consult
+`GraphWeaver.executor`). `mode:` picks value fabrication: `:faker`
+(semantic, field-name matched — raises if the gem is missing),
+`:literal` (plain type-derived), or nil to auto-detect faker.
+
+**Simulating failures** — every failure mode is just an executor, so
+error-handling paths are testable without a server that misbehaves on cue:
+
+```ruby
+Failure = GraphWeaver::Testing::Failure
+
+PersonQuery.execute(id: "1", executor: Failure.transport)             # TransportError (cause preserved)
+PersonQuery.execute(id: "1", executor: Failure.server(status: 502))   # ServerError
+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", executor: Failure.graphql("boom", data: {...}))  # partial failure
+
+# retries: fail twice, then succeed
+GraphWeaver::Testing::SequenceExecutor.new(Failure.transport, Failure.transport, fake)
+
+# type mismatch: corrupt: derives a wrong-typed wire value for the field —
+# casting raises GraphWeaver::TypeError (overrides remain the manual escape hatch)
+GraphWeaver::Testing::FakeExecutor.new(schema:, corrupt: "Person.birthday")
+
+# stale schema naming a real (sampled) field
+Failure.stale_schema(schema: MySchema)
+
+# field-level partial failure with real GraphQL null propagation: the error
+# lands with its concrete path and nulls bubble to the nearest nullable spot
+GraphWeaver::Testing::FakeExecutor.new(schema:, fail_at: { path: "person.email", code: "PRIVATE" })
+```
+
+**Capture and replay** — cassettes live above the transport (no HTTP
+interception), so they work identically for HTTP, Faraday, or in-process
+executors:
+
+```ruby
+# records against the live executor when the file is missing, replays after
+executor = GraphWeaver::Testing::Cassette.use("github", executor: live)
+```
+
+Cassettes hold real responses. Anonymize before committing — shape,
+nulls, list lengths, enums, and id relationships survive; values are
+replaced with (semantically matched) fakes:
+
+```ruby
+GraphWeaver::Testing::Cassette.new("spec/cassettes/github.yml").anonymize!(schema:)
+```
+

data/graph_weaver.gemspec

@@ -15,7 +15,10 @@ Gem::Specification.new do |s|
   s.add_dependency "graphql", ">= 2"
   s.add_dependency "sorbet-runtime"
 
+  s.add_development_dependency "bigdecimal"
   s.add_development_dependency "debug"
+  s.add_development_dependency "faker"
+  s.add_development_dependency "faraday"
   s.add_development_dependency "rspec"
   s.add_development_dependency "simplecov"
   s.add_development_dependency "sorbet"

data/lib/graph_weaver/codegen/emit.rb

@@ -0,0 +1,237 @@
+# typed: true
+# frozen_string_literal: true
+
+# Source emission: turns the node tree into the generated module text.
+# Mixed into Codegen — methods run with the generator instance state.
+class GraphWeaver::Codegen
+  module Emit
+    include GraphWeaver::Inflect
+
+    private
+
+    def emit_nested(node, out, indent)
+      case node
+      when UnionNode then emit_union(node, out, indent)
+      when EnumNode then emit_enum(node, out, indent)
+      else emit_object(node, out, indent)
+      end
+    end
+
+    def emit_enum(node, out, indent)
+      pad = "  " * indent
+
+      out << "#{pad}class #{node.class_name} < T::Enum"
+      out << "#{pad}  enums do"
+      node.values.each do |value|
+        out << "#{pad}    #{camelize(value.downcase)} = new(#{value.inspect})"
+      end
+      out << "#{pad}  end"
+      out << "#{pad}end"
+    end
+
+    def emit_object(node, out, indent)
+      pad = "  " * indent
+
+      out << "#{pad}class #{node.class_name} < T::Struct"
+      out << "#{pad}  extend T::Sig"
+      out << ""
+
+      node.fields.filter_map { |field| field.node.nested }.each do |child|
+        emit_nested(child, out, indent + 1)
+        out << ""
+      end
+
+      node.fields.each do |field|
+        out << "#{pad}  const :#{field.prop}, #{field.node.prop_type}"
+      end
+
+      out << ""
+      out << "#{pad}  sig { params(data: T::Hash[String, T.untyped]).returns(#{node.class_name}) }"
+      out << "#{pad}  def self.from_h(data)"
+      out << "#{pad}    new("
+      node.fields.each do |field|
+        out << "#{pad}      #{field.prop}: #{field_cast(field)},"
+      end
+      out << "#{pad}    )"
+      out << "#{pad}  rescue GraphWeaver::TypeError"
+      out << "#{pad}    raise # already wrapped by a nested struct — keep the innermost context"
+      out << "#{pad}  rescue TypeError, ArgumentError, KeyError => e"
+      out << "#{pad}    raise GraphWeaver::TypeError.new(struct: self, error: e)"
+      out << "#{pad}  end"
+      out << "#{pad}end"
+    end
+
+    def emit_union(node, out, indent)
+      pad = "  " * indent
+
+      out << "#{pad}module #{node.class_name}"
+      out << "#{pad}  extend T::Sig"
+      out << ""
+
+      node.members.each_value do |member|
+        emit_object(member, out, indent + 1)
+        out << ""
+      end
+
+      member_names = node.members.values.map(&:class_name)
+      type_alias = member_names.size == 1 ? member_names.first : "T.any(#{member_names.join(", ")})"
+      out << "#{pad}  Type = T.type_alias { #{type_alias} }"
+      out << ""
+      out << "#{pad}  sig { params(data: T::Hash[String, T.untyped]).returns(Type) }"
+      out << "#{pad}  def self.from_h(data)"
+      out << "#{pad}    case (typename = data.fetch(\"__typename\"))"
+      node.members.each do |graphql_name, member|
+        out << "#{pad}    when #{graphql_name.inspect} then #{member.class_name}.from_h(data)"
+      end
+      out << "#{pad}    else raise GraphWeaver::TypeError.new(struct: self, message: \"unexpected __typename: \#{typename}\")"
+      out << "#{pad}    end"
+      out << "#{pad}  end"
+      out << "#{pad}end"
+    end
+
+    def emit_execute(out, variables)
+      out << "  @executor = T.let(nil, T.untyped)"
+      out << ""
+      out << "  class << self"
+      out << "    extend T::Sig"
+      out << ""
+      out << "    sig { params(executor: T.untyped).void }"
+      out << "    attr_writer :executor"
+      out << ""
+      out << "    # default transport for execute"
+      out << "    sig { returns(T.untyped) }"
+      out << "    def executor"
+      out << "      @executor || #{@executor_const || "GraphWeaver.executor"}"
+      out << "    end"
+      out << "  end"
+      out << ""
+
+      sig_params = variables.map do |var|
+        bare = var.node.coerce? ? var.node.coerce_input_type : var.node.bare_type
+        kwarg_type = var.required ? bare : "T.nilable(#{bare})"
+        "#{var.kwarg}: #{kwarg_type}"
+      end
+      sig_params << "executor: T.untyped"
+
+      kwargs = variables.map { |var| var.required ? "#{var.kwarg}:" : "#{var.kwarg}: nil" }
+      kwargs << "executor: self.executor"
+
+      # execute returns the full envelope; execute! is the strict shortcut for
+      # `execute(...).data!` — the typed result, or a raised QueryError.
+      forward = (variables.map { |var| "#{var.kwarg}: #{var.kwarg}" } + ["executor: executor"]).join(", ")
+
+      out << "  sig { params(#{sig_params.join(", ")}).returns(GraphWeaver::Response[Result]) }"
+      out << "  def self.execute(#{kwargs.join(", ")})"
+
+      required, optional = variables.partition(&:required)
+      if required.empty?
+        out << "    variables = {}"
+      else
+        out << "    variables = {"
+        required.each do |var|
+          out << "      #{var.wire.inspect} => #{variable_serialize(var)},"
+        end
+        out << "    }"
+      end
+      optional.each do |var|
+        out << "    variables[#{var.wire.inspect}] = #{variable_serialize(var)} unless #{var.kwarg}.nil?"
+      end
+
+      out << ""
+      out << "    raw = executor.execute(QUERY, variables: variables).to_h"
+      out << "    GraphWeaver::Response[Result].new("
+      out << "      data: (Result.from_h(raw[\"data\"]) if raw[\"data\"]),"
+      out << "      errors: (raw[\"errors\"] || []).map { |e| GraphWeaver::GraphQLError.from_h(e) },"
+      out << "      extensions: raw[\"extensions\"] || {},"
+      out << "    )"
+      out << "  end"
+      out << ""
+      out << "  sig { params(#{sig_params.join(", ")}).returns(Result) }"
+      out << "  def self.execute!(#{kwargs.join(", ")})"
+      out << "    execute(#{forward}).data!"
+      out << "  end"
+    end
+
+    def variable_serialize(var)
+      value = var.node.coerce? ? var.node.coerce(var.kwarg) : var.kwarg
+      var.node.serialize_identity? ? value : var.node.serialize(value, 1)
+    end
+
+    # Structured shape for a schema-validation error: message plus its first
+    # source location, so ValidationError#errors is inspectable.
+    def validation_detail(error)
+      loc = (error.to_h["locations"]&.first if error.respond_to?(:to_h))
+      { message: error.message, line: loc && loc["line"], column: loc && loc["column"] }
+    end
+
+    def field_cast(field)
+      node = field.node
+
+      if node.non_null?
+        raw = "data.fetch(#{field.key.inspect})"
+        node.identity? ? raw : node.cast(raw, 1)
+      else
+        raw = "data[#{field.key.inspect}]"
+        node.identity? ? raw : "#{raw}&.then { |v1| #{node.cast("v1", 2)} }"
+      end
+    end
+
+    # a module-level T::Struct per input type; serialize builds the wire
+    # hash, omitting optional fields left nil
+    def emit_input(node, out, indent)
+      pad = "  " * indent
+
+      out << "#{pad}class #{node.class_name} < T::Struct"
+      out << "#{pad}  extend T::Sig"
+      out << ""
+      node.fields.each do |field|
+        default = field.required ? "" : ", default: nil"
+        out << "#{pad}  const :#{field.prop}, #{field.node.prop_type}#{default}"
+      end
+      out << ""
+      out << "#{pad}  sig { returns(T::Hash[String, T.untyped]) }"
+      out << "#{pad}  def serialize"
+      out << "#{pad}    result = T.let({}, T::Hash[String, T.untyped])"
+      node.fields.each do |field|
+        value = field.node.serialize_identity? ? field.prop.to_s : field.node.serialize(field.prop.to_s, 1)
+        line = "result[#{field.wire.inspect}] = #{value}"
+        line += " unless #{field.prop}.nil?" unless field.required
+        out << "#{pad}    #{line}"
+      end
+      out << "#{pad}    result"
+      out << "#{pad}  end"
+      out << ""
+      out << "#{pad}  # serialize, under the conventional name"
+      out << "#{pad}  sig { returns(T::Hash[String, T.untyped]) }"
+      out << "#{pad}  def to_h = serialize"
+      out << ""
+      out << "#{pad}  # Build from a plain hash (underscored keys, Symbol or String):"
+      out << "#{pad}  # enums accept their wire values, nested inputs accept hashes;"
+      out << "#{pad}  # the struct's types are enforced on construction."
+      out << "#{pad}  sig { params(value: T.any(#{node.class_name}, T::Hash[T.untyped, T.untyped])).returns(#{node.class_name}) }"
+      out << "#{pad}  def self.coerce(value)"
+      out << "#{pad}    return value if value.is_a?(#{node.class_name})"
+      out << ""
+      out << "#{pad}    new("
+      node.fields.each do |field|
+        raw = "value_at(value, :#{field.prop})"
+        expr = if field.node.hash_coerce_identity?
+          raw
+        elsif field.required
+          "#{raw}.then { |v1| #{field.node.hash_coerce("v1", 2)} }"
+        else
+          "#{raw}&.then { |v1| #{field.node.hash_coerce("v1", 2)} }"
+        end
+        out << "#{pad}      #{field.prop}: #{expr},"
+      end
+      out << "#{pad}    )"
+      out << "#{pad}  end"
+      out << ""
+      out << "#{pad}  sig { params(hash: T::Hash[T.untyped, T.untyped], key: Symbol).returns(T.untyped) }"
+      out << "#{pad}  private_class_method def self.value_at(hash, key)"
+      out << "#{pad}    hash.key?(key) ? hash[key] : hash[key.to_s]"
+      out << "#{pad}  end"
+      out << "#{pad}end"
+    end
+  end
+end