graph_weaver 0.2.2 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7673fd6efc0459bdb3097e73e1c3f8fe265910bfdaf349bf7a358adc1ece1830
-  data.tar.gz: f5ce9f4c484e1fb8f5eb074eaaac502ca62fb3ecf6ab90d9157a2a055e88c3b3
+  metadata.gz: e66ac94243bdc7f065534845a722bfd209c8d7b23a3a5fa1eff6041e3f563655
+  data.tar.gz: 413217dbda71c297abe537dc996b8e8413821365d9e966493bf7301d6351a6c7
 SHA512:
-  metadata.gz: a75dd5a723dd52108e2f449bd1c5f0e1dc9a71065106614c57854f318024f700e16596cd4764cf9768f02d536cc040bd0554bdd75762eeba23c09b71a7051cf5
-  data.tar.gz: 377c07a20d2cf47873425c72ad84709c36555396fea1a2102c7bdc3f79e07e8e823ed9639238aecac8066f352e65599a10ae15a71013a7de3a0a4d3675bf169c
+  metadata.gz: 62dab00fca85973dbff0e695dcd9970a554ca98b6a717a375fa7f2cde349b2967672ce541bf108d3b058b54b47ce7d274f6c8f11f069360a59e95fcb86ff8ae5
+  data.tar.gz: 3a11e52459c3b0158d831c8815ced9c4ca5cd323435ffac4e36a8648e83179dd87763a4570aaa56b240d0d7d77d3b91e43d1706f40112d3eae2fa608950b797c

data/CHANGELOG.md

@@ -1,3 +1,19 @@
+###  v0.3.0  (2026-07-28)
+- Renamed `register_type` to `extend_type` to disambiguate intent: it
+  *decorates* a generated struct with mixin modules/helpers — it doesn't
+  define or replace a type's deserialization (that's `register_scalar` /
+  `register_enum`, for leaf types, whose Ruby shape is fixed; a composite's
+  shape is per-query, so there's nothing fixed to replace). No deprecation —
+  the old name is dropped.
+- Invalid query input now raises `GraphWeaver::InputError` (under the
+  `GraphWeaver::Error` umbrella) instead of a raw `ArgumentError` /
+  `KeyError` / sorbet `TypeError`: an unknown or typo'd input key, a
+  missing required field, an out-of-range enum, or a wrong-typed field
+  when an input object is built from a hash through `coerce`. Carries
+  `#field` / `#struct` and a JSON-ready `#to_h` — one rescue point for
+  returning a 422 at an API boundary. Top-level *scalar* kwargs still
+  fail like any Ruby method call (sorbet `TypeError` / `ArgumentError`).
+
 ###  v0.2.2  (2026-07-22)
 - Generated modules expose from_response / from_response! alongside
   execute / execute!: deserialize a raw GraphQL response (fetched by any

data/CLAUDE.md

@@ -0,0 +1,70 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## What this is
+
+A typed GraphQL client for Ruby: generates `# typed: strict` Ruby (nested
+`T::Struct`s + a typed `execute`) from your queries, checked against the schema
+at generation time. Sorbet is core to the product.
+
+## Sorbet typing policy — type by value, not for coverage
+
+Sorbet being core does **not** mean every file should be `# typed: strict`. Type
+where it pays off in developer experience; leave the rest at `# typed: true`.
+
+- **Strict (full sigs) — developer-facing contracts.** The types users touch:
+  `response.rb` (the envelope every `execute` returns), the error hierarchy
+  (`errors.rb`), and the **generated code** (emitted `# typed: strict`). Concrete
+  types here give downstream apps real call-site checking + autocomplete — that's
+  the product.
+- **`# typed: true` (loose) — dynamic / boundary internals.** The codegen
+  (`codegen.rb`, `codegen/nodes.rb`, `codegen/emit.rb`, `codegen/scalar_type.rb`,
+  `codegen/enum_type.rb`) walks graphql-ruby's approximately-typed AST and builds
+  modules/strings dynamically; `client.rb` wraps a graphql-ruby schema and a
+  duck-typed transport. Strict here is ~all `T.untyped` — paperwork that documents
+  shape without catching anything. **Don't promote these to strict.**
+- Rule of thumb: if a sig would be mostly `T.untyped`, it isn't worth writing.
+  Concrete types = value; `T.untyped` sigs = paperwork.
+- `railtie.rb` / `tasks.rb` are `# typed: ignore` (Rails/Rake DSL);
+  `directive_defaults_patch.rb` is `# typed: false` (a prepended monkeypatch).
+
+## Design invariants (don't "fix" these)
+
+- **The client slot is duck-typed.** A transport, `Retry`, a live graphql-ruby
+  schema class, or a test fake all satisfy one contract —
+  `execute(query, variables:) => {"data" => ..., "errors" => ...}` — with no
+  shared base class. **Don't formalize it as a strict Sorbet interface**: a
+  graphql-ruby `Schema` class fits the slot without inheriting anything, and a
+  strict interface would exclude it. This is why the transport/client seams stay
+  loosely typed.
+- **Codegen is query-driven.** Structs are generated per selection set, only for
+  the types a query actually touches — not the whole schema (so extra schema
+  types, e.g. federation `join__*`, generate no code).
+- **Leaf codecs vs composite decoration.** `register_scalar` / `register_enum`
+  *define/replace* how a leaf deserializes (its Ruby shape is fixed);
+  `extend_type` only *decorates* a generated composite struct with mixins — it
+  can't replace one, because a composite's shape varies per query. Don't add a
+  "replace a composite's deserializer" path.
+
+## Green before commit
+
+```sh
+bundle exec rspec        # full suite
+bundle exec srb tc       # Sorbet typecheck (CI gates on this too)
+```
+
+Both must pass. Sorbet sigs are runtime-checked by sorbet-runtime, so a wrong
+sig surfaces as an rspec failure, not only a `srb tc` error — a green suite
+validates the sigs against real usage.
+
+## Version bumps
+
+Bump `lib/graph_weaver/version.rb` and, in the **same commit**:
+
+- update `Gemfile.lock` (the gem pins its own version there; CI runs a frozen
+  `bundle install`, which fails at the *setup* step with exit code 16 — before
+  tests — if the lock is stale), and
+- add a `CHANGELOG.md` entry.
+
+`gem push` (the actual RubyGems release) is a separate, manual step.

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    graph_weaver (0.2.2)
+    graph_weaver (0.3.0)
       graphql (>= 2)
       sorbet-runtime
 
@@ -176,7 +176,7 @@ CHECKSUMS
   google-protobuf (4.35.1-arm64-darwin) sha256=d9c957df04fa89c749fa9a72a7b383eb4296efc9b2303dc6fd6fbe39c698ad6b
   google-protobuf (4.35.1-x86_64-darwin) sha256=66b62b4df00931018a692806df66393efa960d6d2b7da69735187249f950d3ee
   google-protobuf (4.35.1-x86_64-linux-gnu) sha256=c786439087512a3fbd199e9897d265b855f951d4027e218ea55e858d45969edd
-  graph_weaver (0.2.2)
+  graph_weaver (0.3.0)
   graphql (2.6.6) sha256=7438e2036b571c884377eb1529225470ba959365f26dc47152953c213bc38c31
   i18n (1.15.2) sha256=00f9eb62412fe593b2a65a97daa75300d37abb8f7202ec748e94b6d46a9dd1b5
   io-console (0.8.2) sha256=d6e3ae7a7cc7574f4b8893b4fca2162e57a825b223a177b7afa236c5ef9814cc

data/README.md

@@ -113,6 +113,8 @@ api.execute!("query($id: ID!) { person(id: $id) { name } }", id: "1")
   `@skip`/`@include`, naming, clients, dynamic mode
 - **[Against a real API](docs/real_world.md)** — the exploratory tour:
   introspect a live endpoint (GitHub end to end), dynamic mode, schema caching
+- **[Federation](docs/federation.md)** — Apollo Federation: supergraph vs API
+  schema, feeding weaver a composed graph, the `@inaccessible` caveat
 - **[Transports](docs/transports.md)** — clients, the execute contract,
   Faraday, retries and backoff
 - **[Custom scalars](docs/scalars.md)** — the registry: codec inference,

data/docs/errors.md

@@ -31,6 +31,7 @@ it failed:
 | `ServerError` | reached it, non-2xx HTTP — `#status`, `#body` |
 | `QueryError` | 200 body with top-level GraphQL errors — `#errors`, `#data`, `#extensions`, `#codes` |
 | `TypeError` | the response wouldn't cast into the generated structs — `#struct`, `#cause` |
+| `InputError` | the variables wouldn't build into the generated input structs — unknown/typo'd key, missing required field, out-of-range enum, wrong-typed field — `#field`, `#struct` |
 | `ValidationError` | build time: the query didn't validate against the schema |
 
 ```ruby
@@ -64,11 +65,30 @@ Defaults match the rescue block above: transport failures always retry,
 override with `retry_if:`), and GraphQL-level codes only when listed in
 `retry_codes:`. Exhausting `tries:` re-raises the last error.
 
-Two deliberate exceptions live *outside* the hierarchy, because typed
-kwargs should fail like any Ruby method call: a wrong-typed variable
-raises sorbet-runtime's `TypeError` ("Parameter 'page': Expected type
-T.nilable(Integer), got type String"), and a missing required variable
-raises a plain `ArgumentError` ("missing keyword: :id").
+**Top-level scalar variables** fail like any Ruby method call, *outside* the
+hierarchy on purpose — passing the wrong Ruby type for a scalar kwarg is a
+programming bug, not caller input: a wrong-typed one raises sorbet-runtime's
+`TypeError` ("Parameter 'page': Expected type T.nilable(Integer), got type
+String"), a missing required one a plain `ArgumentError` ("missing keyword: :id").
+
+**Input-object variables** are the caller-input case, so they're *inside* the
+hierarchy. When you pass an input object as a hash (or struct) it's built
+through the generated `coerce`, and any problem there — an unknown/typo'd key, a
+missing required field, an out-of-range enum, a wrong-typed field — raises
+`GraphWeaver::InputError`. That's one rescue point for turning invalid input
+into a 422:
+
+```ruby
+rescue GraphWeaver::InputError => e
+  render json: e.to_h, status: :unprocessable_entity
+  # { "error" => "GraphWeaver::InputError",
+  #   "message" => "unknown key(s) for …Input: staus (did you mean 'status'?)",
+  #   "field" => "staus", "struct" => "…Input" }
+end
+```
+
+A nested filter reports the innermost input type, so the error points at the
+input that actually held the bad field.
 
 Business/validation failures returned *as data* (Shopify-style `userErrors { field
 message code }`) aren't errors here — they're just fields you selected, so they

data/docs/federation.md

@@ -0,0 +1,100 @@
+# Federation
+
+GraphWeaver generates a client for the **whole** graph, so with Apollo
+Federation you point it at the *composed* schema — the supergraph or the API
+schema — not at individual subgraph files.
+
+## The schema you feed it
+
+Three artifacts, easy to mix up:
+
+| Artifact | What it is | Feed to weaver? |
+|----------|------------|-----------------|
+| **Subgraph SDL** | one service's `.graphql`, with `@key`/`@shareable`/`extend schema @link` | No — it's a fragment of the graph, and its federation directives are declared elsewhere (imported via `@link`), so plain SDL loading rejects them |
+| **Supergraph** | the composed graph, annotated with `@join__*`/`@link` machinery | Yes — self-contained (see below) |
+| **API schema** | the supergraph with federation internals stripped — exactly what the router serves and what an introspection query returns | Yes — the exact client contract |
+
+`SchemaLoader.load` (and `Client.new(path_or_sdl)`) take the supergraph or the
+API schema as an SDL file or introspection dump; or point weaver at the router
+URL to introspect the API schema live.
+
+## Pointing weaver at a supergraph
+
+A supergraph SDL works as-is. It declares its own `@join__*`/`@link` directives
+and `join__*` types, so graphql-ruby builds it; weaver reads field types and
+args, not directives, so the join plumbing is ignored; and because codegen is
+**query-driven**, the federation-internal types generate no code unless a query
+names them (none would). Field shapes — nullability, args, enums, inputs — are
+identical to the API schema, so your generated structs are correct.
+
+The one caveat: a supergraph is a **superset** of the API schema, so weaver can
+only ever **over-permit** — it will never reject a valid query, but it won't
+flag one that selects a field the API *hides*. In practice that's exactly one
+thing: `@inaccessible`.
+
+### `@inaccessible`
+
+A federation-v2 directive marking an element as *present in the federated graph
+but removed from the public API schema*. Its common use is safely rolling out a
+change to a **shared type**: add the field to one subgraph marked
+`@inaccessible` (so composition doesn't require every subgraph to have it yet),
+roll it out to the rest, then drop the directive to publish it. (Apollo
+contracts also pair `@tag` + `@inaccessible` to build filtered API variants.)
+It's a fed-v2 feature — common in mature, multi-team graphs with lots of shared
+types, rare in small or young ones, and targeted where present (a handful of
+elements, not every field).
+
+Reading the raw supergraph, weaver would let you select an `@inaccessible`
+field — but the router serves the API schema and rejects it at runtime (a
+"field doesn't exist" error, surfaced as [`QueryError` / `schema_stale?`](errors.md)).
+So the gap is narrow (you'd have to query a hidden field on purpose) and fails
+loudly, not silently.
+
+One grep says whether it affects you at all:
+
+```sh
+grep -c '@inaccessible' supergraph.graphql
+```
+
+Zero, and the supergraph *is* the API schema for weaver's purposes — feed it
+directly.
+
+Other federation directives hide nothing from the schema:
+`@requiresScopes` / `@policy` / `@authenticated` keep the field and enforce
+access at runtime; `@tag` / `@requires` / `@provides` / `@external` are metadata
+weaver ignores.
+
+## The exact contract: the API schema
+
+To make codegen match the router precisely (no over-permit), feed weaver the
+**API schema** instead of the raw supergraph. Deriving it is a *subtraction*
+from the composed graph — not composition — done with Apollo's tooling:
+
+```sh
+rover supergraph compose --config supergraph.yaml > supergraph.graphql
+```
+
+```js
+// then, in JS, strip to the API schema:
+import { Supergraph } from '@apollo/federation-internals';
+import { printSchema } from 'graphql';
+
+const api = Supergraph.fromString(supergraphSdl).apiSchema().toGraphQLJSSchema();
+process.stdout.write(printSchema(api));   // api.graphql — feed this to weaver
+```
+
+Check the API SDL in (many teams already emit it in CI) and point weaver at it:
+codegen then validates against exactly what clients can query, with no live
+gateway involved.
+
+## Which to use
+
+- **No `@inaccessible`** → point weaver at the supergraph and move on.
+- **Uses `@inaccessible`, and you want codegen to catch hidden-field mistakes** →
+  feed the derived API schema (above), or introspect the live router.
+
+A large real supergraph carries more constructs than a toy one (interface
+objects via `@join__type(isInterfaceObject:)`, `@join__unionMember`, enum join
+directives). The mechanism holds, but the honest check is to run codegen against
+your actual composed schema plus a couple of representative queries before
+relying on it.

data/docs/scalars.md

@@ -155,7 +155,7 @@ module PetHelpers
   def display_name = adult? ? "#{name} 🦴" : "#{name} 🐶"
 end
 
-GraphWeaver.register_type("Pet", PetHelpers)   # or api.register_type(...)
+GraphWeaver.extend_type("Pet", PetHelpers)   # or api.extend_type(...)
 
 pet.display_name   # => "Shelby 🦴"
 pet.name           # => "Shelby" — the wire value stays honest
@@ -173,7 +173,7 @@ For quick decoration, build the mixin inline — the block is
 `GraphWeaver::TypeHelpers` so generated files can reference it:
 
 ```ruby
-api.register_type("Pet") do
+api.extend_type("Pet") do
   def display_name = "#{name} 🐶"
 end
 ```

data/lib/graph_weaver/client.rb

@@ -101,8 +101,8 @@ class GraphWeaver::Client
   # Client-scoped type helpers: include app-owned modules into every
   # struct this client generates from the named GraphQL type — pass
   # modules, or a block to build one inline. Additive with global
-  # registrations (see GraphWeaver.register_type).
-  def register_type(graphql_name, *mixins, requires: nil, &block)
+  # registrations (see GraphWeaver.extend_type).
+  def extend_type(graphql_name, *mixins, requires: nil, &block)
     validate_registration!("type", graphql_name.to_s)
     entry = @types[graphql_name.to_s] ||= { mixins: [], requires: [] }
     GraphWeaver::Codegen.add_type_helpers(entry, graphql_name, mixins, requires, block)

data/lib/graph_weaver/codegen/enum_type.rb

@@ -90,19 +90,19 @@ class GraphWeaver::Codegen
     # Attach app-owned helper modules to every struct generated from a
     # GraphQL type — the logic stays in your code, generation wires it in:
     #
-    #      GraphWeaver.register_type("Pet", PetHelpers)
+    #      GraphWeaver.extend_type("Pet", PetHelpers)
     #
     # Or build the mixin inline — the block is module_eval'd into a fresh
     # module auto-named GraphWeaver::TypeHelpers::<Type>. Handy for quick
     # decoration; srb tc can't see into block-defined methods, so prefer
     # a named module where static checking matters:
     #
-    #      GraphWeaver.register_type("Pet") do
+    #      GraphWeaver.extend_type("Pet") do
     #        def display_name = "#{name} the pet"
     #      end
     #
     # Additive: repeated registrations (and client-scoped ones) stack.
-    def register_type(graphql_name, *mixins, requires: nil, &block)
+    def extend_type(graphql_name, *mixins, requires: nil, &block)
       entry = type_registry[graphql_name.to_s] ||= { mixins: [], requires: [] }
       add_type_helpers(entry, graphql_name, mixins, requires, block)
     end
@@ -111,7 +111,7 @@ class GraphWeaver::Codegen
       @type_registry ||= {}
     end
 
-    # shared with Client#register_type: build/validate the mixins and
+    # shared with Client#extend_type: build/validate the mixins and
     # append them to a registry entry
     def add_type_helpers(entry, graphql_name, mixins, requires, block)
       mixins = mixins.dup
@@ -143,7 +143,7 @@ class GraphWeaver::Codegen
 end
 
 module GraphWeaver
-  # Home of block-built type helpers (register_type with a block), which
+  # Home of block-built type helpers (extend_type with a block), which
   # need constant names so generated files can reference them.
   module TypeHelpers; end
 end

data/lib/graph_weaver/codegen/nodes.rb

@@ -147,7 +147,7 @@ class GraphWeaver::Codegen
 
     attr_reader :class_name, :fields
     # the GraphQL type this struct was generated from, and any registered
-    # helper modules to include (see Codegen.register_type)
+    # helper modules to include (see Codegen.extend_type)
     attr_accessor :graphql_type, :mixins
 
     def initialize(class_name)

data/lib/graph_weaver/codegen.rb

@@ -219,7 +219,9 @@ class GraphWeaver::Codegen
     suggestion = defined?(DidYouMean::SpellChecker) &&
       DidYouMean::SpellChecker.new(dictionary: schema.types.keys).correct(name).first
     hint = suggestion ? " — did you mean '#{suggestion}'?" : ""
-    raise GraphWeaver::Error, "register_#{kind}(#{name.inspect}) matches no type in this schema#{hint}"
+    # the type registry is reached via extend_type; scalars/enums via register_*
+    method = kind == "type" ? "extend_type" : "register_#{kind}"
+    raise GraphWeaver::Error, "#{method}(#{name.inspect}) matches no type in this schema#{hint}"
   end
 
   # Structured shape for a schema-validation error: message plus its first

data/lib/graph_weaver/errors.rb

@@ -1,4 +1,4 @@
-# typed: true
+# typed: strict
 # frozen_string_literal: true
 
 require "sorbet-runtime"
@@ -12,16 +12,20 @@ module GraphWeaver
   # structured failures to users. One subclass per failure site —
   # {TransportError} (never reached the server), {ServerError} (non-2xx),
   # {QueryError} (GraphQL-level errors), {TypeError} (response wouldn't
-  # cast), {ValidationError} (build time) — each merging its specifics
-  # into #to_h.
+  # cast), {InputError} (bad variables), {ValidationError} (build time) —
+  # each merging its specifics into #to_h.
   class Error < StandardError
+    extend T::Sig
+
     # every GraphWeaver error surfaces on the logger too (see
     # GraphWeaver.logger) — construction here means a raise
+    sig { params(args: T.untyped).void }
     def initialize(*args)
       super
       GraphWeaver.log(:warn) { "#{self.class.name}: #{message}" }
     end
 
+    sig { overridable.returns(T::Hash[String, T.untyped]) }
     def to_h
       { "error" => self.class.name, "message" => message }
     end
@@ -31,12 +35,17 @@ module GraphWeaver
   # TLS handshake, timeout. The original exception is preserved as #cause.
   # Generally retriable.
   class TransportError < Error
+    extend T::Sig
+
+    sig { override.returns(T::Hash[String, T.untyped]) }
     def to_h
       super.merge("cause" => cause&.class&.name)
     end
   end
 
   class << self
+    extend T::Sig
+
     # The exception classes the bundled transports reclassify as
     # TransportError — network-level failures where the request never
     # reached the server. A mutable Set: each transport contributes its own
@@ -48,11 +57,16 @@ module GraphWeaver
     #
     # SystemCallError covers every Errno::* (connection refused/reset, host
     # unreachable); SocketError covers DNS.
+    sig { returns(T::Set[T.class_of(Exception)]) }
     def transport_errors
-      @transport_errors ||= Set[SocketError, SystemCallError, IOError]
+      @transport_errors ||= T.let(
+        Set[SocketError, SystemCallError, IOError],
+        T.nilable(T::Set[T.class_of(Exception)]),
+      )
     end
 
     # Add one or more exception classes to the transport-error set.
+    sig { params(classes: T.class_of(Exception)).returns(T::Array[T.class_of(Exception)]) }
     def register_transport_error(*classes)
       transport_errors.merge(classes)
       classes
@@ -63,8 +77,15 @@ module GraphWeaver
   # that exploded, a 502 from a proxy, a 401, etc. Distinct from a GraphQL
   # error: we got an HTTP response, it just wasn't success.
   class ServerError < Error
-    attr_reader :status, :body
+    extend T::Sig
 
+    sig { returns(Integer) }
+    attr_reader :status
+
+    sig { returns(T.untyped) }
+    attr_reader :body
+
+    sig { params(status: Integer, body: T.untyped).void }
     def initialize(status:, body: nil)
       @status = status
       @body = body
@@ -72,6 +93,7 @@ module GraphWeaver
       super("HTTP #{status}#{snippet}")
     end
 
+    sig { override.returns(T::Hash[String, T.untyped]) }
     def to_h
       super.merge("status" => status)
     end
@@ -81,16 +103,38 @@ module GraphWeaver
   # object (not raised) — the response envelope and QueryError carry these.
   # Match on #code (extensions["code"]) rather than the message string.
   class GraphQLError
-    attr_reader :message, :locations, :path, :extensions
+    extend T::Sig
+
+    sig { returns(String) }
+    attr_reader :message
+
+    sig { returns(T::Array[T.untyped]) }
+    attr_reader :locations
 
+    sig { returns(T.nilable(T::Array[T.untyped])) }
+    attr_reader :path
+
+    sig { returns(T::Hash[String, T.untyped]) }
+    attr_reader :extensions
+
+    sig do
+      params(
+        message: String,
+        locations: T::Array[T.untyped],
+        path: T.nilable(T::Array[T.untyped]),
+        extensions: T::Hash[String, T.untyped],
+        type: T.nilable(String),
+      ).void
+    end
     def initialize(message:, locations: [], path: nil, extensions: {}, type: nil)
       @message = message
       @locations = locations
       @path = path
       @extensions = extensions
-      @error_type = type
+      @error_type = T.let(type, T.nilable(String))
     end
 
+    sig { params(hash: T::Hash[String, T.untyped]).returns(GraphQLError) }
     def self.from_h(hash)
       new(
         message: hash["message"] || "(no message)",
@@ -105,6 +149,7 @@ module GraphWeaver
     # branch on. Read from extensions.code (the Apollo/spec-adjacent
     # convention) or a top-level "type" (GitHub's dialect: NOT_FOUND,
     # FORBIDDEN). nil when the server sent neither.
+    sig { returns(T.nilable(String)) }
     def code
       extensions["code"] || @error_type
     end
@@ -113,11 +158,15 @@ module GraphWeaver
     # (unknown field/type/argument). Heuristic by necessity: only Apollo
     # sets a standard code (GRAPHQL_VALIDATION_FAILED); graphql-ruby and
     # GitHub speak in messages.
-    VALIDATION_MESSAGE = /doesn't exist|Cannot query field|Unknown (field|type|argument)|isn't defined|undefined (field|type)/i
+    VALIDATION_MESSAGE = T.let(
+      /doesn't exist|Cannot query field|Unknown (field|type|argument)|isn't defined|undefined (field|type)/i,
+      Regexp,
+    )
 
     # True when this error looks like the server rejected the query's
     # shape — for a generated module that usually means the schema
     # changed after generation.
+    sig { returns(T::Boolean) }
     def validation?
       code == "GRAPHQL_VALIDATION_FAILED" || VALIDATION_MESSAGE.match?(message)
     end
@@ -126,17 +175,21 @@ module GraphWeaver
     # indices stripped — ["people", 3, "email"] => "people.email". The
     # parseable key for grouping/reporting (the raw #path keeps indices).
     # nil for global errors with no path.
+    sig { returns(T.nilable(String)) }
     def field
-      return unless path
+      p = path
+      return unless p
 
-      named = path.reject { |seg| seg.is_a?(Integer) || seg.to_s.match?(/\A\d+\z/) }
+      named = p.reject { |seg| seg.is_a?(Integer) || seg.to_s.match?(/\A\d+\z/) }
       named.join(".") unless named.empty?
     end
 
+    sig { returns(String) }
     def to_s
-      loc = locations&.first
+      loc = locations.first
       at = loc ? " at #{loc["line"]}:#{loc["column"]}" : ""
-      where = path ? " (path: #{path.join(".")})" : ""
+      p = path
+      where = p ? " (path: #{p.join(".")})" : ""
       tag = code ? " [#{code}]" : ""
       "#{message}#{at}#{where}#{tag}"
     end
@@ -144,6 +197,7 @@ module GraphWeaver
     # JSON-ready: the problematic field (both forms — #field for grouping,
     # #path with indices for exact location), the machine code, and the
     # server's full extensions.
+    sig { returns(T::Hash[String, T.untyped]) }
     def to_h
       {
         "message" => message,
@@ -158,15 +212,18 @@ module GraphWeaver
   end
 
   # Shared filtering over a collection of GraphQLErrors, for surfacing
-  # field-level failures programmatically. Host must define #errors.
+  # field-level failures programmatically. Host must define #errors / #data.
   module ErrorFiltering
+    extend T::Sig
     include Kernel # for sorbet: hosts are Objects
 
     # the host's interface, overridden by its attr_readers
+    sig { overridable.returns(T::Array[GraphQLError]) }
     def errors
       raise NotImplementedError, "#{self.class} must define #errors"
     end
 
+    sig { overridable.returns(T.untyped) }
     def data
       raise NotImplementedError, "#{self.class} must define #data"
     end
@@ -174,15 +231,20 @@ module GraphWeaver
     # Errors touching a field path — "user.email" or ["user", "email"];
     # prefix match, so deeper errors count too. List indices appear as
     # path segments ("people.0.email").
+    sig { params(path: T.any(String, T::Array[T.untyped])).returns(T::Array[GraphQLError]) }
     def errors_at(path)
       want = (path.is_a?(String) ? path.split(".") : path).map(&:to_s)
-      errors.select { |error| error.path && error.path.map(&:to_s).first(want.size) == want }
+      errors.select do |error|
+        p = error.path
+        p && p.map(&:to_s).first(want.size) == want
+      end
     end
 
     # True when any error looks like the server rejected the query's
     # shape — the schema has likely changed since the module was
     # generated. Refresh the schema dump and regenerate (rake
     # graph_weaver:schema:refresh && rake graph_weaver:generate).
+    sig { returns(T::Boolean) }
     def schema_stale?
       errors.any?(&:validation?)
     end
@@ -193,25 +255,31 @@ module GraphWeaver
     #      response.each_error do |field, errors|
     #        form.add_error(field, errors.map(&:message))
     #      end
+    sig { returns(T::Hash[T.nilable(String), T::Array[GraphQLError]]) }
     def errors_by_field
       errors.group_by(&:field)
     end
 
+    sig do
+      params(block: T.proc.params(field: T.nilable(String), errors: T::Array[GraphQLError]).void).void
+    end
     def each_error(&block)
-      errors_by_field.each(&block)
+      errors_by_field.each { |field, errs| block.call(field, errs) }
     end
 
     # The id of the record an error points into, resolved by walking the
     # error's path through the (partial) typed data: an error at
     # ["people", 3, "email"] resolves to people[3].id. nil when the data
     # is missing, the path doesn't walk, or the record has no id field.
+    sig { params(error: GraphQLError).returns(T.untyped) }
     def entity_id(error)
       # untyped by nature: the walk traverses whatever structs this query
       # generated, reassigning across types at each step
       node = T.let(data, T.untyped)
-      return unless node && error.path
+      path = error.path
+      return unless node && path
 
-      error.path[0..-2].each do |segment|
+      (path[0..-2] || []).each do |segment|
         node = if segment.is_a?(Integer) || segment.to_s.match?(/\A\d+\z/)
           node.is_a?(Array) ? node[segment.to_i] : nil
         else
@@ -230,6 +298,7 @@ module GraphWeaver
     #
     #      { "people.email" => { "messages" => [...], "codes" => [...],
     #        "entity_ids" => ["7", "9"], "errors" => [full to_h...] } }
+    sig { returns(T::Hash[T.nilable(String), T::Hash[String, T.untyped]]) }
     def report
       errors_by_field.to_h do |field, field_errors|
         [field, {
@@ -247,10 +316,25 @@ module GraphWeaver
   # Carries the structured errors, any partial data, and top-level
   # extensions (cost/throttle metadata).
   class QueryError < Error
+    extend T::Sig
     include ErrorFiltering
 
-    attr_reader :errors, :data, :extensions
+    sig { override.returns(T::Array[GraphQLError]) }
+    attr_reader :errors
+
+    sig { override.returns(T.untyped) }
+    attr_reader :data
 
+    sig { returns(T::Hash[String, T.untyped]) }
+    attr_reader :extensions
+
+    sig do
+      params(
+        errors: T::Array[GraphQLError],
+        data: T.untyped,
+        extensions: T::Hash[String, T.untyped],
+      ).void
+    end
     def initialize(errors, data: nil, extensions: {})
       @errors = errors
       @data = data
@@ -259,12 +343,14 @@ module GraphWeaver
     end
 
     # All non-nil error codes — handy for `codes.include?("THROTTLED")`.
+    sig { returns(T::Array[String]) }
     def codes
-      errors.map(&:code).compact
+      errors.filter_map(&:code)
     end
 
     # The machine side: every error with its path/code/extensions, plus
     # the drift verdict — nest this straight into a JSON response.
+    sig { override.returns(T::Hash[String, T.untyped]) }
     def to_h
       super.merge(
         "schema_stale" => schema_stale?,
@@ -276,6 +362,7 @@ module GraphWeaver
 
     private
 
+    sig { returns(String) }
     def summary
       first = errors.first
       more = errors.size > 1 ? " (and #{errors.size - 1} more)" : ""
@@ -291,30 +378,69 @@ module GraphWeaver
   # #cause carries the original TypeError/KeyError with the offending
   # prop in its message.
   class TypeError < Error
+    extend T::Sig
+
+    sig { returns(T.untyped) }
     attr_reader :struct
 
+    sig { params(struct: T.untyped, error: T.nilable(Exception), message: T.nilable(String)).void }
     def initialize(struct:, error: nil, message: nil)
       @struct = struct
       super("failed to cast response into #{struct}: #{message || error&.message}")
     end
 
+    sig { override.returns(T::Hash[String, T.untyped]) }
     def to_h
       super.merge("struct" => struct.to_s, "cause" => cause&.message)
     end
   end
 
+  # Raised when the variables passed to a query or mutation can't be built
+  # into the generated input structs — an unknown or typo'd input key, a
+  # missing required input field, an out-of-range enum, or a wrong-typed
+  # field. This is the "the caller's input was invalid" error: rescue it at
+  # an API boundary to return a 422. #field names the offending input field
+  # when known, #struct the input type being built; the underlying
+  # TypeError/KeyError/ArgumentError is preserved as #cause.
+  class InputError < Error
+    extend T::Sig
+
+    sig { returns(T.nilable(String)) }
+    attr_reader :field
+
+    sig { returns(T.untyped) }
+    attr_reader :struct
+
+    sig { params(message: String, field: T.nilable(String), struct: T.untyped).void }
+    def initialize(message, field: nil, struct: nil)
+      @field = field
+      @struct = struct
+      super(message)
+    end
+
+    sig { override.returns(T::Hash[String, T.untyped]) }
+    def to_h
+      super.merge("field" => field, "struct" => struct&.to_s).compact
+    end
+  end
+
   # Build-time: the query didn't validate against the schema. Carries the
   # structured validation errors (message + line/column) rather than a
   # joined string. Under the Error umbrella like everything else raised
   # here (through 0.1.0 it was an ArgumentError instead).
   class ValidationError < Error
+    extend T::Sig
+
+    sig { returns(T::Array[T::Hash[Symbol, T.untyped]]) }
     attr_reader :errors
 
+    sig { params(errors: T::Array[T::Hash[Symbol, T.untyped]]).void }
     def initialize(errors)
       @errors = errors
       super("invalid query: #{errors.map { |e| e[:message] }.join("; ")}")
     end
 
+    sig { override.returns(T::Hash[String, T.untyped]) }
     def to_h
       super.merge("errors" => errors.map { |e| e.transform_keys(&:to_s) })
     end

data/lib/graph_weaver/hints.rb

@@ -3,6 +3,7 @@
 
 require "sorbet-runtime"
 
+require_relative "errors"
 require_relative "inflect"
 
 module GraphWeaver
@@ -32,7 +33,11 @@ module GraphWeaver
         end
         suggestion ? "#{key} (did you mean '#{suggestion}'?)" : key
       end
-      raise ArgumentError, "unknown key(s) for #{struct}: #{hints.join(", ")}"
+      raise GraphWeaver::InputError.new(
+        "unknown key(s) for #{struct}: #{hints.join(", ")}",
+        field: unknown.join(", "),
+        struct: struct,
+      )
     end
 
     def method_missing(name, *args, &block)

data/lib/graph_weaver/input_struct.rb

@@ -3,6 +3,7 @@
 
 require "sorbet-runtime"
 
+require_relative "errors"
 require_relative "hints"
 
 module GraphWeaver
@@ -53,6 +54,13 @@ module GraphWeaver
           raw = value.key?(field.prop) ? value[field.prop] : value[field.prop.to_s]
           [field.prop, raw.nil? || field.coercer.nil? ? raw : field.coercer.call(raw)]
         end)
+      rescue GraphWeaver::InputError
+        raise # already contextualized by a nested input / enum coercion
+      rescue ::TypeError, ::ArgumentError, KeyError => e
+        # a wrong-typed field, a missing required field, or an out-of-range
+        # enum — surface one branded, structured error for a 422. (`::` so the
+        # rescue catches Ruby's TypeError, not GraphWeaver::TypeError.)
+        raise GraphWeaver::InputError.new("invalid input for #{self}: #{e.message}", struct: self)
       end
     end
   end

data/lib/graph_weaver/response.rb

@@ -19,10 +19,10 @@ module GraphWeaver
 
     Data = type_member
 
-    sig { returns(T.nilable(Data)) }
+    sig { override.returns(T.nilable(Data)) }
     attr_reader :data
 
-    sig { returns(T::Array[GraphWeaver::GraphQLError]) }
+    sig { override.returns(T::Array[GraphWeaver::GraphQLError]) }
     attr_reader :errors
 
     sig { returns(T::Hash[String, T.untyped]) }

data/lib/graph_weaver/version.rb

@@ -1,3 +1,3 @@
 module GraphWeaver
-  VERSION = "0.2.2"
+  VERSION = "0.3.0"
 end

data/lib/graph_weaver.rb

@@ -285,19 +285,19 @@ module GraphWeaver
     # GraphQL type — derived values live as methods next to the honest
     # wire data, and srb tc checks them against each query's selection:
     #
-    #      GraphWeaver.register_type("Pet", PetHelpers)
+    #      GraphWeaver.extend_type("Pet", PetHelpers)
     #
     # Or build the mixin inline with a block (module_eval'd into an
     # auto-named module — quick, but invisible to srb tc):
     #
-    #      GraphWeaver.register_type("Pet") do
+    #      GraphWeaver.extend_type("Pet") do
     #        def display_name = "#{name} the pet"
     #      end
     #
     # Additive (repeated and client-scoped registrations stack). Global;
-    # client.register_type scopes to one client.
-    def register_type(graphql_name, *mixins, requires: nil, &block)
-      Codegen.register_type(graphql_name, *mixins, requires:, &block)
+    # client.extend_type scopes to one client.
+    def extend_type(graphql_name, *mixins, requires: nil, &block)
+      Codegen.extend_type(graphql_name, *mixins, requires:, &block)
     end
 
     # Restore the built-in scalars, dropping every custom registration —

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: graph_weaver
 version: !ruby/object:Gem::Version
-  version: 0.2.2
+  version: 0.3.0
 platform: ruby
 authors:
 - Daniel Pepper
@@ -227,6 +227,7 @@ extra_rdoc_files: []
 files:
 - ".yardopts"
 - CHANGELOG.md
+- CLAUDE.md
 - Gemfile
 - Gemfile.lock
 - LICENSE.txt
@@ -236,6 +237,7 @@ files:
 - README.md
 - docs/cassettes.md
 - docs/errors.md
+- docs/federation.md
 - docs/generated_modules.md
 - docs/getting_started.md
 - docs/logging.md