rigortype 0.1.4 → 0.1.5

data/lib/rigor/analysis/runner.rb

@@ -11,11 +11,14 @@ require_relative "../reflection"
 require_relative "../type/combinator"
 require_relative "../inference/coverage_scanner"
 require_relative "../inference/scope_indexer"
+require_relative "../inference/synthetic_method_scanner"
 require_relative "../inference/method_dispatcher/file_folding"
 require_relative "check_rules"
 require_relative "dependency_source_inference"
 require_relative "diagnostic"
 require_relative "result"
+require_relative "run_stats"
+require_relative "worker_session"
 
 module Rigor
   module Analysis
@@ -35,13 +38,29 @@ module Rigor
       #   run; the CLI's `--no-cache` flag wires `nil` through.
       #   v0.0.9 group A slice 1 introduces the surface; later
       #   slices route real producers through it.
+      # @param workers [Integer] ADR-15 Phase 4b — when greater
+      #   than zero, per-file analysis dispatches across a pool of
+      #   N Ractor workers built around {WorkerSession}. Default
+      #   `0` keeps the sequential code path bit-for-bit
+      #   unchanged. Phase 4c will wire the CLI / `.rigor.yml`
+      #   surface that produces non-zero values; this slice
+      #   leaves the parameter as a programmatic opt-in only.
+      # @param collect_stats [Boolean] when true (default), `#run`
+      #   builds a {RunStats} summary exposed via `result.stats`
+      #   — this forces the RBS env build at end-of-run so the
+      #   `class_decl_paths` snapshot has real source attribution.
+      #   Set to false to skip the stats summary entirely; the
+      #   CLI's `--no-stats` threads `false` through to keep
+      #   trivial-fixture runs from warming `.rigor/cache`.
       def initialize(configuration:, explain: false,
                      cache_store: Cache::Store.new(root: DEFAULT_CACHE_ROOT),
-                     plugin_requirer: nil)
+                     plugin_requirer: nil, workers: 0, collect_stats: true)
         @configuration = configuration
         @explain = explain
         @cache_store = cache_store
         @plugin_requirer = plugin_requirer
+        @workers = workers
+        @collect_stats = collect_stats
         @plugin_registry = Plugin::Registry::EMPTY
         @dependency_source_index = DependencySourceInference::Index::EMPTY
         @rbs_extended_reporter = RbsExtended::Reporter.new
@@ -60,28 +79,69 @@ module Rigor
         Inference::MethodDispatcher::FileFolding.fold_platform_specific_paths =
           @configuration.fold_platform_specific_paths
 
+        wall_started_at = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
         target_ruby_error = validate_target_ruby
         return Result.new(diagnostics: [target_ruby_error]) if target_ruby_error
 
         @plugin_registry = load_plugins
         @dependency_source_index = DependencySourceInference::Builder.build(@configuration.dependencies)
-        environment = Environment.for_project(
-          libraries: @configuration.libraries,
-          signature_paths: @configuration.signature_paths,
-          cache_store: @cache_store,
+        expansion = expand_paths(paths)
+        @class_decl_paths_snapshot = {}.freeze
+        @signature_paths_snapshot = []
+        # ADR-16 slice 2b — Tier C pre-pass. Built once per run
+        # against the resolved file set + the loaded plugin
+        # registry's `heredoc_templates` so synthetic methods are
+        # visible cross-file when per-file inference dispatches.
+        @synthetic_method_index = Inference::SyntheticMethodScanner.scan(
           plugin_registry: @plugin_registry,
-          dependency_source_index: @dependency_source_index,
-          rbs_extended_reporter: @rbs_extended_reporter,
-          boundary_cross_reporter: @boundary_cross_reporter
+          paths: expansion.fetch(:files),
+          environment: nil
         )
-        expansion = expand_paths(paths)
 
         diagnostics = pre_file_diagnostics(expansion)
-        diagnostics += expansion.fetch(:files).flat_map { |path| analyze_file(path, environment) }
+        diagnostics += analyze_files(expansion.fetch(:files))
         diagnostics += rbs_extended_reporter_diagnostics
         diagnostics += boundary_cross_diagnostics
 
-        Result.new(diagnostics: apply_severity_profile(diagnostics))
+        Result.new(
+          diagnostics: apply_severity_profile(diagnostics),
+          stats: @collect_stats ? build_run_stats(wall_started_at: wall_started_at, expansion: expansion) : nil
+        )
+      end
+
+      # ADR-15 Phase 4b — routes per-file analysis to either the
+      # sequential coordinator-side Environment (legacy path,
+      # default) or a Ractor worker pool built around
+      # {WorkerSession} (opt-in via `workers:`). The sequential
+      # path is bit-for-bit unchanged from v0.1.4 / earlier; the
+      # pool path is the substrate exercised by phase 4c when
+      # `RIGOR_RACTOR_WORKERS` / `.rigor.yml` `parallel.workers:`
+      # is wired.
+      #
+      # Sequential mode also snapshots `class_decl_paths` from the
+      # local environment after the per-file loop completes so
+      # `RunStats` can attribute the RBS class universe between
+      # project-sig and bundled sources. The env stays a LOCAL
+      # variable (not an ivar) so it goes GC-eligible when the
+      # 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)
+        return [] if files.empty?
+
+        if pool_mode?
+          analyze_files_in_pool(files)
+        else
+          environment = build_runner_environment
+          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
       end
 
       # Pre-file diagnostic streams that fire once per run rather
@@ -90,12 +150,25 @@ module Rigor
       # `expand_paths` errors for `paths:` entries that don't
       # exist or aren't `.rb`. Aggregated here so `#run` stays
       # under the ABC budget.
+      #
+      # ADR-15 Phase 4b — `plugin_prepare_diagnostics` runs on
+      # the coordinator's plugin registry under sequential mode;
+      # under pool mode each worker re-runs `prepare` against
+      # its own plugin instances, so the pool path drains the
+      # first worker's prepare-diagnostic snapshot into the
+      # aggregated diagnostic stream instead (see
+      # {#analyze_files_in_pool}). Skipping the coordinator
+      # prepare in pool mode avoids double-running `#prepare`
+      # against the coordinator-side plugin instances (which
+      # the pool path never consults for per-file analysis).
       def pre_file_diagnostics(expansion)
+        prepare = pool_mode? ? [] : plugin_prepare_diagnostics
         plugin_load_diagnostics +
-          plugin_prepare_diagnostics +
+          prepare +
           dependency_source_diagnostics +
           dependency_source_budget_diagnostics +
           dependency_source_config_conflict_diagnostics +
+          rbs_coverage_diagnostics +
           expansion.fetch(:errors)
       end
 
@@ -120,6 +193,244 @@ module Rigor
 
       private
 
+      def pool_mode?
+        @workers.is_a?(Integer) && @workers.positive?
+      end
+
+      # Coordinator-side Environment used by the sequential code
+      # path. Pool mode builds one Environment per worker inside
+      # the worker Ractor's body instead.
+      def build_runner_environment
+        Environment.for_project(
+          libraries: @configuration.libraries,
+          signature_paths: @configuration.signature_paths,
+          cache_store: @cache_store,
+          plugin_registry: @plugin_registry,
+          dependency_source_index: @dependency_source_index,
+          rbs_extended_reporter: @rbs_extended_reporter,
+          boundary_cross_reporter: @boundary_cross_reporter,
+          bundler_bundle_path: @configuration.bundler_bundle_path,
+          bundler_auto_detect: @configuration.bundler_auto_detect,
+          bundler_lockfile: @configuration.bundler_lockfile,
+          rbs_collection_lockfile: @configuration.rbs_collection_lockfile,
+          rbs_collection_auto_detect: @configuration.rbs_collection_auto_detect,
+          synthetic_method_index: @synthetic_method_index
+        )
+      end
+
+      # ADR-15 Phase 4b — Ractor pool around {WorkerSession}.
+      # Spawns `@workers` Ractors; each takes the shareable
+      # payload (Configuration, cache_root String, plugin
+      # Blueprint Array, explain Boolean) and builds its OWN
+      # WorkerSession internally. Files are distributed
+      # round-robin across the pool; each worker writes back to
+      # the main Ractor's mailbox via `Ractor.main.send` with
+      # one of three message kinds:
+      #
+      # - `[:prepare, diagnostics]` — once at startup, the
+      #   session's `prepare_diagnostics` snapshot. The
+      #   coordinator keeps the FIRST worker's snapshot only
+      #   (plugin `#prepare` is deterministic per plugin, so
+      #   each worker produces the same diagnostic set; surfacing
+      #   them once avoids N× duplication).
+      # - `[:file, path, diagnostics]` — one per analysed file.
+      # - `[:done, drained_reporters]` — once at exit, the
+      #   per-worker reporter snapshots for end-of-pool merge.
+      #
+      # The Ruby 4.0+ Ractor model uses a single per-Ractor
+      # mailbox (no `Ractor.yield`); workers push back via
+      # `Ractor.main.send`. The coordinator drains its mailbox
+      # via `Ractor.receive` until it has counted exactly
+      # `pool.size` `:done` messages.
+      #
+      # Diagnostic order: original path order. Workers may
+      # complete files out of order; the coordinator re-orders
+      # via the `results_by_path` Hash before flattening.
+      #
+      # Reporter merge: per-worker `RbsExtended::Reporter` and
+      # `BoundaryCrossReporter` entries are replayed into the
+      # runner-side accumulators via their `record_*` APIs,
+      # which dedupe on the same keys as a single-session run
+      # would. Net result: reporter state is identical to the
+      # sequential path.
+      def analyze_files_in_pool(files) # rubocop:disable Metrics/MethodLength,Metrics/AbcSize,Metrics/CyclomaticComplexity
+        # Pre-warm class-level lazy memos on the MAIN Ractor.
+        # `Environment::ClassRegistry.default` is the
+        # default kwarg threaded through `Environment.new`
+        # inside each worker session; lazy-initialising it
+        # from a non-main Ractor would trip
+        # `Ractor::IsolationError`. Touching it here forces
+        # the (shareable) registry into the class-ivar cache
+        # before any worker reads.
+        Environment::ClassRegistry.default
+
+        # ADR-15 Phase 4b.x — pre-warm the RBS cache so
+        # workers serve every reflection query from the
+        # Marshal blob on disk. Without this, the first
+        # cache MISS inside a worker falls through to
+        # `RBS::EnvironmentLoader.new`, which reads a chain
+        # of non-`Ractor.shareable?` RubyGems / RBS module
+        # constants and raises `Ractor::IsolationError`.
+        # Pre-warming requires a `cache_store`; the run aborts
+        # to sequential mode otherwise. See ADR-15 Phase 4b.x
+        # for the full chain of failing constants.
+        if @cache_store.nil?
+          return analyze_files_sequentially_fallback(
+            files, reason: "pool mode requires a cache_store (--no-cache disables pool)"
+          )
+        end
+        prewarm_rbs_cache_for_pool
+
+        configuration = @configuration
+        cache_root = @cache_store&.root
+        blueprints = @plugin_registry.blueprints
+        explain = @explain
+
+        pool = Array.new(@workers) do
+          Ractor.new(configuration, cache_root, blueprints, explain) do |configuration, cache_root, blueprints, explain|
+            cache_store = cache_root ? Rigor::Cache::Store.new(root: cache_root) : nil
+            session = Rigor::Analysis::WorkerSession.new(
+              configuration: configuration,
+              cache_store: cache_store,
+              plugin_blueprints: blueprints,
+              explain: explain
+            )
+            main = Ractor.main
+            main.send([:prepare, session.prepare_diagnostics])
+
+            loop do
+              msg = Ractor.receive
+              break if msg.nil?
+
+              main.send([:file, msg, session.analyze(msg)])
+            end
+
+            main.send([:done, session.drain_reporters])
+          end
+        end
+
+        files.each_with_index { |path, index| pool[index % pool.size].send(path) }
+        pool.each { |worker| worker.send(nil) }
+
+        prepare_diagnostics = nil
+        results_by_path = {}
+        done_count = 0
+
+        while done_count < pool.size
+          message = Ractor.receive
+          case message.first
+          when :prepare
+            prepare_diagnostics ||= message.last
+          when :file
+            results_by_path[message[1]] = message[2]
+          when :done
+            merge_worker_reporters(message.last)
+            done_count += 1
+          end
+        end
+
+        pool.each(&:join)
+
+        Array(prepare_diagnostics) + files.flat_map { |path| results_by_path.fetch(path, []) }
+      end
+
+      # End-of-run telemetry. Walks the cached
+      # `class_decl_paths` snapshot (sequential mode: from
+      # the coordinator's environment; pool mode: from the
+      # first worker's `:prepare` payload) and partitions the
+      # RBS class universe into "project sig/" (paths under
+      # `signature_paths`) vs "bundled" (everything else).
+      # Gem source-walk counts come from `dependency_source_index`
+      # which is already constructed regardless of pool mode.
+      # Wall + RSS are single syscalls; total cost is bounded
+      # by the snapshot size (~1000-2000 entries).
+      def build_run_stats(wall_started_at:, expansion:)
+        snapshot = @class_decl_paths_snapshot || {}.freeze
+        project_sig, bundled = RunStats.partition_classes(
+          class_decl_paths: snapshot,
+          signature_paths: @signature_paths_snapshot
+        )
+        RunStats.new(
+          wall_seconds: Process.clock_gettime(Process::CLOCK_MONOTONIC) - wall_started_at,
+          peak_rss_bytes: RunStats.peak_rss_bytes,
+          target_files: expansion.fetch(:files).size,
+          rbs_classes_total: snapshot.size,
+          rbs_classes_project_sig: project_sig,
+          rbs_classes_bundled: bundled,
+          rbs_attribution_available: RunStats.attribution_available?(class_decl_paths: snapshot),
+          gem_walk_classes: @dependency_source_index.class_to_gem.size,
+          gem_walk_gems: @dependency_source_index.resolved_gems.size
+        )
+      end
+
+      # ADR-15 Phase 4b.x — drives every cached RBS producer
+      # on the main Ractor so each worker can serve all
+      # reflection queries from disk (Marshal-load only).
+      # Builds a single coordinator-side {Environment} for
+      # this purpose; the env object is discarded immediately
+      # after the cache is warm — workers build their own
+      # `Environment.for_project` inside the Ractor body,
+      # which then routes through `cached_env` instead of
+      # `RBS::EnvironmentLoader.new`.
+      def prewarm_rbs_cache_for_pool
+        warm_env = Environment.for_project(
+          libraries: @configuration.libraries,
+          signature_paths: @configuration.signature_paths,
+          cache_store: @cache_store,
+          bundler_bundle_path: @configuration.bundler_bundle_path,
+          bundler_auto_detect: @configuration.bundler_auto_detect,
+          bundler_lockfile: @configuration.bundler_lockfile,
+          rbs_collection_lockfile: @configuration.rbs_collection_lockfile,
+          rbs_collection_auto_detect: @configuration.rbs_collection_auto_detect
+        )
+        warm_env.rbs_loader&.prewarm
+      end
+
+      # ADR-15 Phase 4b.x — pool-mode safety net. When pool
+      # mode is configured but a precondition fails (currently:
+      # `--no-cache` would force workers through
+      # `EnvironmentLoader.new`), degrade to sequential
+      # analysis with a `:warning` `pool-degraded` diagnostic
+      # at run start. The actual per-file analysis runs on
+      # the coordinator, identical to the default sequential
+      # path.
+      def analyze_files_sequentially_fallback(files, reason:)
+        environment = build_runner_environment
+        diagnostics = files.flat_map { |path| analyze_file(path, environment) }
+        loader = environment.rbs_loader
+        @class_decl_paths_snapshot = loader&.class_decl_paths || {}.freeze
+        @signature_paths_snapshot = loader&.signature_paths || [].freeze
+        diagnostics.unshift(
+          Diagnostic.new(
+            path: ".rigor.yml", line: 1, column: 1,
+            message: "pool mode degraded to sequential: #{reason}",
+            severity: :warning, rule: "pool-degraded", source_family: :builtin
+          )
+        )
+      end
+
+      def merge_worker_reporters(drained)
+        rbs = drained.fetch(:rbs_extended)
+        rbs.fetch(:unresolved_payloads).each do |entry|
+          @rbs_extended_reporter.record_unresolved(
+            payload: entry.payload, source_location: entry.source_location
+          )
+        end
+        rbs.fetch(:lossy_projections).each do |entry|
+          @rbs_extended_reporter.record_lossy_projection(
+            head: entry.head, source_location: entry.source_location
+          )
+        end
+        drained.fetch(:boundary_cross).each do |entry|
+          @boundary_cross_reporter.record(
+            class_name: entry.class_name,
+            method_name: entry.method_name,
+            gem_name: entry.gem_name,
+            rbs_display: entry.rbs_display
+          )
+        end
+      end
+
       # Loads project-configured plugins through {Rigor::Plugin::Loader}
       # and returns the resulting {Rigor::Plugin::Registry}. Loader
       # failures are isolated: each surfaces as a `:plugin_loader`
@@ -304,6 +615,70 @@ module Rigor
         end
       end
 
+      # O4 Layer 3 slice 3 — graceful-degradation coverage
+      # report. When the project has a `Gemfile.lock` (slice 1)
+      # and one or more locked gems are not covered by ANY of
+      # the four RBS resolution paths (`DEFAULT_LIBRARIES`,
+      # `data/vendored_gem_sigs/`, slice-1 bundle-shipped
+      # `sig/`, slice-2 `rbs_collection.lock.yaml`), emit a
+      # single `:info` diagnostic summarising the uncovered set
+      # so the user can act on it (run `rbs collection install`,
+      # opt the gem into `dependencies.source_inference:`, or
+      # accept the `Dynamic[T]` fallback).
+      #
+      # Suppressed when the lockfile is empty, when every gem
+      # is covered, or when slice 1's `bundler.lockfile`
+      # discovery returned nothing (no lockfile to read).
+      def rbs_coverage_diagnostics
+        locked = Environment::LockfileResolver.locked_gems(
+          lockfile_path: @configuration.bundler_lockfile,
+          project_root: Dir.pwd,
+          auto_detect: @configuration.bundler_auto_detect
+        )
+        return [] if locked.empty?
+
+        bundle_sig_paths = Environment::BundleSigDiscovery.discover(
+          bundle_path: @configuration.bundler_bundle_path,
+          project_root: Dir.pwd,
+          auto_detect: @configuration.bundler_auto_detect,
+          locked_gems: locked
+        )
+        collection_paths = Environment::RbsCollectionDiscovery.discover(
+          lockfile_path: @configuration.rbs_collection_lockfile,
+          project_root: Dir.pwd,
+          auto_detect: @configuration.rbs_collection_auto_detect
+        )
+        rows = Environment::RbsCoverageReport.classify(
+          locked_gems: locked,
+          default_libraries: Environment::DEFAULT_LIBRARIES,
+          bundle_sig_paths: bundle_sig_paths,
+          rbs_collection_paths: collection_paths
+        )
+        missing = Environment::RbsCoverageReport.missing(rows)
+        return [] if missing.empty?
+
+        [build_rbs_coverage_missing_diagnostic(missing)]
+      end
+
+      def build_rbs_coverage_missing_diagnostic(missing)
+        sample_size = 5
+        sample = missing.first(sample_size).map(&:gem_name)
+        suffix = missing.size > sample_size ? ", and #{missing.size - sample_size} more" : ""
+        Diagnostic.new(
+          path: ".rigor.yml",
+          line: 1,
+          column: 1,
+          message: "#{missing.size} gem(s) in Gemfile.lock have no RBS available: " \
+                   "#{sample.join(', ')}#{suffix}. " \
+                   "Consider `rbs collection install` to fetch community RBS from " \
+                   "`ruby/gem_rbs_collection`, ship `sig/` in the gem itself, or " \
+                   "opt the gem into `dependencies.source_inference:` in `.rigor.yml`.",
+          severity: :info,
+          rule: "rbs.coverage.missing-gem",
+          source_family: :builtin
+        )
+      end
+
       # ADR-13 slice 3b — drains the per-run
       # {RbsExtended::Reporter} into one diagnostic per accumulated
       # event: