graph_weaver 0.3.0 → 0.4.4

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.3.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
@@ -67,7 +64,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 +72,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 +91,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 +130,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 +144,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 +154,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 +169,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 +213,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 +274,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 +311,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
@@ -282,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"
@@ -296,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 —
@@ -322,11 +387,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.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)