graph_weaver 0.5.0 → 0.6.0

data/lib/graph_weaver/codegen/emit.rb

@@ -1,6 +1,8 @@
 # typed: true
 # frozen_string_literal: true
 
+require_relative "../version"
+
 # Source emission: turns the node tree into the generated module text.
 # Mixed into Codegen — methods run with the generator instance state.
 class GraphWeaver::Codegen
@@ -137,7 +139,7 @@ class GraphWeaver::Codegen
       out << "# typed: strict"
       out << "# frozen_string_literal: true"
       out << ""
-      out << "# Generated by GraphWeaver — do not edit. Shared types for this schema —"
+      out << "# Generated by GraphWeaver #{GraphWeaver::VERSION} — do not edit. Shared types for this schema —"
       out << "# input types, enums, and unions hoisted from shared fragments — one file"
       out << "# per type; query modules alias what they use."
       out << ""
@@ -146,13 +148,13 @@ class GraphWeaver::Codegen
         requires.each { |req| out << "require #{req.inspect}" }
         out << ""
       end
-      out << "module #{@module_name}; end"
+      out << "module #{@name}; end"
       out << ""
       if inputs.any?
         out << "# runtime-only forward declarations: input types reference each other"
         out << "# across files, so every constant must exist before any definition loads"
         out << "# (srb sees only the full bodies)"
-        out << "module #{@module_name}"
+        out << "module #{@name}"
         out << "  eval(<<~RUBY, binding, __FILE__, __LINE__ + 1)"
         inputs.each { |input| out << "    class #{input.class_name} < T::Struct; end" }
         out << "  RUBY"
@@ -180,9 +182,9 @@ class GraphWeaver::Codegen
       out << "# typed: strict"
       out << "# frozen_string_literal: true"
       out << ""
-      out << "# Generated by GraphWeaver — do not edit."
+      out << "# Generated by GraphWeaver #{GraphWeaver::VERSION} — do not edit."
       out << ""
-      out << "module #{@module_name}"
+      out << "module #{@name}"
       yield(out)
       out << "end"
 
@@ -210,7 +212,7 @@ class GraphWeaver::Codegen
       out << "# typed: strict"
       out << "# frozen_string_literal: true"
       out << ""
-      out << "# Generated by GraphWeaver — do not edit."
+      out << "# Generated by GraphWeaver #{GraphWeaver::VERSION} — do not edit."
       out << ""
       requires = @requires.uniq.sort
       if requires.any?
@@ -223,7 +225,7 @@ class GraphWeaver::Codegen
         out << "require_relative \"types\""
         out << ""
       end
-      out << "module #{@module_name}"
+      out << "module #{@name}"
       out << "  extend T::Sig" << "" if GraphWeaver.extend_t_sig?
       # a GraphQL block string could contain a bare GRAPHQL line, which
       # would terminate the heredoc early — pick a delimiter the query
@@ -266,7 +268,10 @@ class GraphWeaver::Codegen
         out << ""
         out << "    # #{node.graphql_type} #{node.key_fields.map { |set| "@key(fields: #{set.inspect})" }.join(" ")}"
         sig = node.params.map { |param| "#{param.kwarg}: #{param.type}" }.join(", ")
-        out << "    sig { params(#{sig}).returns(T::Hash[String, T.untyped]) }"
+        # .checked(:never), as on execute: an untyped value (a Rails param)
+        # reaches the coercion in the body instead of sorbet-runtime's
+        # argument check; srb tc still holds typed call sites.
+        out << "    sig { params(#{sig}).returns(T::Hash[String, T.untyped]).checked(:never) }"
         kwargs = node.params.map { |param| param.required ? "#{param.kwarg}:" : "#{param.kwarg}: nil" }.join(", ")
         out << "    def self.#{node.method_name}(#{kwargs})"
         out << "      GraphWeaver::Representation.build(#{node.graphql_type.inspect}, {"
@@ -369,9 +374,10 @@ class GraphWeaver::Codegen
       end
       out << "#{pad}    )"
       out << "#{pad}  rescue GraphWeaver::Error"
-      out << "#{pad}    raise # already branded by a nested struct — keep the innermost context"
-      out << "#{pad}  rescue StandardError => e" # a scalar's cast may raise anything
-      out << "#{pad}    raise GraphWeaver::TypeError.new(struct: self, error: e)"
+      out << "#{pad}    raise # already branded by a nested struct or leaf — keep the innermost context"
+      out << "#{pad}  rescue StandardError => e" # sorbet's prop check, mostly
+      out << "#{pad}    raise GraphWeaver::TypeError.new(struct: self, " \
+        "message: GraphWeaver::Hints.cast_message(self, data, e))"
       out << "#{pad}  end"
 
       # alias delegators (extend_type alias:) — typed accessors that project a
@@ -430,6 +436,8 @@ class GraphWeaver::Codegen
         out << ""
         out << "  # the baked default client, resolved on first use"
         out << "  DEFAULT_CLIENT = T.let(-> { #{@client_const} }, T.proc.returns(T.untyped))"
+        # QueryModule reads it with const_get, which privacy doesn't block
+        out << "  private_constant :DEFAULT_CLIENT"
       end
       out << ""
 
@@ -445,23 +453,58 @@ class GraphWeaver::Codegen
       ordered = required + optional
 
       sig_params = ordered.map do |var|
-        bare = var.node.coerce? ? var.node.coerce_input_type : var.node.bare_type
+        bare = var.node.input_type
         kwarg_type = var.required || bare == "T.untyped" ? bare : "T.nilable(#{bare})"
         "#{var.kwarg}: #{kwarg_type}"
       end
       sig_params << "client: T.untyped"
 
+      # GraphQL tells an absent variable from an explicit null; a Ruby kwarg
+      # with a nil default cannot. The default expression runs exactly when
+      # the keyword was left out, which is the missing third state — so
+      # `execute(bio: nil)` clears a bio and `execute()` leaves it alone.
+      # Only where the schema permits null: a non-null variable can't take
+      # one, so nil there still means omit and let its default apply.
+      omitted = optional.reject { |var| var.node.non_null? }
+        .to_h { |var| [var, "#{var.kwarg}_omitted"] }
+
       kwargs = required.map { |var| "#{var.kwarg}:" } +
-        optional.map { |var| "#{var.kwarg}: nil" } + ["client: nil"]
+        optional.map { |var|
+          flag = omitted[var]
+          flag ? "#{var.kwarg}: (#{flag} = true; nil)" : "#{var.kwarg}: nil"
+        } + ["client: nil"]
 
-      # execute returns the full envelope; execute! is the strict shortcut for
-      # `execute(...).data!` — the typed result, or a raised QueryError.
-      # kwargs forward via hash shorthand (key == value)
-      forward = (ordered.map { |var| "#{var.kwarg}:" } + ["client:"]).join(", ")
+      call = "client_for(client).execute(QUERY, variables:, operation_name: OPERATION_NAME)"
 
-      out << "  sig { params(#{sig_params.join(", ")}).returns(GraphWeaver::Response[Result]) }"
+      # execute returns the full envelope; execute! is the strict shortcut for
+      # the typed result, or a raised QueryError.
+      out << "  # .checked(:never): an untyped value (a Rails param) reaches the coercion below"
+      out << "  # instead of sorbet-runtime's argument check; srb tc still holds typed call sites."
+      out << "  sig { params(#{sig_params.join(", ")}).returns(GraphWeaver::Response[Result]).checked(:never) }"
       out << "  def self.execute(#{kwargs.join(", ")})"
+      emit_variables(out, required, optional, omitted)
+      out << ""
+      out << "    from_response(#{call})"
+      out << "  end"
+      out << ""
+      out << "  sig { params(#{sig_params.join(", ")}).returns(Result).checked(:never) }"
+      out << "  def self.execute!(#{kwargs.join(", ")})"
+      if omitted.empty?
+        # kwargs forward via hash shorthand (key == value)
+        out << "    execute(#{(ordered.map { |var| "#{var.kwarg}:" } + ["client:"]).join(", ")}).data!"
+      else
+        # repeats the variables rather than delegating: which keywords were
+        # left out is exactly what a Ruby call can't forward
+        emit_variables(out, required, optional, omitted)
+        out << ""
+        out << "    from_response(#{call}).data!"
+      end
+      out << "  end"
+      out << ""
+      emit_from_response(out)
+    end
 
+    def emit_variables(out, required, optional, omitted)
       if required.empty?
         out << "    variables = {}"
       else
@@ -472,19 +515,15 @@ class GraphWeaver::Codegen
         out << "    }"
       end
       optional.each do |var|
-        out << "    variables[#{var.wire.inspect}] = #{variable_serialize(var)} unless #{var.kwarg}.nil?"
+        value = variable_serialize(var)
+        if (flag = omitted[var])
+          # nil is a value here, so the serializer has to be stepped around
+          value = "(#{var.kwarg}.nil? ? nil : #{value})" unless value == var.kwarg
+          out << "    variables[#{var.wire.inspect}] = #{value} unless #{flag}"
+        else
+          out << "    variables[#{var.wire.inspect}] = #{value} unless #{var.kwarg}.nil?"
+        end
       end
-
-      out << ""
-      out << "    from_response(client_for(client).execute(QUERY, variables:, operation_name: OPERATION_NAME))"
-      out << "  end"
-      out << ""
-      out << "  sig { params(#{sig_params.join(", ")}).returns(Result) }"
-      out << "  def self.execute!(#{kwargs.join(", ")})"
-      out << "    execute(#{forward}).data!"
-      out << "  end"
-      out << ""
-      emit_from_response(out)
     end
 
     # The network-free half of execute: deserialize a raw GraphQL response
@@ -499,10 +538,13 @@ class GraphWeaver::Codegen
       out << "  # \"errors\" => ..., \"extensions\" => ...} with wire-cased string keys."
       out << "  sig { params(response: T.untyped).returns(GraphWeaver::Response[Result]) }"
       out << "  def self.from_response(response)"
-      out << "    raw = GraphWeaver.check_envelope!(response.to_h, Result)"
+      out << "    raw = GraphWeaver.check_envelope!(response, Result)"
+      # errors first: a cast failure is usually a field the server nulled for
+      # a reason it stated, and that reason belongs in the raised error
+      out << "    errors = (raw[\"errors\"] || []).map { |e| GraphWeaver::GraphQLError.from_h(e) }"
       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 << "      data: (GraphWeaver.cast_data(Result, raw[\"data\"], errors) if raw[\"data\"]),"
+      out << "      errors:,"
       out << "      extensions: raw[\"extensions\"] || {},"
       out << "    )"
       out << "  end"
@@ -514,21 +556,36 @@ class GraphWeaver::Codegen
       out << "  end"
     end
 
+    # A kwarg's trip onto the wire: normalize whatever arrived into the type
+    # the sig promises — the sig itself is `.checked(:never)`, so this is the
+    # check — then serialize. Coercion is wrapped so a refusal names the
+    # variable and the operation; the value alone locates nothing.
     def variable_serialize(var)
-      value = var.node.coerce? ? var.node.coerce(var.kwarg) : var.kwarg
+      value = if var.node.coerce?
+        "GraphWeaver::Coerce.variable(#{var.wire.inspect}, OPERATION_NAME, #{var.kwarg}) " \
+          "{ |v| #{var.node.coerce("v")} }"
+      else
+        var.kwarg
+      end
       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
+      cast =
+        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
+      return cast if node.identity? || !node.leaf?
+
+      # a leaf's cast raises about the value alone ("invalid date"); nothing
+      # else in the trace says which of the struct's four dates it was
+      "GraphWeaver::Hints.field(self, #{field.key.inspect}) { #{cast} }"
     end
 
     # A module-level T::Struct per input type: typed consts plus a FIELDS
@@ -545,11 +602,17 @@ class GraphWeaver::Codegen
       if node.one_of
         out << "#{pad}  # @oneOf: every field is nullable, so exactly-one is checked at runtime"
         out << "#{pad}  ONE_OF = T.let(true, T::Boolean)"
+        out << "#{pad}  private_constant :ONE_OF"
         out << ""
       end
       node.fields.each do |field|
+        # A schema default makes the field optional here, so the prop has to
+        # admit the nil that omitting it leaves behind — the same widening
+        # execute's kwargs already get.
+        type = field.node.prop_type
+        type = "T.nilable(#{type})" if !field.required && field.node.non_null? && type != "T.untyped"
         default = field.required ? "" : ", default: nil"
-        out << "#{pad}  const :#{field.prop}, #{field.node.prop_type}#{default}"
+        out << "#{pad}  const :#{field.prop}, #{type}#{default}"
       end
       out << ""
       out << "#{pad}  # (prop, wire, required, serializer, coercer) per field"
@@ -560,6 +623,8 @@ class GraphWeaver::Codegen
         out << "#{pad}    GraphWeaver::InputStruct::Field.new(:#{field.prop}, #{field.wire.inspect}, #{field.required}, #{serializer}, #{coercer}),"
       end
       out << "#{pad}  ].freeze, T::Array[GraphWeaver::InputStruct::Field])"
+      # InputStruct reads it with const_get, which privacy doesn't block
+      out << "#{pad}  private_constant :FIELDS"
       out << "#{pad}end"
     end
   end

data/lib/graph_weaver/codegen/enum_type.rb

@@ -27,9 +27,7 @@ class GraphWeaver::Codegen
       # autoloading is set up after those run. Say where it does resolve.
       if type.is_a?(String)
         raise ArgumentError, "type: is the T::Enum itself, not its name — " \
-          "register_enum(#{@graphql_name.inspect}, #{type}). An autoloaded constant isn't " \
-          "resolvable while config/initializers run; register from a " \
-          "Rails.application.config.to_prepare block, which generation also runs first."
+          "register_enum(#{@graphql_name.inspect}, #{type}). #{GraphWeaver::Codegen::AUTOLOAD_HINT}"
       end
       unless type.is_a?(Class) && type < T::Enum
         raise ArgumentError, "type: must be a T::Enum subclass, got #{type.inspect}"
@@ -107,4 +105,7 @@ class GraphWeaver::Codegen
       self
     end
   end
+
+  # codegen's own record of a register_enum mapping
+  private_constant :EnumType
 end

data/lib/graph_weaver/codegen/nodes.rb

@@ -8,14 +8,23 @@ require "forwardable"
 # cast/serialize code to emit.
 class GraphWeaver::Codegen
   # 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?,
+  # protocol: bare_type, prop_type, cast(expr, depth), identity?, leaf?,
+  # serialize(expr, depth), serialize_identity?, input_type, coerce?,
+  # coerce(expr), 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})"
+    # The Sorbet type an execute kwarg (or input-struct field) accepts. Same
+    # as the prop type for anything a caller can only pass as itself; wider
+    # where a wire spelling is also accepted (an enum, an input hash).
+    # Independent of #coerce: the sig says what typechecks, the body
+    # normalizes whatever actually arrives.
+    def input_type = bare_type
     def identity? = false
+    # a scalar or enum: its cast is arbitrary code that raises on its own
+    # terms, so the field name has to be attached from outside
+    def leaf? = false
     def serialize_identity? = false
     def coerce? = false
     def hash_coerce_identity? = false
@@ -48,6 +57,8 @@ class GraphWeaver::Codegen
       !@scalar.cast?
     end
 
+    def leaf? = true
+
     def serialize(expr, _depth)
       @scalar.serialize(expr)
     end
@@ -56,15 +67,14 @@ class GraphWeaver::Codegen
       !@scalar.serialize?
     end
 
-    # coercion (coerce: per scalar, or GraphWeaver.auto_coerce for all):
-    # accept the value or its raw input and normalize before serializing.
-    # See ScalarType#coercion.
+    # An untyped value reaching the kwarg is normalized to the scalar's Ruby
+    # type before it is serialized — the sig stays narrow. See
+    # ScalarType#coerce_input.
     def coerce? = @scalar.coerce?
     def coerce(expr) = @scalar.coerce_input(expr)
-    def coerce_input_type = @scalar.coerce_type
 
-    # inside input-struct hashes, scalars coerce exactly like variable
-    # kwargs do — the registry (incl. GraphWeaver.auto_coerce) decides
+    # inside input-struct hashes, scalars coerce exactly as variable
+    # kwargs do
     def hash_coerce(expr, _depth)
       @scalar.coerce_input(expr) || expr
     end
@@ -79,8 +89,8 @@ class GraphWeaver::Codegen
 
     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_delegators :@of, :bare_type, :cast, :identity?, :leaf?, :serialize, :serialize_identity?,
+      :input_type, :coerce?, :coerce, :hash_coerce, :hash_coerce_identity?, :nested
 
     def initialize(of)
       @of = of
@@ -113,6 +123,7 @@ class GraphWeaver::Codegen
     end
 
     def identity? = @of.identity?
+    def leaf? = @of.leaf?
 
     def serialize(expr, depth)
       var = "v#{depth}"
@@ -134,9 +145,9 @@ class GraphWeaver::Codegen
     def coerce? = !hash_coerce_identity?
     def coerce(expr) = hash_coerce(expr, 1)
 
-    def coerce_input_type
-      element = @of.coerce? ? @of.coerce_input_type : @of.prop_type
-      element = "T.nilable(#{element})" if @of.coerce? && !@of.non_null? && element != "T.untyped"
+    def input_type
+      element = @of.input_type
+      element = "T.nilable(#{element})" if !@of.non_null? && element != "T.untyped"
       "T::Array[#{element}]"
     end
 
@@ -193,22 +204,24 @@ class GraphWeaver::Codegen
     def bare_type = class_name
 
     def cast(expr, _depth)
-      "#{class_name}.deserialize(#{expr})"
+      "GraphWeaver::Hints.enum(#{class_name}, #{expr})"
     end
 
     def serialize(expr, _depth)
       "#{expr}.serialize"
     end
 
+    def leaf? = true
+
     # enums always coerce: a kwarg or hash field accepts the T::Enum or
     # its wire value (deserialize raises on anything else)
     def coerce? = true
 
     def coerce(expr)
-      "(#{expr}.is_a?(#{class_name}) ? #{expr} : #{class_name}.deserialize(#{expr}))"
+      "GraphWeaver::InputStruct.enum(#{class_name}, #{expr})"
     end
 
-    def coerce_input_type = "T.any(#{class_name}, String)"
+    def input_type = "T.any(#{class_name}, String)"
     def hash_coerce(expr, _depth) = coerce(expr)
     def nested = self
   end
@@ -236,7 +249,7 @@ class GraphWeaver::Codegen
       if @fallback
         "#{const_prefix}_FROM_WIRE.fetch(#{expr}) { #{fallback_const} }"
       else
-        "#{const_prefix}_FROM_WIRE.fetch(#{expr})"
+        "GraphWeaver::Hints.mapped_enum(#{@type_name}, #{const_prefix}_FROM_WIRE, #{expr})"
       end
     end
 
@@ -244,16 +257,18 @@ class GraphWeaver::Codegen
       "#{const_prefix}_TO_WIRE.fetch(#{expr})"
     end
 
+    def leaf? = true
+
     # 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)
     def coerce? = true
 
     def coerce(expr)
-      "(#{expr}.is_a?(#{@type_name}) ? #{expr} : #{const_prefix}_FROM_WIRE.fetch(#{expr}))"
+      "GraphWeaver::InputStruct.mapped_enum(#{@type_name}, #{const_prefix}_FROM_WIRE, #{expr})"
     end
 
-    def coerce_input_type = "T.any(#{@type_name}, String)"
+    def input_type = "T.any(#{@type_name}, String)"
     def hash_coerce(expr, _depth) = coerce(expr)
   end
 
@@ -360,7 +375,7 @@ class GraphWeaver::Codegen
 
     def coerce? = true
     def coerce(expr) = "#{class_name}.coerce(#{expr})"
-    def coerce_input_type = "T.any(#{class_name}, T::Hash[T.untyped, T.untyped])"
+    def input_type = "T.any(#{class_name}, T::Hash[T.untyped, T.untyped])"
 
     # building a struct field from a caller-supplied plain hash value
     def hash_coerce(expr, _depth) = "#{class_name}.coerce(#{expr})"
@@ -391,4 +406,10 @@ class GraphWeaver::Codegen
       @params = params
     end
   end
+
+  # The IR is codegen's own vocabulary — every node type is reachable only
+  # from inside the walk.
+  private_constant :Node, :Scalar, :NonNull, :List, :ObjectNode, :EnumNode,
+    :MappedEnum, :NarrowedNode, :UnionNode, :UnionRefNode, :InputNode,
+    :RepresentationNode
 end