rigortype 0.1.4 → 0.1.6

data/lib/rigor/cli.rb

@@ -25,7 +25,8 @@ module Rigor
       "type-scan" => :run_type_scan,
       "explain" => :run_explain,
       "diff" => :run_diff,
-      "sig-gen" => :run_sig_gen
+      "sig-gen" => :run_sig_gen,
+      "lsp" => :run_lsp
     }.freeze
 
     def self.start(argv = ARGV, out: $stdout, err: $stderr)
@@ -69,29 +70,91 @@ module Rigor
 
     def run_check
       require_relative "analysis/runner"
+      require_relative "analysis/buffer_binding"
       require_relative "cache/store"
 
       options = parse_check_options
+      buffer = resolve_buffer_binding(options)
+      return EXIT_USAGE if buffer == :usage_error
 
       configuration = Configuration.load(options.fetch(:config))
       cache_root = configuration.cache_path
       handle_clear_cache(cache_root) if options.fetch(:clear_cache)
-      cache_store = options.fetch(:no_cache) ? nil : Cache::Store.new(root: cache_root)
 
-      paths = @argv.empty? ? configuration.paths : @argv
-      runner = Analysis::Runner.new(
-        configuration: configuration,
-        explain: options.fetch(:explain),
-        cache_store: cache_store
+      runner = build_check_runner(
+        configuration: configuration, options: options,
+        buffer: buffer, cache_root: cache_root
       )
-      result = runner.run(paths)
+      result = runner.run(@argv.empty? ? configuration.paths : @argv)
 
       write_result(result, options.fetch(:format))
+      write_run_stats(result.stats) if result.stats
       write_cache_stats(cache_root, runner.cache_store) if options.fetch(:cache_stats)
       result.success? ? 0 : 1
     end
 
-    def parse_check_options
+    def build_check_runner(configuration:, options:, buffer:, cache_root:)
+      cache_store = options.fetch(:no_cache) ? nil : Cache::Store.new(root: cache_root)
+      Analysis::Runner.new(
+        configuration: configuration,
+        explain: options.fetch(:explain),
+        cache_store: cache_store,
+        collect_stats: options.fetch(:stats),
+        workers: resolve_workers(options, configuration),
+        buffer: buffer
+      )
+    end
+
+    # Editor-mode CLI envelope. The `--tmp-file=PATH` /
+    # `--instead-of=PATH` pair binds an in-flight buffer file to
+    # the logical project path it represents (see
+    # `docs/design/20260516-editor-mode.md`). Both flags must
+    # appear together; either alone is a usage error. The
+    # physical file must be readable; missing-file is a usage
+    # error too so editors get one consistent failure shape.
+    #
+    # Returns:
+    # - `nil` when neither flag was supplied (legacy path).
+    # - `Rigor::Analysis::BufferBinding` when the pair is valid.
+    # - `:usage_error` after writing one diagnostic to stderr;
+    #   the caller MUST translate this to `EXIT_USAGE`.
+    def resolve_buffer_binding(options)
+      tmp = options[:tmp_file]
+      instead = options[:instead_of]
+      return nil if tmp.nil? && instead.nil?
+
+      if tmp.nil? || instead.nil?
+        @err.puts("--tmp-file and --instead-of must appear together")
+        return :usage_error
+      end
+
+      unless File.file?(tmp)
+        @err.puts("--tmp-file #{tmp.inspect}: no such file or not readable")
+        return :usage_error
+      end
+
+      Analysis::BufferBinding.new(logical_path: instead, physical_path: tmp)
+    end
+
+    # ADR-15 Phase 4c — resolves the worker count by
+    # precedence: CLI `--workers=N` (most explicit) > env
+    # `RIGOR_RACTOR_WORKERS` > config `.rigor.yml`
+    # `parallel.workers:` > 0 (sequential default). Returns
+    # an Integer; non-numeric values raise so typos fail
+    # loudly. CLI / env may pass a negative value — clamped
+    # to 0 (sequential) so a stray `-1` doesn't crash the
+    # pool spawn loop.
+    def resolve_workers(options, configuration)
+      cli_value = options[:workers]
+      return [Integer(cli_value), 0].max if cli_value
+
+      env_value = ENV.fetch("RIGOR_RACTOR_WORKERS", nil)
+      return [Integer(env_value), 0].max if env_value && !env_value.empty?
+
+      configuration.parallel_workers
+    end
+
+    def parse_check_options # rubocop:disable Metrics/AbcSize,Metrics/MethodLength
       options = {
         # `nil` triggers `Configuration.discover` (`.rigor.yml` then
         # `.rigor.dist.yml`); an explicit `--config=PATH` overrides.
@@ -100,7 +163,24 @@ module Rigor
         explain: false,
         cache_stats: false,
         clear_cache: false,
-        no_cache: false
+        no_cache: false,
+        # Run-stats summary (target files, RBS class universe
+        # breakdown, wall time, peak RSS) is on by default
+        # because collection is ~free (single syscall for RSS,
+        # one walk of `class_decl_paths` for the breakdown).
+        # `--no-stats` suppresses it for callers that want a
+        # diagnostic-only output stream.
+        stats: true,
+        # ADR-15 Phase 4c — when nil, falls back to
+        # `RIGOR_RACTOR_WORKERS` then `.rigor.yml`
+        # `parallel.workers:` then 0 (sequential). See
+        # `resolve_workers` for the precedence chain.
+        workers: nil,
+        # Editor mode (`docs/design/20260516-editor-mode.md`).
+        # Both must appear together; the runner uses the pair
+        # to bind an in-flight buffer file to its logical path.
+        tmp_file: nil,
+        instead_of: nil
       }
       parser = OptionParser.new do |opts|
         opts.banner = "Usage: rigor check [options] [paths]"
@@ -110,6 +190,22 @@ module Rigor
         opts.on("--cache-stats", "Print on-disk cache inventory at end of run") { options[:cache_stats] = true }
         opts.on("--clear-cache", "Remove the .rigor/cache directory before running") { options[:clear_cache] = true }
         opts.on("--no-cache", "Disable the persistent cache for this run") { options[:no_cache] = true }
+        opts.on("--[no-]stats",
+                "Print run summary (files, classes, memory, wall time) to stderr (default: on)") do |value|
+          options[:stats] = value
+        end
+        opts.on("--workers=N", Integer,
+                "Dispatch per-file analysis across N Ractor workers (default: 0; sequential)") do |value|
+          options[:workers] = value
+        end
+        opts.on("--tmp-file=PATH",
+                "Editor mode: read source bytes from PATH instead of --instead-of (paired)") do |value|
+          options[:tmp_file] = value
+        end
+        opts.on("--instead-of=PATH",
+                "Editor mode: the logical project path the buffer represents (paired with --tmp-file)") do |value|
+          options[:instead_of] = value
+        end
       end
       parser.parse!(@argv)
       options
@@ -124,6 +220,15 @@ module Rigor
       end
     end
 
+    # Emits the {Analysis::RunStats} summary to STDERR so it
+    # doesn't interleave with the diagnostic stream (text or
+    # JSON) on STDOUT. JSON consumers can pipe stdout cleanly;
+    # interactive users still see the summary on their tty.
+    def write_run_stats(stats)
+      @err.puts("")
+      stats.format(@err)
+    end
+
     def write_cache_stats(cache_root, runtime_store)
       inv = Cache::Store.disk_inventory(root: cache_root)
 
@@ -286,6 +391,12 @@ module Rigor
       SigGenCommand.new(argv: @argv, out: @out, err: @err).run
     end
 
+    def run_lsp
+      require_relative "cli/lsp_command"
+
+      LspCommand.new(argv: @argv, out: @out, err: @err).run
+    end
+
     def write_result(result, format)
       case format
       when "json"
@@ -326,6 +437,7 @@ module Rigor
           explain    Print the description of one or all CheckRules
           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
           version    Print the Rigor version
           help       Print this help
       HELP

data/lib/rigor/configuration.rb

@@ -49,6 +49,16 @@ module Rigor
       "disable" => [],
       "libraries" => [],
       "signature_paths" => nil,
+      # ADR-17 — project-side monkey-patch pre-evaluation.
+      # Empty by default; users opt in by listing explicit files
+      # that the analyzer walks before per-file inference so
+      # patched-method declarations are visible across the
+      # project (e.g. `lib/core_ext/string_extensions.rb`). Slice 1
+      # plumbing only — listed files are validated at config-load
+      # time (`pre-eval.file-not-found` on a missing path), but
+      # the dispatcher tier consuming the registry lands in
+      # slice 2.
+      "pre_eval" => [],
       "fold_platform_specific_paths" => false,
       "cache" => {
         "path" => ".rigor/cache"
@@ -63,6 +73,81 @@ module Rigor
       "dependencies" => {
         "source_inference" => [],
         "budget_per_gem" => Configuration::Dependencies::DEFAULT_BUDGET_PER_GEM
+      },
+      "parallel" => {
+        # ADR-15 Phase 4c — when greater than zero, `rigor check`
+        # dispatches per-file analysis across N Ractor workers
+        # built around {Rigor::Analysis::WorkerSession}.
+        # `0` (default) keeps the sequential coordinator path
+        # bit-for-bit unchanged. The CLI's `--workers=N` flag
+        # and the `RIGOR_RACTOR_WORKERS` env var both override
+        # this setting; precedence is CLI > env > config > 0.
+        "workers" => 0
+      },
+      "bundler" => {
+        # Open item O4 — target-project Bundler awareness.
+        # When `bundle_path:` is set (or auto-detected), Rigor
+        # walks `<bundle_path>/ruby/*/gems/*/sig/` and adds each
+        # gem-shipped sig directory to `signature_paths:`. With
+        # O7's failure-memo in place, conflicts (a vendored sig
+        # already declares the same constant) degrade gracefully
+        # to "no RBS env" with a single-line warning naming the
+        # offending file, rather than hanging.
+        #
+        # `bundle_path:` (String, optional): explicit path to the
+        # bundler install root (e.g., "vendor/bundle" or an
+        # absolute path). Resolved relative to the project root
+        # (`paths:`'s base) when relative.
+        #
+        # `auto_detect:` (Boolean, default true): when no
+        # explicit `bundle_path:` is set, try `.bundle/config`'s
+        # `BUNDLE_PATH:` first; fall back to `vendor/bundle/`
+        # under the project root if it exists. When neither is
+        # found, no extra sigs are added — the analyzer sees
+        # only rigor's vendored RBS and the user's
+        # `signature_paths:`.
+        #
+        # O4 Layer 3 keys:
+        #
+        # `lockfile:` (String, optional): explicit path to a
+        # `Gemfile.lock`. Resolved relative to the project root
+        # when relative. When set (or auto-detected via the
+        # `auto_detect:` flag below) Rigor parses the lockfile
+        # and uses it to FILTER the bundle-discovered `sig/`
+        # directories: only gems whose `(name, version,
+        # platform)` matches a lockfile entry are admitted to
+        # `signature_paths:`. Stale or out-of-band gems sitting
+        # in the bundle install tree are silently dropped.
+        #
+        # `auto_detect:` (Boolean, also gates the lockfile
+        # search): when true and `lockfile:` is nil, look for
+        # `<project_root>/Gemfile.lock`.
+        "bundle_path" => nil,
+        "auto_detect" => true,
+        "lockfile" => nil
+      },
+      "rbs_collection" => {
+        # Open item O4 Layer 3 slice 2 — `rbs collection
+        # install` awareness. When the target project has been
+        # set up with `rbs collection install`, the resulting
+        # `rbs_collection.lock.yaml` carries the resolved (gem,
+        # version, source) triples and `.gem_rbs_collection/`
+        # holds the downloaded `.rbs` files. Rigor parses the
+        # lockfile and auto-feeds each gem's
+        # `<collection_root>/<name>/<version>/` directory into
+        # `RbsLoader`'s `signature_paths:`. Sources of type
+        # `stdlib` are skipped because rigor's bundled
+        # `DEFAULT_LIBRARIES` already covers that surface.
+        #
+        # `lockfile:` (String, optional): explicit path to
+        # `rbs_collection.lock.yaml`. Resolved relative to the
+        # project root when relative.
+        #
+        # `auto_detect:` (Boolean, default true): when no
+        # explicit `lockfile:` is set, look for
+        # `<project_root>/rbs_collection.lock.yaml`.
+        "lockfile" => nil,
+        "auto_detect" => true
       }
     }.freeze
 
@@ -70,7 +155,7 @@ module Rigor
     # MUST be resolved relative to the config file's directory.
     # `exclude:` is intentionally NOT in this list — its entries
     # are glob patterns (`**/vendor/**`), not paths.
-    PATH_KEYS = %w[paths signature_paths].freeze
+    PATH_KEYS = %w[paths signature_paths pre_eval].freeze
     private_constant :PATH_KEYS
 
     attr_reader :target_ruby, :paths, :exclude_patterns, :plugins, :cache_path, :disabled_rules,
@@ -78,7 +163,10 @@ module Rigor
                 :plugins_io_network, :plugins_io_allowed_paths,
                 :plugins_io_allowed_url_hosts,
                 :severity_profile, :severity_overrides,
-                :dependencies
+                :dependencies, :parallel_workers,
+                :bundler_bundle_path, :bundler_auto_detect, :bundler_lockfile,
+                :rbs_collection_lockfile, :rbs_collection_auto_detect,
+                :pre_eval
 
     # Loads a configuration file.
     #
@@ -214,13 +302,13 @@ module Rigor
     private_class_method :load_with_includes, :merge_includes, :resolve_paths_in, :deep_merge,
                          :merge_value, :merge_dependencies_hash
 
-    # rubocop:disable Metrics/AbcSize
+    # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
     def initialize(data = DEFAULTS)
       cache = DEFAULTS.fetch("cache").merge(data.fetch("cache", {}))
       plugins_io = DEFAULTS.fetch("plugins_io").merge(data.fetch("plugins_io", {}))
 
       @target_ruby = coerce_target_ruby(data.fetch("target_ruby", DEFAULTS.fetch("target_ruby")))
-      @paths = Array(data.fetch("paths", DEFAULTS.fetch("paths"))).map(&:to_s)
+      @paths = Array(data.fetch("paths", DEFAULTS.fetch("paths"))).map(&:to_s).freeze
       user_excludes = Array(data.fetch("exclude", DEFAULTS.fetch("exclude"))).map(&:to_s)
       @exclude_patterns = (BUILTIN_EXCLUDES + user_excludes).uniq.freeze
       @plugins = Array(data.fetch("plugins", DEFAULTS.fetch("plugins"))).map do |entry|
@@ -230,6 +318,9 @@ module Rigor
       @libraries = Array(data.fetch("libraries", DEFAULTS.fetch("libraries"))).map(&:to_s).freeze
       sig_paths = data.fetch("signature_paths", DEFAULTS.fetch("signature_paths"))
       @signature_paths = sig_paths.nil? ? nil : Array(sig_paths).map(&:to_s).freeze
+      @pre_eval = expand_pre_eval_entries(
+        Array(data.fetch("pre_eval", DEFAULTS.fetch("pre_eval"))).map(&:to_s)
+      )
       @fold_platform_specific_paths = data.fetch(
         "fold_platform_specific_paths", DEFAULTS.fetch("fold_platform_specific_paths")
       ) == true
@@ -246,10 +337,32 @@ module Rigor
       @dependencies = Dependencies.from_h(
         data.fetch("dependencies", DEFAULTS.fetch("dependencies"))
       )
+      parallel = DEFAULTS.fetch("parallel").merge(data.fetch("parallel", {}))
+      @parallel_workers = coerce_parallel_workers(parallel.fetch("workers"))
+      bundler = DEFAULTS.fetch("bundler").merge(data.fetch("bundler", {}))
+      bp = bundler.fetch("bundle_path")
+      @bundler_bundle_path = bp.nil? ? nil : bp.to_s.dup.freeze
+      @bundler_auto_detect = bundler.fetch("auto_detect") == true
+      lf = bundler.fetch("lockfile")
+      @bundler_lockfile = lf.nil? ? nil : lf.to_s.dup.freeze
+      rbs_collection = DEFAULTS.fetch("rbs_collection").merge(data.fetch("rbs_collection", {}))
+      rclf = rbs_collection.fetch("lockfile")
+      @rbs_collection_lockfile = rclf.nil? ? nil : rclf.to_s.dup.freeze
+      @rbs_collection_auto_detect = rbs_collection.fetch("auto_detect") == true
+      # Ractor migration Phase 2a: deep-freeze the
+      # Configuration so it is `Ractor.shareable?`. Every
+      # ivar above is now either a frozen value (Symbol /
+      # nil / Boolean) or an explicitly frozen
+      # collection / value object; freezing `self` makes the
+      # whole carrier safe to send across Ractor boundaries
+      # (and catches accidental post-init mutation in any
+      # caller). See
+      # `docs/design/20260514-ractor-migration.md`.
+      freeze
     end
-    # rubocop:enable Metrics/AbcSize
+    # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
 
-    def to_h
+    def to_h # rubocop:disable Metrics/MethodLength
       {
         "target_ruby" => target_ruby,
         "paths" => paths,
@@ -258,6 +371,7 @@ module Rigor
         "disable" => disabled_rules,
         "libraries" => libraries,
         "signature_paths" => signature_paths,
+        "pre_eval" => pre_eval,
         "fold_platform_specific_paths" => fold_platform_specific_paths,
         "cache" => {
           "path" => cache_path
@@ -269,12 +383,45 @@ module Rigor
         },
         "severity_profile" => severity_profile.to_s,
         "severity_overrides" => severity_overrides.to_h { |k, v| [k, v.to_s] },
-        "dependencies" => dependencies.to_h
+        "dependencies" => dependencies.to_h,
+        "parallel" => {
+          "workers" => parallel_workers
+        },
+        "bundler" => {
+          "bundle_path" => bundler_bundle_path,
+          "auto_detect" => bundler_auto_detect,
+          "lockfile" => bundler_lockfile
+        },
+        "rbs_collection" => {
+          "lockfile" => rbs_collection_lockfile,
+          "auto_detect" => rbs_collection_auto_detect
+        }
       }
     end
 
     private
 
+    # ADR-17 slice 4 — `pre_eval:` glob expansion. Each entry is
+    # accepted as either a literal path (slice 1 contract) OR a
+    # `File.fnmatch?`-shaped glob pattern (`lib/core_ext/**/*.rb`).
+    # Glob meta characters (`*`, `?`, `[`) trigger `Dir.glob`
+    # expansion; the resulting file list is folded into the
+    # `pre_eval:` set with `uniq`. Literal entries that don't
+    # exist on disk continue to surface as `pre-eval.file-not-found`
+    # `:error` (slice 1 behaviour); glob entries that match
+    # nothing degrade silently to "no contribution from this
+    # entry" so a templated `**` pattern in a fresh project
+    # doesn't generate an error per match-less pattern.
+    def expand_pre_eval_entries(entries)
+      entries.flat_map do |entry|
+        glob_pattern?(entry) ? Dir.glob(entry, sort: true) : [entry]
+      end.uniq.freeze
+    end
+
+    def glob_pattern?(path)
+      path.include?("*") || path.include?("?") || path.include?("[")
+    end
+
     # Accepts either `"rigor-foo"` (gem-name shorthand) or
     # `{ "gem" => "rigor-foo", "id" => "foo", "config" => {...} }`
     # (full form). Returns the canonical hash form so the loader
@@ -327,6 +474,20 @@ module Rigor
     VALID_NETWORK_POLICIES = %i[disabled allowlist].freeze
     private_constant :VALID_NETWORK_POLICIES
 
+    # ADR-15 Phase 4c — accepts a non-negative Integer (or a
+    # string-shaped one from YAML files that miss type
+    # annotations). Negative / non-integer values raise so
+    # typos / bad YAML fail loudly rather than silently
+    # disabling parallelism.
+    def coerce_parallel_workers(value)
+      integer = Integer(value)
+      raise ArgumentError, "parallel.workers must be >= 0, got #{value.inspect}" if integer.negative?
+
+      integer
+    rescue TypeError, ArgumentError => e
+      raise ArgumentError, "parallel.workers must be a non-negative Integer, got #{value.inspect} (#{e.message})"
+    end
+
     def coerce_network_policy(value)
       sym = value.to_sym
       unless VALID_NETWORK_POLICIES.include?(sym)

data/lib/rigor/environment/bundle_sig_discovery.rb

@@ -0,0 +1,198 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module Rigor
+  class Environment
+    # Open item O4 — target-project Bundler awareness.
+    #
+    # Walks a Bundler-installed gem tree (e.g., the project's
+    # `vendor/bundle` or a Docker-mounted bundle root) and
+    # returns the per-gem `sig/` directories to feed into
+    # `RbsLoader`'s `signature_paths:`. Of the ~3% of gems that
+    # ship `sig/` in their gem package today (per the four-project
+    # Mastodon Docker bundle-install measurement on 2026-05-15:
+    # 10 of 343 gems shipped sig — `prism`, `aws-sdk-s3`,
+    # `aws-sdk-kms`, `aws-sdk-core`, `playwright-ruby-client`,
+    # `mutex_m`, `webrick`, `base64`, `stoplight`, `ffi`), this
+    # discovery surfaces the typed contract the gem author
+    # explicitly published.
+    #
+    # Conflicts with rigor's bundled stdlib RBS (the prism case
+    # was the motivating example) degrade gracefully via O7's
+    # failure-memo in `RbsLoader#env`: a single warning naming
+    # the offending file is emitted and analysis continues with
+    # `Dynamic[top]` everywhere rather than hanging.
+    #
+    # The discovery is intentionally a pure file-system walk —
+    # no `Bundler` API call, no `Gemfile.lock` parse — so rigor
+    # doesn't need the target project's Bundler context.
+    module BundleSigDiscovery
+      # Gems already covered by rigor's `DEFAULT_LIBRARIES`
+      # (stdlib RBS) plus the `data/vendored_gem_sigs/` bundle.
+      # Skipping these from bundle discovery prevents
+      # `RBS::DuplicatedDeclarationError` (the prism case was the
+      # motivating example — Ruby 4.0 ships prism's RBS in
+      # stdlib, and the gem also ships its own `sig/`, so loading
+      # both raises on `Prism::BACKEND` etc.).
+      #
+      # The list is hard-coded for the MVP because it tracks
+      # rigor's bundled coverage 1:1. When a new gem is vendored
+      # under `data/vendored_gem_sigs/` or added to
+      # `DEFAULT_LIBRARIES`, add its name here.
+      SKIPPED_GEMS_BY_DEFAULT = Set[
+        # DEFAULT_LIBRARIES (lib/rigor/environment.rb)
+        "pathname", "optparse", "json", "yaml", "fileutils",
+        "tempfile", "tmpdir", "stringio", "forwardable",
+        "digest", "securerandom", "uri", "logger", "date",
+        "pp", "delegate", "singleton", "observable", "abbrev",
+        "find", "tsort", "shellwords", "benchmark", "base64",
+        "did_you_mean", "monitor", "mutex_m", "timeout",
+        "open3", "erb", "etc", "ipaddr", "bigdecimal",
+        "bigdecimal-math", "prettyprint",
+        "random-formatter", "time", "open-uri", "resolv",
+        "csv", "pstore", "objspace", "io-console", "cgi", "cgi-escape",
+        "strscan",
+        "prism", "rbs",
+        # data/vendored_gem_sigs/
+        "pg", "mysql2", "nokogiri", "bcrypt", "redis", "idn-ruby"
+      ].freeze
+
+      # @param bundle_path [String, Pathname, nil] explicit path
+      #   to the bundler install root. When `nil`, falls back to
+      #   `auto_detect` if `auto_detect:` is true.
+      # @param project_root [String] resolution base for relative
+      #   `bundle_path:` and the auto-detect search.
+      # @param auto_detect [Boolean] when true and `bundle_path:`
+      #   is nil, try `.bundle/config`'s `BUNDLE_PATH:` and
+      #   `vendor/bundle/` under `project_root`.
+      # @param skip_gems [Set<String>] gem names to exclude from
+      #   discovery. Defaults to {SKIPPED_GEMS_BY_DEFAULT}.
+      # @param locked_gems [Hash{String => LockfileResolver::LockedGem}, nil]
+      #   Optional O4-Layer-3 filter. When non-nil and non-empty,
+      #   only `sig/` directories whose gem `(name, version,
+      #   platform)` tuple matches a lockfile entry are returned.
+      #   Bundle entries absent from the lockfile (or at a drifted
+      #   version) are silently dropped — the lockfile is treated
+      #   as the source of truth for "what gems this project
+      #   actually declares". Pass `nil` (the default) to keep
+      #   the pre-Layer-3 behaviour of returning every non-skipped
+      #   `sig/` under the bundle.
+      # @return [Array<Pathname>] every `<gem-dir>/sig` directory
+      #   under the resolved bundle path, minus any whose gem
+      #   name is in `skip_gems` and (when `locked_gems` is
+      #   supplied) minus any whose `(name, version, platform)`
+      #   does not match a lockfile entry.
+      def self.discover(bundle_path:, project_root: Dir.pwd, auto_detect: true,
+                        skip_gems: SKIPPED_GEMS_BY_DEFAULT, locked_gems: nil)
+        resolved = resolve_bundle_path(
+          bundle_path: bundle_path,
+          project_root: project_root,
+          auto_detect: auto_detect
+        )
+        return [] if resolved.nil?
+
+        # `<bundle>/ruby/X.Y.Z/gems/<name>-<ver>/sig/` is the
+        # canonical bundler layout. `*` on the ruby version dir
+        # picks up whichever Ruby the bundle was installed for.
+        all = Dir.glob(resolved.join("ruby", "*", "gems", "*", "sig")).map { |d| Pathname.new(d) }
+        filtered = all.reject { |sig_dir| skip_gems.include?(gem_name_from_sig_path(sig_dir)) }
+        return filtered if locked_gems.nil? || locked_gems.empty?
+
+        expected_dirs = expected_gem_dirs(locked_gems)
+        filtered.select { |sig_dir| expected_dirs.include?(sig_dir.parent.basename.to_s) }
+      end
+
+      # `{name => LockedGem}` → set of canonical bundler gem
+      # directory basenames. Pure-Ruby gems install as
+      # `<name>-<version>`; platform-specific gems install as
+      # `<name>-<version>-<platform>` (e.g. `ffi-1.17.4-aarch64-linux-gnu`).
+      # Lockfile platform `"ruby"` is the pure-Ruby case; any
+      # other value is treated as a platform tag.
+      def self.expected_gem_dirs(locked_gems)
+        locked_gems.each_value.with_object(Set.new) do |locked, set|
+          base = "#{locked.name}-#{locked.version}"
+          set << if locked.platform == "ruby" || locked.platform.empty?
+                   base
+                 else
+                   "#{base}-#{locked.platform}"
+                 end
+        end
+      end
+      private_class_method :expected_gem_dirs
+
+      # `<bundle>/ruby/X.Y.Z/gems/<name>-<ver>/sig` → `<name>`.
+      # The gem directory follows the canonical
+      # `<name>-<version>` pattern; we strip everything from the
+      # last hyphen onwards to recover the name. (Platform-tagged
+      # variants like `ffi-1.17.4-aarch64-linux-gnu/` keep their
+      # platform suffix in the version part, so the first hyphen
+      # from the right is still the name boundary.)
+      #
+      # Public so the O4 Layer 3 slice-3 coverage report
+      # (`RbsCoverageReport`) can classify discovered bundle sigs
+      # against locked gem names without re-running discovery.
+      def self.gem_name_from_sig_path(sig_dir)
+        gem_dir = sig_dir.parent.basename.to_s
+        # Strip `-<version>` and any platform suffix. The version
+        # always starts with a digit, so split at the first
+        # `-` followed by a digit.
+        gem_dir.sub(/-\d.*\z/, "")
+      end
+
+      # Returns `Pathname` resolved bundle path, or `nil` when
+      # neither explicit nor auto-detected. Public for the stats
+      # banner so end users can see what rigor picked up.
+      def self.resolve_bundle_path(bundle_path:, project_root: Dir.pwd, auto_detect: true)
+        if bundle_path
+          path = Pathname.new(File.expand_path(bundle_path.to_s, project_root))
+          return path if path.directory?
+
+          return nil
+        end
+
+        return nil unless auto_detect
+
+        detected = auto_detect(project_root: project_root)
+        Pathname.new(detected) if detected
+      end
+
+      # Auto-detection order:
+      # 1. `<project_root>/.bundle/config` carries `BUNDLE_PATH:`
+      #    set by `bundle config set --local path <dir>`.
+      # 2. `<project_root>/vendor/bundle/` — the conventional
+      #    in-tree install location when a developer ran
+      #    `bundle install --path vendor/bundle`.
+      # 3. `nil` — let the caller proceed without bundle sig
+      #    discovery (rigor's vendored RBS still loads).
+      def self.auto_detect(project_root:)
+        from_config = read_bundle_config_path(project_root)
+        return File.expand_path(from_config, project_root) if from_config
+
+        vendor = File.join(project_root, "vendor", "bundle")
+        return vendor if File.directory?(vendor)
+
+        nil
+      end
+
+      def self.read_bundle_config_path(project_root)
+        config_path = File.join(project_root, ".bundle", "config")
+        return nil unless File.exist?(config_path)
+
+        # `.bundle/config` is YAML with all-caps env-style keys.
+        # `BUNDLE_PATH:` is the canonical key (Bundler 2.x); the
+        # `--path` flag sets it.
+        data = YAML.safe_load_file(config_path)
+        return nil unless data.is_a?(Hash)
+
+        data["BUNDLE_PATH"]
+      rescue StandardError
+        # Malformed `.bundle/config` should not break analysis;
+        # silently skip auto-detection.
+        nil
+      end
+
+      private_class_method :read_bundle_config_path
+    end
+  end
+end

data/lib/rigor/environment/class_registry.rb

@@ -67,10 +67,19 @@ module Rigor
 
         private
 
+        # ADR-15 Phase 4b — the default registry MUST be
+        # `Ractor.shareable?` so worker Ractors that consult
+        # `Environment.for_project`'s default `class_registry:`
+        # don't trip `Ractor::IsolationError`. The internal
+        # `@nominals` / `@class_objects` Hashes are populated
+        # via `register`, then `Ractor.make_shareable`
+        # recursively freezes the registry, the two Hashes,
+        # and confirms every entry (Type::Nominal carriers +
+        # core Ruby classes) is itself shareable.
         def build_default
-          new.tap do |registry|
-            CORE_BUILT_INS.each { |klass| registry.register(klass) }
-          end.freeze
+          registry = new
+          CORE_BUILT_INS.each { |klass| registry.register(klass) }
+          Ractor.make_shareable(registry)
         end
       end