rigortype 0.1.10 → 0.1.12

data/plugins/rigor-rspec/lib/rigor/plugin/rspec/let_scope_index.rb

@@ -0,0 +1,200 @@
+# frozen_string_literal: true
+
+require "prism"
+
+require_relative "scope_walker"
+
+module Rigor
+  module Plugin
+    class Rspec < Rigor::Plugin::Base
+      # Per-file index of RSpec scope hierarchy. Each
+      # describe scope carries:
+      #
+      # - `outer_range`: `Range[Integer]` of line numbers
+      #   covered by the describe's block body (start_line..end_line).
+      # - `describe_const`: the model constant string named in
+      #   `RSpec.describe SomeModel do` / `describe SomeModel do`,
+      #   or `nil` when the describe's first arg is a String
+      #   (`describe ".foo"`).
+      # - `lets`: `Hash{Symbol => Prism::BlockNode}` of `let(:name)
+      #   { ... }` and `subject(:name) { ... }` declarations.
+      #   `:subject` is the key for the implicit `subject { ... }`.
+      #
+      # Pillar 2 Slice 2 — used by the plugin's
+      # `flow_contribution_for` hook to bind `let`-named
+      # method-shape calls inside `it` bodies to the let
+      # block's inferred type.
+      class LetScopeIndex
+        Record = Struct.new(:outer_range, :describe_const, :lets, keyword_init: true) do
+          def contains?(line) = outer_range.cover?(line)
+          def let?(name) = lets.key?(name.to_sym)
+          def let_block(name) = lets[name.to_sym]
+        end
+
+        attr_reader :records
+
+        def initialize(records)
+          @records = records.freeze
+          freeze
+        end
+
+        # Returns every record whose outer_range contains the
+        # given line, ordered from outermost to innermost. The
+        # innermost wins on `let` name collisions per Ruby's
+        # method-resolution order (RSpec nested `let` shadows
+        # the outer `let`).
+        def records_at(line)
+          @records.select { |rec| rec.contains?(line) }
+        end
+
+        # Resolves a `let` name at the given line by walking
+        # records innermost to outermost.
+        # @return [Prism::BlockNode, nil]
+        def let_block_at(line, name)
+          name_sym = name.to_sym
+          records_at(line).reverse.each do |rec|
+            return rec.let_block(name_sym) if rec.let?(name_sym)
+          end
+          nil
+        end
+
+        # Resolves the `describe`-anchor constant name at the
+        # given line. The innermost describe with a constant
+        # anchor wins; describe-with-String anchors are skipped.
+        # @return [String, nil]
+        def describe_const_at(line)
+          records_at(line).reverse.each do |rec|
+            return rec.describe_const if rec.describe_const
+          end
+          nil
+        end
+
+        # Builds an index from a parsed root node.
+        def self.build(root)
+          records = []
+          collect(root, anchor: nil, accumulator: records)
+          new(records)
+        end
+
+        def self.collect(node, anchor:, accumulator:)
+          return unless node.is_a?(Prism::Node)
+
+          if describe_call?(node)
+            record = build_record(node, anchor)
+            accumulator << record
+            if node.block&.body
+              collect(node.block.body, anchor: record.describe_const || anchor, accumulator: accumulator)
+            end
+            return
+          end
+
+          node.compact_child_nodes.each do |child|
+            collect(child, anchor: anchor, accumulator: accumulator)
+          end
+        end
+
+        def self.build_record(describe_call, parent_anchor)
+          block_body = describe_call.block.body
+          start_line = block_body&.location&.start_line || describe_call.location.start_line
+          end_line = block_body&.location&.end_line || describe_call.block.location.end_line
+
+          Record.new(
+            outer_range: (start_line..end_line),
+            describe_const: describe_call_const(describe_call) || parent_anchor,
+            lets: collect_lets(describe_call.block.body)
+          )
+        end
+
+        def self.describe_call?(node)
+          return false unless node.is_a?(Prism::CallNode)
+          return false unless ScopeWalker::SCOPE_METHODS.include?(node.name) || node.name == :describe
+          return false unless node.block.is_a?(Prism::BlockNode)
+
+          # `RSpec.describe ...` has receiver = RSpec; bare
+          # `describe ... do` has nil receiver. Accept both.
+          node.receiver.nil? || describe_receiver?(node.receiver)
+        end
+
+        def self.describe_receiver?(receiver)
+          case receiver
+          when Prism::ConstantReadNode then receiver.name == :RSpec
+          when Prism::ConstantPathNode then receiver.name == :RSpec && receiver.parent.nil?
+          else false
+          end
+        end
+
+        def self.describe_call_const(describe_call)
+          first_arg = describe_call.arguments&.arguments&.first
+          render_const(first_arg)
+        end
+
+        def self.render_const(node)
+          case node
+          when Prism::ConstantReadNode then node.name.to_s
+          when Prism::ConstantPathNode
+            parts = []
+            current = node
+            while current.is_a?(Prism::ConstantPathNode)
+              parts.unshift(current.name.to_s)
+              current = current.parent
+            end
+            case current
+            when nil then "::#{parts.join('::')}"
+            when Prism::ConstantReadNode then "#{current.name}::#{parts.join('::')}"
+            end
+          end
+        end
+
+        # Walks the describe's body shallowly: collects every
+        # top-level `let(:name) { ... }` / `subject(:name) { ... }`
+        # / `subject { ... }` declaration. Does NOT recurse into
+        # nested describe / context blocks — those have their
+        # own record built by `collect` above.
+        def self.collect_lets(body)
+          return {} unless body.is_a?(Prism::Node)
+
+          lets = {}
+          statements_of(body).each do |stmt|
+            decl = let_declaration(stmt)
+            next if decl.nil?
+
+            lets[decl[:name]] = decl[:block]
+          end
+          lets.freeze
+        end
+
+        def self.statements_of(node)
+          case node
+          when Prism::StatementsNode then node.body
+          else [node]
+          end
+        end
+
+        def self.let_declaration(node)
+          return nil unless node.is_a?(Prism::CallNode)
+          return nil unless node.receiver.nil?
+          return nil unless %i[let let! subject].include?(node.name)
+          return nil unless node.block.is_a?(Prism::BlockNode)
+
+          name = let_declaration_name(node)
+          return nil if name.nil?
+
+          { name: name, block: node.block }
+        end
+
+        def self.let_declaration_name(call_node)
+          first_arg = call_node.arguments&.arguments&.first
+          if first_arg.nil?
+            # `subject { ... }` with no name — implicit :subject.
+            return :subject if call_node.name == :subject
+
+            return nil
+          end
+          return nil unless first_arg.is_a?(Prism::SymbolNode)
+
+          first_arg.unescaped.to_sym
+        end
+      end
+    end
+  end
+end

data/plugins/rigor-rspec/lib/rigor/plugin/rspec/let_type_resolver.rb

@@ -0,0 +1,170 @@
+# frozen_string_literal: true
+
+require "prism"
+require "rigor/type"
+
+module Rigor
+  module Plugin
+    class Rspec < Rigor::Plugin::Base
+      # Pillar 2 Slice 2 — resolves the runtime type of a
+      # `let(:name) { body }` or `subject(:name) { body }`
+      # block by pattern-matching its body's tail expression.
+      #
+      # Recognised body shapes (floor):
+      #
+      # - `ConstantClass.new(...)` → `Nominal[ConstantClass]`
+      # - `Foo::Bar.new(...)` → `Nominal[Foo::Bar]`
+      # - `described_class.new(...)` → `Nominal[<describe const>]`
+      #   when the surrounding describe block has a constant
+      #   anchor.
+      # - `create(:factory)` / `build(:factory)` /
+      #   `build_stubbed(:factory)` / `attributes_for(:factory)`
+      #   → `Nominal[<factory.model_class>]` when the
+      #   `:factory_index` ADR-9 fact is available and the
+      #   factory name is known.
+      # - `FactoryBot.create(:factory)` etc. — same as the
+      #   implicit-receiver factorybot form.
+      #
+      # Returns `nil` for any other body shape. Multi-statement
+      # bodies use the LAST statement (the block's return
+      # value).
+      module LetTypeResolver
+        FACTORYBOT_ENTRY_METHODS = %i[
+          create build build_stubbed attributes_for
+          create_list build_list build_stubbed_list
+        ].freeze
+
+        module_function
+
+        # @param block_node [Prism::BlockNode]
+        # @param describe_const [String, nil]
+        # @param factory_index [Object, nil] something
+        #   responding to `find(factory_name)` and returning
+        #   an entry that responds to `model_class`.
+        # @param environment [Rigor::Environment, nil]
+        # @return [Rigor::Type, nil]
+        def resolve(block_node, describe_const:, factory_index:, environment:)
+          tail = body_tail(block_node)
+          return nil if tail.nil?
+
+          nominal_for_call(
+            tail,
+            describe_const: describe_const,
+            factory_index: factory_index,
+            environment: environment
+          )
+        end
+
+        def body_tail(block_node)
+          body = block_node.body
+          return nil if body.nil?
+
+          case body
+          when Prism::StatementsNode
+            body.body.last
+          else
+            body
+          end
+        end
+
+        def nominal_for_call(node, describe_const:, factory_index:, environment:)
+          return nil unless node.is_a?(Prism::CallNode)
+
+          # `<Const>.new(...)` / `<ConstPath>.new(...)`
+          if node.name == :new && const_receiver?(node.receiver)
+            class_name = render_const(node.receiver)
+            return nominal_for(class_name, environment: environment) if class_name
+          end
+
+          # `described_class.new(...)`
+          if node.name == :new && described_class_receiver?(node.receiver)
+            return nil if describe_const.nil?
+
+            return nominal_for(describe_const, environment: environment)
+          end
+
+          # `create(:name)` / `build(:name)` / `FactoryBot.create(:name)` / `*_list`
+          factorybot_nominal(node, factory_index: factory_index, environment: environment)
+        end
+
+        def factorybot_nominal(call_node, factory_index:, environment:)
+          return nil if factory_index.nil?
+          return nil unless factorybot_call?(call_node)
+
+          factory_name = factorybot_first_arg(call_node)
+          return nil if factory_name.nil?
+
+          entry = factory_index.find(factory_name)
+          return nil if entry.nil?
+
+          model_class = entry.respond_to?(:model_class) ? entry.model_class : nil
+          return nil if model_class.nil?
+
+          nominal_for(model_class, environment: environment)
+        end
+
+        # Recognises both `create(:name)` (implicit receiver,
+        # via `include FactoryBot::Syntax::Methods`) and the
+        # explicit `FactoryBot.create(:name)` /
+        # `FactoryGirl.create(:name)` (legacy) forms.
+        def factorybot_call?(call_node)
+          return false unless FACTORYBOT_ENTRY_METHODS.include?(call_node.name)
+
+          recv = call_node.receiver
+          recv.nil? || factorybot_constant?(recv)
+        end
+
+        def factorybot_constant?(node)
+          case node
+          when Prism::ConstantReadNode then %i[FactoryBot FactoryGirl].include?(node.name)
+          when Prism::ConstantPathNode
+            node.parent.nil? && %i[FactoryBot FactoryGirl].include?(node.name)
+          else false
+          end
+        end
+
+        def factorybot_first_arg(call_node)
+          first_arg = call_node.arguments&.arguments&.first
+          case first_arg
+          when Prism::SymbolNode then first_arg.unescaped
+          when Prism::StringNode then first_arg.unescaped
+          end
+        end
+
+        def const_receiver?(node)
+          node.is_a?(Prism::ConstantReadNode) || node.is_a?(Prism::ConstantPathNode)
+        end
+
+        def described_class_receiver?(node)
+          node.is_a?(Prism::CallNode) && node.name == :described_class && node.receiver.nil?
+        end
+
+        def render_const(node)
+          case node
+          when Prism::ConstantReadNode then node.name.to_s
+          when Prism::ConstantPathNode
+            parts = []
+            current = node
+            while current.is_a?(Prism::ConstantPathNode)
+              parts.unshift(current.name.to_s)
+              current = current.parent
+            end
+            case current
+            when nil then "::#{parts.join('::')}"
+            when Prism::ConstantReadNode then "#{current.name}::#{parts.join('::')}"
+            end
+          end
+        end
+
+        def nominal_for(class_name, environment:)
+          if environment
+            environment.nominal_for_name(class_name) ||
+              Rigor::Type::Combinator.nominal_of(class_name)
+          else
+            Rigor::Type::Combinator.nominal_of(class_name)
+          end
+        end
+      end
+    end
+  end
+end

data/plugins/rigor-rspec/lib/rigor/plugin/rspec/matcher_analyzer.rb

@@ -0,0 +1,233 @@
+# frozen_string_literal: true
+
+require "prism"
+require "rigor/type"
+require "rigor/flow_contribution"
+require "rigor/flow_contribution/fact"
+
+module Rigor
+  module Plugin
+    class Rspec < Rigor::Plugin::Base
+      # Pillar 2 Slice 1 — recognises `expect(x).to MATCHER`
+      # patterns at `flow_contribution_for` time and emits
+      # `post_return_facts` that narrow the named local on the
+      # post-call edge.
+      #
+      # The supported matchers are the lowest-false-positive
+      # floor of the RSpec matcher DSL:
+      #
+      # - `be_a(T)` / `be_kind_of(T)` — `x is_a?(T)` style class
+      #   membership; narrows `x` to `T`.
+      # - `be_instance_of(T)` — exact-class match; narrows
+      #   `x` to `T` (the engine currently treats Nominal[T]
+      #   uniformly, so the distinction with `be_a` is observed
+      #   at the carrier level but not the runtime).
+      # - `be_nil` — narrows `x` to `Constant<nil>`.
+      # - `eq(LITERAL)` for a literal-value argument — narrows
+      #   `x` to `Constant<literal>`.
+      #
+      # The matchers below this floor (`be_truthy` / `be_falsey`
+      # / `be_within` / `be > / < / >=` / `include` / `start_with`
+      # / `match(regex)` / `raise_error` / receive-style mocks)
+      # require either edge-aware fragments (`truthy_facts` /
+      # `falsey_facts` rather than `post_return_facts`) or
+      # diagnostic-only enforcement; both are queued for follow-up
+      # slices.
+      #
+      # The analyzer fires ONLY when:
+      #
+      # 1. The call node is one of `<recv>.to(matcher)` /
+      #    `<recv>.not_to(matcher)` / `<recv>.to_not(matcher)`.
+      #    `not_to` / `to_not` flip the fact's `negative` flag
+      #    so the engine narrows AWAY from the matcher's type
+      #    (e.g. `not_to be_nil` removes nil from the receiver).
+      # 2. The receiver is `expect(<local_var>)` — exactly one
+      #    positional argument that's a LocalVariableReadNode.
+      #    Composite receivers (`expect(foo.bar)`,
+      #    `expect { ... }.to raise_error`) fall through.
+      # 3. The matcher is one of the recognised forms above
+      #    (`be_a` / `be_kind_of` / `be_instance_of` /
+      #    `be_an_instance_of` / `be_nil` / `eq(literal)` /
+      #    `eql(literal)` / `match(/regex/)`).
+      module MatcherAnalyzer
+        module_function
+
+        # @param call_node [Prism::CallNode] the call whose
+        #   contribution we're computing. Returns nil when the
+        #   call shape does not match `expect(local).to matcher`.
+        # @param environment [Rigor::Environment, nil] the
+        #   surrounding environment used to resolve a matcher's
+        #   class-name argument to a `Type::Nominal`. When nil,
+        #   class-name resolution falls back to a bare
+        #   `Nominal[<name>]` carrier (sound — the receiver
+        #   constant may be a user class not in RBS).
+        # @return [Rigor::FlowContribution, nil]
+        def contribution_for(call_node, environment:)
+          verb = assertion_verb(call_node)
+          return nil if verb.nil?
+          return nil unless call_node.receiver.is_a?(Prism::CallNode)
+
+          expect_call = call_node.receiver
+          return nil unless expect_call?(expect_call)
+
+          target_local = expect_first_arg_local(expect_call)
+          return nil if target_local.nil?
+
+          matcher = matcher_call(call_node)
+          return nil if matcher.nil?
+
+          narrowed_type = narrowed_type_for(matcher, environment: environment)
+          return nil if narrowed_type.nil?
+
+          fact = Rigor::FlowContribution::Fact.new(
+            target_kind: :local,
+            target_name: target_local,
+            type: narrowed_type,
+            negative: verb == :negative
+          )
+          Rigor::FlowContribution.new(post_return_facts: [fact])
+        end
+
+        # Recognises the assertion verb chained after `expect(...)`:
+        # - `.to(<matcher>)`     → :positive
+        # - `.not_to(<matcher>)` → :negative
+        # - `.to_not(<matcher>)` → :negative (older spelling)
+        # Returns nil for any other call.
+        def assertion_verb(node)
+          return nil unless node.is_a?(Prism::CallNode)
+          return nil unless node.arguments&.arguments&.size == 1
+
+          case node.name
+          when :to then :positive
+          when :not_to, :to_not then :negative
+          end
+        end
+
+        def expect_call?(node)
+          node.is_a?(Prism::CallNode) && node.name == :expect &&
+            node.receiver.nil? && node.arguments&.arguments&.size == 1
+        end
+
+        def expect_first_arg_local(expect_call)
+          arg = expect_call.arguments.arguments.first
+          return nil unless arg.is_a?(Prism::LocalVariableReadNode)
+
+          arg.name
+        end
+
+        def matcher_call(to_call)
+          to_call.arguments.arguments.first
+        end
+
+        # Translates a recognised matcher CallNode into the
+        # narrowed type. Returns nil when the matcher is
+        # unrecognised or its argument shape does not match the
+        # supported envelope.
+        def narrowed_type_for(matcher, environment:)
+          return nil unless matcher.is_a?(Prism::CallNode) && matcher.receiver.nil?
+
+          case matcher.name
+          when :be_a, :be_kind_of, :be_instance_of, :be_an_instance_of
+            nominal_type_for_class_arg(matcher, environment: environment)
+          when :be_nil
+            return nil unless empty_args?(matcher)
+
+            Rigor::Type::Combinator.constant_of(nil)
+          when :eq, :eql
+            constant_type_for_literal_arg(matcher)
+          when :match
+            # `match(/regex/)` narrows x to String. `match("...")`
+            # or `match(arbitrary_object)` falls through — the
+            # broader matcher dispatch needs the receiver to be a
+            # String, but we can only assert that for a literal
+            # regex.
+            string_type_for_regex_arg(matcher)
+          end
+        end
+
+        def nominal_type_for_class_arg(matcher, environment:)
+          args = matcher.arguments&.arguments || []
+          return nil unless args.size == 1
+
+          class_name = constant_path_name(args.first)
+          return nil if class_name.nil?
+
+          if environment
+            environment.nominal_for_name(class_name) ||
+              Rigor::Type::Combinator.nominal_of(class_name)
+          else
+            Rigor::Type::Combinator.nominal_of(class_name)
+          end
+        end
+
+        def constant_type_for_literal_arg(matcher)
+          args = matcher.arguments&.arguments || []
+          return nil unless args.size == 1
+
+          literal_value = literal_value_for(args.first)
+          return nil if literal_value.equal?(NO_LITERAL)
+
+          Rigor::Type::Combinator.constant_of(literal_value)
+        end
+
+        def string_type_for_regex_arg(matcher)
+          args = matcher.arguments&.arguments || []
+          return nil unless args.size == 1
+
+          arg = args.first
+          return nil unless arg.is_a?(Prism::RegularExpressionNode) ||
+                            arg.is_a?(Prism::InterpolatedRegularExpressionNode)
+
+          Rigor::Type::Combinator.nominal_of("String")
+        end
+
+        NO_LITERAL = Object.new.freeze
+        private_constant :NO_LITERAL
+
+        # Returns the Ruby value of a literal-AST argument, or
+        # `NO_LITERAL` when the node isn't a recognised literal
+        # shape. Recognised forms cover the common `eq(literal)`
+        # case: integer, float, true/false/nil, string, symbol.
+        def literal_value_for(node)
+          case node
+          when Prism::IntegerNode then node.value
+          when Prism::FloatNode then node.value
+          when Prism::TrueNode then true
+          when Prism::FalseNode then false
+          when Prism::NilNode then nil
+          when Prism::StringNode then node.unescaped
+          when Prism::SymbolNode then node.unescaped.to_sym
+          else NO_LITERAL
+          end
+        end
+
+        def empty_args?(matcher)
+          args = matcher.arguments&.arguments
+          args.nil? || args.empty?
+        end
+
+        # Renders a `Prism::ConstantReadNode` /
+        # `Prism::ConstantPathNode` chain as a `"Foo::Bar"`
+        # String. Returns nil when the node isn't a constant
+        # reference.
+        def constant_path_name(node)
+          case node
+          when Prism::ConstantReadNode
+            node.name.to_s
+          when Prism::ConstantPathNode
+            parts = []
+            current = node
+            while current.is_a?(Prism::ConstantPathNode)
+              parts.unshift(current.name.to_s)
+              current = current.parent
+            end
+            case current
+            when nil then "::#{parts.join('::')}"
+            when Prism::ConstantReadNode then "#{current.name}::#{parts.join('::')}"
+            end
+          end
+        end
+      end
+    end
+  end
+end