rigortype 0.4.2 → 0.4.4

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,141 @@ 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]
+          runtime = use.receiver_open ? runtime_targets(receiver, name, use.inherit, local) : []
+          own = declared_member(receiver, name, local)
+          return [own, *runtime].uniq if own
+          return runtime unless use.inherit
+
+          (plausible_ancestors(receiver).filter_map { |scope| declared_member(scope, name, local) } + runtime)
+            .uniq + [nil]
+        end
+
+        # The declarations a descendant of `receiver` holding `name` adds (#1878): a `self` standing for the
+        # enclosing declaration is whichever subclass, includer, prepender or extender the method runs on, and
+        # Ruby looks the name up there first. Each descendant is searched with its own ancestors unless the call
+        # passes `inherit = false`. The descendants are over-approximated as {#plausible_ancestors} is.
+        def runtime_targets(receiver, name, inherit, local)
+          descendants_of(receiver).flat_map do |descendant|
+            scopes = inherit ? [descendant, *plausible_ancestors(descendant)] : [descendant]
+            scopes.filter_map { |scope| declared_member(scope, name, local) }
+          end.uniq
+        end
+
+        def descendants_of(fqn)
+          @plausible_descendants ||= @by_fqn.keys.each_with_object(Hash.new { |h, k| h[k] = [] }) do |declared, out|
+            plausible_ancestors(declared).each { |ancestor| out[ancestor] << declared }
+          end
+          @plausible_descendants.fetch(fqn, [])
+        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 +150,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
@@ -40,7 +177,6 @@ module Rigor
         def initialize(declarations:, references:, root_fqns: [], dynamic_uses: [], shadows: [],
                        foreign: ->(_fqn) { false })
           @declarations = declarations
-          @references = references + literal_dynamic_references(dynamic_uses)
           @root_fqns = root_fqns.to_set
           @foreign = foreign
           @by_fqn = declarations.group_by(&:fqn)
@@ -48,8 +184,9 @@ module Rigor
           @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| use.anchored { |ref| resolve_ref(ref) } }
+          @dynamic_uses = dynamic_uses.flat_map { |use| anchored(use) }
         end
 
         def report
@@ -87,19 +224,6 @@ module Rigor
                      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