rigortype 0.1.9 → 0.1.11

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

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

@@ -0,0 +1,190 @@
+# frozen_string_literal: true
+
+require "prism"
+
+module Rigor
+  module Plugin
+    class Rspec < Rigor::Plugin::Base
+      # Walks an RSpec spec file's AST and yields, for each
+      # describe / context block (including the outer
+      # `RSpec.describe`), a `Scope` value with the `let`
+      # and `subject` declarations recorded inside that
+      # scope.
+      #
+      # Scope hierarchy is preserved: each `Scope` carries
+      # a list of its `nested_scopes`. The analyzer uses the
+      # hierarchy to detect cross-scope shadowing.
+      #
+      # Recognised scope methods (when called without a
+      # receiver, or with `RSpec` as the receiver):
+      #
+      # - `describe` / `context` — both open a new nested
+      #   scope.
+      # - `RSpec.describe` — the outermost scope.
+      #
+      # Recognised declaration methods (inside any scope,
+      # called without a receiver):
+      #
+      # - `let(:name) { ... }` — caches the block result
+      #   per-example; recorded as a Declaration.
+      # - `let!(:name) { ... }` — same, but evaluated
+      #   eagerly via a `before` hook; same shape for our
+      #   purposes.
+      # - `subject(:name) { ... }` — special-cases name
+      #   `:subject` when called without a name.
+      module ScopeWalker
+        SCOPE_METHODS = %i[describe context].freeze
+        DECLARATION_METHODS = %i[let let! subject].freeze
+
+        # @!attribute [r] kind
+        #   `:describe`, `:context`, or `:rspec_describe` for
+        #   the root.
+        # @!attribute [r] declarations
+        #   `Array<Declaration>` declared in this scope.
+        # @!attribute [r] nested_scopes
+        #   `Array<Scope>` nested under this scope.
+        # @!attribute [r] location
+        #   `Prism::Location` of the call node that opened
+        #   this scope.
+        Scope = Struct.new(:kind, :declarations, :nested_scopes, :location, keyword_init: true)
+
+        # @!attribute [r] name
+        #   `Symbol` declared name (`:user`, `:subject`,
+        #   ...).
+        # @!attribute [r] kind
+        #   `:let`, `:let!`, or `:subject`.
+        # @!attribute [r] location
+        #   `Prism::Location` of the call node.
+        # @!attribute [r] block_node
+        #   `Prism::BlockNode` of the declaration's body.
+        Declaration = Struct.new(:name, :kind, :location, :block_node, keyword_init: true)
+
+        module_function
+
+        # Walks the parsed file and returns an array of
+        # top-level scopes (each `RSpec.describe` is a
+        # separate root). Files with no recognised scopes
+        # return an empty array.
+        def collect_scopes(root)
+          scopes = []
+          walk_top_level(root, scopes)
+          scopes
+        end
+
+        # Walks every scope in a tree (root + descendants)
+        # and yields each in turn.
+        def each_scope(scope, &)
+          yield scope
+          scope.nested_scopes.each { |child| each_scope(child, &) }
+        end
+
+        def walk_top_level(node, scopes)
+          return unless node.is_a?(Prism::Node)
+
+          if rspec_describe_call?(node)
+            scopes << build_scope(node, kind: :rspec_describe)
+          else
+            node.compact_child_nodes.each { |child| walk_top_level(child, scopes) }
+          end
+        end
+
+        # Returns true for `RSpec.describe ... do |...| ...
+        # end` calls.
+        def rspec_describe_call?(node)
+          return false unless node.is_a?(Prism::CallNode)
+          return false unless node.name == :describe
+          return false unless node.block.is_a?(Prism::BlockNode)
+
+          receiver_name = constant_name(node.receiver)
+          %w[RSpec ::RSpec].include?(receiver_name)
+        end
+
+        # Returns true for `describe ... do ... end` /
+        # `context ... do ... end` (called without an
+        # explicit receiver — `RSpec.describe` is handled
+        # separately by `rspec_describe_call?`).
+        def nested_scope_call?(node)
+          node.is_a?(Prism::CallNode) &&
+            SCOPE_METHODS.include?(node.name) &&
+            node.block.is_a?(Prism::BlockNode) &&
+            node.receiver.nil?
+        end
+
+        def declaration_call?(node)
+          node.is_a?(Prism::CallNode) &&
+            DECLARATION_METHODS.include?(node.name) &&
+            node.receiver.nil?
+        end
+
+        # Constructs a Scope from a describe / context /
+        # RSpec.describe call node. Walks the block body
+        # for declarations + nested scopes.
+        def build_scope(call_node, kind:)
+          declarations = []
+          nested = []
+          (call_node.block.body&.compact_child_nodes || []).each do |child|
+            classify_child(child, declarations, nested)
+          end
+
+          Scope.new(
+            kind: kind,
+            declarations: declarations,
+            nested_scopes: nested,
+            location: call_node.location
+          )
+        end
+
+        def classify_child(child, declarations, nested)
+          if declaration_call?(child)
+            decl = build_declaration(child)
+            declarations << decl if decl
+          elsif nested_scope_call?(child)
+            nested << build_scope(child, kind: child.name)
+          end
+        end
+
+        def build_declaration(call_node)
+          first_arg = call_node.arguments&.arguments&.first
+          # `subject(&block)` (no name) defaults to the
+          # implicit subject; record it as `:subject`.
+          if first_arg.nil?
+            return nil unless call_node.name == :subject
+
+            return Declaration.new(
+              name: :subject,
+              kind: call_node.name,
+              location: call_node.location,
+              block_node: call_node.block
+            )
+          end
+          return nil unless first_arg.is_a?(Prism::SymbolNode)
+
+          Declaration.new(
+            name: first_arg.unescaped.to_sym,
+            kind: call_node.name,
+            location: call_node.location,
+            block_node: call_node.block
+          )
+        end
+
+        def constant_name(node)
+          case node
+          when nil then nil
+          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
+      end
+    end
+  end
+end

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

@@ -0,0 +1,188 @@
+# frozen_string_literal: true
+
+require "rigor/plugin"
+
+require_relative "rspec/scope_walker"
+require_relative "rspec/analyzer"
+require_relative "rspec/matcher_analyzer"
+require_relative "rspec/let_scope_index"
+require_relative "rspec/let_type_resolver"
+
+module Rigor
+  module Plugin
+    # rigor-rspec — validates RSpec `let` / `subject`
+    # declarations within each describe / context scope.
+    #
+    # Tier 3A of the [Rails plugins roadmap](../../../../docs/design/20260508-rails-plugins-roadmap.md).
+    # Deliberately scoped — the roadmap describes a much
+    # larger plugin (let-typo detection in `it` bodies,
+    # `expect(x).to receive(:method)` mock-target
+    # validation). Both are out of scope for v0.1.0; this
+    # plugin ships the two checks that have the lowest
+    # false-positive risk:
+    #
+    # 1. **Duplicate `let` / `subject` declarations** in
+    #    the same scope (`warning`). RSpec's runtime lets
+    #    the last declaration win, so the first one is
+    #    silently shadowed — almost always a copy-paste
+    #    bug.
+    # 2. **Self-referencing `let` / `subject`** — calling
+    #    the declared name *inside* its own block body
+    #    (`error`). At runtime this infinite-loops; users
+    #    typically meant to call a different method or
+    #    forgot to introduce a `super`.
+    #
+    # ## Configuration
+    #
+    # No knobs in v0.1.0. The plugin walks every analysed
+    # file looking for `RSpec.describe ... do` blocks; spec
+    # files outside the project's `paths:` are not scanned.
+    #
+    # ## Limitations (v0.1.0)
+    #
+    # - **No let-typo detection.** Detecting an `it`
+    #   block's reference to a misspelled `let` name
+    #   requires resolving every method call inside the
+    #   block against the let scope chain, the included
+    #   modules, the matchers DSL, and helper methods.
+    #   Reliable diagnostics here need a much heavier
+    #   walker — see the README's `Future direction`.
+    # - **No mock-target validation.**
+    #   `expect(x).to receive(:nme)` validating against
+    #   `x`'s methods is a separate slice; it overlaps with
+    #   the engine's general method-existence
+    #   diagnostics and needs careful coordination to avoid
+    #   double-firing.
+    # - **No shared-context resolution.** `include_context`,
+    #   `shared_context`, and `it_behaves_like` are
+    #   recognised as scope-opening calls but their
+    #   declarations are not pulled into the host scope.
+    # - **Constant validation is not done here.**
+    #   `RSpec.describe SomeClass do` does not validate
+    #   `SomeClass`; the engine's `inference.unresolved-constant`
+    #   already catches that.
+    class Rspec < Rigor::Plugin::Base
+      manifest(
+        id: "rspec",
+        version: "0.3.0",
+        description: "Validates RSpec `let` / `subject` declarations within each scope; " \
+                     "narrows expect(x).to <matcher> assertions downstream in `it` bodies; " \
+                     "binds let / subject locals to their inferred return type (Pillar 2 " \
+                     "Slice 2) — `let(:user) { User.new(...) }` / `let(:user) { create(:user) }` / " \
+                     "`subject { described_class.new(...) }`.",
+        consumes: [
+          { plugin_id: "factorybot", name: :factory_index, optional: true }
+        ]
+      )
+
+      def init(services)
+        @services = services
+        @factory_index_resolved = false
+        @factory_index = nil
+        # Per-path `LetScopeIndex` cache. The plugin's
+        # `flow_contribution_for` is called for every call
+        # node the dispatcher visits; building the index once
+        # per file is essential for performance.
+        @let_index_cache = {}
+      end
+
+      def diagnostics_for_file(path:, scope:, root:) # rubocop:disable Lint/UnusedMethodArgument
+        # Build the let-scope index for this file while we
+        # have the parsed root in hand — `flow_contribution_for`
+        # picks it up from `@let_index_cache` keyed on path.
+        @let_index_cache[path] ||= LetScopeIndex.build(root)
+        Analyzer.diagnose(path: path, root: root).map { |diag| build_diagnostic(diag) }
+      end
+
+      # Pillar 2 Slice 1 — spec-derived flow facts from RSpec
+      # matcher assertions (six-matcher floor: `be_a`,
+      # `be_kind_of`, `be_instance_of`, `be_nil`, `eq(literal)`,
+      # `eql(literal)`; `match(/regex/)`; `not_to` / `to_not`).
+      #
+      # Pillar 2 Slice 2 (v0.3.0) — additionally binds local
+      # reads in `it` / spec bodies to their `let(:name) { ... }`
+      # block's inferred return type. Composes with Slice 1:
+      # a matcher narrowing fires after the let binding.
+      def flow_contribution_for(call_node:, scope:)
+        matcher = MatcherAnalyzer.contribution_for(call_node, environment: scope&.environment)
+        return matcher if matcher
+
+        let_binding_contribution(call_node, scope)
+      end
+
+      private
+
+      # Pillar 2 Slice 2 — when the call node is a no-receiver
+      # method call (`user`, `subject`, etc.) inside an RSpec
+      # `describe` block whose lets include a matching name,
+      # return a `FlowContribution(return_type: <inferred>)`.
+      def let_binding_contribution(call_node, scope)
+        return nil if scope.nil?
+        return nil unless candidate_call?(call_node)
+
+        index = let_scope_index_for(scope.source_path)
+        return nil if index.nil?
+
+        line = call_node.location.start_line
+        block_node = index.let_block_at(line, call_node.name)
+        return nil if block_node.nil?
+
+        describe_const = index.describe_const_at(line)
+        type = LetTypeResolver.resolve(
+          block_node,
+          describe_const: describe_const,
+          factory_index: factory_index_or_nil,
+          environment: scope.environment
+        )
+        return nil if type.nil?
+
+        Rigor::FlowContribution.new(return_type: type)
+      end
+
+      def candidate_call?(call_node)
+        call_node.is_a?(Prism::CallNode) &&
+          call_node.receiver.nil? &&
+          call_node.block.nil? &&
+          # Calls with arguments are matcher / DSL invocations,
+          # not let-bound name reads. `subject` / `user` etc.
+          # without args are the implicit-method-call shape RSpec
+          # uses to expose let / subject in `it` bodies.
+          (call_node.arguments.nil? || call_node.arguments.arguments.empty?)
+      end
+
+      def let_scope_index_for(path)
+        return nil if path.nil?
+        return @let_index_cache[path] if @let_index_cache.key?(path)
+
+        @let_index_cache[path] = build_let_scope_index(path)
+      end
+
+      def build_let_scope_index(path)
+        source = io_boundary.read_file(path)
+        parse_result = Prism.parse(source)
+        return nil unless parse_result.errors.empty?
+
+        LetScopeIndex.build(parse_result.value)
+      rescue Rigor::Plugin::AccessDeniedError, Errno::ENOENT
+        nil
+      end
+
+      def factory_index_or_nil
+        return @factory_index if @factory_index_resolved
+
+        @factory_index = @services&.fact_store&.read(plugin_id: "factorybot", name: :factory_index)
+        @factory_index_resolved = true
+        @factory_index
+      end
+
+      def build_diagnostic(diag)
+        Rigor::Analysis::Diagnostic.new(
+          path: diag.path, line: diag.line, column: diag.column,
+          message: diag.message, severity: diag.severity, rule: diag.rule
+        )
+      end
+    end
+
+    Rigor::Plugin.register(Rspec)
+  end
+end

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

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative "rigor/plugin/rspec"