rigortype 0.1.16 → 0.1.17

data/lib/rigor/analysis/runner.rb

@@ -1,14 +1,17 @@
 # frozen_string_literal: true
 
+require "digest"
 require "prism"
 require "tmpdir"
 
 require_relative "../environment"
 require_relative "../scope"
 require_relative "../cache/store"
+require_relative "../cache/rbs_descriptor"
 require_relative "../plugin"
 require_relative "../plugin/source_rbs_synthesis_reporter"
 require_relative "../rbs_extended/reporter"
+require_relative "../rbs_extended/conformance_checker"
 require_relative "../reflection"
 require_relative "../type/combinator"
 require_relative "../inference/coverage_scanner"
@@ -18,6 +21,10 @@ require_relative "../inference/project_patched_scanner"
 require_relative "../inference/method_dispatcher/file_folding"
 require_relative "buffer_binding"
 require_relative "check_rules"
+require_relative "dependency_recorder"
+require_relative "self_call_resolution_recorder"
+require_relative "incremental"
+require_relative "incremental_session"
 require_relative "dependency_source_inference"
 require_relative "diagnostic"
 require_relative "erb_template_detector"
@@ -33,7 +40,8 @@ module Rigor
       DEFAULT_CACHE_ROOT = ".rigor/cache"
 
       attr_reader :cache_store, :plugin_registry, :dependency_source_index,
-                  :rbs_extended_reporter, :boundary_cross_reporter
+                  :rbs_extended_reporter, :boundary_cross_reporter, :file_dependencies,
+                  :analyzed_files, :unresolved_self_calls
 
       # @param configuration [Rigor::Configuration]
       # @param explain [Boolean] surface fail-soft fallback events
@@ -82,10 +90,11 @@ module Rigor
       #   (bundler / lockfile / collection discovery, RbsLoader
       #   construction). Pool mode ignores the override — each
       #   worker continues to build its own Environment.
-      def initialize(configuration:, explain: false, # rubocop:disable Metrics/ParameterLists
+      def initialize(configuration:, explain: false, # rubocop:disable Metrics/ParameterLists,Metrics/AbcSize,Metrics/MethodLength
                      cache_store: Cache::Store.new(root: DEFAULT_CACHE_ROOT),
                      plugin_requirer: nil, workers: 0, collect_stats: true,
-                     buffer: nil, prebuilt: nil, environment: nil)
+                     buffer: nil, prebuilt: nil, environment: nil,
+                     record_dependencies: false, record_self_calls: false, analyze_only: nil)
         @configuration = configuration
         @explain = explain
         @cache_store = enforce_read_only_cache(cache_store, buffer)
@@ -95,6 +104,35 @@ module Rigor
         @buffer = buffer
         @prebuilt = prebuilt
         @environment_override = environment
+        # ADR-46 slice 1 — opt-in cross-file dependency recording. Off by
+        # default; when true, `analyze_file` records each file's
+        # cross-file reads into `file_dependencies` (the incremental
+        # cache, a later slice, consumes them).
+        @record_dependencies = record_dependencies
+        # ADR-24 slice 4a — opt-in unresolved-implicit-self-call recording.
+        # Off by default; when true, `analyze_file` activates the engine
+        # choke-point recorder and collects each file's misses into
+        # `unresolved_self_calls` (a later closed-class-gated rule consumes
+        # them). Purely observational — diagnostics are byte-identical.
+        @record_self_calls = record_self_calls
+        @unresolved_self_calls = {}
+        # Memoised activation decision for the `call.self-undefined-method`
+        # rule (nil = not yet computed). See `self_undefined_rule_active?`.
+        @self_undefined_rule_active = nil
+        @analyzed_files = [].freeze
+        # In-memory source map for `#run_source` — `{ logical_path => source
+        # String }`. When set, `parse_source` reads bytes from here instead
+        # of disk and `expand_paths` accepts the (possibly non-existent)
+        # logical path. nil on a normal disk-backed run.
+        @in_memory_sources = nil
+        # ADR-46 slice 2 — the subset-analysis hook. When set (a collection
+        # of paths), the whole-project pre-pass still runs over every file
+        # (so the cross-file index is complete), but only files in this set
+        # are analyzed for diagnostics — the body tier re-analyses the
+        # affected closure and serves the rest from the per-file cache.
+        # `nil` (the default) analyzes everything.
+        @analyze_only = analyze_only && Set.new(analyze_only)
+        @file_dependencies = {}
         @plugin_registry = Plugin::Registry::EMPTY
         @dependency_source_index = DependencySourceInference::Index::EMPTY
         @rbs_extended_reporter = RbsExtended::Reporter.new
@@ -103,18 +141,27 @@ module Rigor
         # `#run` resets these for each invocation; pre-seed them to
         # empty containers so `build_run_stats` / `pre_file_diagnostics`
         # (private, called only from `#run`) can read them without
-        # nil-guards.
+        # nil-guards. Kept inline (not a helper) so the engine's own
+        # flow analysis sees the ivars established in the constructor.
         @class_decl_paths_snapshot = {}.freeze
         @signature_paths_snapshot = [].freeze
         @synthesized_namespaces_snapshot = [].freeze
+        # `rigor:v1:conforms-to` results, snapshotted from the
+        # per-run RBS env in `analyze_files_sequentially` (gated on
+        # the project declaring `signature_paths:`) and drained by
+        # `conforms_to_diagnostics`. Inline default per the comment
+        # above so the engine's own flow analysis sees it seeded.
+        @conformance_results_snapshot = [].freeze
         @cached_plugin_prepare_diagnostics = [].freeze
         @project_discovered_classes = {}.freeze
         @project_discovered_def_nodes = {}.freeze
         @project_discovered_def_sources = {}.freeze
         @project_discovered_superclasses = {}.freeze
         @project_discovered_includes = {}.freeze
+        @project_discovered_class_sources = {}.freeze
         @project_discovered_method_visibilities = {}.freeze
         @project_discovered_methods = {}.freeze
+        @project_data_member_layouts = {}.freeze
       end
 
       # ADR-pending editor mode — present when the runner is wired
@@ -144,6 +191,7 @@ module Rigor
         @class_decl_paths_snapshot = {}.freeze
         @signature_paths_snapshot = []
         @synthesized_namespaces_snapshot = []
+        @conformance_results_snapshot = []
 
         if @prebuilt
           adopt_prebuilt_project_scan(@prebuilt)
@@ -151,17 +199,210 @@ module Rigor
           run_project_pre_passes(expansion: expansion)
         end
 
+        diagnostics = compute_run_diagnostics(expansion)
+
+        Result.new(
+          diagnostics: apply_severity_profile(diagnostics),
+          stats: stats_for_run(wall_started_at: wall_started_at, expansion: expansion)
+        )
+      end
+
+      # Analyze a single source String in memory, without writing it to
+      # disk — a clean entry point for embedders (LSP / editor mode) and a
+      # faster spec path than the per-call tmpdir + chdir. The source is
+      # bound to `path` (purely a logical identity carried in diagnostic
+      # locations; it need not exist on disk). The full run machinery still
+      # runs — environment build, plugin `prepare`, severity profile — so
+      # the result matches a one-file disk run; only the cross-file project
+      # pre-pass is empty (there is one file, and the per-file indexer
+      # self-discovers its own classes / defs).
+      #
+      # @param source [String] Ruby source to analyze.
+      # @param path [String] logical path for diagnostic locations.
+      # @return [Result]
+      def run_source(source:, path: "(source).rb")
+        @in_memory_sources = { path => source }
+        run([path])
+      ensure
+        @in_memory_sources = nil
+      end
+
+      # ADR-46 — the project file set that a run over `paths` would
+      # analyze, computed by globbing only (no RBS environment build), so
+      # the incremental fingerprint can be derived cheaply on the warm path
+      # before deciding whether to build the env at all.
+      def analysis_file_set(paths = @configuration.paths)
+        expand_paths(paths).fetch(:files)
+      end
+
+      # ADR-46 §2 — inverts {#file_dependencies} into the reverse edge the
+      # incremental step walks: `dependents[X] = { A : A read a
+      # declaration / body from X }`. On an edit to X, the body tier
+      # (slice 2) re-analyses `{X} ∪ dependents[X]` and serves every other
+      # file from the per-file cache. Built on demand from the recorded
+      # `sources` sets (so it reflects whatever `analyze_file` captured —
+      # empty unless the runner was constructed with
+      # `record_dependencies: true`). The negative (`missing`) edges are
+      # NOT inverted here: they feed the structural tier (slice 3), which
+      # re-checks a consumer when a name it looked up and did not resolve
+      # later appears.
+      def file_dependents
+        Incremental.invert(@file_dependencies.transform_values(&:sources))
+      end
+
+      # ADR-46 slice 4 — per-symbol body fingerprints, computed from the
+      # project pre-pass def index. Returns a frozen hash of the form:
+      #   { "path/to/file.rb" => { "ClassName#method" => sha256_hex, … }, … }
+      # Used by {Analysis::IncrementalSession} to detect which symbols in a
+      # changed file actually changed bodies, so only callers of those
+      # specific symbols are re-checked. Only meaningful after a run that
+      # populated `@project_discovered_def_nodes` (i.e. any full or subset
+      # analysis); returns an empty frozen hash before the first run.
+      def symbol_fingerprints
+        result = Hash.new { |h, k| h[k] = {} }
+        @project_discovered_def_sources.each do |class_name, methods|
+          methods.each do |method_sym, path_line|
+            path = path_line.split(":", 2).first
+            node = @project_discovered_def_nodes.dig(class_name, method_sym)
+            next unless node
+
+            result[path]["#{class_name}##{method_sym}"] =
+              Digest::SHA256.hexdigest(node.location.slice)
+          end
+        end
+        result.transform_values(&:freeze).freeze
+      end
+
+      # ADR-46 slice 3 — per-file set of the qualified class/module names
+      # declared in that file. Used to detect a class that *appeared* in an
+      # edit so a subclass whose ancestor was previously undefined (and so
+      # recorded a negative class edge) is re-checked. Inverts the project
+      # class-source attribution (class → declaring files).
+      def class_declarations
+        result = Hash.new { |hash, key| hash[key] = Set.new }
+        @project_discovered_class_sources.each do |class_name, files|
+          files.each { |file| result[file] << class_name }
+        end
+        result.transform_values(&:freeze).freeze
+      end
+
+      # ADR-45 — unchanged-project fast path. Serves the whole run's
+      # (pre-severity-profile) diagnostics from one record-and-validate
+      # cache entry when every file the previous run read is unchanged,
+      # skipping the dominant per-file inference. The dependency set is
+      # collected AFTER the run (so it captures files the plugins read
+      # mid-analysis, e.g. a Pundit policy) and re-validated on the next
+      # run; the entry is keyed on the inputs known up front (config, gem
+      # / engine versions, analyzed-path set).
+      def compute_run_diagnostics(expansion)
+        @run_served_from_cache = false
+        return assemble_run_diagnostics(expansion) unless run_result_cacheable?
+
+        environment = resolve_sequential_environment(source_files: target_files(expansion))
+        rbs_descriptor = environment&.rbs_loader ? Cache::RbsDescriptor.build(environment.rbs_loader) : Cache::Descriptor.new
+        key_descriptor = run_key_descriptor(expansion, rbs_descriptor)
+        return assemble_run_diagnostics(expansion, environment: environment) if key_descriptor.nil?
+
+        computed = false
+        diagnostics = @cache_store.fetch_or_validate(
+          producer_id: "analysis.run-diagnostics", key_descriptor: key_descriptor
+        ) do
+          computed = true
+          diags = assemble_run_diagnostics(expansion, environment: environment)
+          [diags, run_dependency_descriptor(expansion, rbs_descriptor)]
+        end
+        @run_served_from_cache = !computed
+        diagnostics
+      rescue StandardError
+        # The result cache must never break a run. If anything in the
+        # cache path fails, fall back to a direct, uncached analysis.
+        @run_served_from_cache = false
+        assemble_run_diagnostics(expansion)
+      end
+
+      def assemble_run_diagnostics(expansion, environment: nil)
         diagnostics = pre_file_diagnostics(expansion)
-        diagnostics += analyze_files(target_files(expansion))
+        # ADR-46 — record which project files this run actually analyzed
+        # (the `analyze_only` subset, or all of them). The incremental
+        # orchestrator serves every analyzed-but-not-affected file from the
+        # per-file cache, so it needs the full analyzed set to subtract the
+        # affected closure from.
+        targets = target_files(expansion)
+        @analyzed_files = targets
+        diagnostics += analyze_files(targets, environment: environment)
         diagnostics += rbs_synthesized_namespace_diagnostics
+        diagnostics += conforms_to_diagnostics
         diagnostics += rbs_extended_reporter_diagnostics
         diagnostics += boundary_cross_diagnostics
-        diagnostics += source_rbs_synthesis_diagnostics
-
-        Result.new(
-          diagnostics: apply_severity_profile(diagnostics),
-          stats: @collect_stats ? build_run_stats(wall_started_at: wall_started_at, expansion: expansion) : nil
+        diagnostics + source_rbs_synthesis_diagnostics
+      end
+
+      # A cache hit skipped the analysis, so the per-run stats (wall
+      # split, RBS-class counts, …) were never gathered — report none
+      # rather than the stale snapshot defaults.
+      def stats_for_run(wall_started_at:, expansion:)
+        return nil unless @collect_stats
+        return nil if @run_served_from_cache
+
+        build_run_stats(wall_started_at: wall_started_at, expansion: expansion)
+      end
+
+      # Cacheable only for a full sequential project run with a writable
+      # cache and no per-buffer / prebuilt override — every other mode has
+      # a different result identity (pool workers read in separate
+      # processes; editor mode is per-buffer; prebuilt is the LSP path).
+      def run_result_cacheable?
+        !@cache_store.nil? && !@cache_store.read_only? &&
+          @buffer.nil? && @prebuilt.nil? && !pool_mode?
+      end
+
+      # Stable cache key inputs — known before the run: a digest of the
+      # resolved configuration, the engine + rbs versions + `--explain`,
+      # and the analyzed-path SET (adding/removing a file changes the
+      # key; editing one is caught by dependency validation). nil disables
+      # the cache for this run rather than risking a malformed key.
+      def run_key_descriptor(expansion, rbs_descriptor)
+        Cache::Descriptor.new(
+          gems: rbs_descriptor.gems,
+          configs: rbs_descriptor.configs + [
+            config_hash_entry("configuration", Marshal.dump(@configuration.to_h)),
+            config_hash_entry("engine", "#{Rigor::VERSION}:#{Cache::Descriptor::SCHEMA_VERSION}:#{@explain}"),
+            config_hash_entry("paths", expansion.fetch(:files).sort.join("\n"))
+          ]
         )
+      rescue StandardError
+        nil
+      end
+
+      # Files the run actually depended on, collected AFTER it ran:
+      # every analyzed file, every RBS `sig` file (`rbs_descriptor.files`),
+      # and every file each plugin read (complete post-run, so reads made
+      # mid-analysis are included). Re-digested on the next run by
+      # {Descriptor#fresh?}.
+      def run_dependency_descriptor(expansion, rbs_descriptor)
+        entries = analyzed_file_entries(expansion) + rbs_descriptor.files
+        @plugin_registry.plugins.each do |plugin|
+          # Read the boundary WITHOUT triggering its lazy `@io_boundary ||=`
+          # initializer: plugin instances are frozen after the run, and a
+          # plugin that never built a boundary read no files through it, so
+          # it contributes no dependencies.
+          boundary = plugin.instance_variable_get(:@io_boundary)
+          entries.concat(boundary.cache_descriptor.files) if boundary
+        end
+        Cache::Descriptor.new(files: entries)
+      end
+
+      def analyzed_file_entries(expansion)
+        expansion.fetch(:files).map do |path|
+          physical = @buffer ? @buffer.resolve(path) : path
+          Cache::Descriptor::FileEntry.new(
+            path: physical, comparator: :digest, value: Digest::SHA256.file(physical).hexdigest
+          )
+        end
+      end
+
+      def config_hash_entry(key, payload)
+        Cache::Descriptor::ConfigEntry.new(key: key, value_hash: Digest::SHA256.hexdigest(payload))
       end
 
       # Runs every project-wide pre-pass (`load_plugins` +
@@ -204,7 +445,7 @@ module Rigor
       # downstream `#run` body expects. Extracted so
       # `#prepare_project_scan` and the prebuilt-less `#run` path
       # share one implementation.
-      def run_project_pre_passes(expansion:)
+      def run_project_pre_passes(expansion:) # rubocop:disable Metrics/AbcSize
         @plugin_registry = load_plugins
         @dependency_source_index = DependencySourceInference::Builder.build(@configuration.dependencies)
         # ADR-18 slice 3 — plugin prepare MUST run before the
@@ -266,8 +507,10 @@ module Rigor
         @project_discovered_def_sources = def_index.fetch(:def_sources)
         @project_discovered_superclasses = def_index.fetch(:superclasses)
         @project_discovered_includes = def_index.fetch(:includes)
+        @project_discovered_class_sources = def_index.fetch(:class_sources)
         @project_discovered_method_visibilities = def_index.fetch(:method_visibilities)
         @project_discovered_methods = def_index.fetch(:methods)
+        @project_data_member_layouts = def_index.fetch(:data_member_layouts)
       end
 
       # Internal: adopts a frozen {ProjectScan} snapshot supplied
@@ -301,31 +544,36 @@ module Rigor
       # method returns — holding it as long-lived state added
       # memory pressure that surfaced as a Bus Error during the
       # spec suite under Ruby 4.0 + rbs 4.0.2.
-      def analyze_files(files)
+      def analyze_files(files, environment: nil)
         return [] if files.empty?
-
-        if pool_mode?
-          dispatch_pool(files)
-        else
-          environment = resolve_sequential_environment(source_files: files)
-          # Snapshot the small synthesized-namespace name list (NOT the
-          # env — see the method comment) so #run can surface the
-          # malformed-RBS `:info` diagnostic without rebuilding the env.
-          # Gated on the project actually declaring `signature_paths:`:
-          # synthesis only matters for the project's own RBS, and
-          # `#synthesized_namespaces` forces the (otherwise-lazy) RBS env
-          # to build — doing so when there is no project sig set would
-          # warm `.rigor/cache` on a bare `--no-stats` run.
-          @synthesized_namespaces_snapshot =
-            project_signature_paths? ? (environment.rbs_loader&.synthesized_namespaces || []) : []
-          result = files.flat_map { |path| analyze_file(path, environment) }
-          if @collect_stats
-            loader = environment.rbs_loader
-            @class_decl_paths_snapshot = loader&.class_decl_paths || {}.freeze
-            @signature_paths_snapshot = loader&.signature_paths || [].freeze
-          end
-          result
+        return dispatch_pool(files) if pool_mode?
+
+        analyze_files_sequentially(files, environment || resolve_sequential_environment(source_files: files))
+      end
+
+      def analyze_files_sequentially(files, environment)
+        # Snapshot the small synthesized-namespace name list (NOT the
+        # env — see the method comment) so #run can surface the
+        # malformed-RBS `:info` diagnostic without rebuilding the env.
+        # Gated on the project actually declaring `signature_paths:`:
+        # synthesis only matters for the project's own RBS, and
+        # `#synthesized_namespaces` forces the (otherwise-lazy) RBS env
+        # to build — doing so when there is no project sig set would
+        # warm `.rigor/cache` on a bare `--no-stats` run.
+        @synthesized_namespaces_snapshot =
+          project_signature_paths? ? (environment.rbs_loader&.synthesized_namespaces || []) : []
+        # `rigor:v1:conforms-to` lives only in the project's own
+        # `signature_paths:` RBS, so gate the scan the same way and
+        # reuse the already-built env (no extra RBS load).
+        @conformance_results_snapshot =
+          project_signature_paths? ? RbsExtended::ConformanceChecker.scan(environment.rbs_loader) : []
+        result = files.flat_map { |path| analyze_file(path, environment) }
+        if @collect_stats
+          loader = environment.rbs_loader
+          @class_decl_paths_snapshot = loader&.class_decl_paths || {}.freeze
+          @signature_paths_snapshot = loader&.signature_paths || [].freeze
         end
+        result
       end
 
       # Sequential-mode environment resolver. Returns the supplied
@@ -463,6 +711,11 @@ module Rigor
       # buffer".
       def target_files(expansion)
         files = expansion.fetch(:files)
+        # ADR-46 slice 2 — restrict the analyzed set to the affected
+        # closure while the pre-pass (run separately over `expansion`'s
+        # full file list) keeps the cross-file index complete. Buffer mode
+        # takes precedence — its single logical path is the analyzed set.
+        files = files.select { |path| @analyze_only.include?(path) } if @analyze_only
         return files if @buffer.nil?
 
         [@buffer.logical_path]
@@ -1146,6 +1399,72 @@ module Rigor
         [build_rbs_synthesized_namespace_diagnostic(synthesized)]
       end
 
+      # Maps the per-run `rigor:v1:conforms-to` scan results into
+      # diagnostics (spec: `rbs-extended.md` § "Explicit conformance
+      # directive"). A class that declares `conforms-to _Interface`
+      # but is missing a required interface method surfaces as
+      # `rbs_extended.unsatisfied-conformance`; an unresolvable
+      # interface name surfaces as `dynamic.rbs-extended.unresolved`
+      # `:info` (the same fail-soft channel the other directive
+      # parsers use). Empty for a project with no directive, a
+      # well-formed conformance, or a non-sequential pool run (the
+      # snapshot mirrors `synthesized_namespaces`).
+      def conforms_to_diagnostics
+        results = @conformance_results_snapshot
+        return [] if results.nil? || results.empty?
+
+        results.map { |record| build_conformance_diagnostic(record) }
+      end
+
+      def build_conformance_diagnostic(record)
+        case record
+        when RbsExtended::ConformanceChecker::Unsatisfied
+          build_unsatisfied_conformance_diagnostic(record)
+        when RbsExtended::ConformanceChecker::IncompatibleSignature
+          build_incompatible_signature_diagnostic(record)
+        else # UnresolvedInterface
+          build_reporter_diagnostic(
+            record.location,
+            rule: "dynamic.rbs-extended.unresolved",
+            message: "`#{record.class_name}` declares `conforms-to #{record.interface_name}` but " \
+                     "interface `#{record.interface_name}` is not loaded. Check for a typo or add " \
+                     "the `sig`/library that declares it to the RBS load path."
+          )
+        end
+      end
+
+      def build_unsatisfied_conformance_diagnostic(record)
+        path, line, column = location_fields(record.location)
+        Diagnostic.new(
+          path: path, line: line, column: column,
+          message: "`#{record.class_name}` declares `conforms-to #{record.interface_name}` " \
+                   "but does not provide #{pluralize_methods(record.missing_methods)}: " \
+                   "#{record.missing_methods.map { |m| "`##{m}`" }.join(', ')}. Implement the " \
+                   "missing method(s) or remove the directive.",
+          severity: :warning,
+          rule: "rbs_extended.unsatisfied-conformance",
+          source_family: :builtin
+        )
+      end
+
+      def build_incompatible_signature_diagnostic(record)
+        path, line, column = location_fields(record.location)
+        Diagnostic.new(
+          path: path, line: line, column: column,
+          message: "`#{record.class_name}##{record.method_name}` does not satisfy " \
+                   "`conforms-to #{record.interface_name}`: #{record.detail}. Adjust the " \
+                   "signature to a subtype of the interface contract.",
+          severity: :warning,
+          rule: "rbs_extended.unsatisfied-conformance",
+          source_family: :builtin,
+          method_name: record.method_name
+        )
+      end
+
+      def pluralize_methods(methods)
+        methods.size == 1 ? "required method" : "#{methods.size} required methods"
+      end
+
       # True when the project declares its own `signature_paths:` (the
       # only place the qualified-name-without-namespace mistake lives).
       def project_signature_paths?
@@ -1455,7 +1774,8 @@ module Rigor
 
       def accept_as_ruby_file?(path)
         (File.file?(path) && path.end_with?(".rb")) ||
-          (@buffer && path == @buffer.logical_path)
+          (@buffer && path == @buffer.logical_path) ||
+          @in_memory_sources&.key?(path)
       end
 
       # `Configuration#exclude_patterns` is a list of glob patterns
@@ -1494,6 +1814,10 @@ module Rigor
       # LOGICAL path. Non-binding paths go through the cheaper
       # `Prism.parse_file` codepath unchanged.
       def parse_source(path)
+        if @in_memory_sources&.key?(path)
+          return Prism.parse(@in_memory_sources[path], filepath: path, version: @configuration.target_ruby)
+        end
+
         physical = @buffer ? @buffer.resolve(path) : path
         return Prism.parse_file(physical, version: @configuration.target_ruby) if physical == path
 
@@ -1522,10 +1846,34 @@ module Rigor
           scope = scope.with_discovered_method_visibilities(@project_discovered_method_visibilities)
         end
         scope = scope.with_discovered_methods(@project_discovered_methods) unless @project_discovered_methods.empty?
+        scope = scope.with_data_member_layouts(@project_data_member_layouts) unless @project_data_member_layouts.empty?
+        # ADR-46 slice 1 — the class-declaration source map is read only by
+        # the ancestry accessors during dependency recording, so seed it
+        # only when recording is on; a normal run never carries it.
+        if @record_dependencies && !@project_discovered_class_sources.empty?
+          scope = scope.with_discovered_class_sources(@project_discovered_class_sources)
+        end
         scope
       end
 
-      def analyze_file(path, environment) # rubocop:disable Metrics/MethodLength
+      # ADR-46 slice 1 — when dependency recording is enabled, wrap the
+      # per-file analysis so the cross-file reads its inference makes are
+      # captured into `file_dependencies[path]`. Off by default: a normal
+      # run calls the body directly and the instrumented `Scope` accessors
+      # short-circuit on `DependencyRecorder.active? == false`. Recording
+      # is observational, so diagnostics are byte-identical either way.
+      def analyze_file(path, environment)
+        return analyze_file_body(path, environment) unless @record_dependencies
+
+        diagnostics = nil
+        record = DependencyRecorder.record_for(path) do
+          diagnostics = analyze_file_body(path, environment)
+        end
+        @file_dependencies[path] = record
+        diagnostics
+      end
+
+      def analyze_file_body(path, environment) # rubocop:disable Metrics/MethodLength
         parse_result = parse_source(path)
         unless parse_result.errors.empty?
           return [] if ErbTemplateDetector.template?(parse_result)
@@ -1534,11 +1882,20 @@ module Rigor
         end
 
         scope = seed_project_scope(Scope.empty(environment: environment, source_path: path))
-        index = Inference::ScopeIndexer.index(parse_result.value, default_scope: scope)
+        # ADR-24 slice 4a/4 — record unresolved implicit-self calls during the
+        # typing pass ONLY (not CheckRules, whose own `type_of` queries would
+        # otherwise re-trigger the choke-point). `self_call_misses` feeds the
+        # `call.self-undefined-method` collector; the recorder is inert unless
+        # the rule is active or `record_self_calls:` opted in.
+        index = nil
+        self_call_record = with_self_call_recording(path) do
+          index = Inference::ScopeIndexer.index(parse_result.value, default_scope: scope)
+        end
         diagnostics = CheckRules.diagnose(
           path: path,
           root: parse_result.value,
           scope_index: index,
+          self_call_misses: self_call_record ? self_call_record.calls : [],
           comments: parse_result.comments,
           disabled_rules: @configuration.disabled_rules
         )
@@ -1566,6 +1923,46 @@ module Rigor
         ]
       end
 
+      # ADR-24 slice 4a — runs `block` (the typing pass) with the self-call
+      # recorder active when either the test-only `record_self_calls:` flag is
+      # set or the `call.self-undefined-method` rule resolves to a firing
+      # severity. Returns the frozen {SelfCallResolutionRecorder::Record}, or
+      # nil when recording is inactive (the common path — one integer read).
+      def with_self_call_recording(path, &)
+        unless self_call_recording_active?
+          yield
+          return nil
+        end
+
+        record = SelfCallResolutionRecorder.record_for(path, &)
+        @unresolved_self_calls[path] = record
+        record
+      end
+
+      def self_call_recording_active?
+        @record_self_calls || self_undefined_rule_active?
+      end
+
+      # Memoised: the rule fires only when its resolved severity is not `:off`
+      # and it is not in `disable:`. Default profiles map it to `:off`, so a
+      # normal run never activates the recorder (pending the external WD4
+      # corpus FP gate — see ADR-24 § "Slice 4"); a project opts in via
+      # `severity_overrides:`.
+      def self_undefined_rule_active?
+        return @self_undefined_rule_active unless @self_undefined_rule_active.nil?
+
+        rule = CheckRules::RULE_SELF_UNDEFINED_METHOD
+        @self_undefined_rule_active =
+          if @configuration.disabled_rules.include?(rule) || @configuration.disabled_rules.include?("call")
+            false
+          else
+            Configuration::SeverityProfile.resolve(
+              rule: rule, authored_severity: :warning,
+              profile: @configuration.severity_profile, overrides: @configuration.severity_overrides
+            ) != :off
+          end
+      end
+
       # v0.0.2 #10 — fail-soft fallback explanation. When
       # `--explain` is set the runner additionally walks the
       # file with `Rigor::Inference::CoverageScanner` and emits