graph_weaver 0.4.4 → 0.4.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fac36591b869f046295946094078847ed33a1aa15aa8a2402e6a46f6e17ebaa0
-  data.tar.gz: c366d845da86029839f57214ba6216b78f2a870b67873851c2514d3d00aaa78d
+  metadata.gz: f01ed46a3a7d500364530c522e28f5b1f70f9db803988f940e487630bca0f10c
+  data.tar.gz: ee2e237e936ca60054b6465f62e14714c359235abfab376fb3b14e232ef851f9
 SHA512:
-  metadata.gz: 37c814f83659a3189407b4c8e4531db4782fc4f38cd0e62df4f8e473a75c713adc3d0bb43de62a51854c1d6f0aeea1195e89848e83bd61c74018a840bfe56924
-  data.tar.gz: 787508b524cb027fb31281379f64bc566b1bb23709a79883928005ced38cf478c6c90b62a09d2de66317a6d7415eea77014667a5f543472a6f42d8ad043634de
+  metadata.gz: bb3adc8c4d4f3164a34a650fe989c785d45559a78c52b10bc93abe21e4ab26c9fb3892b76694c563cbc62b2e342b2bd49b87cf2f7119afe9439facc8dc837e94
+  data.tar.gz: ae4521a62bb818a9d8da0053533c4749a56e021f88c343acd25123b04016176a942da9e824bcb41df32083ae1c28db6a81b32079490c15014940bb016d821be6

data/CHANGELOG.md

@@ -1,3 +1,46 @@
+###  v0.4.6  (2026-07-30)
+Bug fixes from a full-library review (all with regression coverage):
+- alias: a nested-object/enum leaf (`meta.sub`) now qualifies its constant
+  (`Meta::Sub`) instead of emitting a bare `Sub` that raised NameError; alias
+  names/segments are validated as identifiers (were interpolated verbatim,
+  allowing injection); `optional:` no longer swallows a reserved-name/collision
+  mistake; a real field named `first`/`last` resolves as a field.
+- Shared unions: a hoisted member selecting a mapped enum now emits its
+  `<NAME>_FROM_WIRE` table into `unions.rb` (was a NameError at `from_h`); a
+  fragment whose name collides with `Result`/`QUERY` is refused.
+- A named interface fragment holding inline `... on X` conditions now dispatches
+  instead of silently dropping those fields; fragment cycles raise a clear error
+  in the FakeClient/Anonymizer walkers instead of `SystemStackError`.
+- Malformed responses/inputs stay under `GraphWeaver::Error`: a non-2xx
+  `errors: null` body keeps its status; a 2xx non-object body is a `ServerError`;
+  `data!` on null-data/no-errors raises `QueryError`; `coerce(non-Hash)` raises
+  `InputError`.
+- Testing harness: FakeClient/Anonymizer merge duplicate result keys (were
+  fabricating shapes the generated struct couldn't cast); `fail_at` fires every
+  execute; symbol-keyed cassette variables no longer crash on reload; the
+  Anonymizer keeps concrete-fragment fields when data lacks `__typename`.
+- Federation: a user type named `link` is no longer dropped; an all-`@inaccessible`
+  schema raises a pointed error. Client accepts `retries: nil` on a schema
+  source; `register_scalar` rejects an anonymous class.
+- FakeClient: an Integer `list_size` now means exactly that length (a Range
+  randomizes within it). Codegen rejects two variables that underscore to the
+  same kwarg (`$userId` + `$user_id`). The Faraday transport raises rather than
+  silently dropping `headers:`/block when handed a prebuilt connection.
+
+###  v0.4.5  (2026-07-30)
+- `alias:` paths gain list-element selectors: a `first`/`last` segment picks one
+  element out of a list hop, always nilable — `alias: { entity: "_entities.first" }`
+  yields `def entity = _entities&.first`, and navigation continues into the
+  element (`_entities.first.name`). Typed from the selection: a single inline
+  fragment lands on the concrete member (`T.nilable(Widget)`), a multi-fragment
+  selection on the union. Selectors are checked against the node shape — `.first`
+  on a non-list raises. Cleanly retires the `result._entities&.first&.field`
+  boilerplate of single-entity federation `_entities` queries.
+- `extend_type(..., optional: true)` makes its aliases lenient: a query whose
+  selection doesn't fit the path omits the accessor instead of failing
+  generation. For an alias on a universal type (a `Query` accessor a strict alias
+  would force every query to satisfy), or one that only fits some selections.
+
 ###  v0.4.4  (2026-07-30)
 - Supergraph loading now derives the **API schema**: `@inaccessible` elements
   (present in the federated graph but hidden from what the router serves) are

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    graph_weaver (0.4.4)
+    graph_weaver (0.4.6)
       graphql (>= 2.6.7)
       sorbet-runtime
 
@@ -176,7 +176,7 @@ CHECKSUMS
   google-protobuf (4.35.1-arm64-darwin) sha256=d9c957df04fa89c749fa9a72a7b383eb4296efc9b2303dc6fd6fbe39c698ad6b
   google-protobuf (4.35.1-x86_64-darwin) sha256=66b62b4df00931018a692806df66393efa960d6d2b7da69735187249f950d3ee
   google-protobuf (4.35.1-x86_64-linux-gnu) sha256=c786439087512a3fbd199e9897d265b855f951d4027e218ea55e858d45969edd
-  graph_weaver (0.4.4)
+  graph_weaver (0.4.6)
   graphql (2.6.7) sha256=759755ce5819c965b6459c5039605cf2e4d876bb8ba5e03451676870ea787c45
   i18n (1.15.2) sha256=00f9eb62412fe593b2a65a97daa75300d37abb8f7202ec748e94b6d46a9dd1b5
   io-console (0.8.2) sha256=d6e3ae7a7cc7574f4b8893b4fca2162e57a825b223a177b7afa236c5ef9814cc

data/docs/scalars.md

@@ -232,8 +232,26 @@ alias: { label: "name", tag: "meta.tag" }
 The path is the Ruby accessor chain (`meta.tag`), typed from the selection: any
 nullable hop makes the accessor nilable and inserts `&.`; the leaf can be a
 scalar, enum, or nested struct. It's validated against each query at generation —
-an unselected or misspelled segment (`did you mean 'tag'?`), a path through a
-list, or a name that collides with a real field all fail with a pointed error.
-Registrations stack and are client-scopable, like the mixin forms. For anything
-beyond a passthrough projection — real logic, still typed — reopen the generated
-struct in your own file and add sig'd methods; Sorbet merges the bodies.
+an unselected or misspelled segment (`did you mean 'tag'?`), a selector on a
+non-list, or a name that collides with a real field all fail with a pointed
+error. Registrations stack and are client-scopable, like the mixin forms.
+
+A segment can also be `first` or `last` to pick one element out of a list hop —
+always nilable, since the list may be empty. This is what turns an
+`_entities`-style "array that logically holds one thing" into a clean accessor:
+
+```ruby
+GraphWeaver.extend_type("Query", alias: { entity: "_entities.first" }, optional: true)
+
+#   sig { returns(T.nilable(Widget)) }        # concrete, when the selection is one `... on Widget`
+#   def entity = _entities&.first             # (a multi-fragment selection types it as the union)
+```
+
+`optional: true` makes the aliases *lenient*: a query whose selection doesn't fit
+the path just omits the accessor instead of failing generation. Reach for it when
+the alias lives on a universal type like `Query` — where a strict alias would
+force *every* query to select the path — or when it only fits some selections.
+
+For anything beyond a passthrough projection — real logic, still typed — reopen
+the generated struct in your own file and add sig'd methods; Sorbet merges the
+bodies.

data/lib/graph_weaver/client.rb

@@ -35,7 +35,7 @@ class GraphWeaver::Client
 
       @transport = wrap_retries(build_transport(source, auth:, headers:, &middleware), retries)
     else
-      if auth || middleware || retries != false
+      if auth || middleware || retries
         raise ArgumentError, "auth:/retries:/middleware apply to a url — got a schema source"
       end
       if cache || ttl

data/lib/graph_weaver/codegen/emit.rb

@@ -194,6 +194,13 @@ class GraphWeaver::Codegen
         end
         out << "module #{@module_name}"
         out << "  extend T::Sig" << "" if GraphWeaver.extend_t_sig?
+        # a member selecting a mapped enum (register_enum) reads its module-level
+        # <NAME>_FROM_WIRE table — emit those here so from_h resolves them, the
+        # same way emit_variable_types does for the query module
+        @mapped_enums.each_value do |mapped|
+          emit_mapped_enum(mapped, out, 1)
+          out << ""
+        end
         unions.each do |union|
           emit_union(union, out, 1)
           out << ""

data/lib/graph_weaver/codegen/enum_type.rb

@@ -110,30 +110,56 @@ class GraphWeaver::Codegen
     #      GraphWeaver.extend_type("Widget", alias: { tag: "meta.tag" })
     #      GraphWeaver.extend_type("Widget", alias: "meta.tag")        # accessor named `tag`
     #      GraphWeaver.extend_type("Widget", alias: ["meta.tag", "meta.color"])
+    #
+    # A path segment is a field, or `first`/`last` to pick one element out of a
+    # list hop (always nilable): `alias: { entity: "_entities.first" }`.
+    #
+    # optional: true makes the aliases lenient — a query whose selection doesn't
+    # 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.
     def extend_type(graphql_name, *mixins, requires: nil, **kw, &block)
       aliases = take_aliases(kw)
       entry = type_registry[graphql_name.to_s] ||= { mixins: [], requires: [], aliases: {} }
       add_type_helpers(entry, graphql_name, mixins, requires, block, aliases)
     end
 
-    # Pull alias: out of the keyword rest and normalize it; any other keyword
-    # is a typo worth flagging rather than silently dropping.
+    # 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))
+      aliases = normalize_aliases(kw.delete(:alias), optional: !!kw.delete(:optional))
       raise ArgumentError, "unknown keyword: #{kw.keys.first}" unless kw.empty?
       aliases
     end
 
-    # { accessor => [path, segments] } from a path string (accessor named
-    # after the last segment), an array of such, or an { accessor => path } hash.
-    def normalize_aliases(input)
-      case input
-      when nil then {}
-      when String then { input.split(".").last => input.split(".") }
-      when Array then input.to_h { |path| [path.split(".").last, path.split(".")] }
-      when Hash then input.to_h { |name, path| [name.to_s, path.to_s.split(".")] }
+    # 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
+    ALIAS_NAME = /\A[a-zA-Z_]\w*[?!]?\z/
+    ALIAS_SEGMENT = /\A[a-zA-Z_]\w*\z/
+
+    # { accessor => { segments:, optional: } } from a path string (accessor
+    # named after the last segment), an array of such, or an { accessor => path }
+    # hash. `optional:` marks every alias in this registration as lenient.
+    def normalize_aliases(input, optional:)
+      pairs = case input
+      when nil then []
+      when String then [[input.split(".").last, input.split(".")]]
+      when Array then input.map { |path| [path.split(".").last, path.split(".")] }
+      when Hash then input.map { |name, path| [name.to_s, path.to_s.split(".")] }
       else raise ArgumentError, "alias: expects a String, Array, or Hash, got #{input.class}"
       end
+      pairs.to_h do |name, segments|
+        unless name.to_s.match?(ALIAS_NAME)
+          raise ArgumentError, "alias name #{name.inspect} is not a valid method name"
+        end
+        raise ArgumentError, "alias #{name.inspect} has an empty path" if segments.empty?
+
+        bad = segments.reject { |seg| seg.match?(ALIAS_SEGMENT) }
+        raise ArgumentError, "alias #{name.inspect} has an invalid path segment: #{bad.first.inspect}" if bad.any?
+
+        [name, { segments:, optional: }]
+      end
     end
 
     def type_registry

data/lib/graph_weaver/codegen/scalar_type.rb

@@ -123,7 +123,10 @@ class GraphWeaver::Codegen
 
     def type_name(type)
       case type
-      when Module then type.name
+      when Module
+        # an anonymous class has no name to emit — it would land as a literal
+        # `nil` in generated source
+        type.name || raise(ArgumentError, "type: must be a named class/module, got an anonymous one")
       when String then type
       else raise ArgumentError, "type: must be a class/module or String, got #{type.inspect}"
       end

data/lib/graph_weaver/codegen.rb

@@ -175,14 +175,26 @@ class GraphWeaver::Codegen
     @fragments = fragments
 
     unions = names.uniq.sort.map do |name|
+      class_name = camelize(name)
+      # the query module aliases <class_name> = <unions module>::<class_name>;
+      # a name that camelizes to a generated module-level constant (the Result
+      # struct, the QUERY heredoc) would collide with that alias at load
+      if HOISTED_UNION_RESERVED.include?(class_name)
+        raise GraphWeaver::Error,
+          "shared fragment #{name.inspect} hoists to #{class_name}, which collides with a generated constant — rename the fragment"
+      end
       fragment = fragments.fetch(name)
       type = @schema.get_type(fragment.type.name)
-      UnionNode.new(camelize(name), union_members(type, fragment.selections))
+      UnionNode.new(class_name, union_members(type, fragment.selections))
     end
 
     emit_unions_file(unions)
   end
 
+  # module-level constants every generated query module defines — a hoisted
+  # union aliased to one of these would clash at load
+  HOISTED_UNION_RESERVED = %w[Result QUERY].to_set.freeze
+
   VarDef = Struct.new(:kwarg, :wire, :node, :required)
 
   # Names that cannot appear bare in generated Ruby: keywords aren't
@@ -246,6 +258,15 @@ class GraphWeaver::Codegen
       VarDef.new(kwarg, var.name, node, required)
     end
 
+    # two variables that underscore to the same kwarg ($userId + $user_id) would
+    # silently drop one on the wire — flag it like a prop collision
+    collision = variables.group_by(&:kwarg).find { |_, vars| vars.size > 1 }
+    if collision
+      wire = collision.last.map { |var| "$#{var.wire}" }.join(", ")
+      raise GraphWeaver::Error,
+        "variables #{wire} both map to the kwarg '#{collision.first}:' — rename one"
+    end
+
     root = object_node(root_type, operation.selections, "Result")
 
     emit_module(root, variables)
@@ -270,8 +291,7 @@ class GraphWeaver::Codegen
 
     return if schema.get_type(name)
 
-    suggestion = defined?(DidYouMean::SpellChecker) &&
-      DidYouMean::SpellChecker.new(dictionary: schema.types.keys).correct(name).first
+    suggestion = GraphWeaver.did_you_mean(schema.types.keys, name)
     hint = suggestion ? " — did you mean '#{suggestion}'?" : ""
     # the type registry is reached via extend_type; scalars/enums via register_*
     method = kind == "type" ? "extend_type" : "register_#{kind}"
@@ -367,14 +387,6 @@ class GraphWeaver::Codegen
   end
 
 
-  # Selection#each_field, collected by result key (codegen groups
-  # repeated selections of one field so it can merge them)
-  def gather(type, selections)
-    out = {}
-    each_field(type, selections) { |key, node| (out[key] ||= []) << node }
-    out
-  end
-
   def object_node(type, selections, class_name)
     node = ObjectNode.new(class_name)
     node.graphql_type = type.graphql_name
@@ -474,8 +486,25 @@ class GraphWeaver::Codegen
   # struct body. Validated here, per query, so an unselected or untraversable
   # path fails at generation with a pointed message.
   def resolve_aliases(node)
-    type_aliases(node.graphql_type).map do |name, segments|
-      resolve_alias(node, name, segments)
+    type_aliases(node.graphql_type).filter_map do |name, spec|
+      # a bad accessor name (reserved, or colliding with a real field) is a
+      # registration mistake — it fails for every query, so it always raises,
+      # even for optional aliases (which otherwise mask it as "doesn't fit").
+      check_alias_name!(node, name)
+      begin
+        resolve_alias(node, name, spec[:segments])
+      rescue GraphWeaver::Error
+        # a path that doesn't fit THIS query's selection: strict raises,
+        # optional simply omits the accessor
+        raise unless spec[:optional]
+      end
+    end
+  end
+
+  def check_alias_name!(node, name)
+    if node.fields.any? { |f| f.prop == name } || ALIAS_RESERVED.include?(name)
+      raise GraphWeaver::Error,
+        "alias #{name.inspect} on #{node.graphql_type} collides with an existing field or method"
     end
   end
 
@@ -487,61 +516,126 @@ class GraphWeaver::Codegen
   end
 
   ALIAS_RESERVED = (%w[from_h serialize to_h].to_set + RUBY_KEYWORDS).freeze
-
-  # Walk a dotted path (Ruby prop names) through this struct's selected fields,
-  # building the delegator expression (`meta&.tag`) and its return type. Any hop
-  # is nilable -> the accessor is nilable; a list hop or an unselected segment
-  # raises. The leaf may be any node (scalar, enum, nested struct).
+  # list selectors — pick one element out of a list-typed hop, always nilable
+  # (the list may be empty). Everything else is a field prop.
+  LIST_SELECTORS = %w[first last].freeze
+
+  # Walk a dotted path through this struct's selected shape, building the
+  # delegator expression (`meta&.tag`, `_entities.first&.name`) and its return
+  # type. A segment is a field prop, or `first`/`last` to pick a list element.
+  # Everything is checked against the node tree: a field on a non-object, a
+  # selector on a non-list, or an unselected segment raises. Any nilable hop
+  # (a nullable field, or a list element) makes the accessor nilable.
   def resolve_alias(node, name, segments)
-    if node.fields.any? { |f| f.prop == name } || ALIAS_RESERVED.include?(name)
-      raise GraphWeaver::Error,
-        "alias #{name.inspect} on #{node.graphql_type} collides with an existing field or method"
+    cur = T.let(node, T.untyped)           # the node the path has reached
+    cur_nilable = T.let(false, T::Boolean) # is the expression so far nilable
+    nilable = T.let(false, T::Boolean)     # is the accessor overall nilable
+    containers = T.let([], T::Array[String]) # nested-struct class names on the way to the leaf
+    expr = +""
+
+    segments.each do |seg|
+      connector = expr.empty? ? "" : (cur_nilable ? "&." : ".")
+
+      # `first`/`last` select an element only when the current hop is actually a
+      # list; otherwise they're an ordinary field (a schema field named `first`)
+      if LIST_SELECTORS.include?(seg) && list_of(cur)
+        expr << connector << seg
+        cur = list_of(cur).of
+        cur_nilable = true # first/last is nil on an empty list
+        nilable = true
+      else
+        obj = object_of(cur)
+        unless obj
+          hint = if list_of(cur)
+            " — use .first or .last to pick an element"
+          elsif LIST_SELECTORS.include?(seg)
+            " — .#{seg} needs a list"
+          else
+            ""
+          end
+          raise GraphWeaver::Error,
+            "alias #{name.inspect} on #{node.graphql_type}: '#{seg}' can't be read here (not an object)#{hint}"
+        end
+        # the object a field is read from is the lexical container of its result
+        # (nested structs emit inside their parent); the aliased struct itself is
+        # the delegator's own scope, so it contributes no prefix
+        containers << obj.class_name unless obj.equal?(node)
+        field = obj.fields.find { |f| f.prop == seg }
+        unless field
+          props = obj.fields.map(&:prop)
+          suggestion = GraphWeaver.did_you_mean(props, seg)
+          hint = suggestion ? " — did you mean '#{suggestion}'?" : " (have: #{props.join(", ")})"
+          raise GraphWeaver::Error,
+            "alias #{name.inspect} on #{node.graphql_type}: '#{seg}' is not a selected field#{hint}"
+        end
+        expr << connector << seg
+        cur = field.node
+        cur_nilable = !field.node.non_null?
+        nilable ||= cur_nilable
+      end
     end
 
-    current = T.let(node, T.untyped)
-    parts = []
-    nilable = T.let(false, T::Boolean)
-    segments.each_with_index do |seg, i|
-      field = current.fields.find { |f| f.prop == seg }
-      unless field
-        props = current.fields.map(&:prop)
-        suggestion = defined?(DidYouMean::SpellChecker) &&
-          DidYouMean::SpellChecker.new(dictionary: props).correct(seg).first
-        hint = suggestion ? " — did you mean '#{suggestion}'?" : " (have: #{props.join(", ")})"
-        raise GraphWeaver::Error,
-          "alias #{name.inspect} on #{node.graphql_type}: '#{seg}' is not a selected field#{hint}"
-      end
-      nilable ||= !field.node.non_null?
+    leaf = qualified_alias_type(cur, containers)
+    type = nilable && leaf != "T.untyped" ? "T.nilable(#{leaf})" : leaf
+    ObjectNode::Alias.new(name, expr, type)
+  end
 
-      if i == segments.size - 1
-        leaf = field.node.bare_type
-        type = nilable && leaf != "T.untyped" ? "T.nilable(#{leaf})" : leaf
-        return ObjectNode::Alias.new(name, (parts << seg).join, type)
-      end
+  # The leaf's Sorbet type as referenced from the aliased struct. Generated
+  # nested constants (structs, enums, unions) must carry the container path,
+  # since the delegator's `sig` is emitted in an outer struct where a bare
+  # `Sub` wouldn't resolve; scalars, mapped enums, and hoisted union refs are
+  # already top-level. `containers` is the class-name chain to the leaf.
+  def qualified_alias_type(node, containers)
+    node = node.of if node.is_a?(NonNull)
+    prefix = containers.empty? ? "" : "#{containers.join("::")}::"
 
-      inner = T.let(field.node, T.untyped)
-      inner = inner.of while inner.is_a?(NonNull)
-      raise GraphWeaver::Error, "alias #{name.inspect}: cannot traverse list-typed '#{seg}'" if inner.is_a?(List)
-      unless inner.is_a?(ObjectNode)
-        raise GraphWeaver::Error, "alias #{name.inspect}: '#{seg}' is not an object to traverse into"
+    case node
+    when List
+      element = node.of.is_a?(NonNull) ? qualified_alias_type(node.of, containers) : begin
+        inner = qualified_alias_type(node.of, containers)
+        inner == "T.untyped" ? inner : "T.nilable(#{inner})"
       end
-
-      parts << seg << (field.node.non_null? ? "." : "&.")
-      current = inner
+      "T::Array[#{element}]"
+    when ObjectNode, EnumNode, NarrowedNode then "#{prefix}#{node.class_name}"
+    when UnionNode then "#{prefix}#{node.bare_type}"
+    else node.bare_type # Scalar, MappedEnum, UnionRefNode — already top-level
     end
   end
 
-  # 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|
+  # the List a node wraps (through NON_NULL), or nil
+  def list_of(node)
+    node = T.let(node, T.untyped)
+    node = node.of while node.is_a?(NonNull)
+    node if node.is_a?(List)
+  end
+
+  # the ObjectNode a node resolves to for field access (through NON_NULL and a
+  # narrowed abstract member), or nil — unions/scalars/lists can't be read into
+  def object_of(node)
+    node = T.let(node, T.untyped)
+    node = node.of while node.is_a?(NonNull)
+    node = node.nested if node.is_a?(NarrowedNode)
+    node if node.is_a?(ObjectNode)
+  end
+
+  # The concrete type conditions a selection mentions, minus conditions naming
+  # the abstract type itself — recursing into named-fragment and inline bodies,
+  # so a `... on X` nested inside a spread (`{ ...NodeFields }` where NodeFields
+  # holds `... on X`) still drives dispatch instead of being silently dropped.
+  def concrete_conditions(core, selections, visiting = Set.new)
+    selections.flat_map do |selection|
       case selection
       when GraphQL::Language::Nodes::InlineFragment
-        selection.type&.name
+        [selection.type&.name, *concrete_conditions(core, selection.selections, visiting)]
       when GraphQL::Language::Nodes::FragmentSpread
-        @fragments.fetch(selection.name).type.name
+        next [] if visiting.include?(selection.name)
+
+        fragment = @fragments.fetch(selection.name)
+        [fragment.type.name, *concrete_conditions(core, fragment.selections, visiting | [selection.name])]
+      else
+        []
       end
-    end.uniq - [core.graphql_name]
+    end.compact.uniq - [core.graphql_name]
   end
 
   # result keys selected as plain fields (outside any type condition)

data/lib/graph_weaver/hints.rb

@@ -28,8 +28,8 @@ module GraphWeaver
         prop = GraphWeaver::Inflect.underscore(key)
         suggestion = if known.include?(prop)
           prop # a wire-cased key — the exact snake_case prop exists
-        elsif defined?(DidYouMean::SpellChecker)
-          DidYouMean::SpellChecker.new(dictionary: known).correct(prop).first
+        else
+          GraphWeaver.did_you_mean(known, prop)
         end
         suggestion ? "#{key} (did you mean '#{suggestion}'?)" : key
       end
@@ -56,12 +56,10 @@ module GraphWeaver
         return "GraphQL fields generate snake_case props; use '#{prop}'"
       end
 
-      return unless defined?(DidYouMean::SpellChecker)
-
       # a guess, not a mapping — spellcheck the (underscored) miss
       # against the props that exist, so typos in either casing land
       props = T.unsafe(self.class).props.keys.map(&:to_s)
-      suggestion = DidYouMean::SpellChecker.new(dictionary: props).correct(prop).first
+      suggestion = GraphWeaver.did_you_mean(props, prop)
       "did you mean '#{suggestion}'?" if suggestion
     end
   end

data/lib/graph_weaver/input_struct.rb

@@ -46,6 +46,13 @@ module GraphWeaver
       def coerce(value)
         return value if value.is_a?(self)
 
+        # a caller passing a non-Hash (a bare string, or a Hash where a nested
+        # list was expected) is bad input — surface a branded 422, not a raw
+        # NoMethodError from validate_keys!'s `.keys`
+        unless value.is_a?(Hash)
+          raise GraphWeaver::InputError.new("expected a Hash or #{self}, got #{value.class}", struct: self)
+        end
+
         # a typo'd key must not silently drop off the wire
         GraphWeaver::Hints.validate_keys!(self, value)
 

data/lib/graph_weaver/response.rb

@@ -49,7 +49,14 @@ module GraphWeaver
     sig { returns(Data) }
     def data!
       raise GraphWeaver::QueryError.new(errors, data: data, extensions: extensions) unless errors.empty?
-      T.must(data)
+
+      # a well-formed GraphQL response always pairs null data with errors; a
+      # server (or an errors-stripping proxy) that returns neither is broken —
+      # brand it rather than leaking a bare `T.must` TypeError
+      data || raise(GraphWeaver::QueryError.new(
+        [GraphWeaver::GraphQLError.new(message: "response carried neither data nor errors")],
+        extensions: extensions,
+      ))
     end
   end
 end

data/lib/graph_weaver/schema_loader.rb

@@ -58,11 +58,18 @@ module GraphWeaver::SchemaLoader
   FEDERATION_PREFIXES = %w[join__ link__ core__].freeze
   FEDERATION_DIRECTIVES = %w[link core inaccessible].to_set.freeze
 
-  # Whether a type/directive name belongs to the federation composition layer.
-  def self.federation_name?(name)
+  # Synthetic composition TYPES are always prefixed (join__Graph, link__Import).
+  # The bare names (link/core/inaccessible) are DIRECTIVES only — a user type
+  # literally named `link` (Hasura-style lowercase) must not be dropped.
+  def self.federation_type_name?(name)
+    !!name && name.start_with?(*FEDERATION_PREFIXES)
+  end
+  private_class_method :federation_type_name?
+
+  def self.federation_directive_name?(name)
     !!name && (name.start_with?(*FEDERATION_PREFIXES) || FEDERATION_DIRECTIVES.include?(name))
   end
-  private_class_method :federation_name?
+  private_class_method :federation_directive_name?
 
   # Drop the composition machinery from supergraph SDL: the synthetic
   # join__*/link__* type and directive definitions, and every @join__*/@link
@@ -74,11 +81,31 @@ module GraphWeaver::SchemaLoader
   def self.strip_federation(sdl)
     doc = GraphQL.parse(sdl)
     defs = remove_inaccessible(doc.definitions)
-      .reject { |defn| defn.respond_to?(:name) && federation_name?(defn.name) }
+      .reject { |defn| federation_definition?(defn) }
       .map { |defn| strip_federation_directives(defn) }
+
+    if defs.none? { |d| d.is_a?(GraphQL::Language::Nodes::ObjectTypeDefinition) }
+      raise GraphWeaver::Error,
+        "supergraph has no object types left after stripping the federation machinery — " \
+        "is the whole schema behind @inaccessible?"
+    end
+
     GraphQL::Language::Nodes::Document.new(definitions: defs).to_query_string
   end
 
+  # a synthetic composition definition to drop: a federation directive
+  # definition (by name), or a synthetic join__*/link__* type (by prefix)
+  def self.federation_definition?(defn)
+    return false unless defn.respond_to?(:name)
+
+    if defn.is_a?(GraphQL::Language::Nodes::DirectiveDefinition)
+      federation_directive_name?(defn.name)
+    else
+      federation_type_name?(defn.name)
+    end
+  end
+  private_class_method :federation_definition?
+
   # Derive the API schema by dropping every element marked @inaccessible —
   # present in the federated graph but hidden from the public API the router
   # serves (its common use is safely rolling out a field on a shared type).
@@ -93,8 +120,9 @@ module GraphWeaver::SchemaLoader
       survivors = definitions
         .reject { |d| type_definition?(d) && removed.include?(d.name) }
         .map { |d| prune_inaccessible(d, removed) }
+      # survivors already exclude `removed`, so anything newly emptied is fresh
       newly = survivors.select { |d| type_definition?(d) && type_emptied?(d) }.map(&:name)
-      return survivors if (newly - removed.to_a).empty?
+      return survivors if newly.empty?
 
       removed.merge(newly)
     end
@@ -162,7 +190,7 @@ module GraphWeaver::SchemaLoader
   def self.strip_federation_directives(node)
     changes = {}
     if node.respond_to?(:directives) && node.directives
-      changes[:directives] = node.directives.reject { |d| federation_name?(d.name) }
+      changes[:directives] = node.directives.reject { |d| federation_directive_name?(d.name) }
     end
     changes[:fields] = node.fields.map { |c| strip_federation_directives(c) } if node.respond_to?(:fields) && node.fields
     changes[:arguments] = node.arguments.map { |c| strip_federation_directives(c) } if node.respond_to?(:arguments) && node.arguments

data/lib/graph_weaver/selection.rb

@@ -34,24 +34,41 @@ module GraphWeaver
     # Flatten a selection set as seen by `type`, yielding (result_key,
     # field_node) per field: plain fields yield directly; inline fragments
     # and named spreads recurse when their type condition applies.
-    def each_field(type, selections, &block)
+    def each_field(type, selections, visiting = Set.new, &block)
       selections.each do |selection|
         case selection
         when GraphQL::Language::Nodes::Field
           yield(selection.alias || selection.name, selection)
         when GraphQL::Language::Nodes::InlineFragment
-          each_field(type, selection.selections, &block) if applies?(selection.type&.name, type)
+          each_field(type, selection.selections, visiting, &block) if applies?(selection.type&.name, type)
         when GraphQL::Language::Nodes::FragmentSpread
           fragment = @fragments.fetch(selection.name) do
             raise ArgumentError, "unknown fragment: #{selection.name}"
           end
-          each_field(type, fragment.selections, &block) if applies?(fragment.type.name, type)
+          if visiting.include?(selection.name)
+            raise GraphWeaver::Error, "fragment cycle through #{selection.name}"
+          end
+
+          if applies?(fragment.type.name, type)
+            each_field(type, fragment.selections, visiting | [selection.name], &block)
+          end
         else
           raise GraphWeaver::Error, "unsupported selection: #{selection.class}"
         end
       end
     end
 
+    # each_field grouped by result key: repeated selections of one field
+    # (`a { x } a { y }`, or the same field reached through two fragments)
+    # collect together, so callers MERGE their sub-selections rather than
+    # last-writer-wins. Codegen relies on this; FakeClient/Anonymizer must too,
+    # or they'd fabricate/keep a shape the generated struct can't cast.
+    def gather(type, selections)
+      out = {}
+      each_field(type, selections) { |key, node| (out[key] ||= []) << node }
+      out
+    end
+
     # A fragment's type condition applies when it names this type exactly,
     # or an interface/union this type belongs to (`... on Named { ... }`).
     def applies?(condition, type)

data/lib/graph_weaver/testing/cassette.rb

@@ -70,7 +70,7 @@ module GraphWeaver
         entry = {
           "key" => self.class.key(query, variables),
           "query" => query,
-          "variables" => variables,
+          "variables" => self.class.normalize_variables(variables),
           "response" => response,
         }
         @entries.reject! { |existing| existing["key"] == entry["key"] }
@@ -92,7 +92,14 @@ module GraphWeaver
       end
 
       def self.key(query, variables)
-        { "query" => query.gsub(/\s+/, " ").strip, "variables" => variables || {} }
+        { "query" => query.gsub(/\s+/, " ").strip, "variables" => normalize_variables(variables) }
+      end
+
+      # JSON round-trip so symbol keys become strings — otherwise YAML.dump
+      # writes Ruby symbols the safe loader rejects on the next run, and lookup
+      # keys stay stable across processes
+      def self.normalize_variables(variables)
+        JSON.parse(JSON.generate(variables || {}))
       end
 
       private
@@ -167,6 +174,19 @@ module GraphWeaver
 
       private
 
+      # Anonymization walks recorded data, not a live dispatch. When the query
+      # narrows an abstract type without selecting __typename (`named { name
+      # ... on Pet { species } }`), the recorded data has no type tag, so the
+      # strict applies? would drop the `... on Pet` fields. Treat any concrete
+      # member condition as applying; object_value's `data.key?(key)` guard
+      # discards fields the actual member's response didn't carry.
+      def applies?(condition, type)
+        return true if super
+
+        member = @schema.get_type(condition)
+        !!member && @schema.possible_types(type).include?(member)
+      end
+
       def object_value(type, selections, data)
         return data if data.nil?
 
@@ -190,7 +210,12 @@ module GraphWeaver
       end
 
       def field_value(parent_type, node, value)
-        type_value(@schema.get_field(parent_type.graphql_name, node.name).type, node, value)
+        # a field from a `... on Member` fragment lives on the member, not the
+        # abstract type we're walking (no __typename to narrow by), so fall back
+        # to whichever possible type declares it
+        field = @schema.get_field(parent_type.graphql_name, node.name) ||
+          @schema.possible_types(parent_type).filter_map { |t| @schema.get_field(t.graphql_name, node.name) }.first
+        type_value(field.type, node, value)
       end
 
       def type_value(type, node, value)

data/lib/graph_weaver/testing/fake_client.rb

@@ -73,6 +73,8 @@ class GraphWeaver::Testing::FakeClient
 
     @path = []
     @failures = []
+    # fail_at fires once per execute, not once per client lifetime
+    @fail_at.each { |spec| spec.delete("triggered") }
     data = object_value(root_type, operation.selections)
     data = nil if data.equal?(NULL_BUBBLE) # total propagation, like a real server
 
@@ -104,9 +106,12 @@ class GraphWeaver::Testing::FakeClient
 
   def object_value(type, selections)
     result = {}
-    each_field(type, selections) do |key, node|
+    # gather (not each_field) so a field selected twice — `a { x } a { y }` —
+    # fabricates the MERGED shape codegen's struct expects, not last-writer-wins
+    gather(type, selections).each do |key, nodes|
+      node = nodes.first
       @path.push(key)
-      value = node.name == "__typename" ? type.graphql_name : field_value(type, node)
+      value = node.name == "__typename" ? type.graphql_name : field_value(type, node, nodes.flat_map(&:selections))
       @path.pop
 
       if value.equal?(NULL_BUBBLE)
@@ -127,7 +132,7 @@ class GraphWeaver::Testing::FakeClient
     @schema.get_field(type.graphql_name, node.name).type.kind.name == "NON_NULL"
   end
 
-  def field_value(parent_type, node)
+  def field_value(parent_type, node, selections)
     if (spec = matching_failure)
       @failures << {
         "message" => spec["message"] || "simulated failure",
@@ -148,7 +153,7 @@ class GraphWeaver::Testing::FakeClient
       return corrupt_value(field_type)
     end
 
-    type_value(field_type, node)
+    type_value(field_type, node, selections)
   end
 
   # a value casting can't accept, derived from the field's own type — and
@@ -181,17 +186,18 @@ class GraphWeaver::Testing::FakeClient
     argument = node.arguments.find { |arg| %w[first last limit].include?(arg.name) }
     return argument.value if argument && argument.value.is_a?(Integer)
 
-    rng.rand(@list_size)
+    # an Integer list_size means exactly that many; a Range randomizes within it
+    @list_size.is_a?(Range) ? rng.rand(@list_size) : @list_size
   end
 
-  def type_value(type, node, non_null: false)
+  def type_value(type, node, selections, non_null: false)
     case type.kind.name
     when "NON_NULL"
-      type_value(type.of_type, node, non_null: true)
+      type_value(type.of_type, node, selections, non_null: true)
     when "LIST"
       elements = Array.new(list_length(node)) do |index|
         @path.push(index)
-        element = type_value(type.of_type, node)
+        element = type_value(type.of_type, node, selections)
         @path.pop
         element
       end
@@ -206,21 +212,21 @@ class GraphWeaver::Testing::FakeClient
     else
       return if !non_null && rng.rand < @null_chance
 
-      core_value(type, node)
+      core_value(type, node, selections)
     end
   end
 
-  def core_value(type, node)
+  def core_value(type, node, selections)
     case type.kind.name
     when "SCALAR"
       @values.scalar(type.graphql_name, node.name)
     when "ENUM"
       type.values.keys.sort.sample(random: rng)
     when "OBJECT"
-      object_value(type, node.selections)
+      object_value(type, selections)
     when "UNION", "INTERFACE"
       member = @schema.possible_types(type).sort_by(&:graphql_name).sample(random: rng)
-      object_value(member, node.selections)
+      object_value(member, selections)
     else
       raise NotImplementedError, "cannot fake kind: #{type.kind.name}"
     end

data/lib/graph_weaver/transport/faraday.rb

@@ -32,6 +32,13 @@ module GraphWeaver
       def initialize(url_or_connection, headers: {}, &block)
         @connection = case url_or_connection
         when ::Faraday::Connection
+          # a prebuilt connection carries its own headers/middleware, so
+          # headers:/block would be silently dropped — fail loudly instead
+          unless headers.empty? && block.nil?
+            raise ArgumentError,
+              "headers:/block are ignored when passing a prebuilt Faraday::Connection — configure them on it"
+          end
+
           url_or_connection
         else
           # Faraday appends the default adapter when the block doesn't set one

data/lib/graph_weaver/transport.rb

@@ -62,15 +62,18 @@ class GraphWeaver::Transport
     # envelope so QueryError machinery sees the structured errors; only
     # a body that isn't GraphQL (proxy pages, HTML 500s) is a ServerError.
     unless (200..299).cover?(status)
-      return parsed if parsed.is_a?(Hash) && parsed.key?("errors")
+      # only a body carrying actual GraphQL errors flows through — a 4xx with
+      # `"errors": null` (or []) isn't a structured error response, so the
+      # status stays the signal
+      return parsed if parsed.is_a?(Hash) && parsed["errors"].is_a?(Array) && parsed["errors"].any?
 
       raise GraphWeaver::ServerError.new(status:, body: body.to_s)
     end
 
-    unless parsed
-      # a 200 that isn't GraphQL — an HTML error page from a proxy, a
-      # captive portal: the server misbehaved, classify it that way
-      raise GraphWeaver::ServerError.new(status:, body: "non-JSON response: #{body.to_s[0, 500]}")
+    unless parsed.is_a?(Hash)
+      # a 200 that isn't a GraphQL object — an HTML error page from a proxy, a
+      # captive portal, or a bare JSON array/string: the server misbehaved
+      raise GraphWeaver::ServerError.new(status:, body: "non-GraphQL response: #{body.to_s[0, 500]}")
     end
 
     parsed

data/lib/graph_weaver/version.rb

@@ -1,3 +1,3 @@
 module GraphWeaver
-  VERSION = "0.4.4"
+  VERSION = "0.4.6"
 end

data/lib/graph_weaver.rb

@@ -293,6 +293,15 @@ module GraphWeaver
     # (`class Module; include T::Sig`) — extracted so it's stubbable in tests.
     def global_tsig? = Module.include?(T::Sig)
 
+    # The closest entry in `dictionary` to `term` — a "did you mean" suggestion,
+    # or nil (also nil when did_you_mean isn't loadable). One home for the guard
+    # used by codegen validation, alias resolution, and the runtime prop hints.
+    def did_you_mean(dictionary, term)
+      return unless defined?(DidYouMean::SpellChecker)
+
+      DidYouMean::SpellChecker.new(dictionary: dictionary).correct(term).first
+    end
+
     # Teach the generator how a GraphQL custom scalar deserializes into a
     # rich Ruby object (and serializes back onto the wire when used as a
     # variable):

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: graph_weaver
 version: !ruby/object:Gem::Version
-  version: 0.4.4
+  version: 0.4.6
 platform: ruby
 authors:
 - Daniel Pepper