graph_weaver 0.2.2 → 0.4.0

data/lib/graph_weaver/codegen/enum_type.rb

@@ -90,19 +90,19 @@ class GraphWeaver::Codegen
     # Attach app-owned helper modules to every struct generated from a
     # GraphQL type — the logic stays in your code, generation wires it in:
     #
-    #      GraphWeaver.register_type("Pet", PetHelpers)
+    #      GraphWeaver.extend_type("Pet", PetHelpers)
     #
     # Or build the mixin inline — the block is module_eval'd into a fresh
     # module auto-named GraphWeaver::TypeHelpers::<Type>. Handy for quick
     # decoration; srb tc can't see into block-defined methods, so prefer
     # a named module where static checking matters:
     #
-    #      GraphWeaver.register_type("Pet") do
+    #      GraphWeaver.extend_type("Pet") do
     #        def display_name = "#{name} the pet"
     #      end
     #
     # Additive: repeated registrations (and client-scoped ones) stack.
-    def register_type(graphql_name, *mixins, requires: nil, &block)
+    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)
     end
@@ -111,7 +111,7 @@ class GraphWeaver::Codegen
       @type_registry ||= {}
     end
 
-    # shared with Client#register_type: build/validate the mixins and
+    # 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)
       mixins = mixins.dup
@@ -143,7 +143,7 @@ class GraphWeaver::Codegen
 end
 
 module GraphWeaver
-  # Home of block-built type helpers (register_type with a block), which
+  # Home of block-built type helpers (extend_type with a block), which
   # need constant names so generated files can reference them.
   module TypeHelpers; end
 end

data/lib/graph_weaver/codegen/nodes.rb

@@ -147,7 +147,7 @@ class GraphWeaver::Codegen
 
     attr_reader :class_name, :fields
     # the GraphQL type this struct was generated from, and any registered
-    # helper modules to include (see Codegen.register_type)
+    # helper modules to include (see Codegen.extend_type)
     attr_accessor :graphql_type, :mixins
 
     def initialize(class_name)
@@ -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,13 +260,98 @@ 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) &&
       DidYouMean::SpellChecker.new(dictionary: schema.types.keys).correct(name).first
     hint = suggestion ? " — did you mean '#{suggestion}'?" : ""
-    raise GraphWeaver::Error, "register_#{kind}(#{name.inspect}) matches no type in this schema#{hint}"
+    # the type registry is reached via extend_type; scalars/enums via register_*
+    method = kind == "type" ? "extend_type" : "register_#{kind}"
+    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.
@@ -249,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
@@ -289,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))
@@ -303,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
@@ -339,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)
@@ -365,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
@@ -460,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