graph_weaver 0.3.0 → 0.4.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e66ac94243bdc7f065534845a722bfd209c8d7b23a3a5fa1eff6041e3f563655
-  data.tar.gz: 413217dbda71c297abe537dc996b8e8413821365d9e966493bf7301d6351a6c7
+  metadata.gz: fac36591b869f046295946094078847ed33a1aa15aa8a2402e6a46f6e17ebaa0
+  data.tar.gz: c366d845da86029839f57214ba6216b78f2a870b67873851c2514d3d00aaa78d
 SHA512:
-  metadata.gz: 62dab00fca85973dbff0e695dcd9970a554ca98b6a717a375fa7f2cde349b2967672ce541bf108d3b058b54b47ce7d274f6c8f11f069360a59e95fcb86ff8ae5
-  data.tar.gz: 3a11e52459c3b0158d831c8815ced9c4ca5cd323435ffac4e36a8648e83179dd87763a4570aaa56b240d0d7d77d3b91e43d1706f40112d3eae2fa608950b797c
+  metadata.gz: 37c814f83659a3189407b4c8e4531db4782fc4f38cd0e62df4f8e473a75c713adc3d0bb43de62a51854c1d6f0aeea1195e89848e83bd61c74018a840bfe56924
+  data.tar.gz: 787508b524cb027fb31281379f64bc566b1bb23709a79883928005ced38cf478c6c90b62a09d2de66317a6d7415eea77014667a5f543472a6f42d8ad043634de

data/CHANGELOG.md

@@ -1,3 +1,91 @@
+###  v0.4.4  (2026-07-30)
+- Supergraph loading now derives the **API schema**: `@inaccessible` elements
+  (present in the federated graph but hidden from what the router serves) are
+  removed on load, cascading — a field/argument/union-member/interface
+  referencing a removed type goes too, and a type left empty is removed in turn.
+  So codegen validates against exactly what clients can query, with no
+  over-permitting and no Apollo JS tooling to subtract the API schema first.
+  Plain (non-federation) SDL is untouched.
+
+###  v0.4.3  (2026-07-30)
+- Federation-aware supergraph loading: `SchemaLoader` (and `Client.new`) now
+  load a composed Apollo Federation v2 supergraph SDL directly. When the `@join__*`
+  markers are present it strips the composition machinery — the synthetic
+  `join__*`/`link__*` types and directive definitions, and every `@join__*`/`@link`
+  application — via an AST rewrite before `from_definition`, so the merged type
+  shapes load cleanly with nothing federation-internal leaking into
+  `schema.types`. Plain SDL is untouched. A query can now be typed against the
+  composed supergraph, not just per-subgraph schema objects.
+- Removed `directive_defaults_patch.rb` (the graphql-ruby monkeypatch); the
+  preprocessor supersedes it and `graphql-ruby` fixed the underlying issue. The
+  gem now requires `graphql >= 2.6.7`.
+
+###  v0.4.2  (2026-07-30)
+- `extend_type` accepts `alias:` — project a selected field (possibly nested)
+  onto a flat, typed accessor emitted into the struct body:
+  `extend_type("Widget", alias: { tag: "meta.tag" })` generates a sig'd
+  `def tag = meta&.tag`. Retires hand-written value objects that only flattened
+  a passthrough field. Takes a `{ name => path }` hash, a bare path string
+  (accessor named after the last segment), or an array of paths. Typed from the
+  selection — a nullable hop makes the accessor nilable and nil-safe; the leaf
+  may be a scalar, enum, or nested struct. Validated per query at generation: an
+  unselected/misspelled segment (with `did you mean`), a list hop, or a name
+  collision raises. Stacks and is client-scopable like the mixin forms.
+
+###  v0.4.1  (2026-07-29)
+- Generated `execute!` forwards its kwargs to `execute` via hash shorthand
+  (`execute(client, name:, species:)` rather than `name: name, species: species`)
+  — cosmetic only. Regenerate to refresh (`verify` flags the drift otherwise).
+
+###  v0.4.0  (2026-07-28)
+- Shared unions: when a named shared fragment is the whole selection on a union
+  field (`feed { ...FeedItemFields }`), its type is hoisted once into a
+  `GraphQLUnions` module and every query that spreads it aliases the same type —
+  so a union selected across many queries is one Ruby type family (one
+  exhaustive `case … T.absurd`), not a fresh dispatch module per query. No flag:
+  the shared fragment is the opt-in. Triggers only for an exact lone spread;
+  mixing other fields, or shadowing with a query-local fragment, keeps the union
+  inlined. Module name derives from the output path (override with
+  `GraphWeaver.unions_module=`); dynamic `parse` still inlines.
+- Removed the `shared_inputs:` option from `generate!` / `verify_generated!`.
+  Directory-based generation always emits each input type once into a shared
+  module — the self-contained-module opt-out added complexity for little value.
+  Single-query `parse` / `Codegen.generate` still inline their types (there's
+  no set to share against). Only affects callers who passed
+  `shared_inputs: false`.
+
+###  v0.3.4  (2026-07-29)
+- Shared fragments: define reusable named fragments once (default
+  `app/graphql/fragments`, configurable via `GraphWeaver.fragments_paths`) and
+  spread them from any query. Each query inlines only the fragments it
+  transitively spreads, so the sent query stays self-contained. Fragment files
+  hold only fragments; names are unique across them. Works in `generate!` and
+  dynamic `parse`.
+
+###  v0.3.3  (2026-07-29)
+- Union member-type dedup: a union selected more than once on a struct now
+  collapses to one Ruby type family instead of a distinct per-field family with
+  identical members — so a consumer gets a single exhaustive
+  `case … T.absurd` across every field of that union. Structurally different
+  selections stay distinct types. (First cut: same-struct siblings; regenerate
+  checked-in modules to pick it up.)
+
+###  v0.3.2  (2026-07-29)
+- `register_scalar` accepts a `Type.field` coordinate to override how one
+  field's scalar deserializes — so the same scalar can be different Ruby types
+  across fields (`register_scalar("User.birthday", Date)` while
+  `ISO8601DateTime` stays a `Time` elsewhere). Field overrides win over the
+  scalar-name registration; both stack global-then-client. The coordinate is
+  validated against the schema (a typo'd or non-scalar field raises). Same
+  method, same signature — a `.` in the name selects the field form.
+
+###  v0.3.1  (2026-07-28)
+- `GraphWeaver.extend_t_sig` controls whether generated modules/structs emit
+  `extend T::Sig`. Default (`nil`) auto-detects a global T::Sig injection
+  (`class Module; include T::Sig`) and skips the now-redundant `extend` — so
+  generated code stays clean under rubocop's `Sorbet/RedundantExtendTSig`.
+  Force with `true`/`false`; `false` requires the global include.
+
 ###  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

data/CLAUDE.md

@@ -26,8 +26,7 @@ where it pays off in developer experience; leave the rest at `# typed: true`.
   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).
+- `railtie.rb` / `tasks.rb` are `# typed: ignore` (Rails/Rake DSL).
 
 ## Design invariants (don't "fix" these)
 

data/Gemfile.lock

@@ -1,8 +1,8 @@
 PATH
   remote: .
   specs:
-    graph_weaver (0.3.0)
-      graphql (>= 2)
+    graph_weaver (0.4.4)
+      graphql (>= 2.6.7)
       sorbet-runtime
 
 GEM
@@ -42,7 +42,7 @@ GEM
     google-protobuf (4.35.1-x86_64-linux-gnu)
       bigdecimal
       rake (~> 13.3)
-    graphql (2.6.6)
+    graphql (2.6.7)
       base64
       fiber-storage
       logger
@@ -99,16 +99,16 @@ GEM
     rubydex (0.2.7-arm64-darwin)
     rubydex (0.2.7-x86_64-darwin)
     rubydex (0.2.7-x86_64-linux)
-    simplecov (1.0.2)
-    sorbet (0.6.13347)
-      sorbet-static (= 0.6.13347)
-    sorbet-runtime (0.6.13347)
-    sorbet-static (0.6.13347-aarch64-linux)
-    sorbet-static (0.6.13347-universal-darwin)
-    sorbet-static (0.6.13347-x86_64-linux)
-    sorbet-static-and-runtime (0.6.13347)
-      sorbet (= 0.6.13347)
-      sorbet-runtime (= 0.6.13347)
+    simplecov (1.0.3)
+    sorbet (0.6.13365)
+      sorbet-static (= 0.6.13365)
+    sorbet-runtime (0.6.13365)
+    sorbet-static (0.6.13365-aarch64-linux)
+    sorbet-static (0.6.13365-universal-darwin)
+    sorbet-static (0.6.13365-x86_64-linux)
+    sorbet-static-and-runtime (0.6.13365)
+      sorbet (= 0.6.13365)
+      sorbet-runtime (= 0.6.13365)
     spoom (1.8.3)
       erubi (>= 1.10.0)
       prism (>= 0.28.0)
@@ -176,8 +176,8 @@ 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.3.0)
-  graphql (2.6.6) sha256=7438e2036b571c884377eb1529225470ba959365f26dc47152953c213bc38c31
+  graph_weaver (0.4.4)
+  graphql (2.6.7) sha256=759755ce5819c965b6459c5039605cf2e4d876bb8ba5e03451676870ea787c45
   i18n (1.15.2) sha256=00f9eb62412fe593b2a65a97daa75300d37abb8f7202ec748e94b6d46a9dd1b5
   io-console (0.8.2) sha256=d6e3ae7a7cc7574f4b8893b4fca2162e57a825b223a177b7afa236c5ef9814cc
   irb (1.18.0) sha256=de9454a0703a54704b9811a5ef31a60c86949fbf4013fcf244fabc7c775248e3
@@ -206,13 +206,13 @@ CHECKSUMS
   rubydex (0.2.7-arm64-darwin) sha256=f0d28bbf4153568be79b671642424750053e0bea971b60ddf5cec19bf4563990
   rubydex (0.2.7-x86_64-darwin) sha256=b002b259d118ac69de44470eff1597143318402c45630c47371f9542631447dc
   rubydex (0.2.7-x86_64-linux) sha256=dacfade9fa42ce4469618da6dac07e69d5f3ac6a313b4caced5234c8f052419a
-  simplecov (1.0.2) sha256=c6459434efe4b948b46477cc2df2faa73ab365f83a33c7c17f81262f4f7f1244
-  sorbet (0.6.13347) sha256=2830946e6efda8dc732c5d703350bed17f437fbea1ccfbef543a65e33ae445c1
-  sorbet-runtime (0.6.13347) sha256=54e7221d9f4b63f58aec79f3043752a9ba7810347c6ae0d903531591cc2d5f01
-  sorbet-static (0.6.13347-aarch64-linux) sha256=9bb60509bf9a8715d93e77cd55f96659575d81a5f47b52bd4f66b3dfe6f2182e
-  sorbet-static (0.6.13347-universal-darwin) sha256=d12678a45369dba9db724103d8badda995e66a83ae35798f68d804c46a6d3e45
-  sorbet-static (0.6.13347-x86_64-linux) sha256=5a4803d2ba4fc1964e23f3aa4073b224c345c2a72a5f5317623a4bae7ce2c8da
-  sorbet-static-and-runtime (0.6.13347) sha256=2130e3c20326948a3edd20385b444345cb7327eea9b141f373486e7c087a498d
+  simplecov (1.0.3) sha256=38ef0514f16ae7562f0d0f4df02610071115103d301b6de7dacbcc000082e39b
+  sorbet (0.6.13365) sha256=3a642fe7afb031ad670c2e6161b3d5492dd67705cbcafb132c9e87ded7ccf676
+  sorbet-runtime (0.6.13365) sha256=0657cddfd2319c9695a0b6e13aa7a7c7b093149e5589448c03b911adf1e243cb
+  sorbet-static (0.6.13365-aarch64-linux) sha256=14b7bf3a227ee102c119763158618bc6b677994cebfda2705b94bca56e4c25e1
+  sorbet-static (0.6.13365-universal-darwin) sha256=0f6033dde8a0dc7b7e72ada3ce73e1e3097843be16e473fb8bb2b8fb6199212b
+  sorbet-static (0.6.13365-x86_64-linux) sha256=f94daadcae55f2e0f7797f8fdc8a250c89ec62e11f2d41905ed6fb1e60ff708e
+  sorbet-static-and-runtime (0.6.13365) sha256=9768c114686f7cac0a6f2e222db4213887d294df6059802242ba6e4e08adbad9
   spoom (1.8.3) sha256=32871fa189bbfa49cf557a50f819f23cc9a6ceefd0346caa7a6adc193becd5dd
   tapioca (0.19.2) sha256=938731b07811aee8d23871b1aee8861d464fbaf2cfffbf79a62b0c869a5120ec
   thor (1.5.0) sha256=e3a9e55fe857e44859ce104a84675ab6e8cd59c650a49106a05f55f136425e73

data/docs/federation.md

@@ -20,17 +20,20 @@ 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`.
+A supergraph SDL works as-is. When `SchemaLoader` sees the `@join__*` markers it
+strips the composition machinery before building the schema — the synthetic
+`join__*`/`link__*` types and directive definitions, and every `@join__*`/`@link`
+application on the real types — so what codegen sees is the merged graph's
+ordinary type shapes, with no federation plumbing leaking into `schema.types`.
+(It's a pure AST rewrite of the SDL; no graphql-ruby monkeypatch, and plain
+schemas pass through untouched.) Field shapes — nullability, args, enums,
+inputs — are identical to the API schema, so your generated structs are correct;
+and because codegen is **query-driven**, nothing federation-internal could
+generate code anyway.
+
+A supergraph is a **superset** of the API schema — it carries elements the
+public API hides, marked `@inaccessible`. Weaver removes those on load (below),
+so the schema it generates against is the API schema, not the superset.
 
 ### `@inaccessible`
 
@@ -44,57 +47,32 @@ It's a fed-v2 feature — common in mature, multi-team graphs with lots of share
 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.
+Weaver derives the API schema from the supergraph for you: loading strips every
+`@inaccessible` element and cascades — a field/argument/union-member/interface
+referencing a removed type goes too, and a type left empty is removed in turn —
+so codegen validates against **exactly** what clients can query. There's no
+over-permit gap, and no need for Apollo's JS tooling (`@apollo/federation-internals`)
+to subtract the API schema first; feed weaver the raw supergraph and you get the
+router's contract. (This is a pure SDL rewrite at load time — see
+[`SchemaLoader`](../lib/graph_weaver/schema_loader.rb).)
 
-One grep says whether it affects you at all:
+Other federation directives hide nothing from the schema, so weaver keeps the
+field and ignores the directive: `@requiresScopes` / `@policy` / `@authenticated`
+enforce access at runtime; `@tag` / `@requires` / `@provides` / `@external` are
+metadata.
 
-```sh
-grep -c '@inaccessible' supergraph.graphql
-```
+## Which schema to feed
 
-Zero, and the supergraph *is* the API schema for weaver's purposes — feed it
-directly.
+Any of these — they all produce the same generated code:
 
-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.
+- **The supergraph SDL** — weaver strips the `@join__*`/`@link` machinery and
+  derives the API schema (removing `@inaccessible`). The common case.
+- **The API schema SDL** — already subtracted (e.g. emitted in your CI); loads
+  as an ordinary schema.
+- **The live router** — introspect it; it already serves the API schema.
 
 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.
+directives). The stripping holds across them, 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/generated_modules.md

@@ -210,9 +210,8 @@ emitted **once per schema** — one file per type under
 named from the output path: the conventional layout gets
 `GraphQLInputs`, while a multi-schema layout names each schema's module
 after its directory (`app/graphql/github/generated` → `GithubInputs`).
-Override globally with `GraphWeaver.inputs_module=` or per run with
-`generate!(inputs_module:)`; opt out with
-`generate!(shared_inputs: false)`. Per-type files keep schema drift
+Override the module name globally with `GraphWeaver.inputs_module=` or per run
+with `generate!(inputs_module:)`. Per-type files keep schema drift
 reviewable: a migration diffs exactly the types it touched, and types
 the schema drops are pruned on regeneration (`verify` flags strays).
 Query modules alias what they touch,
@@ -254,7 +253,11 @@ mod.execute!(where:)
   interface-level fields only → one shared struct; a single `... on X`
   condition and nothing else → `X`'s struct, always nilable — a
   non-matching runtime type comes back as `nil`, so narrowing doubles as
-  filtering.
+  filtering. When a whole union field is selected as one named *shared*
+  fragment (`{ ...FeedItemFields }`), that type is hoisted once into the
+  `GraphQLUnions` module and each query aliases it — so the same union is one
+  Ruby type family across queries, not a fresh dispatch module per query. Like
+  shared inputs, it's a `generate!`-directory concern; dynamic `parse` inlines.
 - **`@skip` / `@include`** — a directive-conditional field may be absent from
   the response regardless of schema nullability, so its generated type is
   always nilable.
@@ -267,6 +270,39 @@ mode) the struct raises a NoMethodError naming the prop that does exist —
 `use 'name_with_owner'` for the exact wire name, `did you mean ...?` for
 a near-miss typo in either casing.
 
+### Consuming a union — dispatch on the class, not `__typename`
+
+`from_h` already reads `__typename` off the wire and builds the right member
+struct, so what you hold is a real `Book` or `Disc`, not a tag. Branch on the
+class and let Sorbet do the rest:
+
+```ruby
+items.each do |item|          # item : T.any(Result::Item::Book, Result::Item::Disc)
+  case item
+  when Result::Item::Book then item.title     # narrowed to Book — .title is available
+  when Result::Item::Disc then item.runtime   # narrowed to Disc — .runtime is available
+  else T.absurd(item)
+  end
+end
+```
+
+Two things a `case item.__typename` on the string can't give you. `when Book`
+*narrows*: inside the branch `item` is statically a `Book`, so its fields
+typecheck (a `Disc` field would be a compile error) — a string value narrows
+nothing. And after every member, the `T.any` is exhausted, so `T.absurd` asserts
+the `else` is unreachable: add a member to the union, regenerate, and the
+`T.absurd` stops compiling until you handle it. Dispatching on the string tag
+gets you neither — mistakes and schema growth fall through to a runtime raise.
+
+`__typename` is still there as a plain `String` if you want the raw tag, but you
+rarely need it to dispatch. Its one real use is the case the class can't cover:
+two *differently-selected* occurrences of the same union are distinct type
+families (`Result::Item::Book` is not `Result::FeaturedItem::Book`), so a `case`
+written for one won't span the other. To hold "the same union" as one type
+across queries, select it through a shared fragment
+([shared unions](#selections)); if all you have is the bare tag, `__typename` is
+the common denominator (but an unchecked one).
+
 ## Naming
 
 Module names derive from the operation name (`query GetPerson` → `GetPerson`);

data/docs/getting_started.md

@@ -86,6 +86,51 @@ reviewed like any other code — and never edited by hand.
 PersonQuery.execute!(id: "1").person&.name   # typed, via GraphWeaver.client
 ```
 
+### Shared fragments
+
+Define reusable fragments once and spread them from any query:
+
+```graphql
+# app/graphql/fragments/person_fields.graphql
+fragment PersonFields on Person { name birthday }
+
+# app/graphql/queries/person.graphql
+query($id: ID!) { person(id: $id) { ...PersonFields } }
+```
+
+Each query inlines only the fragments it (transitively) spreads, so the sent
+`QUERY` stays self-contained — the server never needs your fragment library.
+Fragment files hold only fragments (no operations), and names are unique across
+them. Point elsewhere with `GraphWeaver.fragments_paths` (an appendable list,
+default `app/graphql/fragments`).
+
+### Shared unions
+
+When a shared fragment *is* the whole selection on a union field, its type is
+hoisted once into a `GraphQLUnions` module and every query that spreads it
+aliases the same type — so a `union` selected across many queries becomes one
+Ruby type family, and you write one exhaustive `case … when … T.absurd` that
+works everywhere:
+
+```graphql
+# app/graphql/fragments/feed_item.graphql
+fragment FeedItemFields on FeedItem {
+  __typename
+  ... on Post { title }
+  ... on Photo { url }
+}
+
+# any query
+query { feed { ...FeedItemFields } }   # feed : T::Array[FeedItemFields::Type]
+```
+
+Hoisting is what the shared fragment buys you — there's no flag. It triggers
+only when the union field's selection is exactly that one spread (mix in other
+fields, or shadow the fragment with a query-local one of the same name, and the
+union stays inlined in that query). Named like the inputs module from the output
+path (`GraphQLUnions`, or `GithubUnions` in a multi-schema layout); override
+with `GraphWeaver.unions_module=`.
+
 ## 6. Test against fakes
 
 ```ruby
@@ -127,6 +172,13 @@ generated files — dynamic `parse` is invisible to `srb tc`. Everything
 works without Sorbet; codegen plus Sorbet is what moves type errors from
 runtime to CI.
 
+If your app globally injects `T::Sig` (`class Module; include T::Sig`), the
+per-struct `extend T::Sig` in generated files is redundant — rubocop's
+`Sorbet/RedundantExtendTSig` flags it. GraphWeaver auto-detects that at
+generation time and skips the `extend`; override with
+`GraphWeaver.extend_t_sig = true`/`false`. (Generated code is machine-generated
+and marked "do not edit," so excluding `generated/**` from rubocop is also fine.)
+
 ## Not Rails?
 
 Everything above works the same, minus the Railtie conveniences: add

data/docs/scalars.md

@@ -14,6 +14,19 @@ them: `client.register_scalar(...)` overlays the global registry for that
 client's generation only — so two servers can disagree about what a
 `DateTime` is, and neither leaks into the other.
 
+Pass a `Type.field` **coordinate** instead of a scalar name to override just
+that one field — so the same scalar can deserialize as different Ruby types
+across fields:
+
+```ruby
+GraphWeaver.register_scalar("ISO8601DateTime", Time)   # the default, everywhere
+GraphWeaver.register_scalar("User.birthday", Date)     # this field only
+```
+
+A field override wins over the scalar-name registration; both stack the same
+global-then-client way. (GraphQL names can't contain `.`, so the coordinate is
+unambiguous — and it's validated against the schema, so a typo'd field raises.)
+
 Pass a real class as `type:` and the cast/serialize are **inferred** from it by
 probing the deserialize side and pairing its serializer:
 
@@ -161,12 +174,18 @@ pet.display_name   # => "Shelby 🦴"
 pet.name           # => "Shelby" — the wire value stays honest
 ```
 
-Because the include is emitted into the generated source, `srb tc` checks
-the helpers against each query's actual selection — a helper that calls
-`birthday` on a query that never selected it is a **static error**, which
-doubles as selection-completeness checking. Registrations are additive
-(global plus client-scoped stack), and fakes/cassettes get the behavior
-automatically since it lives on the struct.
+The methods live on the struct, so they see its wire fields at runtime and
+fakes/cassettes get the behavior automatically; registrations are additive
+(global plus client-scoped stack). One caveat on *static* typing, though:
+`srb tc` checks a mixin's method bodies in the module's own scope, not the
+including struct's — so a helper that reads a wire field (`name`, `birthday`)
+doesn't resolve it and fails with "method does not exist on the module." Write
+such a helper at `# typed: false`, or reach the field through `T.unsafe(self)`
+— either way its body isn't statically checked against the selection. (Sorbet's
+`requires_ancestor` is the escape in principle, but it needs an experimental
+flag and a concrete ancestor, which a per-query struct isn't.) The only place a
+field-reading derivation type-checks natively is *inside* the struct body, where
+the field is in scope — which is codegen's job, not a mixin's.
 
 For quick decoration, build the mixin inline — the block is
 `module_eval`'d into a fresh module auto-named under
@@ -178,6 +197,43 @@ api.extend_type("Pet") do
 end
 ```
 
-Same runtime behavior, one caveat: `srb tc` can't see into block-defined
-methods, so prefer a named module where static checking matters —
-complexity on demand.
+Same runtime behavior, less static reach: the block becomes a runtime module
+with no source on disk, so `srb tc` can't see its methods at all — fine in
+dynamic `parse`, but in a checked-in `# typed: strict` file it's an unresolved
+reference. Prefer a named module (and mind the field-access caveat above) where
+static checking matters — complexity on demand.
+
+### Flat accessors with `alias:`
+
+The one derivation the generator can type for you is a plain projection — a
+selected field, possibly nested, exposed under a flat accessor. `alias:` emits a
+sig'd delegator *into the struct body*, where the field is in scope, so it's
+fully checked (the thing a mixin can't be):
+
+```ruby
+GraphWeaver.extend_type("Widget", alias: { tag: "meta.tag" })
+
+# generated on the Widget struct:
+#   sig { returns(T.nilable(String)) }
+#   def tag = meta&.tag
+```
+
+So a hand-written value object that only existed to expose `tag` flat over
+`data.dig("meta", "tag")` drops away — the generated struct answers `.tag`
+directly. Forms:
+
+```ruby
+alias: { tag: "meta.tag" }              # explicit accessor name
+alias: "meta.tag"                       # accessor named after the last segment (`tag`)
+alias: ["meta.tag", "meta.color"]       # several at once
+alias: { label: "name", tag: "meta.tag" }
+```
+
+The path is the Ruby accessor chain (`meta.tag`), typed from the selection: any
+nullable hop makes the accessor nilable and inserts `&.`; the leaf can be a
+scalar, enum, or nested struct. It's validated against each query at generation —
+an unselected or misspelled segment (`did you mean 'tag'?`), a path through a
+list, or a name that collides with a real field all fail with a pointed error.
+Registrations stack and are client-scopable, like the mixin forms. For anything
+beyond a passthrough projection — real logic, still typed — reopen the generated
+struct in your own file and add sig'd methods; Sorbet merges the bodies.

data/graph_weaver.gemspec

@@ -14,7 +14,9 @@ Gem::Specification.new do |s|
 
   s.required_ruby_version = ">= 3.3"
 
-  s.add_dependency "graphql", ">= 2"
+  # 2.6.7 fills defaulted directive arguments when building from SDL
+  # (rmosolgo/graphql-ruby#5659) — needed since we dropped our own patch for it
+  s.add_dependency "graphql", ">= 2.6.7"
   s.add_dependency "sorbet-runtime"
 
   s.add_development_dependency "apollo-federation" # federation integration subgraphs

data/lib/graph_weaver/client.rb

@@ -76,7 +76,8 @@ class GraphWeaver::Client
 
   # Client-scoped scalar registration: consulted before the global
   # registry when this client generates code, so two clients can map the
-  # same scalar name onto different Ruby types. Same signature as
+  # same scalar name onto different Ruby types. A `Type.field` coordinate
+  # (e.g. "User.birthday") overrides just that field. Same signature as
   # GraphWeaver.register_scalar.
   def register_scalar(graphql_name, type, cast: nil, serialize: nil, requires: nil, coerce: nil)
     validate_registration!("scalar", graphql_name.to_s)
@@ -102,10 +103,11 @@ class GraphWeaver::Client
   # struct this client generates from the named GraphQL type — pass
   # modules, or a block to build one inline. Additive with global
   # registrations (see GraphWeaver.extend_type).
-  def extend_type(graphql_name, *mixins, requires: nil, &block)
+  def extend_type(graphql_name, *mixins, requires: nil, **kw, &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)
+    aliases = GraphWeaver::Codegen.take_aliases(kw)
+    entry = @types[graphql_name.to_s] ||= { mixins: [], requires: [], aliases: {} }
+    GraphWeaver::Codegen.add_type_helpers(entry, graphql_name, mixins, requires, block, aliases)
   end
 
   # Parse a query (a .graphql path or raw string) into a typed module