graph_weaver 0.0.1 → 0.2.0

data/lib/graph_weaver/codegen/emit.rb

@@ -0,0 +1,286 @@
+# typed: true
+# frozen_string_literal: true
+
+# Source emission: turns the node tree into the generated module text.
+# Mixed into Codegen — methods run with the generator instance state.
+class GraphWeaver::Codegen
+  module Emit
+    include GraphWeaver::Inflect
+
+    private
+
+    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
+
+    # module-level wire translation tables for an app-mapped enum
+    def emit_mapped_enum(node, out, indent)
+      pad = "  " * indent
+      type = node.bare_type
+      prefix = node.const_prefix
+
+      out << "#{pad}# GraphQL enum #{node.graphql_name} <-> #{type} (registered mapping)"
+      out << "#{pad}#{prefix}_FROM_WIRE = T.let({"
+      node.mapping.each do |wire, member|
+        out << "#{pad}  #{wire.inspect} => #{type}.deserialize(#{member.serialize.to_s.inspect}),"
+      end
+      out << "#{pad}}.freeze, T::Hash[String, #{type}])"
+      out << "#{pad}#{prefix}_TO_WIRE = T.let(#{prefix}_FROM_WIRE.invert.freeze, T::Hash[#{type}, String])"
+    end
+
+    def emit_object(node, out, indent)
+      pad = "  " * indent
+
+      out << "#{pad}class #{node.class_name} < T::Struct"
+      out << "#{pad}  extend T::Sig"
+      out << "#{pad}  include GraphWeaver::Hints"
+      node.mixins.each do |mixin|
+        out << "#{pad}  include #{mixin} # registered for #{node.graphql_type}"
+      end
+      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}  rescue GraphWeaver::TypeError"
+      out << "#{pad}    raise # already wrapped by a nested struct — keep the innermost context"
+      out << "#{pad}  rescue TypeError, ArgumentError, KeyError => e"
+      out << "#{pad}    raise GraphWeaver::TypeError.new(struct: self, error: e)"
+      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 GraphWeaver::TypeError.new(struct: self, message: \"unexpected __typename: \#{typename}\")"
+      out << "#{pad}    end"
+      out << "#{pad}  end"
+      out << "#{pad}end"
+    end
+
+    def emit_execute(out, variables, flatten: nil)
+      out << "  @client = T.let(nil, T.untyped)"
+      out << ""
+      out << "  class << self"
+      out << "    extend T::Sig"
+      out << ""
+      out << "    sig { params(client: T.untyped).void }"
+      out << "    attr_writer :client"
+      out << ""
+      out << "    # default client (a GraphWeaver::Client or any transport) for"
+      out << "    # execute: per-module override, else the app default"
+      out << "    sig { returns(T.untyped) }"
+      out << "    def client"
+      out << "      @client || #{@client_const || "GraphWeaver.client!"}"
+      out << "    end"
+      out << "  end"
+      out << ""
+
+      # the kwarg surface: the input's fields when flattened, else one
+      # kwarg per declared variable — typed identically either way. The
+      # per-call client override rides as an optional POSITIONAL arg, so
+      # variables keep the entire kwarg namespace (nothing is reserved).
+      params = flatten ? flatten.fields.partition(&:required).flatten : variables
+
+      sig_params = ["client: T.untyped"]
+      sig_params += params.map do |param|
+        bare = param.node.coerce? ? param.node.coerce_input_type : param.node.bare_type
+        kwarg_type = param.required || bare == "T.untyped" ? bare : "T.nilable(#{bare})"
+        "#{kwarg_name(param)}: #{kwarg_type}"
+      end
+
+      kwargs = ["client = nil"]
+      kwargs += params.map { |param| param.required ? "#{kwarg_name(param)}:" : "#{kwarg_name(param)}: nil" }
+
+      # execute returns the full envelope; execute! is the strict shortcut for
+      # `execute(...).data!` — the typed result, or a raised QueryError.
+      forward = (["client"] + params.map { |param| "#{kwarg_name(param)}: #{kwarg_name(param)}" }).join(", ")
+
+      if flatten
+        out << "  # $#{variables.first.wire}'s fields, flattened into kwargs (single input-object variable)"
+      end
+      out << "  sig { params(#{sig_params.join(", ")}).returns(GraphWeaver::Response[Result]) }"
+      out << "  def self.execute(#{kwargs.join(", ")})"
+
+      if flatten
+        fields = flatten.fields.map { |field| "#{field.prop}:" }.join(", ")
+        out << "    variables = {"
+        out << "      #{variables.first.wire.inspect} => #{flatten.class_name}.coerce({ #{fields} }).serialize,"
+        out << "    }"
+      else
+        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
+      end
+
+      out << ""
+      out << "    transport = GraphWeaver.resolve_transport(client || self.client)"
+      out << "    raw = transport.execute(QUERY, variables: variables).to_h"
+      out << "    GraphWeaver::Response[Result].new("
+      out << "      data: (Result.from_h(raw[\"data\"]) if raw[\"data\"]),"
+      out << "      errors: (raw[\"errors\"] || []).map { |e| GraphWeaver::GraphQLError.from_h(e) },"
+      out << "      extensions: raw[\"extensions\"] || {},"
+      out << "    )"
+      out << "  end"
+      out << ""
+      out << "  sig { params(#{sig_params.join(", ")}).returns(Result) }"
+      out << "  def self.execute!(#{kwargs.join(", ")})"
+      out << "    execute(#{forward}).data!"
+      out << "  end"
+    end
+
+    # a kwarg surface entry is a VarDef (.kwarg) or, when flattened, an
+    # InputNode::Field (.prop)
+    def kwarg_name(param)
+      param.respond_to?(:kwarg) ? param.kwarg : param.prop
+    end
+
+    def variable_serialize(var)
+      value = var.node.coerce? ? var.node.coerce(var.kwarg) : var.kwarg
+      var.node.serialize_identity? ? value : var.node.serialize(value, 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
+
+    # a module-level T::Struct per input type; serialize builds the wire
+    # hash, omitting optional fields left nil
+    def emit_input(node, out, indent)
+      pad = "  " * indent
+
+      out << "#{pad}class #{node.class_name} < T::Struct"
+      out << "#{pad}  extend T::Sig"
+      out << ""
+      node.fields.each do |field|
+        default = field.required ? "" : ", default: nil"
+        out << "#{pad}  const :#{field.prop}, #{field.node.prop_type}#{default}"
+      end
+      out << ""
+      # locals wear the reserved __gw prefix: prop readers are bare method
+      # calls here, and a prop named "result" or "value" would otherwise
+      # be shadowed — GraphQL reserves __-names, so no field can collide
+      out << "#{pad}  sig { returns(T::Hash[String, T.untyped]) }"
+      out << "#{pad}  def serialize"
+      out << "#{pad}    __gw_result = T.let({}, T::Hash[String, T.untyped])"
+      node.fields.each do |field|
+        if field.required || field.node.serialize_identity?
+          value = field.node.serialize_identity? ? field.prop.to_s : field.node.serialize(field.prop.to_s, 1)
+          line = "__gw_result[#{field.wire.inspect}] = #{value}"
+          line += " unless #{field.prop}.nil?" unless field.required
+          out << "#{pad}    #{line}"
+        else
+          # bind a local so sorbet's flow-sensitivity narrows the nilable
+          out << "#{pad}    unless (__gw_value = #{field.prop}).nil?"
+          out << "#{pad}      __gw_result[#{field.wire.inspect}] = #{field.node.serialize("__gw_value", 1)}"
+          out << "#{pad}    end"
+        end
+      end
+      out << "#{pad}    __gw_result"
+      out << "#{pad}  end"
+      out << ""
+      out << "#{pad}  # serialize, under the conventional name"
+      out << "#{pad}  sig { returns(T::Hash[String, T.untyped]) }"
+      out << "#{pad}  def to_h = serialize"
+      out << ""
+      out << "#{pad}  # Build from a plain hash (underscored keys, Symbol or String):"
+      out << "#{pad}  # enums accept their wire values, nested inputs accept hashes;"
+      out << "#{pad}  # the struct's types are enforced on construction."
+      out << "#{pad}  sig { params(value: T.any(#{node.class_name}, T::Hash[T.untyped, T.untyped])).returns(#{node.class_name}) }"
+      out << "#{pad}  def self.coerce(value)"
+      out << "#{pad}    return value if value.is_a?(#{node.class_name})"
+      out << ""
+      out << "#{pad}    # a typo'd key must not silently drop off the wire"
+      out << "#{pad}    GraphWeaver::Hints.validate_keys!(self, value)"
+      out << ""
+      out << "#{pad}    new("
+      node.fields.each do |field|
+        raw = "value_at(value, :#{field.prop})"
+        expr = if field.node.hash_coerce_identity?
+          raw
+        elsif field.required
+          "#{raw}.then { |v1| #{field.node.hash_coerce("v1", 2)} }"
+        else
+          "#{raw}&.then { |v1| #{field.node.hash_coerce("v1", 2)} }"
+        end
+        out << "#{pad}      #{field.prop}: #{expr},"
+      end
+      out << "#{pad}    )"
+      out << "#{pad}  end"
+      out << ""
+      out << "#{pad}  sig { params(hash: T::Hash[T.untyped, T.untyped], key: Symbol).returns(T.untyped) }"
+      out << "#{pad}  private_class_method def self.value_at(hash, key)"
+      out << "#{pad}    hash.key?(key) ? hash[key] : hash[key.to_s]"
+      out << "#{pad}  end"
+      out << "#{pad}end"
+    end
+  end
+end

data/lib/graph_weaver/codegen/enum_type.rb

@@ -0,0 +1,149 @@
+# typed: true
+# frozen_string_literal: true
+
+class GraphWeaver::Codegen
+  # How one GraphQL enum maps onto an app-owned T::Enum, so generated
+  # code speaks YOUR enum instead of generating one per module:
+  #
+  #      class PetKind < T::Enum
+  #        enums { Cat = new("cat"); Dog = new("dog") }
+  #      end
+  #
+  #      GraphWeaver.register_enum("Species", PetKind)
+  #
+  # The wire mapping is inferred by name ("CAT" <-> PetKind::Cat,
+  # case/underscore-insensitive against each member's serialized value);
+  # map: pins renames explicitly and merges over inference. Every wire
+  # value the schema declares must resolve — generation fails naming the
+  # gaps — unless fallback: names a member to absorb unknown values
+  # (forward-compat for servers that add members; inputs stay strict).
+  class EnumType
+    attr_reader :graphql_name, :type, :fallback, :requires
+
+    def initialize(graphql_name, type, map: nil, fallback: nil, requires: nil)
+      @graphql_name = graphql_name.to_s
+      unless type.is_a?(Class) && type < T::Enum
+        raise ArgumentError, "type: must be a T::Enum subclass, got #{type.inspect}"
+      end
+      unless type.name
+        raise ArgumentError, "type: must be a named constant (anonymous classes can't appear in generated source)"
+      end
+
+      @type = type
+      @map = map || {}
+      @fallback = fallback
+      @requires = Array(requires)
+
+      if fallback && !type.values.include?(fallback)
+        raise ArgumentError, "fallback: must be a #{type} member, got #{fallback.inspect}"
+      end
+    end
+
+    # wire value => member for every value the schema declares; raises
+    # naming the unmappable ones (unless fallback: absorbs them)
+    def mapping_for(wire_values)
+      mapping = {}
+      missing = []
+
+      wire_values.each do |wire|
+        member = @map[wire] || infer(wire)
+        member ? mapping[wire] = member : missing << wire
+      end
+
+      if missing.any? && !fallback
+        raise GraphWeaver::Error,
+          "#{type} has no member for #{graphql_name} value(s) #{missing.join(", ")} — " \
+          "add them, pin with map:, or absorb with fallback:"
+      end
+
+      mapping
+    end
+
+    private
+
+    # "CAT" matches serialize "cat"; "NOT_FOUND" matches "not_found"
+    def infer(wire)
+      @type.values.find { |member| normalize(member.serialize.to_s) == normalize(wire) }
+    end
+
+    def normalize(value)
+      value.downcase.delete("_")
+    end
+  end
+
+  class << self
+    # Map a GraphQL enum onto an app-owned T::Enum (see EnumType); the
+    # global default — client.register_enum scopes to one client.
+    def register_enum(graphql_name, type, map: nil, fallback: nil, requires: nil)
+      enum_registry[graphql_name.to_s] = EnumType.new(graphql_name, type, map:, fallback:, requires:)
+    end
+
+    # Bulk, inference-only form: register_enums("Species" => PetKind, ...)
+    def register_enums(mappings)
+      mappings.each { |graphql_name, type| register_enum(graphql_name, type) }
+    end
+
+    def enum_registry
+      @enum_registry ||= {}
+    end
+
+    # 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)
+    #
+    # 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
+    #        def display_name = "#{name} the pet"
+    #      end
+    #
+    # Additive: repeated registrations (and client-scoped ones) stack.
+    def register_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
+
+    def type_registry
+      @type_registry ||= {}
+    end
+
+    # shared with Client#register_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
+      mixins << helper_module(graphql_name, block) if block
+
+      raise ArgumentError, "pass one or more helper modules, or a block" if mixins.empty?
+      mixins.each do |mixin|
+        unless mixin.is_a?(Module) && mixin.name
+          raise ArgumentError, "type helpers must be named modules, got #{mixin.inspect}"
+        end
+      end
+
+      entry[:mixins].concat(mixins)
+      entry[:requires].concat(Array(requires))
+      entry
+    end
+
+    # a block-built mixin needs a name generated files can reference:
+    # GraphWeaver::TypeHelpers::Pet (suffixed on re-registration)
+    def helper_module(graphql_name, block)
+      base = GraphWeaver::Inflect.camelize(graphql_name.to_s)
+      name = base
+      count = 1
+      name = "#{base}V#{count += 1}" while GraphWeaver::TypeHelpers.const_defined?(name, false)
+      GraphWeaver::TypeHelpers.const_set(name, Module.new(&block))
+    end
+    private :helper_module
+  end
+end
+
+module GraphWeaver
+  # Home of block-built type helpers (register_type with a block), which
+  # need constant names so generated files can reference them.
+  module TypeHelpers; end
+end