rigortype 0.2.8 → 0.3.0

data/lib/rigor/configuration/severity_profile.rb

@@ -37,11 +37,15 @@ module Rigor
           "call.wrong-arity" => :error,
           "call.argument-type-mismatch" => :warning,
           "call.possible-nil-receiver" => :warning,
+          "call.raise-non-exception" => :warning,
           "flow.always-raises" => :warning,
           "flow.unreachable-branch" => :info,
           "flow.dead-assignment" => :info,
           "flow.always-truthy-condition" => :info,
           "flow.unreachable-clause" => :info,
+          "flow.duplicate-hash-key" => :info,
+          "flow.return-in-ensure" => :info,
+          "flow.shadowed-rescue-clause" => :info,
           "assert.type-mismatch" => :error,
           "dump.type" => :info,
           "def.return-type-mismatch" => :warning,
@@ -50,6 +54,16 @@ module Rigor
           "def.override-return-widened" => :off,
           "def.override-param-narrowed" => :off,
           "def.ivar-write-mismatch" => :warning,
+          # ADR-8 companion (PHPStan IgnoreParseErrorRule-modelled): a broken suppression comment is
+          # equally bad in every profile — it silently fails to do what the author believes it does — so
+          # both rules stay :warning across all three profiles (including strict).
+          "suppression.unknown-rule" => :warning,
+          "suppression.empty" => :warning,
+          "suppression.unknown-marker" => :warning,
+          # ADR-100 — a new required diagnostic (ADR-50 WD1), so it is `:off` in every shipped profile and
+          # reaches a user only through the `use-of-void-value` bleeding-edge feature, which overrides this
+          # to `:warning`.
+          "static.value-use.void" => :off,
           # Opt-in author assertion: you only see it if you wrote a
           # `conforms-to` directive, so it stays a :warning even in
           # lenient — it is never unsolicited noise.
@@ -62,6 +76,7 @@ module Rigor
           "call.wrong-arity" => :error,
           "call.argument-type-mismatch" => :error,
           "call.possible-nil-receiver" => :error,
+          "call.raise-non-exception" => :error,
           "flow.always-raises" => :error,
           "flow.unreachable-branch" => :warning,
           "flow.dead-assignment" => :warning,
@@ -71,6 +86,9 @@ module Rigor
           # green; promote to :warning once Mastodon/GitLab/Redmine triage
           # to zero net false positives.
           "flow.unreachable-clause" => :info,
+          "flow.duplicate-hash-key" => :warning,
+          "flow.return-in-ensure" => :warning,
+          "flow.shadowed-rescue-clause" => :warning,
           "assert.type-mismatch" => :error,
           "dump.type" => :info,
           "def.return-type-mismatch" => :warning,
@@ -79,6 +97,10 @@ module Rigor
           "def.override-return-widened" => :warning,
           "def.override-param-narrowed" => :warning,
           "def.ivar-write-mismatch" => :warning,
+          "suppression.unknown-rule" => :warning,
+          "suppression.empty" => :warning,
+          "suppression.unknown-marker" => :warning,
+          "static.value-use.void" => :off,
           "rbs_extended.unsatisfied-conformance" => :warning
         }.freeze,
         strict: {
@@ -88,6 +110,7 @@ module Rigor
           "call.wrong-arity" => :error,
           "call.argument-type-mismatch" => :error,
           "call.possible-nil-receiver" => :error,
+          "call.raise-non-exception" => :error,
           "flow.always-raises" => :error,
           "flow.unreachable-branch" => :error,
           "flow.dead-assignment" => :error,
@@ -96,6 +119,9 @@ module Rigor
           # below its :error siblings) while it proves out — see the
           # balanced-profile note above.
           "flow.unreachable-clause" => :warning,
+          "flow.duplicate-hash-key" => :error,
+          "flow.return-in-ensure" => :error,
+          "flow.shadowed-rescue-clause" => :error,
           "assert.type-mismatch" => :error,
           "dump.type" => :error,
           "def.return-type-mismatch" => :error,
@@ -104,6 +130,11 @@ module Rigor
           "def.override-return-widened" => :error,
           "def.override-param-narrowed" => :error,
           "def.ivar-write-mismatch" => :error,
+          "suppression.unknown-rule" => :warning,
+          "suppression.empty" => :warning,
+          "suppression.unknown-marker" => :warning,
+          # `:off` even under strict: the gate is `bleeding_edge:`, not the profile (ADR-50 WD1 / ADR-100).
+          "static.value-use.void" => :off,
           "rbs_extended.unsatisfied-conformance" => :error
         }.freeze
       }.freeze

data/lib/rigor/configuration.rb

@@ -3,6 +3,7 @@
 require "yaml"
 
 require_relative "bleeding_edge"
+require_relative "ci_detector"
 require_relative "configuration/dependencies"
 require_relative "configuration/severity_profile"
 
@@ -55,6 +56,13 @@ module Rigor
       # filtering — the path must be named here (WD2 (b) of ADR-22).
       "baseline" => nil,
       "fold_platform_specific_paths" => false,
+      # ADR-67 WD6a — opt-in call-site parameter type inference on the `check` walk. When `true`, `rigor
+      # check` runs the {Inference::ParameterInferenceCollector} as a one-round pre-pass into the discovery
+      # seed, so an undeclared `def` / `initialize` / setter parameter is typed to the union of its resolved
+      # call-site argument types (precision-additive only — the in-body negative rules decline on the inferred
+      # lower bound, WD6b). `false` (the default, resolved off by every severity profile) keeps the table empty
+      # and the run byte-identical to today. Mutually exclusive with `--incremental` (WD6c).
+      "parameter_inference" => false,
       "cache" => {
         "path" => ".rigor/cache",
         # LRU eviction cap in bytes (ADR-54 WD3). The least-recently-used entries are removed at the end of a
@@ -63,7 +71,18 @@ module Rigor
         # would otherwise ever delete; a full active per-project set is ~2 MB, so the cap never touches live
         # entries. Set explicitly to `null` to disable eviction (pre-WD3 behaviour: the cache grows until
         # `--clear-cache`).
-        "max_bytes" => 268_435_456
+        "max_bytes" => 268_435_456,
+        # ADR-87 WD1 — file-freshness validation strategy. `"stat"` validates a recorded file
+        # dependency by stat-ing it first and re-hashing only when the `(size, mtime_ns, ctime_ns, inode)`
+        # tuple moved (or the racy window fires), so an unchanged monorepo hashes ~0 bytes on a warm run.
+        # `"digest"` restores the pre-ADR-87 behaviour of SHA-256'ing every recorded file on every run — the
+        # per-run escape hatch is the `RIGOR_STRICT_VALIDATION=1` env var, which wins over this setting.
+        # `"auto"` (default, #190) resolves per environment: `"digest"` when {CiDetector} recognises a CI
+        # provider — a fresh checkout regenerates every stat tuple, so the stat tier can never short-circuit
+        # there and stat-signature glob slots would recompute on every run — and `"stat"` everywhere else.
+        # A self-hosted runner with a persistent workspace opts back into the stat floor with an explicit
+        # `"stat"` (or `RIGOR_CI_DETECT=0`).
+        "validation" => "auto"
       },
       "plugins_io" => {
         "network" => "disabled",
@@ -143,9 +162,45 @@ module Rigor
     PATH_KEYS = %w[paths signature_paths pre_eval].freeze
     private_constant :PATH_KEYS
 
+    # Top-level keys this implementation DECLARES but never reads — see `docs/internal-spec/config.md`
+    # § "Reserved namespaces" and ADR-99.
+    #
+    # A sibling implementation (`rigor-rs`, which vendors our schema rather than keeping its own)
+    # groups keys for concepts we do not have under its own namespace, so one `.rigor.yml` feeds both.
+    # Such a key answers to the SCHEMA TIER ONLY: it is type-checked where it is written, and here it
+    # is never read, never validated, never coerced, and never an error however invalid its value.
+    #
+    # That is already the emergent behaviour — `#initialize` fetches each key it owns and never
+    # enumerates the rest — so this constant does not gate the runtime. It exists to make the
+    # reservation FINDABLE by the next person adding config validation (#166 is exactly that), and to
+    # give the schema-parity spec something to key on: a reserved namespace is by definition absent
+    # from DEFAULTS, so the DEFAULTS-driven schema gate can never see it.
+    RESERVED_NAMESPACES = %w[rigor_rs].freeze
+
+    # Every top-level key a conforming `.rigor.yml` may carry: the keys this implementation owns, plus
+    # `includes:`, plus the namespaces reserved for another implementation. Anything else is recorded in
+    # {#unknown_keys} and warned about by {ConfigAudit}, and is also the did-you-mean dictionary for a
+    # near-miss.
+    #
+    # `includes:` is a load-time directive — {load_with_includes} `delete`s it while merging, so it never
+    # reaches `#initialize` and could not be seen as unknown regardless. It is listed because a user
+    # legitimately writes it, so a typo like `include:` must be able to suggest it.
+    KNOWN_KEYS = (DEFAULTS.keys + %w[includes] + RESERVED_NAMESPACES).freeze
+
+    # Top-level keys the loaded config carried that this implementation does not own — neither a
+    # {DEFAULTS} key, nor `includes:`, nor a reserved namespace. Recorded rather than acted on: an
+    # unknown key stays as inert at run time as it has always been, and {ConfigAudit} turns the record
+    # into a warning. Empty for every conforming config.
+    #
+    # This exists because `#initialize` fetches each key it owns and never enumerates the rest, so by
+    # the time anything holds a Configuration the unknown keys are gone. The audit reads a
+    # Configuration, so without this the class of mistake it exists to catch — a value that silently
+    # resolves to nothing — was structurally invisible to it for whole keys.
+    attr_reader :unknown_keys
+
     attr_reader :target_ruby, :paths, :exclude_patterns, :plugins, :cache_path, :cache_max_bytes,
-                :disabled_rules,
-                :libraries, :signature_paths, :fold_platform_specific_paths,
+                :cache_validation, :disabled_rules,
+                :libraries, :signature_paths, :fold_platform_specific_paths, :parameter_inference,
                 :plugins_io_network, :plugins_io_allowed_paths,
                 :plugins_io_allowed_url_hosts,
                 :severity_profile, :severity_overrides,
@@ -168,10 +223,67 @@ module Rigor
     # [PHPStan](https://phpstan.org/config-reference#paths).
     def self.load(path = nil)
       resolved = path || discover
-      return new(DEFAULTS) if resolved.nil? || !File.exist?(resolved)
+      data =
+        if resolved.nil? || !File.exist?(resolved)
+          DEFAULTS
+        else
+          DEFAULTS.merge(load_with_includes(resolved))
+        end
+      new(autowire_default_plugins(data))
+    end
 
-      data = load_with_includes(resolved)
-      new(DEFAULTS.merge(data))
+    # ADR-93 WD2 — the one bundled plugin default-wired without a `plugins:` entry. `rigor-rbs-inline` is the
+    # gem; `rbs-inline` is its manifest id (the loader raises on a duplicate id, so both forms count as
+    # "already listed").
+    AUTOWIRED_RBS_INLINE_GEM = "rigor-rbs-inline"
+    AUTOWIRED_RBS_INLINE_ID = "rbs-inline"
+
+    # ADR-93 WD2 — default-wire the bundled `rigor-rbs-inline` plugin, in WD1's annotation-gated,
+    # magic-comment-free mode, when the upstream `rbs-inline` library is resolvable and the user has not
+    # already listed the plugin. Runs from {load} only — the real-project route — never from a bare
+    # {Configuration.new}, so the suite's unit constructions do not auto-wire. The gate is presence-based
+    # (ADR-72's shape): an annotation-free project pays only a comment scan and contributes nothing, so
+    # wiring it on cannot regress the run. This partially reverses the ADR-27/ADR-31 auto-load deferral for
+    # this one bundled plugin (the executed code is already vendored, not arbitrary third-party plugin code).
+    # Opt out with a `plugins:` entry disabling it (`enabled: false`), or per-file `# rbs_inline: disabled`.
+    def self.autowire_default_plugins(data)
+      entries = Array(data["plugins"])
+      return data if entries.any? { |entry| rbs_inline_plugin_entry?(entry) }
+      return data unless rbs_inline_library_resolvable?
+
+      merged = data.dup
+      merged["plugins"] = entries + [{
+        "gem" => AUTOWIRED_RBS_INLINE_GEM,
+        "id" => AUTOWIRED_RBS_INLINE_ID,
+        "config" => { "require_magic_comment" => false }
+      }]
+      merged
+    end
+
+    # True when a `plugins:` entry (String or Hash, string- or symbol-keyed) already references the
+    # `rigor-rbs-inline` plugin by gem name or by manifest id. Single-homed here so the CLI's
+    # `--treat-all-as-inline-rbs` injection and the WD2 auto-wire gate agree on what "already listed" means.
+    def self.rbs_inline_plugin_entry?(entry)
+      case entry
+      when String
+        entry == AUTOWIRED_RBS_INLINE_GEM
+      when Hash
+        string_keyed = entry.to_h { |k, v| [k.to_s, v] }
+        string_keyed["gem"] == AUTOWIRED_RBS_INLINE_GEM || string_keyed["id"] == AUTOWIRED_RBS_INLINE_ID
+      else
+        false
+      end
+    end
+
+    # A probe with no load side effect: it does not `require` the library, only asks whether RubyGems can
+    # resolve the name. `Gem::Specification.find_by_name` raises `Gem::MissingSpecError` (a `Gem::LoadError`)
+    # when the gem is absent — the standalone `gem install rigortype` case, WD3's residual. ADR-90's
+    # project-bundle fallback resolves the same name at the plugin's own `require` time.
+    def self.rbs_inline_library_resolvable?
+      Gem::Specification.find_by_name("rbs-inline")
+      true
+    rescue Gem::LoadError
+      false
     end
 
     # Returns the path to the config file Rigor would load under auto-discovery, or `nil` when neither
@@ -280,6 +392,10 @@ module Rigor
 
     # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
     def initialize(data = DEFAULTS)
+      # Record before the per-key fetches below discard the evidence. Top level only, deliberately —
+      # see {ConfigAudit.unknown_key_warnings} for why a nested check cannot key on DEFAULTS.
+      @unknown_keys = (data.keys.map(&:to_s) - KNOWN_KEYS).sort.freeze
+
       cache = DEFAULTS.fetch("cache").merge(data.fetch("cache", {}))
       plugins_io = DEFAULTS.fetch("plugins_io").merge(data.fetch("plugins_io", {}))
 
@@ -300,10 +416,14 @@ module Rigor
       @baseline_path = coerce_baseline_path(data.fetch("baseline", DEFAULTS.fetch("baseline")))
       @fold_platform_specific_paths = data.fetch(
         "fold_platform_specific_paths", DEFAULTS.fetch("fold_platform_specific_paths")
-      ) == true
+      )
+      # ADR-67 WD6a — resolve to a strict Boolean so a truthy non-`true` value (e.g. a stray String) does not
+      # silently enable the gate; only the literal `true` activates the check-walk collector pre-pass.
+      @parameter_inference = data.fetch("parameter_inference", DEFAULTS.fetch("parameter_inference")) == true
       @cache_path = cache.fetch("path").to_s
       raw_max = cache.fetch("max_bytes")
       @cache_max_bytes = raw_max.nil? ? nil : Integer(raw_max)
+      @cache_validation = coerce_cache_validation(cache.fetch("validation", "auto"))
       @plugins_io_network = coerce_network_policy(plugins_io.fetch("network"))
       @plugins_io_allowed_paths = Array(plugins_io.fetch("allowed_paths")).map(&:to_s).freeze
       @plugins_io_allowed_url_hosts = Array(plugins_io.fetch("allowed_url_hosts")).map(&:to_s).freeze
@@ -340,6 +460,20 @@ module Rigor
     end
     # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
 
+    # Resolves the `cache.validation` tri-state to the boolean the run installs via
+    # {Cache::FileDigest.with_run}'s `strict:`. Explicit `"digest"` / `"stat"` win outright; the `"auto"`
+    # default is strict exactly when {CiDetector} recognises a CI provider (#190) — deliberately NOT stored at
+    # construction so the resolution honours the environment of the run, not of `Configuration.load`, and the
+    # frozen carrier stays env-independent. `RIGOR_STRICT_VALIDATION=1` is enforced separately inside
+    # {Cache::FileDigest.strict_validation?} and wins over all three values.
+    def cache_validation_strict?(env = ENV)
+      case cache_validation
+      when "digest" then true
+      when "stat" then false
+      else !CiDetector.detect(env).nil?
+      end
+    end
+
     def to_h # rubocop:disable Metrics/MethodLength, Metrics/AbcSize
       {
         "target_ruby" => target_ruby,
@@ -351,9 +485,11 @@ module Rigor
         "signature_paths" => signature_paths,
         "pre_eval" => pre_eval,
         "fold_platform_specific_paths" => fold_platform_specific_paths,
+        "parameter_inference" => parameter_inference,
         "cache" => {
           "path" => cache_path,
-          "max_bytes" => cache_max_bytes
+          "max_bytes" => cache_max_bytes,
+          "validation" => cache_validation
         },
         "plugins_io" => {
           "network" => plugins_io_network.to_s,
@@ -483,6 +619,18 @@ module Rigor
       value.to_s
     end
 
+    # ADR-87 WD1 — `cache.validation` is `"auto"` (default), `"stat"`, or `"digest"`. An unrecognised value
+    # fails soft to the default rather than aborting a check over a typo — the strict `"digest"` behaviour is
+    # the safe fallback either way, and the always-available `RIGOR_STRICT_VALIDATION=1` env escape hatch does
+    # not depend on this value being valid.
+    VALID_CACHE_VALIDATIONS = %w[auto stat digest].freeze
+    private_constant :VALID_CACHE_VALIDATIONS
+
+    def coerce_cache_validation(value)
+      str = value.to_s
+      VALID_CACHE_VALIDATIONS.include?(str) ? str : "auto"
+    end
+
     def coerce_network_policy(value)
       sym = value.to_sym
       unless VALID_NETWORK_POLICIES.include?(sym)

data/lib/rigor/environment/default_libraries.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Rigor
+  class Environment
+    # Slice A stdlib expansion. Stdlib libraries that `Environment.for_project` loads on top of RBS core
+    # unless the caller passes an explicit `libraries:` array. Each entry MUST be a stdlib library name
+    # accepted by `RBS::EnvironmentLoader#has_library?`; unknown libraries MUST fail-soft
+    # (`RbsLoader#build_env` already filters through `has_library?`). The default set covers the common
+    # stdlib surface a Ruby program is likely to import (`pathname`, `optparse`, `json`, `yaml`, `fileutils`,
+    # `tempfile`, `uri`, `logger`, `date`) plus the analyzer-adjacent gems shipping their own RBS in this
+    # bundle (`prism`, `rbs`). On hosts where one of these libraries is not installed, the loader silently
+    # drops it.
+    #
+    # Callers MAY add to the default by passing `libraries: %w[csv ...]`; the explicit list is appended to
+    # `DEFAULT_LIBRARIES` and de-duplicated. Callers that need a strictly RBS-core view MUST construct an
+    # `RbsLoader` directly instead of going through `for_project`.
+    #
+    # ADR-87 WD4 — extracted to its own light file (no engine requires) so the boot-slimming hit probe can
+    # reconstruct `Environment.for_project`'s merged library list — which feeds the run cache KEY's
+    # `rbs.libraries` slot — WITHOUT building the RBS environment (or loading the inference engine).
+    DEFAULT_LIBRARIES = %w[
+      pathname optparse json yaml fileutils tempfile tmpdir
+      stringio forwardable digest securerandom
+      uri logger date
+      pp delegate observable abbrev find tsort singleton
+      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
+    ].freeze
+  end
+end

data/lib/rigor/environment/missing_gem_constant_index.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+require "prism"
+
+module Rigor
+  class Environment
+    # ADR-82 WD9 — maps a top-level constant name to the locked, RBS-less gem that declares it, so an
+    # unresolved constant read (`Faraday`, `Sidekiq`) can carry the `external_gem_without_rbs` provenance
+    # cause instead of the generic `unsupported_syntax`. For a gem with no RBS the constant read is where the
+    # class name is last visible — by dispatch time the receiver is already `Dynamic[top]` — so this index is
+    # what lets `coverage --protection` route those holes to `add_rbs` honestly.
+    #
+    # Ownership is established by READING, never by guessing: each gem's conventional entry file
+    # (`lib/<name>.rb`, with the dash → directory variant) is parsed with Prism and its top-level
+    # class / module / constant declarations recorded under their root name. No gem code runs — the same
+    # posture as ADR-72's "loads RBS data only" and the ADR-10 walker. A name-derivation heuristic
+    # (`faraday` → `Faraday` by camelizing) is deliberately NOT used: it breaks on irregular names
+    # (`activesupport` → `ActiveSupport`) and is exactly the guessing the ADR-82 honesty criterion forbids.
+    #
+    # Everything fails OPEN to "no owner": a gem that is not installed, an entry file that does not exist or
+    # does not parse, a root constant declared only in a deeper file. An unindexed constant keeps today's
+    # generic cause — the failure mode is a missing label, never a wrong one.
+    #
+    # The scan is bounded to entry files (one or two per gem) so building the index over a real app's
+    # hundreds of RBS-less gems stays sub-second; it is built lazily on the first unresolved constant, so a
+    # project whose constants all resolve never pays it.
+    #
+    # **Gem-directory resolution.** Rigor runs under its OWN bundle (`BUNDLE_GEMFILE=<rigor>/Gemfile`), so
+    # `Gem::Specification.find_by_name` sees rigor's gems, not the target project's — it would resolve only
+    # the handful of gems both bundles happen to share (i18n, rack) and miss every project-specific gem
+    # (the very ones a Rails app's holes root at). So the primary resolver is the **target's bundle install
+    # tree** (`<bundle>/ruby/*/gems/<name>-<version>/`, the same pure-filesystem layout
+    # {BundleSigDiscovery} walks — no `Bundler` API, no gem code). `Gem::Specification` remains a last-resort
+    # fallback for a project installed against system gems with no discoverable bundle; reading a gem's own
+    # entry file for its own top-level namespace constant is version-stable, so even a rigor-vs-target
+    # version skew on a shared gem yields the same constant name.
+    module MissingGemConstantIndex
+      module_function
+
+      # @param gems [Enumerable<Array(String, String)>] `[gem_name, version]` pairs (the `:missing` rows of
+      #   {RbsCoverageReport}).
+      # @param bundle_path [String, Pathname, nil] the target's resolved bundler install root, or nil.
+      # @param spec_resolver [#call] `(name, version) -> String?` fallback dir resolver. Injectable for
+      #   specs; the default is the RubyGems-metadata lookup (no code load).
+      # @return [Hash{String => String}] frozen `root constant name => gem name`. On a collision (two gems
+      #   declaring the same top-level constant) the first gem wins — the CAUSE recorded downstream
+      #   (external gem without RBS) is true under either owner.
+      def build(gems, bundle_path: nil, spec_resolver: method(:installed_gem_dir))
+        bundle_dirs = bundle_gem_dirs(bundle_path)
+        index = {}
+        gems.each do |gem_name, version|
+          dir = bundle_dirs["#{gem_name}-#{version}"] || spec_resolver.call(gem_name, version)
+          next unless dir
+
+          entry_files(dir, gem_name).each do |file|
+            top_level_root_constants(file).each { |name| index[name] ||= gem_name }
+          end
+        end
+        index.freeze
+      end
+
+      # `{"<name>-<version>" => gem_dir}` for the target's bundle, or `{}` when no bundle is resolvable. The
+      # glob mirrors {BundleSigDiscovery}: `<bundle>/ruby/X.Y.Z/gems/<name>-<version>/`. Keyed on the dir
+      # basename so a platform-tagged variant (`ffi-1.17.4-aarch64-linux-gnu`) simply doesn't match a
+      # `<name>-<version>` lookup — those gems ship native code, not the pure-Ruby constants this indexes.
+      def bundle_gem_dirs(bundle_path)
+        return {} if bundle_path.nil?
+
+        base = Pathname.new(bundle_path)
+        return {} unless base.directory?
+
+        Dir.glob(base.join("ruby", "*", "gems", "*")).each_with_object({}) do |dir, acc|
+          acc[File.basename(dir)] ||= dir
+        end
+      end
+
+      # RubyGems spec metadata lookup — the gem's on-disk source root, without loading any of its code.
+      # Exact-version first, any-version fallback. See the class note on why this is only a fallback.
+      def installed_gem_dir(name, version)
+        spec = begin
+          Gem::Specification.find_by_name(name, "= #{version}")
+        rescue Gem::LoadError
+          begin
+            Gem::Specification.find_by_name(name)
+          rescue Gem::LoadError
+            nil
+          end
+        end
+        spec&.full_gem_path
+      end
+
+      # The conventional require targets for a gem name: `lib/foo.rb`, and `lib/foo/bar.rb` for a dashed
+      # `foo-bar`. This is the require-name convention Bundler.require depends on — a filename convention,
+      # not a constant-name guess; the constants come from parsing whichever of these exists.
+      def entry_files(dir, gem_name)
+        candidates = ["lib/#{gem_name}.rb"]
+        candidates << "lib/#{gem_name.tr('-', '/')}.rb" if gem_name.include?("-")
+        candidates.filter_map do |relative|
+          path = File.join(dir, relative)
+          path if File.file?(path)
+        end
+      end
+
+      # Root names of the file's top-level declarations. Only direct children of the program are read — the
+      # root constant of a gem's namespace is declared at file top level by construction (`module Faraday`,
+      # `class Money::Error < …` roots at `Money`), so no recursion into bodies is needed.
+      def top_level_root_constants(path)
+        result = Prism.parse(File.read(path))
+        return [] unless result.errors.empty?
+
+        result.value.statements.body.filter_map do |node|
+          case node
+          when Prism::ClassNode, Prism::ModuleNode then root_segment(node.constant_path)
+          when Prism::ConstantWriteNode then node.name.to_s
+          end
+        end
+      rescue StandardError
+        []
+      end
+
+      def root_segment(node)
+        current = node
+        current = current.parent while current.is_a?(Prism::ConstantPathNode) && current.parent
+        current.respond_to?(:name) && current.name ? current.name.to_s : nil
+      end
+    end
+  end
+end