rigortype 0.0.2 → 0.0.3

data/lib/rigor/inference/narrowing.rb

@@ -155,6 +155,61 @@ module Rigor
         end
       end
 
+      # Integer-comparison fragment of `type` against an Integer
+      # literal `bound`. Narrows the receiver of `x < n`, `x <= n`,
+      # `x > n`, `x >= n` (and the reversed forms) to the subset of
+      # the existing domain that satisfies the comparison. Hooks in:
+      # - `Constant<Integer>` is preserved when it satisfies the
+      #   comparison, otherwise collapsed to `Bot`.
+      # - `IntegerRange[a..b]` becomes the intersection with the
+      #   half-line implied by the comparison; an empty intersection
+      #   collapses to `Bot`, a single-point intersection collapses
+      #   to `Constant<Integer>`.
+      # - `Nominal[Integer]` becomes the half-line itself (e.g.
+      #   `x > 0` on `Nominal[Integer]` is `positive_int`).
+      # - `Union` narrows each member independently.
+      # - Other carriers (Float, String, Top, Dynamic) flow through
+      #   unchanged: the analyzer does not have a Float-range carrier
+      #   today, and no other carrier participates in numeric ordering.
+      def narrow_integer_comparison(type, comparator, bound)
+        return type unless bound.is_a?(Integer) && %i[< <= > >=].include?(comparator)
+
+        narrow_integer_comparison_dispatch(type, comparator, bound)
+      end
+
+      # Equality fragment of `type` against an Integer `value`.
+      # `Constant<Integer>` is preserved when it equals `value`,
+      # otherwise collapses to `Bot`. `IntegerRange` covers? `value`
+      # narrows to `Constant[value]`; an out-of-range comparison
+      # collapses to `Bot`. `Nominal[Integer]` narrows to
+      # `Constant[value]`. `Union` narrows each member.
+      def narrow_integer_equal(type, value)
+        return type unless value.is_a?(Integer)
+
+        narrow_integer_equal_dispatch(type, value)
+      end
+
+      # Complement of {.narrow_integer_equal}. Removes a single
+      # integer value from the domain when one endpoint of an
+      # `IntegerRange` is exactly that value (so the result stays a
+      # contiguous range). Domains where the value sits strictly
+      # between the endpoints stay unchanged: punching a hole would
+      # require a two-piece carrier the lattice does not yet model.
+      def narrow_integer_not_equal(type, value)
+        return type unless value.is_a?(Integer)
+
+        case type
+        when Type::Constant
+          type.value == value ? Type::Combinator.bot : type
+        when Type::IntegerRange
+          narrow_integer_range_not_equal(type, value)
+        when Type::Union
+          Type::Combinator.union(*type.members.map { |m| narrow_integer_not_equal(m, value) })
+        else
+          type
+        end
+      end
+
       # Class-membership fragment of `type`: the subset whose
       # inhabitants are instances of `class_name` (or its subclasses
       # when `exact: false`). `class_name` is the qualified name of
@@ -452,7 +507,21 @@ module Rigor
           end
         end
 
+        ZERO_CLASS_PREDICATES = %i[positive? negative? zero? nonzero?].freeze
+        COMPARISON_OPERATORS = %i[< <= > >=].freeze
+        private_constant :ZERO_CLASS_PREDICATES, :COMPARISON_OPERATORS
+
         def dispatch_call(node, scope, name)
+          return dispatch_call_simple(node, scope, name) if simple_dispatch_name?(name)
+
+          dispatch_call_numeric(node, scope, name)
+        end
+
+        def simple_dispatch_name?(name)
+          %i[nil? ! is_a? kind_of? instance_of? == != ===].include?(name)
+        end
+
+        def dispatch_call_simple(node, scope, name)
           case name
           when :nil?, :! then dispatch_unary_predicate(node, scope, name)
           when :is_a?, :kind_of? then analyse_class_predicate(node, scope, exact: false)
@@ -462,6 +531,92 @@ module Rigor
           end
         end
 
+        def dispatch_call_numeric(node, scope, name)
+          if COMPARISON_OPERATORS.include?(name)
+            analyse_comparison_predicate(node, scope, comparator: name)
+          elsif ZERO_CLASS_PREDICATES.include?(name)
+            analyse_zero_class_predicate(node, scope, predicate: name)
+          elsif name == :between?
+            analyse_between_predicate(node, scope)
+          end
+        end
+
+        # `:positive?` / `:negative?` / `:zero?` / `:nonzero?` are
+        # zero-arg predicates on `Numeric`. We model them as
+        # comparisons against the literal 0 so the existing range
+        # narrowing handles them uniformly.
+        ZERO_CLASS_PREDICATE_RULES = {
+          positive?: { truthy: [:>, 0],  falsey: [:<=, 0] },
+          negative?: { truthy: [:<, 0],  falsey: [:>=, 0] },
+          zero?: { truthy: [:eq, 0], falsey: [:ne, 0] },
+          nonzero?: { truthy: [:ne, 0], falsey: [:eq, 0] }
+        }.freeze
+        private_constant :ZERO_CLASS_PREDICATE_RULES
+
+        def analyse_zero_class_predicate(node, scope, predicate:)
+          return nil unless argument_free?(node)
+          return nil unless node.receiver.is_a?(Prism::LocalVariableReadNode)
+
+          local_name = node.receiver.name
+          current = scope.local(local_name)
+          return nil if current.nil?
+
+          rules = ZERO_CLASS_PREDICATE_RULES[predicate]
+          truthy = apply_zero_rule(current, rules[:truthy])
+          falsey = apply_zero_rule(current, rules[:falsey])
+          [scope.with_local(local_name, truthy), scope.with_local(local_name, falsey)]
+        end
+
+        def apply_zero_rule(type, rule)
+          case rule[0]
+          when :eq then narrow_integer_equal(type, rule[1])
+          when :ne then narrow_integer_not_equal(type, rule[1])
+          else
+            narrow_integer_comparison(type, rule[0], rule[1])
+          end
+        end
+
+        # `x.between?(a, b)` truthy edge narrows to
+        # `narrow_integer_comparison(>=, a)` ∩
+        # `narrow_integer_comparison(<=, b)`. The falsey edge is left
+        # unchanged because the complement is a two-piece domain
+        # (`x < a || x > b`) that the lattice cannot express
+        # precisely. `a` and `b` MUST both be integer literals.
+        def analyse_between_predicate(node, scope)
+          return nil unless node.receiver.is_a?(Prism::LocalVariableReadNode)
+          return nil if node.arguments.nil?
+          return nil unless node.arguments.arguments.size == 2
+
+          low, high = node.arguments.arguments
+          return nil unless low.is_a?(Prism::IntegerNode) && high.is_a?(Prism::IntegerNode)
+
+          local_name = node.receiver.name
+          current = scope.local(local_name)
+          return nil if current.nil?
+
+          truthy = narrow_integer_comparison(
+            narrow_integer_comparison(current, :>=, low.value),
+            :<=, high.value
+          )
+          [scope.with_local(local_name, truthy), scope]
+        end
+
+        # Helper for {.narrow_integer_not_equal}. Only adjusts when the
+        # value sits exactly on one endpoint, so the result stays
+        # contiguous; otherwise the input range is preserved.
+        def narrow_integer_range_not_equal(range, value)
+          return range if range.lower > value || range.upper < value
+          return Type::Combinator.bot if single_point_range_equal?(range, value)
+          return build_narrowing_integer_range(value + 1, range.upper) if range.lower == value
+          return build_narrowing_integer_range(range.lower, value - 1) if range.upper == value
+
+          range
+        end
+
+        def single_point_range_equal?(range, value)
+          range.finite? && range.min == value && range.max == value
+        end
+
         def dispatch_unary_predicate(node, scope, name)
           return nil unless argument_free?(node)
 
@@ -491,6 +646,126 @@ module Rigor
           equality == :== ? [positive, negative] : [negative, positive]
         end
 
+        # Comparison predicate analyser. Recognised shapes:
+        #   x  <  Int        x  <=  Int        x  >  Int        x  >=  Int
+        #   Int <  x         Int <=  x         Int >  x         Int >=  x
+        # The reversed (literal-on-left) form is normalised by
+        # transposing the operator so the receiver-local always
+        # appears on the left of the rule.
+        INVERT_COMPARISON_OP = { :< => :>=, :<= => :>, :> => :<=, :>= => :< }.freeze
+        REVERSE_COMPARISON_OP = { :< => :>, :<= => :>=, :> => :<, :>= => :<= }.freeze
+        private_constant :INVERT_COMPARISON_OP, :REVERSE_COMPARISON_OP
+
+        def analyse_comparison_predicate(node, scope, comparator:)
+          return nil if node.arguments.nil?
+          return nil unless node.arguments.arguments.size == 1
+
+          match = comparison_local_literal(node.receiver, node.arguments.arguments.first, comparator)
+          return nil if match.nil?
+
+          local_name, normalised_op, bound = match
+          current = scope.local(local_name)
+          return nil if current.nil?
+
+          truthy = narrow_integer_comparison(current, normalised_op, bound)
+          falsey = narrow_integer_comparison(current, INVERT_COMPARISON_OP[normalised_op], bound)
+          [scope.with_local(local_name, truthy), scope.with_local(local_name, falsey)]
+        end
+
+        def comparison_local_literal(left, right, comparator)
+          if left.is_a?(Prism::LocalVariableReadNode) && right.is_a?(Prism::IntegerNode)
+            return [left.name, comparator, right.value]
+          end
+          return nil unless right.is_a?(Prism::LocalVariableReadNode) && left.is_a?(Prism::IntegerNode)
+
+          [right.name, REVERSE_COMPARISON_OP[comparator], left.value]
+        end
+
+        def narrow_integer_equal_dispatch(type, value)
+          case type
+          when Type::Constant then narrow_integer_equal_constant(type, value)
+          when Type::IntegerRange then narrow_integer_equal_range(type, value)
+          when Type::Nominal then narrow_integer_equal_nominal(type, value)
+          when Type::Union
+            Type::Combinator.union(*type.members.map { |m| narrow_integer_equal(m, value) })
+          else type
+          end
+        end
+
+        def narrow_integer_equal_constant(constant, value)
+          constant.value == value ? constant : Type::Combinator.bot
+        end
+
+        def narrow_integer_equal_range(range, value)
+          range.covers?(value) ? Type::Combinator.constant_of(value) : Type::Combinator.bot
+        end
+
+        def narrow_integer_equal_nominal(nominal, value)
+          return nominal unless nominal.class_name == "Integer" && nominal.type_args.empty?
+
+          Type::Combinator.constant_of(value)
+        end
+
+        def narrow_integer_comparison_dispatch(type, comparator, bound)
+          case type
+          when Type::Constant
+            integer_constant_satisfies?(type.value, comparator, bound) ? type : Type::Combinator.bot
+          when Type::IntegerRange
+            intersect_integer_range(type, comparator, bound)
+          when Type::Nominal
+            narrow_integer_comparison_nominal(type, comparator, bound)
+          when Type::Union
+            Type::Combinator.union(
+              *type.members.map { |m| narrow_integer_comparison(m, comparator, bound) }
+            )
+          else
+            type
+          end
+        end
+
+        def narrow_integer_comparison_nominal(nominal, comparator, bound)
+          return nominal unless nominal.class_name == "Integer" && nominal.type_args.empty?
+
+          intersect_integer_range(Type::Combinator.universal_int, comparator, bound)
+        end
+
+        def integer_constant_satisfies?(value, comparator, bound)
+          return false unless value.is_a?(Integer)
+
+          case comparator
+          when :<  then value < bound
+          when :<= then value <= bound
+          when :>  then value > bound
+          when :>= then value >= bound
+          end
+        end
+
+        def intersect_integer_range(range, comparator, bound)
+          new_lower, new_upper = comparison_endpoints(range, comparator, bound)
+          return Type::Combinator.bot if new_lower > new_upper
+
+          build_narrowing_integer_range(new_lower, new_upper)
+        end
+
+        def comparison_endpoints(range, comparator, bound)
+          case comparator
+          when :<  then [range.lower, [range.upper, bound - 1].min]
+          when :<= then [range.lower, [range.upper, bound].min]
+          when :>  then [[range.lower, bound + 1].max, range.upper]
+          when :>= then [[range.lower, bound].max, range.upper]
+          end
+        end
+
+        def build_narrowing_integer_range(lower, upper)
+          min = lower == -Float::INFINITY ? Type::IntegerRange::NEG_INFINITY : Integer(lower)
+          max = upper == Float::INFINITY ? Type::IntegerRange::POS_INFINITY : Integer(upper)
+          if min.is_a?(Integer) && max.is_a?(Integer) && min == max
+            Type::Combinator.constant_of(min)
+          else
+            Type::Combinator.integer_range(min, max)
+          end
+        end
+
         def equality_local_literal(left, right, scope)
           if left.is_a?(Prism::LocalVariableReadNode)
             literal = static_literal_type(right, scope)
@@ -850,10 +1125,11 @@ module Rigor
           fully_narrowable = true
 
           conditions.each do |condition|
-            target = static_class_name(condition) || case_equality_target_class(condition)
-            if target
-              truthy_members << narrow_class(current, target, exact: false, environment: scope.environment)
-              falsey_type = narrow_not_class(falsey_type, target, exact: false, environment: scope.environment)
+            applied = apply_case_when_condition(scope, current, condition, falsey_type)
+            if applied
+              truthy_members << applied[:truthy]
+              falsey_type = applied[:falsey]
+              fully_narrowable &&= applied[:fully_narrowable]
             else
               fully_narrowable = false
             end
@@ -866,6 +1142,100 @@ module Rigor
           ]
         end
 
+        # Per-condition rule. Returns `nil` when the condition shape
+        # is not recognised (caller marks `fully_narrowable = false`),
+        # or `{truthy:, falsey:, fully_narrowable:}` when it is.
+        def apply_case_when_condition(scope, current, condition, falsey_acc)
+          int_range = case_equality_integer_range(condition)
+          return integer_range_when_result(current, int_range, falsey_acc) if int_range && integer_rooted_type?(current)
+
+          int_literal = case_equality_integer_literal(condition)
+          if int_literal && integer_rooted_type?(current)
+            return integer_literal_when_result(current, int_literal, falsey_acc)
+          end
+
+          target = static_class_name(condition) || case_equality_target_class(condition)
+          return class_when_result(scope, current, target, falsey_acc) if target
+
+          nil
+        end
+
+        def case_equality_integer_literal(condition)
+          condition = unwrap_parens(condition)
+          condition.is_a?(Prism::IntegerNode) ? condition.value : nil
+        end
+
+        def integer_literal_when_result(current, value, falsey_acc)
+          # `case n when k` is `k === n` which for Integer is value
+          # equality. The truthy edge collapses the local to
+          # `Constant[k]`; the falsey edge tightens via
+          # `narrow_integer_not_equal` (only effective when k sits
+          # at one endpoint of the current range).
+          {
+            truthy: narrow_integer_equal(current, value),
+            falsey: narrow_integer_not_equal(falsey_acc, value),
+            fully_narrowable: true
+          }
+        end
+
+        def integer_range_when_result(current, range_pair, falsey_acc)
+          low, high = range_pair
+          truthy = narrow_integer_comparison(
+            narrow_integer_comparison(current, :>=, low),
+            :<=, high
+          )
+          # The falsey edge of `n in [a, b]` is two-piece; we cannot
+          # express the complement precisely with a single carrier,
+          # so keep the accumulator unchanged. `fully_narrowable: false`
+          # forces the else-branch to see `current` (the unmodified
+          # entry type), which mirrors `between?` falsey behaviour.
+          { truthy: truthy, falsey: falsey_acc, fully_narrowable: false }
+        end
+
+        def class_when_result(scope, current, target, falsey_acc)
+          {
+            truthy: narrow_class(current, target, exact: false, environment: scope.environment),
+            falsey: narrow_not_class(falsey_acc, target, exact: false, environment: scope.environment),
+            fully_narrowable: true
+          }
+        end
+
+        # Returns `[low, high]` for a `Prism::RangeNode` whose
+        # endpoints are both `Prism::IntegerNode` literals, with
+        # `..`/`...` exclusivity respected. Open-ended ranges use
+        # the symbolic infinities so the existing comparison
+        # narrowing tier handles them. Returns `nil` for any other
+        # shape (Float endpoints, String endpoints, dynamic
+        # expressions).
+        def case_equality_integer_range(condition)
+          condition = unwrap_parens(condition)
+          return nil unless condition.is_a?(Prism::RangeNode)
+
+          low = integer_range_endpoint(condition.left, default: Type::IntegerRange::NEG_INFINITY)
+          high = integer_range_endpoint(condition.right, default: Type::IntegerRange::POS_INFINITY)
+          return nil if low.nil? || high.nil?
+
+          high -= 1 if condition.exclude_end? && high.is_a?(Integer)
+          [low, high]
+        end
+
+        def integer_range_endpoint(node, default:)
+          return default if node.nil?
+          return node.value if node.is_a?(Prism::IntegerNode)
+
+          nil
+        end
+
+        def integer_rooted_type?(type)
+          case type
+          when Type::Constant then type.value.is_a?(Integer)
+          when Type::IntegerRange then true
+          when Type::Nominal then type.class_name == "Integer" && type.type_args.empty?
+          when Type::Union then type.members.all? { |m| integer_rooted_type?(m) }
+          else false
+          end
+        end
+
         def range_target_class(range_node)
           left = range_node.left
           right = range_node.right

data/lib/rigor/inference/scope_indexer.rb

@@ -418,11 +418,19 @@ module Rigor
         end
       end
 
+      # v0.0.3 A — sentinel key under which `record_def_node`
+      # files DefNodes that live outside any class / module
+      # body (top-level helpers, `def`s nested inside DSL
+      # blocks like `RSpec.describe ... do; def helper; end`).
+      # Looked up by `Scope#top_level_def_for` to give
+      # implicit-self calls priority over RBS dispatch when
+      # the file defines a same-named local method.
+      TOP_LEVEL_DEF_KEY = "<toplevel>"
+
       def record_def_node(def_node, qualified_prefix, in_singleton_class, accumulator)
-        return if qualified_prefix.empty?
         return if def_node.receiver.is_a?(Prism::SelfNode) || in_singleton_class
 
-        class_name = qualified_prefix.join("::")
+        class_name = qualified_prefix.empty? ? TOP_LEVEL_DEF_KEY : qualified_prefix.join("::")
         accumulator[class_name] ||= {}
         accumulator[class_name][def_node.name] = def_node
       end

data/lib/rigor/inference/statement_evaluator.rb

@@ -335,7 +335,17 @@ module Rigor
       # nil-injection on half-bound names so a name set in one branch
       # but not the other is observable as `T | nil` after the if.
       def eval_if(node)
-        _pred_type, post_pred = sub_eval(node.predicate, scope)
+        pred_type, post_pred = sub_eval(node.predicate, scope)
+
+        # When the predicate is a known-truthy / known-falsey type
+        # (notably `Constant[true]` / `Constant[false]` after the
+        # constant-fold tier), only the live branch contributes a
+        # type and a post-scope. The dead branch is skipped so the
+        # result type is precise (`Constant[:even]` instead of the
+        # joined `Constant[:even] | Constant[:odd]`).
+        live = live_branch_for_if(node, pred_type, post_pred)
+        return live if live
+
         truthy_scope, falsey_scope = Narrowing.predicate_scopes(node.predicate, post_pred)
         then_type, then_scope = eval_branch_or_nil(node.statements, truthy_scope)
         else_type, else_scope = eval_branch_or_nil(node.subsequent, falsey_scope)
@@ -360,7 +370,11 @@ module Rigor
       # narrower's truthy/falsey edges are routed in swapped form
       # because `unless` runs its body when the predicate is falsey.
       def eval_unless(node)
-        _pred_type, post_pred = sub_eval(node.predicate, scope)
+        pred_type, post_pred = sub_eval(node.predicate, scope)
+
+        live = live_branch_for_unless(node, pred_type, post_pred)
+        return live if live
+
         truthy_scope, falsey_scope = Narrowing.predicate_scopes(node.predicate, post_pred)
         then_type, then_scope = eval_branch_or_nil(node.statements, falsey_scope)
         else_type, else_scope = eval_branch_or_nil(node.else_clause, truthy_scope)
@@ -378,6 +392,38 @@ module Rigor
         ]
       end
 
+      # Returns the `[type, post_scope]` of the live branch when the
+      # predicate is provably truthy / falsey, else nil so the
+      # caller falls through to the standard both-branch evaluation.
+      # Constant `true`/`false` is the obvious trigger; non-falsey
+      # carriers like `Nominal[Integer]` (Integer is always truthy
+      # in Ruby — including 0) also collapse the dead else.
+      def live_branch_for_if(node, pred_type, post_pred)
+        case predicate_certainty(pred_type)
+        when :always_truthy then eval_branch_or_nil(node.statements, post_pred)
+        when :always_falsey then eval_branch_or_nil(node.subsequent, post_pred)
+        end
+      end
+
+      def live_branch_for_unless(node, pred_type, post_pred)
+        case predicate_certainty(pred_type)
+        when :always_truthy then eval_branch_or_nil(node.else_clause, post_pred)
+        when :always_falsey then eval_branch_or_nil(node.statements, post_pred)
+        end
+      end
+
+      def predicate_certainty(pred_type)
+        return nil if pred_type.nil? || pred_type.is_a?(Type::Bot)
+
+        truthy_bot = Narrowing.narrow_truthy(pred_type).is_a?(Type::Bot)
+        falsey_bot = Narrowing.narrow_falsey(pred_type).is_a?(Type::Bot)
+
+        return :always_falsey if truthy_bot && !falsey_bot
+        return :always_truthy if !truthy_bot && falsey_bot
+
+        nil
+      end
+
       def eval_else(node)
         return [Type::Combinator.constant_of(nil), scope] if node.statements.nil?
 
@@ -606,9 +652,172 @@ module Rigor
         evaluate_block_if_present(node)
         post_scope = record_closure_escape_if_any(node)
         post_scope = apply_rbs_extended_assertions(node, post_scope)
+        post_scope = apply_rspec_matcher_narrowing(node, post_scope)
         [call_type, post_scope]
       end
 
+      # v0.0.3 — recognises a small catalogue of RSpec
+      # matcher patterns as assert-shaped narrows on the
+      # local passed to `expect(...)`. The pattern is
+      # matched purely on AST shape; no RBS for RSpec is
+      # required (and none is shipped today).
+      #
+      # Recognised today:
+      #
+      #   expect(x).not_to(be_nil)
+      #   expect(x).to_not(be_nil)
+      #     → narrow `x` AWAY from `NilClass`.
+      #
+      #   expect(x).to(be_a(C))
+      #   expect(x).to(be_kind_of(C))
+      #   expect(x).to(be_an_instance_of(C))
+      #     → narrow `x` to `C` (exact for
+      #       `be_an_instance_of`, subtype-permitting
+      #       otherwise).
+      #
+      # Anything else is silently passed through. Symmetric
+      # negative class assertions (`not_to be_a(C)`) and
+      # narrowing TO `NilClass` are intentionally NOT
+      # modelled: they are rarely useful in practice and
+      # risk masking bugs if the assertion later fails.
+      def apply_rspec_matcher_narrowing(call_node, current_scope)
+        narrow = rspec_matcher_narrowing_request(call_node)
+        return current_scope if narrow.nil?
+
+        local_name = narrow.fetch(:local)
+        current_type = current_scope.local(local_name)
+        return current_scope if current_type.nil?
+
+        narrowed = apply_rspec_narrow(current_type, narrow, current_scope.environment)
+        current_scope.with_local(local_name, narrowed)
+      end
+
+      # Decodes an `expect(x).<chain>` outer call into a
+      # narrowing request hash, or `nil` when the shape is
+      # not recognised. The hash carries `:local` (the local
+      # name being narrowed) plus the narrowing parameters.
+      def rspec_matcher_narrowing_request(call_node)
+        local_name = rspec_expectation_target(call_node)
+        return nil if local_name.nil?
+
+        case call_node.name
+        when :not_to, :to_not
+          rspec_negative_narrow(call_node, local_name)
+        when :to
+          rspec_positive_narrow(call_node, local_name)
+        end
+      end
+
+      def rspec_negative_narrow(call_node, local_name)
+        return nil unless rspec_matcher_argument?(call_node, :be_nil)
+
+        { local: local_name, kind: :not_class, class_name: "NilClass", exact: false }
+      end
+
+      def rspec_positive_narrow(call_node, local_name)
+        matcher = rspec_matcher_node(call_node)
+        return nil if matcher.nil?
+
+        case matcher.name
+        when :be_a, :be_kind_of
+          rspec_be_a_narrow(matcher, local_name, exact: false)
+        when :be_an_instance_of, :be_instance_of
+          rspec_be_a_narrow(matcher, local_name, exact: true)
+        end
+      end
+
+      # `be_a` / `be_kind_of` / `be_an_instance_of` accept a
+      # single class argument — either a `ConstantReadNode`
+      # (`Integer`) or a `ConstantPathNode` (`Rigor::Type::Nominal`).
+      def rspec_be_a_narrow(matcher, local_name, exact:)
+        args = matcher.arguments&.arguments || []
+        return nil unless args.size == 1
+
+        class_name = constant_node_name(args.first)
+        return nil if class_name.nil?
+
+        { local: local_name, kind: :class, class_name: class_name, exact: exact }
+      end
+
+      def apply_rspec_narrow(current_type, narrow, environment)
+        case narrow.fetch(:kind)
+        when :not_class
+          Narrowing.narrow_not_class(current_type, narrow.fetch(:class_name),
+                                     exact: narrow.fetch(:exact), environment: environment)
+        when :class
+          Narrowing.narrow_class(current_type, narrow.fetch(:class_name),
+                                 exact: narrow.fetch(:exact), environment: environment)
+        end
+      end
+
+      # Returns the local name passed to `expect(...)` when
+      # the receiver chain matches `expect(<local>)` exactly,
+      # or nil otherwise. Centralised so each per-matcher
+      # decoder can short-circuit on a non-matching outer
+      # call.
+      def rspec_expectation_target(call_node) # rubocop:disable Metrics/CyclomaticComplexity
+        receiver = call_node.receiver
+        return nil unless receiver.is_a?(Prism::CallNode) && receiver.name == :expect
+        return nil unless receiver.receiver.nil?
+
+        args = receiver.arguments&.arguments || []
+        return nil unless args.size == 1
+
+        target = args.first
+        target.is_a?(Prism::LocalVariableReadNode) ? target.name : nil
+      end
+
+      def rspec_matcher_node(call_node)
+        args = call_node.arguments&.arguments || []
+        return nil unless args.size == 1
+
+        matcher = args.first
+        return nil unless matcher.is_a?(Prism::CallNode) && matcher.receiver.nil? && matcher.block.nil?
+
+        matcher
+      end
+
+      # True when `call_node`'s sole argument is an
+      # implicit-self matcher call with the given name and
+      # no positional arguments — used by the no-arg
+      # matchers (`be_nil`).
+      def rspec_matcher_argument?(call_node, matcher_name)
+        matcher = rspec_matcher_node(call_node)
+        return false if matcher.nil?
+        return false unless matcher.name == matcher_name
+
+        matcher.arguments.nil? || matcher.arguments.arguments.empty?
+      end
+
+      # Decodes a `Prism::ConstantReadNode` /
+      # `Prism::ConstantPathNode` into a colon-joined class
+      # name string, or returns nil for any other node
+      # shape. Mirrors the conservative envelope used by the
+      # `is_a?` / `kind_of?` predicate narrower.
+      def constant_node_name(node)
+        case node
+        when Prism::ConstantReadNode
+          node.name.to_s
+        when Prism::ConstantPathNode
+          flatten_constant_path(node)
+        end
+      end
+
+      def flatten_constant_path(node)
+        parts = []
+        cursor = node
+        while cursor.is_a?(Prism::ConstantPathNode)
+          parts.unshift(cursor.name.to_s)
+          cursor = cursor.parent
+        end
+        case cursor
+        when Prism::ConstantReadNode then parts.unshift(cursor.name.to_s)
+        when nil then nil # ::Foo absolute root — preserve as-is
+        else return nil
+        end
+        parts.join("::")
+      end
+
       # v0.0.2 — applies `RBS::Extended` `assert <target> is T`
       # directives to the post-call scope. The conditional
       # variants (`assert-if-true` / `assert-if-false`) are