rigortype 0.1.4 → 0.1.5

data/lib/rigor/configuration.rb

@@ -63,6 +63,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
 
@@ -78,7 +153,9 @@ 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
 
     # Loads a configuration file.
     #
@@ -214,13 +291,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|
@@ -246,10 +323,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,
@@ -269,7 +368,19 @@ 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
 
@@ -327,6 +438,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
 

data/lib/rigor/environment/lockfile_resolver.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+module Rigor
+  class Environment
+    # Open item O4 Layer 3 — Gemfile.lock parse.
+    #
+    # Parses a target project's `Gemfile.lock` via Bundler's
+    # `LockfileParser` and exposes the locked gem set as a frozen
+    # `Hash[String, LockfileResolver::LockedGem]` keyed by gem
+    # name. Used by {Rigor::Environment::BundleSigDiscovery} as a
+    # filter so the discovered `sig/` directories under the
+    # bundler install root are limited to gems the project
+    # actually declares (and at the version it declared them).
+    #
+    # The resolver is intentionally read-only. It does NOT load
+    # the project's `Gemfile`, does NOT resolve dependencies,
+    # does NOT touch the network, and does NOT require the
+    # target project's Bundler context. It only reads bytes from
+    # the lockfile.
+    #
+    # Failure modes are deliberately quiet: a missing or
+    # malformed lockfile returns an empty map. The auto-detect
+    # path is the configuration default; users who want hard
+    # failures should pass an explicit `bundler.lockfile:` and
+    # check the result via the stats banner.
+    module LockfileResolver
+      # Frozen value object for one locked gem entry.
+      #
+      # `version` is the resolved version string (e.g. "8.0.1");
+      # `platform` is the lockfile's platform tag, normalised to
+      # `"ruby"` when the lockfile records `ruby` and to the
+      # raw String otherwise (e.g. "aarch64-linux-gnu").
+      LockedGem = Data.define(:name, :version, :platform) do
+        def initialize(name:, version:, platform:)
+          super(
+            name: -name.to_s,
+            version: -version.to_s,
+            platform: -platform.to_s
+          )
+        end
+      end
+
+      # @param lockfile_path [String, Pathname, nil] explicit path
+      #   to the Gemfile.lock. When `nil`, falls back to
+      #   `auto_detect` if `auto_detect:` is true.
+      # @param project_root [String] resolution base for a
+      #   relative `lockfile_path:` and the auto-detect search.
+      # @param auto_detect [Boolean] when true and
+      #   `lockfile_path:` is nil, look for
+      #   `<project_root>/Gemfile.lock`.
+      # @return [Hash{String => LockedGem}] frozen map of gem
+      #   name → locked entry. Returns the empty frozen hash
+      #   when no lockfile is resolvable, when the file is
+      #   unreadable, or when Bundler refuses to parse it.
+      def self.locked_gems(lockfile_path:, project_root: Dir.pwd, auto_detect: true)
+        resolved = resolve_lockfile_path(
+          lockfile_path: lockfile_path,
+          project_root: project_root,
+          auto_detect: auto_detect
+        )
+        return EMPTY unless resolved
+
+        parse(resolved)
+      end
+
+      # Returns the resolved lockfile path (`Pathname`) or `nil`
+      # when neither explicit nor auto-detect produces one.
+      # Public so the stats banner can show what rigor picked up.
+      def self.resolve_lockfile_path(lockfile_path:, project_root: Dir.pwd, auto_detect: true)
+        if lockfile_path
+          path = Pathname.new(File.expand_path(lockfile_path.to_s, project_root))
+          return path if path.file?
+
+          return nil
+        end
+
+        return nil unless auto_detect
+
+        candidate = Pathname.new(File.join(project_root, "Gemfile.lock"))
+        candidate.file? ? candidate : nil
+      end
+
+      EMPTY = {}.freeze
+      private_constant :EMPTY
+
+      # Parses a Gemfile.lock at the given path. Bundler load
+      # errors and malformed lockfile bytes both surface as the
+      # empty frozen hash; analysis must not crash because a
+      # lockfile is malformed. A single warning is emitted to
+      # `$stderr` so the user can see why their lockfile was
+      # ignored.
+      def self.parse(path)
+        require "bundler"
+      rescue LoadError => e
+        warn "rigor: cannot read #{path}: bundler is not available (#{e.message})"
+        EMPTY
+      else
+        do_parse(path)
+      end
+      private_class_method :parse
+
+      def self.do_parse(path)
+        body = File.read(path.to_s)
+        parser = Bundler::LockfileParser.new(body)
+        locked = parser.specs.each_with_object({}) do |spec, h|
+          # `Bundler::LazySpecification` carries name, version,
+          # platform. Platform is `Gem::Platform` or the symbol
+          # `:ruby`; both stringify cleanly. The upstream
+          # bundler RBS shim (references/rbs/sig/shims/bundler.rbs)
+          # does NOT declare `LazySpecification#platform` so the
+          # call site needs a suppression marker.
+          platform = spec.platform.to_s # rigor:disable undefined-method
+          h[spec.name.to_s] = LockedGem.new(
+            name: spec.name, version: spec.version.to_s, platform: platform
+          )
+        end
+        locked.freeze
+      rescue StandardError => e
+        warn "rigor: ignoring malformed #{path} (#{e.class}: #{e.message})"
+        EMPTY
+      end
+      private_class_method :do_parse
+    end
+  end
+end

data/lib/rigor/environment/rbs_collection_discovery.rb

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module Rigor
+  class Environment
+    # Open item O4 Layer 3 slice 2 — `rbs collection install`
+    # awareness.
+    #
+    # When the target project has been set up with `rbs
+    # collection install` (the standard RBS-ecosystem flow for
+    # pulling community RBS from
+    # https://github.com/ruby/gem_rbs_collection), a
+    # `rbs_collection.lock.yaml` records the resolved (gem,
+    # version, source) triples and `.gem_rbs_collection/<name>/
+    # <version>/` carries the actual `.rbs` files. This module
+    # parses the lockfile and returns the per-gem RBS directory
+    # paths so they can be appended to `RbsLoader`'s
+    # `signature_paths:`.
+    #
+    # The discovery is intentionally a pure file-system + YAML
+    # walk — no Bundler API call, no network access. Failure
+    # modes (missing lockfile, malformed YAML, missing
+    # collection directory) silently degrade to an empty list.
+    module RbsCollectionDiscovery
+      # `stdlib`-typed entries in the lockfile are loaded into
+      # the RBS environment by the standard library mechanism
+      # (rigor's `Environment::DEFAULT_LIBRARIES` already covers
+      # this surface). Including them as `signature_paths:`
+      # entries would risk `RBS::DuplicatedDeclarationError`
+      # (the same hazard O7's failure-memo handles). The other
+      # documented source types — `git` (the gem_rbs_collection
+      # repo), `rubygems` (sigs lifted from a gem's bundled
+      # `sig/`), and `local` (a user-managed RBS dir) — all
+      # produce a directory under the collection root and are
+      # admitted.
+      SKIPPED_SOURCE_TYPES = Set["stdlib"].freeze
+
+      DEFAULT_COLLECTION_PATH = ".gem_rbs_collection"
+      private_constant :DEFAULT_COLLECTION_PATH
+
+      # @param lockfile_path [String, Pathname, nil] explicit
+      #   path to `rbs_collection.lock.yaml`. When `nil`, falls
+      #   back to `auto_detect` if `auto_detect:` is true.
+      # @param project_root [String] resolution base for
+      #   relative `lockfile_path:` and the auto-detect search.
+      # @param auto_detect [Boolean] when true and
+      #   `lockfile_path:` is nil, look for
+      #   `<project_root>/rbs_collection.lock.yaml`.
+      # @return [Array<Pathname>] every
+      #   `<collection_path>/<gem-name>/<gem-version>/`
+      #   directory listed in the lockfile whose entry has a
+      #   non-skipped source type and whose directory exists on
+      #   disk. Returns `[]` when no lockfile is resolvable,
+      #   when the YAML is unreadable, or when the collection
+      #   path doesn't exist.
+      def self.discover(lockfile_path:, project_root: Dir.pwd, auto_detect: true)
+        resolved = resolve_lockfile_path(
+          lockfile_path: lockfile_path,
+          project_root: project_root,
+          auto_detect: auto_detect
+        )
+        return [] if resolved.nil?
+
+        data = read_lockfile_yaml(resolved)
+        return [] if data.nil?
+
+        collection_root = resolve_collection_root(resolved, data)
+        return [] unless collection_root.directory?
+
+        gem_paths_from(collection_root, data)
+      end
+
+      # Returns the resolved lockfile path (`Pathname`) or `nil`
+      # when neither explicit nor auto-detect produces one.
+      # Public so the stats banner can surface what rigor found.
+      def self.resolve_lockfile_path(lockfile_path:, project_root: Dir.pwd, auto_detect: true)
+        if lockfile_path
+          path = Pathname.new(File.expand_path(lockfile_path.to_s, project_root))
+          return path if path.file?
+
+          return nil
+        end
+
+        return nil unless auto_detect
+
+        candidate = Pathname.new(File.join(project_root, "rbs_collection.lock.yaml"))
+        candidate.file? ? candidate : nil
+      end
+
+      def self.read_lockfile_yaml(path)
+        data = YAML.safe_load_file(path.to_s, aliases: false)
+        data.is_a?(Hash) ? data : nil
+      rescue StandardError
+        nil
+      end
+      private_class_method :read_lockfile_yaml
+
+      def self.resolve_collection_root(lockfile_pathname, data)
+        rel = data["path"]
+        rel = DEFAULT_COLLECTION_PATH if rel.nil? || rel.to_s.empty?
+        # `path:` is documented as relative to the directory
+        # holding the lockfile (RBS::Collection::Config::Lockfile#fullpath).
+        lockfile_pathname.parent + Pathname.new(rel.to_s)
+      end
+      private_class_method :resolve_collection_root
+
+      def self.gem_paths_from(collection_root, data)
+        Array(data["gems"]).filter_map do |entry|
+          next unless entry.is_a?(Hash)
+
+          source_type = entry.dig("source", "type").to_s
+          next if SKIPPED_SOURCE_TYPES.include?(source_type)
+
+          name = entry["name"]
+          version = entry["version"]
+          next if name.nil? || version.nil?
+
+          gem_root = collection_root + name.to_s + version.to_s
+          gem_root if gem_root.directory?
+        end
+      end
+      private_class_method :gem_paths_from
+    end
+  end
+end