rigortype 0.3.3 → 0.3.4

data/lib/rigor/analysis/reachability/plugin_roots.rb

@@ -0,0 +1,164 @@
+# frozen_string_literal: true
+
+require_relative "../../plugin"
+require_relative "../../plugin/loader"
+require_relative "../../plugin/services"
+require_relative "../../reflection"
+require_relative "../../type/combinator"
+
+module Rigor
+  module Analysis
+    module Reachability
+      # ADR-102 WD3 — the plugin contribution protocol: framework knowledge stays in plugins, and the core
+      # defines only the channel it arrives through.
+      #
+      # The channel is the EXISTING cross-plugin fact mechanism (ADR-9), not a new hook. A plugin declares
+      # `produces: [:reachability_roots]` in its manifest and publishes an Array of fully-qualified constant
+      # names from its `#prepare(services)` hook; this module loads the project's plugins, runs every
+      # `#prepare`, and hands the union to {Graph}'s `root_fqns:`. Reusing the fact store means the ordering
+      # guarantee is already settled — `#prepare` runs before anything reads the store — and a plugin that
+      # already computes the knowledge (`rigor-rails-routes` parses `config/routes.rb` for its helper table
+      # regardless) publishes a second view of it for free.
+      #
+      # Why roots at all: a Rails controller is reached by NAME at request time, so a reference index sees a
+      # live controller exactly as it sees a dead one. Route roots were the single largest lever in the #345
+      # corpus measurement — subtracting them removed 40 % / 62 % / 67 % of the class tier across three
+      # targets, more than every other stage combined.
+      #
+      # **Two facts, because a root is not the only thing a plugin knows.** `:reachability_references` is the
+      # sibling fact (#350): an Array of `{name:, role:}`, threaded into the graph as extra REFERENCES rather
+      # than as roots. FactoryBot is the motivating case — `factory :user, class: "Admin::User"` names a class
+      # by a string the constant scan cannot see, so it is real evidence of use, but a factory lives in the
+      # test tree and rooting it would promote `Admin::User` to production-reachable and erase WD8's
+      # "reachable only from tests" answer for it. Carrying the referrer's role keeps the two apart.
+      #
+      # The module keeps its `PluginRoots` name because roots stay its primary product, and because both
+      # facts arrive through ONE plugin-load pass — loading the registry a second time would double a
+      # report's startup cost to collect a strictly smaller fact.
+      #
+      # **Fail-soft is the invariant.** A project with no plugins, a plugin gem that will not resolve, or a
+      # plugin that raises in `#prepare` degrades to the root set the report had without plugins — never a
+      # crash. `rigor unused` is a report a human reads; refusing to print it because one plugin is
+      # misconfigured trades a slightly wider candidate list for no output at all.
+      #
+      # **Under-supply beats over-supply.** A root that names a constant the project does not declare is
+      # inert (the graph intersects roots with owned declarations), but a root claiming a namespace it does
+      # not really reach silently hides real dead code. That asymmetry is why {.collect} validates the shape
+      # of what a plugin publishes rather than trusting it, and why the report surfaces the count of
+      # supplied roots that matched no declaration — a plugin's contribution needs its own corpus check
+      # (ADR-102 § Consequences).
+      module PluginRoots
+        # The fact name a root-contributing plugin publishes under. Namespaced by `plugin_id` inside the
+        # store, so two plugins contributing roots never collide.
+        FACT_NAME = :reachability_roots
+
+        # The sibling fact: references that carry their referrer's role instead of rooting anything (#350).
+        REFERENCE_FACT_NAME = :reachability_references
+
+        # A published entry is accepted only when it is shaped like a constant path. The filter is not a
+        # security boundary — plugins are trusted code (ADR-2) — it keeps a plugin bug (a path, a helper
+        # name, a nil) from entering the graph as a root that silently matches nothing.
+        CONSTANT_NAME = /\A(?:::)?[A-Z][A-Za-z0-9_]*(?:::[A-Z][A-Za-z0-9_]*)*\z/
+
+        # The roles {Scan.role_for} assigns a file, and therefore the only roles a plugin may claim for a
+        # reference it contributes. An unrecognised role is dropped rather than defaulted: defaulting to
+        # `:production` would silently promote a test-tree reference, which is the one outcome WD8 exists to
+        # prevent.
+        ROLES = %i[production test task config].freeze
+
+        # One plugin-contributed reference. `role` is the role of whatever names the constant, exactly as a
+        # scanned file's role would be.
+        Reference = Data.define(:name, :role)
+
+        # Everything one plugin-load pass yields. Roots seed the mark-and-sweep; references enter the graph
+        # beside the scanned ones.
+        Contribution = Data.define(:roots, :references) do
+          def self.empty = new(roots: [].freeze, references: [].freeze)
+
+          def empty? = roots.empty? && references.empty?
+        end
+
+        module_function
+
+        # Loads the project's configured plugins, runs every `#prepare`, and returns the union of every
+        # published `:reachability_roots` and `:reachability_references` fact.
+        #
+        # @param configuration [Rigor::Configuration] the loaded project configuration.
+        # @param plugin_requirer [#call] how a plugin gem is brought into the process. The same seam
+        #   `Analysis::Runner` exposes, so a spec can register a plugin class without publishing a gem.
+        # @return [Contribution] sorted and de-duplicated. Empty whenever the project declares no plugins, no
+        #   plugin contributes anything, or anything at all goes wrong.
+        def collect(configuration:, plugin_requirer: ->(name) { require name })
+          return Contribution.empty if configuration.plugins.empty?
+
+          services = build_services(configuration)
+          registry = Plugin::Loader.load(configuration: configuration, services: services,
+                                         requirer: plugin_requirer)
+          return Contribution.empty if registry.nil? || registry.empty?
+
+          run_prepare(registry)
+          harvest(services.fact_store)
+        rescue StandardError, ScriptError
+          Contribution.empty
+        end
+
+        # Mirrors `CLI::ProbeEnvironment.load_plugin_registry`: a `Plugin::Services` with no cache store
+        # (this is a one-shot report, so a producer recomputes rather than reading and writing cache slots)
+        # driving `Plugin::Loader.load`. Holding the `Services` is what gives access to the fact store the
+        # loaded plugins share — the loader hands the same instance to every plugin.
+        def build_services(configuration)
+          Plugin::Services.new(
+            reflection: Reflection,
+            type: Type::Combinator,
+            configuration: configuration,
+            cache_store: nil
+          )
+        end
+
+        # Per-plugin isolation, matching `Analysis::WorkerSession#run_plugin_prepare`: one raising plugin
+        # loses its own facts, never the facts of the plugins beside it.
+        def run_prepare(registry)
+          registry.plugins.each do |plugin|
+            plugin.prepare(plugin.services)
+          rescue StandardError, ScriptError
+            next
+          end
+        end
+
+        # Reads every plugin's contribution. `each_fact` rather than a `read(plugin_id:, name:)` per known
+        # producer: the core deliberately does not know WHICH plugins contribute roots, which is the whole
+        # point of routing this through the fact store instead of an allow-list in the core.
+        def harvest(fact_store)
+          roots = Set.new
+          references = Set.new
+          fact_store.each_fact do |fact|
+            case fact.name
+            when FACT_NAME then Array(fact.value).each { |entry| collect_root(entry, roots) }
+            when REFERENCE_FACT_NAME then Array(fact.value).each { |entry| collect_reference(entry, references) }
+            end
+          end
+          Contribution.new(roots: roots.to_a.sort.freeze,
+                           references: references.to_a.sort_by { |ref| [ref.name, ref.role] }.freeze)
+        end
+
+        def collect_root(entry, roots)
+          name = entry.to_s
+          roots << name.delete_prefix("::") if CONSTANT_NAME.match?(name)
+        end
+
+        # A reference entry is a Hash so the fact stays self-describing across the store — a bare pair would
+        # read identically whichever way round a plugin author wrote it. String and Symbol keys are both
+        # accepted because a plugin may have round-tripped the value through a cache slot.
+        def collect_reference(entry, references)
+          return unless entry.is_a?(Hash)
+
+          name = (entry[:name] || entry["name"]).to_s
+          role = (entry[:role] || entry["role"])&.to_sym
+          return unless CONSTANT_NAME.match?(name) && ROLES.include?(role)
+
+          references << Reference.new(name: name.delete_prefix("::"), role: role)
+        end
+      end
+    end
+  end
+end

data/lib/rigor/analysis/reachability/project_files.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Rigor
+  module Analysis
+    module Reachability
+      # Which files in a checkout are the PROJECT's, for the purpose of harvesting references.
+      #
+      # `rigor unused` reads references from the whole project rather than only the analysed `paths:` (ADR-102
+      # WD7), which makes "the whole project" a question that needs answering rather than assuming.
+      module ProjectFiles
+        # Trees that are never a project's own source. A reference found inside a vendored gem is not evidence
+        # about this project, and globbing them can cost more than every analysed file combined.
+        VENDOR_DIRS = %r{\A(vendor|node_modules|tmp|\.git|\.rigor|coverage)/}
+
+        module_function
+
+        # Path prefixes of the checkout's git submodules, from `.gitmodules`.
+        #
+        # A submodule is a separate project that happens to live inside this one; its contents are neither this
+        # project's declarations nor references to them. Rigor's own repository is the case that made this
+        # unmissable — it vendors upstream sources under `references/`, 13,894 of the 18,002 files the
+        # reference glob would otherwise read, and one of them crashed the run outright.
+        #
+        # Reads `.gitmodules` rather than probing for nested `.git` entries: it is one cheap file against a
+        # second full tree walk, and it is what the repository itself declares. A nested checkout that is not a
+        # registered submodule is therefore not detected — `exclude:` covers that case.
+        def submodule_prefixes(root)
+          gitmodules = File.join(root, ".gitmodules")
+          return [] unless File.file?(gitmodules)
+
+          File.read(gitmodules).scan(/^\s*path\s*=\s*(.+)$/).flatten.filter_map do |path|
+            trimmed = path.strip
+            "#{trimmed.delete_suffix('/')}/" unless trimmed.empty?
+          end
+        rescue SystemCallError
+          []
+        end
+
+        # Does an `--entry-point` glob match this path?
+        #
+        # `File::FNM_PATHNAME` is what makes `**` mean "zero or more directories" rather than "one or more".
+        # Without it `lib/workers/**/*.rb` does not match `lib/workers/a.rb` — only files nested a level
+        # deeper — and a user writing that glob means the whole tree. The failure is silent and in the bad
+        # direction: the top-level declarations stay in the report and read as dead code.
+        def entry_point_match?(pattern, path)
+          File.fnmatch?(pattern, path, File::FNM_PATHNAME)
+        end
+
+        # @param relative_paths [Array<String>] paths relative to `root`.
+        # @return [Array<String>] those that belong to the project itself.
+        def own(relative_paths, root)
+          prefixes = submodule_prefixes(root)
+          relative_paths.grep_v(VENDOR_DIRS).reject { |rel| prefixes.any? { |prefix| rel.start_with?(prefix) } }
+        end
+      end
+    end
+  end
+end

data/lib/rigor/analysis/reachability/scan.rb

@@ -0,0 +1,241 @@
+# frozen_string_literal: true
+
+require "prism"
+
+require_relative "../../source/constant_path"
+require_relative "../../source/node_children"
+
+module Rigor
+  module Analysis
+    module Reachability
+      # ADR-102 — the per-file half of the reference index: one Prism walk that records every constant
+      # DECLARATION and every constant REFERENCE, each with the lexical nesting in force at that point.
+      #
+      # This is deliberately NOT a hook on the typing path. `Reflection.resolve_constant_type` fires only where
+      # the engine needs a constant's *type*, so a constant that is read but never typed leaves no trace there —
+      # the #345 measurement found five distinct losses (cross-file value constants, parameter defaults,
+      # lambda-rvalue bodies, superclass positions, intermediate namespace segments) and produced 140 candidates
+      # of which zero were genuine. A reference index has to see every constant node regardless of whether a type
+      # was wanted, which is what this walk does.
+      #
+      # Names are recorded AS WRITTEN together with their nesting; resolution to a fully-qualified name happens
+      # in {Graph}, after every file has been scanned, because a bare `Foo` cannot be resolved until the whole
+      # declaration set is known.
+      module Scan
+        # A class / module declaration, or a constant assigned one of the meta-new forms. `nesting` is the
+        # enclosing declaration path at the declaration site, so `fqn` is exact.
+        Declaration = Data.define(:fqn, :path, :line, :superclass, :includes)
+
+        # One constant reference. `from` is the fully-qualified name of the innermost enclosing declaration, or
+        # nil for a reference written at file level — that is what makes the graph a reachability graph rather
+        # than a reference count (ADR-102 WD2). `role` is the referring FILE's role (WD8).
+        Reference = Data.define(:as_written, :nesting, :from, :role, :path, :line)
+
+        # ADR-102 WD4 — a site where a constant is reached by a mechanism the static reading cannot follow.
+        # `name` is the exact constant when the argument is a literal (`"Foo".constantize`), in which case this
+        # is as good as a reference. `prefix` is the namespace a dynamic construction can reach into
+        # (`"Foo::#{k}".constantize` → `"Foo"`, and `nil` when even that is unknown), which taints every
+        # declaration at or below it rather than proving any single one used.
+        DynamicUse = Data.define(:name, :prefix, :reason, :site, :path, :line)
+
+        Result = Data.define(:declarations, :references, :dynamic_uses)
+
+        # Roles a referring file can have (ADR-102 WD8). A reference edge carries its referrer's role so
+        # "used only by its own test" is a reportable category rather than a bucket boundary.
+        def self.role_for(path)
+          case path
+          when %r{(\A|/)(spec|test)/}, /_(spec|test)\.rb\z/ then :test
+          when /\.rake\z/, %r{(\A|/)(lib/)?tasks/} then :task
+          when %r{(\A|/)config/} then :config
+          else :production
+          end
+        end
+
+        # @param path [String] the file's path, as the report should render it.
+        # @param source [String] the file's bytes.
+        # @param target_ruby [String, nil] Prism version string, threaded from the project configuration.
+        # @return [Result, nil] nil when the file does not parse (a parse error is the analyzer's business, not
+        #   this scan's — it simply contributes nothing rather than half a file).
+        # A constant name is ASCII by construction, so a byte sequence that is not valid UTF-8 cannot be one.
+        # Dropping it is both correct and the only safe answer: carrying it forward crashed the whole run on
+        # the first `String#sub` downstream, which is how this surfaced — `rigor unused` on Rigor's own
+        # repository, which vendors a CRuby checkout containing deliberately ill-encoded encoding fixtures.
+        def self.usable_name(raw)
+          return nil if raw.nil?
+
+          name = raw.dup.force_encoding(Encoding::UTF_8)
+          name.valid_encoding? ? name : nil
+        end
+
+        def self.call(path:, source:, target_ruby: nil)
+          parsed = if target_ruby
+                     Prism.parse(source, filepath: path,
+                                         version: target_ruby)
+                   else
+                     Prism.parse(source, filepath: path)
+                   end
+          return nil unless parsed.success?
+
+          walker = Walker.new(path: path, role: role_for(path))
+          walker.walk(parsed.value, [])
+          Result.new(declarations: walker.declarations.freeze, references: walker.references.freeze,
+                     dynamic_uses: walker.dynamic_uses.freeze)
+        end
+
+        # Single-pass walker. Tracks `nesting` as the stack of enclosing declaration names.
+        class Walker
+          attr_reader :declarations, :references, :dynamic_uses
+
+          def initialize(path:, role:)
+            @path = path
+            @role = role
+            @declarations = []
+            @references = []
+            @dynamic_uses = []
+          end
+
+          def walk(node, nesting)
+            return unless node.is_a?(Prism::Node)
+
+            case node
+            when Prism::ClassNode  then return walk_declaration(node, nesting, superclass: node.superclass)
+            when Prism::ModuleNode then return walk_declaration(node, nesting, superclass: nil)
+            when Prism::ConstantReadNode, Prism::ConstantPathNode
+              record_reference(node, nesting)
+              # A constant path's segments are not separate references — `A::B::C` is one reference to the leaf,
+              # and descending would record `A` and `A::B` as references in their own right (22 spurious
+              # candidates on Rigor's own lib came from exactly that in the #345 probe).
+              return
+            when Prism::ConstantWriteNode
+              record_meta_new(node, nesting)
+              walk(node.value, nesting)
+              return
+            when Prism::CallNode
+              record_dynamic_use(node)
+            end
+
+            node.rigor_each_child { |child| walk(child, nesting) }
+          end
+
+          private
+
+          def walk_declaration(node, nesting, superclass:)
+            name = Source::ConstantPath.qualified_name(node.constant_path)
+            return node.rigor_each_child { |child| walk(child, nesting) } if name.nil?
+
+            fqn = (nesting + [name]).join("::")
+            # The superclass position IS a reference — `class Sub < Base` reads `Base` — and it resolves against
+            # the OUTER nesting, not inside the body being opened.
+            record_reference(superclass, nesting) if superclass
+            includes = node.body ? mixin_names(node.body) : []
+            @declarations << Declaration.new(fqn: fqn, path: @path, line: node.location.start_line,
+                                             superclass: superclass && Source::ConstantPath.qualified_name(superclass),
+                                             includes: includes.freeze)
+            walk(node.body, nesting + [name]) if node.body
+          end
+
+          # `Const = Class.new` / `Module.new` / `Data.define(...)` / `Struct.new(...)` declare a class under a
+          # constant, and `ScopeIndexer#record_class_new_constant_decl` already treats them as class declarations
+          # for cross-file resolution. The report must agree, or every such constant reads as an unreferenced
+          # value rather than a class.
+          META_NEW = { "Class" => :new, "Module" => :new, "Data" => :define, "Struct" => :new }.freeze
+          private_constant :META_NEW
+
+          def record_meta_new(node, nesting)
+            call = node.value
+            return unless call.is_a?(Prism::CallNode)
+
+            recv = call.receiver
+            return unless recv.is_a?(Prism::ConstantReadNode) && META_NEW[recv.name.to_s] == call.name
+
+            @declarations << Declaration.new(fqn: (nesting + [node.name.to_s]).join("::"), path: @path,
+                                             line: node.location.start_line, superclass: nil, includes: [].freeze)
+          end
+
+          # `include` / `prepend` / `extend` argument names written directly in the declaration body. Only the
+          # top level of the body is inspected: a mixin applied inside a conditional or a nested def is not a
+          # static ancestor edge.
+          def mixin_names(body)
+            body.child_nodes.filter_map do |stmt|
+              next unless stmt.is_a?(Prism::CallNode) && %i[include prepend extend].include?(stmt.name)
+              next if stmt.receiver
+
+              arg = stmt.arguments&.arguments&.first
+              arg && Source::ConstantPath.qualified_name_or_nil(arg)
+            end
+          end
+
+          # Names that turn a String into a constant. `constantize` / `safe_constantize` are ActiveSupport;
+          # `const_get` is core and may carry an explicit receiver (`Object.const_get`, `self.class.const_get`).
+          DYNAMIC_RESOLVERS = %i[constantize safe_constantize const_get].freeze
+          private_constant :DYNAMIC_RESOLVERS
+
+          SUBJECT_SHAPES = {
+            Prism::StringNode => "a literal string",
+            Prism::SymbolNode => "a literal symbol",
+            Prism::InterpolatedStringNode => "an interpolated string"
+          }.freeze
+          private_constant :SUBJECT_SHAPES
+
+          # Rigor knows the argument's shape, which is the whole reason this can be tiered rather than treated
+          # as a blanket namespace poison: a literal argument names the exact constant and is as good as a
+          # written reference, while an interpolated one can only bound the namespace it reaches into.
+          def record_dynamic_use(node)
+            return unless DYNAMIC_RESOLVERS.include?(node.name)
+
+            subject = node.name == :const_get ? node.arguments&.arguments&.first : node.receiver
+            return if subject.nil?
+
+            name, prefix = dynamic_target(subject)
+            # A literal whose bytes are not valid UTF-8 cannot name a constant; dropping it is the only safe
+            # answer, and carrying it forward crashed the whole run downstream.
+            return if subject.is_a?(Prism::StringNode) && name.nil?
+            return if subject.is_a?(Prism::SymbolNode) && name.nil?
+
+            @dynamic_uses << DynamicUse.new(
+              name: name, prefix: prefix, site: site(node), path: @path, line: node.location.start_line,
+              reason: "#{node.name} on #{SUBJECT_SHAPES.fetch(subject.class, 'a computed value')}"
+            )
+          end
+
+          # `[exact name, bounded namespace]` for a dynamic-resolution subject. A literal names its constant
+          # exactly; an interpolation can only bound the namespace its literal head names; anything else bounds
+          # nothing.
+          def dynamic_target(subject)
+            case subject
+            when Prism::StringNode, Prism::SymbolNode then [Scan.usable_name(subject.unescaped), nil]
+            when Prism::InterpolatedStringNode then [nil, literal_prefix(subject)]
+            else [nil, nil]
+            end
+          end
+
+          # The literal head of an interpolated name: `"Foo::Bar::#{k}"` bounds the reach to `Foo::Bar`. Returns
+          # nil when the interpolation starts the string, which bounds nothing.
+          def site(node)
+            "#{@path}:#{node.location.start_line}"
+          end
+
+          def literal_prefix(node)
+            head = node.parts.first
+            return nil unless head.is_a?(Prism::StringNode)
+
+            literal = Scan.usable_name(head.unescaped)
+            return nil if literal.nil?
+
+            trimmed = literal.sub(/::\z/, "")
+            trimmed.empty? ? nil : trimmed
+          end
+
+          def record_reference(node, nesting)
+            as_written = Source::ConstantPath.qualified_name_or_nil(node)
+            return if as_written.nil?
+
+            @references << Reference.new(as_written: as_written, nesting: nesting.dup.freeze,
+                                         from: nesting.empty? ? nil : nesting.join("::"),
+                                         role: @role, path: @path, line: node.location.start_line)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rigor/analysis/reachability/signature_scan.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+require "rbs"
+
+require_relative "scan"
+
+module Rigor
+  module Analysis
+    module Reachability
+      # ADR-102 WD7 / issue #363 — the RBS half of the reference corpus.
+      #
+      # A constant named only from the project's own `sig/` is genuinely referenced, which is why signatures
+      # are read at all: the #345 probe reported such constants as false candidates until an RBS-side hook was
+      # added. But a signature file also DECLARES, and the two must not be confused.
+      #
+      # The first implementation scanned each file for constant-shaped tokens, which cannot tell the
+      # difference. With `rbs-inline`-generated signatures — where every project class has a mirror
+      # declaration under `sig/` — that made a large fraction of the project unconditionally reachable: on one
+      # application 48 of 101 roots came from `sig/`, hiding seven candidates and ten test-only rows. Over-supply
+      # is the worse direction (an under-supplied root leaves a row where a human can see it; an over-supplied
+      # one removes it where nobody will), so this parses instead.
+      #
+      # The rule: a declaration's own name is a DECLARATION and contributes nothing. Every type name appearing
+      # in a POSITION — a superclass, a mixin argument, a parameter or return type, a constant's type, a type
+      # alias body, a generic argument — is a reference and counts.
+      module SignatureScan
+        module_function
+
+        # @param file [String] path to a `.rbs` file.
+        # @return [Array<Scan::Reference>] one file-level reference per distinct referenced name. Empty when the
+        #   file cannot be read or parsed — a broken signature is the analyzer's business, not this scan's.
+        def call(file)
+          _, _, decls = ::RBS::Parser.parse_signature(::RBS::Buffer.new(name: file, content: File.read(file)))
+          found = []
+          decls.each { |decl| walk(decl, [], found) }
+          found.uniq.map do |name, nesting|
+            Scan::Reference.new(as_written: name, nesting: nesting, from: nil, role: :config, path: file,
+                                line: 1)
+          end
+        rescue ::RBS::BaseError, SystemCallError, ArgumentError
+          []
+        end
+
+        # Walks a declaration, threading the lexical nesting so a name written relative to an enclosing module
+        # resolves the way the graph's own candidate walk expects. Without this, `module A; class B < C; end`
+        # would contribute a bare `C` that resolves against nothing.
+        def walk(node, nesting, out)
+          case node
+          when ::RBS::AST::Declarations::Class then walk_class(node, nesting, out)
+          when ::RBS::AST::Declarations::Module then walk_module(node, nesting, out)
+          when ::RBS::AST::Declarations::Interface
+            descend(node, nesting + segments(node.name), out)
+          when ::RBS::AST::Members::Include, ::RBS::AST::Members::Extend, ::RBS::AST::Members::Prepend
+            record(node.name, nesting, out)
+            node.args&.each { |arg| collect_types(arg, nesting, out) }
+          when ::RBS::AST::Members::MethodDefinition
+            node.overloads.each { |overload| collect_types(overload.method_type, nesting, out) }
+          when *TYPED_NODES
+            collect_types(node.type, nesting, out)
+          end
+        end
+
+        # Nodes whose whole contribution is the type they carry: a constant's or alias's right-hand side, and
+        # the attribute / variable families.
+        TYPED_NODES = [
+          ::RBS::AST::Declarations::Constant, ::RBS::AST::Declarations::TypeAlias,
+          ::RBS::AST::Members::AttrReader, ::RBS::AST::Members::AttrWriter,
+          ::RBS::AST::Members::AttrAccessor, ::RBS::AST::Members::InstanceVariable,
+          ::RBS::AST::Members::ClassInstanceVariable, ::RBS::AST::Members::ClassVariable
+        ].freeze
+
+        def walk_class(node, nesting, out)
+          record(node.super_class&.name, nesting, out)
+          node.super_class&.args&.each { |arg| collect_types(arg, nesting, out) }
+          descend(node, nesting + segments(node.name), out)
+        end
+
+        def walk_module(node, nesting, out)
+          node.self_types&.each { |self_type| record(self_type.name, nesting, out) }
+          descend(node, nesting + segments(node.name), out)
+        end
+
+        def descend(node, nesting, out)
+          node.members&.each { |member| walk(member, nesting, out) }
+        end
+
+        # Every `RBS::TypeName` reachable from a type, found reflectively. RBS's type zoo is wide (unions,
+        # intersections, tuples, records, optionals, procs, generics) and grows between releases; enumerating
+        # the classes would silently drop references the day a new one lands, and dropping a reference here
+        # manufactures a false candidate.
+        def collect_types(type, nesting, out)
+          return if type.nil?
+
+          record(type.name, nesting, out) if type.respond_to?(:name) && type.name.is_a?(::RBS::TypeName)
+          type.instance_variables.each do |ivar|
+            value = type.instance_variable_get(ivar)
+            case value
+            when ::RBS::TypeName then record(value, nesting, out)
+            when Array then value.each { |v| collect_types(v, nesting, out) }
+            when Hash then value.each_value { |v| collect_types(v, nesting, out) }
+            else collect_types(value, nesting, out) if value.respond_to?(:instance_variables)
+            end
+          end
+        end
+
+        # Records the name AS WRITTEN together with the nesting it was written under, and lets
+        # {Graph#resolve} do the lexical walk — the same walk it does for a name read out of Ruby source.
+        #
+        # An earlier version hand-built the qualified form instead (`"#{nesting}::#{bare}"`) on the reasoning
+        # that over-approximating which of absolute / relative / top-level a name is could only fail to remove
+        # a candidate. That was wrong, and it resurrected the very defect #363 fixed. `include Alba::Resource`
+        # inside `class SignageResource` produced `SignageResource::Alba::Resource`; the graph resolves a
+        # reference to a member as a reference to its owner, so it peeled that to `SignageResource::Alba` and
+        # then to `SignageResource` — a declaration. The reference is file-level, so the class rooted ITSELF,
+        # and three genuinely dead classes stayed out of the report on the project where this was found.
+        #
+        # Passing the real nesting cannot do that: the walk tries the qualified candidate, misses, and the peel
+        # then applies to the written name alone.
+        def record(type_name, nesting, out)
+          return if type_name.nil?
+
+          bare = type_name.to_s.delete_prefix("::")
+          return if bare.empty?
+
+          out << [bare, nesting.dup.freeze]
+        end
+
+        def segments(type_name)
+          type_name.to_s.delete_prefix("::").split("::")
+        end
+      end
+    end
+  end
+end