graph_weaver 0.7.4 → 0.7.6

data/lib/graph_weaver/codegen.rb

@@ -66,15 +66,15 @@ class GraphWeaver::Codegen
   # defines, defaulting to the operation's own name; default_name: is
   # parse's container-scoped fallback (file generation stays strict — a
   # checked-in file deserves a deliberate name). types_namespace: is the shared-types workflow (see
-  # GraphWeaver.generate!): input types, schema enums, and unions hoisted from
-  # shared fragments live once in that module and the query module aliases what
-  # it uses. hoistable_unions: is the set of shared fragment names this query
-  # may hoist (spreads it inlined, minus any it shadows locally) — a
-  # whole-union field spread as one of them resolves to a canonical type in the
-  # shared module (see used_union_names). path: is the file the query was read
+  # GraphWeaver.generate!): input types, schema enums, and the types hoisted out
+  # of shared fragments live once in that module and the query module aliases
+  # what it uses. hoistable_fragments: is the set of shared fragment names this
+  # query may hoist (spreads it inlined, minus any it shadows locally) — a whole
+  # field spread as one of them resolves to a canonical type in the shared
+  # module (see used_fragment_names). path: is the file the query was read
   # from, named alongside line and column in validation errors.
   def initialize(schema:, query:, name: nil, default_name: nil,
-    types_namespace: nil, hoistable_unions: nil, path: nil, module_name: nil,
+    types_namespace: nil, hoistable_fragments: nil, path: nil, module_name: nil,
     graph_name: nil, registry: GraphWeaver::Codegen.registry)
     renamed!(module_name)
     @schema = schema
@@ -87,8 +87,8 @@ class GraphWeaver::Codegen
     @name = name
     @default_name = default_name
     @types_namespace = types_namespace
-    @hoistable_unions = hoistable_unions || []
-    @used_unions = []
+    @hoistable_fragments = hoistable_fragments || []
+    @used_fragments = []
     # scalars this generation had no registration for (see report_untyped_scalars)
     @untyped_scalars = []
     # the graph this module belongs to: its client and, under a test mode,
@@ -144,10 +144,10 @@ class GraphWeaver::Codegen
     { inputs: @variable_inputs.keys, enums: @enums.keys, mapped: @mapped_enums.keys }
   end
 
-  # The shared union fragments this query hoisted, by name — the generate!
-  # workflow unions these across queries to decide what the shared types module
-  # must contain.
-  def used_union_names = @used_unions.dup
+  # The shared fragments this query hoisted, by name — the generate! workflow
+  # unions these across queries to decide what the shared types module must
+  # contain.
+  def used_fragment_names = @used_fragments.dup
 
   # The custom scalars this walk found no registration for (see
   # report_untyped_scalars) — the generate! workflow unions these across
@@ -172,26 +172,29 @@ class GraphWeaver::Codegen
   #   T::Enum, or the wire tables for one mapped onto an app enum
   #   (register_enum) — so a value read out of one query's result hands
   #   straight back into another's variable;
-  # - unions: each named shared fragment a query spread as a whole union field,
-  #   so the same union across queries is one Ruby type family. `fragments` is
-  #   the loaded shared-fragment table (nested spreads resolve through it).
+  # - hoisted: each named shared fragment a query spread as a whole field, so
+  #   the same shape across queries is one Ruby type. `fragments` is the loaded
+  #   shared-fragment table (nested spreads resolve through it).
   #
-  # Unions are built first: a hoisted fragment's own selections are the one
-  # place a query walk never reaches, so the enums they touch are only known
-  # once the fragments are built.
-  def generate_types(inputs:, enums:, unions:, fragments:)
+  # Hoisted fragments are built first: their own selections are the one place a
+  # query walk never reaches, so the enums they touch are only known once the
+  # fragments are built.
+  def generate_types(inputs:, enums:, hoisted:, fragments:)
     validate_module_name!("types module name")
     reset_walk_state!
     # nested spreads inside a shared fragment resolve through the whole table
     @fragments = fragments
 
-    union_nodes = unions.uniq.sort.map { |name| hoisted_union(fragments, name) }
+    nodes = hoisted.uniq.sort.map { |name| hoisted_fragment(fragments, name) }
     inputs.sort.each { |name| input_node(@schema.get_type(name)) }
     enums.uniq.sort.each { |name| variable_core(@schema.get_type(name)) }
-    check_shared_collisions!(unions)
-    union_nodes.each { |union| check_shadowing!(union) }
+    check_shared_collisions!(hoisted)
+    nodes.each do |node|
+      check_shadowing!(node)
+      check_abstract_mixins!(node, hoisted: true)
+    end
 
-    emit_types_files(union_nodes).tap { report_untyped_scalars }
+    emit_types_files(nodes).tap { report_untyped_scalars }
   end
 
   # module-level constants every generated query module defines — a shared
@@ -201,7 +204,7 @@ class GraphWeaver::Codegen
 
   # One hoisted shared fragment, built against the schema and named for the
   # fragment rather than the field that spread it.
-  def hoisted_union(fragments, name)
+  def hoisted_fragment(fragments, name)
     class_name = camelize(name)
     # the query module aliases <class_name> = <shared module>::<class_name>; a
     # name that camelizes to a generated module-level constant (the Result
@@ -213,28 +216,44 @@ class GraphWeaver::Codegen
 
     fragment = fragments.fetch(name)
     type = @schema.get_type(fragment.type.name)
-    members = union_members(type, fragment.selections)
-    UnionNode.new(class_name, members, catch_all_member(type, fragment.selections, members))
+    selections = fragment.selections
+    return object_node(type, selections, class_name) if type.kind.object?
+
+    # the abstract shape is the fragment's own selections' to decide, exactly
+    # as it would be at a field spelling them inline — see abstract_shape
+    case (shape = abstract_shape(type, selections))
+    when :abstract_level then object_node(type, selections, class_name)
+    when :dispatch
+      members = union_members(type, selections)
+      UnionNode.new(class_name, members, catch_all_member(type, selections, members))
+    else
+      narrowing_tag!(shape, type, selections)
+      object_node(shape, selections, class_name)
+    end
   end
-  private :hoisted_union
+  private :hoisted_fragment
 
   # Schema type names are unique, so an input and an enum can never land on the
-  # same name — but a hoisted union is named for its FRAGMENT, which the schema
-  # knows nothing about. One shared module means one namespace, so a fragment
-  # named after a type it doesn't describe has to refuse rather than overwrite.
+  # same name — but a hoisted type is named for its FRAGMENT, which the schema
+  # knows nothing about: two fragments camelize onto one name as readily as one
+  # lands on a type's. One shared module means one namespace, so either
+  # collision refuses rather than overwrites. Sorted, so which query file was
+  # walked first doesn't decide which fragment is named as the incumbent.
   def check_shared_collisions!(names)
     taken = {}
     @enums.each { |graphql_name, node| taken[node.class_name] = "the schema enum #{graphql_name}" }
     @mapped_enums.each_key { |graphql_name| taken[camelize(graphql_name)] = "the schema enum #{graphql_name}" }
     @variable_inputs.each { |graphql_name, node| taken[node.class_name] = "the input type #{graphql_name}" }
 
-    names.each do |name|
+    names.uniq.sort.each do |name|
       class_name = camelize(name)
-      claim = taken[class_name] or next
+      if (claim = taken[class_name])
+        raise GraphWeaver::Error,
+          "shared fragment #{name.inspect} hoists to #{@name}::#{class_name}, " \
+          "where #{claim} already generates — rename the fragment"
+      end
 
-      raise GraphWeaver::Error,
-        "shared fragment #{name.inspect} hoists to #{@name}::#{class_name}, " \
-        "where #{claim} already generates — rename the fragment"
+      taken[class_name] = "the shared fragment #{name.inspect}"
     end
   end
   private :check_shared_collisions!
@@ -250,7 +269,7 @@ class GraphWeaver::Codegen
     @input_list = false
     @input_hops = []
     @mapped_enums = {}
-    @used_unions = []
+    @used_fragments = []
     # block-built type helpers this walk included — see #block_helpers
     @block_helpers = []
     # requires the generated file needs (custom scalars, enum mappings,
@@ -408,6 +427,7 @@ class GraphWeaver::Codegen
     variables = build_variables(operation)
     root = object_node(root_type, operation.selections, "Result")
     check_shadowing!(root)
+    check_abstract_mixins!(root)
 
     # An anonymous operation takes the module's name — declared in the document
     # AND sent as operationName, which have to agree (a server rejects an
@@ -719,7 +739,7 @@ class GraphWeaver::Codegen
   # The shared fragments a query spreads (transitively), excluding any it
   # shadows with a local definition of the same name — the names
   # inline_fragments appends, and the set the generate! workflow may hoist
-  # when they sit on a whole-union field.
+  # when they are a field's whole selection.
   def self.shared_fragment_spreads(query, shared, path = nil)
     # parsed even with nothing to spread: this is the first look at the document
     # on the generate! path, so it's where a syntax error gets branded and
@@ -872,59 +892,16 @@ class GraphWeaver::Codegen
 
         case (core = field_type.unwrap).kind.name
         when "OBJECT"
-          name = pick_name(key, taken)
-          type_ref(field_type) { object_node(core, sub_selections, name) }
-        when "UNION", "INTERFACE"
-          conditions = concrete_conditions(core, sub_selections)
-          shared = abstract_level_fields(core, sub_selections)
-
-          if conditions.empty?
-            # abstract-level fields only — every member shares them, so one
-            # struct suffices and no __typename dispatch is needed (for a
-            # union that selection can only be __typename)
+          if (frag = hoistable_spread(core, sub_selections))
+            hoisted_ref(field_type, frag)
+          else
             name = pick_name(key, taken)
             type_ref(field_type) { object_node(core, sub_selections, name) }
-          elsif conditions.size == 1 && shared.empty? &&
-              (member = @schema.get_type(conditions.first)).kind.name == "OBJECT"
-            # a single `... on X` condition: narrow to X's struct — nil
-            # when the runtime type doesn't match (narrowing filters).
-            # With `__typename` selected the match is read off the tag;
-            # without one there is nothing to read but emptiness, and a
-            # fragment whose every field hides behind @skip/@include would
-            # make a real match indistinguishable from a miss ({} either
-            # way) — refuse rather than guess.
-            tag = member.graphql_name if dispatchable_typename?(core, sub_selections)
-            unless tag || unconditional_field?(member, sub_selections)
-              raise GraphWeaver::Error,
-                "narrowed `... on #{member.graphql_name}` needs at least one field not under " \
-                "@skip/@include (or a `__typename` to match on) — an all-conditional selection " \
-                "makes a match indistinguishable from nil"
-            end
-
-            name = pick_name(key, taken)
-            nilable_type_ref(field_type) { NarrowedNode.new(object_node(member, sub_selections, name), typename: tag) }
-          elsif @types_namespace && (frag = lone_shared_spread(sub_selections)) &&
-              @hoistable_unions.include?(frag)
-            # a whole-union field spread as a named shared fragment: hoist to
-            # the shared types module so the same union across queries is one
-            # Ruby type family (one exhaustive `case ... T.absurd`).
-            @used_unions << frag unless @used_unions.include?(frag)
-            ref = UnionRefNode.new(camelize(frag))
-            type_ref(field_type) { ref }
-          else
-            members = union_members(core, sub_selections)
-            catch_all = catch_all_member(core, sub_selections, members)
-            # reuse an identical sibling union — the shared type takes the
-            # first of the sharing keys alphabetically, not in walk order
-            signature = union_signature(members, catch_all)
-            union = union_cache[signature]
-            if union
-              rename_union(union, key, taken) if camelize(key) < union.class_name
-            else
-              union = union_cache[signature] = UnionNode.new(pick_name(key, taken), members, catch_all)
-            end
-            type_ref(field_type) { union }
           end
+        when "UNION", "INTERFACE"
+          abstract_field(AbstractField.new(
+            type: field_type, selections: sub_selections, key:, taken:, union_cache:,
+          ))
         when "ENUM"
           # one schema enum is one Ruby type: module-level, named for the enum,
           # shared by every result field and variable that reaches it (and, on
@@ -953,6 +930,114 @@ class GraphWeaver::Codegen
     node
   end
 
+  # An abstract-typed (union or interface) field: what was selected through it,
+  # and the two ledgers the struct being built keeps — the names already claimed
+  # in its scope, and the unions it has already emitted.
+  AbstractField = Data.define(:type, :selections, :key, :taken, :union_cache) do
+    def core = type.unwrap
+  end
+  private_constant :AbstractField
+
+  # An abstract-typed field. Hoisting is asked FIRST, as it is for an object
+  # field: a whole field spread as one shared fragment is one shared type
+  # whatever shape that fragment has, and which shape it has must not be what
+  # decides — adding a second `... on` to a fragment would otherwise move every
+  # consumer's constant.
+  def abstract_field(field)
+    if (frag = hoistable_spread(field.core, field.selections))
+      return hoisted_ref(field.type, frag)
+    end
+
+    case (shape = abstract_shape(field.core, field.selections))
+    when :abstract_level then abstract_level_struct(field)
+    when :dispatch then dispatch_union(field)
+    else narrowed_struct(field, shape)
+    end
+  end
+
+  # Which of three shapes an abstract selection generates, decided by the
+  # selection rather than the schema: :abstract_level when it names no concrete
+  # type, the one object member when it narrows to exactly that and nothing
+  # else, :dispatch otherwise. Both the hoisted type and every reference to it
+  # ask this, so the two can't disagree about what was built.
+  def abstract_shape(core, selections)
+    conditions = concrete_conditions(core, selections)
+    return :abstract_level if conditions.empty?
+    return :dispatch unless conditions.size == 1 && abstract_level_fields(core, selections).empty?
+
+    member = @schema.get_type(conditions.first)
+    member.kind.name == "OBJECT" ? member : :dispatch
+  end
+
+  # Every member carries the abstract-level fields, so one struct answers for
+  # all of them and there is nothing to dispatch on — for a union, the only
+  # selection that can get here is __typename.
+  def abstract_level_struct(field)
+    name = pick_name(field.key, field.taken)
+    type_ref(field.type) { object_node(field.core, field.selections, name) }
+  end
+
+  # Narrowing to the one member a `... on X` names filters: the field is nil
+  # whenever the runtime type doesn't match.
+  def narrowed_struct(field, member)
+    tag = narrowing_tag!(member, field.core, field.selections)
+    name = pick_name(field.key, field.taken)
+    nilable_type_ref(field.type) { NarrowedNode.new(object_node(member, field.selections, name), typename: tag) }
+  end
+
+  # What a narrowed selection matches on: the member's name when `__typename`
+  # is selected, else nil for "the object came back empty". A fragment whose
+  # every field hides behind @skip/@include leaves nothing to read either way
+  # ({} on a match and on a miss alike) — refuse rather than guess.
+  def narrowing_tag!(member, core, selections)
+    return member.graphql_name if dispatchable_typename?(core, selections)
+    return if unconditional_field?(member, selections)
+
+    raise GraphWeaver::Error,
+      "narrowed `... on #{member.graphql_name}` needs at least one field not under " \
+      "@skip/@include (or a `__typename` to match on) — an all-conditional selection " \
+      "makes a match indistinguishable from nil"
+  end
+
+  # A whole field spread as one named shared fragment points at the type
+  # hoisted into the shared types module, so the same shape across queries is
+  # one Ruby type. Which node stands in for it follows the shape hoisted_fragment
+  # built: a dispatch module for a union, a struct otherwise — and a narrowed
+  # one still filters, so the match is read here rather than inside a struct
+  # whose from_h cannot answer nil.
+  def hoisted_ref(field_type, frag)
+    @used_fragments << frag unless @used_fragments.include?(frag)
+    core = field_type.unwrap
+    name = camelize(frag)
+    return type_ref(field_type) { HoistedRefNode.new(name, core.graphql_name) } if core.kind.object?
+
+    selections = @fragments.fetch(frag).selections
+    case (shape = abstract_shape(core, selections))
+    when :abstract_level then type_ref(field_type) { HoistedRefNode.new(name, core.graphql_name) }
+    when :dispatch then type_ref(field_type) { UnionRefNode.new(name, core.graphql_name) }
+    else
+      tag = narrowing_tag!(shape, core, selections)
+      nilable_type_ref(field_type) { NarrowedRefNode.new(name, core.graphql_name, typename: tag) }
+    end
+  end
+
+  # One member struct per type the selection names, chosen at runtime off
+  # __typename. Structurally identical sibling unions share one Ruby type,
+  # named for the first of the sharing keys alphabetically so that which one
+  # the walk reached first doesn't decide.
+  def dispatch_union(field)
+    members = union_members(field.core, field.selections)
+    catch_all = catch_all_member(field.core, field.selections, members)
+    signature = union_signature(members, catch_all)
+    union = field.union_cache[signature]
+    if union
+      rename_union(union, field.key, field.taken) if camelize(field.key) < union.class_name
+    else
+      union = field.union_cache[signature] = UnionNode.new(pick_name(field.key, field.taken), members, catch_all)
+    end
+    type_ref(field.type) { union }
+  end
+
   # A generated class name is only ever a name; Ruby resolves it lexically. So
   # a struct nesting `class Date < T::Struct` (from a result key `date`) turns
   # a sibling `Date` scalar prop into that struct, and `Date.iso8601` into a
@@ -1066,10 +1151,26 @@ class GraphWeaver::Codegen
     dispatchable_typename?(core, selections) ? keys - ["__typename"] : keys
   end
 
+  # The name a field's whole selection hoists under: exactly one bare spread of
+  # a fragment this query may hoist, written on the field's own type. Only the
+  # generate! workflow has a shared module to hoist into — dynamic `parse`
+  # inlines.
+  def hoistable_spread(core, selections)
+    return unless @types_namespace
+
+    frag = lone_shared_spread(selections)
+    return unless frag && @hoistable_fragments.include?(frag)
+
+    # the shared type is built from the fragment's own type condition, so it is
+    # this field's type only when the two agree — a fragment on a narrower (or
+    # wider) type stays a locally-emitted struct
+    frag if @fragments.fetch(frag).type.name == core.graphql_name
+  end
+
   # The fragment name when a selection is exactly one bare fragment spread
-  # (`{ ...F }`) — the shape a union field must have to hoist into the shared
-  # unions module. A spread carrying directives (@skip/@include), or mixed with
-  # other fields, stays a locally-emitted union.
+  # (`{ ...F }`) — the shape a field must have to hoist into the shared types
+  # module. A spread carrying directives (@skip/@include), or mixed with other
+  # fields, stays locally emitted.
   def lone_shared_spread(selections)
     return unless selections.size == 1
 
@@ -1172,7 +1273,7 @@ class GraphWeaver::Codegen
   # it. It carries what the abstract type itself guarantees, plus anything a
   # `... on SomeInterface` asked for, since an unnamed member may implement it.
   def catch_all_member(type, selections, members)
-    node = object_node(type, selections, catch_all_name(members))
+    node = object_node(type, selections, catch_all_name(members.each_value.map(&:class_name)))
     taken = node.fields.map(&:key)
 
     # These are nilable whatever the schema promises: the member that arrives
@@ -1222,9 +1323,9 @@ class GraphWeaver::Codegen
     sibling_conditions(condition, selections, visiting, out)
   end
 
-  # "Other", unless a real member already claims that name.
-  def catch_all_name(members)
-    taken = members.each_value.map(&:class_name)
+  # "Other", unless a real member already claims that name — one rule for a
+  # union's catch-all struct and a generated enum's fallback member.
+  def catch_all_name(taken)
     name = "Other"
     suffix = 2
     while taken.include?(name)
@@ -1251,13 +1352,13 @@ class GraphWeaver::Codegen
     when List then "[#{signature(node.of)}]"
     when NarrowedNode then "?#{signature(node.nested)}"
     when Scalar then "s:#{node.bare_type}"
-    when EnumNode then "e:#{node.values.sort.join("|")}"
+    when EnumNode then "e:#{node.values.sort.join("|")}#{"+" if node.fallback?}"
     when MappedEnum then "m:#{node.graphql_name}"
     when ObjectNode
       inner = node.fields.map { |f| "#{f.prop}=#{signature(f.node)}" }.sort.join(",")
       "o:#{node.graphql_type}(#{inner})"
     when UnionNode then "u:(#{union_signature(node.members, node.catch_all)})"
-    when UnionRefNode then "ur:#{node.class_name}" # hoisted — identity is its shared name
+    when HoistedRefNode then "hr:#{node.class_name}" # hoisted — identity is its shared name
     else "x:#{node.object_id}" # unknown node kind — never collapse
     end
   end
@@ -1406,8 +1507,12 @@ class GraphWeaver::Codegen
         "constant — map it onto one of yours: register_enum(#{core.graphql_name.inspect}, YourEnum)"
     end
 
-    aliases = @registry.enum_registry[core.graphql_name]&.aliases_for(core.values.keys.sort) || {}
-    EnumNode.new(class_name, enum_values(core, aliases), aliases)
+    entry = @registry.enum_registry[core.graphql_name]
+    aliases = entry&.aliases_for(core.values.keys.sort) || {}
+    values = enum_values(core, aliases)
+    # named the way a union's catch-all is: Other, or Other2 past a declared OTHER
+    fallback = catch_all_name(values.map { |value| camelize(value.downcase) }) if entry&.generated_fallback?
+    EnumNode.new(class_name, values, aliases, fallback:)
   end
 
   # A schema enum's constant-bearing wire values, sorted so output is
@@ -1435,7 +1540,7 @@ class GraphWeaver::Codegen
       constant, group = collisions.first
       more = collisions.size - 1
       raise GraphWeaver::Error,
-        "enum #{core.graphql_name} values #{group.join(" and ")} both become the constant #{constant}" \
+        "enum #{core.graphql_name} values #{group.join(" and ")} all 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" \
@@ -1479,6 +1584,61 @@ class GraphWeaver::Codegen
   end
   private :abstract_mixin_members
 
+  # An `abstract!` mixin goes into EVERY struct generated from its type, but
+  # only a struct that selected the members it declares can satisfy them — so a
+  # query selecting a subset generated fine and failed in the app's own
+  # `srb tc`, two tools from the query that fell short. Walked from the root the
+  # way shadowing is, so the refusal can name the struct by its path.
+  def check_abstract_mixins!(node, path = [], hoisted: false)
+    case node
+    when UnionNode
+      inner = path + [node.class_name]
+      (node.members.each_value.to_a + [node.catch_all]).each do |member|
+        check_abstract_mixins!(member, inner, hoisted:)
+      end
+    when ObjectNode
+      inner = path + [node.class_name]
+      refuse_unsatisfiable_mixin!(node, inner, hoisted:)
+      node.fields.each do |field|
+        check_abstract_mixins!(field.node.nested, inner, hoisted:) if field.node.nested
+      end
+    end
+  end
+
+  def refuse_unsatisfiable_mixin!(node, path, hoisted:)
+    return if node.overrides.empty?
+
+    mixins = @registry.type_registry.dig(node.graphql_type, :mixins) || []
+    provided = (node.fields.map(&:prop) + node.aliases.map(&:name)).to_set
+    # what is still abstract with every registered mixin included: a member one
+    # of them implements for another is already answered
+    probe = Module.new
+    mixins.each { |mixin| probe.include(mixin) }
+    missing = T::AbstractUtils.abstract_methods_for(probe)
+      .map { |method| method.name.to_s }.reject { |member| provided.include?(member) }.sort
+    return if missing.empty?
+
+    mixin = mixins.find { |m|
+      T::AbstractUtils.declared_abstract_methods_for(m).any? { |method| missing.include?(method.name.to_s) }
+    }
+    them = missing.one? ? "it" : "them"
+    # the second door is "hoist it", which a struct built inside the shared
+    # types module has already been through
+    fix = if hoisted
+      "Select #{them} in the fragment."
+    else
+      "Select #{them} here, or select #{node.graphql_type} through one shared " \
+        "fragment (`{ ...Frag }`), which hoists one struct for every query to share."
+    end
+
+    raise GraphWeaver::Error,
+      "#{[@name, *path].join("::")} includes #{mixin.name}, which declares " \
+      "#{GraphWeaver::Internal::Util.sample(missing.map(&:inspect))} abstract — this selection does " \
+      "not provide #{them}, and every struct generated from " \
+      "#{node.graphql_type} includes the mixin, so `srb tc` fails on this one. #{fix}"
+  end
+  private :check_abstract_mixins!, :refuse_unsatisfiable_mixin!
+
   # The MappedEnum node for a schema enum with a registered app-enum
   # mapping; nil when unregistered — or registered for alias: alone, which
   # says nothing about the Ruby type — falling back to a generated T::Enum.

data/lib/graph_weaver/coerce.rb

@@ -255,7 +255,7 @@ module GraphWeaver
 
       # the article by the initial, so a registered Ruby class ("an Integer")
       # reads as well as the scalars ("an Int", "an ID", "a Date")
-      def expected(scalar) = "expected #{scalar.start_with?(/[AEIOU]/) ? "an" : "a"} #{scalar}"
+      def expected(scalar) = "expected #{Internal::Util.article(scalar)} #{scalar}"
     end
   end
 end

data/lib/graph_weaver/federation.rb

@@ -341,15 +341,10 @@ module GraphWeaver
           *@skipped.sort.map { |name, what| "  #{name} (#{evidence(what)})" }]
       end
 
-      # how many coordinates the report names before it says "and N more"
-      SAMPLE = 5
-      private_constant :SAMPLE
-
       def evidence(coordinates)
         return "the supergraph attributes nothing to it alone" if coordinates.empty?
-        return coordinates.join(", ") if coordinates.size <= SAMPLE
 
-        "#{coordinates.first(SAMPLE).join(", ")} and #{coordinates.size - SAMPLE} more"
+        Internal::Util.sample(coordinates)
       end
 
       def faked_section

data/lib/graph_weaver/graph.rb

@@ -152,15 +152,48 @@ module GraphWeaver
       # read a source off, so the source is where its modules already post.
       # That is what bootstraps a second graph's dump: URL= names one
       # endpoint, and each graph has its own.
-      url = path ? GraphWeaver::SchemaLoader.provenance(path)&.dig("url") : (client_url if named_dump_path)
-      url || live_schema
+      source = path ? GraphWeaver::SchemaLoader.provenance(path)&.dig("url") : (client_source if named_dump_path)
+      source || live_schema
+    end
+
+    # The server behind this graph, however it is named: the url the dump
+    # recorded, else the graphql-ruby class this process runs, else whatever
+    # this graph's client reaches. nil when there is nothing to ask — a dump
+    # with no provenance, and no client with a server behind it.
+    #
+    # The one source rule the three schema tasks share: `schema:refresh`
+    # rewrites the dump from it, `schema:diff` says how far it has moved, and
+    # `queries:check` validates the queries against it.
+    def source = dump_source || client_source
+
+    # The server this graph's client reaches, as something to ask: the url it
+    # posts to, else the graphql-ruby class it runs in-process. A client that
+    # runs one names a server as surely as a client that posts to one — and
+    # reading only the url is what let `source_transport` reach a schema class
+    # that `source` said wasn't there.
+    def client_source
+      client_url || GraphWeaver::Internal::Util.live_schema(client || GraphWeaver.client)
+    end
+    private :client_source
+
+    # How to reach that source. A schema class answers introspection itself. A
+    # url the dump recorded goes through SchemaLoader, which authenticates from
+    # the auth_env the dump named. A url that came from the graph's client is
+    # that client's own transport — headers, auth and all.
+    def source_transport
+      found = source
+      return found if found.is_a?(Module)
+      return GraphWeaver::SchemaLoader.source_transport(dump_path) if dump_source
+
+      target = client || GraphWeaver.client
+      target.respond_to?(:transport) ? target.transport : target
     end
 
     # The url this graph's modules post to, or nil — the graph's own client,
-    # else the app default, which is where its modules go too. What
-    # `schema:refresh` bootstraps a missing dump from, and what `rake
+    # else the app default, which is where its modules go too. What `rake
     # graph_weaver:graphs` reports; a client with no url (a schema class
-    # running in-process) has none to report.
+    # running in-process) has none to report, and `client_source` is the
+    # question that covers both.
     def client_url
       target = client || GraphWeaver.client
       target = (target.transport if target.respond_to?(:transport)) || target
@@ -248,6 +281,7 @@ module GraphWeaver
       def self.build(name, &block)
         builder = new(name)
         builder.instance_eval(&block)
+        refuse_callable_client!(name, builder.settings[:client])
         graph = GraphWeaver::Graph.new(name:, registrations: builder.registrations, **builder.settings)
         # the block's registrations are applied at generation; run them once
         # here so a bad one is a mistake in the block, said where it is written
@@ -265,6 +299,22 @@ module GraphWeaver
           "Declare graph #{name.inspect} from one.", e.backtrace
       end
 
+      # `schema` takes a callable — that is how an initializer names a class
+      # Zeitwerk hasn't loaded — and the same page says so, which makes one
+      # here an easy mistake. It was accepted, and surfaced much later as
+      # `undefined method 'execute' for an instance of Proc` under a rake
+      # backtrace. A client needs no lambda: the string form names the
+      # constant and is resolved when a module calls it.
+      def self.refuse_callable_client!(name, client)
+        return unless client.respond_to?(:call) && !client.respond_to?(:execute)
+
+        raise ArgumentError, "client in graph #{name.inspect} takes the object your modules " \
+          "call, and a callable doesn't answer #execute — name the object (client " \
+          "GraphWeaver.new(\"https://api.example.com/graphql\")), or its constant (client " \
+          "\"Billing::Schema\"), which is resolved when a module calls it and so needs no lambda"
+      end
+      private_class_method :refuse_callable_client!
+
       def initialize(name)
         @name = name
         @settings = {}