rigortype 0.1.2 → 0.1.4

data/lib/rigor/analysis/dependency_source_inference/index.rb

@@ -0,0 +1,139 @@
+# frozen_string_literal: true
+
+require_relative "../../cache/descriptor"
+
+module Rigor
+  module Analysis
+    module DependencySourceInference
+      # Per-run collection of gem-source-inference state. Holds
+      # the resolved gems the walker MAY visit (slice 2b) plus
+      # the unresolvable entries the runner SHOULD surface as
+      # `dynamic.dependency-source.gem-not-found` diagnostics.
+      #
+      # Slice 2a lands the data structure only; the dispatcher
+      # tier consults {#contribution_for} but the lookup always
+      # answers `nil` until slice 2b populates the method table
+      # by walking the resolved gems' `roots:`.
+      class Index
+        attr_reader :resolved_gems, :unresolvable, :method_catalog, :budget_exceeded,
+                    :class_to_gem, :budget_overrun_strategy, :gem_modes
+
+        # @param method_catalog [Hash{[String, Symbol] => Symbol}]
+        #   the flat `(class_name, method_name) → :instance | :singleton`
+        #   table produced by {Walker.walk}, aggregated across
+        #   every resolved gem in the run. The Index itself stays
+        #   gem-agnostic — the per-gem attribution that slice 3's
+        #   cache descriptor needs lives on `Resolved`, not here.
+        # @param budget_exceeded [Array<String>] gem names whose
+        #   {Walker} run hit the per-gem catalog cap (slice 4).
+        #   The Runner consumes this list to emit one
+        #   `dynamic.dependency-source.budget-exceeded` warning
+        #   per gem.
+        # @param class_to_gem [Hash<String, String>] reverse
+        #   lookup `class_name → gem_name` (slice 5b). Built
+        #   first-write-wins: when two opt-in gems re-open the
+        #   same class, the first gem owns it. The dispatcher
+        #   consults this map under the `:dependency_silence`
+        #   budget overrun strategy so call sites on a
+        #   budget-exceeded gem's classes degrade to
+        #   `Dynamic[top]` instead of falling through to the
+        #   user-class fallback.
+        # @param gem_modes [Hash<String, Symbol>] per-gem mode
+        #   table (`gem_name → :disabled | :when_missing |
+        #   :full`). ADR-10 slice 5c consults this through
+        #   {#mode_for} to identify call sites where gem-source
+        #   and RBS both contribute under `mode: :full`. The map
+        #   is keyed on `gem_name` (not class) because re-opened
+        #   classes belong to the first gem they appeared in
+        #   per `class_to_gem`; `mode_for(class_name)` chains
+        #   the two lookups.
+        def initialize(
+          resolved_gems: [], unresolvable: [], method_catalog: {},
+          budget_exceeded: [], class_to_gem: {},
+          budget_overrun_strategy: :walker_cap, gem_modes: {}
+        )
+          @resolved_gems = resolved_gems.freeze
+          @unresolvable = unresolvable.freeze
+          @method_catalog = method_catalog.freeze
+          @budget_exceeded = budget_exceeded.freeze
+          @class_to_gem = class_to_gem.freeze
+          @budget_overrun_strategy = budget_overrun_strategy
+          @gem_modes = gem_modes.freeze
+          freeze
+        end
+
+        # @return [String, nil] the gem that owns `class_name`
+        #   (first-write-wins); `nil` when the class isn't in
+        #   any opt-in gem's catalog.
+        def gem_for(class_name)
+          @class_to_gem[class_name]
+        end
+
+        # ADR-10 slice 5c — per-class mode lookup. Chains
+        # `class_to_gem` + `gem_modes`; returns `nil` when the
+        # class isn't owned by any opt-in gem in this run.
+        def mode_for(class_name)
+          gem_name = @class_to_gem[class_name]
+          return nil if gem_name.nil?
+
+          @gem_modes[gem_name]
+        end
+
+        # ADR-10 slice 5c — true when the receiver class belongs
+        # to a gem the user opted into `mode: :full` for. The
+        # dispatcher consults this AFTER an authoritative-source
+        # (RBS / plugin) dispatch resolves so it can record the
+        # boundary-crossing for audit.
+        def full_mode?(class_name)
+          mode_for(class_name) == :full
+        end
+
+        # Looks up the recorded method kind for a
+        # `(class_name, method_name)` pair. Returns `:instance`
+        # / `:singleton` when the walker observed a definition
+        # under one of the resolved gems' `roots:`, or `nil`
+        # otherwise. Slice 2b-ii enriches this with the inferred
+        # return type so the dispatcher tier can build a
+        # `Type::Dynamic` directly from the lookup result.
+        def contribution_for(class_name:, method_name:)
+          @method_catalog[[class_name, method_name]]
+        end
+
+        def empty?
+          @resolved_gems.empty?
+        end
+
+        # Builds a frozen `Cache::Descriptor` carrying one
+        # `DependencyEntry` row per resolved gem in this run.
+        # Cache producers that observe ADR-10 inference outputs
+        # compose this descriptor with their own (RBS, plugin,
+        # file-digest) descriptors so a `bundle update` on a
+        # listed gem invalidates exactly that gem's slice while
+        # leaving the rest of the cache hot.
+        #
+        # Unresolvable entries contribute nothing — there is no
+        # version to key on, and the runner already surfaces them
+        # as `dynamic.dependency-source.gem-not-found`
+        # diagnostics. Resolved-but-disabled entries are also
+        # absent: the {Builder} skips them before resolution, so
+        # they never reach the index.
+        def cache_descriptor
+          dependencies = @resolved_gems.map do |resolved|
+            Cache::Descriptor::DependencyEntry.new(
+              gem_name: resolved.gem_name,
+              gem_version: resolved.version,
+              mode: resolved.mode
+            )
+          end
+          Cache::Descriptor.new(dependencies: dependencies)
+        end
+      end
+
+      # Frozen empty index — the runner uses this when
+      # `Configuration#dependencies.source_inference` is empty
+      # so the dispatcher tier holds a stable, non-nil
+      # reference even on default configurations.
+      Index::EMPTY = Index.new.freeze
+    end
+  end
+end

data/lib/rigor/analysis/dependency_source_inference/walker.rb

@@ -0,0 +1,200 @@
+# frozen_string_literal: true
+
+require "prism"
+
+module Rigor
+  module Analysis
+    module DependencySourceInference
+      # Walks a resolved gem's `roots:` and collects the
+      # `(class_name, method_name) → :instance | :singleton`
+      # method catalog. The walker is the source of facts the
+      # dispatcher tier (slice 2b-ii) consults to recognise a
+      # method as defined by an opt-in gem and contribute a
+      # `Type::Dynamic` return at the call site.
+      #
+      # Slice 2b-i intentionally collects only the catalog, not
+      # the inferred return type. The dispatcher tier returns
+      # `Dynamic[top]` on a hit until slice 2b-ii wires return-
+      # type inference; the visible payoff today is removing the
+      # `call.undefined-method` diagnostic for opt-in gem methods
+      # at receivers Rigor knows by `Nominal[T]` (typically
+      # because the user authored an RBS skeleton).
+      #
+      # Hard exclusions are NOT user-configurable, per ADR-10
+      # § "Hard exclusions": top-level `spec/`, `test/`, `bin/`,
+      # plus any non-`.rb` source. C extensions fall out
+      # automatically because the walker only loads `.rb` files.
+      module Walker
+        # Top-level directories that MUST NOT participate in
+        # gem-source inference even when the user lists them
+        # under `roots:`. The check is case-insensitive against
+        # the first segment of `roots:`; nested `spec/` /
+        # `test/` directories deeper inside `lib/` are NOT
+        # filtered (a few gems legitimately ship `lib/.../spec/`).
+        HARD_EXCLUDED_ROOTS = %w[spec test bin].freeze
+
+        # Walker outcome wrapping the harvested method catalog
+        # plus a budget-exceeded flag. ADR-10 slice 4 introduces
+        # the cap; the Walker stops appending to the accumulator
+        # once `catalog.size` reaches `budget`, and `truncated?`
+        # reports whether the cap was reached. The Index records
+        # this per-gem so the Runner can surface a single
+        # `dynamic.dependency-source.budget-exceeded` warning
+        # naming the affected gem(s).
+        class Outcome < Data.define(:catalog, :truncated)
+          def truncated? = truncated
+        end
+
+        # Sentinel for "no cap" — used by callers that don't
+        # care about the budget (specs, tooling). Production
+        # code MUST pass an integer.
+        UNBOUNDED = Float::INFINITY
+
+        module_function
+
+        # @param gem_dir [String, Pathname] absolute path to the
+        #   gem's installation directory.
+        # @param roots [Array<String>] subdirectory names within
+        #   the gem to walk (defaults to `["lib"]` per
+        #   `Configuration::Dependencies::Entry`).
+        # @param budget [Integer, Float] per-gem catalog cap
+        #   (method-definition count). When unset, defaults to
+        #   `UNBOUNDED` for backwards-compatible test paths.
+        # @return [Outcome] frozen wrapper carrying the catalog
+        #   (`Hash{[class_name, method_name] => :instance |
+        #   :singleton}`) and a `truncated?` flag set when the
+        #   walker stopped harvesting because the budget was
+        #   reached. Methods of identical name on the same class
+        #   with different kinds (rare; private API mostly)
+        #   carry the kind that wins the per-class first walk.
+        def walk(gem_dir:, roots:, budget: UNBOUNDED)
+          accumulator = {}
+          truncated = false
+          accepted_roots(roots).each do |root|
+            break if truncated
+
+            truncated = walk_root(File.join(gem_dir.to_s, root), accumulator, budget)
+          end
+          Outcome.new(catalog: accumulator.freeze, truncated: truncated)
+        end
+
+        # Drops hard-excluded entries before any filesystem
+        # walk happens. Reasoning: we never want a gem's
+        # `spec/` to participate even if the user requested
+        # it — the noise from RSpec-style globals plus the
+        # cost of walking test fixtures isn't worth the
+        # marginal coverage.
+        def accepted_roots(roots)
+          roots.reject { |root| HARD_EXCLUDED_ROOTS.include?(root.downcase) }
+        end
+
+        # Returns true when the budget tripped during this
+        # root's walk so the caller can stop iterating
+        # subsequent roots.
+        def walk_root(root_dir, accumulator, budget) # rubocop:disable Naming/PredicateMethod
+          return false unless File.directory?(root_dir)
+
+          Dir.glob(File.join(root_dir, "**", "*.rb")).each do |path|
+            harvest_file(path, accumulator, budget)
+            return true if accumulator.size >= budget
+          end
+          false
+        end
+
+        def harvest_file(path, accumulator, budget)
+          parse_result = Prism.parse_file(path)
+          return unless parse_result.errors.empty?
+
+          walk_node(parse_result.value, [], false, accumulator, budget)
+        rescue StandardError
+          # Gem source we can't parse / read silently degrades
+          # to "no contribution from this file". The user-facing
+          # diagnostic stream is reserved for the project source;
+          # opt-in gem source MUST NOT pollute it with parse
+          # errors the user cannot fix.
+          nil
+        end
+
+        # Walks a Prism subtree, accumulating method definitions
+        # under their qualified class name. Mirrors the shape of
+        # `Inference::ScopeIndexer#walk_methods` but stays
+        # decoupled from `Scope` because gem-source inference
+        # runs without a scope context.
+        def walk_node(node, qualified_prefix, in_singleton_class, accumulator, budget)
+          return unless node.is_a?(Prism::Node)
+          return if accumulator.size >= budget
+
+          case node
+          when Prism::ClassNode, Prism::ModuleNode
+            descend_class_or_module(node, qualified_prefix, in_singleton_class, accumulator, budget)
+          when Prism::SingletonClassNode
+            descend_singleton_class(node, qualified_prefix, accumulator, budget)
+          when Prism::DefNode
+            record_def_node(node, qualified_prefix, in_singleton_class, accumulator, budget)
+          else
+            walk_children(node, qualified_prefix, in_singleton_class, accumulator, budget)
+          end
+        end
+
+        def walk_children(node, qualified_prefix, in_singleton_class, accumulator, budget)
+          node.compact_child_nodes.each do |child|
+            break if accumulator.size >= budget
+
+            walk_node(child, qualified_prefix, in_singleton_class, accumulator, budget)
+          end
+        end
+
+        # `class Foo` / `module Bar`. The dynamic-prefix shape
+        # (`module ::Foo`-rooted variants whose left side is a
+        # runtime expression) is treated as opaque — we walk the
+        # children under the same prefix so any inner class
+        # definitions are still recorded under their own name.
+        def descend_class_or_module(node, qualified_prefix, in_singleton_class, accumulator, budget)
+          name = qualified_name_for(node.constant_path)
+          if name && node.body
+            walk_node(node.body, qualified_prefix + [name], in_singleton_class, accumulator, budget)
+          else
+            walk_children(node, qualified_prefix, in_singleton_class, accumulator, budget)
+          end
+        end
+
+        # `class << self` only — `class << expr` for any other
+        # `expr` is treated as opaque so we don't accidentally
+        # record per-instance singleton methods under the
+        # surrounding class.
+        def descend_singleton_class(node, qualified_prefix, accumulator, budget)
+          if node.expression.is_a?(Prism::SelfNode) && node.body
+            walk_node(node.body, qualified_prefix, true, accumulator, budget)
+          else
+            walk_children(node, qualified_prefix, false, accumulator, budget)
+          end
+        end
+
+        def record_def_node(node, qualified_prefix, in_singleton_class, accumulator, _budget)
+          return if qualified_prefix.empty?
+
+          class_name = qualified_prefix.join("::")
+          kind = node.receiver.is_a?(Prism::SelfNode) || in_singleton_class ? :singleton : :instance
+          accumulator[[class_name, node.name]] ||= kind
+        end
+
+        # Resolves a `Prism::ConstantPathNode` /
+        # `Prism::ConstantReadNode` chain to its dot-separated
+        # name (e.g. `"Foo::Bar"`). Returns nil for the rare
+        # dynamic-prefix shape (`module ::Foo`-rooted variants
+        # whose left side is a runtime expression) so the
+        # walker treats those as opaque rather than guessing.
+        def qualified_name_for(node)
+          case node
+          when Prism::ConstantReadNode then node.name.to_s
+          when Prism::ConstantPathNode
+            parent = node.parent.nil? ? nil : qualified_name_for(node.parent)
+            return nil if !node.parent.nil? && parent.nil?
+
+            parent.nil? ? node.name.to_s : "#{parent}::#{node.name}"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rigor/analysis/dependency_source_inference.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require_relative "dependency_source_inference/boundary_cross_reporter"
+require_relative "dependency_source_inference/gem_resolver"
+require_relative "dependency_source_inference/index"
+require_relative "dependency_source_inference/walker"
+require_relative "dependency_source_inference/builder"
+
+module Rigor
+  module Analysis
+    # Implementation of [ADR-10 — Opt-in dependency-source
+    # inference](../../../docs/adr/10-dependency-source-inference.md).
+    #
+    # The namespace coordinates three components:
+    #
+    # - {GemResolver} maps a
+    #   `Configuration::Dependencies::Entry` to either a frozen
+    #   `Resolved(gem_name, version, gem_dir, mode, roots)` or an
+    #   `Unresolvable(gem_name, reason)` value.
+    # - {Builder.build} folds a `Configuration::Dependencies`
+    #   into a frozen {Index} carrying the partitioned outcomes.
+    # - {Index} holds the per-run state the dispatcher tier
+    #   consults via `#contribution_for`. Slice 2a ships the
+    #   stub returning `nil`; slice 2b populates the method
+    #   table by walking each resolved gem's `roots:`.
+    #
+    # Per the ADR's "Implementation slicing" section, slice 2 is
+    # split internally:
+    #
+    # - Slice 2a (this commit): gem resolution, index plumbing,
+    #   `Analysis::Runner` wiring, `dynamic.dependency-source.gem-not-found`
+    #   diagnostic for unresolvable entries.
+    # - Slice 2b (next commit): walker, dispatcher tier
+    #   integration, `Type::Dynamic`-wrapped returns.
+    module DependencySourceInference
+    end
+  end
+end

data/lib/rigor/analysis/diagnostic.rb

@@ -24,10 +24,8 @@ module Rigor
       # ADR-2 § "Plugin Diagnostic Provenance") let consumers
       # distinguish where a diagnostic originated without committing
       # to the plugin API itself.
-      # rubocop:disable Metrics/ParameterLists
       def initialize(path:, line:, column:, message:, severity: :error, rule: nil,
                      source_family: DEFAULT_SOURCE_FAMILY)
-        # rubocop:enable Metrics/ParameterLists
         @path = path
         @line = line
         @column = column

data/lib/rigor/analysis/fact_store.rb

@@ -18,7 +18,7 @@ module Rigor
         relational
       ].freeze
 
-      Target = Data.define(:kind, :name) do
+      class Target < Data.define(:kind, :name)
         def self.local(name)
           new(kind: :local, name: name.to_sym)
         end
@@ -28,7 +28,7 @@ module Rigor
         end
       end
 
-      Fact = Data.define(:bucket, :target, :predicate, :payload, :polarity, :stability) do
+      class Fact < Data.define(:bucket, :target, :predicate, :payload, :polarity, :stability)
         def initialize(bucket:, target:, predicate:, payload: nil, polarity: :positive, stability: :local_binding)
           bucket = bucket.to_sym
           raise ArgumentError, "unknown fact bucket #{bucket.inspect}" unless BUCKETS.include?(bucket)
@@ -125,8 +125,16 @@ module Rigor
         unique.freeze
       end
 
+      # `fact.target` is `Target | Array[Target]` per the carrier
+      # contract. Branching with an early return on the `Array`
+      # arm lets type narrowing collapse the post-return value to
+      # the bare `Target` case, so the wrapped tuple is `[Target]`
+      # and the union of return paths is exactly `Array[Target]`.
       def fact_targets(fact)
-        Array(fact.target)
+        target = fact.target
+        return target if target.is_a?(Array)
+
+        [target]
       end
     end
   end

data/lib/rigor/analysis/rule_catalog.rb

@@ -31,8 +31,8 @@ module Rigor
     #   from `Configuration::SeverityProfile::PROFILES`.
     # - `since` — first version the rule shipped in.
     module RuleCatalog # rubocop:disable Metrics/ModuleLength
-      Entry = Data.define(:id, :summary, :fires_when, :does_not_fire_when,
-                          :suppression, :severity_authored, :severity_by_profile, :since) do
+      class Entry < Data.define(:id, :summary, :fires_when, :does_not_fire_when,
+                                :suppression, :severity_authored, :severity_by_profile, :since)
         def aliases
           CheckRules::LEGACY_RULE_ALIASES.select { |_legacy, canonical| canonical == id }.keys
         end