graph_weaver 0.7.3 → 0.7.4

data/lib/graph_weaver/codegen/scalar_type.rb

@@ -56,6 +56,8 @@ class GraphWeaver::Codegen
     # is the whole rule, so key on that — a custom scalar registered as a
     # plain String gets the same check. ID is the exception GraphQL itself
     # names (see Coerce.id), matched by GraphQL name in #coercer.
+    # Read back off the wire too, where the type is one JSON already holds
+    # (see #wire_cast).
     COERCERS = {
       "Integer" => "integer",
       "Float" => "float",
@@ -83,15 +85,15 @@ class GraphWeaver::Codegen
 
     STDLIB = {
       "BigDecimal" => { serialize: [:to_s, "F"], requires: "bigdecimal" },
-      # JSON has one number type, so a whole Float arrives as `1` from every
-      # encoder that drops the trailing zero (graphql-js and Go both do)
-      "Float" => { cast: ->(expr) { "GraphWeaver::Coerce.float(#{expr})" } },
       # strftime, not #iso8601: DateTime < Date passes the is_a? guard, and its
       # #iso8601 writes a timestamp where the schema said a date goes
       "Date" => { cast: :iso8601, serialize: [:strftime, "%F"], requires: "date" },
-      # #iso8601 takes no precision, so it writes whole seconds and a
-      # sub-second timestamp goes back out poorer than it came in
-      "Time" => { cast: :parse, serialize: TIMESTAMP, call: TIMESTAMP_CALL, requires: "time" },
+      # Time.iso8601, not Time.parse: the latter also reads "Jan 15 2024
+      # 10:20", which no spec-compliant server writes, at 3× the cost.
+      # Writing back goes through Coerce.timestamp rather than #iso8601,
+      # which takes no precision — a sub-second timestamp would go out
+      # poorer than it came in.
+      "Time" => { cast: :iso8601, serialize: TIMESTAMP, call: TIMESTAMP_CALL, requires: "time" },
       "DateTime" => { cast: :iso8601, serialize: TIMESTAMP, call: TIMESTAMP_CALL, requires: "date" },
     }.freeze
 
@@ -122,11 +124,12 @@ class GraphWeaver::Codegen
         end
       @cast_given = cast unless cast == :itself
       codec = @klass && CODECS.find { |c| @klass.respond_to?(c.probe) }
-      @cast = normalize_cast(cast || known[:cast], codec&.cast || kernel_cast)
+      @cast = normalize_cast(cast || known[:cast], wire_cast || codec&.cast || kernel_cast)
       @serialize = normalize_serialize(serialize || known[:serialize], codec&.serialize)
       @serialize_value = (known[:call] if serialize.nil?) ||
         runtime_serialize(serialize || known[:serialize], codec)
       warn_half_a_value_object
+      warn_half_a_codec(serialize)
     end
 
     def cast(expr) = @cast&.call(expr)
@@ -145,6 +148,10 @@ class GraphWeaver::Codegen
       @serialize_value.call(value)
     end
 
+    # Whether #serialize_value actually runs this registration's serializer,
+    # rather than passing the value through for want of one to run.
+    def serialize_value? = !@serialize_value.nil?
+
     # The code that normalizes a loose input — a Rails param — into this
     # scalar's Ruby type before it is serialized, or nil for nothing to do.
     # The Ruby type's own rule in Coerce is the check, which is what
@@ -207,6 +214,32 @@ class GraphWeaver::Codegen
       end
     end
 
+    # The other half of the same rule: a registration says both directions or
+    # is told what it can't do. A cast with nothing to write back reads the
+    # wire and can't put a variable of that scalar onto it, and a result's
+    # #as_json can't reproduce what the server sent — both silent, since
+    # `#to_json` answers for any object.
+    def warn_half_a_codec(serialize)
+      # nothing said and nothing inferred: `serialize: :itself` said it, and a
+      # Ruby type JSON already holds has no other half to name
+      return if !cast? || serialize? || !serialize.nil? || json_shaped?
+
+      GraphWeaver::Internal::Log.log(:warn) do
+        "register_scalar(#{@graphql_name.inspect}, #{@klass ? @type : @type.inspect}): cast: reads " \
+          "#{GraphWeaver::Internal::Util.article(@type)} #{@type} off the wire and nothing writes one " \
+          "back — a #{@graphql_name} variable goes out as whatever #to_json makes of it, and a result's " \
+          "#as_json can't reproduce what the server sent. Name the other half (serialize: :to_s names an " \
+          "instance method, serialize: [:to_s, \"F\"] passes it arguments, " \
+          "serialize: ->(v) { \"\#{v}.to_s\" } emits any expression), or serialize: :itself if the value " \
+          "really does go out as it is"
+      end
+    end
+
+    # A Ruby type JSON already holds writes itself, subclasses included
+    def json_shaped?
+      wire_class?(@type) || (!@klass.nil? && WIRE_CLASSES.any? { |native| @klass <= native })
+    end
+
     def defines?(method)
       ![BasicObject, Kernel, Object].include?(@klass.instance_method(method).owner)
     end
@@ -231,13 +264,31 @@ class GraphWeaver::Codegen
       end
     end
 
+    # `register_scalar("Count", Integer)` says the scalar IS an Integer, so the
+    # library's own rule for that class runs in both directions — the entry
+    # #coercer brands a variable with, reading the wire as well. It is the
+    # lenient reading: a custom scalar is the server's own, and may write the
+    # number as a string where the spec's `Int` may not (which is why the
+    # pre-registered Int/String/Boolean/ID opt out with `cast: :itself`).
+    # Only the wire class itself — Coerce hands back the plain type, so a
+    # subclass would land in a prop it doesn't satisfy — and only where Coerce
+    # has a rule, leaving Hash and Array passing through.
+    def wire_cast
+      return unless wire_class?(@type) && (fn = COERCERS[@type])
+
+      ->(_type, expr) { "GraphWeaver::Coerce.#{fn}(#{expr}, #{@graphql_name.inspect})" }
+    end
+
+    # T::Boolean is the pair TrueClass/FalseClass, spelled as Sorbet types it
+    def wire_class?(name) = name == "T::Boolean" || WIRE_CLASSES.any? { |native| native.name == name }
+
     # Kernel's conversion functions are how a wire value becomes one of these
     # — BigDecimal defines neither .parse nor .load, but Kernel#BigDecimal has
     # read a decimal string all along. Only for a type the wire can't already
     # be: Kernel#String and Kernel#Array wrap a value rather than convert it.
     def kernel_cast
       return unless Kernel.private_method_defined?(@type.to_sym)
-      return if WIRE_CLASSES.any? { |native| native.name == @type }
+      return if wire_class?(@type)
 
       ->(type, expr) { "#{type}(#{expr})" }
     end
@@ -373,12 +424,15 @@ class GraphWeaver::Codegen
     # Pre-registered scalars — ordinary entries in the one registry, so a
     # later register_scalar overrides any of them.
     #
-    # The five the spec names stay pass-through: their Ruby classes (String,
-    # Integer) define neither .parse nor .load, so inference matches nothing
-    # and leaves them identity — which is exactly why we can name them with
-    # the real class constants. Float is the exception, and its rule lives in
-    # STDLIB with the others, so `register_scalar "Ratio", Float` reads the
-    # wire exactly as the built-in Float does.
+    # Four of the five the spec names stay pass-through coming back —
+    # `cast: :itself` — because the spec guarantees their JSON type, so
+    # checking it would cost a call on the commonest leaves in every response
+    # and refuse nothing a compliant server sends. (Going out is another
+    # matter: a Rails param is a String whatever the sig says, so the same
+    # scalars still coerce there.) A scalar an app registers as one of those
+    # classes is the server's own, and gets the rule in both directions.
+    # Float is the exception even coming back: JSON has one number type, so
+    # `1.0` arrives as `1` from graphql-js and from Go.
     #
     # The rest are names, not guesses: graphql-ruby ships all but DateTime as
     # its own scalars, and this library runs a graphql-ruby schema in-process.
@@ -388,11 +442,11 @@ class GraphWeaver::Codegen
     # away. Date and datetime are told apart by their Ruby type — a Date cast
     # to Time would invent a midnight the server never sent.
     def register_builtin_scalars!
-      register_scalar "ID", String
-      register_scalar "String", String
-      register_scalar "Int", Integer
+      register_scalar "ID", String, cast: :itself
+      register_scalar "String", String, cast: :itself
+      register_scalar "Int", Integer, cast: :itself
       register_scalar "Float", Float
-      register_scalar "Boolean", "T::Boolean"
+      register_scalar "Boolean", "T::Boolean", cast: :itself
       register_scalar "Date", Date
       register_scalar "ISO8601Date", Date
       register_scalar "ISO8601DateTime", Time

data/lib/graph_weaver/codegen/type_helpers.rb

@@ -45,10 +45,21 @@ class GraphWeaver::Codegen
     # fit the path just omits the accessor instead of failing generation. Use it
     # for a root-type accessor (a Query alias every query would otherwise have to
     # satisfy) or one that only fits some selections.
+    #
+    # Inside the block, `alias_field` is the same keyword said next to the
+    # methods that use it — one alias per line, always strict:
+    #
+    #      GraphWeaver.extend_type("Widget") do
+    #        alias_field :tag, "meta.tag"
+    #        def shout = tag&.upcase
+    #      end
     def extend_type(graphql_name, *mixins, requires: nil, **kw, &block)
-      aliases = take_aliases(kw)
+      optional = !!kw.delete(:optional)
+      aliases = normalize_aliases(kw.delete(:alias), optional:)
+      raise ArgumentError, "unknown keyword: #{kw.keys.first}" unless kw.empty?
+
       mixins = mixins.dup
-      mixins << helper_module(graphql_name, block) if block
+      mixins << helper_module(graphql_name, block, aliases) if block
 
       raise ArgumentError, "pass one or more helper modules, a block, or alias:" if mixins.empty? && aliases.empty?
       mixins.each do |mixin|
@@ -70,15 +81,6 @@ class GraphWeaver::Codegen
       entry
     end
 
-    # Pull alias:/optional: out of the keyword rest and normalize; any other
-    # keyword is a typo worth flagging rather than silently dropping.
-    def take_aliases(kw)
-      aliases = normalize_aliases(kw.delete(:alias), optional: !!kw.delete(:optional))
-      raise ArgumentError, "unknown keyword: #{kw.keys.first}" unless kw.empty?
-      aliases
-    end
-    private :take_aliases
-
     # accessor names and path segments are interpolated verbatim into generated
     # source, so — like module_name — they must be plain identifiers, never
     # arbitrary text that could inject code
@@ -138,7 +140,7 @@ class GraphWeaver::Codegen
     # naming it after whichever constants happened to exist made it a function
     # of how many times THIS process had read the registry, and `generate`
     # wrote a name a plain boot never creates.
-    def helper_module(graphql_name, block)
+    def helper_module(graphql_name, block, aliases)
       namespace = helper_namespace
       type = GraphWeaver::Inflect.camelize(graphql_name.to_s)
       index = (helper_counts[[namespace.name, type]] += 1)
@@ -146,11 +148,67 @@ class GraphWeaver::Codegen
       # reused rather than replaced, so re-declaring the same source (a Rails
       # to_prepare reload) keeps the module already-loaded structs include
       mod = const_under(namespace, name) { Module.new }
-      mod.module_eval(&block)
+      aliases.merge!(collect_aliases(graphql_name, mod, aliases, &block))
       mod
     end
     private :helper_module
 
+    # Run the block with `alias_field` available — the alias: keyword said one
+    # line at a time — and hand back what it collected.
+    #
+    # It lives on the module's singleton for the length of the block and is
+    # removed after: a generated struct includes this module, and an
+    # `alias_field` left behind would be an instance method the wire never named.
+    def collect_aliases(graphql_name, mod, keyword_aliases, &block)
+      registry, collected = self, {}
+      mod.define_singleton_method(:alias_field) do |name, path = nil, **kw|
+        collected.merge!(registry.send(:one_alias, graphql_name, name, path, kw))
+      end
+      mod.module_eval(&block)
+
+      twice = keyword_aliases.keys & collected.keys
+      unless twice.empty?
+        raise ArgumentError, "extend_type(#{graphql_name.to_s.inspect}) declares alias " \
+          "#{twice.first.inspect} twice — once as alias:, once as alias_field; keep one"
+      end
+      collected
+    ensure
+      mod.singleton_class.send(:remove_method, :alias_field)
+    end
+    private :collect_aliases
+
+    ALIAS_FIELD_FORMS = %(one alias per line — alias_field "meta.tag", or alias_field :tag, "meta.tag"; ) +
+      %(a Hash or Array of paths goes on the alias: keyword)
+    private_constant :ALIAS_FIELD_FORMS
+
+    # One `alias_field` line, normalized the way the keyword's own paths are.
+    # The block takes no optional: — leniency has one spelling, on the keyword,
+    # because it is a property of the registration and not of one accessor.
+    def one_alias(graphql_name, name, path, kw)
+      if kw.key?(:optional)
+        keyword = path ? "alias: { #{name}: #{path.inspect} }" : "alias: #{name.inspect}"
+        raise ArgumentError, "alias_field is always strict — for a lenient alias use the keyword: " \
+          "extend_type(#{graphql_name.to_s.inspect}, #{keyword}, optional: true)"
+      end
+      raise ArgumentError, "unknown keyword: #{kw.keys.first}" unless kw.empty?
+
+      input = if path.nil? && name.is_a?(String)
+        name
+      elsif path.is_a?(String) && (name.is_a?(String) || name.is_a?(Symbol))
+        { name => path }
+      end
+      if input.nil?
+        # spelled as a caller writes it — Hash#inspect changed between Ruby 3.3 and 3.4
+        given = [name, path].compact.map do |arg|
+          arg.is_a?(Hash) ? "{#{arg.map { |k, v| "#{k}: #{v.inspect}" }.join(", ")}}" : arg.inspect
+        end.join(", ")
+        raise ArgumentError, "alias_field #{given}: #{ALIAS_FIELD_FORMS}"
+      end
+
+      normalize_aliases(input, optional: false)
+    end
+    private :one_alias
+
     # Where this registry's block-built helpers live: under a module named for
     # the graph, so two graphs extending the same type get two constants and
     # neither has to know the other exists.

data/lib/graph_weaver/codegen.rb

@@ -154,6 +154,12 @@ class GraphWeaver::Codegen
   # queries so the build says them once, for GraphWeaver.untyped_scalars.
   def untyped_scalars = @untyped_scalars.uniq.sort
 
+  # The block-built type helpers this walk included, by constant name. They are
+  # minted at registration, so no source file declares them and an app's
+  # `srb tc` can't resolve the include this emitted — the generate! workflow
+  # unions these across queries and declares them in an .rbi.
+  def block_helpers = @block_helpers.uniq.sort
+
   # The shared types artifact: every type a schema shares across query modules,
   # emitted once as a manifest (types.rb) plus one file per type under types/,
   # so a schema migration diffs only the types it touched. Returns
@@ -245,6 +251,8 @@ class GraphWeaver::Codegen
     @input_hops = []
     @mapped_enums = {}
     @used_unions = []
+    # block-built type helpers this walk included — see #block_helpers
+    @block_helpers = []
     # requires the generated file needs (custom scalars, enum mappings,
     # type helpers all contribute)
     @requires = []
@@ -840,6 +848,7 @@ class GraphWeaver::Codegen
     node = ObjectNode.new(class_name)
     node.graphql_type = type.graphql_name
     node.mixins = type_mixins(type.graphql_name)
+    node.overrides = abstract_mixin_members(type.graphql_name)
     # class name => the result key that claimed it; the struct itself first,
     # claimed by nothing (see pick_name)
     taken = { class_name => nil }
@@ -1315,7 +1324,8 @@ class GraphWeaver::Codegen
       child = type_ref(argument.type) { variable_core(argument.type.unwrap) }
       @input_hops.pop
       required = child.non_null? && !argument.default_value?
-      node.fields << InputNode::Field.new(prop, argument.graphql_name, child, required)
+      node.fields << InputNode::Field.new(prop, argument.graphql_name, child, required,
+        argument.type.to_type_signature)
     end
     check_input_props!(core, node)
     node
@@ -1396,15 +1406,18 @@ class GraphWeaver::Codegen
         "constant — map it onto one of yours: register_enum(#{core.graphql_name.inspect}, YourEnum)"
     end
 
-    EnumNode.new(class_name, enum_values(core))
+    aliases = @registry.enum_registry[core.graphql_name]&.aliases_for(core.values.keys.sort) || {}
+    EnumNode.new(class_name, enum_values(core, aliases), aliases)
   end
 
-  # A schema enum's wire values, sorted so output is deterministic across schema
-  # sources (SDL round-trips reorder values alphabetically). Values that differ
-  # only in case name the same T::Enum constant, which raises at LOAD time
-  # ("Enum values must be assigned to constants") — catch it here instead.
-  def enum_values(core)
-    values = core.values.keys.sort
+  # A schema enum's constant-bearing wire values, sorted so output is
+  # deterministic across schema sources (SDL round-trips reorder values
+  # alphabetically). An aliased spelling is read as another of the values, so
+  # it gets no constant. Values that differ only in case name the same T::Enum
+  # constant, which raises at LOAD time ("Enum values must be assigned to
+  # constants") — catch it here instead.
+  def enum_values(core, aliases = {})
+    values = core.values.keys.sort - aliases.keys
     # `_` and `__` are legal GraphQL enum values and camelize to nothing, so
     # the emitted `= new("_")` isn't even parseable — the file fails at load
     # with a syntax error pointing into generated source
@@ -1415,12 +1428,18 @@ class GraphWeaver::Codegen
         "one of yours: register_enum(#{core.graphql_name.inspect}, YourEnum)"
     end
 
-    collision = values.group_by { |value| camelize(value.downcase) }.find { |_, group| group.size > 1 }
-    if collision
+    # A schema mid-rename declares every value twice, so every pair collides:
+    # name one, count the rest, and print the registration that fixes them all.
+    collisions = values.group_by { |value| camelize(value.downcase) }.select { |_, group| group.size > 1 }
+    if collisions.any?
+      constant, group = collisions.first
+      more = collisions.size - 1
       raise GraphWeaver::Error,
-        "enum #{core.graphql_name} values #{collision.last.join(" and ")} both become the constant " \
-        "#{collision.first} — map the enum onto one of yours: " \
-        "register_enum(#{core.graphql_name.inspect}, YourEnum)"
+        "enum #{core.graphql_name} values #{group.join(" and ")} both become the constant #{constant}" \
+        "#{" (and #{more} more colliding pair#{"s" if more > 1})" unless more.zero?} — if each pair is one " \
+        "value, say which spelling goes on the wire:\n  " \
+        "#{EnumType.alias_suggestion(core.graphql_name, collisions.values)}\n" \
+        "or map the enum onto one of yours: register_enum(#{core.graphql_name.inspect}, YourEnum)"
     end
 
     values
@@ -1432,14 +1451,40 @@ class GraphWeaver::Codegen
     return [] unless entry
 
     @requires.concat(entry[:requires])
-    entry[:mixins].map(&:name)
+    names = entry[:mixins].map(&:name)
+    # GraphWeaver::TypeHelpers is where extend_type mints a block's mixin, and
+    # a module there exists in no source file — so generation has to declare it
+    @block_helpers.concat(names.grep(BLOCK_HELPER))
+    names
+  end
+
+  # A block-built mixin's constant, by the namespace extend_type mints it under.
+  BLOCK_HELPER = /\AGraphWeaver::TypeHelpers::/
+  private_constant :BLOCK_HELPER
+
+  # Struct members a registered mixin declares abstract (docs/generated_modules.md
+  # recommends that shape so a named helper carries sigs srb tc can check).
+  # Sorbet demands the override be declared on whatever satisfies an abstract
+  # sig, and nothing generation writes can be corrected by hand — a `const` has
+  # no sig to insert `override.` into — so codegen derives it, the same way it
+  # derives an alias's type. Mixin ancestors count: an inherited abstract sig is
+  # one Sorbet demands the override for just the same.
+  def abstract_mixin_members(graphql_name)
+    entry = @registry.type_registry[graphql_name]
+    return [] unless entry
+
+    entry[:mixins].flat_map { |mixin|
+      T::AbstractUtils.declared_abstract_methods_for(mixin).map { |method| method.name.to_s }
+    }.uniq
   end
+  private :abstract_mixin_members
 
   # The MappedEnum node for a schema enum with a registered app-enum
-  # mapping; nil when unregistered, falling back to a generated T::Enum.
+  # mapping; nil when unregistered — or registered for alias: alone, which
+  # says nothing about the Ruby type — falling back to a generated T::Enum.
   def mapped_enum_node(core)
     enum_type = @registry.enum_registry[core.graphql_name]
-    return unless enum_type
+    return unless enum_type&.type
 
     @requires.concat(enum_type.requires)
     @mapped_enums[core.graphql_name] ||= MappedEnum.new(enum_type, core.values.keys.sort)

data/lib/graph_weaver/coerce.rb

@@ -2,6 +2,7 @@
 # frozen_string_literal: true
 
 require "date" # Date/DateTime, named below
+require "time" # Time.iso8601
 
 require_relative "errors"
 require_relative "internal/refusal"
@@ -38,19 +39,24 @@ module GraphWeaver
       # app translates for a user. It defaults to the GraphQL scalar the rule
       # is named for; generated code passes the schema's own name, so a
       # `register_scalar("BigInt", Integer)` field refuses as a BigInt.
+      #
+      # A real number converts to the number the scalar names, and whether it
+      # is whole is asked of the value — so a BigDecimal off a decimal column
+      # and a Rational are ordinary arguments.
       def integer(value, scalar = "Int")
         case value
         when Integer then value
-        when Float then whole(value, scalar)
+        when Numeric then whole(real(value, scalar), scalar)
         when String then INTEGER.match?(value.strip) ? Integer(value.strip, 10) : unparseable(value, scalar)
         else refuse(value, scalar)
         end
       end
 
+      # Float's own precision is what asking for a Float means, so a BigDecimal
+      # past it loses digits here rather than being refused.
       def float(value, scalar = "Float")
         case value
-        when Float then finite(value, scalar)
-        when Integer then finite(value.to_f, scalar)
+        when Numeric then finite(real(value, scalar).to_f, scalar)
         when String then NUMBER.match?(value.strip) ? finite(Float(value.strip), scalar) : unparseable(value, scalar)
         else refuse(value, scalar)
         end
@@ -70,12 +76,16 @@ module GraphWeaver
         end
       end
 
+      # A timestamp string is ISO 8601, read by Time.iso8601 — the coercer
+      # graphql-ruby's own ISO8601DateTime reads input with, and the only
+      # shape its coerce_result writes. Time.parse also reads "Jan 15 2024
+      # 10:20", which no server sends and no generated struct should take.
       def time(value, scalar = "Time")
         case value
         when Time then value
         when DateTime then value.to_time # the same instant in another class
         when Date then cross(value, scalar, TIME_HINT)
-        when String then parsing(scalar, value) { Time.parse(value) }
+        when String then parsing(scalar, value) { Time.iso8601(value) }
         else time_like?(value) ? value.to_time : refuse(value, scalar)
         end
       end
@@ -194,8 +204,17 @@ module GraphWeaver
         raise mismatch(ArgumentError, "#{expected(scalar)}, got #{shown(value)} — not a finite number", scalar)
       end
 
+      # Complex is the one Numeric that is not a number a scalar can name, and
+      # #real? is the predicate for it — no class list to keep up to date.
+      def real(value, scalar)
+        return value if value.real?
+
+        refuse(value, scalar)
+      end
+
       def whole(value, scalar = "Int")
-        # Integer(2.5) is 2 — a silent loss where refusing costs nothing
+        # Integer(2.5) is 2 — a silent loss where refusing costs nothing. `% 1`
+        # is exact for a BigDecimal and a Rational; asking Float would not be.
         return value.to_i if value.finite? && (value % 1).zero?
 
         raise mismatch(ArgumentError, "#{expected(scalar)}, got #{shown(value)} — not a whole number", scalar)

data/lib/graph_weaver/graph.rb

@@ -54,12 +54,15 @@ module GraphWeaver
     # block runs once, at the declaration (GraphBuilder.build reads the
     # registry there), and every read after replays the module it made.
     def replay(registry, registration)
-      call, args, kwargs, block = registration
+      call, args, kwargs, block, aliases = registration
       entry = registry.public_send(call, *args, **kwargs, &block)
+      # the block's alias_field lines ran with it, so replay them too
+      entry[:aliases].merge!(aliases) if aliases
       return unless block && call == :extend_type
 
       registration[1] = args + [entry[:mixins].last]
       registration[3] = nil
+      registration[4] = entry[:aliases].dup
     end
     private :replay
 

data/lib/graph_weaver/hints.rb

@@ -68,7 +68,10 @@ module GraphWeaver
     # you generated) rather than a bad value, and T::Enum's own KeyError says
     # neither that nor which values exist. Raised bare so the enclosing
     # Hints.field brands it with the field.
-    def self.enum(type, value)
+    # aliases (register_enum alias:) is wire spelling => the value it reads as.
+    def self.enum(type, value, aliases = nil)
+      value = aliases.fetch(value, value) if aliases
+
       type.try_deserialize(value) || drifted!(type, value, type.values.map(&:serialize))
     end
 

data/lib/graph_weaver/input_struct.rb

@@ -21,18 +21,21 @@ module GraphWeaver
 
     # serializer/coercer are code-as-data from the generated file; nil
     # means identity (the wire value passes through untouched). coordinate
-    # is the schema's name for the slot ("PetFilter.species"), so a refusal
-    # can say where it happened without reflecting at runtime.
-    Field = Data.define(:prop, :wire, :required, :serializer, :coercer, :coordinate)
+    # is the schema's name for the slot ("PetFilter.species") and type its
+    # spelling of what goes there ("[Float!]!"), so a refusal can say where
+    # it happened, and in whose vocabulary, without reflecting at runtime.
+    Field = Data.define(:prop, :wire, :required, :serializer, :coercer, :coordinate, :type)
 
     # An enum reaching the library as input — an execute kwarg or an input
     # field — as the member or its wire value. Generated code calls these
     # rather than T::Enum.deserialize / the wire table directly: both raise a
     # bare KeyError naming an anonymous module and none of the values they
     # would have taken.
-    def self.enum(type, value)
+    def self.enum(type, value, aliases = nil)
       return value if value.is_a?(type)
 
+      value = aliases.fetch(value, value) if aliases
+
       type.try_deserialize(value) || invalid_enum!(type, value, type.values.map(&:serialize))
     end
 
@@ -260,11 +263,14 @@ module GraphWeaver
           # out blaming the list that held the struct, in sorbet's words.
           next if T::Utils.coerce(info[:type_object]).recursively_valid?(value)
 
-          type = T::Utils.coerce(info[:type]).to_s
+          # the SCHEMA's spelling, from the FIELDS row — #details[:type] is
+          # what an app translates for a user, and "T::Array[Float]" is the
+          # library's vocabulary leaking into theirs
+          field = T.unsafe(self).const_get(:FIELDS).find { |f| f.prop == prop }
+          type = field&.type || T::Utils.coerce(info[:type]).to_s
           return GraphWeaver::InputError.new(
             "#{prop}: expected #{type}, got #{GraphWeaver::Internal::Redact.shown(value, prop)}",
-            kind: :type_mismatch, path: [prop.to_s],
-            coordinate: T.unsafe(self).const_get(:FIELDS).find { |f| f.prop == prop }&.coordinate,
+            kind: :type_mismatch, path: [prop.to_s], coordinate: field&.coordinate,
             value: GraphWeaver::Internal::Redact.value(prop, value),
             details: { type: }, struct: self,
           )

data/lib/graph_weaver/internal/values.rb

@@ -51,8 +51,11 @@ class GraphWeaver::Internal::Values
   UNREGISTERED = "T.untyped"
 
   # What JSON can hold. Anything else a pin offers is a Ruby object the
-  # registration has to serialize before it can stand in for a response.
-  WIRE = [NilClass, TrueClass, FalseClass, Numeric, String, Symbol, Array, Hash].freeze
+  # registration has to serialize before it can stand in for a response —
+  # Integer and Float, not Numeric, because a BigDecimal is a Numeric that
+  # JSON has no spelling for, and taking one as written sent 12.5 where the
+  # registration says the server writes "12.5".
+  WIRE = [NilClass, TrueClass, FalseClass, Integer, Float, String, Symbol, Array, Hash].freeze
 
   # The fallback, for a scalar nobody registered: its prop is T.untyped, so
   # anything holds and a plausible shape beats a placeholder.

data/lib/graph_weaver/internal.rb

@@ -299,6 +299,73 @@ module GraphWeaver
       end
     end
 
+    # One query, checked against one schema. Both doors onto it —
+    # GraphWeaver.check_queries (every file on disk) and Client#check_query
+    # (a string) — report the same hashes and brand subgraphs the same way,
+    # because the implementation lives here rather than once each.
+    module QueryCheck
+      class << self
+        # A query's schema-validation errors as JSON-ready hashes, with the
+        # source position graphql-ruby reports. Unparseable counts as an error
+        # too — it doesn't validate either, and inline_fragments (which parses
+        # first) has already branded it with its position.
+        def errors(schema, source, shared, table = nil)
+          # path omitted: check_queries keys its report by file, so branding the
+          # message with it too would just print the path twice
+          schema.validate(Codegen.inline_fragments(source, shared)).map do |error|
+            detail = error.to_h
+            location = detail["locations"]&.first || {}
+            subgraphs = table ? attribute(table, detail["extensions"]) : []
+            entry = {
+              "message" => subgraphs.empty? ? error.message : "#{error.message} (#{subgraphs.join(", ")})",
+              "line" => location["line"],
+              "column" => location["column"],
+            }
+            subgraphs.empty? ? entry : entry.merge("subgraphs" => subgraphs)
+          end
+        rescue GraphWeaver::QueryValidationError => e
+          # an unparseable query: codegen folds the position (and the file) into
+          # the message, and this report keeps them separate — same splitter the
+          # rendered error uses, so the two can't drift apart
+          e.errors.map do |detail|
+            _path, _position, message = GraphWeaver::QueryValidationError.split(detail)
+            detail.transform_keys(&:to_s).merge("message" => message)
+          end
+        end
+
+        # The routing table behind a dump path, when the dump is a composed
+        # supergraph: it says who resolves what, so a validation error can name
+        # the subgraph whose code to look at. nil for anything else — a plain
+        # schema, a url client, a live class are all unaffected.
+        def routing_table_for(path)
+          path = path.to_path if path.respond_to?(:to_path)
+          return unless path&.end_with?(".graphql", ".gql")
+
+          sdl = File.read(path)
+          SchemaLoader.routing_table(sdl) if SchemaLoader.federation_sdl?(sdl)
+        end
+
+        private
+
+        # Which subgraphs a validation error is about, on a federated schema:
+        # "Field 'weight' doesn't exist on type 'Product'" is much less useful
+        # than the same line plus "(products)" — whose code to look at, whose
+        # team to talk to. graphql-ruby reports the coordinate structurally, so
+        # this is a lookup rather than message parsing. Both halves of the
+        # coordinate are required: an argument error reports typeName "Field"
+        # (the AST node kind, not a type), and looking that up would attribute
+        # confidently and wrongly.
+        def attribute(table, extensions)
+          return [] unless extensions
+
+          type_name, field_name = extensions.values_at("typeName", "fieldName")
+          return [] unless type_name && field_name
+
+          table.responsible(type_name, field_name)
+        end
+      end
+    end
+
     # What makes two GraphQL requests the same request — and how one reads
     # when an error has to quote it. A cassette matches on this, so the
     # rules belong somewhere both the cassette and the error that reports a