rigortype 0.3.2 → 0.3.4

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

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