graph_weaver 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e66ac94243bdc7f065534845a722bfd209c8d7b23a3a5fa1eff6041e3f563655
-  data.tar.gz: 413217dbda71c297abe537dc996b8e8413821365d9e966493bf7301d6351a6c7
+  metadata.gz: a608ee344d2e8ebf8ff0e847a34005114cfd1efd5a44c7aa66ef81c457706526
+  data.tar.gz: 4622816580d4158d4b84140b85876f00582ac85521686da4417f1945cdb4c276
 SHA512:
-  metadata.gz: 62dab00fca85973dbff0e695dcd9970a554ca98b6a717a375fa7f2cde349b2967672ce541bf108d3b058b54b47ce7d274f6c8f11f069360a59e95fcb86ff8ae5
-  data.tar.gz: 3a11e52459c3b0158d831c8815ced9c4ca5cd323435ffac4e36a8648e83179dd87763a4570aaa56b240d0d7d77d3b91e43d1706f40112d3eae2fa608950b797c
+  metadata.gz: 4d496923726cf4296f048f7f60305045aa1bfe042c007bcf10b87d34673bc451af85bf6165187e7f8a7b606dd0176ad54648c0ea504f69cb966d9addc9ba4503
+  data.tar.gz: ae5b74bd0de58a9f89fbc218e0103ab805c2b62bb5a9172bff6ebd38d890ad4804429789877b7a7c9ce343cb0d24f969fe8eb5785222736c042bc56008a2648a

data/CHANGELOG.md

@@ -1,3 +1,52 @@
+###  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/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    graph_weaver (0.3.0)
+    graph_weaver (0.4.0)
       graphql (>= 2)
       sorbet-runtime
 
@@ -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.0)
+  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/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.

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:
 

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)

data/lib/graph_weaver/codegen/emit.rb

@@ -115,10 +115,10 @@ class GraphWeaver::Codegen
         names.uniq
       end
 
-      def emit_shared_aliases(out, names)
+      def emit_shared_aliases(out, names, namespace = @inputs_namespace)
         return if names.empty?
 
-        names.each { |name| out << "  #{name} = #{@inputs_namespace}::#{name}" }
+        names.each { |name| out << "  #{name} = #{namespace}::#{name}" }
         out << ""
       end
 
@@ -175,6 +175,35 @@ class GraphWeaver::Codegen
         files
       end
 
+      # The shared unions artifact as a single file: every hoisted union as a
+      # <module_name>::<Name> module. Unions don't cross-reference (each is a
+      # self-contained fragment), so there's no need for per-type files or the
+      # forward declarations recursive input types require.
+      def emit_unions_file(unions)
+        out = []
+        out << "# typed: strict"
+        out << "# frozen_string_literal: true"
+        out << ""
+        out << "# Generated by GraphWeaver — do not edit. Shared union types for this"
+        out << "# schema (named fragments on union fields); query modules alias what they use."
+        out << ""
+        requires = @requires.uniq.sort
+        if requires.any?
+          requires.each { |req| out << "require #{req.inspect}" }
+          out << ""
+        end
+        out << "module #{@module_name}"
+        out << "  extend T::Sig" << "" if GraphWeaver.extend_t_sig?
+        unions.each do |union|
+          emit_union(union, out, 1)
+          out << ""
+        end
+        out.pop if out.last == ""
+        out << "end"
+
+        { "unions.rb" => out.join("\n") + "\n" }
+      end
+
       # one type per file, wrapped in the namespace so bare sibling
       # references resolve lexically
       def inputs_file(files, name)
@@ -200,6 +229,9 @@ class GraphWeaver::Codegen
     def emit_module(root, variables)
       flatten = flatten_input(variables)
       aliases = @inputs_namespace ? shared_alias_names(variables, flatten) : []
+      # hoisted unions the result tree references, aliased so <Name>::Type and
+      # <Name>.from_h resolve to the shared module
+      union_aliases = @used_unions.map { |name| camelize(name) }.uniq.sort
 
       out = []
       out << "# typed: strict"
@@ -218,9 +250,12 @@ class GraphWeaver::Codegen
         out << "require_relative \"inputs\""
         out << ""
       end
+      if union_aliases.any?
+        out << "require_relative \"unions\""
+        out << ""
+      end
       out << "module #{@module_name}"
-      out << "  extend T::Sig"
-      out << ""
+      out << "  extend T::Sig" << "" if GraphWeaver.extend_t_sig?
       # a GraphQL block string could contain a bare GRAPHQL line, which
       # would terminate the heredoc early — pick a delimiter the query
       # can't collide with
@@ -235,6 +270,7 @@ class GraphWeaver::Codegen
       else
         emit_variable_types(out)
       end
+      emit_shared_aliases(out, union_aliases, @unions_namespace)
       emit_nested(root, out, 1)
       out << ""
       emit_execute(out, variables, flatten:)
@@ -282,14 +318,16 @@ class GraphWeaver::Codegen
       pad = "  " * indent
 
       out << "#{pad}class #{node.class_name} < T::Struct"
-      out << "#{pad}  extend T::Sig"
+      out << "#{pad}  extend T::Sig" if GraphWeaver.extend_t_sig?
       out << "#{pad}  include GraphWeaver::Hints"
       node.mixins.each do |mixin|
         out << "#{pad}  include #{mixin} # registered for #{node.graphql_type}"
       end
       out << ""
 
-      node.fields.filter_map { |field| field.node.nested }.each do |child|
+      # uniq by object identity: deduped sibling unions share one node, so the
+      # shared type is emitted once (both fields' consts already reference it).
+      node.fields.filter_map { |field| field.node.nested }.uniq.each do |child|
         emit_nested(child, out, indent + 1)
         out << ""
       end
@@ -318,8 +356,7 @@ class GraphWeaver::Codegen
       pad = "  " * indent
 
       out << "#{pad}module #{node.class_name}"
-      out << "#{pad}  extend T::Sig"
-      out << ""
+      out << "#{pad}  extend T::Sig" << "" if GraphWeaver.extend_t_sig?
 
       node.members.each_value do |member|
         emit_object(member, out, indent + 1)
@@ -346,8 +383,7 @@ class GraphWeaver::Codegen
       out << "  @client = T.let(nil, T.untyped)"
       out << ""
       out << "  class << self"
-      out << "    extend T::Sig"
-      out << ""
+      out << "    extend T::Sig" << "" if GraphWeaver.extend_t_sig?
       out << "    sig { params(client: T.untyped).void }"
       out << "    attr_writer :client"
       out << ""

data/lib/graph_weaver/codegen/nodes.rb

@@ -277,6 +277,26 @@ class GraphWeaver::Codegen
     def nested = self
   end
 
+  # A reference to a union hoisted into the shared unions module (a named
+  # shared fragment spread as a whole union field): the query references
+  # <Name>::Type and dispatches through <Name>.from_h, where <Name> is the
+  # alias the query module gives GraphQLUnions::<Name>. The type family lives
+  # once in the shared module, so the same union across queries is one Ruby
+  # type — nested is nil, nothing is emitted here.
+  class UnionRefNode < Node
+    attr_reader :class_name
+
+    def initialize(class_name)
+      @class_name = class_name
+    end
+
+    def bare_type = "#{class_name}::Type"
+
+    def cast(expr, _depth)
+      "#{class_name}.from_h(#{expr})"
+    end
+  end
+
   # An input-object variable: emitted as a module-level T::Struct whose
   # serialize produces the wire hash. Inputs never cast FROM the wire.
   # Joins the coerce protocol so execute kwargs accept plain hashes,

data/lib/graph_weaver/codegen.rb

@@ -49,8 +49,12 @@ class GraphWeaver::Codegen
   # mixin modules, each keyed by GraphQL name). inputs_namespace: is the
   # shared-inputs workflow (see GraphWeaver.generate!): variable types
   # live once in that module and the query module aliases what it uses.
+  # unions_namespace:/hoistable_unions: are the parallel shared-unions
+  # workflow — a whole-union field spread as a named shared fragment resolves
+  # to one canonical type in that module (see used_union_names).
   def initialize(schema:, query:, module_name: nil, client: nil, default_module_name: nil,
-    scalars: nil, enums: nil, types: nil, inputs_namespace: nil)
+    scalars: nil, enums: nil, types: nil, inputs_namespace: nil, unions_namespace: nil,
+    hoistable_unions: nil)
     @schema = schema
     @query = query.strip
     @module_name = module_name
@@ -59,6 +63,12 @@ class GraphWeaver::Codegen
     @enums = enums || {}
     @types = types || {}
     @inputs_namespace = inputs_namespace
+    # the shared-unions workflow: unions_namespace names the module hoisted
+    # unions live in; hoistable_unions is the set of shared fragment names this
+    # query may hoist (spreads it inlined, minus any it shadows locally)
+    @unions_namespace = unions_namespace
+    @hoistable_unions = hoistable_unions || []
+    @used_unions = []
     @client_const = self.class.client_const(client)
 
     if client && @client_const.nil?
@@ -111,6 +121,11 @@ class GraphWeaver::Codegen
     { inputs: @variable_inputs.keys, enums: @variable_enums.keys, mapped: @mapped_enums.keys }
   end
 
+  # The shared union fragments this query hoisted, by name — the generate!
+  # workflow unions these across queries to decide what the shared unions
+  # module must contain.
+  def used_union_names = @used_unions.dup
+
   # The shared inputs artifact: the named input/enum types — plus
   # everything they transitively reference — emitted once per schema as
   # a manifest (inputs.rb) plus one file per type under inputs/, so a
@@ -138,6 +153,36 @@ class GraphWeaver::Codegen
     emit_inputs_files
   end
 
+  # The shared unions artifact: each named shared fragment a query hoisted,
+  # built once against the schema as <module_name>::<Name>, so the same union
+  # across queries resolves to one Ruby type family. `fragments` is the loaded
+  # shared-fragment table (nested spreads resolve through it); `names` the
+  # fragments to build. Returns { "unions.rb" => source }.
+  def self.generate_unions(schema:, module_name:, fragments:, names:,
+    scalars: nil, enums: nil, types: nil)
+    codegen = new(schema:, query: "", module_name:, scalars:, enums:, types:)
+    codegen.generate_unions(fragments, names)
+  end
+
+  def generate_unions(fragments, names)
+    unless @module_name&.match?(/\A[A-Z]\w*(::[A-Z]\w*)*\z/)
+      raise ArgumentError, "unions module name must be a constant name, got #{@module_name.inspect}"
+    end
+
+    @requires = []
+    @mapped_enums = {}
+    # nested spreads inside a shared fragment resolve through the whole table
+    @fragments = fragments
+
+    unions = names.uniq.sort.map do |name|
+      fragment = fragments.fetch(name)
+      type = @schema.get_type(fragment.type.name)
+      UnionNode.new(camelize(name), union_members(type, fragment.selections))
+    end
+
+    emit_unions_file(unions)
+  end
+
   VarDef = Struct.new(:kwarg, :wire, :node, :required)
 
   # Names that cannot appear bare in generated Ruby: keywords aren't
@@ -168,6 +213,7 @@ class GraphWeaver::Codegen
     @variable_enums = {}
     @variable_inputs = {}
     @mapped_enums = {}
+    @used_unions = []
     # requires the generated file needs (custom scalars, enum mappings,
     # type helpers all contribute)
     @requires = []
@@ -214,6 +260,14 @@ class GraphWeaver::Codegen
   # whose schema introspects lazily). Global registrations skip this:
   # they may target a different client's server.
   def self.validate_registration!(schema, kind, name)
+    # register_scalar("Type.field", ...) overrides one field's scalar — validate
+    # the field exists and is a scalar, not that a type named "Type.field" exists.
+    if kind == "scalar" && name.include?(".")
+      return if scalar_field?(schema, name)
+
+      raise GraphWeaver::Error, "register_scalar(#{name.inspect}) matches no scalar field in this schema"
+    end
+
     return if schema.get_type(name)
 
     suggestion = defined?(DidYouMean::SpellChecker) &&
@@ -224,6 +278,81 @@ class GraphWeaver::Codegen
     raise GraphWeaver::Error, "#{method}(#{name.inspect}) matches no type in this schema#{hint}"
   end
 
+  # Whether `coordinate` ("Type.field") names an existing scalar field — the
+  # validation for a per-field register_scalar override.
+  def self.scalar_field?(schema, coordinate)
+    type_name, field_name = coordinate.split(".", 2)
+    return false unless field_name
+
+    field = schema.get_field(type_name, field_name)
+    !!field && field.type.unwrap.kind.name == "SCALAR"
+  rescue StandardError
+    false
+  end
+
+  # Parse every fragment file under `paths` into one { name => FragmentDefinition }
+  # map — reusable fragments a query can spread. Fragment files hold only
+  # fragments (no operations); names are unique across them.
+  def self.load_fragments(paths)
+    Array(paths).flat_map { |dir| Dir[File.join(dir, "*.graphql")].sort }.each_with_object({}) do |file, out|
+      doc = GraphQL.parse(File.read(file))
+      if doc.definitions.grep(GraphQL::Language::Nodes::OperationDefinition).any?
+        raise GraphWeaver::Error, "#{file}: fragment files define only fragments, no operations"
+      end
+      doc.definitions.grep(GraphQL::Language::Nodes::FragmentDefinition).each do |frag|
+        raise GraphWeaver::Error, "duplicate shared fragment '#{frag.name}' (#{file})" if out.key?(frag.name)
+        out[frag.name] = frag
+      end
+    end
+  end
+
+  # The shared fragments a query spreads (transitively), excluding any it
+  # shadows with a local definition of the same name — the names
+  # inline_fragments appends, and the set the generate! workflow may hoist
+  # when they sit on a whole-union field.
+  def self.shared_fragment_spreads(query, shared)
+    return [] if shared.empty?
+
+    doc = GraphQL.parse(query)
+    local = doc.definitions.grep(GraphQL::Language::Nodes::FragmentDefinition).map(&:name)
+    reachable_fragments(fragment_spreads(doc.definitions), shared, local)
+  end
+
+  # Append the shared fragments a query spreads (transitively) to its source, so
+  # the sent query is self-contained. Unused shared fragments are left out.
+  def self.inline_fragments(query, shared)
+    used = shared_fragment_spreads(query, shared)
+    return query if used.empty?
+
+    "#{query.rstrip}\n\n#{used.sort.map { |name| shared.fetch(name).to_query_string }.join("\n\n")}\n"
+  end
+
+  # BFS over spreads, following shared fragments into their own spreads; a
+  # locally-defined or unknown spread is left for schema validation to judge.
+  def self.reachable_fragments(spreads, shared, local)
+    needed = []
+    queue = spreads.dup
+    until queue.empty?
+      name = queue.shift
+      next if needed.include?(name) || local.include?(name) || !shared.key?(name)
+
+      needed << name
+      queue.concat(fragment_spreads([shared.fetch(name)]))
+    end
+    needed
+  end
+  private_class_method :reachable_fragments
+
+  # Names of every fragment spread reachable in these AST nodes.
+  def self.fragment_spreads(nodes, acc = [])
+    nodes.each do |node|
+      acc << node.name if node.is_a?(GraphQL::Language::Nodes::FragmentSpread)
+      fragment_spreads(node.selections, acc) if node.respond_to?(:selections)
+    end
+    acc
+  end
+  private_class_method :fragment_spreads
+
   # Structured shape for a schema-validation error: message plus its first
   # source location, so ValidationError#errors is inspectable.
   def validation_detail(error)
@@ -251,6 +380,10 @@ class GraphWeaver::Codegen
     node.graphql_type = type.graphql_name
     node.mixins = type_mixins(type.graphql_name)
     taken = [class_name]
+    # Dedup structurally-identical dispatch-union fields on this struct: the
+    # same union selected two ways (unblockOptions vs selectedOption) shares
+    # one Ruby type, so consumers get one exhaustive `case ... T.absurd`.
+    union_cache = {}
 
     gather(type, selections).each do |key, field_nodes|
       field_name = field_nodes.first.name
@@ -291,9 +424,20 @@ class GraphWeaver::Codegen
 
             name = pick_name(member.graphql_name, key, taken)
             nilable_type_ref(field_type) { NarrowedNode.new(object_node(member, sub_selections, name)) }
+          elsif @unions_namespace && (frag = lone_shared_spread(sub_selections)) &&
+              @hoistable_unions.include?(frag)
+            # a whole-union field spread as a named shared fragment: hoist to
+            # the shared unions module so the same union across queries is one
+            # Ruby type family (one exhaustive `case ... T.absurd`).
+            @used_unions << frag unless @used_unions.include?(frag)
+            ref = UnionRefNode.new(camelize(frag))
+            type_ref(field_type) { ref }
           else
-            name = pick_name(core.graphql_name, key, taken)
-            type_ref(field_type) { union_node(core, sub_selections, name) }
+            members = union_members(core, sub_selections)
+            # reuse an identical sibling union (pick_name/name only on a miss)
+            union = (union_cache[union_signature(members)] ||=
+              UnionNode.new(pick_name(core.graphql_name, key, taken), members))
+            type_ref(field_type) { union }
           end
         when "ENUM"
           if (mapped = mapped_enum_node(core))
@@ -305,7 +449,8 @@ class GraphWeaver::Codegen
             type_ref(field_type) { EnumNode.new(name, core.values.keys.sort) }
           end
         when "SCALAR"
-          type_ref(field_type) { scalar_node(core.graphql_name) }
+          coordinate = "#{type.graphql_name}.#{field_name}"
+          type_ref(field_type) { scalar_node(core.graphql_name, coordinate) }
         else
           raise GraphWeaver::Error, "unsupported kind: #{core.kind.name}"
         end
@@ -341,6 +486,17 @@ class GraphWeaver::Codegen
     selections.grep(GraphQL::Language::Nodes::Field).map { |field| field.alias || field.name }
   end
 
+  # The fragment name when a selection is exactly one bare fragment spread
+  # (`{ ...F }`) — the shape a union field must have to hoist into the shared
+  # unions module. A spread carrying directives (@skip/@include), or mixed with
+  # other fields, stays a locally-emitted union.
+  def lone_shared_spread(selections)
+    return unless selections.size == 1
+
+    spread = selections.first
+    spread.name if spread.is_a?(GraphQL::Language::Nodes::FragmentSpread) && spread.directives.empty?
+  end
+
   # does the flattened selection (as seen by member) include at least one
   # field guaranteed to be present in a matching response?
   def unconditional_field?(member, selections)
@@ -367,19 +523,45 @@ class GraphWeaver::Codegen
   # concrete type: one member struct per possible type; wire dispatch
   # reads __typename, so the query must select it. For interfaces, the
   # interface's own field selections gather into every member.
-  def union_node(type, selections, class_name)
+  # The union's member structs (graphql type name => ObjectNode), sorted for
+  # deterministic output. Dispatch reads __typename, so the query must select
+  # it; for interfaces the interface-level fields gather into every member.
+  def union_members(type, selections)
     unless gather(type, selections).key?("__typename")
       raise ArgumentError,
-        "select __typename on #{type.graphql_name} so #{class_name} can dispatch — " \
+        "select __typename on #{type.graphql_name} so the union can dispatch — " \
         "or narrow to a single `... on Type` condition (no dispatch needed)"
     end
 
-    # sorted so output is deterministic across schema sources
-    members = @schema.possible_types(type).sort_by(&:graphql_name).to_h do |possible|
+    @schema.possible_types(type).sort_by(&:graphql_name).to_h do |possible|
       [possible.graphql_name, object_node(possible, selections, camelize(possible.graphql_name))]
     end
+  end
 
-    UnionNode.new(class_name, members)
+  # A name-independent structural fingerprint of a union's members, so two
+  # occurrences that generate identical structs collapse to one Ruby type.
+  def union_signature(members)
+    members.map { |gname, member| "#{gname}=#{signature(member)}" }.sort.join(",")
+  end
+
+  # Structural signature of a node — ignores the generated class name (which
+  # varies per occurrence), keying on GraphQL type, selection shape, and
+  # nullability so only genuinely-identical shapes collapse.
+  def signature(node)
+    case node
+    when NonNull then "!#{signature(node.of)}"
+    when List then "[#{signature(node.of)}]"
+    when NarrowedNode then "?#{signature(node.nested)}"
+    when Scalar then "s:#{node.bare_type}"
+    when EnumNode then "e:#{node.values.sort.join("|")}"
+    when MappedEnum then "m:#{node.graphql_name}"
+    when ObjectNode
+      inner = node.fields.map { |f| "#{f.prop}=#{signature(f.node)}" }.sort.join(",")
+      "o:#{node.graphql_type}(#{inner})"
+    when UnionNode then "u:(#{union_signature(node.members)})"
+    when UnionRefNode then "ur:#{node.class_name}" # hoisted — identity is its shared name
+    else "x:#{node.object_id}" # unknown node kind — never collapse
+    end
   end
 
   # Build a node from an AST type reference (variable definitions), where
@@ -462,9 +644,13 @@ class GraphWeaver::Codegen
 
   # A Scalar node, recording any requires its registered type needs so the
   # generated file can require them (collected across the whole query).
-  # Resolution: the client-scoped overlay first, then the global registry.
-  def scalar_node(name)
-    scalar = @scalars[name.to_s] || GraphWeaver::Codegen.scalar(name)
+  # Resolution, most specific first: a per-field override (`Type.field`), then
+  # the scalar-name registration — each checked client-scoped, then global.
+  def scalar_node(name, coordinate = nil)
+    scalar =
+      (coordinate && (@scalars[coordinate] || GraphWeaver::Codegen.scalar_registry[coordinate])) ||
+      @scalars[name.to_s] ||
+      GraphWeaver::Codegen.scalar(name)
     @requires.concat(scalar.requires)
     Scalar.new(scalar)
   end

data/lib/graph_weaver/version.rb

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

data/lib/graph_weaver.rb

@@ -67,7 +67,7 @@ module GraphWeaver
     #
     # The singular accessors read the first entry (the default target
     # for generate! and the rake tasks); assigning one replaces the list.
-    attr_writer :queries_paths, :generated_paths, :schema_path
+    attr_writer :queries_paths, :generated_paths, :schema_path, :fragments_paths
 
     # Entries may be glob patterns — the generated default also matches
     # per-schema layouts (app/graphql/github/generated). Queries stay
@@ -75,8 +75,14 @@ module GraphWeaver
     def queries_paths = @queries_paths ||= ["app/graphql/queries"]
     def generated_paths = @generated_paths ||= ["app/graphql/generated", "app/graphql/*/generated"]
 
+    # Reusable named fragments, defined once and available to every query —
+    # each query inlines only the ones it (transitively) spreads, so the sent
+    # query stays self-contained.
+    def fragments_paths = @fragments_paths ||= ["app/graphql/fragments"]
+
     def queries_path = queries_paths.first
     def generated_path = generated_paths.first
+    def fragments_path = fragments_paths.first
 
     def queries_path=(path)
       @queries_paths = path.nil? ? nil : [path]
@@ -88,26 +94,35 @@ module GraphWeaver
 
     def schema_path = @schema_path || "app/graphql/schema.json"
 
-    # The shared-inputs module name: set it globally, pass inputs_module:
-    # per generate!, or let it derive from the output path — the
-    # directory above generated/ names the schema in multi-schema
-    # layouts (app/graphql/github/generated => GithubInputs); the
-    # conventional layout (and anything unrecognizable) stays
-    # GraphQLInputs.
-    attr_writer :inputs_module
+    # The shared-inputs / shared-unions module names: set them globally, pass
+    # inputs_module:/unions_module: per generate!, or let them derive from the
+    # output path — the directory above generated/ names the schema in
+    # multi-schema layouts (app/graphql/github/generated => GithubInputs /
+    # GithubUnions); the conventional layout (and anything unrecognizable)
+    # stays GraphQLInputs / GraphQLUnions.
+    attr_writer :inputs_module, :unions_module
 
     def inputs_module(output = generated_path)
-      return @inputs_module if @inputs_module
+      @inputs_module || derive_module("Inputs", output)
+    end
 
+    def unions_module(output = generated_path)
+      @unions_module || derive_module("Unions", output)
+    end
+
+    # Name a shared module from the output path: <Schema><suffix> in a
+    # multi-schema layout, else GraphQL<suffix>.
+    def derive_module(suffix, output)
       segments = File.expand_path(output.to_s).split(File::SEPARATOR)
       segments.pop if segments.last == "generated"
       parent = segments.last.to_s
       if parent.match?(/\A[a-zA-Z]\w*\z/) && !%w[graphql app lib spec support test].include?(parent)
-        "#{Inflect.camelize(parent)}Inputs"
+        "#{Inflect.camelize(parent)}#{suffix}"
       else
-        "GraphQLInputs"
+        "GraphQL#{suffix}"
       end
     end
+    private :derive_module
 
     # Generate every .graphql query in a directory into checked-in Ruby
     # files. Paths default to the conventions above; schema: defaults to
@@ -118,11 +133,12 @@ module GraphWeaver
     # person.graphql => person_query.rb defining PersonQuery. Returns the
     # written paths. Pair with a freshness spec (docs/generated_modules.md).
     def generate!(schema: nil, queries: queries_path, output: generated_path, client: nil,
-      shared_inputs: true, inputs_module: nil)
+      inputs_module: nil, unions_module: nil)
       schema ||= locate_schema!
       inputs_module ||= self.inputs_module(output)
+      unions_module ||= self.unions_module(output)
 
-      plan = generation_plan(queries:, schema:, client:, shared_inputs:, inputs_module:)
+      plan = generation_plan(queries:, schema:, client:, inputs_module:, unions_module:)
       written = plan.map do |filename, source|
         target = File.join(output, filename)
         FileUtils.mkdir_p(File.dirname(target))
@@ -131,9 +147,9 @@ module GraphWeaver
         target
       end
 
-      # a type dropped from the schema must not linger as a stale file —
-      # inputs/ is wholly generated, so pruning is safe
-      (Dir[File.join(output, "inputs", "*.rb")] - written).each do |orphan|
+      # a type dropped from the schema (or a union no longer hoisted) must not
+      # linger as a stale file — inputs/ and unions.rb are wholly generated
+      (shared_artifacts(output) - written).each do |orphan|
         File.delete(orphan)
         log(:info) { "pruned #{orphan}" }
       end
@@ -141,6 +157,13 @@ module GraphWeaver
       written
     end
 
+    # The wholly-generated shared-artifact files under output (inputs/*.rb and
+    # unions.rb) — safe to prune when regeneration no longer produces them.
+    def shared_artifacts(output)
+      Dir[File.join(output, "inputs", "*.rb")] + Dir[File.join(output, "unions.rb")]
+    end
+    private :shared_artifacts
+
     # The freshness guard: raise unless every generated file matches what
     # the current schema + queries + scalar registrations would produce.
     # One line in a spec, or `rake graph_weaver:verify` in CI:
@@ -149,16 +172,17 @@ module GraphWeaver
     #        GraphWeaver.verify_generated!
     #      end
     def verify_generated!(schema: nil, queries: queries_path, output: generated_path, client: nil,
-      shared_inputs: true, inputs_module: nil)
+      inputs_module: nil, unions_module: nil)
       schema ||= locate_schema!
       inputs_module ||= self.inputs_module(output)
-      plan = generation_plan(queries:, schema:, client:, shared_inputs:, inputs_module:)
+      unions_module ||= self.unions_module(output)
+      plan = generation_plan(queries:, schema:, client:, inputs_module:, unions_module:)
       stale = plan.filter_map do |filename, source|
         target = File.join(output, filename)
         target unless File.exist?(target) && File.read(target) == source
       end
-      # strays: a type file the current schema no longer produces
-      stale += Dir[File.join(output, "inputs", "*.rb")] - plan.map { |f, _| File.join(output, f) }
+      # strays: a shared-artifact file the current schema + queries no longer produce
+      stale += shared_artifacts(output) - plan.map { |f, _| File.join(output, f) }
 
       unless stale.empty?
         raise Error, "stale generated queries — regenerate (rake graph_weaver:generate): #{stale.join(", ")}"
@@ -192,34 +216,49 @@ module GraphWeaver
     end
     private :locate_schema!
 
-    # (filename, source) per artifact: shared_inputs (the default) emits
-    # every variable type once into inputs.rb, with query modules
-    # aliasing what they use — the difference between hundreds of
-    # duplicated bool_exp structs and one copy per schema.
-    def generation_plan(queries:, schema:, client:, shared_inputs:, inputs_module: self.inputs_module)
-      namespace = shared_inputs ? inputs_module : nil
+    # (filename, source) per artifact. Every variable type is emitted once into
+    # inputs.rb, and each named shared fragment spread as a whole-union field
+    # once into unions.rb, with query modules aliasing what they use — the
+    # difference between hundreds of duplicated bool_exp structs (or the same
+    # union re-typed per query) and one copy per schema. (Single-query parse
+    # inlines both — there's no cross-query set to share against.)
+    def generation_plan(queries:, schema:, client:, inputs_module: self.inputs_module,
+      unions_module: self.unions_module, fragments: fragments_paths)
       used = { inputs: [], enums: [], mapped: [] }
+      used_unions = []
+      shared = Codegen.load_fragments(fragments)
 
       plan = Dir[File.join(queries, "*.graphql")].sort.map do |path|
         base = File.basename(path, ".graphql")
+        source = File.read(path)
         codegen = Codegen.new(
           schema:,
-          query: File.read(path),
+          query: Codegen.inline_fragments(source, shared),
           module_name: "#{Inflect.camelize(base)}Query",
           client:,
-          inputs_namespace: namespace,
+          inputs_namespace: inputs_module,
+          unions_namespace: unions_module,
+          hoistable_unions: Codegen.shared_fragment_spreads(source, shared),
         )
-        source = codegen.generate
+        out = codegen.generate
         codegen.variable_type_names.each { |kind, names| used[kind] |= names }
-        ["#{base}_query.rb", source]
+        used_unions |= codegen.used_union_names
+        ["#{base}_query.rb", out]
       end
 
-      if namespace && used.values.any?(&:any?)
-        shared = Codegen.generate_inputs(
-          schema:, module_name: namespace,
+      if inputs_module && used.values.any?(&:any?)
+        inputs = Codegen.generate_inputs(
+          schema:, module_name: inputs_module,
           input_types: used[:inputs], enum_types: used[:enums] + used[:mapped],
         )
-        plan = shared.to_a + plan
+        plan = inputs.to_a + plan
+      end
+
+      if unions_module && used_unions.any?
+        unions = Codegen.generate_unions(
+          schema:, module_name: unions_module, fragments: shared, names: used_unions,
+        )
+        plan = unions.to_a + plan
       end
 
       plan
@@ -238,6 +277,25 @@ module GraphWeaver
     # a registration always wins.
     attr_accessor :auto_coerce
 
+    # Whether generated modules/structs emit `extend T::Sig` (so `sig`
+    # resolves standalone). Default (nil) auto-detects: an app that globally
+    # injects T::Sig (`class Module; include T::Sig`) makes the per-struct
+    # extend redundant — rubocop's Sorbet/RedundantExtendTSig flags it — so
+    # generation skips it. Force with true/false. Resolved at generation time.
+    #
+    #      GraphWeaver.extend_t_sig = false   # never emit (rely on a global include)
+    attr_writer :extend_t_sig
+
+    # The resolved boolean codegen uses: the explicit setting, else emit
+    # unless T::Sig is globally injected into Module.
+    def extend_t_sig?
+      @extend_t_sig.nil? ? !global_tsig? : @extend_t_sig
+    end
+
+    # Whether the host app has globally injected T::Sig into every module
+    # (`class Module; include T::Sig`) — extracted so it's stubbable in tests.
+    def global_tsig? = Module.include?(T::Sig)
+
     # Teach the generator how a GraphQL custom scalar deserializes into a
     # rich Ruby object (and serializes back onto the wire when used as a
     # variable):
@@ -256,7 +314,15 @@ module GraphWeaver
     # raw input (e.g. "12.00"), running the latter through the cast before
     # serializing — it raises on bad input, so some safety survives. Built-in
     # scalars are pre-registered the same way, so this also overrides them.
-    # Call before generating.
+    #
+    # 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 (a `Date` for `User.birthday`, a `Time` elsewhere):
+    #
+    #      GraphWeaver.register_scalar("User.birthday", Date)
+    #
+    # A field-level override wins over the scalar-name registration. Same
+    # signature either way. Call before generating.
     def register_scalar(graphql_name, type, cast: nil, serialize: nil, requires: nil, coerce: nil)
       Codegen.register_scalar(graphql_name, type, cast:, serialize:, requires:, coerce:)
     end
@@ -322,11 +388,13 @@ module GraphWeaver
     # falling back to "Query" for anonymous operations — collisions are
     # impossible since each parse gets its own container). Pass name: to
     # override, client: to bake the module's default client/transport.
-    def parse(schema:, query:, name: nil, client: nil, scalars: nil, enums: nil, types: nil)
+    def parse(schema:, query:, name: nil, client: nil, scalars: nil, enums: nil, types: nil,
+      fragments: fragments_paths)
       if query.end_with?(".graphql", ".gql")
         name ||= "#{Inflect.camelize(File.basename(query, ".*"))}Query"
         query = File.read(query)
       end
+      query = Codegen.inline_fragments(query, Codegen.load_fragments(fragments))
 
       Codegen.parse(schema:, query:, module_name: name, client:, scalars:, enums:, types:)
     end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: graph_weaver
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Daniel Pepper