rigortype 0.2.7 → 0.2.9

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

data/lib/rigor/environment/rbs_collection_discovery.rb

@@ -6,74 +6,51 @@ module Rigor
   class Environment
     # `rbs collection install` awareness (O4 Layer 3 slice 2, implemented).
     #
-    # 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
+    # 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.
+    # 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.
+      # `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.
       #
-      # The `source.type` filter alone is NOT sufficient: gems
-      # that were extracted from Ruby's stdlib into standalone
-      # default gems (e.g. `cgi`, `logger`, `base64`, `csv`,
-      # `bigdecimal`) are published in `ruby/gem_rbs_collection`
-      # under a `git` source type, yet rigor ALSO loads them
-      # from its bundled stdlib via `DEFAULT_LIBRARIES`. Loading
-      # both copies triggers the very
-      # `RBS::DuplicatedDeclarationError` this module exists to
-      # avoid (observed on a Rails 8 app: `.gem_rbs_collection/
-      # cgi/0.5/` vs the bundled `stdlib/cgi`). The
-      # `skip_gem_names:` parameter lets the caller pass the set
-      # of library names rigor already loads so those gems are
-      # dropped regardless of `source.type`.
+      # The `source.type` filter alone is NOT sufficient: gems that were extracted from Ruby's stdlib into
+      # standalone default gems (e.g. `cgi`, `logger`, `base64`, `csv`, `bigdecimal`) are published in
+      # `ruby/gem_rbs_collection` under a `git` source type, yet rigor ALSO loads them from its bundled
+      # stdlib via `DEFAULT_LIBRARIES`. Loading both copies triggers the very
+      # `RBS::DuplicatedDeclarationError` this module exists to avoid (observed on a Rails 8 app:
+      # `.gem_rbs_collection/ cgi/0.5/` vs the bundled `stdlib/cgi`). The `skip_gem_names:` parameter lets
+      # the caller pass the set of library names rigor already loads so those gems are dropped regardless of
+      # `source.type`.
       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
+      # @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`.
-      # @param skip_gem_names [Array<String>, Set<String>] gem
-      #   names rigor already loads from its bundled stdlib (the
-      #   merged `DEFAULT_LIBRARIES + libraries:` set). Entries
-      #   whose `name` is in this set are dropped regardless of
-      #   `source.type` to avoid `RBS::DuplicatedDeclarationError`
-      #   on stdlib-extracted default gems. Defaults to empty.
-      # @return [Array<Pathname>] every
-      #   `<collection_path>/<gem-name>/<gem-version>/`
-      #   directory listed in the lockfile whose entry has a
-      #   non-skipped source type, whose `name` is not in
-      #   `skip_gem_names:`, 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.
+      # @param skip_gem_names [Array<String>, Set<String>] gem names rigor already loads from its bundled
+      #   stdlib (the merged `DEFAULT_LIBRARIES + libraries:` set). Entries whose `name` is in this set are
+      #   dropped regardless of `source.type` to avoid `RBS::DuplicatedDeclarationError` on
+      #   stdlib-extracted default gems. Defaults to empty.
+      # @return [Array<Pathname>] every `<collection_path>/<gem-name>/<gem-version>/` directory listed in the
+      #   lockfile whose entry has a non-skipped source type, whose `name` is not in `skip_gem_names:`, 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, skip_gem_names: [])
         resolved = resolve_lockfile_path(
           lockfile_path: lockfile_path,
@@ -91,9 +68,8 @@ module Rigor
         gem_paths_from(collection_root, data, skip_gem_names.to_set)
       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.
+      # 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))
@@ -119,8 +95,8 @@ module Rigor
       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).
+        # `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

data/lib/rigor/environment/rbs_coverage_report.rb

@@ -2,29 +2,21 @@
 
 module Rigor
   class Environment
-    # Open item O4 Layer 3 slice 3 — graceful-degradation
-    # coverage report.
+    # Open item O4 Layer 3 slice 3 — graceful-degradation coverage report.
     #
-    # When the user has a `Gemfile.lock` (via slice 1) and rigor
-    # has resolved its target-project RBS sources (DEFAULT_LIBRARIES,
-    # `data/vendored_gem_sigs/`, slice-1 bundle-shipped `sig/`,
-    # slice-2 `rbs_collection.lock.yaml` paths), this module
-    # classifies each locked gem by RBS provenance and surfaces
-    # the "no RBS available" set so the run-start diagnostic in
-    # {Rigor::Analysis::Runner} can suggest `rbs collection
-    # install` or `dependencies.source_inference:` for the
-    # uncovered gems.
+    # When the user has a `Gemfile.lock` (via slice 1) and rigor has resolved its target-project RBS sources
+    # (DEFAULT_LIBRARIES, `data/vendored_gem_sigs/`, slice-1 bundle-shipped `sig/`, slice-2
+    # `rbs_collection.lock.yaml` paths), this module classifies each locked gem by RBS provenance and
+    # surfaces the "no RBS available" set so the run-start diagnostic in {Rigor::Analysis::Runner} can
+    # suggest `rbs collection install` or `dependencies.source_inference:` for the uncovered gems.
     #
-    # The classification is a pure function over the inputs
-    # (`locked_gems`, two arrays of resolved sig paths). It does
-    # NOT touch the filesystem on its own — the caller passes in
-    # what discovery returned.
+    # The classification is a pure function over the inputs (`locked_gems`, two arrays of resolved sig
+    # paths). It does NOT touch the filesystem on its own — the caller passes in what discovery returned.
     module RbsCoverageReport
       # Frozen result row.
       #
-      # `source` is a Symbol naming where RBS for this gem
-      # resolves; `:missing` means none of the four resolution
-      # paths covered it.
+      # `source` is a Symbol naming where RBS for this gem resolves; `:missing` means none of the four
+      # resolution paths covered it.
       Coverage = Data.define(:gem_name, :version, :source) do
         def initialize(gem_name:, version:, source:)
           super(
@@ -35,32 +27,24 @@ module Rigor
         end
       end
 
-      # Names of gems whose RBS ships under
-      # `data/vendored_gem_sigs/`. Kept in sync with the
-      # vendored-stubs directory listing; when a new gem is
-      # vendored, add its name here too. (The set is small
-      # enough that hard-coding is acceptable; a directory walk
-      # at every call would add stat-cost to no benefit.)
+      # Names of gems whose RBS ships under `data/vendored_gem_sigs/`. Kept in sync with the vendored-stubs
+      # directory listing; when a new gem is vendored, add its name here too. (The set is small enough that
+      # hard-coding is acceptable; a directory walk at every call would add stat-cost to no benefit.)
       VENDORED_GEM_NAMES = Set[
         "ast", "bcrypt", "bundler", "cgi", "did_you_mean",
         "idn-ruby", "mysql2", "nokogiri", "pg", "prism", "redis", "rubygems"
       ].freeze
 
-      # @param locked_gems [Hash{String => LockfileResolver::LockedGem}]
-      #   The lockfile-resolved gem set. Empty hash → no
-      #   coverage analysis to do.
-      # @param default_libraries [Array<String>] gem names rigor
-      #   auto-loads through `RBS::EnvironmentLoader#add(library:)`.
-      #   Pass `Rigor::Environment::DEFAULT_LIBRARIES` from callers
+      # @param locked_gems [Hash{String => LockfileResolver::LockedGem}] The lockfile-resolved gem set. Empty
+      #   hash → no coverage analysis to do.
+      # @param default_libraries [Array<String>] gem names rigor auto-loads through
+      #   `RBS::EnvironmentLoader#add(library:)`. Pass `Rigor::Environment::DEFAULT_LIBRARIES` from callers
       #   running in a project context.
-      # @param bundle_sig_paths [Array<Pathname, String>] the
-      #   discovered `<bundle>/.../gems/<name>-<ver>/sig` paths
-      #   from {BundleSigDiscovery.discover}.
-      # @param rbs_collection_paths [Array<Pathname, String>] the
-      #   discovered `<collection>/<name>/<version>/` paths from
-      #   {RbsCollectionDiscovery.discover}.
-      # @return [Array<Coverage>] one row per locked gem; sorted
-      #   by gem name for deterministic output.
+      # @param bundle_sig_paths [Array<Pathname, String>] the discovered `<bundle>/.../gems/<name>-<ver>/sig`
+      #   paths from {BundleSigDiscovery.discover}.
+      # @param rbs_collection_paths [Array<Pathname, String>] the discovered `<collection>/<name>/<version>/`
+      #   paths from {RbsCollectionDiscovery.discover}.
+      # @return [Array<Coverage>] one row per locked gem; sorted by gem name for deterministic output.
       def self.classify(locked_gems:, default_libraries:,
                         bundle_sig_paths:, rbs_collection_paths:)
         default_set = default_libraries.to_set
@@ -84,8 +68,7 @@ module Rigor
         end.sort_by(&:gem_name)
       end
 
-      # Convenience accessor for the run-start diagnostic.
-      # Filters {classify} down to `:missing` rows.
+      # Convenience accessor for the run-start diagnostic. Filters {classify} down to `:missing` rows.
       def self.missing(coverage_rows)
         coverage_rows.select { |row| row.source == :missing }
       end
@@ -99,8 +82,7 @@ module Rigor
       private_class_method :extract_gem_names_from_bundle_paths
 
       def self.extract_gem_names_from_collection_paths(paths)
-        # `RbsCollectionDiscovery.discover` returns
-        # `<collection_root>/<name>/<version>/` so the parent
+        # `RbsCollectionDiscovery.discover` returns `<collection_root>/<name>/<version>/` so the parent
         # basename is the gem name.
         paths.each_with_object(Set.new) do |path, set|
           pathname = path.is_a?(Pathname) ? path : Pathname.new(path)