graph_weaver 0.4.0 → 0.4.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a608ee344d2e8ebf8ff0e847a34005114cfd1efd5a44c7aa66ef81c457706526
-  data.tar.gz: 4622816580d4158d4b84140b85876f00582ac85521686da4417f1945cdb4c276
+  metadata.gz: f01ed46a3a7d500364530c522e28f5b1f70f9db803988f940e487630bca0f10c
+  data.tar.gz: ee2e237e936ca60054b6465f62e14714c359235abfab376fb3b14e232ef851f9
 SHA512:
-  metadata.gz: 4d496923726cf4296f048f7f60305045aa1bfe042c007bcf10b87d34673bc451af85bf6165187e7f8a7b606dd0176ad54648c0ea504f69cb966d9addc9ba4503
-  data.tar.gz: ae5b74bd0de58a9f89fbc218e0103ab805c2b62bb5a9172bff6ebd38d890ad4804429789877b7a7c9ce343cb0d24f969fe8eb5785222736c042bc56008a2648a
+  metadata.gz: bb3adc8c4d4f3164a34a650fe989c785d45559a78c52b10bc93abe21e4ab26c9fb3892b76694c563cbc62b2e342b2bd49b87cf2f7119afe9439facc8dc837e94
+  data.tar.gz: ae4521a62bb818a9d8da0053533c4749a56e021f88c343acd25123b04016176a942da9e824bcb41df32083ae1c28db6a81b32079490c15014940bb016d821be6

data/CHANGELOG.md

@@ -1,3 +1,85 @@
+###  v0.4.6  (2026-07-30)
+Bug fixes from a full-library review (all with regression coverage):
+- alias: a nested-object/enum leaf (`meta.sub`) now qualifies its constant
+  (`Meta::Sub`) instead of emitting a bare `Sub` that raised NameError; alias
+  names/segments are validated as identifiers (were interpolated verbatim,
+  allowing injection); `optional:` no longer swallows a reserved-name/collision
+  mistake; a real field named `first`/`last` resolves as a field.
+- Shared unions: a hoisted member selecting a mapped enum now emits its
+  `<NAME>_FROM_WIRE` table into `unions.rb` (was a NameError at `from_h`); a
+  fragment whose name collides with `Result`/`QUERY` is refused.
+- A named interface fragment holding inline `... on X` conditions now dispatches
+  instead of silently dropping those fields; fragment cycles raise a clear error
+  in the FakeClient/Anonymizer walkers instead of `SystemStackError`.
+- Malformed responses/inputs stay under `GraphWeaver::Error`: a non-2xx
+  `errors: null` body keeps its status; a 2xx non-object body is a `ServerError`;
+  `data!` on null-data/no-errors raises `QueryError`; `coerce(non-Hash)` raises
+  `InputError`.
+- Testing harness: FakeClient/Anonymizer merge duplicate result keys (were
+  fabricating shapes the generated struct couldn't cast); `fail_at` fires every
+  execute; symbol-keyed cassette variables no longer crash on reload; the
+  Anonymizer keeps concrete-fragment fields when data lacks `__typename`.
+- Federation: a user type named `link` is no longer dropped; an all-`@inaccessible`
+  schema raises a pointed error. Client accepts `retries: nil` on a schema
+  source; `register_scalar` rejects an anonymous class.
+- FakeClient: an Integer `list_size` now means exactly that length (a Range
+  randomizes within it). Codegen rejects two variables that underscore to the
+  same kwarg (`$userId` + `$user_id`). The Faraday transport raises rather than
+  silently dropping `headers:`/block when handed a prebuilt connection.
+
+###  v0.4.5  (2026-07-30)
+- `alias:` paths gain list-element selectors: a `first`/`last` segment picks one
+  element out of a list hop, always nilable — `alias: { entity: "_entities.first" }`
+  yields `def entity = _entities&.first`, and navigation continues into the
+  element (`_entities.first.name`). Typed from the selection: a single inline
+  fragment lands on the concrete member (`T.nilable(Widget)`), a multi-fragment
+  selection on the union. Selectors are checked against the node shape — `.first`
+  on a non-list raises. Cleanly retires the `result._entities&.first&.field`
+  boilerplate of single-entity federation `_entities` queries.
+- `extend_type(..., optional: true)` makes its aliases lenient: a query whose
+  selection doesn't fit the path omits the accessor instead of failing
+  generation. For an alias on a universal type (a `Query` accessor a strict alias
+  would force every query to satisfy), or one that only fits some selections.
+
+###  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

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.4.0)
-      graphql (>= 2)
+    graph_weaver (0.4.6)
+      graphql (>= 2.6.7)
       sorbet-runtime
 
 GEM
@@ -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.4.0)
+  graph_weaver (0.4.6)
   graphql (2.6.7) sha256=759755ce5819c965b6459c5039605cf2e4d876bb8ba5e03451676870ea787c45
   i18n (1.15.2) sha256=00f9eb62412fe593b2a65a97daa75300d37abb8f7202ec748e94b6d46a9dd1b5
   io-console (0.8.2) sha256=d6e3ae7a7cc7574f4b8893b4fca2162e57a825b223a177b7afa236c5ef9814cc

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

@@ -270,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/scalars.md

@@ -174,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
@@ -191,6 +197,61 @@ 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 selector on a
+non-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.
+
+A segment can also be `first` or `last` to pick one element out of a list hop —
+always nilable, since the list may be empty. This is what turns an
+`_entities`-style "array that logically holds one thing" into a clean accessor:
+
+```ruby
+GraphWeaver.extend_type("Query", alias: { entity: "_entities.first" }, optional: true)
+
+#   sig { returns(T.nilable(Widget)) }        # concrete, when the selection is one `... on Widget`
+#   def entity = _entities&.first             # (a multi-fragment selection types it as the union)
+```
+
+`optional: true` makes the aliases *lenient*: a query whose selection doesn't fit
+the path just omits the accessor instead of failing generation. Reach for it when
+the alias lives on a universal type like `Query` — where a strict alias would
+force *every* query to select the path — or when it only fits some selections.
+
+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

@@ -35,7 +35,7 @@ class GraphWeaver::Client
 
       @transport = wrap_retries(build_transport(source, auth:, headers:, &middleware), retries)
     else
-      if auth || middleware || retries != false
+      if auth || middleware || retries
         raise ArgumentError, "auth:/retries:/middleware apply to a url — got a schema source"
       end
       if cache || ttl
@@ -103,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

data/lib/graph_weaver/codegen/emit.rb

@@ -194,6 +194,13 @@ class GraphWeaver::Codegen
         end
         out << "module #{@module_name}"
         out << "  extend T::Sig" << "" if GraphWeaver.extend_t_sig?
+        # a member selecting a mapped enum (register_enum) reads its module-level
+        # <NAME>_FROM_WIRE table — emit those here so from_h resolves them, the
+        # same way emit_variable_types does for the query module
+        @mapped_enums.each_value do |mapped|
+          emit_mapped_enum(mapped, out, 1)
+          out << ""
+        end
         unions.each do |union|
           emit_union(union, out, 1)
           out << ""
@@ -349,6 +356,14 @@ class GraphWeaver::Codegen
       out << "#{pad}  rescue TypeError, ArgumentError, KeyError => e"
       out << "#{pad}    raise GraphWeaver::TypeError.new(struct: self, error: e)"
       out << "#{pad}  end"
+
+      # alias delegators (extend_type alias:) — typed accessors that project a
+      # selected field onto the struct, next to the honest wire data
+      node.aliases.each do |a|
+        out << ""
+        out << "#{pad}  sig { returns(#{a.type}) }"
+        out << "#{pad}  def #{a.name} = #{a.expr}"
+      end
       out << "#{pad}end"
     end
 
@@ -414,7 +429,8 @@ class GraphWeaver::Codegen
 
       # execute returns the full envelope; execute! is the strict shortcut for
       # `execute(...).data!` — the typed result, or a raised QueryError.
-      forward = (["client"] + params.map { |param| "#{kwarg_name(param)}: #{kwarg_name(param)}" }).join(", ")
+      # kwargs forward via hash shorthand (key == value)
+      forward = (["client"] + params.map { |param| "#{kwarg_name(param)}:" }).join(", ")
 
       if flatten
         out << "  # $#{variables.first.wire}'s fields, flattened into kwargs (single input-object variable)"

data/lib/graph_weaver/codegen/enum_type.rb

@@ -102,9 +102,64 @@ class GraphWeaver::Codegen
     #      end
     #
     # Additive: repeated registrations (and client-scoped ones) stack.
-    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)
+    #
+    # alias: projects a (possibly nested) selected field onto a flat, typed
+    # accessor on the struct — the one derivation codegen can type itself, so
+    # it's emitted into the struct body where the field is in scope:
+    #
+    #      GraphWeaver.extend_type("Widget", alias: { tag: "meta.tag" })
+    #      GraphWeaver.extend_type("Widget", alias: "meta.tag")        # accessor named `tag`
+    #      GraphWeaver.extend_type("Widget", alias: ["meta.tag", "meta.color"])
+    #
+    # A path segment is a field, or `first`/`last` to pick one element out of a
+    # list hop (always nilable): `alias: { entity: "_entities.first" }`.
+    #
+    # optional: true makes the aliases lenient — a query whose selection doesn't
+    # fit the path just omits the accessor instead of failing generation. Use it
+    # for a root-type accessor (a Query alias every query would otherwise have to
+    # satisfy) or one that only fits some selections.
+    def extend_type(graphql_name, *mixins, requires: nil, **kw, &block)
+      aliases = take_aliases(kw)
+      entry = type_registry[graphql_name.to_s] ||= { mixins: [], requires: [], aliases: {} }
+      add_type_helpers(entry, graphql_name, mixins, requires, block, aliases)
+    end
+
+    # Pull alias:/optional: out of the keyword rest and normalize; any other
+    # keyword is a typo worth flagging rather than silently dropping.
+    def take_aliases(kw)
+      aliases = normalize_aliases(kw.delete(:alias), optional: !!kw.delete(:optional))
+      raise ArgumentError, "unknown keyword: #{kw.keys.first}" unless kw.empty?
+      aliases
+    end
+
+    # accessor names and path segments are interpolated verbatim into generated
+    # source, so — like module_name — they must be plain identifiers, never
+    # arbitrary text that could inject code
+    ALIAS_NAME = /\A[a-zA-Z_]\w*[?!]?\z/
+    ALIAS_SEGMENT = /\A[a-zA-Z_]\w*\z/
+
+    # { accessor => { segments:, optional: } } from a path string (accessor
+    # named after the last segment), an array of such, or an { accessor => path }
+    # hash. `optional:` marks every alias in this registration as lenient.
+    def normalize_aliases(input, optional:)
+      pairs = case input
+      when nil then []
+      when String then [[input.split(".").last, input.split(".")]]
+      when Array then input.map { |path| [path.split(".").last, path.split(".")] }
+      when Hash then input.map { |name, path| [name.to_s, path.to_s.split(".")] }
+      else raise ArgumentError, "alias: expects a String, Array, or Hash, got #{input.class}"
+      end
+      pairs.to_h do |name, segments|
+        unless name.to_s.match?(ALIAS_NAME)
+          raise ArgumentError, "alias name #{name.inspect} is not a valid method name"
+        end
+        raise ArgumentError, "alias #{name.inspect} has an empty path" if segments.empty?
+
+        bad = segments.reject { |seg| seg.match?(ALIAS_SEGMENT) }
+        raise ArgumentError, "alias #{name.inspect} has an invalid path segment: #{bad.first.inspect}" if bad.any?
+
+        [name, { segments:, optional: }]
+      end
     end
 
     def type_registry
@@ -113,11 +168,13 @@ class GraphWeaver::Codegen
 
     # 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)
+    def add_type_helpers(entry, graphql_name, mixins, requires, block, aliases = {})
       mixins = mixins.dup
       mixins << helper_module(graphql_name, block) if block
 
-      raise ArgumentError, "pass one or more helper modules, or a block" if mixins.empty?
+      if mixins.empty? && aliases.empty?
+        raise ArgumentError, "pass one or more helper modules, a block, or alias:"
+      end
       mixins.each do |mixin|
         unless mixin.is_a?(Module) && mixin.name
           raise ArgumentError, "type helpers must be named modules, got #{mixin.inspect}"
@@ -126,6 +183,7 @@ class GraphWeaver::Codegen
 
       entry[:mixins].concat(mixins)
       entry[:requires].concat(Array(requires))
+      (entry[:aliases] ||= {}).merge!(aliases)
       entry
     end
 

data/lib/graph_weaver/codegen/nodes.rb

@@ -144,16 +144,20 @@ class GraphWeaver::Codegen
 
   class ObjectNode < Node
     Field = Struct.new(:prop, :key, :node)
+    # a resolved alias delegator (extend_type alias:): the accessor name, the
+    # Ruby path expression it reads (meta&.tag), and its Sorbet return type
+    Alias = Struct.new(:name, :expr, :type)
 
     attr_reader :class_name, :fields
-    # the GraphQL type this struct was generated from, and any registered
-    # helper modules to include (see Codegen.extend_type)
-    attr_accessor :graphql_type, :mixins
+    # the GraphQL type this struct was generated from, any registered helper
+    # modules to include, and any resolved alias delegators (see extend_type)
+    attr_accessor :graphql_type, :mixins, :aliases
 
     def initialize(class_name)
       @class_name = class_name
       @fields = []
       @mixins = []
+      @aliases = []
     end
 
     def bare_type = class_name

data/lib/graph_weaver/codegen/scalar_type.rb

@@ -123,7 +123,10 @@ class GraphWeaver::Codegen
 
     def type_name(type)
       case type
-      when Module then type.name
+      when Module
+        # an anonymous class has no name to emit — it would land as a literal
+        # `nil` in generated source
+        type.name || raise(ArgumentError, "type: must be a named class/module, got an anonymous one")
       when String then type
       else raise ArgumentError, "type: must be a class/module or String, got #{type.inspect}"
       end