graph_weaver 0.2.2 → 0.4.0

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
@@ -285,19 +351,19 @@ module GraphWeaver
     # GraphQL type — derived values live as methods next to the honest
     # wire data, and srb tc checks them against each query's selection:
     #
-    #      GraphWeaver.register_type("Pet", PetHelpers)
+    #      GraphWeaver.extend_type("Pet", PetHelpers)
     #
     # Or build the mixin inline with a block (module_eval'd into an
     # auto-named module — quick, but invisible to srb tc):
     #
-    #      GraphWeaver.register_type("Pet") do
+    #      GraphWeaver.extend_type("Pet") do
     #        def display_name = "#{name} the pet"
     #      end
     #
     # Additive (repeated and client-scoped registrations stack). Global;
-    # client.register_type scopes to one client.
-    def register_type(graphql_name, *mixins, requires: nil, &block)
-      Codegen.register_type(graphql_name, *mixins, requires:, &block)
+    # client.extend_type scopes to one client.
+    def extend_type(graphql_name, *mixins, requires: nil, &block)
+      Codegen.extend_type(graphql_name, *mixins, requires:, &block)
     end
 
     # Restore the built-in scalars, dropping every custom registration —
@@ -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.2.2
+  version: 0.4.0
 platform: ruby
 authors:
 - Daniel Pepper
@@ -227,6 +227,7 @@ extra_rdoc_files: []
 files:
 - ".yardopts"
 - CHANGELOG.md
+- CLAUDE.md
 - Gemfile
 - Gemfile.lock
 - LICENSE.txt
@@ -236,6 +237,7 @@ files:
 - README.md
 - docs/cassettes.md
 - docs/errors.md
+- docs/federation.md
 - docs/generated_modules.md
 - docs/getting_started.md
 - docs/logging.md