graph_weaver 0.4.0 → 0.4.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a608ee344d2e8ebf8ff0e847a34005114cfd1efd5a44c7aa66ef81c457706526
-  data.tar.gz: 4622816580d4158d4b84140b85876f00582ac85521686da4417f1945cdb4c276
+  metadata.gz: fac36591b869f046295946094078847ed33a1aa15aa8a2402e6a46f6e17ebaa0
+  data.tar.gz: c366d845da86029839f57214ba6216b78f2a870b67873851c2514d3d00aaa78d
 SHA512:
-  metadata.gz: 4d496923726cf4296f048f7f60305045aa1bfe042c007bcf10b87d34673bc451af85bf6165187e7f8a7b606dd0176ad54648c0ea504f69cb966d9addc9ba4503
-  data.tar.gz: ae5b74bd0de58a9f89fbc218e0103ab805c2b62bb5a9172bff6ebd38d890ad4804429789877b7a7c9ce343cb0d24f969fe8eb5785222736c042bc56008a2648a
+  metadata.gz: 37c814f83659a3189407b4c8e4531db4782fc4f38cd0e62df4f8e473a75c713adc3d0bb43de62a51854c1d6f0aeea1195e89848e83bd61c74018a840bfe56924
+  data.tar.gz: 787508b524cb027fb31281379f64bc566b1bb23709a79883928005ced38cf478c6c90b62a09d2de66317a6d7415eea77014667a5f543472a6f42d8ad043634de

data/CHANGELOG.md

@@ -1,3 +1,42 @@
+###  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.4)
+      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.4)
   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,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

@@ -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

@@ -349,6 +349,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 +422,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,38 @@ 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"])
+    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: out of the keyword rest and normalize it; any other keyword
+    # is a typo worth flagging rather than silently dropping.
+    def take_aliases(kw)
+      aliases = normalize_aliases(kw.delete(:alias))
+      raise ArgumentError, "unknown keyword: #{kw.keys.first}" unless kw.empty?
+      aliases
+    end
+
+    # { accessor => [path, segments] } from a path string (accessor named
+    # after the last segment), an array of such, or an { accessor => path } hash.
+    def normalize_aliases(input)
+      case input
+      when nil then {}
+      when String then { input.split(".").last => input.split(".") }
+      when Array then input.to_h { |path| [path.split(".").last, path.split(".")] }
+      when Hash then input.to_h { |name, path| [name.to_s, path.to_s.split(".")] }
+      else raise ArgumentError, "alias: expects a String, Array, or Hash, got #{input.class}"
+      end
     end
 
     def type_registry
@@ -113,11 +142,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 +157,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.rb

@@ -465,9 +465,72 @@ class GraphWeaver::Codegen
       node.fields << ObjectNode::Field.new(prop, key, child)
     end
 
+    node.aliases = resolve_aliases(node)
     node
   end
 
+  # Resolve each registered alias (extend_type alias:) for this struct's type
+  # against its actual selection — path -> a typed delegator emitted into the
+  # struct body. Validated here, per query, so an unselected or untraversable
+  # path fails at generation with a pointed message.
+  def resolve_aliases(node)
+    type_aliases(node.graphql_type).map do |name, segments|
+      resolve_alias(node, name, segments)
+    end
+  end
+
+  # Registered aliases for a GraphQL type: global registry plus this client's
+  # overlay (client-scoped wins on a name clash).
+  def type_aliases(graphql_name)
+    global = GraphWeaver::Codegen.type_registry[graphql_name]&.dig(:aliases) || {}
+    (global.merge(@types[graphql_name]&.dig(:aliases) || {}))
+  end
+
+  ALIAS_RESERVED = (%w[from_h serialize to_h].to_set + RUBY_KEYWORDS).freeze
+
+  # Walk a dotted path (Ruby prop names) through this struct's selected fields,
+  # building the delegator expression (`meta&.tag`) and its return type. Any hop
+  # is nilable -> the accessor is nilable; a list hop or an unselected segment
+  # raises. The leaf may be any node (scalar, enum, nested struct).
+  def resolve_alias(node, name, segments)
+    if node.fields.any? { |f| f.prop == name } || ALIAS_RESERVED.include?(name)
+      raise GraphWeaver::Error,
+        "alias #{name.inspect} on #{node.graphql_type} collides with an existing field or method"
+    end
+
+    current = T.let(node, T.untyped)
+    parts = []
+    nilable = T.let(false, T::Boolean)
+    segments.each_with_index do |seg, i|
+      field = current.fields.find { |f| f.prop == seg }
+      unless field
+        props = current.fields.map(&:prop)
+        suggestion = defined?(DidYouMean::SpellChecker) &&
+          DidYouMean::SpellChecker.new(dictionary: props).correct(seg).first
+        hint = suggestion ? " — did you mean '#{suggestion}'?" : " (have: #{props.join(", ")})"
+        raise GraphWeaver::Error,
+          "alias #{name.inspect} on #{node.graphql_type}: '#{seg}' is not a selected field#{hint}"
+      end
+      nilable ||= !field.node.non_null?
+
+      if i == segments.size - 1
+        leaf = field.node.bare_type
+        type = nilable && leaf != "T.untyped" ? "T.nilable(#{leaf})" : leaf
+        return ObjectNode::Alias.new(name, (parts << seg).join, type)
+      end
+
+      inner = T.let(field.node, T.untyped)
+      inner = inner.of while inner.is_a?(NonNull)
+      raise GraphWeaver::Error, "alias #{name.inspect}: cannot traverse list-typed '#{seg}'" if inner.is_a?(List)
+      unless inner.is_a?(ObjectNode)
+        raise GraphWeaver::Error, "alias #{name.inspect}: '#{seg}' is not an object to traverse into"
+      end
+
+      parts << seg << (field.node.non_null? ? "." : "&.")
+      current = inner
+    end
+  end
+
   # The concrete type conditions a selection mentions (inline fragments
   # and named spreads), minus conditions naming the abstract type itself.
   def concrete_conditions(core, selections)

data/lib/graph_weaver/schema_loader.rb

@@ -26,19 +26,151 @@ module GraphWeaver::SchemaLoader
         raise ArgumentError, "unsupported schema content: #{source.lstrip[0, 80].inspect}"
       end
 
-      GraphQL::Schema.from_definition(source)
+      build_sdl(source)
     else # a file path
       case File.extname(source)
       when ".json"
         GraphQL::Schema.from_introspection(JSON.parse(File.read(source)))
       when ".graphql", ".gql"
-        GraphQL::Schema.from_definition(File.read(source))
+        build_sdl(File.read(source))
       else
         raise ArgumentError, "unsupported schema format: #{source}"
       end
     end
   end
 
+  # Build a schema from SDL, first stripping Apollo Federation composition
+  # machinery when the SDL is a composed supergraph — so a supergraph dump
+  # (often the only artifact for the merged graph, and what the router
+  # actually serves) loads like any schema, with the federation plumbing
+  # gone rather than leaked into schema.types. Plain SDL passes through.
+  def self.build_sdl(sdl)
+    GraphQL::Schema.from_definition(federation_sdl?(sdl) ? strip_federation(sdl) : sdl)
+  end
+  private_class_method :build_sdl
+
+  # A composed Fed2 supergraph is marked by @join__* directives (every merged
+  # type carries them); a plain schema has none.
+  def self.federation_sdl?(sdl)
+    sdl.match?(/@join__\w/)
+  end
+
+  FEDERATION_PREFIXES = %w[join__ link__ core__].freeze
+  FEDERATION_DIRECTIVES = %w[link core inaccessible].to_set.freeze
+
+  # Whether a type/directive name belongs to the federation composition layer.
+  def self.federation_name?(name)
+    !!name && (name.start_with?(*FEDERATION_PREFIXES) || FEDERATION_DIRECTIVES.include?(name))
+  end
+  private_class_method :federation_name?
+
+  # Drop the composition machinery from supergraph SDL: the synthetic
+  # join__*/link__* type and directive definitions, and every @join__*/@link
+  # application on the types that remain. What's left is the merged graph's
+  # ordinary type shapes — exactly what codegen reads. Parsing is lenient (it's
+  # schema *building* that rejects the join directives), so we parse, filter the
+  # AST, and reprint clean SDL for from_definition — no graphql-ruby monkeypatch
+  # and no join__* leaking into schema.types.
+  def self.strip_federation(sdl)
+    doc = GraphQL.parse(sdl)
+    defs = remove_inaccessible(doc.definitions)
+      .reject { |defn| defn.respond_to?(:name) && federation_name?(defn.name) }
+      .map { |defn| strip_federation_directives(defn) }
+    GraphQL::Language::Nodes::Document.new(definitions: defs).to_query_string
+  end
+
+  # Derive the API schema by dropping every element marked @inaccessible —
+  # present in the federated graph but hidden from the public API the router
+  # serves (its common use is safely rolling out a field on a shared type).
+  # Cascades: a field/argument/union-member/implements referencing a removed
+  # type goes too, and a type left with no fields/values/members is itself
+  # removed — repeated to a fixpoint. So codegen matches exactly what clients
+  # can query, without the over-permitting a raw supergraph would allow and
+  # without Apollo's JS tooling to subtract the API schema.
+  def self.remove_inaccessible(definitions)
+    removed = definitions.select { |d| type_definition?(d) && inaccessible?(d) }.map(&:name).to_set
+    loop do
+      survivors = definitions
+        .reject { |d| type_definition?(d) && removed.include?(d.name) }
+        .map { |d| prune_inaccessible(d, removed) }
+      newly = survivors.select { |d| type_definition?(d) && type_emptied?(d) }.map(&:name)
+      return survivors if (newly - removed.to_a).empty?
+
+      removed.merge(newly)
+    end
+  end
+  private_class_method :remove_inaccessible
+
+  # A type-system type definition (object/interface/union/enum/input/scalar) —
+  # not a directive or schema definition.
+  def self.type_definition?(node)
+    node.respond_to?(:name) &&
+      !node.is_a?(GraphQL::Language::Nodes::DirectiveDefinition) &&
+      node.class.name.end_with?("TypeDefinition")
+  end
+  private_class_method :type_definition?
+
+  def self.inaccessible?(node)
+    node.respond_to?(:directives) && node.directives.any? { |d| d.name == "inaccessible" }
+  end
+  private_class_method :inaccessible?
+
+  # Whether pruning left the type with nothing the SDL grammar allows to be
+  # empty — a fieldless object/interface/input, a valueless enum, a memberless
+  # union — so it must be removed and its references cascaded.
+  def self.type_emptied?(node)
+    (node.respond_to?(:fields) && node.fields && node.fields.empty?) ||
+      (node.is_a?(GraphQL::Language::Nodes::EnumTypeDefinition) && node.values.empty?) ||
+      (node.is_a?(GraphQL::Language::Nodes::UnionTypeDefinition) && node.types.empty?)
+  end
+  private_class_method :type_emptied?
+
+  # the unwrapped (through NON_NULL/LIST) type name a field or argument references
+  def self.unwrapped_type_name(node)
+    type = node.type
+    type = type.of_type while type.respond_to?(:of_type)
+    type.name
+  end
+  private_class_method :unwrapped_type_name
+
+  # Remove @inaccessible children and children referencing a removed type,
+  # from a type's fields (and their arguments), enum values, union members,
+  # and implemented interfaces.
+  def self.prune_inaccessible(node, removed)
+    gone = lambda do |child|
+      inaccessible?(child) || (child.respond_to?(:type) && removed.include?(unwrapped_type_name(child)))
+    end
+
+    changes = {}
+    if node.respond_to?(:fields) && node.fields
+      changes[:fields] = node.fields.reject(&gone).map do |field|
+        args = field.respond_to?(:arguments) && field.arguments
+        args && args.any? ? field.merge(arguments: args.reject(&gone)) : field
+      end
+    end
+    changes[:values] = node.values.reject(&gone) if node.respond_to?(:values) && node.values
+    changes[:types] = node.types.reject { |t| removed.include?(t.name) } if node.respond_to?(:types) && node.types
+    if node.respond_to?(:interfaces) && node.interfaces
+      changes[:interfaces] = node.interfaces.reject { |i| removed.include?(i.name) }
+    end
+    changes.empty? ? node : node.merge(changes)
+  end
+  private_class_method :prune_inaccessible
+
+  # Recursively remove @join__*/@link applications from a definition and its
+  # fields, arguments, and enum values.
+  def self.strip_federation_directives(node)
+    changes = {}
+    if node.respond_to?(:directives) && node.directives
+      changes[:directives] = node.directives.reject { |d| federation_name?(d.name) }
+    end
+    changes[:fields] = node.fields.map { |c| strip_federation_directives(c) } if node.respond_to?(:fields) && node.fields
+    changes[:arguments] = node.arguments.map { |c| strip_federation_directives(c) } if node.respond_to?(:arguments) && node.arguments
+    changes[:values] = node.values.map { |c| strip_federation_directives(c) } if node.respond_to?(:values) && node.values
+    changes.empty? ? node : node.merge(changes)
+  end
+  private_class_method :strip_federation_directives
+
   # Run the standard introspection query through a transport and build a
   # schema from the result:
   #

data/lib/graph_weaver/version.rb

@@ -1,3 +1,3 @@
 module GraphWeaver
-  VERSION = "0.4.0"
+  VERSION = "0.4.4"
 end

data/lib/graph_weaver.rb

@@ -17,9 +17,6 @@ require_relative "graph_weaver/railtie" if defined?(::Rails::Railtie)
 
 # opt-in extras:
 #      require "graph_weaver/transport/faraday"        # Faraday transport
-#      require "graph_weaver/directive_defaults_patch" # fix graphql-ruby
-#        dropping directive argument defaults when loading SDL (needed for
-#        Apollo supergraph SDL until rmosolgo/graphql-ruby#5659 ships)
 module GraphWeaver
   class << self
     # A client for one GraphQL server — transport, schema, and scoped
@@ -348,13 +345,15 @@ module GraphWeaver
     end
 
     # Include app-owned helper modules into every struct generated from a
-    # GraphQL type — derived values live as methods next to the honest
-    # wire data, and srb tc checks them against each query's selection:
+    # GraphQL type — derived values live as methods next to the honest wire
+    # data, on the struct at runtime (fakes/cassettes included):
     #
     #      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):
+    # A helper that reads a wire field is checked by srb tc in the module's
+    # own scope, not the struct's, so the field won't resolve — write it
+    # # typed: false or reach it via T.unsafe(self). Or build the mixin inline
+    # with a block (module_eval'd into an auto-named module — invisible to srb):
     #
     #      GraphWeaver.extend_type("Pet") do
     #        def display_name = "#{name} the pet"
@@ -362,8 +361,8 @@ module GraphWeaver
     #
     # Additive (repeated and client-scoped registrations stack). Global;
     # client.extend_type scopes to one client.
-    def extend_type(graphql_name, *mixins, requires: nil, &block)
-      Codegen.extend_type(graphql_name, *mixins, requires:, &block)
+    def extend_type(graphql_name, *mixins, requires: nil, **kw, &block)
+      Codegen.extend_type(graphql_name, *mixins, requires:, **kw, &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.4.0
+  version: 0.4.4
 platform: ruby
 authors:
 - Daniel Pepper
@@ -15,14 +15,14 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '2'
+        version: 2.6.7
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '2'
+        version: 2.6.7
 - !ruby/object:Gem::Dependency
   name: sorbet-runtime
   requirement: !ruby/object:Gem::Requirement
@@ -253,7 +253,6 @@ files:
 - lib/graph_weaver/codegen/enum_type.rb
 - lib/graph_weaver/codegen/nodes.rb
 - lib/graph_weaver/codegen/scalar_type.rb
-- lib/graph_weaver/directive_defaults_patch.rb
 - lib/graph_weaver/errors.rb
 - lib/graph_weaver/hints.rb
 - lib/graph_weaver/inflect.rb

data/lib/graph_weaver/directive_defaults_patch.rb

@@ -1,32 +0,0 @@
-# typed: false — monkeypatch; `self.class` resolves against the prepended host
-# frozen_string_literal: true
-
-require "graphql"
-
-# graphql-ruby's SDL builder (BuildFromDefinition#prepare_directives)
-# passes only the directive arguments present at the usage site, but
-# Directive#initialize validates ALL defined arguments — so a defaulted
-# non-null argument (`extension: Boolean! = false`) raises
-# InvalidArgumentError when omitted, even though the SDL spec makes it
-# optional. Real Apollo supergraph SDL (join v0.3) hits this on every
-# @join__type usage.
-#
-# Fill in the declared defaults before validation. This is what upstream
-# should do; present in graphql 2.6.3 (latest at time of writing).
-#
-# TODO: delete this file (and its requires) once
-# https://github.com/rmosolgo/graphql-ruby/pull/5659 lands in a released
-# graphql version and the Gemfile picks it up.
-module DirectiveDefaultsPatch
-  def initialize(owner, **arguments)
-    self.class.all_argument_definitions.each do |arg_defn|
-      if !arguments.key?(arg_defn.keyword) && arg_defn.default_value?
-        arguments[arg_defn.keyword] = arg_defn.default_value
-      end
-    end
-
-    super(owner, **arguments)
-  end
-end
-
-GraphQL::Schema::Directive.prepend(DirectiveDefaultsPatch)