rigortype 0.3.4 → 0.3.6

data/lib/rigor/effects/framework_units.rb

@@ -82,12 +82,15 @@ module Rigor
       #   arguments, as the scanner harvested them
       # @param uniqueness [Boolean] whether the class body declares a uniqueness validator
       # @param plugin_facts [PluginFacts]
-      def synthesize(class_name:, instance_methods:, macros:, uniqueness:, plugin_facts:)
+      # @param own_units [Hash{String=>Boolean}] the units the class body itself defines, keyed by the
+      #   suffix a synthetic key carries (`"#save"`, `".create"`), each mapped to whether that body
+      #   reaches `super`. Read by {.framework_row} and by nothing else.
+      def synthesize(class_name:, instance_methods:, macros:, uniqueness:, plugin_facts:, own_units: {})
         units = []
         plugin_facts.edges_for(:activerecord_callbacks).each do |edge|
           next unless plugin_facts.descends_from?(class_name, edge.receiver)
 
-          units.concat(active_record_units(class_name, macros, uniqueness))
+          units.concat(active_record_units(class_name, macros, uniqueness, plugin_facts, own_units))
         end
         plugin_facts.edges_for(:perform_now).each do |edge|
           next unless plugin_facts.descends_from?(class_name, edge.receiver)
@@ -110,17 +113,18 @@ module Rigor
       # `save` and friends, edged to the callbacks the class body declared. A trigger with no callbacks and
       # no uniqueness validator is NOT synthesised: an empty unit would put `User#save` in the snapshot for
       # every model in the project and say nothing.
-      def active_record_units(class_name, macros, uniqueness)
+      def active_record_units(class_name, macros, uniqueness, plugin_facts, own_units)
         validation = callbacks(macros, VALIDATION_MACROS)
         save = validation + callbacks(macros, SAVE_MACROS)
         destroy = callbacks(macros, DESTROY_MACROS)
         read = uniqueness ? uniqueness_summary(class_name) : nil
+        context = { plugin_facts: plugin_facts, own_units: own_units }
 
         units = []
-        units.concat(triggers(class_name, SAVE_TRIGGERS, save, read, singleton: false))
-        units.concat(triggers(class_name, SINGLETON_SAVE_TRIGGERS, save, read, singleton: true))
-        units.concat(triggers(class_name, VALIDATION_TRIGGERS, validation, read, singleton: false))
-        units.concat(triggers(class_name, DESTROY_TRIGGERS, destroy, nil, singleton: false))
+        units.concat(triggers(class_name, SAVE_TRIGGERS, save, read, singleton: false, **context))
+        units.concat(triggers(class_name, SINGLETON_SAVE_TRIGGERS, save, read, singleton: true, **context))
+        units.concat(triggers(class_name, VALIDATION_TRIGGERS, validation, read, singleton: false, **context))
+        units.concat(triggers(class_name, DESTROY_TRIGGERS, destroy, nil, singleton: false, **context))
         units
       end
 
@@ -132,11 +136,61 @@ module Rigor
         end
       end
 
-      def triggers(class_name, selectors, targets, read, singleton:)
+      # A synthesised trigger exists only when the class body earned it — see {.active_record_units} — but
+      # once it exists it stands for the whole of `save`, so it carries the framework's own claim about the
+      # selector as well as the callbacks (#440).
+      def triggers(class_name, selectors, targets, read, singleton:, plugin_facts:, own_units:)
         return [] if targets.empty? && read.nil?
 
         edges = targets.map { |target| edge_to(class_name, target) }
-        selectors.map { |selector| unit("#{class_name}#{singleton ? '.' : '#'}#{selector}", edges, read) }
+        selectors.map do |selector|
+          row = framework_row(class_name, selector, singleton, plugin_facts, own_units)
+          unit("#{class_name}#{singleton ? '.' : '#'}#{selector}", edges,
+               declared_bundles(read, row), causes(row))
+        end
+      end
+
+      # What the loaded plugins say `class_name`'s `selector` itself does — `ActiveRecord::Base#save` is
+      # `io.db.write` — read off the very table a call site reads (#440).
+      #
+      # Without it the synthetic unit carried the validator's `SELECT` and nothing else, so a model with a
+      # `before_save` or a uniqueness validator reported `AuthSource#save: ≤ io.db.read`: the write was
+      # attributed at every *call site* and never on the row that names the method, which is the row a
+      # reviewer reads. A `narrow:` row is skipped, because narrowing reads an argument at a call site and
+      # there is no call site here.
+      def framework_row(class_name, selector, singleton, plugin_facts, own_units)
+        return nil if replaced?(own_units, selector, singleton)
+
+        row = plugin_facts.class_row(class_name, singleton, selector)
+        return nil if row.nil? || row.narrow || row.labels.empty?
+
+        row
+      end
+
+      # Whether the class spelled the selector out itself and never reaches `super`. Such a body REPLACED
+      # the framework's implementation, so the framework's claim no longer describes what runs: a
+      # `def save = false` that persists nothing must keep reporting nothing. A body that does reach
+      # `super` keeps the claim, which is the case the exemption exists to not break.
+      def replaced?(own_units, selector, singleton)
+        key = "#{singleton ? '.' : '#'}#{selector}"
+        own_units.key?(key) && !own_units[key]
+      end
+
+      def declared_bundles(read, row)
+        bundles = read ? read.dup : {}
+        bundles[Origin.plugin(row.key)] = row.labels if row
+        bundles
+      end
+
+      # Mirrors {UnitScan#attribute_plugin}: a row may discharge and still taint, and a row from a plugin
+      # the engine does not bundle is a claim that leaves the unit non-exhaustive.
+      def causes(row)
+        return [] if row.nil?
+
+        list = []
+        list << [row.taint, row.key] if row.taint
+        list << ["plugin-attribution", row.key] unless row.discharge?
+        list
       end
 
       def callbacks(macros, names)
@@ -151,8 +205,9 @@ module Rigor
         { Origin.plugin("#{class_name}:uniqueness-validator") => IO_DB_READ }
       end
 
-      def unit(key, edges, declared = nil)
-        [key, Summary.new(declared_bundles: declared || {}), edges]
+      def unit(key, edges, declared = nil, causes = [])
+        summary = Summary.new(declared_bundles: declared || {}, exhaustive: causes.empty?, causes: causes)
+        [key, summary, edges]
       end
 
       def edge_to(class_name, selector)
@@ -160,8 +215,8 @@ module Rigor
                                  self_call: false)
       end
 
-      private_class_method :active_record_units, :mailer_units, :triggers, :callbacks, :uniqueness_summary,
-                           :unit, :edge_to
+      private_class_method :active_record_units, :mailer_units, :triggers, :framework_row, :replaced?,
+                           :declared_bundles, :causes, :callbacks, :uniqueness_summary, :unit, :edge_to
     end
   end
 end

data/lib/rigor/effects/inline_anchor.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+module Rigor
+  module Effects
+    # Maps a position read out of a **synthesized** RBS buffer back onto the Ruby file the author
+    # actually wrote in ([#432](https://github.com/rigortype/rigor/issues/432)).
+    #
+    # An rbs-inline annotation never reaches the envelope reader as the line the author typed. The
+    # plugin hands `RBS::Inline::Writer`'s output to the loader as a `virtual:rbs-inline:<path>.rb`
+    # buffer, and that output is a *fresh document*: bodies are gone, the members it emits are the
+    # signatures rather than the `def`s, and every annotation is re-emitted above its member on a line
+    # of the writer's choosing. The buffer name still names the `.rb`, so a location rendered straight
+    # off `RBS::Location` reads `app/models/change.rb:5` — the right file, and a line number that
+    # belongs to a document nobody has. On a file with a licence header it lands inside the copyright
+    # notice and is not even visibly wrong.
+    #
+    # ## Why the answer is the annotation's own text, matched by ordinal
+    #
+    # There is no line table to consult: upstream's writer emits text and keeps no mapping, and the
+    # synthesized buffer is what the RBS parser saw. What both documents *do* share is the author's own
+    # spelling — `%a{pure}` reaches the buffer verbatim — and their order, because the writer emits
+    # members in source order. So the k-th `%a{pure}` of the buffer is the k-th `%a{pure}` of the `.rb`,
+    # and matching on the ordinal is what keeps a file with several identically-bounded methods from
+    # pointing all of them at the first one. A plain "find the text" search cannot tell them apart, and
+    # a fixed offset would encode one fixture's licence header as if it were a rule.
+    #
+    # Two filters make the two lists comparable:
+    #
+    # - in the buffer, only a line whose own text *is* the annotation counts. The writer also echoes the
+    #   author's comment block above each member, so `# @rbs %a{pure}` appears there too and would
+    #   double every count;
+    # - in the `.rb`, only a comment line counts, so a `%a{…}` inside a string literal or a heredoc is
+    #   never mistaken for a declaration.
+    #
+    # Every step degrades to the buffer line it was given: a `.rb` that cannot be read, a spelling with
+    # no match, a writer that some day stops preserving order. A position one line off is a smaller
+    # harm than a raised exception on a run that had a real finding to report.
+    class InlineAnchor
+      RUBY_EXTENSION = ".rb"
+      private_constant :RUBY_EXTENSION
+
+      # An RBS annotation as the parser sees it: the line's own text, not a comment mentioning one.
+      ANNOTATION_PREFIX = "%a{"
+      private_constant :ANNOTATION_PREFIX
+
+      COMMENT_PREFIX = "#"
+      private_constant :COMMENT_PREFIX
+
+      SPELLING_PATTERN = /%a\{[^}]*\}/
+      private_constant :SPELLING_PATTERN
+
+      # @param path [String] the buffer's readable path, as {SignatureSources.source_path} renders it.
+      # @param buffer [String] the synthesized RBS the position was read out of.
+      # @return [InlineAnchor, nil] nil when `path` is not a Ruby file — a real `.rbs` needs no mapping,
+      #   and its own line numbers are already the ones a reader can open.
+      def self.for(path:, buffer:)
+        return nil unless path.to_s.end_with?(RUBY_EXTENSION)
+
+        new(path: path.to_s, buffer: buffer.to_s)
+      end
+
+      # One-shot form, for a caller that holds a `[path, buffer, line]` triple and no anchor.
+      #
+      # @return [Integer] the `.rb` line, or `buffer_line` unchanged when there is nothing to map.
+      def self.ruby_line(path:, buffer:, buffer_line:, spelling: nil)
+        anchor = self.for(path: path, buffer: buffer)
+        return buffer_line if anchor.nil?
+
+        anchor.line_for(buffer_line, spelling: spelling)
+      end
+
+      def initialize(path:, buffer:)
+        @path = path
+        @buffer = buffer
+        @ruby_lines = nil
+      end
+
+      # @param buffer_line [Integer] 1-based, counting into the synthesized buffer.
+      # @param spelling [String, nil] the annotation's own text (`"%a{pure}"`); read off the buffer line
+      #   when the caller does not already hold it.
+      # @return [Integer] the 1-based line of the same annotation in the Ruby file.
+      def line_for(buffer_line, spelling: nil)
+        spelling = normalize(spelling) || spelling_at(buffer_line)
+        return buffer_line if spelling.nil?
+
+        candidates = ruby_lines.filter_map { |number, text| number if text.include?(spelling) }
+        return buffer_line if candidates.empty?
+
+        candidates[ordinal_of(buffer_line, spelling)] || candidates.first
+      end
+
+      private
+
+      # The spelling as it appears in both documents. Callers hold it as `"%a{#{annotation.string}}"`,
+      # which is already that form; anything else is read for its annotation text or dropped.
+      def normalize(spelling)
+        spelling.to_s[SPELLING_PATTERN]
+      end
+
+      def spelling_at(buffer_line)
+        @buffer.each_line.with_index(1) do |text, number|
+          return text[SPELLING_PATTERN] if number == buffer_line
+        end
+        nil
+      end
+
+      # How many annotations of the same spelling the buffer declares before `buffer_line`. Comment
+      # lines are skipped: the writer echoes the author's `# @rbs %a{…}` above the annotation it
+      # generates, and counting both would land every lookup one match too far down the file.
+      def ordinal_of(buffer_line, spelling)
+        seen = 0
+        @buffer.each_line.with_index(1) do |text, number|
+          break if number >= buffer_line
+
+          stripped = text.lstrip
+          seen += 1 if stripped.start_with?(ANNOTATION_PREFIX) && stripped.include?(spelling)
+        end
+        seen
+      end
+
+      # The Ruby file's comment lines, as `[line number, text]`. Read once, and only for a position that
+      # is already going to be rendered.
+      def ruby_lines
+        @ruby_lines ||= begin
+          File.foreach(@path).with_index(1).filter_map do |text, number|
+            [number, text] if text.lstrip.start_with?(COMMENT_PREFIX)
+          end
+        rescue StandardError
+          [].freeze
+        end
+      end
+    end
+  end
+end

data/lib/rigor/effects/liskov_check.rb

@@ -112,11 +112,13 @@ module Rigor
 
         inherited = envelopes.fetch(ancestor_key)
         own = envelopes[key]
-        position = positions.for(key)
+        # The position is read inside the two collectors, after they know a finding exists: `.for` is
+        # what forces a deferred position table, and an inherited envelope nothing widens must not
+        # cost a whole-project discovery parse.
         if own && !own.top?
-          collect_declared(findings, key, ancestor_key, inherited, own, position)
+          collect_declared(findings, key, ancestor_key, inherited, own, positions)
         else
-          collect_proven(findings, table, key, ancestor_key, inherited, position, apply_tolerated)
+          collect_proven(findings, table, key, ancestor_key, inherited, positions, apply_tolerated)
         end
       end
 
@@ -135,16 +137,19 @@ module Rigor
         nil
       end
 
-      def collect_proven(findings, table, key, ancestor_key, inherited, position, apply_tolerated)
+      def collect_proven(findings, table, key, ancestor_key, inherited, positions, apply_tolerated)
         entry = table[key]
         return if entry.nil?
 
         exceeding = inherited.exceeded_by(apply_tolerated ? entry.undischarged : entry.proven)
+        return if exceeding.empty?
+
+        path, line = positions.for(key)
         exceeding.each do |label|
           trail = PathFinder.shortest(table, symbol: key, label: label)
           findings << Finding.new(
             key: key, label: label, ancestor_key: ancestor_key, ancestor_envelope: inherited,
-            own_envelope: nil, path: position.first, line: position.last,
+            own_envelope: nil, path: path, line: line,
             chain: trail&.chain || [key].freeze, origin: trail&.origin
           )
         end
@@ -152,11 +157,15 @@ module Rigor
 
       # Two authored bounds, compared by subsumption alone. `mutate.local` is tolerated here as it is
       # everywhere, so declaring it under an inherited `%a{pure}` is not a widening.
-      def collect_declared(findings, key, ancestor_key, inherited, own, position)
-        own.bound.to_a.reject { |label| inherited.tolerates?(label) }.each do |label|
+      def collect_declared(findings, key, ancestor_key, inherited, own, positions)
+        widened = own.bound.to_a.reject { |label| inherited.tolerates?(label) }
+        return if widened.empty?
+
+        path, line = positions.for(key)
+        widened.each do |label|
           findings << Finding.new(
             key: key, label: label, ancestor_key: ancestor_key, ancestor_envelope: inherited,
-            own_envelope: own, path: position.first, line: position.last, chain: nil, origin: nil
+            own_envelope: own, path: path, line: line, chain: nil, origin: nil
           )
         end
       end

data/lib/rigor/effects/plugin_facts.rb

@@ -46,9 +46,16 @@ module Rigor
     # models are declared only in RBS gets no plugin attribution and no taint, which is the fail-quiet
     # direction.
     class PluginFacts
-      # How far the superclass walk climbs before giving up. A project hierarchy deeper than this is either
-      # pathological or cyclic, and a cycle is possible in a project's *as-written* table.
-      ANCESTRY_CAP = 24
+      # How many ancestors the walk visits before giving up. It bounds *work*, not correctness: cycles are
+      # already handled by the visited set, and the walk is memoised per class.
+      #
+      # It was 24 while the walk climbed superclasses only, where a project deeper than that is
+      # pathological. Once included modules joined the walk (#456) the number stopped measuring depth and
+      # started measuring breadth, and Rails concerns make breadth ordinary — Mastodon's `Account` includes
+      # 21 modules, so `ActiveRecord::Base` fell off the end of a 24-entry chain and every `Account#save`
+      # silently lost its `io.db.write`. A cap that can be reached by ordinary code is a correctness bug
+      # wearing a budget's clothes.
+      ANCESTRY_CAP = 128
 
       NO_ROWS = {}.freeze
       private_constant :NO_ROWS
@@ -67,18 +74,21 @@ module Rigor
       Edge = Data.define(:target, :receiver, :selector, :plugin_id)
 
       def self.empty
-        @empty ||= new(contributions: [], superclasses: NO_ROWS)
+        @empty ||= new(contributions: [], superclasses: NO_ROWS, includes: NO_ROWS)
       end
 
       # @param plugin_registry [Rigor::Plugin::Registry, nil]
       # @param superclasses [Hash{String=>String,Array<String>}] the project's as-written superclass table
       #   (`Scope::DiscoveryIndex#discovered_superclasses`). Empty is legal and simply means no row matches
       #   through inheritance.
-      def self.build(plugin_registry, superclasses: NO_ROWS)
+      # @param includes [Hash{String=>Array<String>}] the project's as-written include / prepend table
+      #   (`Scope::DiscoveryIndex#discovered_includes`), for the frameworks whose contract is a module
+      #   rather than a base class (#456).
+      def self.build(plugin_registry, superclasses: NO_ROWS, includes: NO_ROWS)
         contributions = plugin_registry&.effect_contributions || []
         return empty if contributions.empty?
 
-        new(contributions: contributions, superclasses: superclasses)
+        new(contributions: contributions, superclasses: superclasses, includes: includes)
       rescue StandardError
         empty
       end
@@ -94,7 +104,7 @@ module Rigor
       # Every `effect_entry_points:` preset across the loaded set, in registration order.
       attr_reader :entry_points
 
-      def initialize(contributions:, superclasses:)
+      def initialize(contributions:, superclasses:, includes: NO_ROWS)
         @warnings = []
         @class_rows = {}
         @path_rows = {}
@@ -103,8 +113,10 @@ module Rigor
         @edges = []
         @labels_by_owner = {}
         @entry_points = []
+        @declared_ancestry = {}
         contributions.each { |contribution| absorb(contribution) }
         @superclasses = superclasses || NO_ROWS
+        @includes = includes || NO_ROWS
         @ancestry = {}
         @digest = compute_digest
         finalize
@@ -220,6 +232,27 @@ module Rigor
                              plugin_id: contribution.id)
         end
         @entry_points.concat(contribution.entry_points)
+        contribution.ancestry.each { |entry| absorb_ancestry(contribution, entry) }
+      end
+
+      # ADR-103 WD17 (#465) — an ancestry edge the plugin's gem introduces, which the project's own
+      # source never writes.
+      #
+      # **Bundled plugins only**, and this is the one place it is enforced. A claim carries no labels of
+      # its own, which is what makes it look harmless: what it does is make *other* plugins' rows
+      # reachable, so a third-party plugin asserting `Foo < ActiveRecord::Base` would pull
+      # rigor-activerecord's first-party discharging rows onto `Foo`. The grant is the same fact
+      # {#discharge_granted?} reads — that the engine bundles this plugin — and the refusal is warned
+      # about rather than silent, because a claim that quietly did nothing would read to its author as
+      # the rows having vanished.
+      def absorb_ancestry(contribution, entry)
+        unless contribution.discharge_allowed
+          @warnings << "plugin #{contribution.id.inspect} is not bundled with the engine; its " \
+                       "#{entry.child} < #{entry.parent} ancestry claim is ignored"
+          return
+        end
+
+        (@declared_ancestry[entry.child] ||= []) << entry.parent
       end
 
       # ADR-103 WD2 — a plugin that asked to own a framework root and is not one the engine bundles keeps
@@ -259,16 +292,31 @@ module Rigor
         false
       end
 
-      # `[class_name, …ancestors]`, memoised per class. Cycle-guarded and capped: the table is *as written*,
-      # so a project can spell one that loops.
+      # `[class_name, …ancestors]`, memoised per class. Cycle-guarded and capped: the tables are *as
+      # written*, so a project can spell an ancestry that loops.
+      #
+      # Included and prepended modules are walked beside the superclass, nearer first, because that is
+      # Ruby's own lookup order and because a framework's contract is as often a module as a base class:
+      # a Sidekiq worker is `class TriggerWebhookWorker; include Sidekiq::Job`, with no base class at all,
+      # so a superclass-only walk could not match a row about it however the plugin spelled one (#456).
+      # `ExpressionTyper#enqueue_ancestors` already resolves a self-call this way; the two tables
+      # disagreeing about what an ancestor is was the bug.
       def ancestry(class_name)
         @ancestry[class_name] ||= begin
           chain = []
           seen = Set.new
-          current = class_name
-          while current && seen.add?(current) && chain.length < ANCESTRY_CAP
+          queue = [class_name]
+          until queue.empty? || chain.length >= ANCESTRY_CAP
+            current = queue.shift
+            next unless current && seen.add?(current)
+
             chain << current
-            current = Array(@superclasses[current]).first
+            queue.concat(Array(@includes[current]).compact)
+            parent = Array(@superclasses[current]).first
+            queue << parent if parent
+            # Last, so a project's own declaration always wins the first-match race against a plugin's
+            # claim about a gem (#465).
+            queue.concat(Array(@declared_ancestry[current]))
           end
           chain.freeze
         end
@@ -281,7 +329,8 @@ module Rigor
                           .map { |singleton| [singleton, sorted(@class_rows[singleton])] },
           sorted(@path_rows), sorted(@self_rows), sorted(@result_rows),
           @edges.map { |edge| [edge.target.to_s, edge.receiver, edge.selector.to_s, edge.plugin_id] }.sort,
-          @entry_points.map(&:to_h).sort_by { |preset| preset["name"] }
+          @entry_points.map(&:to_h).sort_by { |preset| preset["name"] },
+          @declared_ancestry.sort.map { |child, parents| [child, parents.sort] }
         ]
         Digest::SHA256.hexdigest(payload.inspect)
       end

data/lib/rigor/effects/propagator.rb

@@ -53,23 +53,49 @@ module Rigor
         return EffectTable.empty if collection.summaries.empty?
 
         summaries = collection.summaries
-        edges = resolve_edges(collection)
         state = seed(summaries, discharge)
+        edges = resolve_edges(collection, state)
         iterate(state, edges)
         EffectTable.new(build_entries(summaries, edges, state))
       rescue StandardError
         EffectTable.empty
       end
 
-      # `{caller_key => [callee_key]}`, sorted and de-duplicated.
-      def resolve_edges(collection)
+      # `{caller_key => [callee_key]}`, sorted and de-duplicated. Seeds the `unresolved-super` taint in
+      # the same pass, because whether a `super` resolved is exactly what this resolution answers.
+      def resolve_edges(collection, state)
         index = Index.new(collection)
         collection.edges.each_with_object({}) do |(caller_key, list), out|
-          targets = list.flat_map { |edge| index.targets_for(edge) }.uniq.sort
+          targets = list.flat_map do |edge|
+            resolved = index.targets_for(edge)
+            taint_unresolved_super(state, caller_key, edge) if edge.super_call && resolved.empty?
+            resolved
+          end.uniq.sort
           out[caller_key] = targets.freeze unless targets.empty?
         end
       end
 
+      # A `super` the project's own ancestry does not answer — the implementation is in a gem, in Ruby's
+      # core, or in a module prepended at run time — is the case the taint exists for (#446). Silence
+      # would be the one thing the effect model must never say: that the list is complete when a call in
+      # the body was not read. An unresolved ORDINARY edge is dropped instead, because most such calls
+      # are inherited ones the catalogue simply has no row for and the site's own taint was already
+      # decided from the typer's verdict; a `super` has no site verdict to fall back on, and it always
+      # dispatches to something.
+      #
+      # Decided here rather than in the collector because only the merged ancestry can say whether the
+      # parent resolves, and written into the SEED rather than into the direct summary so the fixpoint
+      # carries it to this method's callers exactly as it carries any other cause. A snapshot's
+      # `methods:` table records direct summaries and so does not show it; `reach:`, the report and the
+      # judgment all read the closure and do.
+      def taint_unresolved_super(state, caller_key, edge)
+        entry = state[caller_key]
+        return if entry.nil?
+
+        entry[:exhaustive] = false
+        entry[:causes] << ["unresolved-super", edge.selector].freeze
+      end
+
       # Causes are carried as a Set through the fixpoint and flattened back to a sorted Array in
       # {build_entries}. A Set is what {absorb} needs: unioning one along an edge must cost the source's
       # size and allocate NOTHING when it adds nothing, and the array-concat-and-uniq it replaces
@@ -170,8 +196,8 @@ module Rigor
         end
       end
 
-      private_class_method :resolve_edges, :seed, :iterate, :reverse_edges, :absorb, :join_lane,
-                           :build_entries
+      private_class_method :resolve_edges, :taint_unresolved_super, :seed, :iterate, :reverse_edges,
+                           :absorb, :join_lane, :build_entries
 
       # The class graph a run's collections describe, and the edge resolution over it. Built once per
       # propagation; every lookup is a Hash read.
@@ -189,25 +215,43 @@ module Rigor
         # Every project method key `edge` may reach: the definition its ancestry resolves to, plus every
         # override of the same selector in a project subclass of the receiver's class.
         #
-        # Memoised on `(receiver class, kind, selector)` — the answer depends on nothing else, and one
-        # such triple is asked for once per call site in the project. `ApplicationRecord#save` alone is
+        # Memoised on `(receiver class, kind, selector, super?)` — the answer depends on nothing else, and
+        # one such tuple is asked for once per call site in the project. `ApplicationRecord#save` alone is
         # thousands of sites on a Rails app, each of which used to re-walk the whole subclass forest.
         def targets_for(edge)
-          @targets[[edge.receiver_class, edge.kind, edge.selector]] ||= begin
+          @targets[[edge.receiver_class, edge.kind, edge.selector, edge.super_call]] ||= begin
             separator = edge.kind == :singleton ? "." : "#"
-            targets = []
-            owner = resolve_owner(edge.receiver_class, separator, edge.selector)
-            targets << owner if owner
-            descendant_closure(edge.receiver_class).each do |subclass|
-              key = "#{subclass}#{separator}#{edge.selector}"
-              targets << key if @summaries.key?(key)
-            end
-            targets.freeze
+            edge.super_call ? super_targets(edge, separator) : call_targets(edge, separator)
           end
         end
 
         private
 
+        def call_targets(edge, separator)
+          targets = []
+          owner = resolve_owner(edge.receiver_class, separator, edge.selector)
+          targets << owner if owner
+          descendant_closure(edge.receiver_class).each do |subclass|
+            key = "#{subclass}#{separator}#{edge.selector}"
+            targets << key if @summaries.key?(key)
+          end
+          targets.freeze
+        end
+
+        # A `super` reaches **one** definition, and the closed-world override join every other edge gets
+        # is deliberately absent from it (#446). `super` in `C#m` dispatches into the ancestry above `C`
+        # in the receiver's chain, and a subclass of `C` is never in it however the receiver was
+        # constructed — so joining `D#m` would put a proven label on `C#m` that no execution of `C#m` can
+        # produce. Ruby's lack of `final` is the argument for the join at an ordinary call site and says
+        # nothing here.
+        def super_targets(edge, separator)
+          target = resolve_super(edge.receiver_class, separator, edge.selector)
+          target ? [target].freeze : NO_TARGETS
+        end
+
+        NO_TARGETS = [].freeze
+        private_constant :NO_TARGETS
+
         # The transitive subclass closure, memoised per class. A deep hierarchy's root is asked for it
         # once, not once per selector reaching it.
         def descendant_closure(class_name)
@@ -220,8 +264,24 @@ module Rigor
         # enqueued and the most-qualified one comes first, so the right constant wins the race and a
         # spelling that names nothing simply matches no key.
         def resolve_owner(class_name, separator, selector)
-          seen = Set.new
-          queue = [class_name]
+          walk_ancestors([class_name], Set.new, separator, selector)
+        end
+
+        # Where `super` from `class_name#selector` lands: the same ancestor walk, started one step up —
+        # the modules the class includes, then its superclass chain — with the class itself already in
+        # `seen`, because a method never `super`s into itself.
+        #
+        # The includes are instance-side only. `include M` puts `M#m` between the class and its
+        # superclass, which is exactly where `super` looks, while `M.m` is a singleton method `include`
+        # never contributes; a singleton `super` that really does reach a module went through `extend` or
+        # a `class << self` include, neither of which is collected, so it resolves to nothing and taints.
+        def resolve_super(class_name, separator, selector)
+          queue = separator == "#" ? @includes.fetch(class_name, []).dup : []
+          queue.concat(@superclasses.fetch(class_name, []))
+          walk_ancestors(queue, Set.new([class_name]), separator, selector)
+        end
+
+        def walk_ancestors(queue, seen, separator, selector)
           until queue.empty?
             current = queue.shift
             next if current.nil? || !seen.add?(current)

data/lib/rigor/effects/registry.rb

@@ -74,14 +74,16 @@ module Rigor
         new(
           vocabulary_version: raw.fetch("vocabulary", 0),
           labels: raw.fetch("labels", nil) || [],
-          retired: raw.fetch("retired", nil) || {}
+          retired: raw.fetch("retired", nil) || {},
+          descriptions: raw.fetch("descriptions", nil) || {}
         )
       end
 
       attr_reader :vocabulary_version
 
-      def initialize(vocabulary_version:, labels:, retired: {})
+      def initialize(vocabulary_version:, labels:, retired: {}, descriptions: {})
         @vocabulary_version = vocabulary_version
+        @descriptions = descriptions.to_h { |root, text| [root.to_s, text.to_s.gsub(/\s+/, " ").strip] }.freeze
         @labels = labels.map(&:to_s).uniq.sort.freeze
         @known = build_known(@labels)
         @roots = @known.select { |label| Label.parent(label).nil? }.sort.freeze
@@ -96,6 +98,10 @@ module Rigor
       # The roots of the vocabulary — the outermost segments {#with} treats as already owned.
       attr_reader :roots
 
+      # One line per root, from the data file's `descriptions:` — what `rigor effects --list-labels`
+      # prints beside a root (#429). A root nothing describes (a plugin's, a project's) has no entry.
+      attr_reader :descriptions
+
       # Whether the vocabulary recognises `label`: an exact row, or an ancestor of one. A declared
       # `io` is recognised because `io.net` exists, so a bound may name an interior node the data
       # file never spells out on its own line.
@@ -142,7 +148,8 @@ module Rigor
 
           check_ownership(label, owner)
         end
-        self.class.new(vocabulary_version: @vocabulary_version, labels: @labels + added, retired: @retired)
+        self.class.new(vocabulary_version: @vocabulary_version, labels: @labels + added, retired: @retired,
+                       descriptions: @descriptions)
       end
 
       private