rigortype 0.1.7 → 0.1.9

data/lib/rigor/analysis/check_rules.rb

@@ -355,6 +355,15 @@ module Rigor
           class_name = concrete_class_name(receiver_type)
           return nil if class_name.nil?
 
+          # ADR-26 — a plugin may declare a class "open": one
+          # known to respond beyond its RBS-declared method
+          # surface (e.g. `ActiveRecord::Relation`, which
+          # delegates an unbounded set of user-defined scopes to
+          # 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)
+
           # Slice 7 phase 12 — suppress when the user has
           # declared the method in source (instance `def`,
           # `def self.foo`, or recognised `define_method`).
@@ -424,6 +433,17 @@ module Rigor
           nil
         end
 
+        # ADR-26 — whether `class_name` is declared "open" by a
+        # loaded plugin (manifest `open_receivers:`). An open
+        # class responds beyond its RBS surface, so the
+        # `call.undefined-method` rule must not fire for it.
+        def open_receiver?(class_name, scope)
+          registry = scope.environment&.plugin_registry
+          return false if registry.nil?
+
+          registry.open_receiver?(class_name)
+        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?
@@ -1215,7 +1235,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/annotate_command.rb

@@ -0,0 +1,224 @@
+# frozen_string_literal: true
+
+require "optionparser"
+require "prism"
+
+require_relative "../configuration"
+require_relative "../environment"
+require_relative "../scope"
+require_relative "../inference/scope_indexer"
+require_relative "prism_colorizer"
+
+module Rigor
+  class CLI
+    # Executes `rigor annotate FILE`.
+    #
+    # For every source line the command finds the expression the
+    # line evaluates to — the last statement that ends on the line
+    # (so `1; 2; 3` reports `3`), or, for a line that no statement
+    # closes, the widest expression ending there (so the `if nil`
+    # header reports its condition). It infers that expression's
+    # type and appends a `#=> dump_type: <type>` comment.
+    #
+    # The annotated source is re-parsed with Prism — a sanity gate,
+    # since the appended text is always a comment — and printed to
+    # stdout with IRB-style syntax highlighting via
+    # {PrismColorizer}.
+    class AnnotateCommand
+      USAGE = "Usage: rigor annotate [options] FILE"
+
+      # Appended ` #=> dump_type: <type>` suffix. Matched and
+      # stripped before re-annotating so re-running is idempotent.
+      ANNOTATION_PATTERN = /\s*#=>\s*dump_type:.*\z/
+
+      def initialize(argv:, out:, err:)
+        @argv = argv
+        @out = out
+        @err = err
+      end
+
+      # @return [Integer] CLI exit status.
+      def run
+        options = parse_options
+        file = @argv.shift
+        if file.nil?
+          @err.puts(USAGE)
+          return CLI::EXIT_USAGE
+        end
+        unless File.file?(file)
+          @err.puts("annotate: file not found: #{file}")
+          return 1
+        end
+
+        execute(file, options)
+      end
+
+      private
+
+      def parse_options
+        # Default: colour a tty, unless `NO_COLOR` opts out. An
+        # explicit `--color` / `--no-color` overrides both.
+        options = { config: nil, color: @out.tty? && !no_color_env? }
+
+        parser = OptionParser.new do |opts|
+          opts.banner = USAGE
+          opts.on("--config=PATH", "Path to the Rigor configuration file") { |value| options[:config] = value }
+          opts.on("--[no-]color",
+                  "Force or disable ANSI colour (default: auto-detect a tty; honours NO_COLOR)") do |value|
+            options[:color] = value
+          end
+        end
+        parser.parse!(@argv)
+
+        options
+      end
+
+      # https://no-color.org — colour output is suppressed by
+      # default when `NO_COLOR` is present and not an empty string,
+      # regardless of its value.
+      def no_color_env?
+        value = ENV.fetch("NO_COLOR", nil)
+        !value.nil? && !value.empty?
+      end
+
+      def execute(file, options)
+        configuration = Configuration.load(options.fetch(:config))
+        source = File.read(file)
+        parse_result = Prism.parse(source, filepath: file, version: configuration.target_ruby)
+        return 1 if parse_errors?(parse_result, file)
+
+        scope_index = Inference::ScopeIndexer.index(
+          parse_result.value, default_scope: base_scope(configuration)
+        )
+        line_types = LineTypeCollector.new(scope_index).collect(parse_result.value)
+
+        @out.puts(render(annotate(source, line_types), color: options.fetch(:color)))
+        0
+      end
+
+      def base_scope(configuration)
+        Scope.empty(
+          environment: Environment.for_project(
+            libraries: configuration.libraries,
+            signature_paths: configuration.signature_paths
+          )
+        )
+      end
+
+      def parse_errors?(parse_result, file)
+        return false if parse_result.success?
+
+        parse_result.errors.each do |error|
+          @err.puts("#{file}:#{error.location.start_line}: #{error.message}")
+        end
+        true
+      end
+
+      # Appends ` #=> dump_type: <type>` to every line a type was
+      # inferred for, aligning the comment column.
+      def annotate(source, line_types)
+        lines = source.lines
+        column = annotation_column(lines, line_types)
+
+        lines.each_with_index.map do |line, index|
+          type = line_types[index + 1]
+          eol = line.end_with?("\n") ? "\n" : ""
+          code = line.chomp.sub(ANNOTATION_PATTERN, "")
+          next "#{code}#{eol}" if type.nil?
+
+          "#{code.ljust(column)}  #=> dump_type: #{type.describe(:short)}#{eol}"
+        end.join
+      end
+
+      def annotation_column(lines, line_types)
+        widths = lines.each_index.filter_map do |index|
+          next unless line_types.key?(index + 1)
+
+          lines[index].chomp.sub(ANNOTATION_PATTERN, "").length
+        end
+        widths.max || 0
+      end
+
+      def render(annotated, color:)
+        return annotated unless color
+        return annotated unless Prism.parse(annotated).success?
+
+        PrismColorizer.colorize(annotated)
+      end
+    end
+
+    # Walks a parsed program and resolves, per source line, the
+    # type of the expression the line evaluates to. Used only by
+    # {AnnotateCommand}.
+    class LineTypeCollector
+      def initialize(scope_index)
+        @scope_index = scope_index
+      end
+
+      # @param program [Prism::ProgramNode]
+      # @return [Hash{Integer => Rigor::Type}] 1-indexed line => type.
+      def collect(program)
+        by_line = {}
+        each_statement(program) do |statement|
+          type = type_of(statement)
+          by_line[statement.location.end_line] = type unless type.nil?
+        end
+        fill_uncovered_lines(program, by_line)
+        by_line
+      end
+
+      private
+
+      # Yields each statement node (a child of any `StatementsNode`
+      # anywhere in the tree) in source order, so a later statement
+      # ending on a line overwrites an earlier one — `1; 2; 3`
+      # resolves to `3`.
+      def each_statement(node, &)
+        return if node.nil?
+
+        node.body.each(&) if node.is_a?(Prism::StatementsNode)
+        node.compact_child_nodes.each { |child| each_statement(child, &) }
+      end
+
+      # For a line no statement closes (the `if` / block header
+      # lines), fall back to the widest expression ending there.
+      def fill_uncovered_lines(program, by_line)
+        widest_per_line(program).each do |line, node|
+          next if by_line.key?(line)
+
+          type = type_of(node)
+          by_line[line] = type unless type.nil?
+        end
+      end
+
+      def widest_per_line(program)
+        widest = {}
+        walk(program) do |node|
+          next if node.is_a?(Prism::ProgramNode) || node.is_a?(Prism::StatementsNode)
+
+          line = node.location.end_line
+          current = widest[line]
+          widest[line] = node if current.nil? || span(node) > span(current)
+        end
+        widest
+      end
+
+      def span(node)
+        node.location.end_offset - node.location.start_offset
+      end
+
+      def walk(node, &block)
+        return if node.nil?
+
+        block.call(node)
+        node.compact_child_nodes.each { |child| walk(child, &block) }
+      end
+
+      def type_of(node)
+        @scope_index[node].type_of(node)
+      rescue StandardError
+        nil
+      end
+    end
+  end
+end