rigortype 0.1.18 → 0.2.0

data/lib/rigor/inference/narrowing.rb

@@ -11,7 +11,8 @@ require_relative "../builtins/regex_refinement"
 
 module Rigor
   module Inference
-    # Slice 6 phase 1 minimal narrowing surface.
+    # Control-flow predicate narrowing and type-lattice narrowing
+    # primitives.
     #
     # `Rigor::Inference::Narrowing` answers two related questions:
     #
@@ -19,22 +20,19 @@ module Rigor
     #    truthy fragment, its falsey fragment, its nil fragment, and its
     #    non-nil fragment? These primitives understand the value-lattice
     #    algebra (`Constant`, `Nominal`, `Singleton`, `Tuple`, `HashShape`,
-    #    `Union`) and stay conservative on `Top` and `Dynamic[T]`, where
-    #    the analyzer cannot prove the boundary either way.
+    #    `Union`) and stay conservative on `Top` and `Dynamic[T]`.
     # 2. Predicate-level narrowing: given a Prism predicate node and an
     #    entry scope, what are the truthy-edge scope and the falsey-edge
-    #    scope after the predicate has been evaluated? The phase 1
-    #    catalogue covers truthiness on `LocalVariableReadNode`, `nil?`
-    #    against a local, the unary `!` inverter, parenthesised
-    #    predicates, and short-circuiting `&&` / `||` chains.
+    #    scope? The catalogue covers truthiness, `nil?`, `!`, `&&`/`||`,
+    #    class-membership (`is_a?`, `kind_of?`, `instance_of?`), trusted
+    #    equality/inequality against static literals, `case`/`when`,
+    #    regex match globals, string predicates (`start_with?` etc.),
+    #    key-presence, array emptiness, numeric comparison, and
+    #    `respond_to?`.
     #
-    # Predicate-level narrowing is consumed by
-    # `Rigor::Inference::StatementEvaluator` to refine the `then` and
-    # `else` scopes of `IfNode`/`UnlessNode`. Phase 1 narrows local
-    # bindings on truthiness and `nil?`; phase 2 extends the catalogue
-    # with class-membership predicates (`is_a?`, `kind_of?`,
-    # `instance_of?`) and trusted equality/inequality checks against
-    # static literals.
+    # Consumed by `Rigor::Inference::StatementEvaluator` to refine
+    # `then`/`else` scopes of `IfNode`/`UnlessNode` and
+    # `case`/`when` branches.
     #
     # The module is pure: every public function returns fresh values and
     # MUST NOT mutate its inputs. Unrecognised predicate shapes degrade
@@ -43,8 +41,8 @@ module Rigor
     # `[truthy_scope, falsey_scope]` pair (the entry scope twice when no
     # rule matches).
     #
-    # See docs/internal-spec/inference-engine.md (Slice 6 — Narrowing)
-    # and docs/type-specification/control-flow-analysis.md for the
+    # See docs/internal-spec/inference-engine.md (Narrowing) and
+    # docs/type-specification/control-flow-analysis.md for the
     # binding contract.
     # rubocop:disable Metrics/ModuleLength
     module Narrowing
@@ -423,13 +421,45 @@ module Rigor
       # @param scope [Rigor::Scope]
       # @return [Array(Rigor::Scope, Rigor::Scope)]
       def case_when_scopes(subject, conditions, scope)
-        return [scope, scope] unless subject.is_a?(Prism::LocalVariableReadNode)
+        # C1 — `case x when /re/` runs `/re/ === x`, which sets the
+        # regex match-data globals exactly as a successful `=~` does.
+        # Narrow `$~`/`$&`/`$1..$N` on the clause body (the match
+        # edge); the falsey scope keeps the entry globals because a
+        # later clause may match a different regex. Applied even when
+        # the subject is not a narrowable local read.
+        body_scope = apply_when_regex_globals(conditions, scope)
+
+        return [body_scope, scope] unless subject.is_a?(Prism::LocalVariableReadNode)
 
         local_name = subject.name
         current = scope.local(local_name)
-        return [scope, scope] if current.nil?
+        return [body_scope, scope] if current.nil?
+
+        truthy, = accumulate_case_when_scopes(body_scope, local_name, current, conditions)
+        _, falsey = accumulate_case_when_scopes(scope, local_name, current, conditions)
+        [truthy, falsey]
+      end
 
-        accumulate_case_when_scopes(scope, local_name, current, conditions)
+      # When the clause has exactly one `RegularExpressionNode`
+      # literal condition, narrow the match-data globals on the body
+      # edge (same rule as `analyse_regex_match_predicate`'s truthy
+      # edge). With multiple regex conditions (`when /a/, /b/`) the
+      # body is reachable through any of them, so only `$~`/`$&` are
+      # safely non-nil; numbered groups whose presence differs per
+      # alternative stay `String | nil`. With no regex condition the
+      # entry scope passes through unchanged.
+      def apply_when_regex_globals(conditions, scope)
+        regexes = conditions.grep(Prism::RegularExpressionNode)
+        return scope if regexes.empty?
+
+        unconditional =
+          if regexes.size == 1
+            unconditional_capture_groups(regexes.first.unescaped)
+          else
+            Set.new
+          end
+        truthy, = regex_match_predicate_scopes(scope, unconditional)
+        truthy
       end
 
       # Internal analyser. Returns `[truthy_scope, falsey_scope]` when
@@ -936,11 +966,23 @@ module Rigor
 
           unless node.receiver.nil?
             shape_result = dispatch_call(node, scope, node.name)
-            return shape_result if shape_result
+            return apply_safe_nav_non_nil(node, scope, 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
+            return apply_safe_nav_non_nil(node, scope, string_predicate_result) if string_predicate_result
+
+            # A safe-navigation call (`v&.foo`) whose result is truthy
+            # proves the receiver was non-nil — `&.` returns `nil` when
+            # the receiver is nil, so a truthy outcome can only come from
+            # a non-nil receiver. Narrow the receiver on the truthy edge
+            # even when the call itself carries no other flow fact, so
+            # `v&.start_with?('[') && v.end_with?(']')` sees `v` non-nil
+            # in the `&&` right operand. The falsey edge is the
+            # conservative no-op (falsey could mean nil receiver OR a
+            # falsey method result).
+            safe_nav_result = analyse_safe_nav_receiver(node, scope)
+            return safe_nav_result if safe_nav_result
           end
 
           # Slice 7 phase 15 — RBS::Extended predicate
@@ -1020,7 +1062,8 @@ module Rigor
         end
 
         def simple_dispatch_name?(name)
-          %i[nil? ! is_a? kind_of? instance_of? == != === =~ key? has_key? empty? any? none?].include?(name)
+          %i[nil? ! is_a? kind_of? instance_of? == != === =~ key? has_key? empty? any? none?
+             respond_to?].include?(name)
         end
 
         def dispatch_call_simple(node, scope, name)
@@ -1033,9 +1076,62 @@ module Rigor
           when :=~ then analyse_regex_match_predicate(node, scope)
           when :key?, :has_key? then analyse_key_presence_predicate(node, scope)
           when :empty?, :any?, :none? then analyse_array_emptiness_predicate(node, scope, name)
+          when :respond_to? then analyse_respond_to_predicate(node, scope)
           end
         end
 
+        # T3 (template-corpora survey) — `recv.respond_to?(sym)` truthy
+        # edge narrows `recv` non-nil. `nil.respond_to?(m)` is `false`
+        # for every method `m` that `NilClass` does not define, so a
+        # truthy `respond_to?` proves the receiver was not `nil` UNLESS
+        # the queried symbol is one of `NilClass`'s own methods (`:to_s`,
+        # `:inspect`, `:nil?`, …) — `nil` DOES respond to those, so the
+        # truthy edge admits a nil receiver and we narrow nothing.
+        #
+        # Conservative floor: narrow only on a literal `Symbol`/`String`
+        # argument resolved against the RBS environment; a non-literal
+        # symbol, a missing argument, or a symbol that IS in `NilClass`'s
+        # method set declines. The falsey edge is always the no-op
+        # ("does not respond" proves little about the receiver's type).
+        # Narrowing-only: it removes the `nil` constituent and never
+        # promotes a non-nil type.
+        def analyse_respond_to_predicate(node, scope)
+          return nil if node.block
+          return nil if node.arguments.nil? || node.arguments.arguments.size != 1
+
+          sym = static_hash_key(node.arguments.arguments.first)
+          return nil if sym.nil?
+          return nil if nilclass_method?(sym, scope)
+
+          reader, writer = emptiness_receiver_accessors(node.receiver)
+          return nil if reader.nil?
+
+          current = scope.public_send(reader, node.receiver.name)
+          return nil if current.nil?
+
+          non_nil = narrow_non_nil(current)
+          return nil if non_nil.equal?(current)
+
+          [scope.public_send(writer, node.receiver.name, non_nil), scope]
+        end
+
+        # True when `nil` responds to `sym` — i.e. `NilClass` (own,
+        # inherited Kernel/BasicObject) defines an instance method named
+        # `sym`. Resolved against the RBS environment; when the lookup
+        # is unavailable the answer is conservatively `true` (decline to
+        # narrow) so an unknown environment never manufactures a false
+        # non-nil narrowing.
+        def nilclass_method?(sym, scope)
+          name = sym.respond_to?(:to_sym) ? sym.to_sym : sym
+          return true unless name.is_a?(Symbol)
+
+          !Rigor::Reflection.instance_method_definition(
+            "NilClass", name, environment: scope.environment
+          ).nil?
+        rescue StandardError
+          true
+        end
+
         # ADR-47 §4-4 (Elixir `tuple_size`/non-empty analogue) — a bare
         # `arr.empty?` / `arr.any?` / `arr.none?` (no block, no args)
         # narrows an Array-typed receiver to `non-empty-array[T]` on the
@@ -1230,8 +1326,8 @@ module Rigor
           regex_node = regex_match_literal(node.receiver, node.arguments.arguments.first)
           return nil if regex_node.nil?
 
-          group_count = count_regex_capture_groups(regex_node.unescaped)
-          regex_match_predicate_scopes(scope, group_count)
+          unconditional = unconditional_capture_groups(regex_node.unescaped)
+          regex_match_predicate_scopes(scope, unconditional)
         end
 
         def regex_match_literal(left, right)
@@ -1247,7 +1343,15 @@ module Rigor
         REGEX_MATCH_GLOBALS = %i[$~ $& $` $' $+].freeze
         private_constant :REGEX_MATCH_GLOBALS
 
-        def regex_match_predicate_scopes(scope, group_count)
+        # `unconditional` is the Set of 1-based numbered-capture
+        # indices whose group is guaranteed to participate in any
+        # successful match (no optional quantifier on the group or
+        # an ancestor, no alternation in the pattern). Those `$N`
+        # are bound to `String`; every other numbered group present
+        # in the pattern stays `String | nil` on both edges (a
+        # truthy match leaves an optional group nil at runtime), so
+        # we do not narrow it on the truthy edge.
+        def regex_match_predicate_scopes(scope, unconditional)
           string_t = Type::Combinator.nominal_of("String")
           match_data_t = Type::Combinator.nominal_of("MatchData")
           nil_t = Type::Combinator.constant_of(nil)
@@ -1262,45 +1366,127 @@ module Rigor
             truthy = truthy.with_global(name, string_t)
             falsey = falsey.with_global(name, nil_t)
           end
-          group_count.times do |i|
-            name = :"$#{i + 1}"
+          unconditional.each do |index|
+            name = :"$#{index}"
             truthy = truthy.with_global(name, string_t)
             falsey = falsey.with_global(name, nil_t)
           end
           [truthy, falsey]
         end
 
-        # Counts capture groups (numbered + named — both
-        # contribute to `$1..$N`) in a regex source. Backslash
-        # escapes are skipped; non-capturing `(?:...)`, lookahead
-        # `(?=...)` / `(?!...)`, and lookbehind `(?<=...)` /
-        # `(?<!...)` do NOT count. Named groups `(?<name>...)`
-        # DO count. The walker is intentionally light — it does
-        # not parse the regex AST, just scans char-by-char — so
-        # exotic constructs that overlap the lookaround syntax
-        # may miscount; the unsoundness is bounded (over- or
-        # under-binding a few `$N` globals) and we already accept
-        # the same shape of unsoundness for `analyse_match_write`.
-        def count_regex_capture_groups(source)
-          i = 0
-          total = 0
+        # Returns the Set of 1-based numbered-capture indices that
+        # are UNCONDITIONAL in `source`: present on every successful
+        # match because no optional quantifier (`?`, `*`, `{0,…}`)
+        # applies to the group or any ancestor group, and the
+        # pattern contains no alternation (`|`). Optional and
+        # alternation-reachable groups are excluded — at runtime `$N`
+        # is `nil` for them even when the overall match succeeds, so
+        # narrowing them to non-nil `String` would be unsound. The
+        # walker is intentionally light (char scan, not a regex-AST
+        # parse): backslash escapes are skipped; `(?:…)`, lookahead
+        # `(?=…)`/`(?!…)`, and lookbehind `(?<=…)`/`(?<!…)` do not
+        # capture; named groups `(?<name>…)` do. Conservatism is
+        # one-directional — when in doubt a group is treated as
+        # conditional (dropped from the Set), never the reverse.
+        def unconditional_capture_groups(source)
+          # `unconditional` collects every capturing index; a group is
+          # later removed (with its whole subtree) when it is optionally
+          # quantified, nested under an optional ancestor, or sits in an
+          # alternation branch. `stack` holds one frame per open group
+          # (plus a virtual root frame for the top level) as
+          # `[group_index_or_nil, descendant_indices, alternated?]`.
+          # A `|` marks the CURRENT group's frame alternated — its
+          # branches are mutually exclusive, so its descendant captures
+          # may be absent on a successful match; the group itself still
+          # participates. Closing a frame rolls its subtree up to the
+          # parent so an optional / alternated ancestor disqualifies it.
+          state = { unconditional: Set.new, stack: [[nil, [], false]], group_index: 0 }
+          pos = 0
           length = source.length
-          while i < length
-            c = source[i]
-            if c == "\\"
-              i += 2
+          while pos < length
+            chr = source[pos]
+            if chr == "\\"
+              pos += 2
               next
             end
-            if c == "("
-              if source[i + 1] == "?"
-                total += 1 if source[i + 2] == "<" && source[i + 3] != "=" && source[i + 3] != "!"
-              else
-                total += 1
-              end
+            if chr == "["
+              pos = skip_char_class(source, pos) + 1
+              next
+            end
+            scan_group_char(source, pos, chr, state)
+            pos += 1
+          end
+          # Drain the virtual root: a top-level `|` disqualifies all.
+          finalize_frame(state, state[:stack].pop, optional: false)
+          state[:unconditional]
+        end
+
+        # Updates the walk `state` at a group-relevant char during
+        # {#unconditional_capture_groups}: `(` pushes a frame, `)` pops
+        # and resolves it, `|` flags the current frame as alternated.
+        def scan_group_char(source, pos, chr, state)
+          case chr
+          when "("
+            idx = nil
+            if capturing_group?(source, pos)
+              idx = (state[:group_index] += 1)
+              state[:unconditional] << idx
             end
-            i += 1
+            state[:stack].push([idx, [], false])
+          when ")"
+            finalize_frame(state, state[:stack].pop, optional: next_quantifier_optional?(source, pos + 1))
+          when "|"
+            state[:stack].last[2] = true
+          end
+        end
+
+        # Resolves a closed (or virtual-root) group frame: its subtree is
+        # its own index plus every descendant index. The subtree is
+        # disqualified when the group is optionally quantified or its
+        # branches are alternated (only the descendants in that case —
+        # but a self subtree always keeps its own index unless optional).
+        def finalize_frame(state, frame, optional:)
+          idx, descendants, alternated = frame
+          subtree = descendants.dup
+          subtree << idx if idx
+          state[:unconditional].subtract(subtree) if optional
+          # Alternation disqualifies the branch contents (descendants),
+          # never the enclosing group itself.
+          state[:unconditional].subtract(descendants) if alternated
+          state[:stack].last && state[:stack].last[1].concat(subtree)
+        end
+
+        # True when the group whose closing paren is at `source[pos]`
+        # is followed by a quantifier that permits zero repetitions
+        # (`?`, `*`, `{0…}`). `+` and `{1,…}` do NOT make a group
+        # optional. A lazy/possessive suffix (`*?`, `*+`) is still
+        # zero-permitting on the base quantifier.
+        def next_quantifier_optional?(source, pos)
+          case source[pos]
+          when "?", "*" then true
+          when "{" then source[pos + 1] == "0"
+          else false
+          end
+        end
+
+        def capturing_group?(source, pos)
+          return true unless source[pos + 1] == "?"
+
+          # `(?<name>…)` captures; `(?<=…)`/`(?<!…)` (lookbehind) and
+          # `(?:…)`/`(?=…)`/`(?!…)` do not.
+          source[pos + 2] == "<" && source[pos + 3] != "=" && source[pos + 3] != "!"
+        end
+
+        def skip_char_class(source, start)
+          pos = start + 1
+          pos += 1 if source[pos] == "^"
+          pos += 1 if source[pos] == "]" # literal ] as first member
+          while pos < source.length
+            return pos if source[pos] == "]"
+
+            pos += source[pos] == "\\" ? 2 : 1
           end
-          total
+          pos
         end
 
         def dispatch_call_numeric(node, scope, name)
@@ -2379,6 +2565,51 @@ module Rigor
           end
         end
 
+        # Narrows a safe-navigation call's receiver (`v&.foo`) to its
+        # non-nil fragment on the truthy edge, returning `[truthy, falsey]`
+        # or nil when nothing applies (not safe-nav, opaque receiver, or
+        # already non-nil). Used standalone for a bare `v&.foo` truthy
+        # edge and as a post-pass over the existing predicate edges.
+        def analyse_safe_nav_receiver(node, scope)
+          return nil unless node.safe_navigation?
+
+          receiver = node.receiver
+          reader, writer =
+            case receiver
+            when Prism::LocalVariableReadNode then %i[local with_local]
+            when Prism::InstanceVariableReadNode then %i[ivar with_ivar]
+            else return nil
+            end
+
+          current = scope.public_send(reader, receiver.name)
+          return nil if current.nil?
+
+          non_nil = narrow_non_nil(current)
+          return nil if non_nil.equal?(current)
+
+          [scope.public_send(writer, receiver.name, non_nil), scope]
+        end
+
+        # Layers the safe-nav non-nil truthy narrowing over the edges an
+        # existing predicate path already produced, so a safe-nav string
+        # predicate (`v&.start_with?(x)`) keeps its relational fact AND
+        # proves `v` non-nil on the truthy edge. Re-runs the predicate's
+        # narrowing under the non-nil truthy scope so the fact is attached
+        # to the narrowed binding. No-op for non-safe-nav calls.
+        def apply_safe_nav_non_nil(node, scope, edges)
+          return edges unless node.safe_navigation? && edges
+
+          truthy, falsey = edges
+          safe = analyse_safe_nav_receiver(node, scope)
+          return edges unless safe
+
+          receiver = node.receiver
+          reader = receiver.is_a?(Prism::InstanceVariableReadNode) ? :ivar : :local
+          non_nil = safe.first.public_send(reader, receiver.name)
+          writer = receiver.is_a?(Prism::InstanceVariableReadNode) ? :with_ivar : :with_local
+          [truthy.public_send(writer, receiver.name, non_nil), falsey]
+        end
+
         # `a && b` short-circuits: the truthy edge is the truthy edge
         # of `b` evaluated under `a`'s truthy scope; the falsey edge
         # is the union of `a`'s falsey scope (b skipped) and `b`'s