graph_weaver 0.2.0 → 0.2.2

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.2"
 end

data/lib/graph_weaver.rb

@@ -4,6 +4,7 @@ require "sorbet-runtime"
 require_relative "graph_weaver/logging"
 require_relative "graph_weaver/errors"
 require_relative "graph_weaver/hints"
+require_relative "graph_weaver/input_struct"
 require_relative "graph_weaver/response"
 require_relative "graph_weaver/inflect"
 require_relative "graph_weaver/codegen"
@@ -56,15 +57,58 @@ module GraphWeaver
       target.is_a?(Client) ? target.transport! : target
     end
 
-    # Conventional locations, factory_bot-style: used as defaults by
-    # generate!, verify_generated!, load_generated!, and the rake tasks;
-    # override the accessors or pass paths.
-    attr_writer :queries_path, :generated_path, :schema_path
+    # Conventional locations, factory_bot-style — LISTS, so extra
+    # locations (a test-only dir, an engine's) can be appended and every
+    # loader walks them all:
+    #
+    #      # e.g. in spec/support/graph_weaver.rb
+    #      GraphWeaver.generated_paths << "spec/support/graphql/generated"
+    #      GraphWeaver.queries_paths << "spec/support/graphql/queries"
+    #
+    # 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
+
+    # Entries may be glob patterns — the generated default also matches
+    # per-schema layouts (app/graphql/github/generated). Queries stay
+    # single-schema: load_queries! parses everything against one client.
+    def queries_paths = @queries_paths ||= ["app/graphql/queries"]
+    def generated_paths = @generated_paths ||= ["app/graphql/generated", "app/graphql/*/generated"]
+
+    def queries_path = queries_paths.first
+    def generated_path = generated_paths.first
+
+    def queries_path=(path)
+      @queries_paths = path.nil? ? nil : [path]
+    end
+
+    def generated_path=(path)
+      @generated_paths = path.nil? ? nil : [path]
+    end
 
-    def queries_path = @queries_path || "app/graphql/queries"
-    def generated_path = @generated_path || "app/graphql/generated"
     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
+
+    def inputs_module(output = generated_path)
+      return @inputs_module if @inputs_module
+
+      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"
+      else
+        "GraphQLInputs"
+      end
+    end
+
     # Generate every .graphql query in a directory into checked-in Ruby
     # files. Paths default to the conventions above; schema: defaults to
     # the dump at schema_path (any supported extension):
@@ -73,16 +117,28 @@ 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)
+    def generate!(schema: nil, queries: queries_path, output: generated_path, client: nil,
+      shared_inputs: true, inputs_module: nil)
       schema ||= locate_schema!
-      FileUtils.mkdir_p(output)
+      inputs_module ||= self.inputs_module(output)
 
-      each_query(queries, schema:, client:).map do |base, source|
-        target = File.join(output, "#{base}_query.rb")
+      plan = generation_plan(queries:, schema:, client:, shared_inputs:, inputs_module:)
+      written = plan.map do |filename, source|
+        target = File.join(output, filename)
+        FileUtils.mkdir_p(File.dirname(target))
         File.write(target, source)
         log(:info) { "generated #{target}" }
         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|
+        File.delete(orphan)
+        log(:info) { "pruned #{orphan}" }
+      end
+
+      written
     end
 
     # The freshness guard: raise unless every generated file matches what
@@ -92,12 +148,17 @@ module GraphWeaver
     #      it "generated queries are current" do
     #        GraphWeaver.verify_generated!
     #      end
-    def verify_generated!(schema: nil, queries: queries_path, output: generated_path, client: nil)
+    def verify_generated!(schema: nil, queries: queries_path, output: generated_path, client: nil,
+      shared_inputs: true, inputs_module: nil)
       schema ||= locate_schema!
-      stale = each_query(queries, schema:, client:).filter_map do |base, source|
-        target = File.join(output, "#{base}_query.rb")
+      inputs_module ||= self.inputs_module(output)
+      plan = generation_plan(queries:, schema:, client:, shared_inputs:, inputs_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) }
 
       unless stale.empty?
         raise Error, "stale generated queries — regenerate (rake graph_weaver:generate): #{stale.join(", ")}"
@@ -116,10 +177,11 @@ module GraphWeaver
     # Generated::PersonQuery from generated/person_query.rb, and
     # generated code only changes on regeneration anyway (restart, like
     # a schema migration).
-    def load_generated!(path = generated_path)
-      files = Dir[File.join(path, "**/*.rb")].sort
+    def load_generated!(path = nil)
+      paths = path ? [path] : generated_paths
+      files = paths.flat_map { |dir| Dir[File.join(dir, "**/*.rb")].sort }.uniq
       files.each { |file| require File.expand_path(file) }
-      log(:info) { "loaded #{files.size} generated module(s) from #{path}" }
+      log(:info) { "loaded #{files.size} generated module(s) from #{paths.join(", ")}" }
       files
     end
 
@@ -130,20 +192,39 @@ module GraphWeaver
     end
     private :locate_schema!
 
-    # (base, generated_source) per .graphql file in a directory
-    def each_query(queries, schema:, client:)
-      Dir[File.join(queries, "*.graphql")].sort.map do |path|
+    # (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
+      used = { inputs: [], enums: [], mapped: [] }
+
+      plan = Dir[File.join(queries, "*.graphql")].sort.map do |path|
         base = File.basename(path, ".graphql")
-        source = Codegen.generate(
+        codegen = Codegen.new(
           schema:,
           query: File.read(path),
           module_name: "#{Inflect.camelize(base)}Query",
           client:,
+          inputs_namespace: namespace,
         )
-        [base, source]
+        source = codegen.generate
+        codegen.variable_type_names.each { |kind, names| used[kind] |= names }
+        ["#{base}_query.rb", source]
       end
+
+      if namespace && used.values.any?(&:any?)
+        shared = Codegen.generate_inputs(
+          schema:, module_name: namespace,
+          input_types: used[:inputs], enum_types: used[:enums] + used[:mapped],
+        )
+        plan = shared.to_a + plan
+      end
+
+      plan
     end
-    private :each_query
+    private :generation_plan
 
     # Default input coercion for scalars that don't say coerce: themselves,
     # resolved lazily at generation time (so set it any time before you

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: graph_weaver
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.2.2
 platform: ruby
 authors:
 - Daniel Pepper
@@ -255,6 +255,7 @@ files:
 - lib/graph_weaver/errors.rb
 - lib/graph_weaver/hints.rb
 - lib/graph_weaver/inflect.rb
+- lib/graph_weaver/input_struct.rb
 - lib/graph_weaver/logging.rb
 - lib/graph_weaver/railtie.rb
 - lib/graph_weaver/response.rb