rigortype 0.4.1 → 0.4.3

data/lib/rigor/analysis/plugin_fact_fingerprint.rb

@@ -36,12 +36,55 @@ module Rigor
     # The probe is ALWAYS sequential and independent of the analysis's pool mode, so the invalidation decision
     # is identical whether the recheck ran pooled or sequential (the pooled-vs-sequential parity requirement).
     class PluginFactFingerprint
-      # `digest` is nil when no plugins are loaded — the fast path (nothing to fingerprint), which reuses
-      # freely. `opaque_plugin_ids` names contributing-but-surfaceless plugins (see the class doc); when
-      # non-empty the snapshot is never reused.
-      Result = Data.define(:digest, :opaque_plugin_ids) do
+      # Why one plugin is opaque to the fingerprint. `kind` is one of:
+      #   :no_surface    the plugin contributes types and declares no fact, producer or hook;
+      #   :undigestible  a value it declares or publishes cannot be digested (a Proc, an IO, ...);
+      #   :raised        the hook or a producer raised while its value was being read.
+      # `input` names the input: `"producer worker_index"`, `"fact callback"`, `"hook incremental_state_fingerprint"`.
+      # `class_name` is the class of the value that could not be digested, or of the exception raised; an anonymous
+      # class reads "anonymous Class", and nil means the class itself could not be read.
+      OpaqueReason = Data.define(:kind, :input, :class_name) do
+        # The clause a note states about plugin `id`. The note groups :no_surface plugins itself, so this is only
+        # called for :undigestible and :raised reasons.
+        def describe(id)
+          return "plugin #{id}'s #{input} raised #{class_name}" if kind == :raised
+
+          "plugin #{id}'s #{input} has a value the incremental fingerprint cannot digest#{parenthesised_class}"
+        end
+
+        # The same verdict without the plugin id, for a `--cache-stats` line that already names it.
+        def summary
+          return "no incremental fingerprint surface" if kind == :no_surface
+          return "#{input} raised #{class_name}" if kind == :raised
+
+          "#{input} has a value the incremental fingerprint cannot digest#{parenthesised_class}"
+        end
+
+        private
+
+        def parenthesised_class
+          return "" if class_name.nil?
+
+          " (#{article(class_name)} #{class_name})"
+        end
+
+        def article(word)
+          word.match?(/\A[aeiou]/i) ? "an" : "a"
+        end
+      end
+
+      # `digest` is nil when no plugins are loaded — the fast path (nothing to fingerprint), which reuses freely.
+      # `opaque_reasons` maps each opaque plugin id to its {OpaqueReason}, sorted by id. `fact_store_unreadable` is
+      # true when the fact store could not be read at all: no single plugin is to blame, so no reason names one.
+      # Either makes the snapshot un-reusable.
+      Result = Data.define(:digest, :opaque_reasons, :fact_store_unreadable) do
+        # The opaque plugin ids, sorted (the keys of {#opaque_reasons}).
+        def opaque_plugin_ids
+          opaque_reasons.keys
+        end
+
         def opaque?
-          !opaque_plugin_ids.empty?
+          fact_store_unreadable || !opaque_reasons.empty?
         end
 
         # A warm recheck may reuse the snapshot only when this run is not opaque and its fact-surface digest
@@ -97,16 +140,20 @@ module Rigor
       end
 
       def digest_registry(registry)
-        return Result.new(digest: nil, opaque_plugin_ids: [].freeze) if registry.nil? || registry.empty?
+        empty = registry.nil? || registry.empty?
+        return Result.new(digest: nil, opaque_reasons: {}.freeze, fact_store_unreadable: false) if empty
 
-        opaque = []
-        facts_by_plugin = facts_by_plugin(registry, opaque)
-        parts = fact_parts(facts_by_plugin)
-        registry.plugins.each { |plugin| collect_plugin_parts(plugin, facts_by_plugin, parts, opaque) }
-        # Sort the parts so the digest is independent of plugin registration / iteration order.
+        reasons = {}
+        facts, store_unreadable = facts_by_plugin(registry, reasons)
+        parts = fact_parts(facts)
+        registry.plugins.each { |plugin| collect_plugin_parts(plugin, facts, parts, reasons) }
+        # Sort the parts so the digest is independent of plugin registration / iteration order. An unreadable
+        # store names no plugin: the snapshot is opaque as a whole, and per-plugin reasons would blame plugins
+        # whose facts were simply not read.
         Result.new(
           digest: Digest::SHA256.hexdigest(parts.sort.join("\x00")),
-          opaque_plugin_ids: opaque.uniq.freeze
+          opaque_reasons: (store_unreadable ? {} : reasons.sort.to_h).freeze,
+          fact_store_unreadable: store_unreadable
         )
       end
 
@@ -119,23 +166,25 @@ module Rigor
 
       # Appends one plugin's producer / hook parts to `parts` and marks it opaque when it contributes a type
       # (`dynamic_return` / `narrowing_facts`) yet declares NONE of (a)/(b)/(c).
-      def collect_plugin_parts(plugin, facts_by_plugin, parts, opaque)
+      def collect_plugin_parts(plugin, facts_by_plugin, parts, reasons)
         id = safe_id(plugin)
         has_facts = facts_by_plugin.key?(id)
-        has_producers = collect_producer_parts(plugin, id, parts, opaque)
-        has_hook = collect_hook_part(plugin, id, parts, opaque)
+        has_producers = collect_producer_parts(plugin, id, parts, reasons)
+        has_hook = collect_hook_part(plugin, id, parts, reasons)
         surface = has_facts || has_producers || has_hook
-        opaque << id if !surface && contributes_types?(plugin)
+        return if surface || !contributes_types?(plugin)
+
+        mark_opaque(reasons, id, OpaqueReason.new(kind: :no_surface, input: nil, class_name: nil))
       end
 
-      # `{ plugin_id => ["name=digest", ...] }` for every ADR-9 published fact (channel a). A plugin that
-      # published nothing does not appear.
+      # `[{ plugin_id => ["name=digest", ...] }, unreadable]` for every ADR-9 published fact (channel a). A plugin
+      # that published nothing does not appear.
       #
-      # A fact the fingerprint cannot digest is an input it cannot see, so its publisher is opaque, whether or
-      # not the publisher contributes a type itself: other plugins read its facts. A fact store that cannot be
-      # read at all makes every plugin opaque. Both force the full run; dropping the facts instead would let a
-      # plugin with another surface reuse a snapshot its facts no longer match.
-      def facts_by_plugin(registry, opaque)
+      # A fact the fingerprint cannot digest is an input it cannot see, so its publisher is opaque, whether or not
+      # the publisher contributes a type itself: other plugins read its facts. A fact store that cannot be read at
+      # all makes the whole surface opaque. Both force the full run; dropping the facts instead would let a plugin
+      # with another surface reuse a snapshot its facts no longer match.
+      def facts_by_plugin(registry, reasons)
         result = Hash.new { |hash, key| hash[key] = [] }
         fact_store = registry.plugins.first&.services&.fact_store
         fact_store&.each_fact do |fact|
@@ -143,13 +192,12 @@ module Rigor
           begin
             result[plugin_id] << "#{fact.name}=#{digest_value(fact.value)}"
           rescue StandardError
-            opaque << plugin_id
+            mark_opaque(reasons, plugin_id, undigestible("fact #{fact.name}", fact.value))
           end
         end
-        result
+        [result, false]
       rescue StandardError
-        registry.plugins.each { |plugin| opaque << safe_id(plugin) }
-        Hash.new { |hash, key| hash[key] = [] }
+        [Hash.new { |hash, key| hash[key] = [] }, true]
       end
 
       # Channel (b): a stable signature of every declared producer's VALUE — a digest of the producer's own
@@ -161,28 +209,67 @@ module Rigor
       # a value-preserving edit keeps the recheck incremental. Returns true when the plugin declared at least
       # one producer (a surface); a producer whose value cannot be digested marks the plugin opaque.
       # rubocop:disable-next Naming/PredicateMethod -- reports has-surface AND appends parts (a side-effecting builder)
-      def collect_producer_parts(plugin, id, parts, opaque)
+      def collect_producer_parts(plugin, id, parts, reasons)
         producer_ids = plugin.class.producers.keys
         return false if producer_ids.empty?
 
         producer_ids.sort.each do |producer_id|
-          parts << "prod\x1f#{id}\x1f#{producer_id}\x1f#{digest_value(plugin.producer_value(producer_id))}"
-        rescue StandardError
-          opaque << id
+          input = "producer #{producer_id}"
+          begin
+            value = plugin.producer_value(producer_id)
+          rescue StandardError => e
+            mark_opaque(reasons, id, raised(input, e))
+            next
+          end
+          digest_part(parts, reasons, id, input, "prod\x1f#{id}\x1f#{producer_id}", value)
         end
         true
       end
 
-      # Channel (c): the optional {Plugin::Base#incremental_state_fingerprint} hook. Returns true when the
-      # plugin defines it (it has a surface).
-      def collect_hook_part(plugin, id, parts, opaque)
+      # Channel (c): the optional {Plugin::Base#incremental_state_fingerprint} hook. Returns true when the plugin
+      # defines it (it has a surface).
+      # rubocop:disable-next Naming/PredicateMethod -- reports has-surface AND appends parts (a side-effecting builder)
+      def collect_hook_part(plugin, id, parts, reasons)
         return false unless plugin.respond_to?(:incremental_state_fingerprint)
 
-        parts << "hook\x1f#{id}\x1f#{digest_value(plugin.incremental_state_fingerprint)}"
+        input = "hook incremental_state_fingerprint"
+        begin
+          value = plugin.incremental_state_fingerprint
+        rescue StandardError => e
+          mark_opaque(reasons, id, raised(input, e))
+          return true
+        end
+        digest_part(parts, reasons, id, input, "hook\x1f#{id}", value)
         true
+      end
+
+      # Appends `prefix\x1f<digest of value>` to `parts`, or marks the plugin opaque when the value cannot be digested.
+      def digest_part(parts, reasons, id, input, prefix, value)
+        parts << "#{prefix}\x1f#{digest_value(value)}"
       rescue StandardError
-        opaque << id
-        true
+        mark_opaque(reasons, id, undigestible(input, value))
+      end
+
+      # The first reason a plugin is found opaque wins: one reason per plugin id, as {Result#opaque_reasons} states.
+      def mark_opaque(reasons, id, reason)
+        reasons[id] ||= reason
+      end
+
+      def undigestible(input, value)
+        OpaqueReason.new(kind: :undigestible, input: input, class_name: class_name_of(value))
+      end
+
+      def raised(input, error)
+        OpaqueReason.new(kind: :raised, input: input, class_name: class_name_of(error))
+      end
+
+      # The name of `object`'s class, "anonymous Class" for an anonymous one, or nil when even the class is unreadable
+      # (a BasicObject has no `#class`).
+      def class_name_of(object)
+        klass = object.class
+        klass.name || "anonymous Class"
+      rescue StandardError
+        nil
       end
 
       # A digest of a fact / producer / hook value that depends on the value alone (issue #1574). A producer's

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

@@ -5,6 +5,121 @@ require_relative "scan"
 module Rigor
   module Analysis
     module Reachability
+      # ADR-102 WD4 — how {Graph} reads a `constantize` / `const_get` site: a literal name becomes a reference
+      # looked up where Ruby looks it up, and an interpolated one on a known receiver is anchored there.
+      module DynamicLookup
+        private
+
+        # A literal-argument `"Foo::Bar".constantize` names its constant exactly, so it is a REFERENCE, not an
+        # unknown. Keeping this distinct from {Graph#tainted} is what stops the tier being a blanket namespace
+        # poison — Rigor knows the argument's shape, and a type-free indexer does not.
+        #
+        # A literal `const_get` on a known receiver is looked up where Ruby looks it up (#1761): the receiver,
+        # then its ancestors unless the call passes `inherit = false`, then the top level unless it does. A
+        # receiver holding the name is the answer — resolving it anywhere else too would make a dead same-named
+        # constant reachable; past the receiver see {#literal_targets}. A receiver that does not resolve as a
+        # whole is unknown — `Outer::Missing` peeled to `Outer` may alias anything, and `const_get` never
+        # searches `Outer` — so it falls back to the top level as an unknown receiver does.
+        #
+        # The reference carries the referring file's role (WD8): a spec's `const_get("Foo")` keeps `Foo`
+        # test-reachable, as its written `Foo` would, rather than making it live in production.
+        def literal_dynamic_references(dynamic_uses)
+          dynamic_uses.flat_map do |use|
+            next [] if use.name.nil?
+
+            name = use.name.delete_prefix("::")
+            targets = use.within ? literal_targets(use, name) : [nil]
+            targets.map do |target|
+              Scan::Reference.new(as_written: target || name, nesting: [].freeze, from: nil,
+                                  role: use.role, path: use.path, line: use.line,
+                                  rooted: !target.nil? || use.name.start_with?("::"))
+            end
+          end
+        end
+
+        # The declarations a literal `name` can name when looked up from `use.within`, a member's owner peeled
+        # as {#resolve} peels it; nil stands for the top level. The receiver declaring it is the answer. Past
+        # the receiver the walk only approximates Ruby: an ancestor named as written may resolve elsewhere
+        # (`class Api::Thing < Base` inherits `::Base`, not `Api::Base`), so every scope an ancestor could be
+        # that declares the name is kept, and the top level with them. Keeping a dead constant reachable is
+        # the cheaper mistake than listing a live one. A receiver that does not resolve is the top level; with
+        # `inherit = false` a resolved receiver that does not declare the name is nothing (Ruby raises
+        # `NameError` there).
+        def literal_targets(use, name)
+          receiver = use.receiver { |ref| resolve_ref(ref) }
+          return [nil] if receiver.nil?
+
+          local = @shadows[use.path]
+          own = declared_member(receiver, name, local)
+          return [own] if own
+          return [] unless use.inherit
+
+          plausible_ancestors(receiver).filter_map { |scope| declared_member(scope, name, local) }.uniq + [nil]
+        end
+
+        # `scope::name`, or the longest declared prefix of it, when one is declared.
+        def declared_member(scope, name, local)
+          segments = name.split("::")
+          segments.length.downto(1) do |count|
+            candidate = "#{scope}::#{segments.first(count).join('::')}"
+            return candidate if declared?(candidate, nil, local)
+          end
+          nil
+        end
+
+        # Every declaration an ancestor of `fqn` could be: each as-written superclass or mixin resolved at
+        # every enclosing scope that declares it, not only the innermost, and transitively.
+        def plausible_ancestors(fqn)
+          (@plausible_ancestors ||= {})[fqn] ||= plausible_ancestor_walk(fqn)
+        end
+
+        def plausible_ancestor_walk(fqn)
+          seen = Set[fqn]
+          queue = [fqn]
+          out = []
+          until queue.empty?
+            current = queue.shift
+            @by_fqn.fetch(current, []).each do |decl|
+              (decl.includes + [decl.superclass]).compact.each do |raw|
+                plausible_resolutions(current, raw).each do |resolved|
+                  next if seen.include?(resolved)
+
+                  seen << resolved
+                  out << resolved
+                  queue << resolved
+                end
+              end
+            end
+          end
+          out.freeze
+        end
+
+        def plausible_resolutions(subclass_fqn, raw)
+          segments = subclass_fqn.split("::")
+          (segments.length - 1).downto(0).filter_map do |i|
+            candidate = (segments[0, i] + [raw]).join("::")
+            candidate if candidate != subclass_fqn && @by_fqn.key?(candidate)
+          end
+        end
+
+        # The namespaces a `const_get` on `anchors` searches before the top level: the receiver, then, with the
+        # default `inherit = true`, every scope its superclass chain and mixins could be (#1761) — a taint is
+        # safe to over-reach.
+        def receiver_scopes(use, anchors)
+          return anchors unless use.inherit
+
+          anchors.flat_map { |anchor| [anchor, *plausible_ancestors(anchor)] }.uniq
+        end
+
+        # An interpolated site on a known receiver, with the receiver resolved into absolute `prefix`es.
+        def anchored(use)
+          return [use] if use.within.nil? || use.prefix.nil?
+
+          anchors = use.anchors { |ref| resolve_ref(ref) }
+          receiver_scopes(use, anchors).map { |scope| use.with(prefix: "#{scope}::#{use.prefix}", within: nil) }
+        end
+      end
+
       # ADR-102 — the cross-file half: resolves every as-written reference to a declaration, then marks from the
       # root set. Pure data; no engine coupling, so `rigor check`'s diagnostic stream is untouched by
       # construction rather than by a gate (WD1).
@@ -15,6 +130,8 @@ module Rigor
       # believe in. The two walks are separate implementations (this one is name-level and needs no types), so
       # `spec/rigor/analysis/reachability/graph_spec.rb` pins them to the same answers on shared fixtures.
       class Graph
+        include DynamicLookup
+
         Candidate = Data.define(:fqn, :path, :line)
 
         # `test_only` is its own list, not a flag on `candidates`: a candidate is by definition unreachable, so
@@ -35,15 +152,21 @@ module Rigor
         #   a reopened gem or stdlib class must never be a candidate (WD6). Defaults to "nothing is foreign".
         # @param dynamic_uses — sites where a constant is reached by name at runtime.
         #   A literal-argument site contributes a real reference; a dynamic one taints a namespace (WD4).
-        def initialize(declarations:, references:, root_fqns: [], dynamic_uses: [], foreign: ->(_fqn) { false })
+        # @param shadows — declarations made in files outside the analysed paths. They are never nodes, but a
+        #   reference written in the SAME file resolves to them first, as Ruby would (#1732, see {#resolve_ref}).
+        def initialize(declarations:, references:, root_fqns: [], dynamic_uses: [], shadows: [],
+                       foreign: ->(_fqn) { false })
           @declarations = declarations
-          @dynamic_uses = dynamic_uses
-          @references = references + literal_dynamic_references(dynamic_uses)
           @root_fqns = root_fqns.to_set
           @foreign = foreign
           @by_fqn = declarations.group_by(&:fqn)
+          @shadows = shadows.group_by(&:path).transform_values { |decls| decls.to_set(&:fqn) }
+          @shadows.default = Set.new.freeze
           @owned = @by_fqn.keys.reject { |fqn| @foreign.call(fqn) }.to_set
           @ancestors = {}
+          @references = references + literal_dynamic_references(dynamic_uses)
+          # `Foo.const_get("V#{k}")` bounds its reach by `Foo`, a reference like any other (#1734).
+          @dynamic_uses = dynamic_uses.flat_map { |use| anchored(use) }
         end
 
         def report
@@ -51,39 +174,36 @@ module Rigor
           production = walk(edges, seeds: production_seeds, roles: %i[production task config])
           reachable = walk(edges, seeds: production_seeds | test_seeds, roles: %i[production task config test])
           unreached = @owned - reachable
-          namespaces = namespace_only(unreached, reachable)
+          # A namespace is excused by a member PRODUCTION reaches. One whose members only tests reach is dead
+          # production code like them, so it joins them under test-only rather than vanishing from every
+          # bucket (#1732).
+          namespaces = namespace_only(unreached, production)
+          test_only = (reachable - production) | namespace_only(unreached - namespaces, reachable)
+          unreached -= namespaces | test_only
+          # A namespace a test names (`Ns::CONST`) while production reaches a declaration under it is live in
+          # production for the same reason an unreached one is not dead (#1732).
+          live_namespaces = namespace_only(test_only, production)
+          test_only -= live_namespaces
           # The data-file demotion applies to BOTH buckets it can speak to, which is what the tier
           # contract says and what the implementation had narrowed (#370). See {#tainted}.
-          test_only = reachable - production
-          undecidable = tainted(unreached - namespaces).merge(tainted(test_only))
-          build_report(edges: edges, reachable: reachable, unreached: unreached, namespaces: namespaces,
-                       test_only: test_only, undecidable: undecidable)
+          undecidable = tainted(unreached).merge(tainted(test_only))
+          undecidable = spread_undecidable(edges, undecidable, unreached | test_only,
+                                           through: namespaces | live_namespaces)
+          build_report(edges:, reachable:, unreached:, namespaces:, test_only:, undecidable:)
         end
 
         private
 
         def build_report(edges:, reachable:, unreached:, namespaces:, test_only:, undecidable:)
           demoted = undecidable.keys.to_set
-          Report.new(declared: @owned.size, reachable: reachable.size,
-                     candidates: rows(unreached - namespaces - demoted),
+          # A test-only namespace counts as reachable, like the members it is listed with.
+          Report.new(declared: @owned.size, reachable: (reachable | test_only).size,
+                     candidates: rows(unreached - demoted),
                      undecidable: undecidable.map { |fqn, reason| undecidable_row(fqn, reason) }.freeze,
                      test_only: rows(test_only - demoted),
                      namespaces: namespaces.size, roots: production_seeds.size, edges: edges.size)
         end
 
-        # A literal-argument `"Foo::Bar".constantize` names its constant exactly, so it is a REFERENCE, not an
-        # unknown. Keeping this distinct from the taint below is what stops the tier being a blanket namespace
-        # poison — Rigor knows the argument's shape, and a type-free indexer does not.
-        def literal_dynamic_references(dynamic_uses)
-          dynamic_uses.filter_map do |use|
-            next if use.name.nil?
-
-            Scan::Reference.new(as_written: use.name.sub(/\A::/, ""), nesting: [].freeze, from: nil,
-                                role: :production, path: use.path, line: use.line,
-                                rooted: use.name.start_with?("::"))
-          end
-        end
-
         # `{fqn => reason}` for every declaration in `fqns` a dynamic site could still be naming. A site with a
         # literal prefix taints that namespace and everything under it; a site with no prefix at all cannot be
         # bounded, so it taints nothing rather than everything — poisoning the whole project would empty the
@@ -109,6 +229,41 @@ module Rigor
           end
         end
 
+        # Whatever an undecidable declaration reaches is undecidable too (#1720 review). `class Sub < Base` with
+        # `Sub` reachable through `"Sub#{x}".constantize` left `Base` a DEFINITE candidate, and acting on that row
+        # deletes the base of a class that may well be live. Only declarations that would otherwise be
+        # reported — unreached or test-only — are moved; the reason names the declaration they hang from.
+        #
+        # The spread passes `through` a declaration hidden as a namespace without listing it: a service hidden
+        # only because something names a constant nested in it (`Svc::Error`) still carries the undecidable
+        # evidence on to what its body names. Stopping there left the next service down under "reachable only
+        # from tests" (#1732).
+        def spread_undecidable(edges, undecidable, reportable, through:)
+          return undecidable if undecidable.empty?
+
+          out = Hash.new { |h, k| h[k] = [] }
+          edges.each { |from, to, _role| out[from] << to }
+          result = undecidable.dup
+          passed = Set.new
+          queue = undecidable.keys
+          until queue.empty?
+            from = queue.shift
+            out[from].each do |target|
+              next if result.key?(target) || passed.include?(target)
+
+              if reportable.include?(target)
+                result[target] = "reachable from #{from}, which cannot be decided"
+              elsif through.include?(target)
+                passed << target
+              else
+                next
+              end
+              queue << target
+            end
+          end
+          result
+        end
+
         def undecidable_row(fqn, reason)
           site = @by_fqn.fetch(fqn).first
           Undecidable.new(fqn: fqn, path: site.path, line: site.line, reason: reason)
@@ -132,14 +287,32 @@ module Rigor
         # Seeds that make a declaration live in PRODUCTION: named entry points, plus anything referenced at
         # file level by a non-test file (file-level code runs on load, so its target is live).
         def production_seeds
-          @production_seeds ||= (@root_fqns & @owned) | seeds_from { |ref| ref.from.nil? && ref.role != :test }
+          @production_seeds ||= (@root_fqns & @owned) | seeds_from { |ref| source(ref).nil? && ref.role != :test }
         end
 
         # Seeds that make a declaration live only through TEST code. Kept separate from production seeds
         # rather than folded in: a spec's file-level `Foo.new` would otherwise promote `Foo` to a root and
         # erase the very distinction WD8 exists to report.
         def test_seeds
-          @test_seeds ||= seeds_from { |ref| ref.from.nil? && ref.role == :test }
+          @test_seeds ||= seeds_from { |ref| source(ref).nil? && ref.role == :test }
+        end
+
+        # The node an edge leaves: the owned declaration whose code holds the reference, with a declaration-header
+        # reference (`class Sub < Base`) credited to `Sub` (#1720). Only an owned declaration from `paths:` is a
+        # node, though. A class an initializer, `config/application.rb` or a spec helper declares, or a reopened
+        # gem class (WD6), is outside the declaration set, so the walk can never start from it and an edge
+        # leaving it would silently drop the evidence. Falling back to the enclosing nesting (#1724) did not help
+        # either: `module MyApp; class Application` and a spec's `module Outer; class Fake < OBase` fall back to a
+        # module that is never reached itself, or is not a node at all (#1732).
+        #
+        # Such a reference counts as file-level code of its file instead, in that file's role: a spec helper's
+        # reference keeps its target test-reachable, an initializer's keeps it live in production. A class header
+        # and a class body's own statements run when the file loads; a method body is read the same way because
+        # whether it runs is not decidable from a declaration this report does not own, and the other reading
+        # would report live code as dead. What the reference NAMES is still resolved against its own file's
+        # declarations first (see {#resolve_ref}).
+        def source(ref)
+          @owned.include?(ref.from) ? ref.from : nil
         end
 
         def seeds_from
@@ -147,7 +320,7 @@ module Rigor
           @references.each do |ref|
             next unless yield(ref)
 
-            target = resolve(ref.as_written, ref.nesting, rooted: ref.rooted)
+            target = resolve_ref(ref)
             set << target if target && @owned.include?(target)
           end
           set
@@ -156,14 +329,39 @@ module Rigor
         # `[from_fqn_or_nil, to_fqn, role]` for every reference that resolves to an owned declaration.
         def resolved_edges
           @resolved_edges ||= @references.filter_map do |ref|
-            target = resolve(ref.as_written, ref.nesting, rooted: ref.rooted)
+            target = resolve_ref(ref)
             next unless target && @owned.include?(target)
-            next if ref.from == target # a declaration referencing itself is not evidence of use
 
-            [ref.from, target, ref.role]
+            from = source(ref)
+            next if from == target # a declaration referencing itself is not evidence of use
+
+            [from, target, ref.role]
           end
         end
 
+        # A declaration-header reference never names the declaration it belongs to: `module Api; class User <
+        # User; end; end` reads `User` before `Api::User` exists, so Ruby answers `::User`. Every other reference
+        # resolves as written, and one that lands on its own declaration is dropped as a self-reference.
+        #
+        # A class its own file declares outside `paths:` shadows a same-named owned one, as Ruby's lookup does:
+        # `LegacyThing` inside a migration's local `class LegacyThing < ActiveRecord::Base` stub names the stub,
+        # not the app's model. The answer is then not an owned node and the reference is dropped. Only the
+        # referring file's own declarations count: a spec support file's stub is loaded with the specs, never
+        # with production, so letting it shadow other files could hide a production reference (#1732).
+        def resolve_ref(ref)
+          local = @shadows[ref.path]
+          target = resolve(ref.as_written, ref.nesting, rooted: ref.rooted, local: local)
+          return target unless target && target == ref.from && header?(ref)
+
+          resolve(ref.as_written, ref.nesting, rooted: ref.rooted, exclude: target, local: local)
+        end
+
+        # Only a header reference is credited to something other than the scope it is written in (see
+        # {Scan::Reference}).
+        def header?(ref)
+          ref.from != (ref.nesting.empty? ? nil : ref.nesting.join("::"))
+        end
+
         # Mark-and-sweep, not reference counting: an edge only propagates if its SOURCE is itself reachable, so
         # a cluster of mutually-referencing dead classes stays dead (ADR-102 WD2).
         #
@@ -198,18 +396,19 @@ module Rigor
         # Ruby's constant lookup at name granularity: `Module.nesting` innermost first, then the ancestors of
         # the innermost cresting scope (#354), then the bare name. When `rooted: true`, lexical nesting and
         # ancestors are skipped, answering the top-level declaration directly (#625).
-        def resolve(as_written, nesting, rooted: false)
+        # `exclude` names a declaration the answer must not be (see {#resolve_ref}).
+        def resolve(as_written, nesting, rooted: false, exclude: nil, local: nil)
           if rooted
-            return as_written if @by_fqn.key?(as_written)
+            return as_written if declared?(as_written, exclude, local)
 
             idx = as_written.rindex("::")
-            return idx ? resolve(as_written[0, idx], nesting, rooted: true) : nil
+            return idx ? resolve(as_written[0, idx], nesting, rooted: true, exclude: exclude, local: local) : nil
           end
 
           walker = nesting.dup
           until walker.empty?
             candidate = (walker + [as_written]).join("::")
-            return candidate if @by_fqn.key?(candidate)
+            return candidate if declared?(candidate, exclude, local)
 
             walker.pop
           end
@@ -217,11 +416,11 @@ module Rigor
           unless nesting.empty?
             ancestor_scopes(nesting.join("::")).each do |ancestor|
               candidate = "#{ancestor}::#{as_written}"
-              return candidate if @by_fqn.key?(candidate)
+              return candidate if declared?(candidate, exclude, local)
             end
           end
 
-          return as_written if @by_fqn.key?(as_written)
+          return as_written if declared?(as_written, exclude, local)
 
           # `Scope::DiscoveryIndex::EMPTY` names a constant INSIDE a class, and reading it is a use of that
           # class — but the leaf is not itself a declaration, so the reference would resolve to nothing and
@@ -229,7 +428,11 @@ module Rigor
           # on the first run of this report against Rigor's own `lib`). Peel the trailing segment and retry:
           # a reference to a member is a reference to its owner.
           idx = as_written.rindex("::")
-          idx ? resolve(as_written[0, idx], nesting) : nil
+          idx ? resolve(as_written[0, idx], nesting, exclude: exclude, local: local) : nil
+        end
+
+        def declared?(fqn, exclude, local)
+          fqn != exclude && (@by_fqn.key?(fqn) || local&.include?(fqn))
         end
 
         # Breadth-first over superclass + included modules, mixins first, terminating on a cycle. As-written
@@ -260,7 +463,8 @@ module Rigor
           segments = subclass_fqn.split("::")
           (segments.length - 1).downto(0) do |i|
             candidate = (segments[0, i] + [raw]).join("::")
-            return candidate if @by_fqn.key?(candidate)
+            # `class Api::User < User` cannot inherit from itself; the name was read before it existed.
+            return candidate if candidate != subclass_fqn && @by_fqn.key?(candidate)
           end
           nil
         end