graph_weaver 0.1.0 → 0.2.0

data/lib/graph_weaver/codegen.rb

@@ -1,7 +1,6 @@
 # typed: true
 # frozen_string_literal: true
 
-require "date"
 require "graphql"
 require "sorbet-runtime"
 
@@ -19,8 +18,10 @@ require "sorbet-runtime"
 # 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 "hints"
 require_relative "inflect"
 require_relative "selection"
+require_relative "codegen/enum_type"
 require_relative "codegen/scalar_type"
 require_relative "codegen/nodes"
 require_relative "codegen/emit"
@@ -32,76 +33,106 @@ class GraphWeaver::Codegen
 
   attr_reader :module_name
 
-  # An executor is anything responding to `execute(query, variables:)`
-  # whose result `to_h`s into {"data" => ..., "errors" => ...}.
+  # A client is anything responding to `execute(query, variables:)`
+  # whose result `to_h`s into {"data" => ..., "errors" => ...} — a
+  # GraphWeaver::Client, a transport, a schema class, a fake.
   #
-  # 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
+  # client: (a constant, or its name as a string) becomes the generated
+  # module's baked default; when omitted, generated code falls back to
+  # the app default (GraphWeaver.client=). 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)
+  # 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).
+  def initialize(schema:, query:, module_name: nil, client: nil, default_module_name: nil,
+    scalars: nil, enums: nil, types: nil)
     @schema = schema
     @query = query.strip
     @module_name = module_name
     @default_module_name = default_module_name
-    @executor_const = self.class.executor_const(executor)
+    @scalars = scalars || {}
+    @enums = enums || {}
+    @types = types || {}
+    @client_const = self.class.client_const(client)
 
-    if executor && @executor_const.nil?
+    if client && @client_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"
+      raise ArgumentError, "client: must be a named constant or String (got #{client.inspect}); pass live objects to parse"
     end
   end
 
-  # The constant name an executor can be referenced by in generated
+  # The constant name a client 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
+  def self.client_const(client)
+    case client
+    when String then client
+    when Module then client.name
     end
   end
 
   # one-step shorthand
-  def self.generate(schema:, query:, module_name: nil, executor: nil)
-    new(schema:, query:, module_name:, executor:).generate
+  def self.generate(schema:, query:, module_name: nil, client: nil, scalars: nil, enums: nil, types: nil)
+    new(schema:, query:, module_name:, client:, scalars:, enums:, types:).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.
   # 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)
+  # client: additionally accepts a live object (set via .client=).
+  def self.parse(schema:, query:, module_name: nil, client: nil, scalars: nil, enums: nil, types: nil)
+    client_const = client_const(client)
 
-    codegen = new(schema:, query:, module_name:, executor: executor_const, default_module_name: "Query")
+    codegen = new(schema:, query:, module_name:, client: client_const, default_module_name: "Query",
+      scalars:, enums:, types:)
     source = codegen.generate
 
     container = Module.new
     container.module_eval(source, "(graph_weaver)", 1)
     mod = container.const_get(codegen.module_name)
+    GraphWeaver.log(:debug) { "parsed #{codegen.module_name} (dynamic module, #{source.bytesize} bytes)" }
     # 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.client = client if client && client_const.nil?
     mod
   end
 
   VarDef = Struct.new(:kwarg, :wire, :node, :required)
 
+  # Names that cannot appear bare in generated Ruby: keywords aren't
+  # valid identifiers, and the struct's own generated methods would be
+  # silently replaced by a same-named prop reader.
+  RUBY_KEYWORDS = %w[
+    alias and begin break case class def defined? do else elsif end
+    ensure false for if in module next nil not or redo rescue retry
+    return self super then true undef unless until when while yield
+    BEGIN END __FILE__ __LINE__ __ENCODING__
+  ].to_set.freeze
+  GENERATED_METHODS = %w[serialize to_h].to_set.freeze
+
   def generate
-    errors = @schema.validate(@query)
+    begin
+      errors = @schema.validate(@query)
+    rescue GraphQL::ParseError => e
+      # unparseable queries wrap like invalid ones — everything raised
+      # here descends from GraphWeaver::Error
+      raise GraphWeaver::ValidationError.new([{ message: e.message, line: nil, column: nil }])
+    end
     if errors.any?
       raise GraphWeaver::ValidationError.new(errors.map { |e| validation_detail(e) })
     end
 
+    validate_registrations!
+
     @variable_enums = {}
     @variable_inputs = {}
-    @inputs_in_progress = []
-    # requires contributed by the custom scalars this query actually uses
-    @scalar_requires = []
+    @mapped_enums = {}
+    # requires the generated file needs (custom scalars, enum mappings,
+    # type helpers all contribute)
+    @requires = []
 
     operation = load_operation(@query)
     root_type = operation_root_type(operation)
@@ -121,7 +152,14 @@ class GraphWeaver::Codegen
       # a variable is optional when nullable or defaulted; optional kwargs
       # default to nil and are omitted from the wire
       required = node.non_null? && var.default_value.nil?
-      VarDef.new(underscore(var.name), var.name, node, required)
+      kwarg = underscore(var.name)
+      # kwargs are declared and forwarded bare in generated source
+      if RUBY_KEYWORDS.include?(kwarg)
+        raise GraphWeaver::Error,
+          "variable $#{var.name} would become the kwarg '#{kwarg}:', which generated code can't declare " \
+          "(a Ruby keyword) — rename the variable"
+      end
+      VarDef.new(kwarg, var.name, node, required)
     end
 
     root = object_node(root_type, operation.selections, "Result")
@@ -132,7 +170,7 @@ class GraphWeaver::Codegen
     out << ""
     out << "# Generated by GraphWeaver — do not edit."
     out << ""
-    requires = @scalar_requires.uniq.sort
+    requires = @requires.uniq.sort
     if requires.any?
       requires.each { |req| out << "require #{req.inspect}" }
       out << ""
@@ -149,17 +187,35 @@ class GraphWeaver::Codegen
     @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
-    @variable_inputs.each_value do |input|
+    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)
+    emit_execute(out, variables, flatten: flatten_input(variables))
     out << "end"
 
     out.join("\n") + "\n"
@@ -167,6 +223,49 @@ class GraphWeaver::Codegen
 
   private
 
+  # A client-scoped registration names a type in a specific schema — a
+  # typo'd name would otherwise be a silent no-op, the most confusing
+  # failure mode available. Called eagerly by Client#register_* when the
+  # schema is already loaded, and again at generation (covers clients
+  # whose schema introspects lazily). Global registrations skip this:
+  # they may target a different client's server.
+  def self.validate_registration!(schema, kind, name)
+    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}"
+  end
+
+  # Structured shape for a schema-validation error: message plus its first
+  # source location, so ValidationError#errors is inspectable.
+  def validation_detail(error)
+    loc = (error.to_h["locations"]&.first if error.respond_to?(:to_h))
+    { message: error.message, line: loc && loc["line"], column: loc && loc["column"] }
+  end
+
+  def validate_registrations!
+    { "enum" => @enums, "scalar" => @scalars, "type" => @types }.each do |kind, registry|
+      registry.each_key { |name| self.class.validate_registration!(@schema, kind, name) }
+    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)
   def gather(type, selections)
@@ -177,6 +276,8 @@ class GraphWeaver::Codegen
 
   def object_node(type, selections, class_name)
     node = ObjectNode.new(class_name)
+    node.graphql_type = type.graphql_name
+    node.mixins = type_mixins(type.graphql_name)
     taken = [class_name]
 
     gather(type, selections).each do |key, field_nodes|
@@ -184,7 +285,7 @@ class GraphWeaver::Codegen
       prop = underscore(key)
 
       child = if field_name == "__typename"
-        NonNull.new(Scalar.new("String"))
+        NonNull.new(scalar_node("String"))
       else
         field_type = @schema.get_field(type.graphql_name, field_name).type
         sub_selections = field_nodes.flat_map(&:selections)
@@ -194,17 +295,47 @@ class GraphWeaver::Codegen
           name = pick_name(core.graphql_name, key, taken)
           type_ref(field_type) { object_node(core, sub_selections, name) }
         when "UNION", "INTERFACE"
-          name = pick_name(core.graphql_name, key, taken)
-          type_ref(field_type) { union_node(core, sub_selections, name) }
+          conditions = concrete_conditions(core, sub_selections)
+          bare = bare_fields(sub_selections) - ["__typename"]
+
+          if conditions.empty? && core.kind.name == "INTERFACE"
+            # interface-level fields only — every member shares them, so
+            # one struct suffices and no __typename dispatch is needed
+            name = pick_name(core.graphql_name, key, taken)
+            type_ref(field_type) { object_node(core, sub_selections, name) }
+          elsif conditions.size == 1 && bare.empty? &&
+              (member = @schema.get_type(conditions.first)).kind.name == "OBJECT"
+            # a single `... on X` condition: narrow to X's struct — nil
+            # when the runtime type doesn't match (narrowing filters).
+            # Narrowing reads "no fields came back" as "type didn't
+            # match", so a fragment whose every field hides behind
+            # @skip/@include would make a real match indistinguishable
+            # from a miss ({} either way) — refuse rather than guess.
+            unless unconditional_field?(member, sub_selections)
+              raise GraphWeaver::Error,
+                "narrowed `... on #{member.graphql_name}` needs at least one field not under " \
+                "@skip/@include — an all-conditional selection makes a match indistinguishable from nil"
+            end
+
+            name = pick_name(member.graphql_name, key, taken)
+            nilable_type_ref(field_type) { NarrowedNode.new(object_node(member, sub_selections, name)) }
+          else
+            name = pick_name(core.graphql_name, key, taken)
+            type_ref(field_type) { union_node(core, sub_selections, name) }
+          end
         when "ENUM"
-          name = pick_name(core.graphql_name, key, taken)
-          # sorted so output is deterministic across schema sources
-          # (SDL round-trips reorder values alphabetically)
-          type_ref(field_type) { EnumNode.new(name, core.values.keys.sort) }
+          if (mapped = mapped_enum_node(core))
+            type_ref(field_type) { mapped }
+          else
+            name = pick_name(core.graphql_name, key, taken)
+            # sorted so output is deterministic across schema sources
+            # (SDL round-trips reorder values alphabetically)
+            type_ref(field_type) { EnumNode.new(name, core.values.keys.sort) }
+          end
         when "SCALAR"
           type_ref(field_type) { scalar_node(core.graphql_name) }
         else
-          raise NotImplementedError, "unsupported kind: #{core.kind.name}"
+          raise GraphWeaver::Error, "unsupported kind: #{core.kind.name}"
         end
       end
 
@@ -220,18 +351,60 @@ class GraphWeaver::Codegen
     node
   end
 
-  # Abstract types (unions AND interfaces): 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.
+  # The concrete type conditions a selection mentions (inline fragments
+  # and named spreads), minus conditions naming the abstract type itself.
+  def concrete_conditions(core, selections)
+    selections.filter_map do |selection|
+      case selection
+      when GraphQL::Language::Nodes::InlineFragment
+        selection.type&.name
+      when GraphQL::Language::Nodes::FragmentSpread
+        @fragments.fetch(selection.name).type.name
+      end
+    end.uniq - [core.graphql_name]
+  end
+
+  # result keys selected as plain fields (outside any type condition)
+  def bare_fields(selections)
+    selections.grep(GraphQL::Language::Nodes::Field).map { |field| field.alias || field.name }
+  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)
+    each_field(member, selections) do |_key, node|
+      return true if node.directives.none? { |d| %w[skip include].include?(d.name) }
+    end
+    false
+  end
+
+  # rebuild LIST wrappers but drop NON_NULLs — a narrowed member is nil
+  # whenever the runtime type doesn't match, whatever the schema promises
+  def nilable_type_ref(type, &core)
+    case type.kind.name
+    when "NON_NULL"
+      nilable_type_ref(type.of_type, &core)
+    when "LIST"
+      List.new(nilable_type_ref(type.of_type, &core))
+    else
+      core.call
+    end
+  end
+
+  # Abstract types (unions AND interfaces) whose selections vary by
+  # 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)
     unless gather(type, selections).key?("__typename")
-      raise ArgumentError, "select __typename on #{type.graphql_name} so #{class_name} can dispatch"
+      raise ArgumentError,
+        "select __typename on #{type.graphql_name} so #{class_name} 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|
-      [possible.graphql_name, object_node(possible, selections, possible.graphql_name)]
+      [possible.graphql_name, object_node(possible, selections, camelize(possible.graphql_name))]
     end
 
     UnionNode.new(class_name, members)
@@ -248,7 +421,7 @@ class GraphWeaver::Codegen
     when GraphQL::Language::Nodes::TypeName
       variable_core(@schema.get_type(ast_type.name))
     else
-      raise NotImplementedError, "unsupported type node: #{ast_type.class}"
+      raise GraphWeaver::Error, "unsupported type node: #{ast_type.class}"
     end
   end
 
@@ -258,45 +431,103 @@ class GraphWeaver::Codegen
     when "SCALAR"
       scalar_node(core.graphql_name)
     when "ENUM"
-      @variable_enums[core.graphql_name] ||=
-        EnumNode.new(core.graphql_name, core.values.keys.sort)
+      mapped_enum_node(core) || (@variable_enums[core.graphql_name] ||=
+        EnumNode.new(camelize(core.graphql_name), core.values.keys.sort))
     when "INPUT_OBJECT"
       input_node(core)
     else
-      raise NotImplementedError, "unsupported variable kind: #{core.kind.name}"
+      raise GraphWeaver::Error, "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).
+  # producing the wire hash. Registered once per type — and registered
+  # BEFORE its fields walk, so recursive references (Hasura's bool_exp
+  # _and/_or/_not) resolve to the same node instead of looping.
   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)
+    node = @variable_inputs[core.graphql_name] = InputNode.new(camelize(core.graphql_name))
     # sorted so output is deterministic across schema sources
     core.arguments.values.sort_by(&:graphql_name).each do |argument|
+      prop = underscore(argument.graphql_name)
+      # prop readers are bare method calls in the generated struct
+      if RUBY_KEYWORDS.include?(prop) || GENERATED_METHODS.include?(prop)
+        raise GraphWeaver::Error,
+          "input field #{core.graphql_name}.#{argument.graphql_name} would become prop '#{prop}', " \
+          "which collides with #{RUBY_KEYWORDS.include?(prop) ? "a Ruby keyword" : "the struct's generated ##{prop}"}"
+      end
+
       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
-      )
+      node.fields << InputNode::Field.new(prop, argument.graphql_name, child, required)
     end
+    node
+  end
+
+  # 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.
+  def type_mixins(graphql_name)
+    entries = [GraphWeaver::Codegen.type_registry[graphql_name], @types[graphql_name]].compact
+    entries.each { |entry| @requires.concat(entry[:requires]) }
+    entries.flat_map { |entry| entry[:mixins].map(&:name) }
+  end
+
+  # The MappedEnum node for a schema enum with a registered app-enum
+  # mapping (client overlay first, then the global registry); nil when
+  # unregistered, falling back to a generated T::Enum.
+  def mapped_enum_node(core)
+    enum_type = @enums[core.graphql_name] || GraphWeaver::Codegen.enum_registry[core.graphql_name]
+    return unless enum_type
 
-    @inputs_in_progress.delete(core.graphql_name)
-    @variable_inputs[core.graphql_name] = node
+    @requires.concat(enum_type.requires)
+    @mapped_enums[core.graphql_name] ||= MappedEnum.new(enum_type, core.values.keys.sort)
   end
 
   # 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_requires.concat(GraphWeaver::Codegen.scalar(name).requires)
-    Scalar.new(name)
+    scalar = @scalars[name.to_s] || GraphWeaver::Codegen.scalar(name)
+    @requires.concat(scalar.requires)
+    Scalar.new(scalar)
   end
 
   # rebuild the NON_NULL/LIST wrappers around the core node
@@ -316,10 +547,13 @@ class GraphWeaver::Codegen
     type
   end
 
+  # GraphQL type names become struct names — camelized, because schemas
+  # in the wild use snake_case type names (Hasura, PostGraphile) and a
+  # verbatim lowercase name is not a Ruby constant
   def pick_name(type_name, key, taken)
-    candidate = type_name
-    candidate = "#{camelize(key)}#{type_name}" if taken.include?(candidate)
-    raise NotImplementedError, "class name collision: #{candidate}" if taken.include?(candidate)
+    candidate = camelize(type_name)
+    candidate = "#{camelize(key)}#{candidate}" if taken.include?(candidate)
+    raise GraphWeaver::Error, "class name collision: #{candidate}" if taken.include?(candidate)
 
     taken << candidate
     candidate