rigortype 0.3.8 → 0.4.0

data/lib/rigor/effects/unit_scan.rb

@@ -5,7 +5,9 @@ require "prism"
 require_relative "../source/constant_path"
 require_relative "../source/node_children"
 require_relative "attribution"
+require_relative "callee_rule"
 require_relative "catalog"
+require_relative "definition_context"
 require_relative "envelope_index"
 require_relative "file_collection"
 require_relative "label_set"
@@ -35,12 +37,62 @@ module Rigor
     # Long by construction: the walk carries one `when` per Ruby construct that originates an effect, and
     # splitting that table across classes would put the vocabulary in one file and the reasons in another.
     class UnitScan # rubocop:disable Metrics/ClassLength
-      # `$~` and friends are frame-local, not global state: a read of one is not `global.read`. (Prism
-      # gives `$1` and `$&` node types of their own, so only the named specials need listing.)
-      FRAME_LOCAL_GLOBALS = %w[$~ $_ $& $` $' $+ $!].to_set.freeze
+      # `$~` and `$_` are frame-local, not global state (#1363): Ruby keeps them in the special-variable slot
+      # of the body that runs them. The blocks that body creates reach the same slot, except the root block
+      # of a `Thread.new`, `Fiber.new` or `Ractor.new`, which has its own; a call into a method defined with
+      # `def` does not reach it. A read of one is not `global.read`, and a write (`$_ = line`, `$~ = nil`)
+      # binds only that slot, so it earns no label, as a local-variable write earns none — except in a
+      # `define_method` body (`@shared_slot`), which runs on the slot of the body that defined it and so
+      # shares it with every sibling defined there. The rest of the match family (`$&`, `` $` ``, `$'`, `$+`,
+      # `$1`…) are Prism nodes of their own that this scan does not colour, and none can be assigned.
+      FRAME_LOCAL_GLOBALS = %i[$~ $_].to_set.freeze
+
+      # `$!` and `$@` are the exception being rescued and its backtrace. They are not frame-local: a read
+      # reaches the dynamically enclosing rescue clause, whichever frame runs it — a caller's, or a callee's
+      # that yields to a block written here. So `$!` is an implicit argument of the running call rather than
+      # program state, and a read of it is not `global.read`. A read of `$@` reads that exception's backtrace
+      # as `e.backtrace` would, and a read of an object's state is never labelled. A write is another matter
+      # and stays `gvar-write`: `$@ = bt` changes that object, which the rescuing frame observes
+      # (`rescue => e` sees the new backtrace). Ruby refuses `$! = x`.
+      RESCUED_EXCEPTION_GLOBALS = %i[$! $@].to_set.freeze
+
+      # The globals whose read is not `global.read`.
+      UNCOLOURED_READS = (FRAME_LOCAL_GLOBALS | RESCUED_EXCEPTION_GLOBALS).freeze
 
       REFLECTIVE_SEND = %i[send public_send __send__].to_set.freeze
 
+      # The constructs under which a call may not run (#1048). Only the `responds:` bit reads this, and
+      # only to refuse to record a response the body might not perform: `render :edit if x` leaves the
+      # other path taking Rails' implicit render.
+      #
+      # The modifier forms need no entry of their own — Prism spells `render :x if y` as an ordinary
+      # `IfNode` — and `RescueNode` is the rescue CLAUSE rather than the body it guards, so a `render` in
+      # the `begin` half of `begin … rescue … end` is at depth zero, which is right: that half runs.
+      #
+      # A `LambdaNode` is here for the same reason and needs no exemption: `@after = -> { redirect_to
+      # "/" }` stores a response rather than performing one, and the body may never be called at all.
+      #
+      # A **block** is branching too, but is answered by {#branching?} rather than listed here, because
+      # only the CALL that owns it can say whether it is one. `User.transaction { redirect_to "/" }`,
+      # `[1].each { redirect_to "/" }` and `x.presence&.then { … }` all contain a call the body may not
+      # make, and recording a response from one would drop the implicit-render edge AND leave the unit
+      # reading exhaustive — the combination this bit exists to prevent.
+      BRANCHING = [
+        Prism::IfNode, Prism::UnlessNode, Prism::CaseNode, Prism::CaseMatchNode,
+        Prism::WhileNode, Prism::UntilNode, Prism::ForNode,
+        Prism::RescueNode, Prism::RescueModifierNode, Prism::AndNode, Prism::OrNode,
+        Prism::LambdaNode
+      ].to_set.freeze
+
+      # The one block a response may be recorded through: `respond_to`'s own. It is the format dispatcher
+      # rather than a conditional, and it always runs — but its ARMS do not, so `f.html { … }` is an
+      # ordinary branching block and a `render json:` in the `f.json` arm no longer stands the `f.html`
+      # arm's implicit render down (#1048). The dispatcher's other half is the per-arm conventional edge
+      # (#1071): each `format.<fmt>` arm the body spells renders `<action>.<fmt>` where the arm's block
+      # does not answer on every path of its own body, exactly as an uninstrumented action renders
+      # `<action>.html`. The arms are read off the same syntax that marks the block transparent.
+      DISPATCH_SELECTORS = %i[respond_to respond_with].to_set.freeze
+
       # Selectors a per-class POSTURE default must never answer for, because a more specific reading of
       # the same site exists and would be swallowed: `send` and friends are the `dynamic-send` taint, and
       # `call` is the `opaque-callable` one. An explicit ROW still wins (`Fiddle::Function#call` is
@@ -85,9 +137,10 @@ module Rigor
       # declaration wherever it appears: in a class body it is the only way that method exists, and inside
       # another method it is a definition the enclosing method performs (`mutate.static`) rather than code
       # the enclosing method contains. A non-literal name has no key to file the block under, so it stays
-      # contained in the enclosing method and this returns nil.
+      # contained in the enclosing method and this returns nil. Which side the method lands on is the
+      # {DefinitionContext}'s to say.
       #
-      # @return [Array, nil] `[name, singleton, body, parameters]`
+      # @return `[name, body, parameters]`
       def self.define_method_unit(node)
         return nil unless node.name == :define_method && node.receiver.nil?
 
@@ -97,26 +150,42 @@ module Rigor
         block = node.block
         return nil unless block.is_a?(Prism::BlockNode)
 
-        [first.unescaped, false, block.body, block.parameters]
+        [first.unescaped, block.body, block.parameters]
       end
 
-      # @param singleton [Boolean] whether the unit's `self` is the class object (`def self.x`,
-      #   `class << self`) — the axis that separates `mutate.self` from `mutate.static` on an ivar write
-      # @param block_parameter [String, nil] the unit's `&blk` parameter name, if any; a call on it is
+      # @param context — the {DefinitionContext} the body runs under. Its singleton bit — whether the
+      #   unit's `self` is a class object (`def self.x`, a `def` in `class << self`) — is the axis that
+      #   separates `mutate.self` from `mutate.static` on an ivar write; the rest says where the units
+      #   nested in the body land
+      # @param block_parameter — the unit's `&blk` parameter name, if any; a call on it is
       #   forwarding, not an opaque callable
-      # @param calls [Hash] node-identity table of {Collector::CallRecord}s
-      # @param attribution [Attribution] the project's `effects.attribution:` table
-      # @param envelopes [EnvelopeIndex] the envelopes a call site may import as a `≤` bound (#386)
-      # @param plugin_facts [PluginFacts] the loaded plugins' `effect_attributions:` (#387)
-      # @param owner_class [String, nil] the class this unit is defined on — the carrier an
+      # @param calls — node-identity table of {Collector::CallRecord}s
+      # @param attribution — the project's `effects.attribution:` table
+      # @param envelopes — the envelopes a call site may import as a `≤` bound (#386)
+      # @param plugin_facts — the loaded plugins' `effect_attributions:` (#387)
+      # @param owner_class — the class this unit is defined on — the carrier an
       #   implicit-self call's envelope is looked up under, since the syntax spells `Kernel#name`
-      # @param method_name [String, nil] this unit's own selector — what a `super` in its body names as
+      # @param method_name — this unit's own selector — what a `super` in its body names as
       #   the target the propagator resolves above `owner_class` (#446). With no name to state, a `super`
       #   taints instead.
-      def initialize(singleton:, parameters:, block_parameter:, owned_locals:, calls:, # rubocop:disable Metrics/ParameterLists
+      # @param non_public — whether the class body declared this unit `private` or `protected`
+      #   (#1048). Only a UNIT callee rule reads it, and only to decline: Rails' `action_methods` is a
+      #   controller's PUBLIC instance methods, so a private helper is never implicitly rendered — while
+      #   a project that happens to ship a template of the same name would otherwise hand that
+      #   template's effects to the helper.
+      # @param shared_slot — whether the body is a `define_method` block, which runs on the special-variable
+      #   slot of the body that defined it rather than on one of its own (#1363). A write to a
+      #   {FRAME_LOCAL_GLOBALS} name there reaches every sibling defined in that body, so it stays
+      #   `global.write`.
+      def initialize(context:, parameters:, block_parameter:, owned_locals:, calls:, # rubocop:disable Metrics/ParameterLists
                      attribution: Attribution.empty, envelopes: EnvelopeIndex.empty,
-                     plugin_facts: PluginFacts.empty, owner_class: nil, method_name: nil)
+                     plugin_facts: PluginFacts.empty, owner_class: nil, method_name: nil,
+                     non_public: false, shared_slot: false)
+        singleton = context.singleton?
         @singleton = singleton
+        # The context at the walk's current position. It starts as the body's own and moves only inside a
+        # block or `class << self` body that rebinds `self`; the unit's singleton bit does not move with it.
+        @context = context
         @block_parameter = block_parameter
         @calls = calls
         @attribution = attribution
@@ -124,6 +193,8 @@ module Rigor
         @plugin_facts = plugin_facts
         @owner_class = owner_class
         @method_name = method_name
+        @non_public = non_public ? true : false
+        @shared_slot = shared_slot ? true : false
         @mutation = MutationClassifier.new(
           singleton: singleton, parameters: parameters, owned_locals: owned_locals
         )
@@ -133,10 +204,44 @@ module Rigor
         @edges = []
         @nested = []
         @delegates_upward = false
+        # #1048 — whether a plugin row marked `responds:` fired **unconditionally** in this unit, i.e.
+        # the body supplied the framework's answer on every path through it. It is what stands a UNIT
+        # callee rule down: an action that called `render :edit` or `redirect_to` outright did not take
+        # Rails' implicit render.
+        #
+        # Conditional does not count, and that is the whole of the bit's care. `redirect_to root_path if
+        # @user.nil?` leaves the other path taking the implicit render, so a unit that recorded the
+        # response there would drop the template edge AND read exhaustive — the one combination an
+        # effect summary may never produce. {@conditional} counts the branching ancestors the walk is
+        # inside; only a depth of zero answers.
+        @responded = false
+        @conditional = 0
+        @transparent_blocks = Set.new.compare_by_identity
+        # #1071 — a `respond_to` dispatcher's format arms, read for the per-arm conventional edge that
+        # replaced the single `html` unit edge. Each arm is one `format.<fmt>` call made on the
+        # dispatcher's block parameter, and an arm's own block is a branch the scan walks with the same
+        # {@conditional} bit scoped to it: a `responds:` row fired at the arm's top level stands THAT
+        # arm's conventional template down, exactly as a unit-level response stands the implicit render
+        # down. `@arms_by_block` maps an arm block node to its arm so the walk can open the scope;
+        # `@arm_stack` holds the open ones with the depth their body's top level sits at;
+        # `@block_stack` is every open block node, so an arm call is recognised by its enclosing block
+        # being one of {@transparent_blocks}; `@dispatch_top_level` remembers whether a dispatcher was
+        # spelled at the unit's top level, which is what lets the unit rule stand down for the standard
+        # responder while an action whose `respond_to` is inside a branch still keeps its plain implicit
+        # render.
+        @format_arms = []
+        @arms_by_block = {}.compare_by_identity
+        @arm_stack = []
+        @block_stack = []
+        @dispatch_top_level = false
+        # #391 — set only where a site could not carry the bit on an edge; see {#record_edge}.
+        @unclaimed = false
       end
 
       # Units discovered inside this one — a nested `def`, or a `define_method` with a literal name whose
-      # block becomes that method's body. Each is `[name, singleton, body_node, parameters_node]`.
+      # block becomes that method's body. Each is `[name, body context, body_node, parameters_node,
+      # shared_slot]`, the context being the {DefinitionContext}'s answer at the definition and `shared_slot`
+      # true for the `define_method` block (see {#initialize}). One it cannot place is omitted.
       attr_reader :nested
 
       # Whether this body reaches `super` — an override that delegates upward still runs whatever the
@@ -153,13 +258,22 @@ module Rigor
       # Walks `body` and returns `[Summary, edges]`.
       def run(body)
         walk(body)
+        apply_unit_callees
         summary = Summary.new(
           bundles: @bundles, declared_bundles: @declared_bundles,
-          exhaustive: @causes.empty?, causes: @causes
+          exhaustive: @causes.empty?, causes: @causes, unclaimed: @unclaimed
         )
         [summary, @edges]
       end
 
+      # One `format.<fmt>` arm of a `respond_to` dispatcher (#1071): the format it spells, and whether a
+      # plugin `responds:` row fired unconditionally in the arm's own block. `responded` is mutated by the
+      # walk (a Struct, unlike the Data rows the rules produce) and `conventional?` is the any/all
+      # exclusion — those two arms serve every format and can name no single template.
+      FormatArm = Struct.new(:format, :responded, keyword_init: true) do
+        def conventional? = format != "any" && format != "all"
+      end
+
       private
 
       def add(origin, labels)
@@ -183,21 +297,66 @@ module Rigor
         return if unit_boundary?(node)
 
         visit(node)
-        node.rigor_each_child { |child| walk(child) }
+        return walk_children(node) unless branching?(node)
+
+        @conditional += 1
+        arm = enter_arm_block(node)
+        walk_children(node)
+        @arm_stack.pop if arm
+        @conditional -= 1
+      end
+
+      # The children, with the block stack maintained: an arm call is recognised by its innermost
+      # enclosing block being one of the dispatcher's transparent ones, so every `BlockNode` the walk
+      # descends into has to be on the stack while its body runs (#1071).
+      def walk_children(node)
+        if node.is_a?(Prism::BlockNode)
+          @block_stack.push(node)
+          node.rigor_each_child { |child| walk(child) }
+          @block_stack.pop
+        elsif DefinitionContext.rebinds?(node)
+          walk_rebinding(node)
+        else
+          node.rigor_each_child { |child| walk(child) }
+        end
+      end
+
+      # The children of a node one of which may run under another {DefinitionContext} — a `class_eval`
+      # block, a `class << self` body — so a unit nested there is keyed where Ruby defines it.
+      def walk_rebinding(node)
+        outer = @context
+        node.rigor_each_child do |child|
+          @context = outer.for_child(node, child)
+          walk(child)
+        end
+        @context = outer
+      end
+
+      # Whether the walk is entering a construct whose body may not run. A `BlockNode` answers from the
+      # call that owns it, which {#visit_call} has already marked — `walk` visits a node before its
+      # children, so the mark is always in place by the time the block is reached.
+      def branching?(node)
+        return !@transparent_blocks.include?(node) if node.is_a?(Prism::BlockNode)
+
+        BRANCHING.include?(node.class)
       end
 
       # A nested unit is recorded and NOT descended into: its body belongs to its own summary, and the
-      # enclosing method gets only the `mutate.static` of having defined it.
+      # enclosing method gets only the `mutate.static` of having defined it. One the {DefinitionContext}
+      # cannot place is not descended into either, and belongs to no summary.
       def unit_boundary?(node)
         case node
         when Prism::DefNode
-          @nested << [node.name.to_s, !node.receiver.nil?, node.body, node.parameters]
+          context = @context.def_body(node)
+          @nested << [node.name.to_s, context, node.body, node.parameters, false] if context
           true
         when Prism::CallNode
           declared = self.class.define_method_unit(node)
           return false unless declared
 
-          @nested << declared
+          name, body, parameters = declared
+          context = @context.module_call_body
+          @nested << [name, context, body, parameters, true] if context
           add(DEFINE_METHOD, MUTATE_STATIC)
           true
         else
@@ -211,10 +370,12 @@ module Rigor
         when Prism::XStringNode, Prism::InterpolatedXStringNode
           add(XSTRING, IO_PROCESS)
         when Prism::GlobalVariableReadNode
-          add(GVAR_READ, GLOBAL_READ) unless FRAME_LOCAL_GLOBALS.include?(node.name.to_s)
+          add(GVAR_READ, GLOBAL_READ) unless UNCOLOURED_READS.include?(node.name)
         when Prism::GlobalVariableWriteNode, Prism::GlobalVariableOperatorWriteNode,
-             Prism::GlobalVariableOrWriteNode, Prism::GlobalVariableAndWriteNode
-          add(GVAR_WRITE, GLOBAL_WRITE)
+             Prism::GlobalVariableOrWriteNode, Prism::GlobalVariableAndWriteNode,
+             Prism::GlobalVariableTargetNode
+          # A target is a multiple assignment's, a `for` loop's or a `rescue =>` clause's.
+          add(GVAR_WRITE, GLOBAL_WRITE) unless !@shared_slot && FRAME_LOCAL_GLOBALS.include?(node.name)
         when Prism::ClassVariableReadNode
           add(CVAR_READ, GLOBAL_READ)
         when Prism::ClassVariableWriteNode, Prism::ClassVariableOperatorWriteNode,
@@ -256,6 +417,8 @@ module Rigor
       end
 
       def visit_call(node)
+        mark_transparent_block(node)
+        record_format_arm(node)
         record = @calls[node]
         attribute(node, record)
         plugin = attribute_plugin(node, record)
@@ -270,6 +433,64 @@ module Rigor
         visit_block_argument(node)
       end
 
+      # `respond_to do |format| … end` — the block that is a dispatcher rather than a branch. Marked by
+      # identity, because a `BlockNode` cannot name the call it belongs to and two structurally equal
+      # blocks in one body are two blocks (#1048). A dispatcher spelled at the unit's top level is also
+      # remembered (#1071): its arms answer for the whole body, so the conventional `<action>.html` unit
+      # edge stands down; a dispatcher inside a branch does not cover the fall-through path.
+      def mark_transparent_block(node)
+        return unless node.receiver.nil? && DISPATCH_SELECTORS.include?(node.name)
+
+        block = node.block
+        @transparent_blocks << block if block.is_a?(Prism::BlockNode)
+        @dispatch_top_level ||= true if @conditional.zero?
+      end
+
+      # #1071 — one `format.<fmt>` arm of the enclosing `respond_to`, when the formatter is the block's
+      # own parameter: the edge its arm answers for is the conventional `<action>.<fmt>` template, and the
+      # walk needs the arm registered and its block (if any) mapped before it descends into that block's
+      # body. A call made on anything else in the block is not an arm; a formatter nobody assigned a
+      # parameter is a dispatcher whose arms cannot be read, and the unit rule simply keeps its old
+      # single answer.
+      def record_format_arm(node)
+        enclosing = @block_stack.last
+        return unless enclosing.is_a?(Prism::BlockNode) && @transparent_blocks.include?(enclosing)
+
+        parameter = block_parameter(enclosing)
+        return if parameter.nil?
+        return unless node.receiver.is_a?(Prism::LocalVariableReadNode) && node.receiver.name.to_s == parameter
+
+        arm = FormatArm.new(format: node.name.to_s)
+        @format_arms << arm
+        block = node.block
+        @arms_by_block[block] = arm if block.is_a?(Prism::BlockNode)
+      end
+
+      # The name of a dispatcher block's first required parameter — `|format|` in the ordinary shape. A
+      # `respond_to` whose block spells no parameter (or a splat, or a destructure) has no formatter the
+      # walk can name arms on.
+      def block_parameter(block)
+        params = block.parameters
+        return nil unless params.is_a?(Prism::BlockParametersNode)
+
+        required = params.parameters&.requireds
+        return nil if required.nil? || required.empty?
+
+        first = required.first
+        first.name.to_s if first.respond_to?(:name)
+      end
+
+      # Opens an arm scope for the walk: the arm's own block is a branch like any other, and its body's
+      # top level sits at the current {@conditional} depth — the value a `responds:` row must fire at for
+      # the ARM to count as answered outright.
+      def enter_arm_block(node)
+        arm = @arms_by_block[node]
+        return nil unless arm
+
+        @arm_stack << [arm, @conditional]
+        arm
+      end
+
       # The **plugin stratum** (#387; ADR-103 WD6 / WD10): what the plugin that models a framework says
       # this call does.
       #
@@ -283,22 +504,129 @@ module Rigor
       # Three receiver shapes, tried nearest-syntax first — a written receiver path (`Rails.cache.read`),
       # a receiver rooted at implicit self inside a framework class (`session[:x] = 1`), and the receiver's
       # class through the project's inheritance chain (`user.save`).
-      # @return [PluginFacts::Row, nil] the row that claimed this call, for {#visit_call} to read as a bound
+      # @return the row that claimed this call, for {#visit_call} to read as a bound
       def attribute_plugin(node, record)
         return nil unless @plugin_facts.attributions?
 
         row = plugin_row(node, record)
         return nil if row.nil?
 
+        @responded = true if row.responds && @conditional.zero?
+        mark_arm_responded(row)
+        edged = callee_edge_taken?(node, row)
         labels = row.narrow ? Narrowing.apply(row.narrow, node) : row.labels
-        return row if labels.nil? || labels.empty?
+        # A `narrow:` that narrowed to nothing says the call does nothing, and a call that does nothing
+        # taints nothing. A row that declares no labels at all is a different statement — since #1048 a
+        # row may contribute an EDGE and no label — so it falls through to the taints rather than
+        # returning here.
+        return row if row.narrow && (labels.nil? || labels.empty?)
+
+        add_declared(Origin.plugin(row.key), labels) unless labels.nil? || labels.empty?
+        record_plugin_taints(row, edged)
+        row
+      end
+
+      # The `responds:` bit scoped to an OPEN format arm (#1071): a row fired at the arm's body top
+      # level, so the arm never falls through to its conventional `<action>.<fmt>` template. A deeper
+      # response does not stand the arm's own fall-through down, exactly as a conditional response does
+      # not stand a unit's implicit render down.
+      def mark_arm_responded(row)
+        return unless row.responds
 
-        add_declared(Origin.plugin(row.key), labels)
-        # A row may discharge AND still taint: `render` states exactly what the CONTROLLER does and says
-        # nothing about the template, which is not an effect unit yet (ADR-103 WD11).
-        taint(row.taint, row.key) if row.taint
+        arm, depth = @arm_stack.last
+        return if arm.nil?
+
+        arm.responded = true if @conditional == depth
+      end
+
+      # A row may discharge AND still taint: `render` states exactly what the CONTROLLER does and says
+      # nothing about the template. Where a {CalleeRule} named the template the taint rides the EDGE
+      # instead (#1048), so a render that reaches a real unit clears it and one that reaches nothing
+      # keeps it — decided by the propagator, which is the only thing that knows.
+      def record_plugin_taints(row, edged)
+        taint(row.taint, row.key) if row.taint && !edged
         taint("plugin-attribution", row.key) unless row.discharge?
-        row
+      end
+
+      # #1048 — the call-graph edge a framework method IS, when the plugin's row named a {CalleeRule}.
+      # `render :show` inside `UsersController` runs `view:users/show.html`, which is a unit in the same
+      # table; the rule reads the call's argument literals and nothing else, and answers nil for anything
+      # it cannot settle — a computed target, an unmodelled option, a receiver whose class names no view
+      # directory. Nil leaves the site exactly as it was, taint included.
+      #
+      # @return whether an edge took the row's taint with it
+      def callee_edge_taken?(node, row)
+        return false if row.callee.nil? || !CalleeRule.site_rule?(row.callee)
+
+        callee = CalleeRule.site(row.callee, node, owner_class: @owner_class, unit_key: @method_name,
+                                                   fallbacks: row.callee_fallbacks)
+        return false if callee.nil?
+
+        @edges << FileCollection::Edge.new(
+          receiver_class: callee.receiver, kind: :singleton, selector: callee.selector, self_call: false,
+          taint_if_unresolved: row.taint ? [row.taint, row.key].freeze : nil,
+          fallback_selectors: callee.fallbacks
+        )
+        !row.taint.nil?
+      end
+
+      # The UNIT callee rules (#1048): an edge a plugin declares for a body that made no call at all.
+      # Rails' implicit render is the whole of the case — an action that falls off its end renders
+      # `<controller>/<action>` — so the producing fact is the ABSENCE of a `responds:` row, which only a
+      # finished unit scan can observe.
+      #
+      # Contributes an edge and nothing else — no label, no taint — which is what keeps it from being
+      # wrong about a method that is not an action at all.
+      #
+      # Two units it never applies to, and both are the same false positive twice: a `private` /
+      # `protected` member (Rails' `action_methods` is public only) and a `def` nested inside another
+      # method. A project with `app/views/users/card.html.erb` and a `private def card` would otherwise
+      # hand that template's `io.db.write` to the helper.
+      #
+      # #1071 widens the answer per `respond_to` arm: a unit that spelled a dispatcher renders one
+      # conventional `<action>.<fmt>` template per arm rather than one `<action>.html`, so the row is
+      # applied once per arm the walk read, each answered outright (a `responds:` row at the arm's own
+      # top level) or degenerate (`any` / `all`) standing its arm's edge down. The `<action>.html`
+      # answer survives only for a dispatcher the walk could not name arms on, or one nested under a
+      # branch — the plain fall-through still exists on the path that skips it.
+      def apply_unit_callees
+        return if @responded || @singleton || @non_public
+        return if @owner_class.nil? || @method_name.nil?
+
+        rows = @plugin_facts.unit_callee_rows
+        return if rows.empty?
+
+        rows.each do |row|
+          next unless @plugin_facts.descends_from?(@owner_class, row.receiver)
+
+          apply_unit_callee_row(row)
+        end
+      end
+
+      # One unit callee row across the unit's format arms: nil targets the plain `<action>.html` implicit
+      # render, and one application per arm reaches that arm's own `<action>.<fmt>` convention (#1071) —
+      # an arm that answered outright, or one serving every format (`any` / `all`), names nothing.
+      def apply_unit_callee_row(row)
+        return apply_unit_callee(row, nil) if @format_arms.empty?
+
+        apply_unit_callee(row, nil) unless @dispatch_top_level
+        @format_arms.each { |arm| apply_unit_callee(row, arm) }
+      end
+
+      # Applies one unit callee row's rule for one target format.
+      # @return the {Callee} the edge was recorded for, or nil when the arm (or the format) names nothing
+      def apply_unit_callee(row, arm)
+        return nil if arm && !arm.conventional?
+        return nil if arm&.responded
+
+        format = arm&.format
+        callee = CalleeRule.unit(row.callee, owner_class: @owner_class, unit_key: @method_name, format: format)
+        return nil if callee.nil?
+
+        @edges << FileCollection::Edge.new(
+          receiver_class: callee.receiver, kind: :singleton, selector: callee.selector, self_call: false
+        )
+        callee
       end
 
       def plugin_row(node, record)
@@ -545,7 +873,11 @@ module Rigor
         selector = literal_selector(node.arguments&.arguments&.first)
         return taint("dynamic-send") unless selector
 
-        push_edge(record, selector, node.receiver.nil?)
+        # A literal `send` is an ordinary call and nothing bounded it, so it is unclaimed on the same
+        # terms as {#record_edge}'s.
+        push_edge(record, selector, node.receiver.nil?,
+                  unclaimed: true, constant_receiver: constant_receiver?(node.receiver))
+        @unclaimed = true if !node.receiver.nil? && !edge_recordable?(record)
       end
 
       def literal_selector(node)
@@ -571,7 +903,14 @@ module Rigor
       # such calls are ordinary inherited ones the catalogue simply has no row for.
       def record_edge(node, record, bound = nil)
         self_call = node.receiver.nil?
-        push_edge(record, node.name.to_s, self_call)
+        # #391 — an uncatalogued, unbounded site is a site whose callee nobody described. Whether that
+        # matters is the propagator's to decide: if the edge lands on a project definition the closure
+        # reads that definition's own summary and the site is fully accounted for. So the bit travels ON
+        # the edge, and the unit is marked directly only where there is no edge to carry it.
+        unclaimed = bound.nil?
+        push_edge(record, node.name.to_s, self_call,
+                  unclaimed: unclaimed, constant_receiver: constant_receiver?(node.receiver))
+        @unclaimed = true if unclaimed && !self_call && !edge_recordable?(record)
         return unless self_call && (record.nil? || !record.resolved)
         # An envelope on this unit's own class for the very selector the dispatcher declined is the
         # project declaring the method and stating its bound; a discharging plugin row on the framework
@@ -583,14 +922,30 @@ module Rigor
         taint("unresolved-self-call", node.name.to_s)
       end
 
-      def push_edge(record, selector, self_call)
-        return if record.nil? || record.receiver_class.nil?
+      def push_edge(record, selector, self_call, unclaimed: false, constant_receiver: false)
+        return unless edge_recordable?(record)
 
         @edges << FileCollection::Edge.new(
-          receiver_class: record.receiver_class, kind: record.kind, selector: selector, self_call: self_call
+          receiver_class: record.receiver_class, kind: record.kind, selector: selector,
+          self_call: self_call, unclaimed: unclaimed, constant_receiver: constant_receiver
         )
       end
 
+      # Whether the AUTHOR wrote this receiver as a constant path (#1039). The edge is otherwise keyed on
+      # the receiver's type, which cannot tell `Base.new` from `self.class.new` — the same `Singleton[Base]`
+      # in both — and the two reach different constructors. Everything else, a bare `self` included, is a
+      # receiver whose run-time class may be a subclass.
+      def constant_receiver?(receiver)
+        receiver.is_a?(Prism::ConstantReadNode) || receiver.is_a?(Prism::ConstantPathNode)
+      end
+
+      # Whether {#push_edge} has a receiver to key an edge on. A call whose receiver the typer never
+      # named carries nothing the propagator can resolve, so an unclaimed site of that shape marks the
+      # unit directly instead of handing the bit to an edge that will not exist (#391).
+      def edge_recordable?(record)
+        !record.nil? && !record.receiver_class.nil?
+      end
+
       def visit_block_argument(node)
         block = node.block
         return unless block.is_a?(Prism::BlockArgumentNode)

data/lib/rigor/effects/unknown_label_check.rb

@@ -30,10 +30,6 @@ module Rigor
 
       module_function
 
-      # @param method_envelopes [Hash{String => Envelope}]
-      # @param class_envelopes [Hash{String => Envelope}]
-      # @param registry [Rigor::Effects::Registry]
-      # @return [Array<Finding>]
       def for_envelopes(method_envelopes:, class_envelopes:, registry:)
         seen = {}
         declarations(method_envelopes, class_envelopes).each do |envelope|
@@ -49,10 +45,9 @@ module Rigor
         seen.values
       end
 
-      # @param labels [Array<String>] the list as written, in source order.
-      # @param key_path [String] the `.rigor.yml` key, for the message (`effects.tolerated`).
-      # @param consequence [String] what the degradation cost, for the message.
-      # @return [Array<Finding>]
+      # @param labels — the list as written, in source order.
+      # @param key_path — the `.rigor.yml` key, for the message (`effects.tolerated`).
+      # @param consequence — what the degradation cost, for the message.
       def for_config(labels:, key_path:, consequence:, registry:)
         tokens = Array(labels).map(&:to_s)
         tokens.filter_map do |token|

data/lib/rigor/effects/unknown_label_report.rb

@@ -17,10 +17,9 @@ module Rigor
     # {.for} answers `nil` unless {LabelIntent} says the spelling is evidently a label — the whole
     # point of the diagnostic is that it fires where intent is evident and nowhere else.
     class UnknownLabelReport < Data.define(:token, :suggestion, :retirement)
-      # @param token [String] the spelling as written.
-      # @param registry [Rigor::Effects::Registry, nil] the vocabulary after plugin load.
-      # @param siblings [Array<String>] the other tokens written alongside it.
-      # @return [UnknownLabelReport, nil]
+      # @param token — the spelling as written.
+      # @param registry — the vocabulary after plugin load.
+      # @param siblings — the other tokens written alongside it.
       def self.for(token:, registry:, siblings: [])
         return nil unless LabelIntent.evident?(token, registry, siblings: siblings)