rigortype 0.3.2 → 0.3.4

data/lib/rigor/effects/plugin_facts.rb

@@ -0,0 +1,335 @@
+# frozen_string_literal: true
+
+require "digest"
+
+require_relative "entry_points"
+require_relative "label_set"
+require_relative "registry"
+
+module Rigor
+  module Effects
+    # The loaded plugins' effect contributions, compiled once per process into the tables the scan and the
+    # snapshot read (ADR-103 WD2 / WD6 / WD10 / WD14; #387).
+    #
+    # A plugin's manifest states its contribution declaratively — `effect_labels:`, `effect_attributions:`,
+    # `effect_edges:`, `effect_entry_points:`, all frozen value objects. Nothing here re-reads a manifest at
+    # scan time: the per-call lookup is two Hash reads and, for a class-name row, a walk up a superclass
+    # table that is a Hash read per level.
+    #
+    # **Nothing builds one unless collection is on.** {Plugin::Registry#effect_contributions} is itself
+    # lazy — a plugin MAY compute its rows from project facts, and rigor-activejob does — and this class is
+    # what turns the result into indices. {.build} is called from exactly one place on each side of the fork
+    # boundary, behind `configuration.effects_enabled?`, so a `rigor check` with no `effects:` block neither
+    # allocates one nor lets a plugin read a file for it.
+    #
+    # ## Two matching rules, because the framework has two shapes
+    #
+    # A **class-name** row (`ActiveRecord::Base#save`) matches through the project's inheritance chain:
+    # `user.save` on a `User < ApplicationRecord < ActiveRecord::Base` is the whole point, and matching the
+    # exact owner (which is what {Catalog} does, correctly, for Ruby's core) would find nothing. The chain
+    # walked is the **project's own** superclass table — the cross-file discovery pre-pass's
+    # `discovered_superclasses`, the same table `ExpressionTyper` walks for an unresolved implicit-self
+    # call. It stops where the project stops, which is exactly right: `ApplicationRecord < ActiveRecord::Base`
+    # is a line in `app/models/application_record.rb`, and a class that never names a framework base in
+    # project source is not one.
+    #
+    # A **receiver-path** row (`Rails.cache#read`) matches the receiver *expression* as written. `Rails.cache`
+    # returns an adapter-dependent object by design — memory, Redis, the filesystem — so there is no receiver
+    # class for a class-name row to key on, and the only stable handle is the path the programmer typed.
+    #
+    # ## What is deliberately not consulted
+    #
+    # The RBS ancestor chain. A gem's shipped signatures do carry `class User < ApplicationRecord`-shaped
+    # ancestry when the project generates RBS for its models, but reading it here would make a row's reach a
+    # function of whether the project happens to run `rbs prototype` — a plugin contribution that appears and
+    # disappears with an unrelated tool. The project's own `class … <` lines are the fact; a project whose
+    # 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
+
+      NO_ROWS = {}.freeze
+      private_constant :NO_ROWS
+
+      # One compiled attribution row.
+      #
+      # `discharge` is the RESOLVED grant, not the manifest's request: {.build} has already demoted a
+      # non-first-party plugin's `true` to `false` and recorded a warning, so nothing downstream has to
+      # re-ask who may discharge.
+      Row = Data.define(:key, :labels, :narrow, :discharge, :within, :taint, :plugin_id) do
+        def discharge? = discharge
+      end
+
+      # One compiled framework-edge strategy: the base class a plugin pointed the engine at, and which
+      # plugin pointed.
+      Edge = Data.define(:target, :receiver, :selector, :plugin_id)
+
+      def self.empty
+        @empty ||= new(contributions: [], superclasses: 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)
+        contributions = plugin_registry&.effect_contributions || []
+        return empty if contributions.empty?
+
+        new(contributions: contributions, superclasses: superclasses)
+      rescue StandardError
+        empty
+      end
+
+      # Human-readable notes about contributions that were accepted only in part — a third-party plugin's
+      # `discharge: true` demoted, a label root refused. Surfaced by `rigor effects`; never a diagnostic,
+      # because a plugin the user chose is not the project's mistake to be flagged for.
+      attr_reader :warnings
+
+      # `{owner => [labels]}` — what {#extend_registry} folds into the run's vocabulary.
+      attr_reader :labels_by_owner
+
+      # Every `effect_entry_points:` preset across the loaded set, in registration order.
+      attr_reader :entry_points
+
+      def initialize(contributions:, superclasses:)
+        @warnings = []
+        @class_rows = {}
+        @path_rows = {}
+        @self_rows = {}
+        @result_rows = {}
+        @edges = []
+        @labels_by_owner = {}
+        @entry_points = []
+        contributions.each { |contribution| absorb(contribution) }
+        @superclasses = superclasses || NO_ROWS
+        @ancestry = {}
+        @digest = compute_digest
+        finalize
+      end
+
+      # A content digest of every compiled plugin fact — labels, attributions, edges and presets, each with
+      # the plugin that contributed it. {Identity} folds it in, so upgrading a plugin whose rows moved
+      # invalidates the effects slot exactly as a re-audited `data/effects/core.yml` row does. Deliberately
+      # independent of the project's superclass table, which is a *project* input the diagnostics identity
+      # already covers.
+      attr_reader :digest
+
+      def empty?
+        !attributions? && @edges.empty? && @labels_by_owner.empty? && @entry_points.empty?
+      end
+
+      # Whether any attribution row exists at all — the scan's fast path, asked once per call site.
+      def attributions?
+        !@class_rows.empty? || !@path_rows.empty? || !@self_rows.empty? || !@result_rows.empty?
+      end
+
+      def edges?
+        !@edges.empty?
+      end
+
+      # The row colouring `owner`'s `selector`, found on `owner` itself or on a project ancestor of it.
+      #
+      # @param owner [String, nil] the receiver's class name as the syntax or the typer named it
+      # @param singleton [Boolean] whether the call is `Owner.selector`
+      # @return [Row, nil]
+      def class_row(owner, singleton, selector)
+        return nil if owner.nil? || @class_rows.empty?
+
+        bucket = @class_rows[singleton]
+        return nil if bucket.nil?
+
+        ancestry(owner).each do |candidate|
+          row = bucket[candidate]&.[](selector)
+          return row if row
+        end
+        nil
+      end
+
+      # The row colouring `path`'s `selector`, where `path` is a receiver expression (`"Rails.cache"`).
+      # Exact — a receiver path names one object and has no ancestry to walk.
+      def path_row(path, selector)
+        return nil if path.nil? || @path_rows.empty?
+
+        @path_rows[path]&.[](selector)
+      end
+
+      # The row colouring `path`'s `selector` for a receiver rooted at implicit self (`"self.flash.now"`),
+      # inside a unit whose class is `owner_class`. Answers nil when the row's `within:` class is not on
+      # `owner_class`'s project ancestry — a receiver-less `session` outside a controller is a different
+      # `session`.
+      def self_path_row(path, selector, owner_class)
+        return nil if path.nil? || @self_rows.empty?
+
+        row = @self_rows[path]&.[](selector)
+        return nil if row.nil?
+        return nil unless descends_from?(owner_class, row.within)
+
+        row
+      end
+
+      # The row colouring `selector` on the RESULT of a call to `producer` (or to a project ancestor of it):
+      # `UserMailer.welcome(u).deliver_now`, `WelcomeJob.set(wait: 1.hour).perform_later`. The lazy object
+      # in between has no declared type; the class that made it is written in the source.
+      def result_row(producer, selector)
+        return nil if producer.nil? || @result_rows.empty?
+
+        ancestry(producer).each do |candidate|
+          row = @result_rows[candidate]&.[](selector)
+          return row if row
+        end
+        nil
+      end
+
+      # The framework-edge strategies of one kind, e.g. every `:activerecord_callbacks` base class the
+      # loaded plugins named.
+      def edges_for(target)
+        @edges.select { |edge| edge.target == target }
+      end
+
+      # Whether `class_name` is `ancestor`, or reaches it through the project's own `class … <` lines.
+      def descends_from?(class_name, ancestor)
+        return false if class_name.nil?
+
+        ancestry(class_name).include?(ancestor)
+      end
+
+      # `registry` extended with every plugin's `effect_labels:`, each under its own owner so
+      # {Registry#with} enforces root ownership per plugin rather than for the set as a whole. A refusal is
+      # recorded as a warning and that plugin's labels are dropped; the rest of the run keeps its
+      # vocabulary, because one plugin overreaching must not un-name another's labels.
+      def extend_registry(registry)
+        @labels_by_owner.each do |owner, labels|
+          registry = registry.with(labels: labels, owner: owner)
+        rescue Registry::Error => e
+          @warnings << "effect labels from #{owner.inspect} were not registered: #{e.message}"
+        end
+        registry
+      end
+
+      private
+
+      def absorb(contribution)
+        note_root_demotion(contribution)
+        (@labels_by_owner[contribution.owner] ||= []).concat(contribution.labels)
+        contribution.attributions.each { |entry| absorb_attribution(contribution, entry) }
+        contribution.edges.each do |entry|
+          @edges << Edge.new(target: entry.target, receiver: entry.receiver, selector: entry.method,
+                             plugin_id: contribution.id)
+        end
+        @entry_points.concat(contribution.entry_points)
+      end
+
+      # ADR-103 WD2 — a plugin that asked to own a framework root and is not one the engine bundles keeps
+      # the root named after itself. Worth saying out loud: the labels still register, just under a
+      # different root, and a silent rename would look to the author like the labels vanished.
+      def note_root_demotion(contribution)
+        return if contribution.requested_root.nil? || contribution.requested_root == contribution.owner
+
+        @warnings << "plugin #{contribution.id.inspect} is not bundled with the engine and may not open " \
+                     "the effect-label root #{contribution.requested_root.inspect}; its labels open " \
+                     "#{contribution.owner.inspect} instead"
+      end
+
+      def absorb_attribution(contribution, entry)
+        row = Row.new(key: entry.key, labels: LabelSet.new(entry.labels), narrow: entry.narrow,
+                      discharge: discharge_granted?(contribution, entry), within: entry.within,
+                      taint: entry.taint, plugin_id: contribution.id)
+        (bucket_for(entry)[entry.receiver] ||= {})[entry.method.to_s] = row
+      end
+
+      # Which index a row lands in, from its receiver spelling.
+      def bucket_for(entry)
+        return @self_rows if entry.self_path?
+        return @path_rows if entry.receiver_path?
+        return @result_rows if entry.on_result
+
+        @class_rows[entry.singleton] ||= {}
+      end
+
+      # ADR-103 WD6 — discharge is a grant, and the granting fact is "the engine bundles this plugin".
+      def discharge_granted?(contribution, entry)
+        return false unless entry.discharge
+        return true if contribution.discharge_allowed
+
+        @warnings << "plugin #{contribution.id.inspect} is not bundled with the engine; its " \
+                     "#{entry.key} attribution does not discharge the call site's taint"
+        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.
+      def ancestry(class_name)
+        @ancestry[class_name] ||= begin
+          chain = []
+          seen = Set.new
+          current = class_name
+          while current && seen.add?(current) && chain.length < ANCESTRY_CAP
+            chain << current
+            current = Array(@superclasses[current]).first
+          end
+          chain.freeze
+        end
+      end
+
+      def compute_digest
+        payload = [
+          @labels_by_owner.sort.map { |owner, labels| [owner, labels.sort] },
+          @class_rows.keys.sort_by { |singleton| singleton ? 1 : 0 }
+                          .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"] }
+        ]
+        Digest::SHA256.hexdigest(payload.inspect)
+      end
+
+      # ADR-103 WD14 — `effects.snapshot.reach: [rails]` adopts a preset BY NAME, so the names have to be
+      # registered somewhere between plugin load and snapshot build. Here is that somewhere: this object is
+      # built once per process from the loaded plugin set, which is exactly the condition the registration
+      # needs. {EntryPoints.register} is idempotent for an identical glob set, so a second run in one
+      # process is a no-op; two plugins claiming one name with DIFFERENT globs is a genuine conflict and
+      # becomes a warning rather than taking the run down over a `reach:` key nobody may have used.
+      def register_entry_points
+        return if @entry_points.empty?
+
+        EntryPoints.register_all(@entry_points)
+      rescue EntryPoints::Error => e
+        @warnings << "entry-point preset not registered: #{e.message}"
+      end
+
+      def sorted(bucket)
+        bucket.sort.map do |receiver, rows|
+          [receiver,
+           rows.sort.map do |selector, row|
+             [selector, row.labels.to_a, row.narrow, row.discharge, row.within, row.taint]
+           end]
+        end
+      end
+
+      def finalize
+        @class_rows.each_value { |bucket| bucket.each_value(&:freeze) }
+        @class_rows.each_value(&:freeze)
+        @class_rows.freeze
+        @path_rows.each_value(&:freeze)
+        @path_rows.freeze
+        @self_rows.each_value(&:freeze)
+        @self_rows.freeze
+        @result_rows.each_value(&:freeze)
+        @result_rows.freeze
+        @edges.freeze
+        @labels_by_owner.each_value(&:uniq!)
+        @labels_by_owner.reject! { |_, labels| labels.empty? }
+        @labels_by_owner.freeze
+        @entry_points.freeze
+        register_entry_points
+        # `@warnings` and `@ancestry` stay mutable: the first collects the registry-extension refusals that
+        # can only be known when a vocabulary is folded, and the second is a per-process memo. The object is
+        # therefore not frozen — it is process-local by construction (each fork-pool worker builds its own),
+        # and nothing marshals it.
+      end
+    end
+  end
+end

data/lib/rigor/effects/propagator.rb

@@ -0,0 +1,275 @@
+# frozen_string_literal: true
+
+require_relative "discharge"
+require_relative "effect_table"
+require_relative "file_collection"
+
+module Rigor
+  module Effects
+    # Closes a run's collected summaries over the call graph (ADR-103 WD12).
+    #
+    # Two jobs, in order:
+    #
+    # 1. **Resolve edges.** The collector records a call as `(receiver class, kind, selector)`; a file
+    #    cannot say which definition that reaches, because the class graph spans the project. Here the
+    #    merged ancestry resolves it — the receiver's own class first, then its includes, then its
+    #    superclass chain — and then the **closed world** joins every project-known override of the same
+    #    selector below the receiver's class (ADR-103 WD4: Ruby has no `final`, and the analyzer already
+    #    takes this posture for types). A call that resolves to nothing in the project is dropped, not
+    #    tainted: the taint for an unresolvable call was already decided per site, from the typer's own
+    #    verdict.
+    # 2. **Reach a fixpoint.** Proven labels join along edges, the exhaustiveness bit ANDs, and causes
+    #    union. The lattice is finite (label sets over a closed vocabulary × one bit × a closed cause
+    #    enum) and every step is monotone, so iteration terminates on its own — a recursive or mutually
+    #    recursive cycle simply converges, and no recursion cap is needed or wanted here.
+    #
+    # Propagation is graph-only: it reads no source, types nothing, and touches no `Scope`. It is
+    # fail-soft as a whole — an exception yields the empty table rather than failing the run.
+    #
+    # **Three label lanes, one fixpoint** (#385), each monotone and each joined along the same edges:
+    #
+    # - `proven` — what the analyzer established.
+    # - `undischarged` — the same closure computed from each unit's *undischarged* direct bundles, i.e.
+    #   with every origin bundle `effects.tolerated:` discharges dropped at the seed ({Discharge}).
+    #   Per-origin discharge needs nothing more than that: an origin belongs to exactly one unit's direct
+    #   summary, so the transitive union of surviving bundles IS the closure of the seeded ones, and the
+    #   judgment never has to materialise a per-method set of transitive origins. With no `tolerated:`
+    #   list the policy is inert, the seed is identical, and the lane costs one `equal?`-true join.
+    # - `declared` — the `≤` lane. It travels call edges **exactly as the proven lane does** (ADR-103
+    #   WD1): a controller two hops above an attributed `Net::HTTP.get` reads `≤ io.net.http`, not merely
+    #   "and possibly more". It is joined into itself and never into `proven`, which is the whole
+    #   separation — a claim stays a claim however far it propagates.
+    module Propagator
+      NO_EDGES = [].freeze
+      private_constant :NO_EDGES
+
+      module_function
+
+      # @param collection [FileCollection] the run's merged per-file collections
+      # @param discharge [Discharge] the `effects.tolerated:` policy the undischarged lane is computed
+      #   under; {Discharge.none} makes the two lanes equal.
+      # @return [EffectTable]
+      def propagate(collection, discharge: Discharge.none)
+        return EffectTable.empty if collection.summaries.empty?
+
+        summaries = collection.summaries
+        edges = resolve_edges(collection)
+        state = seed(summaries, discharge)
+        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)
+        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
+          out[caller_key] = targets.freeze unless targets.empty?
+        end
+      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
+      # allocated twice on every visit of every edge.
+      def seed(summaries, discharge)
+        summaries.transform_values do |summary|
+          {
+            proven: summary.proven,
+            undischarged: discharge.inert? ? summary.proven : discharge.undischarged(summary.bundles),
+            declared: summary.declared,
+            exhaustive: summary.exhaustive?, causes: Set.new(summary.causes)
+          }
+        end
+      end
+
+      # A worklist to a fixpoint. `state[key]` changing can only change the methods that CALL `key`, so a
+      # pass re-visits exactly those and the round-robin over the whole table is gone — that walk cost
+      # O(passes × edges) and the passes are the graph's depth.
+      #
+      # Each pass still runs in sorted key order, so the answer does not depend on Hash insertion order
+      # and a pooled run agrees with a sequential one bit for bit. (The lattice is finite and every step
+      # monotone, so the least fixpoint is unique and visit order cannot change it; the sorted pass keeps
+      # the *work* reproducible too.)
+      def iterate(state, edges)
+        order = state.keys.sort
+        callers = reverse_edges(edges)
+        pending = nil
+
+        loop do
+          dirty = nil
+          order.each do |key|
+            next if pending && !pending.include?(key)
+
+            list = edges[key]
+            next if list.nil?
+
+            changed = false
+            list.each { |callee| changed = true if absorb(state, key, callee) }
+            next unless changed
+
+            (dirty ||= Set.new).merge(callers[key]) if callers.key?(key)
+          end
+          break if dirty.nil?
+
+          pending = dirty
+        end
+      end
+
+      # `{callee_key => [caller_key]}` — who has to be re-visited when a key's closure moves.
+      def reverse_edges(edges)
+        edges.each_with_object({}) do |(caller_key, list), out|
+          list.each { |callee| (out[callee] ||= []) << caller_key }
+        end
+      end
+
+      def absorb(state, key, callee)
+        target = state[key]
+        source = state[callee]
+        return false if source.nil? || target.equal?(source)
+
+        # Each lane is named literally rather than looped over an array: this runs once per edge per
+        # visit, and a literal array of lane names would allocate one per call for nothing.
+        changed = join_lane(target, source, :proven)
+        changed = true if join_lane(target, source, :undischarged)
+        changed = true if join_lane(target, source, :declared)
+        if target[:exhaustive] && !source[:exhaustive]
+          target[:exhaustive] = false
+          changed = true
+        end
+        causes = target[:causes]
+        source[:causes].each { |cause| changed = true if causes.add?(cause) }
+        changed
+      end
+
+      # Joins one label lane in place along an edge, answering whether it moved. {LabelSet#join} returns
+      # the receiver untouched when the source adds nothing, so a converged region costs a comparison and
+      # no allocation at all.
+      def join_lane(target, source, lane)
+        joined = target[lane].join(source[lane])
+        moved = joined != target[lane]
+        target[lane] = joined if moved
+        moved
+      end
+
+      def build_entries(summaries, edges, state)
+        summaries.each_with_object({}) do |(key, summary), out|
+          closed = state.fetch(key)
+          out[key] = EffectTable::Entry.new(
+            key: key,
+            direct: summary,
+            proven: closed[:proven],
+            undischarged: closed[:undischarged],
+            declared: closed[:declared],
+            exhaustive: closed[:exhaustive],
+            causes: closed[:causes].sort_by { |cause, detail| [cause, detail.to_s] }.freeze,
+            edges: edges.fetch(key, NO_EDGES)
+          )
+        end
+      end
+
+      private_class_method :resolve_edges, :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.
+      class Index
+        def initialize(collection)
+          @summaries = collection.summaries
+          @superclasses = collection.superclasses
+          @includes = collection.includes
+          @classes = build_classes(collection)
+          @descendants = build_descendants(collection.superclasses)
+          @descendant_closures = {}
+          @targets = {}
+        end
+
+        # 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
+        # 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
+            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
+          end
+        end
+
+        private
+
+        # 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)
+          @descendant_closures[class_name] ||= descendants_of(class_name).freeze
+        end
+
+        # Ancestry order mirrors the engine's: the class itself, the modules it includes, then its
+        # superclass, recursively. Cycle-guarded, because a project may declare one. Ancestry names
+        # arrive as as-written candidate lists (see `Scanner#lexical_candidates`); every candidate is
+        # 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]
+          until queue.empty?
+            current = queue.shift
+            next if current.nil? || !seen.add?(current)
+
+            key = "#{current}#{separator}#{selector}"
+            return key if @summaries.key?(key)
+
+            queue.concat(@includes.fetch(current, []))
+            queue.concat(@superclasses.fetch(current, []))
+          end
+          nil
+        end
+
+        def descendants_of(class_name)
+          collected = []
+          queue = @descendants.fetch(class_name, []).dup
+          seen = Set.new
+          until queue.empty?
+            current = queue.shift
+            next unless seen.add?(current)
+
+            collected << current
+            queue.concat(@descendants.fetch(current, []))
+          end
+          collected
+        end
+
+        # The subclass index the closed-world override join walks. Unlike the ancestor walk, this one
+        # must pick **one** parent per child: enqueuing every candidate would let `A::Base` and `B::Base`
+        # share the short spelling `Base` and join an unrelated class's override into the proven lane.
+        # The most-qualified candidate the project actually defines wins; a child whose parent is outside
+        # the project keeps its first (most-qualified) spelling and simply matches nothing.
+        def build_descendants(superclasses)
+          superclasses.each_with_object({}) do |(child, candidates), out|
+            parent = candidates.find { |candidate| @classes.include?(candidate) } || candidates.first
+            (out[parent] ||= []) << child
+          end
+        end
+
+        # Every class name the project defines a method on — the evidence `build_descendants` resolves an
+        # as-written superclass against.
+        def build_classes(collection)
+          collection.summaries.each_key.with_object(Set.new) do |key, out|
+            index = key.index("#") || key.index(".")
+            out << key[0, index] if index
+          end
+        end
+      end
+    end
+  end
+end