graph_weaver 0.7.4 → 0.7.5

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)
+    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,13 +216,15 @@ class GraphWeaver::Codegen
 
     fragment = fragments.fetch(name)
     type = @schema.get_type(fragment.type.name)
+    return object_node(type, fragment.selections, class_name) if type.kind.object?
+
     members = union_members(type, fragment.selections)
     UnionNode.new(class_name, members, catch_all_member(type, fragment.selections, members))
   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
+  # same name — but a hoisted type 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.
   def check_shared_collisions!(names)
@@ -250,7 +255,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 +413,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 +725,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 +878,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 +916,88 @@ 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
+
+  # Which of four shapes an abstract-typed field generates. The selection
+  # decides, not the schema: what it narrows to, and how it was spread.
+  def abstract_field(field)
+    conditions = concrete_conditions(field.core, field.selections)
+    shared = abstract_level_fields(field.core, field.selections)
+
+    if conditions.empty?
+      abstract_level_struct(field)
+    elsif conditions.size == 1 && shared.empty? &&
+        (member = @schema.get_type(conditions.first)).kind.name == "OBJECT"
+      narrowed_struct(field, member)
+    elsif (frag = hoistable_spread(field.core, field.selections))
+      hoisted_ref(field.type, frag)
+    else
+      dispatch_union(field)
+    end
+  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. 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.
+  def narrowed_struct(field, member)
+    tag = member.graphql_name if dispatchable_typename?(field.core, field.selections)
+    unless tag || unconditional_field?(member, field.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(field.key, field.taken)
+    nilable_type_ref(field.type) { NarrowedNode.new(object_node(member, field.selections, name), typename: tag) }
+  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 — for a union, one exhaustive `case ... T.absurd`.
+  def hoisted_ref(field_type, frag)
+    @used_fragments << frag unless @used_fragments.include?(frag)
+    # an abstract type hoists to a dispatch module, an object type to a struct
+    core = field_type.unwrap
+    node_class = core.kind.object? ? HoistedRefNode : UnionRefNode
+    ref = node_class.new(camelize(frag), core.graphql_name)
+    type_ref(field_type) { ref }
+  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 +1111,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 +1233,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 +1283,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 +1312,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 +1467,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
@@ -1479,6 +1544,49 @@ 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 = [])
+    case node
+    when UnionNode
+      inner = path + [node.class_name]
+      (node.members.each_value.to_a + [node.catch_all]).each { |member| check_abstract_mixins!(member, inner) }
+    when ObjectNode
+      inner = path + [node.class_name]
+      refuse_unsatisfiable_mixin!(node, inner)
+      node.fields.each { |field| check_abstract_mixins!(field.node.nested, inner) if field.node.nested }
+    end
+  end
+
+  def refuse_unsatisfiable_mixin!(node, path)
+    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) }
+    }
+    raise GraphWeaver::Error,
+      "#{[@name, *path].join("::")} includes #{mixin.name}, which declares " \
+      "#{GraphWeaver::Internal::Util.sample(missing.map(&:inspect))} abstract — this selection does " \
+      "not provide #{missing.one? ? "it" : "them"}, and every struct generated from " \
+      "#{node.graphql_type} includes the mixin, so `srb tc` fails on this one. Select " \
+      "#{missing.one? ? "it" : "them"} here, or select #{node.graphql_type} through one shared " \
+      "fragment (`{ ...Frag }`), which hoists one struct for every query to share."
+  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/hints.rb

@@ -69,22 +69,37 @@ module GraphWeaver
     # neither that nor which values exist. Raised bare so the enclosing
     # Hints.field brands it with the field.
     # aliases (register_enum alias:) is wire spelling => the value it reads as.
-    def self.enum(type, value, aliases = nil)
+    # fallback is the Other member, when the registration asked for one.
+    def self.enum(type, value, aliases = nil, fallback: nil)
       value = aliases.fetch(value, value) if aliases
+      member = type.try_deserialize(value)
+      return member if member
+      return absorbed(type, value, fallback) if fallback
 
-      type.try_deserialize(value) || drifted!(type, value, type.values.map(&:serialize))
+      drifted!(type, value, type.values.map(&:serialize), "register_enum fallback: true")
     end
 
     # the same, for an enum mapped onto an app-owned T::Enum, where the wire
     # table rather than the type knows the accepted values
     def self.mapped_enum(type, table, value)
-      table.fetch(value) { drifted!(type, value, table.keys) }
+      table.fetch(value) { drifted!(type, value, table.keys, "register_enum fallback:") }
     end
 
-    def self.drifted!(type, value, values)
+    # A T::Enum member is a singleton, so Other can't carry the value it
+    # swallowed — this line is the only record that anything drifted.
+    def self.absorbed(type, value, fallback)
+      GraphWeaver::Internal::Log.log(:debug) do
+        # the member's bare constant name — a T::Enum member inspects as #<Type::Name>
+        "#{type} absorbed #{GraphWeaver::Internal::Redact.shown(value)} into #{fallback.inspect[/::(\w+)>\z/, 1]}"
+      end
+      fallback
+    end
+    private_class_method :absorbed
+
+    def self.drifted!(type, value, values, suggestion)
       raise KeyError, "#{GraphWeaver::Internal::Redact.shown(value)} is not a #{type} — expected one of: " \
         "#{values.sort.join(", ")}; a value the server added since you generated " \
-        "needs a regenerate, or register_enum fallback: to absorb them"
+        "needs a regenerate, or #{suggestion} to absorb them"
     end
     private_class_method :drifted!
 

data/lib/graph_weaver/in_process.rb

@@ -72,14 +72,12 @@ class GraphWeaver::InProcess
         "#{GraphWeaver::Internal::Wire.truncate_for_log(query)}"
     end
 
-    result = GraphWeaver::Internal::Log.log_timed(:debug, "in-process #{schema_label} #{tag} completed") do
+    GraphWeaver::Internal::Log.log_timed(:debug, "in-process #{schema_label} #{tag} completed") do
       # a copy per query: graphql-ruby writes a resolver's `context[...] =`
       # into the hash it is handed, and one client serves every request
       @schema.execute(query, variables:, operation_name:,
         context: GraphWeaver::Internal::Util.context!(@context).dup)
     end
-
-    result
   rescue GraphWeaver::Error
     raise
   rescue => e

data/lib/graph_weaver/input_struct.rb

@@ -31,12 +31,15 @@ module GraphWeaver
     # 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, 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))
+    # fallback is the generated Other member (register_enum fallback: true).
+    # It is the one member input refuses: nothing on the wire means it, so a
+    # variable carrying it would send a value the server never declared.
+    def self.enum(type, value, aliases = nil, fallback: nil)
+      member = value.is_a?(type) ? value : type.try_deserialize(aliases ? aliases.fetch(value, value) : value)
+      return member if member && !member.equal?(fallback)
+
+      accepted = type.values.map(&:serialize) - [fallback&.serialize].compact
+      member ? unsendable_enum!(member, accepted) : invalid_enum!(type, value, accepted)
     end
 
     # A list element's index, prepended when something inside it refused —
@@ -110,6 +113,18 @@ module GraphWeaver
     end
     private_class_method :invalid_enum!
 
+    # The fallback member is a landing pad for drift, not a value — so it is
+    # refused by name rather than listed among the ones you could have meant.
+    def self.unsendable_enum!(member, accepted)
+      # a T::Enum member inspects as #<Type::Name>
+      raise GraphWeaver::Internal::Refusal.brand(
+        KeyError.new("#{member.inspect[2..-2]} absorbs values the server added, so " \
+          "there is nothing to send for it — expected one of: #{accepted.sort.join(", ")}"),
+        :not_a_member, members: accepted.sort,
+      )
+    end
+    private_class_method :unsendable_enum!
+
     def self.included(base)
       base.extend(ClassMethods)
     end

data/lib/graph_weaver/internal/subgraphs.rb

@@ -34,9 +34,6 @@ module GraphWeaver
     # goes through the same check *and refuses at construction* — a swapped
     # pair fails there rather than as a mystery three fetches later.
     module Subgraphs
-      # how many coordinates a message names before it says "and N more"
-      SAMPLE = 5
-
       # answer this subgraph with fabricated data rather than refusing
       FAKE = :fake
 
@@ -117,15 +114,9 @@ module GraphWeaver
           return schema if gaps.empty?
 
           raise GraphWeaver::ConfigurationError, "subgraphs[#{name.inspect}] is " \
-            "#{schema.name || schema.inspect}, which doesn't define #{sample(gaps)} — the supergraph " \
+            "#{schema.name || schema.inspect}, which doesn't define #{Util.sample(gaps)} — the supergraph " \
             "says #{name} resolves them. Did two entries get swapped?"
         end
-
-        def sample(list)
-          return list.join(", ") if list.size <= SAMPLE
-
-          "#{list.first(SAMPLE).join(", ")} and #{list.size - SAMPLE} more"
-        end
       end
     end
   end

data/lib/graph_weaver/internal/unused.rb

@@ -47,6 +47,11 @@ module GraphWeaver
       # .json.erb's sibling JS — is a blind spot, and the footer says so.
       # .rake and .builder are Ruby too.
       EXTENSIONS = %w[.rb .rake .builder .erb .slim .haml .jbuilder].freeze
+      # Ruby that carries no extension to recognise it by. In a non-Rails
+      # project the entry points live here, so skipping them skipped the
+      # files that read the query.
+      SCRIPT_DIRS = Set["bin", "exe"].freeze
+      RUBY_SHEBANG = /\A#!.*\bruby\b/
       # Directories that hold no app source. "generated" covers both a graph's
       # own output under the convention and a spec/generated fixture dir; a
       # graph that writes somewhere else is pruned by #outputs.
@@ -60,8 +65,9 @@ module GraphWeaver
       # difference between a lint and a number somebody trusts.
       FOOTER = "This is a lint, not a proof — it matches prop names as text, so a common name reads " \
         "as\nused the moment anything says it. It can't see a prop reached by public_send, or a " \
-        "read\nin a file type it doesn't sweep (#{EXTENSIONS.join(", ")}). On a real app half to " \
-        "two\nthirds of genuinely unread selections go unreported; silence is the safe direction."
+        "read\nin a file type it doesn't sweep — #{EXTENSIONS.join(", ")},\nplus Ruby with no " \
+        "extension (any name under bin/ or exe/, a ruby shebang elsewhere). On\na real app half to " \
+        "two thirds of genuinely unread selections go unreported; silence is\nthe safe direction."
 
       # query: the .graphql that selected it. struct/prop: where it landed.
       # wire: how the query spells that prop, when it differs.
@@ -244,19 +250,22 @@ module GraphWeaver
       end
 
       def files
-        @files ||= @roots.flat_map { |root| collect(root, []) }.uniq.sort
+        @files ||= @roots
+          .flat_map { |root| collect(root, [], SCRIPT_DIRS.include?(File.basename(root))) }
+          .uniq.sort
       end
 
       # Pruned as it walks rather than globbed and filtered: node_modules is
-      # the directory you most want never to descend into.
-      def collect(dir, found)
+      # the directory you most want never to descend into. scripts says we are
+      # inside bin/ or exe/, which the walk knows and a path doesn't.
+      def collect(dir, found, scripts)
         Dir.children(dir).sort.each do |entry|
           path = File.join(dir, entry)
           # lstat, so a symlinked directory can't loop the walk
           stat = File.lstat(path)
           if stat.directory?
-            collect(path, found) unless skip_dir?(entry, path)
-          elsif stat.file? && EXTENSIONS.include?(File.extname(entry))
+            collect(path, found, scripts || SCRIPT_DIRS.include?(entry)) unless skip_dir?(entry, path)
+          elsif stat.file? && ruby?(path, entry, scripts)
             found << path
           end
         end
@@ -265,6 +274,22 @@ module GraphWeaver
         found
       end
 
+      # An extension names most of it. A file with none is Ruby if it sits
+      # under bin/ or exe/ — that is what those directories are for — or if
+      # its first line says so.
+      def ruby?(path, entry, scripts)
+        return true if EXTENSIONS.include?(File.extname(entry))
+        return false unless File.extname(entry).empty?
+
+        scripts || shebang?(path)
+      end
+
+      def shebang?(path)
+        File.open(path) { |file| file.gets(chomp: true) }&.match?(RUBY_SHEBANG) || false
+      rescue SystemCallError, ArgumentError
+        false
+      end
+
       def skip_dir?(entry, path) = entry.start_with?(".") || SKIP.include?(entry) || outputs.include?(path)
 
       # The generated directories a name check can't catch: a graph that sets