rigortype 0.1.7 → 0.1.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0eaff9cf0ef65d44ceb3666a23fb77003a3dbb0361d890e1d2991ef6539499de
-  data.tar.gz: e7fdc58be21409504965f35479559d26bcf4726ba0feabe3fd5128bcffe8419b
+  metadata.gz: 9880f534e47f36db5fbbaa5e6d169350f90ecf1ed12081e4ccf5e5e01e9d4518
+  data.tar.gz: 1abb8764932adadaafc6cf43152d2306002aa04419ec403e81e63eed3cedb08e
 SHA512:
-  metadata.gz: 94aae7605ca3243e7226e6f2e1c844f141d3ef04995751718e08ef5fb9dfa550455c6c87420e731332b765ee262442ed2608b5f0d7b05a25b982615b993114e5
-  data.tar.gz: f2dedba8fb33b9f7d98ddaa4debcec042edf56396c22a791ce8897736839c559240cb20158916f7c2bc5f483da06c1bebb7212ec2f24b16c3554164f849da621
+  metadata.gz: c9135e0d12d588614b7fc1c4af793aab3b798f42bae19e0a72d15ba875e979f24927abcce8976431d7694b856bdc89fc94c588874414fdeee5f437c915af956d
+  data.tar.gz: d77dbf70aa13cb3418636e31ff498384ebefd21e0c6887324cc316975e862d1a09c86dc06f313fa081b17fd5f0f7c1592ee786f1958be66ab02e697c5630b80d

data/lib/rigor/analysis/check_rules.rb

@@ -1215,7 +1215,9 @@ module Rigor
             line: location.start_line,
             column: location.start_column + 1,
             message: "undefined method `#{call_node.name}' for #{rendered_receiver}",
-            severity: :error
+            severity: :error,
+            receiver_type: rendered_receiver,
+            method_name: call_node.name.to_s
           )
         end
 

data/lib/rigor/analysis/diagnostic.rb

@@ -8,7 +8,8 @@ module Rigor
       # baseline against which non-default families are recognised.
       DEFAULT_SOURCE_FAMILY = :builtin
 
-      attr_reader :path, :line, :column, :message, :severity, :rule, :source_family
+      attr_reader :path, :line, :column, :message, :severity, :rule, :source_family,
+                  :receiver_type, :method_name
 
       # `rule:` is the stable identifier (a kebab-case string)
       # of the diagnostic's source rule. It is used by the
@@ -24,8 +25,19 @@ module Rigor
       # ADR-2 § "Plugin Diagnostic Provenance") let consumers
       # distinguish where a diagnostic originated without committing
       # to the plugin API itself.
-      def initialize(path:, line:, column:, message:, severity: :error, rule: nil,
-                     source_family: DEFAULT_SOURCE_FAMILY)
+      #
+      # `receiver_type:` / `method_name:` are optional structured
+      # fields populated by the call-related rules (`call.undefined-
+      # method`) — the rendered receiver type and the called method
+      # name as plain strings. ADR-23 WD3 / slice 4: `rigor triage`'s
+      # heuristic recognisers read these directly instead of parsing
+      # the diagnostic message, so the catalogue no longer couples to
+      # message wording. Both stay nil for rules that have no such
+      # pair; a consumer that finds them nil falls back to message
+      # parsing.
+      def initialize(path:, line:, column:, message:, severity: :error, rule: nil, # rubocop:disable Metrics/ParameterLists
+                     source_family: DEFAULT_SOURCE_FAMILY,
+                     receiver_type: nil, method_name: nil)
         @path = path
         @line = line
         @column = column
@@ -33,6 +45,8 @@ module Rigor
         @severity = severity
         @rule = rule
         @source_family = source_family
+        @receiver_type = receiver_type
+        @method_name = method_name
       end
 
       def error?

data/lib/rigor/analysis/runner.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "prism"
+require "tmpdir"
 
 require_relative "../environment"
 require_relative "../scope"
@@ -104,6 +105,9 @@ module Rigor
         @signature_paths_snapshot = [].freeze
         @cached_plugin_prepare_diagnostics = [].freeze
         @project_discovered_classes = {}.freeze
+        @project_discovered_def_nodes = {}.freeze
+        @project_discovered_superclasses = {}.freeze
+        @project_discovered_includes = {}.freeze
       end
 
       # ADR-pending editor mode — present when the runner is wired
@@ -241,6 +245,16 @@ module Rigor
         # can share parses with the existing scanner passes.
         @project_discovered_classes =
           Inference::ScopeIndexer.discovered_classes_for_paths(expansion.fetch(:files), buffer: @buffer)
+        # ADR-24 slice 2 — cross-file def-node + class->superclass
+        # index so an implicit-self call inside a subclass
+        # resolves a superclass `def` declared in a sibling
+        # file. One extra parse pass over the project; shares
+        # the cost profile of the class-discovery pass above.
+        def_index =
+          Inference::ScopeIndexer.discovered_def_index_for_paths(expansion.fetch(:files), buffer: @buffer)
+        @project_discovered_def_nodes = def_index.fetch(:def_nodes)
+        @project_discovered_superclasses = def_index.fetch(:superclasses)
+        @project_discovered_includes = def_index.fetch(:includes)
       end
 
       # Internal: adopts a frozen {ProjectScan} snapshot supplied
@@ -278,7 +292,7 @@ module Rigor
         return [] if files.empty?
 
         if pool_mode?
-          analyze_files_in_pool(files)
+          dispatch_pool(files)
         else
           environment = resolve_sequential_environment
           result = files.flat_map { |path| analyze_file(path, environment) }
@@ -460,6 +474,34 @@ module Rigor
         @buffer.nil?
       end
 
+      # ADR-15 Amendment (2026-05-20) — worker-pool backend selector.
+      # `fork` is the active backend: separate processes sidestep both
+      # the Ruby Bug #22075 use-after-free and the worker-side
+      # `Ractor::IsolationError` that make the Ractor pool unusable
+      # (see the ADR-15 Amendment +
+      # docs/notes/20260520-ractor-pool-cruby-uaf.md). The Ractor pool
+      # is preserved but off the default path — `RIGOR_POOL_BACKEND=ractor`
+      # opts back in so it stays testable. Platforms without `fork`
+      # (Windows) fall back to sequential.
+      def pool_backend
+        return :ractor if ENV["RIGOR_POOL_BACKEND"] == "ractor"
+        return :fork if Process.respond_to?(:fork)
+
+        :sequential
+      end
+
+      # Routes pool-mode analysis to the selected backend.
+      def dispatch_pool(files)
+        case pool_backend
+        when :ractor then analyze_files_in_pool(files)
+        when :fork   then analyze_files_in_fork_pool(files)
+        else
+          analyze_files_sequentially_fallback(
+            files, reason: "fork-based parallelism is unavailable on this platform"
+          )
+        end
+      end
+
       # Coordinator-side Environment used by the sequential code
       # path. Pool mode builds one Environment per worker inside
       # the worker Ractor's body instead.
@@ -598,6 +640,122 @@ module Rigor
         Array(prepare_diagnostics) + files.flat_map { |path| results_by_path.fetch(path, []) }
       end
 
+      # ADR-15 Amendment (2026-05-20) — fork-based worker pool, the
+      # active backend for `workers > 0`. Builds ONE {WorkerSession}
+      # on the parent, then `fork`s N children that copy-on-write
+      # inherit it. Each child analyses a contiguous slice of `files`
+      # and writes a Marshal'd `{results:, reporters:}` payload to a
+      # temp file; the parent `Process.wait`s every child, merges the
+      # payloads, and re-orders diagnostics by original path order.
+      #
+      # Separate processes have separate GC heaps and `vm->ci_table`
+      # (immune to Ruby Bug #22075) and copy-on-write-inherit every
+      # constant (no `Ractor.shareable?` constraint). See the ADR-15
+      # Amendment + docs/notes/20260520-ractor-pool-cruby-uaf.md.
+      #
+      # A child that exits non-zero (crash / unmarshalable payload) is
+      # degraded: the parent re-analyses that slice in-process and
+      # prepends a `pool-degraded` warning.
+      def analyze_files_in_fork_pool(files) # rubocop:disable Metrics/AbcSize
+        Environment::ClassRegistry.default
+
+        session = WorkerSession.new(
+          configuration: @configuration,
+          cache_store: @cache_store,
+          plugin_blueprints: @plugin_registry.blueprints,
+          explain: @explain,
+          synthetic_method_index: @synthetic_method_index,
+          project_patched_methods: @project_patched_methods
+        )
+        # Force the full RBS load on the parent so children
+        # copy-on-write inherit a warm Environment rather than each
+        # rebuilding it after the fork.
+        session.environment.rbs_loader&.prewarm
+        snapshot_fork_pool_stats(session) if @collect_stats
+
+        worker_count = [@workers, files.size].min
+        slices = files.each_slice((files.size.to_f / worker_count).ceil).to_a
+        results_by_path = {}
+
+        degraded = Dir.mktmpdir("rigor-fork-pool") do |tmpdir|
+          children = slices.each_with_index.map do |slice, index|
+            out_path = File.join(tmpdir, "worker-#{index}")
+            { pid: fork { run_fork_worker(session, slice, out_path) },
+              slice: slice, out_path: out_path }
+          end
+          collect_fork_results(children, results_by_path)
+        end
+
+        unless degraded.empty?
+          degraded.each { |path| results_by_path[path] = session.analyze(path) }
+          merge_worker_reporters(session.drain_reporters)
+        end
+
+        diagnostics = Array(session.prepare_diagnostics) +
+                      files.flat_map { |path| results_by_path.fetch(path, []) }
+        degraded.empty? ? diagnostics : diagnostics.unshift(fork_degraded_diagnostic(degraded.size))
+      end
+
+      # Child-process body for {#analyze_files_in_fork_pool}. Analyses
+      # the slice with the copy-on-write-inherited session and writes
+      # the Marshal'd payload to `out_path`. `exit!` skips `at_exit` /
+      # stdio flush — the payload is already durable on disk by then.
+      def run_fork_worker(session, slice, out_path)
+        results = slice.to_h { |path| [path, session.analyze(path)] }
+        payload = { results: results, reporters: session.drain_reporters }
+        File.binwrite(out_path, Marshal.dump(payload))
+        exit!(0)
+      rescue StandardError
+        exit!(1)
+      end
+
+      # Snapshots `class_decl_paths` from the parent session's loader
+      # so end-of-run {RunStats} can attribute the RBS class universe.
+      def snapshot_fork_pool_stats(session)
+        loader = session.environment.rbs_loader
+        @class_decl_paths_snapshot = loader&.class_decl_paths || {}.freeze
+        @signature_paths_snapshot = loader&.signature_paths || [].freeze
+      end
+
+      # Waits for every forked child, merges each successful payload
+      # into `results_by_path`, and returns the file paths whose
+      # worker exited abnormally (for in-process degrade).
+      def collect_fork_results(children, results_by_path)
+        degraded = []
+        children.each do |child|
+          _, status = Process.waitpid2(child[:pid])
+          payload = fork_worker_payload(status, child[:out_path])
+          if payload
+            results_by_path.merge!(payload.fetch(:results))
+            merge_worker_reporters(payload.fetch(:reporters))
+          else
+            degraded.concat(child[:slice])
+          end
+        end
+        degraded
+      end
+
+      # @return [Hash, nil] the child's `{results:, reporters:}`
+      #   payload, or nil when the child exited abnormally or wrote no
+      #   readable payload. `Marshal.load` is safe here: the blob was
+      #   written by our own forked child to a temp file we created.
+      def fork_worker_payload(status, out_path)
+        return nil unless status.success? && File.exist?(out_path)
+
+        Marshal.load(File.binread(out_path)) # rubocop:disable Security/MarshalLoad
+      rescue StandardError
+        nil
+      end
+
+      def fork_degraded_diagnostic(count)
+        Diagnostic.new(
+          path: ".rigor.yml", line: 1, column: 1,
+          message: "fork pool degraded: #{count} file(s) re-analysed in-process " \
+                   "after a worker exited abnormally",
+          severity: :warning, rule: "pool-degraded", source_family: :builtin
+        )
+      end
+
       # End-of-run telemetry. Walks the cached
       # `class_decl_paths` snapshot (sequential mode: from
       # the coordinator's environment; pool mode: from the
@@ -1221,12 +1379,29 @@ module Rigor
         Prism.parse(File.read(physical), filepath: path, version: @configuration.target_ruby)
       end
 
+      # Seeds the cross-file project pre-pass indexes onto a
+      # fresh per-file scope: discovered classes, and the ADR-24
+      # def-node / superclass / included-module maps. Each is
+      # applied only when non-empty so a runner constructed
+      # without the project pre-pass (e.g. a single-file probe)
+      # keeps an empty seed.
+      def seed_project_scope(scope)
+        scope = scope.with_discovered_classes(@project_discovered_classes) unless @project_discovered_classes.empty?
+        unless @project_discovered_def_nodes.empty?
+          scope = scope.with_discovered_def_nodes(@project_discovered_def_nodes)
+        end
+        unless @project_discovered_superclasses.empty?
+          scope = scope.with_discovered_superclasses(@project_discovered_superclasses)
+        end
+        scope = scope.with_discovered_includes(@project_discovered_includes) unless @project_discovered_includes.empty?
+        scope
+      end
+
       def analyze_file(path, environment) # rubocop:disable Metrics/MethodLength
         parse_result = parse_source(path)
         return parse_diagnostics(path, parse_result) unless parse_result.errors.empty?
 
-        scope = Scope.empty(environment: environment, source_path: path)
-        scope = scope.with_discovered_classes(@project_discovered_classes) unless @project_discovered_classes.empty?
+        scope = seed_project_scope(Scope.empty(environment: environment, source_path: path))
         index = Inference::ScopeIndexer.index(parse_result.value, default_scope: scope)
         diagnostics = CheckRules.diagnose(
           path: path,

data/lib/rigor/analysis/worker_session.rb

@@ -38,6 +38,12 @@ module Rigor
     # - `plugin_blueprints` — Phase 3a
     #   (`Array<Plugin::Blueprint>` is `Ractor.shareable?`).
     # - `explain` — Boolean.
+    # - `synthetic_method_index` / `project_patched_methods` —
+    #   optional (default `nil`). NOT `Ractor.shareable?`, so the
+    #   Ractor pool path leaves them unset; the fork backend
+    #   (ADR-15 Amendment), which builds the session pre-fork on the
+    #   parent, threads the runner's project-scan results through so
+    #   per-file inference matches the sequential path exactly.
     #
     # Internally the session OWNS (and never shares):
     #
@@ -70,7 +76,7 @@ module Rigor
     # output (modulo severity-profile re-stamping, which the
     # session leaves to the caller because it is a per-run
     # aggregate concern).
-    class WorkerSession
+    class WorkerSession # rubocop:disable Metrics/ClassLength
       attr_reader :configuration, :cache_store, :services, :plugin_registry,
                   :dependency_source_index, :environment,
                   :rbs_extended_reporter, :boundary_cross_reporter,
@@ -88,11 +94,14 @@ module Rigor
       #   directly-unrecognised node, mirroring
       #   {Rigor::Analysis::Runner#explain_diagnostics}.
       def initialize(configuration:, cache_store: nil, # rubocop:disable Metrics/MethodLength
-                     plugin_blueprints: [], explain: false, buffer: nil)
+                     plugin_blueprints: [], explain: false, buffer: nil,
+                     synthetic_method_index: nil, project_patched_methods: nil)
         @configuration = configuration
         @cache_store = cache_store
         @explain = explain
         @buffer = buffer
+        @synthetic_method_index = synthetic_method_index
+        @project_patched_methods = project_patched_methods
 
         # NOTE: `Inference::MethodDispatcher::FileFolding.fold_platform_specific_paths`
         # is process-global state. Writing it from a non-main
@@ -127,7 +136,9 @@ module Rigor
           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
+          rbs_collection_auto_detect: configuration.rbs_collection_auto_detect,
+          synthetic_method_index: @synthetic_method_index,
+          project_patched_methods: @project_patched_methods
         )
         @prepare_diagnostics = run_plugin_prepare.freeze
       end

data/lib/rigor/cli/triage_command.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+require "optionparser"
+
+require_relative "../configuration"
+require_relative "../analysis/runner"
+require_relative "../cache/store"
+require_relative "../triage"
+require_relative "triage_renderer"
+
+module Rigor
+  class CLI
+    # ADR-23 — executes `rigor triage`.
+    #
+    # Runs the same analysis as `rigor check`, then summarises the
+    # diagnostic stream (rule distribution, per-file hotspots,
+    # heuristic hints) instead of printing the raw per-line list.
+    # Read-only and advisory (WD4): never edits config, never
+    # writes a baseline. Always exits 0 — it is an inspection
+    # command, not a gate (`rigor check` remains the gate).
+    class TriageCommand
+      USAGE = "Usage: rigor triage [options] [paths]"
+      DEFAULT_SECTIONS = %i[distribution hotspots hints].freeze
+
+      def initialize(argv:, out:, err:)
+        @argv = argv
+        @out = out
+        @err = err
+      end
+
+      # @return [Integer] CLI exit status (always 0).
+      def run
+        options = parse_options
+        configuration = Configuration.load(options.fetch(:config))
+        diagnostics = analyze(configuration)
+
+        report = Triage.analyze(diagnostics, top: options.fetch(:top),
+                                             hints: options.fetch(:sections).include?(:hints))
+        renderer = TriageRenderer.new(report, sections: options.fetch(:sections))
+        @out.puts(options.fetch(:format) == "json" ? renderer.json : renderer.text)
+        0
+      end
+
+      private
+
+      def parse_options
+        options = { config: nil, format: "text", top: 10, sections: DEFAULT_SECTIONS }
+        OptionParser.new do |opts|
+          opts.banner = USAGE
+          opts.on("--config=PATH", "Path to the Rigor configuration file") { |v| options[:config] = v }
+          opts.on("--format=FORMAT", "Output format: text (default) or json") { |v| options[:format] = v }
+          opts.on("--top=N", Integer, "Hotspot-file count (default 10)") { |v| options[:top] = v }
+          opts.on("--hints-only", "Print only the heuristic-hints section") { options[:sections] = %i[hints] }
+          opts.on("--no-hints", "Print distribution + hotspots only") do
+            options[:sections] = %i[distribution hotspots]
+          end
+        end.parse!(@argv)
+        validate!(options)
+        options
+      end
+
+      def validate!(options)
+        return if %w[text json].include?(options.fetch(:format))
+
+        raise OptionParser::InvalidArgument, "unsupported format: #{options.fetch(:format)}"
+      end
+
+      # Sequential, cache-backed, no run-stats: triage only needs
+      # the diagnostic stream, and sequential keeps the rule
+      # distribution deterministic (the fork pool's cross-file
+      # divergence would skew the histogram).
+      def analyze(configuration)
+        runner = Analysis::Runner.new(
+          configuration: configuration,
+          cache_store: Cache::Store.new(root: configuration.cache_path),
+          collect_stats: false,
+          workers: 0
+        )
+        runner.run(@argv.empty? ? configuration.paths : @argv).diagnostics
+      end
+    end
+  end
+end

data/lib/rigor/cli/triage_renderer.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require "json"
+
+require_relative "../triage"
+
+module Rigor
+  class CLI
+    # ADR-23 — renders a {Rigor::Triage::Report} as the `rigor
+    # triage` text report or as `--format json`.
+    class TriageRenderer
+      BAR_WIDTH = 24
+
+      def initialize(report, sections:)
+        @report = report
+        @sections = sections # subset of %i[distribution hotspots hints]
+      end
+
+      def json
+        JSON.pretty_generate(Triage.report_to_h(@report))
+      end
+
+      def text
+        blocks = []
+        blocks << distribution_block if @sections.include?(:distribution)
+        blocks << hotspots_block     if @sections.include?(:hotspots)
+        blocks << hints_block        if @sections.include?(:hints)
+        "#{blocks.join("\n\n")}\n"
+      end
+
+      private
+
+      def distribution_block
+        s = @report.summary
+        max = @report.distribution.map(&:count).max || 1
+        lines = ["Diagnostic distribution — #{s.total} total " \
+                 "(#{s.error} error / #{s.warning} warning#{" / #{s.info} info" if s.info.positive?})"]
+        @report.distribution.each do |row|
+          lines << format("  %<rule>-32s %<count>5d  %<bar>s",
+                          rule: row.rule, count: row.count, bar: bar(row.count, max))
+        end
+        lines.join("\n")
+      end
+
+      def hotspots_block
+        return "Hotspot files\n  (none)" if @report.hotspots.empty?
+
+        lines = ["Hotspot files"]
+        @report.hotspots.each do |spot|
+          by_rule = spot.by_rule.map { |rule, count| "#{rule}×#{count}" }.join("  ")
+          lines << format("  %<file>-40s %<count>4d  %<rules>s",
+                          file: spot.file, count: spot.count, rules: by_rule)
+        end
+        lines.join("\n")
+      end
+
+      def hints_block
+        return "Hints\n  (no heuristic hints)" if @report.hints.empty?
+
+        lines = ["Hints — heuristics, verify before acting"]
+        @report.hints.each do |hint|
+          lines << ""
+          lines << "  [#{hint.confidence} #{hint.id}]  #{hint.diagnostic_count} diagnostic(s)"
+          lines << "    #{hint.summary}"
+          lines << "    → #{hint.action}"
+        end
+        lines.join("\n")
+      end
+
+      def bar(count, max)
+        filled = max.zero? ? 0 : (count * BAR_WIDTH / max)
+        filled = 1 if filled.zero? && count.positive?
+        "█" * filled
+      end
+    end
+  end
+end

data/lib/rigor/cli.rb

@@ -27,7 +27,8 @@ module Rigor
       "diff" => :run_diff,
       "sig-gen" => :run_sig_gen,
       "lsp" => :run_lsp,
-      "baseline" => :run_baseline
+      "baseline" => :run_baseline,
+      "triage" => :run_triage
     }.freeze
 
     def self.start(argv = ARGV, out: $stdout, err: $stderr)
@@ -464,6 +465,12 @@ module Rigor
       BaselineCommand.new(argv: @argv, out: @out, err: @err).run
     end
 
+    def run_triage
+      require_relative "cli/triage_command"
+
+      CLI::TriageCommand.new(argv: @argv, out: @out, err: @err).run
+    end
+
     def write_result(result, format)
       case format
       when "json"
@@ -505,6 +512,7 @@ module Rigor
           diff       Compare current diagnostics to a saved baseline JSON
           sig-gen    Emit RBS skeletons inferred from .rb sources (ADR-14)
           lsp        Run the Rigor Language Server (LSP) over stdio
+          triage     Summarise diagnostics: distribution, hotspots, hints (ADR-23)
           version    Print the Rigor version
           help       Print this help
       HELP