graph_weaver 0.0.1 → 0.1.0

data/lib/graph_weaver/codegen.rb

@@ -1,228 +1,92 @@
 # typed: true
 # frozen_string_literal: true
 
+require "date"
 require "graphql"
 require "sorbet-runtime"
 
 # Generates plain, statically-typecheckable Ruby from a GraphQL query +
 # schema: nested T::Structs, from_h casting code, and a sig'd execute
-# method. Unlike StructTypes (which builds classes at parse time, visible
-# only at runtime), the output is source on disk — srb tc sees the exact
-# result type of each query.
+# method. The output is source on disk, so srb tc sees the exact result
+# type of each query.
 #
 # Supports queries and mutations; plain fields, inline fragments, named
 # fragment spreads (including interface type conditions), union- and
 # interface-typed fields (dispatch on __typename), enums (generated
-# T::Enum), and typed variables (kwargs on execute). Input objects and
-# subscriptions are still open.
-class GraphWeaver::Codegen
-  # sorbet types for scalars
-  SCALARS = {
-    "ID" => "String",
-    "String" => "String",
-    "Int" => "Integer",
-    "Float" => "Float",
-    "Boolean" => "T::Boolean",
-    "Date" => "Date",
-  }.freeze
-
-  # deserialization for scalars whose wire format differs from their Ruby
-  # type; anything absent passes through untouched
-  SCALAR_CASTS = {
-    "Date" => ->(expr) { "Date.iso8601(#{expr})" },
-  }.freeze
-
-  # the inverse, for serializing variables onto the wire
-  SCALAR_SERIALIZERS = {
-    "Date" => ->(expr) { "#{expr}.iso8601" },
-  }.freeze
-
-  class Scalar
-    def initialize(name)
-      @name = name
-    end
-
-    def bare_type
-      SCALARS.fetch(@name, "T.untyped")
-    end
-
-    def prop_type
-      "T.nilable(#{bare_type})"
-    end
-
-    def cast(expr, _depth)
-      SCALAR_CASTS.fetch(@name) { return expr }.call(expr)
-    end
-
-    def identity?
-      !SCALAR_CASTS.key?(@name)
-    end
-
-    def serialize(expr, _depth)
-      SCALAR_SERIALIZERS.fetch(@name) { return expr }.call(expr)
-    end
-
-    def serialize_identity?
-      !SCALAR_SERIALIZERS.key?(@name)
-    end
-
-    def non_null? = false
-    def nested = nil
-  end
-
-  class NonNull
-    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 non_null? = true
-    def nested = @of.nested
-  end
-
-  class List
-    def initialize(of)
-      @of = of
-    end
-
-    def bare_type
-      "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?
-        @of.identity? ? var : @of.cast(var, depth + 1)
-      else
-        "#{var}&.then { |v#{depth + 1}| #{@of.cast("v#{depth + 1}", depth + 2)} }"
-      end
-
-      "#{expr}.map { |#{var}| #{element} }"
-    end
-
-    def identity? = @of.identity?
-
-    def serialize(expr, depth)
-      var = "v#{depth}"
-      element = if @of.non_null? || @of.serialize_identity?
-        @of.serialize_identity? ? var : @of.serialize(var, depth + 1)
-      else
-        "#{var}&.then { |v#{depth + 1}| #{@of.serialize("v#{depth + 1}", depth + 2)} }"
-      end
-
-      "#{expr}.map { |#{var}| #{element} }"
-    end
-
-    def serialize_identity? = @of.serialize_identity?
-    def non_null? = false
-    def nested = @of.nested
-  end
-
-  class ObjectNode
-    Field = Struct.new(:prop, :key, :node)
-
-    attr_reader :class_name, :fields
-
-    def initialize(class_name)
-      @class_name = class_name
-      @fields = []
-    end
-
-    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
-    attr_reader :class_name, :values
-
-    def initialize(class_name, values)
-      @class_name = class_name
-      @values = values
-    end
-
-    def bare_type = class_name
-
-    def prop_type
-      "T.nilable(#{bare_type})"
-    end
-
-    def cast(expr, _depth)
-      "#{class_name}.deserialize(#{expr})"
-    end
+# T::Enum), and typed variables (kwargs on execute). Subscriptions are
+# still open.
+#
+# Split across: codegen/scalar_type.rb (the scalar registry),
+# codegen/nodes.rb (the typed IR), codegen/emit.rb (source emission);
+# this file holds the public API and the query walk.
+require_relative "inflect"
+require_relative "selection"
+require_relative "codegen/scalar_type"
+require_relative "codegen/nodes"
+require_relative "codegen/emit"
 
-    def identity? = false
+class GraphWeaver::Codegen
+  include GraphWeaver::Inflect
+  include GraphWeaver::Selection
+  include Emit
+
+  attr_reader :module_name
+
+  # An executor is anything responding to `execute(query, variables:)`
+  # whose result `to_h`s into {"data" => ..., "errors" => ...}.
+  #
+  # executor: (a constant, or its name as a string) becomes the generated
+  # module's default transport; when omitted, generated code falls back
+  # to GraphWeaver.executor. module_name: defaults to the operation's
+  # name; default_module_name: is parse's container-scoped fallback (file
+  # generation stays strict — a checked-in file deserves a deliberate
+  # name).
+  def initialize(schema:, query:, module_name: nil, executor: nil, default_module_name: nil)
+    @schema = schema
+    @query = query.strip
+    @module_name = module_name
+    @default_module_name = default_module_name
+    @executor_const = self.class.executor_const(executor)
 
-    def serialize(expr, _depth)
-      "#{expr}.serialize"
+    if executor && @executor_const.nil?
+      # a live object can't be spelled in generated source — parse can
+      # set one via the module's writer, but file generation cannot
+      raise ArgumentError, "executor: must be a named constant or String (got #{executor.inspect}); pass live objects to parse"
     end
-
-    def serialize_identity? = false
-    def non_null? = false
-    def nested = self
   end
 
-  class UnionNode
-    attr_reader :class_name, :members # graphql type name => ObjectNode
-
-    def initialize(class_name, members)
-      @class_name = class_name
-      @members = members
-    end
-
-    def bare_type = "#{class_name}::Type"
-
-    def prop_type
-      "T.nilable(#{bare_type})"
-    end
-
-    def cast(expr, _depth)
-      "#{class_name}.from_h(#{expr})"
+  # The constant name an executor can be referenced by in generated
+  # source — nil when it can't be (live objects, anonymous modules).
+  def self.executor_const(executor)
+    case executor
+    when String then executor
+    when Module then executor.name
     end
-
-    def identity? = false
-    def non_null? = false
-    def nested = self
   end
 
-  # executor_const names anything responding to
-  # `execute(query, variables:)` whose result `to_h`s into
-  # {"data" => ..., "errors" => ...} — a Schema class for in-process
-  # execution, or an HttpExecutor for a remote endpoint. The generated
-  # execute also accepts an executor: override at runtime.
-  def initialize(schema:, executor_const:, query:, module_name:)
-    @schema = schema
-    @executor_const = executor_const
-    @query = query.strip
-    @module_name = module_name
+  # one-step shorthand
+  def self.generate(schema:, query:, module_name: nil, executor: nil)
+    new(schema:, query:, module_name:, executor:).generate
   end
 
   # Development convenience: generate + eval in one step, no build
   # artifact or checked-in file. Same runtime semantics as the generated
   # file, but invisible to srb tc — use the build step for static typing.
-  def self.load(schema:, executor_const:, query:, module_name:)
-    source = new(schema:, executor_const:, query:, module_name:).generate
-    Object.class_eval(source, "(struct_codegen)", 1)
-    Object.const_get(module_name)
+  # Evaluates into an anonymous container, so no global constants leak;
+  # executor: additionally accepts a live object (set via .executor=).
+  def self.parse(schema:, query:, module_name: nil, executor: nil)
+    executor_const = executor_const(executor)
+
+    codegen = new(schema:, query:, module_name:, executor: executor_const, default_module_name: "Query")
+    source = codegen.generate
+
+    container = Module.new
+    container.module_eval(source, "(graph_weaver)", 1)
+    mod = container.const_get(codegen.module_name)
+    # live objects (or anonymous modules) can't be referenced from
+    # generated source — set them via the module's writer instead
+    mod.executor = executor if executor && executor_const.nil?
+    mod
   end
 
   VarDef = Struct.new(:kwarg, :wire, :node, :required)
@@ -230,20 +94,26 @@ class GraphWeaver::Codegen
   def generate
     errors = @schema.validate(@query)
     if errors.any?
-      raise ArgumentError, "invalid query: #{errors.map(&:message).join("; ")}"
+      raise GraphWeaver::ValidationError.new(errors.map { |e| validation_detail(e) })
     end
 
-    doc = GraphQL.parse(@query)
-    @fragments = doc.definitions
-      .grep(GraphQL::Language::Nodes::FragmentDefinition)
-      .to_h { |fragment| [fragment.name, fragment] }
     @variable_enums = {}
+    @variable_inputs = {}
+    @inputs_in_progress = []
+    # requires contributed by the custom scalars this query actually uses
+    @scalar_requires = []
+
+    operation = load_operation(@query)
+    root_type = operation_root_type(operation)
 
-    operation = doc.definitions.grep(GraphQL::Language::Nodes::OperationDefinition).first
-    root_type = case operation&.operation_type
-    when "query", nil then @schema.query
-    when "mutation" then @schema.mutation
-    else raise NotImplementedError, "unsupported operation: #{operation.operation_type}"
+    @module_name ||= operation.name || @default_module_name
+    unless @module_name
+      raise ArgumentError, "module_name: required for anonymous operations"
+    end
+
+    # generated source is eval'd by parse — never let a name inject code
+    unless @module_name.match?(/\A[A-Z]\w*(::[A-Z]\w*)*\z/)
+      raise ArgumentError, "module_name: must be a constant name, got #{@module_name.inspect}"
     end
 
     variables = operation.variables.map do |var|
@@ -262,17 +132,31 @@ class GraphWeaver::Codegen
     out << ""
     out << "# Generated by GraphWeaver — do not edit."
     out << ""
+    requires = @scalar_requires.uniq.sort
+    if requires.any?
+      requires.each { |req| out << "require #{req.inspect}" }
+      out << ""
+    end
     out << "module #{@module_name}"
     out << "  extend T::Sig"
     out << ""
-    out << "  QUERY = T.let(<<~'GRAPHQL', String)"
+    # 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 << "  GRAPHQL"
+    out << "  #{delimiter}"
     out << ""
     @variable_enums.each_value do |enum|
       emit_enum(enum, out, 1)
       out << ""
     end
+    @variable_inputs.each_value do |input|
+      emit_input(input, out, 1)
+      out << ""
+    end
     emit_nested(root, out, 1)
     out << ""
     emit_execute(out, variables)
@@ -283,53 +167,14 @@ class GraphWeaver::Codegen
 
   private
 
-  # GraphQL names are plain camelCase/SCREAMING_SNAKE — no acronym edge
-  # cases, so minimal inflection beats an activesupport dependency
-  def underscore(name)
-    name.gsub(/([a-z\d])([A-Z])/, '\1_\2').downcase
-  end
-
-  def camelize(name)
-    name.split("_").map { |part| "#{part[0].upcase}#{part[1..]}" }.join
-  end
-
-  # Flatten a selection set as seen by `type`: plain fields collect
-  # directly; inline fragments and named spreads recurse when their type
-  # condition matches (exact name match — interface conditions are out of
-  # scope for this spike).
-  def gather(type, selections, out = {})
-    selections.each do |selection|
-      case selection
-      when GraphQL::Language::Nodes::Field
-        (out[selection.alias || selection.name] ||= []) << selection
-      when GraphQL::Language::Nodes::InlineFragment
-        gather(type, selection.selections, out) if applies?(selection.type&.name, type)
-      when GraphQL::Language::Nodes::FragmentSpread
-        fragment = @fragments.fetch(selection.name) do
-          raise ArgumentError, "unknown fragment: #{selection.name}"
-        end
-        gather(type, fragment.selections, out) if applies?(fragment.type.name, type)
-      else
-        raise NotImplementedError, "unsupported selection: #{selection.class}"
-      end
-    end
-
+  # Selection#each_field, collected by result key (codegen groups
+  # repeated selections of one field so it can merge them)
+  def gather(type, selections)
+    out = {}
+    each_field(type, selections) { |key, node| (out[key] ||= []) << node }
     out
   end
 
-  # A fragment's type condition applies when it names this type exactly,
-  # or an interface/union this type belongs to (`... on Named { ... }`).
-  def applies?(condition, type)
-    return true if condition.nil? || condition == type.graphql_name
-
-    condition_type = @schema.get_type(condition)
-    return false unless condition_type
-
-    kind = condition_type.kind.name
-    (kind == "INTERFACE" || kind == "UNION") &&
-      @schema.possible_types(condition_type).include?(type)
-  end
-
   def object_node(type, selections, class_name)
     node = ObjectNode.new(class_name)
     taken = [class_name]
@@ -357,12 +202,18 @@ class GraphWeaver::Codegen
           # (SDL round-trips reorder values alphabetically)
           type_ref(field_type) { EnumNode.new(name, core.values.keys.sort) }
         when "SCALAR"
-          type_ref(field_type) { Scalar.new(core.graphql_name) }
+          type_ref(field_type) { scalar_node(core.graphql_name) }
         else
           raise NotImplementedError, "unsupported kind: #{core.kind.name}"
         end
       end
 
+      # a field under @skip/@include may be absent from the response no
+      # matter what the schema says — its type must admit nil
+      if field_nodes.any? { |n| n.directives.any? { |d| %w[skip include].include?(d.name) } }
+        child = child.of if child.is_a?(NonNull)
+      end
+
       node.fields << ObjectNode::Field.new(prop, key, child)
     end
 
@@ -395,21 +246,59 @@ class GraphWeaver::Codegen
     when GraphQL::Language::Nodes::ListType
       List.new(ast_type_ref(ast_type.of_type))
     when GraphQL::Language::Nodes::TypeName
-      core = @schema.get_type(ast_type.name)
-      case core.kind.name
-      when "SCALAR"
-        Scalar.new(core.graphql_name)
-      when "ENUM"
-        @variable_enums[core.graphql_name] ||=
-          EnumNode.new(core.graphql_name, core.values.keys.sort)
-      else
-        raise NotImplementedError, "unsupported variable kind: #{core.kind.name}"
-      end
+      variable_core(@schema.get_type(ast_type.name))
     else
       raise NotImplementedError, "unsupported type node: #{ast_type.class}"
     end
   end
 
+  # the input-side core kinds a variable (or input-object field) can have
+  def variable_core(core)
+    case core.kind.name
+    when "SCALAR"
+      scalar_node(core.graphql_name)
+    when "ENUM"
+      @variable_enums[core.graphql_name] ||=
+        EnumNode.new(core.graphql_name, core.values.keys.sort)
+    when "INPUT_OBJECT"
+      input_node(core)
+    else
+      raise NotImplementedError, "unsupported variable kind: #{core.kind.name}"
+    end
+  end
+
+  # A module-level T::Struct per input type, with a serialize method
+  # producing the wire hash. Registered once per type; nested inputs
+  # register their dependencies first (insertion order = emission order).
+  def input_node(core)
+    return @variable_inputs[core.graphql_name] if @variable_inputs.key?(core.graphql_name)
+
+    if @inputs_in_progress.include?(core.graphql_name)
+      raise NotImplementedError, "recursive input type: #{core.graphql_name}"
+    end
+    @inputs_in_progress << core.graphql_name
+
+    node = InputNode.new(core.graphql_name)
+    # sorted so output is deterministic across schema sources
+    core.arguments.values.sort_by(&:graphql_name).each do |argument|
+      child = type_ref(argument.type) { variable_core(unwrap(argument.type)) }
+      required = child.non_null? && !argument.default_value?
+      node.fields << InputNode::Field.new(
+        underscore(argument.graphql_name), argument.graphql_name, child, required
+      )
+    end
+
+    @inputs_in_progress.delete(core.graphql_name)
+    @variable_inputs[core.graphql_name] = node
+  end
+
+  # A Scalar node, recording any requires its registered type needs so the
+  # generated file can require them (collected across the whole query).
+  def scalar_node(name)
+    @scalar_requires.concat(GraphWeaver::Codegen.scalar(name).requires)
+    Scalar.new(name)
+  end
+
   # rebuild the NON_NULL/LIST wrappers around the core node
   def type_ref(type, &core)
     case type.kind.name
@@ -436,132 +325,4 @@ class GraphWeaver::Codegen
     candidate
   end
 
-  def emit_nested(node, out, indent)
-    case node
-    when UnionNode then emit_union(node, out, indent)
-    when EnumNode then emit_enum(node, out, indent)
-    else emit_object(node, out, indent)
-    end
-  end
-
-  def emit_enum(node, out, indent)
-    pad = "  " * indent
-
-    out << "#{pad}class #{node.class_name} < T::Enum"
-    out << "#{pad}  enums do"
-    node.values.each do |value|
-      out << "#{pad}    #{camelize(value.downcase)} = new(#{value.inspect})"
-    end
-    out << "#{pad}  end"
-    out << "#{pad}end"
-  end
-
-  def emit_object(node, out, indent)
-    pad = "  " * indent
-
-    out << "#{pad}class #{node.class_name} < T::Struct"
-    out << "#{pad}  extend T::Sig"
-    out << ""
-
-    node.fields.filter_map { |field| field.node.nested }.each do |child|
-      emit_nested(child, out, indent + 1)
-      out << ""
-    end
-
-    node.fields.each do |field|
-      out << "#{pad}  const :#{field.prop}, #{field.node.prop_type}"
-    end
-
-    out << ""
-    out << "#{pad}  sig { params(data: T::Hash[String, T.untyped]).returns(#{node.class_name}) }"
-    out << "#{pad}  def self.from_h(data)"
-    out << "#{pad}    new("
-    node.fields.each do |field|
-      out << "#{pad}      #{field.prop}: #{field_cast(field)},"
-    end
-    out << "#{pad}    )"
-    out << "#{pad}  end"
-    out << "#{pad}end"
-  end
-
-  def emit_union(node, out, indent)
-    pad = "  " * indent
-
-    out << "#{pad}module #{node.class_name}"
-    out << "#{pad}  extend T::Sig"
-    out << ""
-
-    node.members.each_value do |member|
-      emit_object(member, out, indent + 1)
-      out << ""
-    end
-
-    member_names = node.members.values.map(&:class_name)
-    type_alias = member_names.size == 1 ? member_names.first : "T.any(#{member_names.join(", ")})"
-    out << "#{pad}  Type = T.type_alias { #{type_alias} }"
-    out << ""
-    out << "#{pad}  sig { params(data: T::Hash[String, T.untyped]).returns(Type) }"
-    out << "#{pad}  def self.from_h(data)"
-    out << "#{pad}    case (typename = data.fetch(\"__typename\"))"
-    node.members.each do |graphql_name, member|
-      out << "#{pad}    when #{graphql_name.inspect} then #{member.class_name}.from_h(data)"
-    end
-    out << "#{pad}    else raise \"unexpected __typename: \#{typename}\""
-    out << "#{pad}    end"
-    out << "#{pad}  end"
-    out << "#{pad}end"
-  end
-
-  def emit_execute(out, variables)
-    sig_params = variables.map do |var|
-      kwarg_type = var.required ? var.node.prop_type : "T.nilable(#{var.node.bare_type})"
-      "#{var.kwarg}: #{kwarg_type}"
-    end
-    sig_params << "executor: T.untyped"
-
-    kwargs = variables.map { |var| var.required ? "#{var.kwarg}:" : "#{var.kwarg}: nil" }
-    kwargs << "executor: #{@executor_const}"
-
-    out << "  sig { params(#{sig_params.join(", ")}).returns(Result) }"
-    out << "  def self.execute(#{kwargs.join(", ")})"
-
-    required, optional = variables.partition(&:required)
-    if required.empty?
-      out << "    variables = {}"
-    else
-      out << "    variables = {"
-      required.each do |var|
-        out << "      #{var.wire.inspect} => #{variable_serialize(var)},"
-      end
-      out << "    }"
-    end
-    optional.each do |var|
-      out << "    variables[#{var.wire.inspect}] = #{variable_serialize(var)} unless #{var.kwarg}.nil?"
-    end
-
-    out << ""
-    out << "    result = executor.execute(QUERY, variables: variables).to_h"
-    out << "    if (errors = result[\"errors\"])"
-    out << "      raise \"query failed: \#{errors.inspect}\""
-    out << "    end"
-    out << ""
-    out << "    Result.from_h(result.fetch(\"data\"))"
-    out << "  end"
-  end
-
-  def variable_serialize(var)
-    var.node.serialize_identity? ? var.kwarg : var.node.serialize(var.kwarg, 1)
-  end
-
-  def field_cast(field)
-    node = field.node
-
-    if node.non_null?
-      raw = "data.fetch(#{field.key.inspect})"
-      node.identity? ? raw : node.cast(raw, 1)
-    else
-      raw = "data[#{field.key.inspect}]"
-      node.identity? ? raw : "#{raw}&.then { |v1| #{node.cast("v1", 2)} }"
-    end
-  end
 end