graph_weaver 0.2.0 → 0.2.1

data/lib/graph_weaver/codegen/nodes.rb

@@ -1,11 +1,29 @@
 # typed: true
 # frozen_string_literal: true
 
+require "forwardable"
+
 # The typed intermediate representation of a query selection: one node
 # per GraphQL type shape, each knowing its Sorbet prop type and the
 # cast/serialize code to emit.
 class GraphWeaver::Codegen
-  class Scalar
+  # Protocol defaults — subclasses override what differs. The full node
+  # protocol: bare_type, prop_type, cast(expr, depth), identity?,
+  # serialize(expr, depth), serialize_identity?, coerce?, coerce(expr),
+  # coerce_input_type, hash_coerce(expr, depth), hash_coerce_identity?,
+  # non_null?, nested.
+  class Node
+    def bare_type = raise(GraphWeaver::Error, "#{self.class} must define bare_type")
+    def prop_type = "T.nilable(#{bare_type})"
+    def identity? = false
+    def serialize_identity? = false
+    def coerce? = false
+    def hash_coerce_identity? = false
+    def non_null? = false
+    def nested = nil
+  end
+
+  class Scalar < Node
     # takes a resolved ScalarType — the generator picks it from the
     # client-scoped overlay or the global registry
     def initialize(scalar_type)
@@ -52,34 +70,27 @@ class GraphWeaver::Codegen
     end
 
     def hash_coerce_identity? = !@scalar.coerce?
-
-    def non_null? = false
-    def nested = nil
   end
 
-  class NonNull
+  # NonNull is its inner node with the nilability stripped — everything
+  # else passes through.
+  class NonNull < Node
+    extend Forwardable
+
     attr_reader :of
 
+    def_delegators :@of, :bare_type, :cast, :identity?, :serialize, :serialize_identity?,
+      :coerce?, :coerce, :coerce_input_type, :hash_coerce, :hash_coerce_identity?, :nested
+
     def initialize(of)
       @of = of
     end
 
-    def bare_type = @of.bare_type
     def prop_type = bare_type
-    def cast(expr, depth) = @of.cast(expr, depth)
-    def identity? = @of.identity?
-    def serialize(expr, depth) = @of.serialize(expr, depth)
-    def serialize_identity? = @of.serialize_identity?
-    def coerce? = @of.coerce?
-    def coerce(expr) = @of.coerce(expr)
-    def coerce_input_type = @of.coerce_input_type
-    def hash_coerce(expr, depth) = @of.hash_coerce(expr, depth)
-    def hash_coerce_identity? = @of.hash_coerce_identity?
     def non_null? = true
-    def nested = @of.nested
   end
 
-  class List
+  class List < Node
     attr_reader :of
 
     def initialize(of)
@@ -90,10 +101,6 @@ class GraphWeaver::Codegen
       "T::Array[#{@of.prop_type}]"
     end
 
-    def prop_type
-      "T.nilable(#{bare_type})"
-    end
-
     def cast(expr, depth)
       var = "v#{depth}"
       element = if @of.non_null? || @of.identity?
@@ -119,7 +126,6 @@ class GraphWeaver::Codegen
     end
 
     def serialize_identity? = @of.serialize_identity?
-    def coerce? = false
 
     def hash_coerce(expr, depth)
       var = "v#{depth}"
@@ -133,11 +139,10 @@ class GraphWeaver::Codegen
     end
 
     def hash_coerce_identity? = @of.hash_coerce_identity?
-    def non_null? = false
     def nested = @of.nested
   end
 
-  class ObjectNode
+  class ObjectNode < Node
     Field = Struct.new(:prop, :key, :node)
 
     attr_reader :class_name, :fields
@@ -153,20 +158,14 @@ class GraphWeaver::Codegen
 
     def bare_type = class_name
 
-    def prop_type
-      "T.nilable(#{bare_type})"
-    end
-
     def cast(expr, _depth)
       "#{class_name}.from_h(#{expr})"
     end
 
-    def identity? = false
-    def non_null? = false
     def nested = self
   end
 
-  class EnumNode
+  class EnumNode < Node
     attr_reader :class_name, :values
 
     def initialize(class_name, values)
@@ -176,22 +175,14 @@ class GraphWeaver::Codegen
 
     def bare_type = class_name
 
-    def prop_type
-      "T.nilable(#{bare_type})"
-    end
-
     def cast(expr, _depth)
       "#{class_name}.deserialize(#{expr})"
     end
 
-    def identity? = false
-
     def serialize(expr, _depth)
       "#{expr}.serialize"
     end
 
-    def serialize_identity? = false
-
     # enums always coerce: a kwarg or hash field accepts the T::Enum or
     # its wire value (deserialize raises on anything else)
     def coerce? = true
@@ -202,8 +193,6 @@ class GraphWeaver::Codegen
 
     def coerce_input_type = "T.any(#{class_name}, String)"
     def hash_coerce(expr, _depth) = coerce(expr)
-    def hash_coerce_identity? = false
-    def non_null? = false
     def nested = self
   end
 
@@ -211,7 +200,7 @@ class GraphWeaver::Codegen
   # generated enum class — instead module-level <NAME>_FROM_WIRE /
   # <NAME>_TO_WIRE constants translate at the boundary. fallback: makes
   # casting absorb unknown wire values (inputs stay strict).
-  class MappedEnum
+  class MappedEnum < Node
     attr_reader :graphql_name, :mapping
 
     def initialize(enum_type, wire_values)
@@ -226,10 +215,6 @@ class GraphWeaver::Codegen
 
     def bare_type = @type_name
 
-    def prop_type
-      "T.nilable(#{bare_type})"
-    end
-
     def cast(expr, _depth)
       if @fallback
         "#{const_prefix}_FROM_WIRE.fetch(#{expr}) { #{fallback_const} }"
@@ -238,14 +223,10 @@ class GraphWeaver::Codegen
       end
     end
 
-    def identity? = false
-
     def serialize(expr, _depth)
       "#{const_prefix}_TO_WIRE.fetch(#{expr})"
     end
 
-    def serialize_identity? = false
-
     # kwargs and hash fields accept the member or its wire value; unlike
     # casting, bad input raises even with a fallback (a typo'd input is
     # our bug, not server drift)
@@ -257,9 +238,6 @@ class GraphWeaver::Codegen
 
     def coerce_input_type = "T.any(#{@type_name}, String)"
     def hash_coerce(expr, _depth) = coerce(expr)
-    def hash_coerce_identity? = false
-    def non_null? = false
-    def nested = nil
   end
 
   # A single-condition narrowing of an abstract field (`... on Pet { ... }`
@@ -267,7 +245,7 @@ class GraphWeaver::Codegen
   # nil when it doesn't — a non-match's response object carries no
   # matching fields, so the hash arrives empty. Always nilable, whatever
   # the schema's nullability, because narrowing filters.
-  class NarrowedNode
+  class NarrowedNode < Node
     def initialize(of)
       @of = of
     end
@@ -275,20 +253,14 @@ class GraphWeaver::Codegen
     def class_name = @of.class_name
     def bare_type = @of.bare_type
 
-    def prop_type
-      "T.nilable(#{bare_type})"
-    end
-
     def cast(expr, depth)
       "(#{expr}.empty? ? nil : #{@of.cast(expr, depth)})"
     end
 
-    def identity? = false
-    def non_null? = false
     def nested = @of
   end
 
-  class UnionNode
+  class UnionNode < Node
     attr_reader :class_name, :members # graphql type name => ObjectNode
 
     def initialize(class_name, members)
@@ -298,16 +270,10 @@ class GraphWeaver::Codegen
 
     def bare_type = "#{class_name}::Type"
 
-    def prop_type
-      "T.nilable(#{bare_type})"
-    end
-
     def cast(expr, _depth)
       "#{class_name}.from_h(#{expr})"
     end
 
-    def identity? = false
-    def non_null? = false
     def nested = self
   end
 
@@ -315,7 +281,7 @@ class GraphWeaver::Codegen
   # serialize produces the wire hash. Inputs never cast FROM the wire.
   # Joins the coerce protocol so execute kwargs accept plain hashes,
   # normalized (and type-checked) through the generated .coerce.
-  class InputNode
+  class InputNode < Node
     Field = Struct.new(:prop, :wire, :node, :required)
 
     attr_reader :class_name, :fields
@@ -327,18 +293,12 @@ class GraphWeaver::Codegen
 
     def bare_type = class_name
 
-    def prop_type
-      "T.nilable(#{bare_type})"
-    end
-
     def serialize(expr, _depth)
       "#{expr}.serialize"
     end
 
-    def serialize_identity? = false
-
     def cast(_expr, _depth)
-      raise NotImplementedError, "input objects are never cast from responses"
+      raise GraphWeaver::Error, "input objects are never cast from responses"
     end
 
     def coerce? = true
@@ -347,10 +307,5 @@ class GraphWeaver::Codegen
 
     # building a struct field from a caller-supplied plain hash value
     def hash_coerce(expr, _depth) = "#{class_name}.coerce(#{expr})"
-    def hash_coerce_identity? = false
-
-    def identity? = false
-    def non_null? = false
-    def nested = nil
   end
 end

data/lib/graph_weaver/codegen.rb

@@ -19,6 +19,7 @@ require "sorbet-runtime"
 # codegen/nodes.rb (the typed IR), codegen/emit.rb (source emission);
 # this file holds the public API and the query walk.
 require_relative "hints"
+require_relative "input_struct"
 require_relative "inflect"
 require_relative "selection"
 require_relative "codegen/enum_type"
@@ -45,9 +46,11 @@ class GraphWeaver::Codegen
   # generation stays strict — a checked-in file deserves a deliberate
   # name). scalars:/enums:/types: are client-scoped overlays consulted
   # before the global registries (ScalarType, EnumType, and arrays of
-  # mixin modules, each keyed by GraphQL name).
+  # 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.
   def initialize(schema:, query:, module_name: nil, client: nil, default_module_name: nil,
-    scalars: nil, enums: nil, types: nil)
+    scalars: nil, enums: nil, types: nil, inputs_namespace: nil)
     @schema = schema
     @query = query.strip
     @module_name = module_name
@@ -55,6 +58,7 @@ class GraphWeaver::Codegen
     @scalars = scalars || {}
     @enums = enums || {}
     @types = types || {}
+    @inputs_namespace = inputs_namespace
     @client_const = self.class.client_const(client)
 
     if client && @client_const.nil?
@@ -100,6 +104,40 @@ class GraphWeaver::Codegen
     mod
   end
 
+  # The schema-level variable types this query touched, by GraphQL
+  # name — the generate! workflow unions these across queries to decide
+  # what the shared inputs module must contain.
+  def variable_type_names
+    { inputs: @variable_inputs.keys, enums: @variable_enums.keys, mapped: @mapped_enums.keys }
+  end
+
+  # 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
+  # schema migration diffs only the types it touched. Returns
+  # { relative_filename => source }.
+  def self.generate_inputs(schema:, module_name:, input_types: [], enum_types: [],
+    scalars: nil, enums: nil, types: nil)
+    codegen = new(schema:, query: "", module_name:, scalars:, enums:, types:)
+    codegen.generate_inputs(input_types, enum_types)
+  end
+
+  def generate_inputs(input_types, enum_types)
+    unless @module_name&.match?(/\A[A-Z]\w*(::[A-Z]\w*)*\z/)
+      raise ArgumentError, "inputs module name must be a constant name, got #{@module_name.inspect}"
+    end
+
+    @variable_enums = {}
+    @variable_inputs = {}
+    @mapped_enums = {}
+    @requires = []
+
+    enum_types.sort.each { |name| variable_core(@schema.get_type(name)) }
+    input_types.sort.each { |name| input_node(@schema.get_type(name)) }
+
+    emit_inputs_files
+  end
+
   VarDef = Struct.new(:kwarg, :wire, :node, :required)
 
   # Names that cannot appear bare in generated Ruby: keywords aren't
@@ -164,61 +202,7 @@ class GraphWeaver::Codegen
 
     root = object_node(root_type, operation.selections, "Result")
 
-    out = []
-    out << "# typed: strict"
-    out << "# frozen_string_literal: true"
-    out << ""
-    out << "# Generated by GraphWeaver — do not edit."
-    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"
-    out << ""
-    # 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
-    delimiter = "GRAPHQL"
-    delimiter += "_" while @query.match?(/^\s*#{delimiter}\s*$/)
-    out << "  QUERY = T.let(<<~'#{delimiter}', String)"
-    @query.each_line { |line| out << "    #{line}".rstrip }
-    out << "  #{delimiter}"
-    out << ""
-    @mapped_enums.each_value do |mapped|
-      emit_mapped_enum(mapped, out, 1)
-      out << ""
-    end
-    @variable_enums.each_value do |enum|
-      emit_enum(enum, out, 1)
-      out << ""
-    end
-    inputs, cyclic = ordered_inputs
-    if cyclic
-      # Recursive input types (Hasura bool_exp et al) reference each other,
-      # so no definition order satisfies the runtime — forward-declare every
-      # class empty, then let the full definitions below reopen with props.
-      # eval'd so srb sees only the full bodies (reopening a T::Struct to
-      # add props is a static error; adding them at runtime is fine).
-      out << "  # runtime-only forward declarations: these input types reference"
-      out << "  # each other, so the full definitions below need the constants"
-      out << "  eval(<<~RUBY, binding, __FILE__, __LINE__ + 1)"
-      inputs.each { |input| out << "    class #{input.class_name} < T::Struct; end" }
-      out << "  RUBY"
-      out << ""
-    end
-    inputs.each do |input|
-      emit_input(input, out, 1)
-      out << ""
-    end
-    emit_nested(root, out, 1)
-    out << ""
-    emit_execute(out, variables, flatten: flatten_input(variables))
-    out << "end"
-
-    out.join("\n") + "\n"
+    emit_module(root, variables)
   end
 
   private
@@ -251,20 +235,6 @@ class GraphWeaver::Codegen
     end
   end
 
-  # The Relay convention — an operation whose only variable is a required
-  # input object — reads better flattened: the input's fields become
-  # execute's kwargs directly, and the wrapping level is rebuilt on the
-  # wire. Multi-variable (or nullable-input) operations keep the
-  # variable-per-kwarg surface.
-  def flatten_input(variables)
-    return unless variables.size == 1
-
-    var = variables.first
-    return unless var.required && var.node.is_a?(NonNull)
-
-    input = var.node.of
-    input if input.is_a?(InputNode)
-  end
 
   # Selection#each_field, collected by result key (codegen groups
   # repeated selections of one field so it can merge them)
@@ -467,40 +437,7 @@ class GraphWeaver::Codegen
 
   # The InputNodes a struct's fields reference, through NON_NULL/LIST
   # wrappers — the edges of the input dependency graph.
-  def input_references(node)
-    node.fields.filter_map do |field|
-      child = field.node
-      child = child.of while child.respond_to?(:of)
-      child if child.is_a?(InputNode)
-    end
-  end
-
-  # Input structs in dependency order (referenced types before their
-  # referrers) so each emitted const names an already-defined class.
-  # Cycles make that impossible — flagged so emission can forward-declare
-  # every input class first, then reopen each to add its props.
-  def ordered_inputs
-    ordered = []
-    seen = {} # node => :done | :visiting (bool_exp graphs get big)
-    cyclic = T.let(false, T::Boolean)
-
-    visit = lambda do |node|
-      next if seen[node] == :done
-
-      if seen[node] == :visiting
-        cyclic = true
-        next
-      end
-
-      seen[node] = :visiting
-      input_references(node).each(&visit)
-      seen[node] = :done
-      ordered << node
-    end
-    @variable_inputs.each_value(&visit)
 
-    [ordered, cyclic]
-  end
 
   # Registered helper-module names for a GraphQL type (additive: global
   # registrations plus this client's), collecting their requires.

data/lib/graph_weaver/input_struct.rb

@@ -0,0 +1,59 @@
+# typed: true
+# frozen_string_literal: true
+
+require "sorbet-runtime"
+
+require_relative "hints"
+
+module GraphWeaver
+  # Runtime for generated input structs. Each struct declares its typed
+  # consts plus a compact FIELDS table — (prop, wire name, requiredness,
+  # serializer, coercer) per field, with the conversions emitted as
+  # lambdas — and this module is the loop that drives it. One copy here
+  # instead of unrolled methods in every struct, which is the difference
+  # between ~2 lines and ~6 lines per field when a Hasura bool_exp pulls
+  # hundreds of input types into one module.
+  module InputStruct
+    include Kernel # for sorbet: hosts are T::Structs
+
+    # serializer/coercer are code-as-data from the generated file; nil
+    # means identity (the wire value passes through untouched)
+    Field = Struct.new(:prop, :wire, :required, :serializer, :coercer)
+
+    def self.included(base)
+      base.extend(ClassMethods)
+    end
+
+    # the wire hash — optional fields left nil stay off the wire
+    def serialize
+      self.class.const_get(:FIELDS).each_with_object({}) do |field, wire|
+        value = public_send(field.prop)
+        next if value.nil? && !field.required
+
+        wire[field.wire] = field.serializer && !value.nil? ? field.serializer.call(value) : value
+      end
+    end
+    alias_method :to_h, :serialize
+
+    module ClassMethods
+      include Kernel
+
+      # Build from a plain hash (underscored keys, Symbol or String):
+      # enums accept their wire values, nested inputs accept hashes; the
+      # struct's types are enforced on construction, and unknown keys
+      # raise with a spellchecked hint.
+      def coerce(value)
+        return value if value.is_a?(self)
+
+        # a typo'd key must not silently drop off the wire
+        GraphWeaver::Hints.validate_keys!(self, value)
+
+        fields = T.unsafe(self).const_get(:FIELDS)
+        T.unsafe(self).new(**fields.to_h do |field|
+          raw = value.key?(field.prop) ? value[field.prop] : value[field.prop.to_s]
+          [field.prop, raw.nil? || field.coercer.nil? ? raw : field.coercer.call(raw)]
+        end)
+      end
+    end
+  end
+end

data/lib/graph_weaver/railtie.rb

@@ -24,6 +24,7 @@ class GraphWeaver::Railtie < Rails::Railtie
   end
 
   initializer "graph_weaver.load_generated", after: :load_config_initializers do
-    GraphWeaver.load_generated! if Dir.exist?(GraphWeaver.generated_path)
+    # entries may be globs, so Dir[] rather than Dir.exist?
+    GraphWeaver.load_generated! if GraphWeaver.generated_paths.any? { |path| Dir[path].any? }
   end
 end

data/lib/graph_weaver/rspec.rb

@@ -8,14 +8,12 @@ require_relative "testing"
 #
 #      require "graph_weaver/rspec"
 #
-# That one line is the whole setup in a conventional app: the schema
-# auto-locates from the committed dump (GraphWeaver.schema_path) and
-# auto_fake defaults on, so every example runs against a schema-correct
-# fake. Configure to override:
+# Then opt in to per-example fakes (explicit on purpose — silently
+# swapping every example onto a fake is too surprising to be a default):
 #
 #      GraphWeaver::Testing.configure do |config|
-#        config.schema = MySchema     # instead of the located dump
-#        config.auto_fake = false     # opt out of per-example fakes
+#        config.auto_fake = true      # every example runs against a fake
+#        # config.schema = MySchema   # optional: the committed dump auto-locates
 #      end
 #
 # What it wires up:

data/lib/graph_weaver/testing.rb

@@ -49,10 +49,10 @@ module GraphWeaver
         @mode = nil # auto
         @schema = nil
         @cassette_dir = "spec/cassettes"
-        # on by default — engages only when a schema resolves (below), so
-        # requiring graph_weaver/rspec in a conventional app is
-        # zero-config; config.auto_fake = false opts out
-        @auto_fake = true
+        # explicit opt-in: swapping every example onto a fake is too
+        # surprising to be a default — a little friction beats unexpected
+        # behavior (the schema still auto-locates once you opt in)
+        @auto_fake = false
         # GRAPHWEAVER_RECORD=1 rspec ...  -> Cassette.use re-records
         @record = !ENV["GRAPHWEAVER_RECORD"].to_s.empty?
         # anonymize responses as they're recorded (needs config.schema)

data/lib/graph_weaver/version.rb

@@ -1,3 +1,3 @@
 module GraphWeaver
-  VERSION = "0.2.0"
+  VERSION = "0.2.1"
 end