rigortype 0.0.9 → 0.1.1

data/lib/rigor/inference/narrowing.rb

@@ -7,6 +7,7 @@ require_relative "../type"
 require_relative "../environment"
 require_relative "../rbs_extended"
 require_relative "../analysis/fact_store"
+require_relative "../builtins/regex_refinement"
 
 module Rigor
   module Inference
@@ -293,6 +294,29 @@ module Rigor
         end
       end
 
+      # ADR-7 § "Slice 4-A" — public Fact-shaped narrowing
+      # entry. Distinguishes a `Nominal[<class>]`-typed Fact
+      # (uses `narrow_class` / `narrow_not_class` for
+      # hierarchy-aware narrowing) from a refinement-shaped
+      # Fact (refined types, IntegerRange, Difference, …).
+      # The implementation lives next to its sibling helpers
+      # `narrow_class` and `narrow_not_refinement`; consumers
+      # outside `Narrowing` (today: `StatementEvaluator`'s
+      # post-return assertion path) reach for it via
+      # `Rigor::Inference::Narrowing.narrow_for_fact`.
+      def narrow_for_fact(current, fact, environment)
+        if fact.type.is_a?(Type::Nominal) && fact.type.type_args.empty?
+          class_name = fact.type.class_name
+          return narrow_not_class(current, class_name, exact: false, environment: environment) if fact.negative?
+
+          return narrow_class(current, class_name, exact: false, environment: environment)
+        end
+
+        return narrow_not_refinement(current, fact.type) if fact.negative?
+
+        fact.type
+      end
+
       # Public predicate analyser. Returns `[truthy_scope, falsey_scope]`,
       # always; when no narrowing rule matches the predicate node both
       # entries are the receiver scope unchanged.
@@ -352,7 +376,7 @@ module Rigor
       # the predicate shape is recognised, or `nil` to signal "no
       # narrowing" so the public surface can fall back to the entry
       # scope.
-      def analyse(node, scope)
+      def analyse(node, scope) # rubocop:disable Metrics/CyclomaticComplexity
         case node
         when Prism::ParenthesesNode
           analyse_parentheses(node, scope)
@@ -366,6 +390,8 @@ module Rigor
           analyse_and(node, scope)
         when Prism::OrNode
           analyse_or(node, scope)
+        when Prism::MatchWriteNode
+          analyse_match_write(node, scope)
         end
       end
 
@@ -712,6 +738,60 @@ module Rigor
           ]
         end
 
+        # `if /(?<x>...)/ =~ str` — Prism wraps the `=~` call in a
+        # `MatchWriteNode` listing the named-capture targets. The
+        # parent `eval_match_write` has already bound each target
+        # to `String | nil`; in the truthy branch (the regex
+        # matched) every named capture is guaranteed `String`,
+        # and in the falsey branch (no match) every capture is
+        # `nil`. Subtract the dead half on each edge so callers
+        # like `year.upcase` inside the truthy branch no longer
+        # fire `possible-nil-receiver`.
+        #
+        # v0.1.1 Track 1 slice 1 — when the regex source is a
+        # statically known `RegularExpressionNode` and a named
+        # capture's body matches one of the curated shapes in
+        # {Rigor::Builtins::RegexRefinement::RULES}, the truthy
+        # branch narrows further than `String` to the matching
+        # imported refinement (e.g. `decimal-int-string` for
+        # `\d+`). Bodies outside the table fall back to the
+        # v0.1.0 baseline (plain `String`).
+        def analyse_match_write(node, scope)
+          string_t = Type::Combinator.nominal_of("String")
+          nil_t = Type::Combinator.constant_of(nil)
+          refinements = match_write_capture_refinements(node)
+          truthy = scope
+          falsey = scope
+          node.targets.each do |target|
+            next unless target.is_a?(Prism::LocalVariableTargetNode)
+
+            truthy = truthy.with_local(target.name, refinements[target.name] || string_t)
+            falsey = falsey.with_local(target.name, nil_t)
+          end
+          [truthy, falsey]
+        end
+
+        # Extracts `{ capture_name => Refinement }` for every named
+        # capture group in the `MatchWriteNode`'s wrapped `=~` call
+        # whose body the recogniser table accepts. Bodies that
+        # contain nested groups, anchors, alternation, or anything
+        # else outside the curated forms drop out and the caller
+        # falls back to plain `String`.
+        NAMED_CAPTURE_BODY_RE = /\(\?<([A-Za-z_][A-Za-z0-9_]*)>([^()|]*)\)/
+        private_constant :NAMED_CAPTURE_BODY_RE
+
+        def match_write_capture_refinements(node)
+          regex = node.call.is_a?(Prism::CallNode) ? node.call.receiver : nil
+          return {} unless regex.is_a?(Prism::RegularExpressionNode)
+
+          refinements = {}
+          regex.unescaped.scan(NAMED_CAPTURE_BODY_RE) do |name, body|
+            type = ::Rigor::Builtins::RegexRefinement.for_capture_body(body)
+            refinements[name.to_sym] = type if type
+          end
+          refinements
+        end
+
         # Recognised CallNode predicates:
         # - `recv.nil?` (Slice 6 phase 1, no args, no block)
         # - unary `!recv` (`name == :!`, no args, no block)
@@ -724,42 +804,80 @@ module Rigor
         # through to the no-narrowing fallback.
         def analyse_call(node, scope)
           return nil if node.block
-          return nil if node.receiver.nil?
 
-          shape_result = dispatch_call(node, scope, node.name)
-          return shape_result if shape_result
+          unless node.receiver.nil?
+            shape_result = dispatch_call(node, scope, node.name)
+            return shape_result if shape_result
+
+            # v0.1.1 Track 1 slice 4 — String predicate flow facts.
+            string_predicate_result = analyse_string_predicate(node, scope)
+            return string_predicate_result if string_predicate_result
+          end
 
           # Slice 7 phase 15 — RBS::Extended predicate
           # effects. When the method's RBS signature carries
           # `rigor:v1:predicate-if-true` / `predicate-if-false`
           # annotations, apply them to narrow the corresponding
-          # local-variable arguments on each edge.
-          predicate_result = analyse_rbs_extended_predicate(node, scope)
-          assert_result = analyse_rbs_extended_assert_if(node, scope)
-          merge_extended_results(predicate_result, assert_result, scope)
-        end
-
-        # Combines two `[truthy_scope, falsey_scope]` pair
-        # results from sibling RBS::Extended analysers
-        # (`predicate-if-*` and `assert-if-*`). When only one
-        # side fires, return it directly; when both fire the
-        # right side's per-local deltas are applied on top of
-        # the left side's edges so the rules compose.
-        def merge_extended_results(left, right, base_scope)
-          return left if right.nil?
-          return right if left.nil?
+          # local-variable arguments on each edge. v0.1.1 Track
+          # 1 slice 3 — implicit-self calls (`recv == nil`,
+          # e.g. `admin?` inside an instance method body) flow
+          # through here too so `self`-targeted facts can edit
+          # `scope.self_type`.
+          analyse_rbs_extended_contribution(node, scope)
+        end
+
+        # v0.1.1 Track 1 slice 4 — `String#start_with?` /
+        # `#end_with?` / `#include?` against a `Constant<String>`
+        # needle attaches a relational `FactStore::Fact` to the
+        # local on each edge. The receiver's type does NOT
+        # change — Rigor has no "starts-with-X" carrier today —
+        # so the fact carries the predicate semantics for any
+        # downstream consumer that wants to read it (e.g. a
+        # plugin's `prepare(services)` hook in v0.1.x).
+        # Truthy edge: positive polarity. Falsey edge: negative
+        # polarity. Mirrors the equality-predicate fact pattern
+        # already used by `analyse_equality_predicate`.
+        STRING_PREDICATE_NAMES = %i[start_with? end_with? include?].freeze
+        private_constant :STRING_PREDICATE_NAMES
+
+        def analyse_string_predicate(node, scope)
+          return nil unless string_predicate_call?(node)
+
+          needle = string_predicate_needle(node, scope)
+          return nil if needle.nil?
+
+          local_name = node.receiver.name
+          return nil if scope.local(local_name).nil?
 
           [
-            merge_scope_pair(left[0], right[0], base_scope),
-            merge_scope_pair(left[1], right[1], base_scope)
+            scope.with_fact(string_predicate_fact(local_name, node.name, needle, polarity: :positive)),
+            scope.with_fact(string_predicate_fact(local_name, node.name, needle, polarity: :negative))
           ]
         end
 
-        def merge_scope_pair(left_scope, right_scope, base_scope)
-          right_scope.locals.reduce(left_scope) do |acc, (name, type)|
-            base_type = base_scope.local(name)
-            type.equal?(base_type) ? acc : acc.with_local(name, type)
-          end
+        def string_predicate_call?(node)
+          STRING_PREDICATE_NAMES.include?(node.name) &&
+            node.receiver.is_a?(Prism::LocalVariableReadNode) &&
+            !node.arguments.nil? &&
+            node.arguments.arguments.size == 1
+        end
+
+        def string_predicate_needle(node, scope)
+          needle_type = static_literal_type(node.arguments.arguments.first, scope)
+          return nil unless needle_type.is_a?(Type::Constant) && needle_type.value.is_a?(String)
+
+          needle_type.value
+        end
+
+        def string_predicate_fact(name, predicate, needle, polarity:)
+          Analysis::FactStore::Fact.new(
+            bucket: :relational,
+            target: Analysis::FactStore::Target.local(name),
+            predicate: predicate,
+            payload: needle,
+            polarity: polarity,
+            stability: :local_binding
+          )
         end
 
         ZERO_CLASS_PREDICATES = %i[positive? negative? zero? nonzero?].freeze
@@ -1187,118 +1305,130 @@ module Rigor
           node
         end
 
-        # Slice 7 phase 15 — RBS::Extended predicate-effect
-        # analyser. Resolves the called method through the
-        # RBS environment, reads any `rigor:v1:predicate-if-*`
-        # annotations, and applies them to the call's
-        # local-variable arguments.
+        # Slice 4b-1 (ADR-7 § "Slice 4-A/4-B") — single-point
+        # RBS::Extended contribution analyser. Replaces the
+        # earlier sibling pair (`analyse_rbs_extended_predicate`
+        # + `analyse_rbs_extended_assert_if`) with one path that
+        # routes through `RbsExtended.read_flow_contribution` and
+        # `Rigor::FlowContribution::Merger.merge`. The bundle's
+        # `truthy_facts` slot already includes both the
+        # `predicate-if-true` and `assert-if-true` Facts (slice
+        # 4a routing closed the v0.0.9 imperfection); the
+        # `falsey_facts` slot mirrors that. The merger composes
+        # any future plugin contribution at the same site
+        # alongside the RBS::Extended bundle without changing
+        # this analyser.
         #
-        # Conservative envelope:
+        # Conservative envelope (carried over from the previous
+        # implementation):
         # - Receiver type must be `Type::Nominal`,
         #   `Type::Singleton`, or `Type::Constant`.
         # - The method must be present in the loader.
-        # - For each predicate effect, the corresponding
-        #   positional argument (matched by parameter name in
-        #   the selected overload) MUST be a
-        #   `Prism::LocalVariableReadNode` for narrowing to
-        #   apply.
-        # - When the target is `self`, narrowing applies to
-        #   the receiver — but the engine does not yet narrow
-        #   `self` itself (Slice A-engine self-typing is
-        #   read-only), so `self`-targeted effects are
-        #   accepted by the parser but currently produce no
+        # - For each fact, the corresponding positional
+        #   argument (matched by parameter name in the selected
+        #   overload) MUST be a `Prism::LocalVariableReadNode`
+        #   for narrowing to apply.
+        # - When the target is `self`, narrowing applies to the
+        #   receiver — but the engine does not yet narrow
+        #   `self` itself, so `self`-targeted facts are
+        #   accepted by the merger but currently produce no
         #   scope edits.
-        def analyse_rbs_extended_predicate(node, scope)
+        def analyse_rbs_extended_contribution(node, scope)
           method_def = resolve_rbs_extended_method(node, scope)
           return nil if method_def.nil?
 
-          effects = RbsExtended.read_predicate_effects(method_def)
-          return nil if effects.empty?
+          contribution = RbsExtended.read_flow_contribution(method_def)
+          return nil if contribution.nil?
 
-          truthy_scope = scope
-          falsey_scope = scope
-          effects.each do |effect|
-            truthy_scope, falsey_scope =
-              apply_predicate_effect(effect, node, scope, truthy_scope, falsey_scope, method_def)
-          end
-          [truthy_scope, falsey_scope]
-        end
-
-        # v0.0.2 — `assert-if-true` / `assert-if-false`. Reads
-        # the conditional assertion effects off the called
-        # method and narrows the matching argument on the
-        # corresponding edge. The unconditional `assert`
-        # variant is NOT applied here; `StatementEvaluator`
-        # applies it directly to the post-call scope.
-        def analyse_rbs_extended_assert_if(node, scope)
-          method_def = resolve_rbs_extended_method(node, scope)
-          return nil if method_def.nil?
+          result = Rigor::FlowContribution::Merger.merge([contribution])
+          truthy_facts = result.truthy_facts
+          falsey_facts = result.falsey_facts
+          return nil if truthy_facts.empty? && falsey_facts.empty?
 
-          effects = RbsExtended.read_assert_effects(method_def).reject(&:always?)
-          return nil if effects.empty?
+          apply_facts_to_scope_pair(node, scope, truthy_facts, falsey_facts, method_def)
+        end
 
-          truthy_scope = scope
-          falsey_scope = scope
-          effects.each do |effect|
-            truthy_scope, falsey_scope =
-              apply_assert_if_effect(effect, node, scope, truthy_scope, falsey_scope, method_def)
+        def apply_facts_to_scope_pair(call_node, entry_scope, truthy_facts, falsey_facts, method_def)
+          truthy_scope = entry_scope
+          falsey_scope = entry_scope
+          truthy_facts.each do |fact|
+            truthy_scope = apply_fact_to_scope(fact, call_node, entry_scope, truthy_scope, method_def)
+          end
+          falsey_facts.each do |fact|
+            falsey_scope = apply_fact_to_scope(fact, call_node, entry_scope, falsey_scope, method_def)
           end
           [truthy_scope, falsey_scope]
         end
 
-        # rubocop:disable Metrics/ParameterLists
-        def apply_assert_if_effect(effect, call_node, entry_scope, truthy_scope, falsey_scope, method_def)
-          target_node = effect_target_node(effect, call_node, method_def)
-          return [truthy_scope, falsey_scope] unless target_node.is_a?(Prism::LocalVariableReadNode)
+        def apply_fact_to_scope(fact, call_node, entry_scope, target_scope, method_def)
+          target_node = fact_target_node(fact, call_node, method_def)
+          return apply_self_fact(fact, target_node, entry_scope, target_scope) if fact.target_kind == :self
+          return target_scope unless target_node.is_a?(Prism::LocalVariableReadNode)
 
           local_name = target_node.name
           current = entry_scope.local(local_name)
-          return [truthy_scope, falsey_scope] if current.nil?
+          return target_scope if current.nil?
 
-          narrowed = narrow_for_effect(current, effect, entry_scope.environment)
-          if effect.if_truthy_return?
-            [truthy_scope.with_local(local_name, narrowed), falsey_scope]
-          else
-            [truthy_scope, falsey_scope.with_local(local_name, narrowed)]
-          end
+          narrowed = narrow_for_fact(current, fact, entry_scope.environment)
+          target_scope.with_local(local_name, narrowed)
         end
-        # rubocop:enable Metrics/ParameterLists
-
-        # v0.0.2 #3 — resolves an effect's target node. For
-        # `target: <param>` we look up the matching positional
-        # argument; for `target: self` we use the call's
-        # receiver. In both cases the caller still requires a
-        # `Prism::LocalVariableReadNode` for narrowing to
-        # actually fire (the engine's narrowing surface only
-        # rebinds locals).
-        def effect_target_node(effect, call_node, method_def)
-          if effect.target_kind == :self
-            call_node.receiver
+
+        # v0.1.1 Track 1 slice 3 — `target_kind == :self` facts
+        # (`predicate-if-true self is T`, `predicate-if-false
+        # self is T`) narrow whichever scope binding is bound to
+        # the call's receiver. Four receiver shapes participate:
+        #
+        #   `recv.method?` where recv is...
+        #   - `LocalVariableReadNode`            -> narrow that local
+        #   - `InstanceVariableReadNode`         -> narrow that ivar
+        #   - `Prism::SelfNode` (explicit self)  -> narrow `self_type`
+        #   - nil (implicit self call inside a method body)
+        #                                        -> narrow `self_type`
+        #
+        # Other receiver shapes (method chains, expressions) have
+        # no scope binding to narrow against and fall through.
+        def apply_self_fact(fact, receiver_node, entry_scope, target_scope)
+          case receiver_node
+          when nil, Prism::SelfNode
+            current = entry_scope.self_type
+            return target_scope if current.nil?
+
+            narrowed = narrow_for_fact(current, fact, entry_scope.environment)
+            target_scope.with_self_type(narrowed)
+          when Prism::LocalVariableReadNode
+            current = entry_scope.local(receiver_node.name)
+            return target_scope if current.nil?
+
+            narrowed = narrow_for_fact(current, fact, entry_scope.environment)
+            target_scope.with_local(receiver_node.name, narrowed)
+          when Prism::InstanceVariableReadNode
+            current = entry_scope.ivar(receiver_node.name)
+            return target_scope if current.nil?
+
+            narrowed = narrow_for_fact(current, fact, entry_scope.environment)
+            target_scope.with_ivar(receiver_node.name, narrowed)
           else
-            lookup_positional_arg(call_node, method_def, effect.target_name)
+            target_scope
           end
         end
 
-        # v0.0.2 — selects `narrow_class` (positive) or
-        # `narrow_not_class` (negative `~T` form) based on
-        # the effect's `negative?` flag. Shared between
-        # predicate-if-* and assert-if-* application paths.
-        def narrow_for_effect(current, effect, environment)
-          if effect.respond_to?(:refinement?) && effect.refinement?
-            return narrow_not_refinement(current, effect.refinement_type) if effect.negative?
-
-            return effect.refinement_type
-          end
-
-          if effect.negative?
-            narrow_not_class(current, effect.class_name, exact: false, environment: environment)
+        # Resolves a Fact's target node. Mirrors the earlier
+        # `effect_target_node` helper but reads from the
+        # canonical Fact carrier; `:self` routes to the call
+        # receiver, otherwise we look up the matching
+        # positional argument by parameter name.
+        def fact_target_node(fact, call_node, method_def)
+          if fact.target_kind == :self
+            call_node.receiver
           else
-            narrow_class(current, effect.class_name, exact: false, environment: environment)
+            lookup_positional_arg(call_node, method_def, fact.target_name)
           end
         end
 
         def resolve_rbs_extended_method(node, scope)
-          receiver_type = scope.type_of(node.receiver)
+          receiver_type = receiver_type_for_resolve(node, scope)
+          return nil if receiver_type.nil?
+
           class_name = rbs_extended_class_name(receiver_type)
           return nil if class_name.nil?
           return nil unless Rigor::Reflection.rbs_class_known?(class_name, scope: scope)
@@ -1312,6 +1442,13 @@ module Rigor
           nil
         end
 
+        # Implicit self call (`admin?` with no receiver inside an
+        # instance method body) — read the method definition from
+        # `scope.self_type` per v0.1.1 Track 1 slice 3.
+        def receiver_type_for_resolve(node, scope)
+          node.receiver.nil? ? scope.self_type : scope.type_of(node.receiver)
+        end
+
         def rbs_extended_class_name(receiver_type)
           case receiver_type
           when Type::Nominal, Type::Singleton then receiver_type.class_name
@@ -1332,24 +1469,6 @@ module Rigor
           nil
         end
 
-        # rubocop:disable Metrics/ParameterLists
-        def apply_predicate_effect(effect, call_node, entry_scope, truthy_scope, falsey_scope, method_def)
-          target_node = effect_target_node(effect, call_node, method_def)
-          return [truthy_scope, falsey_scope] unless target_node.is_a?(Prism::LocalVariableReadNode)
-
-          local_name = target_node.name
-          current = entry_scope.local(local_name)
-          return [truthy_scope, falsey_scope] if current.nil?
-
-          narrowed = narrow_for_effect(current, effect, entry_scope.environment)
-          if effect.truthy_only?
-            [truthy_scope.with_local(local_name, narrowed), falsey_scope]
-          else
-            [truthy_scope, falsey_scope.with_local(local_name, narrowed)]
-          end
-        end
-        # rubocop:enable Metrics/ParameterLists
-
         # Maps the effect's target parameter name to the call
         # site argument by inspecting the selected overload's
         # required-positional parameter list. Returns the Prism