rigortype 0.1.1 → 0.1.3

data/lib/rigor/analysis/check_rules.rb

@@ -6,6 +6,9 @@ require_relative "../reflection"
 require_relative "../source/node_walker"
 require_relative "../type"
 require_relative "diagnostic"
+require_relative "check_rules/always_truthy_condition_collector"
+require_relative "check_rules/dead_assignment_collector"
+require_relative "check_rules/ivar_write_collector"
 
 module Rigor
   module Analysis
@@ -60,7 +63,12 @@ module Rigor
       RULE_DUMP_TYPE = "dump.type"
       RULE_ASSERT_TYPE = "assert.type-mismatch"
       RULE_ALWAYS_RAISES = "flow.always-raises"
+      RULE_UNREACHABLE_BRANCH = "flow.unreachable-branch"
       RULE_RETURN_TYPE = "def.return-type-mismatch"
+      RULE_VISIBILITY_MISMATCH = "def.method-visibility-mismatch"
+      RULE_IVAR_WRITE_MISMATCH = "def.ivar-write-mismatch"
+      RULE_DEAD_ASSIGNMENT = "flow.dead-assignment"
+      RULE_ALWAYS_TRUTHY_CONDITION = "flow.always-truthy-condition"
 
       ALL_RULES = [
         RULE_UNDEFINED_METHOD,
@@ -70,7 +78,12 @@ module Rigor
         RULE_DUMP_TYPE,
         RULE_ASSERT_TYPE,
         RULE_ALWAYS_RAISES,
-        RULE_RETURN_TYPE
+        RULE_UNREACHABLE_BRANCH,
+        RULE_DEAD_ASSIGNMENT,
+        RULE_ALWAYS_TRUTHY_CONDITION,
+        RULE_RETURN_TYPE,
+        RULE_VISIBILITY_MISMATCH,
+        RULE_IVAR_WRITE_MISMATCH
       ].freeze
 
       # Backward-compat alias table (ADR-8 § "Backward
@@ -88,7 +101,12 @@ module Rigor
         "possible-nil-receiver" => RULE_NIL_RECEIVER,
         "dump-type" => RULE_DUMP_TYPE,
         "assert-type" => RULE_ASSERT_TYPE,
-        "always-raises" => RULE_ALWAYS_RAISES
+        "always-raises" => RULE_ALWAYS_RAISES,
+        "unreachable-branch" => RULE_UNREACHABLE_BRANCH,
+        "method-visibility-mismatch" => RULE_VISIBILITY_MISMATCH,
+        "ivar-write-mismatch" => RULE_IVAR_WRITE_MISMATCH,
+        "dead-assignment" => RULE_DEAD_ASSIGNMENT,
+        "always-truthy-condition" => RULE_ALWAYS_TRUTHY_CONDITION
       }.freeze
 
       # Family wildcard — a `<family>` token in a suppression
@@ -124,13 +142,20 @@ module Rigor
       def diagnose(path:, root:, scope_index:, comments: [], disabled_rules: [])
         diagnostics = []
         Source::NodeWalker.each(root) do |node|
-          if node.is_a?(Prism::CallNode)
+          case node
+          when Prism::CallNode
             diagnostics.concat(call_node_diagnostics(path, node, scope_index))
-          elsif node.is_a?(Prism::DefNode)
+          when Prism::DefNode
             return_diagnostic = return_type_mismatch_diagnostic(path, node, scope_index)
             diagnostics << return_diagnostic if return_diagnostic
+          when Prism::IfNode, Prism::UnlessNode
+            unreachable = unreachable_branch_diagnostic(path, node, scope_index)
+            diagnostics << unreachable if unreachable
           end
         end
+        diagnostics.concat(always_truthy_condition_diagnostics(path, root, scope_index))
+        diagnostics.concat(ivar_write_mismatch_diagnostics(path, root, scope_index))
+        diagnostics.concat(dead_assignment_diagnostics(path, root, scope_index))
         filter_suppressed(diagnostics, comments: comments, disabled_rules: disabled_rules)
       end
 
@@ -142,17 +167,92 @@ module Rigor
           nil_receiver_diagnostic(path, node, scope_index),
           dump_type_diagnostic(path, node, scope_index),
           assert_type_diagnostic(path, node, scope_index),
-          always_raises_diagnostic(path, node, scope_index)
+          always_raises_diagnostic(path, node, scope_index),
+          visibility_mismatch_diagnostic(path, node, scope_index)
         ].compact
       end
 
-      # v0.0.2 #6 — diagnostic suppression. Two kinds of
+      # v0.1.2 — `def.ivar-write-mismatch`. Walks every
+      # ClassNode / ModuleNode body, gathers per-class ivar
+      # writes with their rvalue types, and emits a diagnostic
+      # when a later write's concrete class disagrees with the
+      # first write's. The first write per (class, ivar) is
+      # treated as the "declared" type; subsequent writes that
+      # land on a different concrete class trigger.
+      #
+      # Conservative envelope:
+      # - Only fires when both the first and the offending
+      #   write resolve to a `concrete_class_name` (Nominal /
+      #   Singleton / Constant / Tuple → "Array" / HashShape →
+      #   "Hash"). Unions / Dynamic / IntegerRange / shape-
+      #   varied carriers fall through.
+      # - `NilClass` is an intentional widening idiom (`@x =
+      #   "value"` then later `@x = nil` to "clear") — skipped.
+      # - Singleton-method (`def self.foo`) bodies are skipped.
+      #   Class-level ivars (`@x = 1` outside any def, in the
+      #   class body) are also skipped — they're a separate
+      #   surface (`Module#@var`) the engine doesn't yet model.
+      def ivar_write_mismatch_diagnostics(path, root, scope_index)
+        IvarWriteCollector.new(scope_index).collect(root).flat_map do |class_name, writes_by_ivar|
+          writes_by_ivar.flat_map do |ivar_name, writes|
+            ivar_mismatch_diagnostics_for(path, class_name, ivar_name, writes)
+          end
+        end
+      end
+
+      # v0.1.2 — `flow.dead-assignment`. Walks every `DefNode`
+      # body and emits a diagnostic for each plain
+      # `LocalVariableWriteNode` whose target name is never
+      # read in the same body. The
+      # `Analysis::CheckRules::DeadAssignmentCollector` describes
+      # the conservative envelope.
+      def dead_assignment_diagnostics(path, root, scope_index)
+        DeadAssignmentCollector.new(scope_index).collect(root).map do |result|
+          build_dead_assignment_diagnostic(path, result[:write_node], result[:def_node])
+        end
+      end
+
+      # v0.1.2 — `flow.always-truthy-condition`. Fires on
+      # `if` / `unless` / ternary predicates whose inferred
+      # type is a `Type::Constant` AND that don't fall in
+      # the literal-only / inside-loop-or-block / defensive-
+      # predicate skip envelope (see
+      # `Analysis::CheckRules::AlwaysTruthyConditionCollector`
+      # for the full triage rationale).
+      def always_truthy_condition_diagnostics(path, root, scope_index)
+        AlwaysTruthyConditionCollector.new(scope_index).collect(root).map do |result|
+          build_always_truthy_condition_diagnostic(path, result.node, result.polarity)
+        end
+      end
+
+      def ivar_mismatch_diagnostics_for(path, class_name, ivar_name, writes)
+        return [] if writes.size < 2
+
+        first_class = ivar_class_for(writes.first[:type])
+        return [] if first_class.nil?
+
+        writes[1..].filter_map do |write|
+          other_class = ivar_class_for(write[:type])
+          next nil if other_class.nil? || other_class == "NilClass" || other_class == first_class
+
+          build_ivar_write_mismatch_diagnostic(path, write[:node], class_name, ivar_name, first_class, other_class)
+        end
+      end
+
+      # v0.0.2 #6 — diagnostic suppression. Three kinds of
       # suppression compose:
       #
       # - **Project-level**: `disabled_rules` is the
       #   project's `.rigor.yml` `disable:` list. Any
       #   diagnostic whose `rule` is in the list is dropped.
-      # - **In-source**: `# rigor:disable <rule1>, <rule2>`
+      # - **File-level** (v0.1.2): `# rigor:disable-file <rule1>,
+      #   <rule2>` anywhere in the file suppresses the matching
+      #   diagnostic for every line. `# rigor:disable-file all`
+      #   suppresses every rule across the file. Convention is
+      #   to put the comment near the top, but Rigor accepts it
+      #   anywhere — the comment scope is "this file" regardless
+      #   of position.
+      # - **In-source line**: `# rigor:disable <rule1>, <rule2>`
       #   on the same line as the offending expression
       #   suppresses the matching diagnostic for that line
       #   only. `# rigor:disable all` on a line suppresses
@@ -162,34 +262,49 @@ module Rigor
       # errors, internal analyzer errors) are NEVER
       # suppressed — they represent failures the user cannot
       # silence away.
-      def filter_suppressed(diagnostics, comments:, disabled_rules:)
-        suppressions = parse_suppression_comments(comments)
+      def filter_suppressed(diagnostics, comments:, disabled_rules:) # rubocop:disable Metrics/CyclomaticComplexity
+        line_suppressions, file_suppressions = parse_suppression_comments(comments)
         disabled = expand_rule_tokens(disabled_rules)
 
         diagnostics.reject do |diagnostic|
           rule = diagnostic.rule
           next false if rule.nil?
           next true if disabled.include?(rule)
+          next true if file_suppressions.include?("all") || file_suppressions.include?(rule)
 
-          line_rules = suppressions[diagnostic.line]
+          line_rules = line_suppressions[diagnostic.line]
           line_rules && (line_rules.include?("all") || line_rules.include?(rule))
         end
       end
 
-      SUPPRESSION_PATTERN = /#\s*rigor:disable\s+(?<rules>[\w.,\s-]+)/
-      private_constant :SUPPRESSION_PATTERN
+      LINE_SUPPRESSION_PATTERN = /#\s*rigor:disable(?!-file)\s+(?<rules>[\w.,\s-]+)/
+      private_constant :LINE_SUPPRESSION_PATTERN
 
+      FILE_SUPPRESSION_PATTERN = /#\s*rigor:disable-file\s+(?<rules>[\w.,\s-]+)/
+      private_constant :FILE_SUPPRESSION_PATTERN
+
+      # @return [Array<(Hash{Integer => Set}, Set)>] pair of
+      #   `(line_suppressions, file_suppressions)`. Line
+      #   suppressions are keyed by source line number; file
+      #   suppressions apply to every line.
       def parse_suppression_comments(comments)
-        result = Hash.new { |h, k| h[k] = Set.new }
+        line_suppressions = Hash.new { |h, k| h[k] = Set.new }
+        file_suppressions = Set.new
         comments.each do |comment|
           source = comment.location.slice
-          match = SUPPRESSION_PATTERN.match(source)
-          next if match.nil?
+          if (match = FILE_SUPPRESSION_PATTERN.match(source))
+            absorb_suppression_tokens(match[:rules], file_suppressions)
+          elsif (match = LINE_SUPPRESSION_PATTERN.match(source))
+            absorb_suppression_tokens(match[:rules], line_suppressions[comment.location.start_line])
+          end
+        end
+        [line_suppressions, file_suppressions]
+      end
 
-          rules = match[:rules].to_s.split(/[\s,]+/).reject(&:empty?)
-          rules.each { |token| result[comment.location.start_line].merge(expand_token(token)) }
+      def absorb_suppression_tokens(raw, target)
+        raw.to_s.split(/[\s,]+/).reject(&:empty?).each do |token|
+          target.merge(expand_token(token))
         end
-        result
       end
 
       # Expands a list of user-supplied rule tokens into the
@@ -698,6 +813,203 @@ module Rigor
           )
         end
 
+        # v0.1.2 — `flow.unreachable-branch`. Fires when an
+        # `IfNode` / `UnlessNode` whose predicate is a literal
+        # `true` / `false` / `nil` (or a literal numeric /
+        # string / symbol whose Ruby truthiness is known
+        # at-a-glance) has an observable dead branch. The
+        # diagnostic points at the dead branch (not the
+        # predicate) so the squiggle lands on the code that
+        # never runs.
+        #
+        # Conservative envelope — by deliberate v0.1.2 design:
+        # - Only **literal-shaped** predicates fire. Inferred-
+        #   constant predicates (`x.method?` that happens to
+        #   fold to `Constant<bool>`) are intentionally
+        #   skipped — Rigor's loop / mutation / RBS-strictness
+        #   modelling is incomplete enough that an inferred
+        #   constant can be a false positive (e.g. accumulator
+        #   `arr << x` doesn't widen the carrier; defensive
+        #   `module.name.nil?` checks against anonymous-class
+        #   nil that the RBS `Module#name -> String` sig hides).
+        #   The literal-only envelope captures the clear
+        #   "user wrote `if false`" case without false alarms.
+        # - Empty dead branches (e.g. `if false; end` with no
+        #   body) are skipped — there is no useful location to
+        #   point at.
+        # - Postfix-`if` / `unless` modifiers with a literal
+        #   predicate ARE flagged (`expr if false` body never
+        #   runs, exactly like the block form).
+        # - Elsif chains (`subsequent` is itself an `IfNode`)
+        #   ARE flagged — the entire downstream chain is
+        #   unreachable when the outer predicate is a constant
+        #   literal.
+        #
+        # Broadening to inferred-constant predicates is queued
+        # for a later v0.1.x release once the loop / mutation
+        # gaps named above are closed.
+        def unreachable_branch_diagnostic(path, node, scope_index)
+          scope = scope_index[node]
+          return nil if scope.nil?
+
+          polarity = literal_predicate_polarity(node.predicate)
+          return nil if polarity.nil?
+
+          dead_branch = unreachable_branch_for(node, polarity == :truthy)
+          return nil if dead_branch.nil?
+
+          build_unreachable_branch_diagnostic(path, dead_branch, polarity)
+        end
+
+        # Returns `:truthy` / `:falsey` for a syntactically-
+        # literal predicate, or nil for anything else.
+        # `TrueNode`, `FalseNode`, `NilNode` are the
+        # unambiguous cases. Numeric / string / symbol literals
+        # are always truthy in Ruby (any non-`false` / non-`nil`
+        # value is truthy, including `0` and `""`).
+        TRUTHY_LITERAL_NODES = [
+          Prism::TrueNode, Prism::IntegerNode, Prism::FloatNode,
+          Prism::StringNode, Prism::SymbolNode, Prism::RegularExpressionNode
+        ].freeze
+        private_constant :TRUTHY_LITERAL_NODES
+
+        FALSEY_LITERAL_NODES = [Prism::FalseNode, Prism::NilNode].freeze
+        private_constant :FALSEY_LITERAL_NODES
+
+        def literal_predicate_polarity(predicate)
+          return :truthy if TRUTHY_LITERAL_NODES.any? { |klass| predicate.is_a?(klass) }
+          return :falsey if FALSEY_LITERAL_NODES.any? { |klass| predicate.is_a?(klass) }
+
+          nil
+        end
+
+        # v0.1.2 — `def.method-visibility-mismatch`. Fires when
+        # an explicit-receiver `Prism::CallNode` targets a
+        # user-class method whose `discovered_method_visibilities`
+        # entry is `:private`. The rule is intentionally narrow:
+        #
+        # - Only `:private`. `:protected` access depends on
+        #   subclass tracking the engine does not yet model;
+        #   broadening waits for that surface.
+        # - Only user classes whose visibility table the indexer
+        #   built. RBS-known classes (stdlib, gems) are NOT
+        #   consulted yet — RBS visibility is reliable but
+        #   surfacing it would broaden the rule to a level the
+        #   per-rule false-positive triage hasn't covered.
+        # - Implicit-self calls are skipped (always allowed for
+        #   private). Calls whose receiver is `Prism::SelfNode`
+        #   are also skipped — Ruby 2.7+ permits `self.foo` for
+        #   private methods.
+        # - Receiver MUST resolve to a `Type::Nominal` so the
+        #   rule has a single class identity to query. Unions /
+        #   Dynamic / shape carriers are skipped.
+        def visibility_mismatch_diagnostic(path, call_node, scope_index)
+          return nil unless explicit_non_self_receiver?(call_node.receiver)
+
+          scope = scope_index[call_node]
+          return nil if scope.nil?
+
+          receiver_type = scope.type_of(call_node.receiver)
+          return nil unless receiver_type.is_a?(Type::Nominal)
+
+          visibility = scope.discovered_method_visibility(receiver_type.class_name, call_node.name)
+          return nil unless visibility == :private
+
+          build_visibility_mismatch_diagnostic(path, call_node, receiver_type)
+        end
+
+        def explicit_non_self_receiver?(receiver)
+          return false if receiver.nil?
+          return false if receiver.is_a?(Prism::SelfNode)
+
+          true
+        end
+
+        def build_visibility_mismatch_diagnostic(path, call_node, receiver_type)
+          location = call_node.message_loc || call_node.location
+          Diagnostic.new(
+            rule: RULE_VISIBILITY_MISMATCH,
+            path: path,
+            line: location.start_line,
+            column: location.start_column + 1,
+            message: "private method `#{call_node.name}' called on #{receiver_type.class_name} receiver",
+            severity: :error
+          )
+        end
+
+        # Pulls a single concrete class name from an ivar write's
+        # rvalue type. Returns nil when the type is too unstable
+        # to compare (Union / Dynamic / IntegerRange / etc.).
+        # `concrete_class_name` already covers Nominal / Singleton
+        # / Constant / Tuple / HashShape; the wrapper exists so
+        # the ivar rule can extend the envelope (or apply
+        # different filters) without disturbing the call rules.
+        def ivar_class_for(type)
+          concrete_class_name(type)
+        end
+
+        def build_always_truthy_condition_diagnostic(path, predicate_node, polarity)
+          location = predicate_node.location
+          Diagnostic.new(
+            rule: RULE_ALWAYS_TRUTHY_CONDITION,
+            path: path,
+            line: location.start_line,
+            column: location.start_column + 1,
+            message: "condition is always #{polarity} (the surrounding flow proves it folds to a constant)",
+            severity: :warning
+          )
+        end
+
+        def build_dead_assignment_diagnostic(path, write_node, def_node)
+          location = write_node.name_loc || write_node.location
+          Diagnostic.new(
+            rule: RULE_DEAD_ASSIGNMENT,
+            path: path,
+            line: location.start_line,
+            column: location.start_column + 1,
+            message: "local `#{write_node.name}' assigned in `#{def_node.name}' but never read",
+            severity: :warning
+          )
+        end
+
+        # rubocop:disable Metrics/ParameterLists
+        def build_ivar_write_mismatch_diagnostic(path, node, class_name, ivar_name, first_class, other_class)
+          location = node.name_loc || node.location
+          Diagnostic.new(
+            rule: RULE_IVAR_WRITE_MISMATCH,
+            path: path,
+            line: location.start_line,
+            column: location.start_column + 1,
+            message: "instance variable `#{ivar_name}' on #{class_name} was previously assigned " \
+                     "#{first_class}; this write assigns #{other_class}",
+            severity: :error
+          )
+        end
+        # rubocop:enable Metrics/ParameterLists
+
+        # Returns the dead-branch node for a literal-predicate
+        # if/unless, or nil when no observable branch is dead.
+        def unreachable_branch_for(node, truthy)
+          dead =
+            case node
+            when Prism::IfNode then truthy ? node.subsequent : node.statements
+            when Prism::UnlessNode then truthy ? node.statements : node.else_clause
+            end
+          dead unless dead.nil?
+        end
+
+        def build_unreachable_branch_diagnostic(path, dead_branch, polarity)
+          location = dead_branch.location
+          Diagnostic.new(
+            rule: RULE_UNREACHABLE_BRANCH,
+            path: path,
+            line: location.start_line,
+            column: location.start_column + 1,
+            message: "unreachable branch: literal predicate is always #{polarity}",
+            severity: :warning
+          )
+        end
+
         # v0.0.2 #4 — argument-type-mismatch diagnostic.
         # Walks a call's positional arguments and checks each
         # against the matching parameter's RBS type via
@@ -915,6 +1227,19 @@ module Rigor
         # Method overloads contribute their union of declared
         # return types (any one of them satisfying the body
         # silences the rule).
+        #
+        # v0.1.2 — when the RBS sig carries a
+        # `%a{rigor:v1:return: <refinement>}` annotation
+        # (recognised by `RbsExtended.read_return_type_override`),
+        # the refinement carrier replaces the RBS-declared
+        # return for this rule. Annotation-driven refinements
+        # — `non-empty-string`, `positive-int`, `non-empty-
+        # array[Integer]`, etc. — are stricter than the
+        # underlying RBS class, so a body whose inferred type
+        # the bare RBS sig would accept may still fail the
+        # refinement (e.g. `def name; ""; end` returns
+        # `Constant[""]`, accepted by `String` but rejected by
+        # `non-empty-string`).
         def declared_return_type(def_node, scope_index)
           scope = scope_index[def_node]
           return nil if scope.nil?
@@ -930,6 +1255,9 @@ module Rigor
             end
           return nil if method_def.nil?
 
+          override = Rigor::RbsExtended.read_return_type_override(method_def)
+          return override if override
+
           declared_return_union(method_def, scope.environment)
         end
 

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

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+require_relative "gem_resolver"
+require_relative "index"
+require_relative "walker"
+
+module Rigor
+  module Analysis
+    module DependencySourceInference
+      # Folds a `Configuration::Dependencies` value into a
+      # frozen {Index}. Resolves each non-disabled entry through
+      # {GemResolver}, walks each resolved gem's `roots:` via
+      # {Walker.walk} under the configured `budget_per_gem` cap,
+      # and aggregates the per-gem method catalogs into the
+      # Index's flat `(class_name, method_name) → kind` table.
+      #
+      # Entries with `mode: :disabled` are skipped without
+      # resolution attempts so users can "list and disable" a
+      # gem in configuration without provoking a missing-gem
+      # diagnostic.
+      module Builder
+        module_function
+
+        # @param dependencies [Rigor::Configuration::Dependencies]
+        # @return [Index]
+        def build(dependencies) # rubocop:disable Metrics/MethodLength
+          return Index::EMPTY if dependencies.empty?
+
+          resolved = []
+          unresolvable = []
+          catalog = {}
+          class_to_gem = {}
+          budget_exceeded = []
+          budget = dependencies.budget_per_gem
+
+          dependencies.source_inference.each do |entry|
+            next if entry.disabled?
+
+            outcome = GemResolver.resolve(entry)
+            case outcome
+            when GemResolver::Resolved
+              resolved << outcome
+              walked = walker_outcome_for(outcome, budget)
+              catalog.merge!(walked.catalog)
+              record_class_to_gem(walked.catalog, outcome.gem_name, class_to_gem)
+              budget_exceeded << outcome.gem_name if walked.truncated?
+            when GemResolver::Unresolvable then unresolvable << outcome
+            end
+          end
+
+          Index.new(
+            resolved_gems: resolved, unresolvable: unresolvable,
+            method_catalog: catalog, budget_exceeded: budget_exceeded,
+            class_to_gem: class_to_gem,
+            budget_overrun_strategy: dependencies.budget_overrun_strategy
+          )
+        end
+
+        # ADR-10 5b — per-class reverse-lookup table (β budget
+        # semantics). Records `class_name → gem_name` for every
+        # class observed in the gem's catalog. First-write-wins:
+        # if two opt-in gems re-open the same class, the first
+        # gem to harvest the class owns it in the reverse index.
+        # The dispatcher only consults this map when the
+        # `budget_overrun_strategy` is `:dependency_silence`,
+        # so the storage cost is never paid back unless the
+        # user opts in.
+        def record_class_to_gem(catalog, gem_name, class_to_gem)
+          catalog.each_key do |(class_name, _method_name)|
+            class_to_gem[class_name] ||= gem_name
+          end
+        end
+
+        # Per-resolved-gem walk. Isolated so a single gem's
+        # filesystem error / parse failure cannot abort the
+        # build; the walker swallows its own per-file errors,
+        # and a top-level raise here degrades the gem to "no
+        # contributions" without touching the rest of the run.
+        def walker_outcome_for(resolved, budget)
+          Walker.walk(gem_dir: resolved.gem_dir, roots: resolved.roots, budget: budget)
+        rescue StandardError
+          Walker::Outcome.new(catalog: {}.freeze, truncated: false)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module Rigor
+  module Analysis
+    module DependencySourceInference
+      # Maps a `Configuration::Dependencies::Entry` to the gem's
+      # on-disk installation directory by consulting RubyGems
+      # (`Gem.loaded_specs` first, falling back to
+      # `Gem::Specification.find_by_name`). Returns either a
+      # frozen {Resolved} value object or an {Unresolvable} value
+      # describing why the gem cannot participate in this run.
+      #
+      # Resolution failures are surfaced as
+      # `dynamic.dependency-source.gem-not-found` diagnostics by
+      # {Analysis::Runner} rather than crashing the run, so a
+      # missing gem in `dependencies.source_inference` degrades
+      # cleanly to "no contributions from that gem" — every other
+      # gem and the project source remain unaffected.
+      module GemResolver
+        # Successful resolution. `version` is the spec version as
+        # a String so it round-trips into cache descriptors
+        # (slice 3) without leaking a `Gem::Version` instance
+        # through public surfaces.
+        Resolved = Data.define(:gem_name, :version, :gem_dir, :mode, :roots) do
+          def descriptor_key
+            [gem_name, version, mode].freeze
+          end
+        end
+
+        # Unresolvable reasons. `:not_in_bundle` covers both the
+        # "RubyGems doesn't know this gem" case and the
+        # `LoadError`-style raise from `find_by_name`. Future
+        # reasons (`:c_extension_only`, `:no_lib_root`) are
+        # introduced as the walker discovers them in slice 2b.
+        Unresolvable = Data.define(:gem_name, :reason)
+
+        VALID_REASONS = %i[not_in_bundle].freeze
+
+        module_function
+
+        # @param entry [Rigor::Configuration::Dependencies::Entry]
+        # @return [Resolved, Unresolvable]
+        def resolve(entry)
+          spec = locate_gem_spec(entry.gem)
+          return Unresolvable.new(gem_name: entry.gem, reason: :not_in_bundle) if spec.nil?
+
+          Resolved.new(
+            gem_name: entry.gem,
+            version: spec.version.to_s,
+            gem_dir: spec.full_gem_path, # rigor:disable undefined-method
+            mode: entry.mode,
+            roots: entry.roots
+          )
+        end
+
+        # Locator. `Gem.loaded_specs` reflects the bundle (cheap
+        # lookup, no filesystem walk); `find_by_name` is the
+        # broader fallback for gems present on the gem path but
+        # not yet `require`'d. `Gem::MissingSpecError` is a
+        # `LoadError` subclass, so the rescue covers both
+        # missing-spec and load-error signals.
+        def locate_gem_spec(name)
+          Gem.loaded_specs[name] || begin
+            Gem::Specification.find_by_name(name)
+          rescue LoadError
+            nil
+          end
+        end
+      end
+    end
+  end
+end