rigortype 0.1.15 → 0.1.17

data/lib/rigor/analysis/check_rules.rb

@@ -6,9 +6,12 @@ require_relative "../reflection"
 require_relative "../source/node_walker"
 require_relative "../type"
 require_relative "diagnostic"
+require_relative "dependency_recorder"
 require_relative "check_rules/always_truthy_condition_collector"
+require_relative "check_rules/unreachable_clause_collector"
 require_relative "check_rules/dead_assignment_collector"
 require_relative "check_rules/ivar_write_collector"
+require_relative "check_rules/self_closedness_scanner"
 
 module Rigor
   module Analysis
@@ -57,6 +60,7 @@ module Rigor
       # system; new rules MUST register here so user configuration
       # can refer to them.
       RULE_UNDEFINED_METHOD = "call.undefined-method"
+      RULE_SELF_UNDEFINED_METHOD = "call.self-undefined-method"
       RULE_UNRESOLVED_TOPLEVEL = "call.unresolved-toplevel"
       RULE_WRONG_ARITY = "call.wrong-arity"
       RULE_ARGUMENT_TYPE = "call.argument-type-mismatch"
@@ -73,9 +77,11 @@ module Rigor
       RULE_IVAR_WRITE_MISMATCH = "def.ivar-write-mismatch"
       RULE_DEAD_ASSIGNMENT = "flow.dead-assignment"
       RULE_ALWAYS_TRUTHY_CONDITION = "flow.always-truthy-condition"
+      RULE_UNREACHABLE_CLAUSE = "flow.unreachable-clause"
 
       ALL_RULES = [
         RULE_UNDEFINED_METHOD,
+        RULE_SELF_UNDEFINED_METHOD,
         RULE_UNRESOLVED_TOPLEVEL,
         RULE_WRONG_ARITY,
         RULE_ARGUMENT_TYPE,
@@ -86,6 +92,7 @@ module Rigor
         RULE_UNREACHABLE_BRANCH,
         RULE_DEAD_ASSIGNMENT,
         RULE_ALWAYS_TRUTHY_CONDITION,
+        RULE_UNREACHABLE_CLAUSE,
         RULE_RETURN_TYPE,
         RULE_VISIBILITY_MISMATCH,
         RULE_OVERRIDE_VISIBILITY_REDUCED,
@@ -104,6 +111,7 @@ module Rigor
       # both spellings resolve identically.
       LEGACY_RULE_ALIASES = {
         "undefined-method" => RULE_UNDEFINED_METHOD,
+        "self-undefined-method" => RULE_SELF_UNDEFINED_METHOD,
         "wrong-arity" => RULE_WRONG_ARITY,
         "argument-type-mismatch" => RULE_ARGUMENT_TYPE,
         "possible-nil-receiver" => RULE_NIL_RECEIVER,
@@ -114,7 +122,8 @@ module Rigor
         "method-visibility-mismatch" => RULE_VISIBILITY_MISMATCH,
         "ivar-write-mismatch" => RULE_IVAR_WRITE_MISMATCH,
         "dead-assignment" => RULE_DEAD_ASSIGNMENT,
-        "always-truthy-condition" => RULE_ALWAYS_TRUTHY_CONDITION
+        "always-truthy-condition" => RULE_ALWAYS_TRUTHY_CONDITION,
+        "unreachable-clause" => RULE_UNREACHABLE_CLAUSE
       }.freeze
 
       # Family wildcard — a `<family>` token in a suppression
@@ -153,7 +162,7 @@ module Rigor
       # @param root [Prism::Node]
       # @param scope_index [Hash{Prism::Node => Rigor::Scope}]
       # @return [Array<Rigor::Analysis::Diagnostic>]
-      def diagnose(path:, root:, scope_index:, comments: [], disabled_rules: [])
+      def diagnose(path:, root:, scope_index:, self_call_misses: [], comments: [], disabled_rules: [])
         diagnostics = []
         Source::NodeWalker.each(root) do |node|
           case node
@@ -173,7 +182,9 @@ module Rigor
             diagnostics << unreachable if unreachable
           end
         end
+        diagnostics.concat(self_undefined_method_diagnostics(path, self_call_misses, root, scope_index))
         diagnostics.concat(always_truthy_condition_diagnostics(path, root, scope_index))
+        diagnostics.concat(unreachable_clause_diagnostics(path, root, scope_index))
         diagnostics.concat(ivar_write_mismatch_diagnostics(path, root, scope_index))
         diagnostics.concat(dead_assignment_diagnostics(path, root, scope_index))
         filter_suppressed(diagnostics, comments: comments, disabled_rules: disabled_rules)
@@ -246,6 +257,16 @@ module Rigor
         end
       end
 
+      # ADR-47 — `flow.unreachable-clause`. One diagnostic per `when` clause
+      # the flow engine's narrowing proves can never match (its narrowed
+      # subject is `bot`). The squiggle lands on the dead clause's body,
+      # mirroring `flow.unreachable-branch`.
+      def unreachable_clause_diagnostics(path, root, scope_index)
+        UnreachableClauseCollector.new(scope_index).collect(root).map do |result|
+          build_unreachable_clause_diagnostic(path, result)
+        end
+      end
+
       def ivar_mismatch_diagnostics_for(path, class_name, ivar_name, writes)
         return [] if writes.size < 2
 
@@ -383,7 +404,16 @@ module Rigor
           # its model). Flagging an undefined method on a class
           # with an open dynamic surface is unsound, so the rule
           # skips it.
-          return nil if open_receiver?(class_name, scope)
+          # An unbounded receiver surface: either a plugin-declared
+          # open receiver (ADR-26 — e.g. `ActiveRecord::Relation`), or
+          # a type Rigor synthesized (a missing-namespace module / a
+          # stub for a referenced-but-undeclared type) to keep a
+          # malformed project signature buildable. A synthesized stub's
+          # method table is empty only because Rigor invented it, not
+          # because the real type is empty (the real `DRb` has
+          # `start_service`), so enumerating it to prove a call
+          # "undefined" would be a false positive.
+          return nil if unbounded_receiver_surface?(class_name, scope)
 
           # Slice 7 phase 12 — suppress when the user has
           # declared the method in source (`def` /
@@ -518,11 +548,9 @@ module Rigor
         end
 
         def build_unresolved_toplevel_diagnostic(path, call_node)
-          location = call_node.message_loc || call_node.location
-          Diagnostic.new(
+          Diagnostic.from_message_loc(
+            call_node,
             path: path,
-            line: location.start_line,
-            column: location.start_column + 1,
             message: "unresolved toplevel call to `#{call_node.name}`. " \
                      "If a project file defines `#{call_node.name}` via a toplevel " \
                      "`def` or a monkey-patch on Object/Kernel, list that file in " \
@@ -566,6 +594,14 @@ module Rigor
         # loaded plugin (manifest `open_receivers:`). An open
         # class responds beyond its RBS surface, so the
         # `call.undefined-method` rule must not fire for it.
+        # True when the receiver class responds beyond an enumerable
+        # RBS method table, so proving a call "undefined" against it is
+        # unsound: a plugin-declared open receiver, or a Rigor-
+        # synthesized stub type (see `RbsLoader#synthesized_type_names`).
+        def unbounded_receiver_surface?(class_name, scope)
+          open_receiver?(class_name, scope) || synthesized_stub_receiver?(class_name, scope)
+        end
+
         def open_receiver?(class_name, scope)
           registry = scope.environment&.plugin_registry
           return false if registry.nil?
@@ -573,6 +609,13 @@ module Rigor
           registry.open_receiver?(class_name)
         end
 
+        def synthesized_stub_receiver?(class_name, scope)
+          loader = scope.environment&.rbs_loader
+          return false if loader.nil? || !loader.respond_to?(:synthesized_type_names)
+
+          loader.synthesized_type_names.include?(class_name.to_s.sub(/\A::/, ""))
+        end
+
         def definition_available?(receiver_type, class_name, scope)
           if receiver_type.is_a?(Type::Singleton)
             !Rigor::Reflection.singleton_definition(class_name, scope: scope).nil?
@@ -581,6 +624,65 @@ module Rigor
           end
         end
 
+        # ADR-24 slice 4 — `call.self-undefined-method`. Consumes the engine's
+        # recorded unresolved implicit-self calls
+        # ({Analysis::SelfCallResolutionRecorder}) and adds only the
+        # closedness POLICY — it NEVER recomputes resolution (the reverted
+        # attempt-1 mistake that produced 135 FPs). A miss reaches here only
+        # because the engine's real resolution found the method nowhere.
+        #
+        # The v1 gate is deliberately the most conservative "confidently
+        # closed" shape: a STANDALONE project class — no superclass and no
+        # `include`/`prepend` (so its in-file method surface is complete) —
+        # that is not a module / mixin contract, defines no `method_missing`,
+        # has no dynamic `attr_*(*splat)` accessor, and is not an ADR-26 open
+        # receiver. Widening to superclass / include chains is a later slice,
+        # each behind the external corpus FP gate. Authored `:warning` but
+        # mapped to `:off` in every shipped profile until that gate is green
+        # (ADR-24 § "Slice 4"); a project opts in via `severity_overrides:`.
+        def self_undefined_method_diagnostics(path, self_call_misses, root, scope_index)
+          return [] if self_call_misses.empty?
+
+          open_names = SelfClosednessScanner.new(root).open_class_names
+          self_call_misses.filter_map do |miss|
+            next if open_names.include?(miss.class_name)
+
+            scope = scope_index[miss.node]
+            next if scope.nil?
+            next unless confidently_closed_self_class?(miss.class_name, scope)
+
+            build_self_undefined_method_diagnostic(path, miss)
+          end
+        end
+
+        def confidently_closed_self_class?(class_name, scope)
+          return false if unbounded_receiver_surface?(class_name, scope)
+          return false if scope.discovered_method?(class_name, :method_missing, :instance)
+          # A superclass or mixin extends the surface beyond what this file
+          # declares; the engine's ancestor walk may have hit an unresolvable
+          # ancestor, so a miss is not provably a typo. Defer to a later slice.
+          return false if scope.superclass_of(class_name)
+          return false unless scope.includes_of(class_name).empty?
+
+          true
+        end
+
+        def build_self_undefined_method_diagnostic(path, miss)
+          Diagnostic.new(
+            path: path,
+            line: miss.line || 1,
+            column: miss.column || 1,
+            message: "implicit-self call to `#{miss.method_name}` resolves to no method on " \
+                     "`#{miss.class_name}` (a standalone class with a complete, project-known " \
+                     "method surface). Likely a typo or a missing `def`.",
+            severity: :warning,
+            rule: RULE_SELF_UNDEFINED_METHOD,
+            source_family: :builtin,
+            receiver_type: miss.class_name,
+            method_name: miss.method_name
+          )
+        end
+
         def lookup_method(receiver_type, class_name, method_name, scope)
           if receiver_type.is_a?(Type::Singleton)
             Rigor::Reflection.singleton_method_definition(class_name, method_name, scope: scope)
@@ -808,11 +910,9 @@ module Rigor
           return nil if inside_rigor_testing?(scope)
 
           type = scope.type_of(arg)
-          location = call_node.message_loc || call_node.location
-          Diagnostic.new(
+          Diagnostic.from_message_loc(
+            call_node,
             path: path,
-            line: location.start_line,
-            column: location.start_column + 1,
             message: "dump_type: #{type.describe(:short)}",
             severity: :info,
             rule: RULE_DUMP_TYPE
@@ -905,24 +1005,20 @@ module Rigor
         end
 
         def build_assert_type_diagnostic(path, call_node, expected, actual)
-          location = call_node.message_loc || call_node.location
-          Diagnostic.new(
+          Diagnostic.from_message_loc(
+            call_node,
             rule: RULE_ASSERT_TYPE,
             path: path,
-            line: location.start_line,
-            column: location.start_column + 1,
             message: "assert_type mismatch: expected #{expected.inspect}, got #{actual.inspect}",
             severity: :error
           )
         end
 
         def build_nil_receiver_diagnostic(path, call_node)
-          location = call_node.message_loc || call_node.location
-          Diagnostic.new(
+          Diagnostic.from_message_loc(
+            call_node,
             rule: RULE_NIL_RECEIVER,
             path: path,
-            line: location.start_line,
-            column: location.start_column + 1,
             message: "possible nil receiver: `#{call_node.name}' is undefined on NilClass",
             severity: :error
           )
@@ -985,12 +1081,10 @@ module Rigor
         end
 
         def build_always_raises_diagnostic(path, call_node)
-          location = call_node.message_loc || call_node.location
-          Diagnostic.new(
+          Diagnostic.from_message_loc(
+            call_node,
             rule: RULE_ALWAYS_RAISES,
             path: path,
-            line: location.start_line,
-            column: location.start_column + 1,
             message: "always raises ZeroDivisionError: `#{call_node.name}' by zero on Integer receiver",
             severity: :error
           )
@@ -1109,12 +1203,10 @@ module Rigor
         end
 
         def build_visibility_mismatch_diagnostic(path, call_node, receiver_type)
-          location = call_node.message_loc || call_node.location
-          Diagnostic.new(
+          Diagnostic.from_message_loc(
+            call_node,
             rule: RULE_VISIBILITY_MISMATCH,
             path: path,
-            line: location.start_line,
-            column: location.start_column + 1,
             message: "private method `#{call_node.name}' called on #{receiver_type.class_name} receiver",
             severity: :error
           )
@@ -1142,36 +1234,55 @@ module Rigor
         end
 
         def build_always_truthy_condition_diagnostic(path, predicate_node, polarity)
-          location = predicate_node.location
-          Diagnostic.new(
+          Diagnostic.from_node(
+            predicate_node,
             rule: RULE_ALWAYS_TRUTHY_CONDITION,
             path: path,
-            line: location.start_line,
-            column: location.start_column + 1,
             message: "condition is always #{polarity} (the surrounding flow proves it folds to a constant)",
             severity: :warning
           )
         end
 
+        def build_unreachable_clause_diagnostic(path, result)
+          Diagnostic.from_node(
+            result.body,
+            rule: RULE_UNREACHABLE_CLAUSE,
+            path: path,
+            message: unreachable_clause_message(result),
+            severity: :warning
+          )
+        end
+
+        def unreachable_clause_message(result)
+          subject = result.subject_name
+          kw = result.keyword
+          case result.kind
+          when :prior_exhaustion
+            "unreachable `#{kw} #{result.condition_source}': `#{subject}' is already covered " \
+            "by an earlier `#{kw}' clause"
+          when :exhausted_else
+            "unreachable `else': the `#{kw}' clauses already cover every value `#{subject}' can take here"
+          else # :disjoint
+            "unreachable `#{kw} #{result.condition_source}': `#{subject}' can never be " \
+            "#{result.condition_source} here (the flow proves the subject disjoint)"
+          end
+        end
+
         def build_dead_assignment_diagnostic(path, write_node, def_node)
-          location = write_node.name_loc || write_node.location
-          Diagnostic.new(
+          Diagnostic.from_name_loc(
+            write_node,
             rule: RULE_DEAD_ASSIGNMENT,
             path: path,
-            line: location.start_line,
-            column: location.start_column + 1,
             message: "local `#{write_node.name}' assigned in `#{def_node.name}' but never read",
             severity: :warning
           )
         end
 
         def build_ivar_write_mismatch_diagnostic(path, node, class_name, ivar_name, first_class, other_class)
-          location = node.name_loc || node.location
-          Diagnostic.new(
+          Diagnostic.from_name_loc(
+            node,
             rule: RULE_IVAR_WRITE_MISMATCH,
             path: path,
-            line: location.start_line,
-            column: location.start_column + 1,
             message: "instance variable `#{ivar_name}' on #{class_name} was previously assigned " \
                      "#{first_class}; this write assigns #{other_class}",
             severity: :error
@@ -1190,12 +1301,10 @@ module Rigor
         end
 
         def build_unreachable_branch_diagnostic(path, dead_branch, polarity)
-          location = dead_branch.location
-          Diagnostic.new(
+          Diagnostic.from_node(
+            dead_branch,
             rule: RULE_UNREACHABLE_BRANCH,
             path: path,
-            line: location.start_line,
-            column: location.start_column + 1,
             message: "unreachable branch: literal predicate is always #{polarity}",
             severity: :warning
           )
@@ -1324,39 +1433,34 @@ module Rigor
         end
 
         def build_argument_type_diagnostic(path, call_node, class_name, mismatch)
-          location = mismatch[:node].location
           method_label = "`#{call_node.name}' on #{class_name}"
           parameter_label = mismatch[:name] ? "parameter `#{mismatch[:name]}' of #{method_label}" : method_label
           message = "argument type mismatch at #{parameter_label}: " \
                     "expected #{mismatch[:expected].describe(:short)}, " \
                     "got #{mismatch[:actual].describe(:short)}"
-          Diagnostic.new(
+          Diagnostic.from_node(
+            mismatch[:node],
             rule: RULE_ARGUMENT_TYPE,
             path: path,
-            line: location.start_line,
-            column: location.start_column + 1,
             message: message,
             severity: :error
           )
         end
 
         def build_arity_diagnostic(path, call_node, class_name, min, max, actual)
-          location = call_node.message_loc || call_node.location
           range = min == max ? min.to_s : "#{min}..#{max}"
           method_label = "`#{call_node.name}' on #{class_name}"
           message = "wrong number of arguments to #{method_label} (given #{actual}, expected #{range})"
-          Diagnostic.new(
+          Diagnostic.from_message_loc(
+            call_node,
             rule: RULE_WRONG_ARITY,
             path: path,
-            line: location.start_line,
-            column: location.start_column + 1,
             message: message,
             severity: :error
           )
         end
 
         def build_undefined_method_diagnostic(path, call_node, receiver_type, definition_site = nil, class_name = nil)
-          location = call_node.message_loc || call_node.location
           rendered_receiver = receiver_type.describe
           message = "undefined method `#{call_node.name}' for #{rendered_receiver}"
           # ADR-17 — when the project itself defines this method on the
@@ -1372,11 +1476,10 @@ module Rigor
                        "#{definition_site} — Rigor does not apply project monkey-patches " \
                        "cross-file; list that file in `.rigor.yml`'s `pre_eval:` (ADR-17)"
           end
-          Diagnostic.new(
+          Diagnostic.from_message_loc(
+            call_node,
             rule: RULE_UNDEFINED_METHOD,
             path: path,
-            line: location.start_line,
-            column: location.start_column + 1,
             message: message,
             severity: :error,
             receiver_type: rendered_receiver,
@@ -1520,12 +1623,10 @@ module Rigor
         end
 
         def build_return_type_mismatch_diagnostic(path, def_node, declared, inferred, severity)
-          location = def_node.name_loc || def_node.location
-          Diagnostic.new(
+          Diagnostic.from_name_loc(
+            def_node,
             rule: RULE_RETURN_TYPE,
             path: path,
-            line: location.start_line,
-            column: location.start_column + 1,
             message: "return-type mismatch on `#{def_node.name}': " \
                      "declared #{declared.describe(:short)}, inferred #{inferred.describe(:short)}",
             severity: severity
@@ -1655,6 +1756,14 @@ module Rigor
             candidate = (segments[0, i] + [raw_ancestor]).join("::")
             return candidate if known_user_class?(scope, candidate)
           end
+          # ADR-46 slice 3 — the override checker reads the class graph
+          # directly (not through the recorder's `Scope` choke points), and
+          # short-circuits when the ancestor resolves to no project class, so
+          # an incremental re-check has no edge telling it to re-check this
+          # subclass when that ancestor is later defined. Record a negative
+          # class edge (keyed on the unqualified name) so the appeared-class
+          # widening picks it up.
+          DependencyRecorder.read_missing(:class, raw_ancestor.to_s.split("::").last) if DependencyRecorder.active?
           nil
         end
 
@@ -1665,12 +1774,10 @@ module Rigor
         end
 
         def build_override_visibility_diagnostic(path, def_node, parent_class, parent_visibility, override_visibility)
-          location = def_node.name_loc || def_node.location
-          Diagnostic.new(
+          Diagnostic.from_name_loc(
+            def_node,
             rule: RULE_OVERRIDE_VISIBILITY_REDUCED,
             path: path,
-            line: location.start_line,
-            column: location.start_column + 1,
             message: "visibility of `#{def_node.name}' reduced from #{parent_visibility} to " \
                      "#{override_visibility} (overrides #{parent_class}##{def_node.name}); " \
                      "breaks substitutability",
@@ -1760,12 +1867,10 @@ module Rigor
         end
 
         def build_override_return_widened_diagnostic(path, def_node, parent_class, parent_return, override_return)
-          location = def_node.name_loc || def_node.location
-          Diagnostic.new(
+          Diagnostic.from_name_loc(
+            def_node,
             rule: RULE_OVERRIDE_RETURN_WIDENED,
             path: path,
-            line: location.start_line,
-            column: location.start_column + 1,
             message: "return type of `#{def_node.name}' widened from #{parent_return.describe(:short)} " \
                      "to #{override_return.describe(:short)} (overrides #{parent_class}##{def_node.name}); " \
                      "breaks substitutability",
@@ -1866,12 +1971,10 @@ module Rigor
         end
 
         def build_override_param_narrowed_diagnostic(path, def_node, parent_class, index, parent_param, override_param)
-          location = def_node.name_loc || def_node.location
-          Diagnostic.new(
+          Diagnostic.from_name_loc(
+            def_node,
             rule: RULE_OVERRIDE_PARAM_NARROWED,
             path: path,
-            line: location.start_line,
-            column: location.start_column + 1,
             message: "parameter #{index + 1} of `#{def_node.name}' narrowed from " \
                      "#{parent_param.describe(:short)} to #{override_param.describe(:short)} " \
                      "(overrides #{parent_class}##{def_node.name}); breaks substitutability",

data/lib/rigor/analysis/dependency_recorder.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+module Rigor
+  module Analysis
+    # ADR-46 slice 1 — records, per analyzed file, which OTHER source
+    # files its analysis read declarations / method bodies from (the
+    # cross-file dependency edges), plus the cross-file lookups that
+    # resolved to nothing (negative edges — adding that symbol later must
+    # re-check the consumer).
+    #
+    # Thread-local and activated per `analyze_file` only when the runner
+    # opts in (`record_dependencies: true`); a normal run never activates
+    # it, so {active?} is a single nil-check and the instrumented `Scope`
+    # accessors pay nothing. Recording is purely observational — it never
+    # changes a diagnostic.
+    #
+    # Modelled on {Inference::BudgetTrace}: process-thread-local state, a
+    # cheap disabled fast path, and a frozen snapshot for consumers.
+    module DependencyRecorder
+      KEY = :__rigor_dependency_recorder__
+      private_constant :KEY
+
+      # Mutable per-consumer accumulator. Frozen into a {Record} snapshot
+      # when `record_for` returns.
+      class Accumulator
+        attr_reader :consumer, :sources, :missing, :symbol_sources, :ancestry_sources
+
+        def initialize(consumer)
+          @consumer = consumer
+          @sources = Set.new
+          @missing = Set.new
+          # ADR-46 slice 4 — symbol-granularity tracking.
+          # `symbol_sources`: source_path → Set<"ClassName#method"> for method-call deps.
+          # `ancestry_sources`: Set<source_path> for class-ancestry (superclass / include)
+          # deps — file-granularity by nature (a superclass edge touches the whole class).
+          @symbol_sources = Hash.new { |h, k| h[k] = Set.new }
+          @ancestry_sources = Set.new
+        end
+
+        def snapshot
+          frozen_sym = @symbol_sources.transform_values(&:freeze).freeze
+          Record.new(
+            consumer: consumer,
+            sources: sources.dup.freeze,
+            missing: missing.dup.freeze,
+            symbol_sources: frozen_sym,
+            ancestry_sources: ancestry_sources.dup.freeze
+          )
+        end
+      end
+
+      # Frozen record of one file's cross-file reads.
+      # `symbol_sources`: source_path → frozen Set<"ClassName#method"> (method-call edges).
+      # `ancestry_sources`: frozen Set<source_path> (class-ancestry edges, file-granularity).
+      Record = Data.define(:consumer, :sources, :missing, :symbol_sources, :ancestry_sources)
+
+      # Module-level activation count so the disabled fast path
+      # ({active?}) is a plain integer read rather than a `Thread.current`
+      # hash lookup — `user_def_for` (the instrumented accessor) is on the
+      # per-dispatch hot path, so a normal (non-recording) run must pay as
+      # little as possible. The per-thread accumulator still isolates the
+      # actual recording, so a non-recording thread seeing `active?` true
+      # (another thread is recording) just performs an extra nil-check.
+      @active_count = 0
+      @mutex = Mutex.new
+
+      module_function
+
+      # Activates recording for `consumer` (the path being analyzed) for
+      # the duration of the block and returns the frozen {Record}. Nests
+      # safely (the inner consumer's reads do not leak to the outer one);
+      # restores the previous recorder on exit.
+      def record_for(consumer)
+        previous = Thread.current[KEY]
+        accumulator = Accumulator.new(consumer.to_s)
+        Thread.current[KEY] = accumulator
+        @mutex.synchronize { @active_count += 1 }
+        yield
+        accumulator.snapshot
+      ensure
+        Thread.current[KEY] = previous
+        @mutex.synchronize { @active_count -= 1 }
+      end
+
+      # Plain integer read (GVL-atomic) — no `Thread.current` lookup on the
+      # disabled fast path.
+      def active?
+        @active_count.positive?
+      end
+
+      # Records that the current consumer read a declaration / body whose
+      # definition site is `path_line` (a `"path:line"` String, or nil).
+      # When `symbol` is given (a `"ClassName#method"` String), the read is
+      # a method-call edge and is recorded at symbol granularity in
+      # `symbol_sources` in addition to the coarse `sources` set.
+      # Without `symbol` the read is a class-ancestry edge (file-granularity)
+      # and is added to `ancestry_sources` only.
+      # Self-reads and nil sites are ignored in all cases.
+      def read_site(path_line, symbol = nil)
+        accumulator = Thread.current[KEY]
+        return if accumulator.nil? || path_line.nil?
+
+        path = path_line.split(":", 2).first
+        return unless path && path != accumulator.consumer
+
+        accumulator.sources << path
+        if symbol
+          accumulator.symbol_sources[path] << symbol
+        else
+          accumulator.ancestry_sources << path
+        end
+      end
+
+      # Records a cross-file lookup of `name` (kind `:method` / `:class` /
+      # `:const` / …) that resolved to nothing — a negative dependency.
+      def read_missing(kind, name)
+        accumulator = Thread.current[KEY]
+        accumulator&.missing&.add("#{kind}:#{name}")
+      end
+    end
+  end
+end