rigortype 0.3.3 → 0.3.4

data/docs/manual/plugins/rigor-sidekiq.md

@@ -50,11 +50,61 @@ plugins:
     config:
       worker_search_paths: ["app/workers", "app/sidekiq"]          # default
       worker_marker_modules: ["Sidekiq::Job", "Sidekiq::Worker"]   # default
+      schedule_paths:                                              # default
+        - "config/schedule.yml"
+        - "config/sidekiq.yml"
 ```
 
 The default `worker_marker_modules` covers both modern Sidekiq
 (`Sidekiq::Job`, since 6.3) and the legacy `Sidekiq::Worker`.
 
+`schedule_paths` are the schedule *files* — not directories — behind
+the reachability roots below. The defaults are where the two schedule
+layouts conventionally live; list your own path if you keep the
+schedule elsewhere.
+
+## Worker roots for `rigor unused`
+
+A cron-scheduled worker is enqueued **by name from YAML**, so
+`NightlyReportWorker` can appear nowhere in your code. Without help,
+[`rigor unused`](../02-cli-reference.md#rigor-unused) reports a job
+that runs every night as possibly dead. This plugin supplies the
+workers your schedule names, so they drop out of the candidate list:
+
+```yaml
+# config/schedule.yml (sidekiq-cron)      config/sidekiq.yml (sidekiq-scheduler)
+nightly_report:                           :scheduler:
+  cron: "0 3 * * *"                         :schedule:
+  class: "NightlyReportWorker"                nightly_report:
+                                                every: "1h"
+                                                class: "NightlyReportWorker"
+```
+
+It reads the `class:` key and nothing else. In particular a **queue
+name is not a class name**: the `:queues:` list in `sidekiq.yml`
+supplies no roots, because inflecting `report_worker` into
+`ReportWorker` would root a worker on a naming coincidence. And a
+`class:` naming a worker the plugin never discovered is dropped rather
+than published, so a typo costs you a root instead of quietly hiding a
+dead worker.
+
+`MyWorker.perform_async` still supplies nothing — it is an ordinary
+constant reference the report already sees. Neither does the mere
+existence of a file under `app/workers`: a worker nothing enqueues
+stays in the report, which is the answer you wanted.
+
+The schedule is read with `YAML.safe_load`; nothing boots.
+A missing, unreadable or malformed file is skipped without affecting
+the rest of the run.
+
+If your workers include a project concern (`include ApplicationWorker`)
+rather than `Sidekiq::Job` directly, add that concern to
+`worker_marker_modules` — otherwise the plugin discovers no workers,
+every scheduled name is dropped, and you get no roots at all. GitLab's
+`config/schedule.yml` names 111 workers, all of them concern-based:
+with the default markers that is 0 roots, and with `ApplicationWorker`
+added it is 100.
+
 ## Limitations
 
 - **Direct `include` only.** A worker that mixes in a custom concern
@@ -68,6 +118,10 @@ The default `worker_marker_modules` covers both modern Sidekiq
   `perform_at` is consumed as the schedule regardless of its type.
 - **Chained `set(...)`** (`Worker.set(queue: "low").perform_async(...)`)
   is validated as a normal call; `set`'s own options are not checked.
+- **Schedule roots are read from `class:` only.** `sidekiq-cron`'s
+  alternative `klass:` spelling, and a schedule built in Ruby with
+  `Sidekiq::Cron::Job.load_from_hash!`, supply no roots — the worker
+  stays a `rigor unused` candidate rather than being guessed at.
 
 ## Plugin internals
 

data/lib/rigor/analysis/check_rules/rule_ids.rb

@@ -44,6 +44,28 @@ module Rigor
       # return, used in value context. Authored `:warning`, resolved `:off` by every profile and promoted to
       # `:warning` only by the `use-of-void-value` bleeding-edge feature.
       RULE_VALUE_USE_VOID = "static.value-use.void"
+      # ADR-103 WD8 / #383 — the first `effect.*` id: a method whose PROVEN effect labels are not
+      # subsumed by the envelope its author declared (`%a{pure}` / `%a{rigor:v1:effect ...}`). Opt-in
+      # twice over — the `effects:` block enables collection, and the envelope is the author's own
+      # directive — so it is never unsolicited.
+      RULE_EFFECT_ENVELOPE_EXCEEDED = "effect.envelope-exceeded"
+      # ADR-103 WD1 / #384 — the paired vocabulary diagnostic. An unknown label degrades the whole tag
+      # to ⊤, which is silent by construction; this is what keeps that fail-open reading honest. It
+      # fires only where label intent is evident (`Effects::LabelIntent`'s four signals), so a project
+      # opening its own vocabulary is never nagged, and it is gated by the same `effects.check` switch
+      # as its sibling: opting into envelope enforcement is exactly what turns on the diagnostic that
+      # says an envelope stopped enforcing.
+      RULE_EFFECT_UNKNOWN_LABEL = "effect.unknown-label"
+      # ADR-103 WD1 / WD14 / #386 — the inherited-bound reading. An override performs, or itself
+      # declares, an effect the envelope written on the method it overrides does not admit. Implementations
+      # may be purer than the bound they inherit, never less pure; both-sides-authored in the ADR-35 sense,
+      # so nothing fires unless someone wrote an envelope on the ancestor.
+      RULE_EFFECT_LISKOV_WIDENED = "effect.liskov-widened"
+      # ADR-103 WD13 commitment 1 / #384 — the residual. A project whose RBS carries `%a{pure}` /
+      # `%a{rigor:v1:effect …}` but no `effects:` block gets ONE `:info` per run saying so. An
+      # annotation must never turn collection on by itself (that would be a project-wide cost cliff
+      # nobody asked for), and it must equally never be silently inert.
+      RULE_EFFECT_ANNOTATIONS_UNCHECKED = "effect.annotations-unchecked"
 
       ALL_RULES = [
         RULE_UNDEFINED_METHOD,
@@ -72,7 +94,11 @@ module Rigor
         RULE_SUPPRESSION_UNKNOWN_RULE,
         RULE_SUPPRESSION_EMPTY,
         RULE_SUPPRESSION_UNKNOWN_MARKER,
-        RULE_VALUE_USE_VOID
+        RULE_VALUE_USE_VOID,
+        RULE_EFFECT_ENVELOPE_EXCEEDED,
+        RULE_EFFECT_LISKOV_WIDENED,
+        RULE_EFFECT_UNKNOWN_LABEL,
+        RULE_EFFECT_ANNOTATIONS_UNCHECKED
       ].freeze
 
       # Backward-compat alias table (ADR-8 § "Backward compatibility"). Existing user code with
@@ -102,7 +128,7 @@ module Rigor
 
       # Family wildcard — a `<family>` token in a suppression comment or `disable:` list disables every rule
       # whose canonical id starts with `<family>.`. Per ADR-8 § "1".
-      RULE_FAMILIES = %w[call flow assert dump def suppression static].freeze
+      RULE_FAMILIES = %w[call flow assert dump def suppression static effect].freeze
 
       # Families of diagnostics the engine emits OUTSIDE the CheckRules catalogue (aggregator-level and
       # reporter-level diagnostics such as `rbs_extended.unsatisfied-conformance`,

data/lib/rigor/analysis/incremental_session.rb

@@ -5,6 +5,9 @@ require_relative "incremental"
 require_relative "plugin_fact_fingerprint"
 require_relative "../cache/file_digest"
 require_relative "../cache/incremental_snapshot"
+require_relative "../effects/file_collection"
+require_relative "../effects/identity"
+require_relative "../effects/propagator"
 require_relative "../inference/scope_indexer"
 
 module Rigor
@@ -105,6 +108,7 @@ module Rigor
         # and a missing invalidation edge is impossible by construction — the reason this is a table diff
         # and not the caller→callee edge recording #204 first sketched.
         @param_table = {}
+        reset_effect_state
         # ADR-88 WD1 — the plugin fact-surface digest computed for THIS invocation (nil until a
         # `#run_incremental` pass runs / a plugin-free project) and the reporting flags a caller (the CLI
         # banner + `--cache-stats`) reads after `#run_incremental`. `@last_runner` is the analysis runner the
@@ -122,6 +126,32 @@ module Rigor
         @analyzed
       end
 
+      # ADR-103 WD12 / issue #382 — the session's effect graph: the fixpoint over the merged whole,
+      # recomputed on every ask. This is the invariant that makes per-file collection reuse sound — the
+      # closure is never partially reused, only its per-file *inputs* are, so a leaf edit whose new label
+      # reaches a caller in an unchanged file still shows up in that caller's `reach`.
+      def effect_table
+        Effects::Propagator.propagate(
+          effect_collection, discharge: Effects::Discharge.new(@configuration.effects_tolerated)
+        )
+      end
+
+      # The merged direct summaries the table above closes over.
+      def effect_collection
+        Effects::FileCollection.merge_all(sorted_effect_collections)
+      end
+
+      # Where each unit was defined — the same shape (and the same purpose: the snapshot's `reach:` globs)
+      # as `Runner#effect_sources`, answered from the session's own per-file collections.
+      def effect_sources
+        sorted_effect_collections.each_with_object({}) do |collection, out|
+          path = collection.path
+          next if path.nil?
+
+          collection.summaries.each_key { |key| (out[key] ||= []) << path }
+        end
+      end
+
       # Full baseline analysis with recording. Returns the run's diagnostics; populates the in-process cache
       # + dependency state.
       def baseline
@@ -135,6 +165,9 @@ module Rigor
         # ADR-67 WD6c lift — the seed table the runner's own pre-pass computed ({} when the gate is off).
         # Reading it back, rather than computing it here, keeps the baseline single-collect.
         @param_table = runner.param_inferred_types
+        # ADR-103 WD13 / #382 — a baseline collects every file, so its collections are the whole world.
+        @effect_collections = runner.effect_collections_by_path
+        @effects_identity = current_effects_identity
         @cache = per_file(diagnostics)
         @digests = @analyzed.to_h { |path| [path, pack_digest(path)] }
         diagnostics
@@ -417,10 +450,18 @@ module Rigor
           # (types with no fingerprint surface) make the snapshot un-reusable.
           if restored
             restore(restored)
+            # ADR-103 WD13 / #382 — the effects sidecar joins the same reuse decision, for a structurally
+            # identical reason: a snapshot whose summaries were collected under a different vocabulary /
+            # catalogue / `effects:` block restores as empty, and a recheck only re-collects the changed
+            # closure, so the merged table would be missing every unchanged file. A full baseline is the
+            # honest answer — it is what "recompute effects" means when collecting requires analysing, and
+            # it is paid on the first collecting run and on an identity change, never with collection off.
+            # Asked BEFORE the recheck, which re-stamps the session with the current identity.
+            effects_reusable = effects_reuse_permitted?(restored)
             result = recheck
             adopt_plugin_fact_fingerprint
-            reuse = @plugin_fact_reusable.reusable_against?(restored.plugin_fact_digest)
-            if reuse
+            fact_reusable = @plugin_fact_reusable.reusable_against?(restored.plugin_fact_digest)
+            if fact_reusable && effects_reusable
               diagnostics = result.diagnostics
               warm = true
               # ADR-87 WD3 — a warm recheck that changed nothing leaves the session state byte-equivalent to the
@@ -428,10 +469,12 @@ module Rigor
               # A cold baseline always persists — there was no valid snapshot to reuse.
               skip_save = result.no_change?
             else
-              # The fact surface moved (a plugin sig/catalog edit) or a plugin is opaque: the cached-served
-              # files the recheck merged may be stale, so re-analyze the whole tree. The current fact-surface
+              # The fact surface moved (a plugin sig/catalog edit), a plugin is opaque, or the effects
+              # identity moved: the cached-served files the recheck merged may be stale (or, for effects, a
+              # partial collection cannot be closed), so re-analyze the whole tree. The current fact-surface
               # digest (from the recheck runner) is unchanged by the re-analysis, so it is kept for the save.
-              @fact_surface_invalidated = true
+              # Only a genuine fact-surface reason sets the reporting flag the CLI banner reads.
+              @fact_surface_invalidated = true unless fact_reusable
               diagnostics = baseline
               warm = false
               skip_save = false
@@ -459,6 +502,12 @@ module Rigor
 
       private
 
+      # Path-sorted, so the fold is reproducible whatever order the files were absorbed in (the same reason
+      # `Runner#effect_collections` sorts).
+      def sorted_effect_collections
+        @effect_collections.sort_by { |path, _| path.to_s }.map(&:last)
+      end
+
       # ADR-88 WD1 — capture this invocation's fact-surface fingerprint (from the last analysis runner) onto the
       # reporting ivars + the `@plugin_fact_reusable` decision object.
       def adopt_plugin_fact_fingerprint
@@ -509,6 +558,12 @@ module Rigor
         @class_decls       = payload.class_decls || {}
         @return_summaries  = payload.return_summaries || {}
         @param_table       = payload.param_table || {} # ADR-67 WD6c lift — the seeds the cache was built under.
+        # ADR-103 WD13 / #382 — the effects sidecar rides its own identity, so a snapshot whose summaries
+        # were collected under a different vocabulary / catalogue / `effects:` block restores as EMPTY
+        # rather than as stale rows. {#run_incremental} turns that emptiness into a full baseline, because
+        # a partial re-collection cannot be closed into a whole-project fixpoint.
+        @effects_identity  = payload.effects_identity
+        @effect_collections = effect_collections_reusable?(payload) ? payload.effect_collections.dup : {}
         @symbol_dependents = Incremental.invert_symbols(@symbol_sources)
         @ancestry_dependents = Incremental.invert(@ancestry_sources)
         @negative_dependents = Incremental.invert(@missing)
@@ -522,10 +577,71 @@ module Rigor
           class_decls: @class_decls, seed_bundles: @seed_bundles,
           plugin_fact_digest: @plugin_fact_digest,
           return_summaries: marshal_safe_return_summaries,
-          param_table: marshal_safe_param_table
+          param_table: marshal_safe_param_table,
+          effect_collections: marshal_safe_effect_collections,
+          effects_identity: @effects_identity
         )
       end
 
+      # ADR-103 WD13 / issue #382 — the per-file effect collections the session serves unchanged files
+      # from, and the effects identity they were collected under. Empty / nil when collection is off, which
+      # is every run that does not carry an `effects:` block. The PROPAGATED table is never kept here:
+      # {#effect_table} re-runs the fixpoint over the merged whole on every ask, because a leaf's summary
+      # reaches every caller and there is no per-file invalidation for a whole-graph closure.
+      def reset_effect_state
+        @effect_collections = {}
+        @effects_identity = nil
+      end
+
+      # Whether the effects half of a restored snapshot permits reuse. Collection off is vacuously true —
+      # the session keeps no collections, writes none, and the pre-#382 reuse decision stands unchanged.
+      def effects_reuse_permitted?(payload)
+        !@configuration.effects_enabled? || effect_collections_reusable?(payload)
+      end
+
+      # ADR-103 WD13 / #382 — whether a restored payload's effect collections may be served this run:
+      # collection is on, and they were collected under the identity this run computes. Collection being
+      # OFF answers false and costs nothing — the session then keeps no collections, writes none, and is
+      # the pre-#382 session in every observable way.
+      def effect_collections_reusable?(payload)
+        return false unless @configuration.effects_enabled?
+        return false if payload.effects_identity.nil? || !payload.effect_collections.is_a?(Hash)
+
+        payload.effects_identity == current_effects_identity
+      end
+
+      # The effects identity for THIS run, memoised: it digests a YAML catalogue and the `effects:` block,
+      # and a recheck asks for it on both the restore and the absorb side. nil when collection is off, so a
+      # non-collecting run never loads the catalogue at all.
+      #
+      # **Deliberately plugin-blind**, unlike the ADR-45 whole-run effects slot, whose descriptor carries
+      # {Effects::PluginFacts#digest} (#387). The two sides of this comparison sit on opposite sides of the
+      # run: the restore asks before any plugin is loaded and the save asks after, so folding the plugin
+      # facts in here would compare a blind digest against a sighted one and miss every single time. The
+      # bound it leaves — a plugin upgrade that moves a row does not invalidate an `--incremental`
+      # snapshot's effect collections — is recorded in `docs/internal-spec/effect-summaries.md`; the
+      # primary (whole-run) path has no such hole, and `--incremental` is opt-in.
+      def current_effects_identity
+        return nil unless @configuration.effects_enabled?
+
+        @current_effects_identity ||= Effects::Identity.digest(configuration: @configuration)
+      end
+
+      # The same Marshal-clean guard {#marshal_safe_return_summaries} applies, for the same reason: a
+      # snapshot save must never raise. A dropped collection makes that file's summaries absent from the
+      # next run's merged table, which understates its effects — so it is dropped only when it genuinely
+      # will not serialise, and {FileCollection} is built to (the fork pool marshals one per file already).
+      def marshal_safe_effect_collections
+        return {} unless @configuration.effects_enabled?
+
+        @effect_collections.each_with_object({}) do |(path, collection), safe|
+          Marshal.dump(collection)
+          safe[path] = collection
+        rescue StandardError
+          next
+        end
+      end
+
       # ADR-89 WD2 — the return summaries filtered to Marshal-clean entries. A summary's `keys` hold live
       # `Type` objects; the common carriers (Nominal, Constant, Union, shapes, Dynamic) Marshal, but a type
       # holding a live AST node would raise and abort the WHOLE snapshot save (a cache must never break a
@@ -568,6 +684,21 @@ module Rigor
         end
         absorb_dependency_graph(runner)
         refresh_return_summaries(runner, analyze_set)
+        refresh_effect_collections(runner, analyze_set)
+      end
+
+      # ADR-103 WD13 / #382 — the effects analogue of {#refresh_return_summaries}, and the same soundness
+      # order: drop every re-analyzed file's collection first, then fold this run's harvest in. A file the
+      # recheck did NOT analyze keeps the collection the snapshot carried, which is exactly the reuse the
+      # slot exists for; a re-analyzed file that produced nothing (a parse failure, a file of constants)
+      # correctly ends up with nothing rather than with its pre-edit summaries.
+      def refresh_effect_collections(runner, analyze_set)
+        return unless @configuration.effects_enabled?
+
+        analyzed = analyze_set.to_set
+        @effect_collections.reject! { |path, _| analyzed.include?(path) }
+        @effect_collections.merge!(runner.effect_collections_by_path)
+        @effects_identity = current_effects_identity
       end
 
       # ADR-89 WD2 — replace the behavioural summaries of every re-analyzed file with THIS run's harvest: drop
@@ -599,6 +730,9 @@ module Rigor
         @symbol_fingerprints.delete(path)
         # ADR-89 WD2 — drop every behavioural summary a removed file provided (keys are `[path, symbol]`).
         @return_summaries.reject! { |(summary_path, _symbol), _| summary_path == path }
+        # ADR-103 WD13 / #382 — and its effect collection, so a deleted file stops contributing summaries
+        # and edges to the merged table the fixpoint closes.
+        @effect_collections.delete(path)
         # @class_decls is wholesale-replaced from the (removed-excluding)
         # pre-pass in absorb_dependency_graph, and is frozen, so no delete.
       end

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

@@ -0,0 +1,244 @@
+# frozen_string_literal: true
+
+require_relative "scan"
+
+module Rigor
+  module Analysis
+    module Reachability
+      # 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).
+      #
+      # Resolution mirrors `Reflection.resolve_constant_type`'s candidate order — lexical nesting innermost
+      # first, then the ancestors of the innermost cresting scope, then the bare name — because a reference
+      # index that resolved names differently from the engine would report on a graph the analyzer does not
+      # 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
+        Candidate = Data.define(:fqn, :path, :line)
+
+        # `test_only` is its own list, not a flag on `candidates`: a candidate is by definition unreachable, so
+        # a flag there could never be true. "Reachable, but only from test code" is a SEPARATE and more
+        # actionable answer — dead production code with a live test — which is exactly what ADR-102 WD8 requires
+        # be reported as its own category rather than folded into a bucket boundary.
+        Report = Data.define(:declared, :reachable, :candidates, :undecidable, :test_only, :namespaces,
+                             :roots, :edges)
+
+        # A candidate demoted out of `candidates` because something can reach it by a mechanism this reading
+        # cannot follow (ADR-102 WD4). Carries the reason so the reader can judge it rather than take the
+        # bucket on trust.
+        Undecidable = Data.define(:fqn, :path, :line, :reason)
+
+        # @param declarations [Array<Scan::Declaration>]
+        # @param references [Array<Scan::Reference>]
+        # @param root_fqns [Enumerable<String>] declarations that are entry points regardless of who references
+        #   them (config-declared globs in this slice; plugin-supplied roots are #349).
+        # @param foreign [#call] predicate answering "is this FQN owned by something outside the project?" —
+        #   a reopened gem or stdlib class must never be a candidate (WD6). Defaults to "nothing is foreign".
+        # @param dynamic_uses [Array<Scan::DynamicUse>] 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 })
+          @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)
+          @owned = @by_fqn.keys.reject { |fqn| @foreign.call(fqn) }.to_set
+          @ancestors = {}
+        end
+
+        def report
+          edges = resolved_edges
+          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)
+          undecidable = tainted(unreached - namespaces)
+          Report.new(declared: @owned.size, reachable: reachable.size,
+                     candidates: rows(unreached - namespaces - undecidable.keys.to_set),
+                     undecidable: undecidable.map { |fqn, reason| undecidable_row(fqn, reason) }.freeze,
+                     test_only: rows(reachable - production),
+                     namespaces: namespaces.size, roots: production_seeds.size, edges: edges.size)
+        end
+
+        private
+
+        # 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)
+          end
+        end
+
+        # `{fqn => reason}` for every unreached declaration 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
+        # report and teach the reader that the tier means nothing.
+        def tainted(unreached)
+          prefixes = @dynamic_uses.filter_map { |use| [use.prefix, use] if use.name.nil? && use.prefix }
+
+          return {} if prefixes.empty?
+
+          unreached.each_with_object({}) do |fqn, out|
+            _, use = prefixes.find { |prefix, _| fqn == prefix || fqn.start_with?("#{prefix}::") }
+            out[fqn] = use.site.nil? ? use.reason : "#{use.reason} (#{use.site})" if use
+          end
+        end
+
+        def undecidable_row(fqn, reason)
+          site = @by_fqn.fetch(fqn).first
+          Undecidable.new(fqn: fqn, path: site.path, line: site.line, reason: reason)
+        end
+
+        # `module A; end` wrapping a live `A::B` is not dead code, but nothing ever references `A` by itself:
+        # a reference to `A::B::Leaf` records the leaf only, never the intermediate segments. Reporting these
+        # buried the real rows — 12 of 18 candidates on Rigor's own `lib`, and 22 of 140 in the #345 probe,
+        # were pure namespaces.
+        #
+        # The test is deliberately "some REACHABLE declaration lives under it", not "some declaration lives
+        # under it": a namespace whose entire contents are dead is itself a genuine finding, and its children
+        # appear alongside it rather than being explained away.
+        def namespace_only(unreached, reachable)
+          unreached.select do |fqn|
+            prefix = "#{fqn}::"
+            reachable.any? { |other| other.start_with?(prefix) }
+          end.to_set
+        end
+
+        # 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 }
+        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 }
+        end
+
+        def seeds_from
+          set = Set.new
+          @references.each do |ref|
+            next unless yield(ref)
+
+            target = resolve(ref.as_written, ref.nesting)
+            set << target if target && @owned.include?(target)
+          end
+          set
+        end
+
+        # `[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)
+            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]
+          end
+        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).
+        #
+        # Run twice with different edge roles admitted (WD8). The production pass admits everything except
+        # test-sourced edges; the full pass admits all of them. The difference is exactly "reachable, but only
+        # from test code" — dead production code with a live test, which is a finding rather than a bucket edge.
+        def walk(edges, seeds:, roles:)
+          admitted = roles.to_set
+          out = Hash.new { |h, k| h[k] = [] }
+          edges.each { |from, to, role| out[from] << to if admitted.include?(role) }
+
+          seen = seeds.dup
+          queue = seeds.to_a
+          until queue.empty?
+            out[queue.shift].each do |target|
+              next if seen.include?(target)
+
+              seen << target
+              queue << target
+            end
+          end
+          seen
+        end
+
+        def rows(fqns)
+          fqns.sort.map do |fqn|
+            site = @by_fqn.fetch(fqn).first
+            Candidate.new(fqn: fqn, path: site.path, line: site.line)
+          end.freeze
+        end
+
+        # Ruby's constant lookup at name granularity: `Module.nesting` innermost first, then the ancestors of
+        # the innermost cresting scope (#354), then the bare name.
+        def resolve(as_written, nesting)
+          walker = nesting.dup
+          until walker.empty?
+            candidate = (walker + [as_written]).join("::")
+            return candidate if @by_fqn.key?(candidate)
+
+            walker.pop
+          end
+
+          unless nesting.empty?
+            ancestor_scopes(nesting.join("::")).each do |ancestor|
+              candidate = "#{ancestor}::#{as_written}"
+              return candidate if @by_fqn.key?(candidate)
+            end
+          end
+
+          return as_written if @by_fqn.key?(as_written)
+
+          # `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
+          # `Scope::DiscoveryIndex` would be reported as unused despite being read all over the engine (it was,
+          # 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
+        end
+
+        # Breadth-first over superclass + included modules, mixins first, terminating on a cycle. As-written
+        # ancestor names resolve against the subclass's own nesting; a name naming no declaration is dropped.
+        def ancestor_scopes(fqn)
+          @ancestors[fqn] ||= begin
+            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|
+                  resolved = resolve_ancestor(current, raw)
+                  next if resolved.nil? || seen.include?(resolved)
+
+                  seen << resolved
+                  out << resolved
+                  queue << resolved
+                end
+              end
+            end
+            out.freeze
+          end
+        end
+
+        def resolve_ancestor(subclass_fqn, raw)
+          segments = subclass_fqn.split("::")
+          (segments.length - 1).downto(0) do |i|
+            candidate = (segments[0, i] + [raw]).join("::")
+            return candidate if @by_fqn.key?(candidate)
+          end
+          nil
+        end
+      end
+    end
+  end
+end