rigortype 0.2.7 → 0.2.8

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)