rigortype 0.1.6 → 0.1.8

data/lib/rigor/inference/narrowing.rb

@@ -950,7 +950,7 @@ module Rigor
         end
 
         def simple_dispatch_name?(name)
-          %i[nil? ! is_a? kind_of? instance_of? == != ===].include?(name)
+          %i[nil? ! is_a? kind_of? instance_of? == != === =~].include?(name)
         end
 
         def dispatch_call_simple(node, scope, name)
@@ -960,9 +960,111 @@ module Rigor
           when :instance_of? then analyse_class_predicate(node, scope, exact: true)
           when :==, :!= then analyse_equality_predicate(node, scope, equality: name)
           when :=== then analyse_case_equality_predicate(node, scope)
+          when :=~ then analyse_regex_match_predicate(node, scope)
           end
         end
 
+        # Survey item (b): `/regex/ =~ str` and `str =~ /regex/`
+        # bind the regex match-data globals on each edge.
+        #
+        # - Truthy edge (`=~` returned an Integer position — the
+        #   match succeeded): `$~` to `Nominal[MatchData]`; `$&`
+        #   and `$1..$N` (where N is the number of capture groups
+        #   in the regex source) to `Nominal[String]`. This is the
+        #   same optimistic-narrowing shape the existing
+        #   `analyse_match_write` uses for named captures inside
+        #   `if /(?<x>...)/ =~ str` — optional groups in the
+        #   regex source (`(\d+)?`) would bind `$N` to `nil` at
+        #   runtime, but the floor here matches the common idiom
+        #   (required captures) and lets `unless /(\d+)/ =~ s;
+        #   raise; end; $1.to_i` resolve cleanly.
+        # - Falsey edge (`=~` returned nil — no match): `$~` and
+        #   every numbered / back-reference global bound to
+        #   `Constant<nil>`.
+        #
+        # Returns nil (no narrowing) when the receiver / argument
+        # pair does not include a `RegularExpressionNode` literal
+        # we can count.
+        def analyse_regex_match_predicate(node, scope)
+          return nil if node.arguments.nil?
+          return nil unless node.arguments.arguments.size == 1
+
+          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)
+        end
+
+        def regex_match_literal(left, right)
+          return left if left.is_a?(Prism::RegularExpressionNode)
+          return right if right.is_a?(Prism::RegularExpressionNode)
+
+          nil
+        end
+
+        # Curated set of back-reference globals bound by every
+        # `=~`. Numbered references (`$1..$N`) are handled
+        # separately because N depends on the regex source.
+        REGEX_MATCH_GLOBALS = %i[$~ $& $` $' $+].freeze
+        private_constant :REGEX_MATCH_GLOBALS
+
+        def regex_match_predicate_scopes(scope, group_count)
+          string_t = Type::Combinator.nominal_of("String")
+          match_data_t = Type::Combinator.nominal_of("MatchData")
+          nil_t = Type::Combinator.constant_of(nil)
+
+          truthy = scope
+          falsey = scope
+          truthy = truthy.with_global(:$~, match_data_t)
+          falsey = falsey.with_global(:$~, nil_t)
+          REGEX_MATCH_GLOBALS.each do |name|
+            next if name == :$~
+
+            truthy = truthy.with_global(name, string_t)
+            falsey = falsey.with_global(name, nil_t)
+          end
+          group_count.times do |i|
+            name = :"$#{i + 1}"
+            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
+          length = source.length
+          while i < length
+            c = source[i]
+            if c == "\\"
+              i += 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
+            end
+            i += 1
+          end
+          total
+        end
+
         def dispatch_call_numeric(node, scope, name)
           if COMPARISON_OPERATORS.include?(name)
             analyse_comparison_predicate(node, scope, comparator: name)

data/lib/rigor/inference/scope_indexer.rb

@@ -109,12 +109,11 @@ module Rigor
         discovered_methods = build_discovered_methods(root)
         seeded_scope = seeded_scope.with_discovered_methods(discovered_methods)
 
-        # v0.0.2 #5 — also record the def node itself for
-        # instance methods so the engine can re-type the body
-        # when a call site dispatches against a user-defined
-        # method without an RBS sig.
-        discovered_def_nodes = build_discovered_def_nodes(root)
-        seeded_scope = seeded_scope.with_discovered_def_nodes(discovered_def_nodes)
+        # v0.0.2 #5 + ADR-24 slice 2 — record per-instance-method
+        # def nodes, the class -> superclass map, and the
+        # class/module -> included-modules map, each merged under
+        # the cross-file pre-pass seed (see below).
+        seeded_scope = merge_project_method_indexes(seeded_scope, default_scope, root)
 
         # v0.1.2 — per-class table of method visibilities
         # (`:public` / `:private` / `:protected`). The
@@ -134,6 +133,31 @@ module Rigor
         table
       end
 
+      # v0.0.2 #5 + ADR-24 slice 2 — seeds the three
+      # project-method indexes onto `seeded_scope`: the
+      # per-instance-method def-node table, the class ->
+      # superclass map, and the class/module -> included-modules
+      # map. Each per-file table is merged UNDER the cross-file
+      # `discovered_def_index_for_paths` seed carried on
+      # `default_scope` — same-file declarations win per entry,
+      # the cross-file seed supplies sibling-file ancestors.
+      def merge_project_method_indexes(seeded_scope, default_scope, root)
+        def_nodes = default_scope.discovered_def_nodes.merge(
+          build_discovered_def_nodes(root)
+        ) { |_class, cross_file, per_file| cross_file.merge(per_file) }
+        superclasses = default_scope.discovered_superclasses.merge(
+          build_discovered_superclasses(root)
+        )
+        includes = default_scope.discovered_includes.merge(
+          build_discovered_includes(root)
+        ) { |_class, cross_file, per_file| (cross_file + per_file).uniq }
+
+        seeded_scope
+          .with_discovered_def_nodes(def_nodes)
+          .with_discovered_superclasses(superclasses)
+          .with_discovered_includes(includes)
+      end
+
       # Slice 7 phase 2. Builds the class-level ivar accumulator
       # by walking every `Prism::ClassNode` / `Prism::ModuleNode`
       # body, descending into each nested `Prism::DefNode`, and
@@ -343,11 +367,26 @@ module Rigor
         unless qualified_prefix.empty?
           body_scope = body_scope.with_self_type(Type::Combinator.singleton_of(qualified_prefix.join("::")))
         end
-        rvalue_type = body_scope.type_of(node.value)
+        rvalue_type = meta_new_constant_type(node, full) || body_scope.type_of(node.value)
         existing = accumulator[full]
         accumulator[full] = existing ? Type::Combinator.union(existing, rvalue_type) : rvalue_type
       end
 
+      # Survey item (e): when the rvalue is a recognised
+      # `Module.new do ... end` / `Class.new do ... end` /
+      # `Struct.new(*sym) do ... end` / `Data.define(*sym) do
+      # ... end` form, type the named constant as
+      # `Singleton[<full>]` so the discovered-method table
+      # registered under `full` becomes reachable through
+      # singleton-side dispatch (`Const.[]=` etc.). Returns nil
+      # for non-meta-new rvalues so the caller falls back to the
+      # default `body_scope.type_of(node.value)` shape.
+      def meta_new_constant_type(node, full)
+        return nil unless meta_new_block_body(node)
+
+        Type::Combinator.singleton_of(full)
+      end
+
       # Slice 7 phase 12 — in-source method discovery pre-pass.
       # Walks every class/module body and records the methods
       # introduced via `Prism::DefNode` (instance + singleton)
@@ -429,16 +468,22 @@ module Rigor
       # v0.1.2 — when a `Const = Data.define(*sym) do ... end`
       # / `Const = Struct.new(*sym) do ... end` constant write
       # carries a block, the block body holds method overrides
-      # whose canonical class is `Const`. Returns the block body
-      # node (a `Prism::StatementsNode`) when the rvalue
-      # matches; nil otherwise. Used by `walk_methods` /
-      # `walk_def_nodes` to push `Const` onto the qualified
-      # prefix before recursing.
+      # whose canonical class is `Const`. Survey item (e) extended
+      # the recognition to `Const = Module.new do ... end` and
+      # `Const = Class.new(?super) do ... end` — the
+      # ADR-16 Tier A "block-as-method" idiom at constant-write
+      # position. Returns the block body node (a
+      # `Prism::StatementsNode`) when the rvalue matches; nil
+      # otherwise. Used by `walk_methods` / `walk_def_nodes` to
+      # push `Const` onto the qualified prefix before recursing.
       def meta_new_block_body(node)
         return nil unless node.is_a?(Prism::ConstantWriteNode)
 
         rvalue = node.value
-        return nil unless data_define_call?(rvalue) || struct_new_call?(rvalue)
+        return nil unless data_define_call?(rvalue) ||
+                          struct_new_call?(rvalue) ||
+                          module_new_call?(rvalue) ||
+                          class_new_call?(rvalue)
 
         rvalue.block&.body
       end
@@ -559,6 +604,94 @@ module Rigor
         accumulator[class_name][def_node.name] = def_node
       end
 
+      # ADR-24 slice 2 — per-class table mapping a fully
+      # qualified user class to its superclass name AS WRITTEN
+      # at the `class Foo < Bar` declaration. Only constant
+      # superclasses are recorded (`class Foo < Struct.new(...)`
+      # and other non-constant superclasses produce no entry).
+      # The as-written name is resolved to a qualified class at
+      # the call site against the subclass's lexical nesting —
+      # see `ExpressionTyper#resolve_ancestor_class_name`.
+      def build_discovered_superclasses(root)
+        accumulator = {}
+        walk_class_superclasses(root, [], accumulator)
+        accumulator.freeze
+      end
+
+      def walk_class_superclasses(node, qualified_prefix, accumulator)
+        return unless node.is_a?(Prism::Node)
+
+        case node
+        when Prism::ClassNode
+          name = qualified_name_for(node.constant_path)
+          if name
+            full = (qualified_prefix + [name]).join("::")
+            superclass = node.superclass && qualified_name_for(node.superclass)
+            accumulator[full] = superclass if superclass
+            walk_class_superclasses(node.body, qualified_prefix + [name], accumulator) if node.body
+            return
+          end
+        when Prism::ModuleNode
+          name = qualified_name_for(node.constant_path)
+          if name
+            walk_class_superclasses(node.body, qualified_prefix + [name], accumulator) if node.body
+            return
+          end
+        end
+
+        node.compact_child_nodes.each do |child|
+          walk_class_superclasses(child, qualified_prefix, accumulator)
+        end
+      end
+
+      MIXIN_CALL_NAMES = %i[include prepend].freeze
+
+      # ADR-24 slice 2 — per-class/module table mapping a fully
+      # qualified user class or module to the list of module
+      # names it `include`s / `prepend`s, AS WRITTEN at the
+      # mixin call (`include Foo` / `include Foo::Bar`). Only
+      # constant arguments are recorded; dynamic mixins
+      # (`include some_method`) produce no entry. `prepend` is
+      # bucketed with `include` — both contribute instance
+      # methods to the ancestor chain. `extend` is NOT tracked
+      # (it adds singleton methods; ADR-24 slice 2 resolves the
+      # instance-side chain).
+      def build_discovered_includes(root)
+        accumulator = {}
+        walk_class_includes(root, [], nil, accumulator)
+        accumulator.transform_values { |mods| mods.uniq.freeze }.freeze
+      end
+
+      def walk_class_includes(node, qualified_prefix, current_class, accumulator)
+        return unless node.is_a?(Prism::Node)
+
+        case node
+        when Prism::ClassNode, Prism::ModuleNode
+          name = qualified_name_for(node.constant_path)
+          if name
+            full = (qualified_prefix + [name]).join("::")
+            walk_class_includes(node.body, qualified_prefix + [name], full, accumulator) if node.body
+            return
+          end
+        when Prism::CallNode
+          record_mixin_call(node, current_class, accumulator)
+        end
+
+        node.compact_child_nodes.each do |child|
+          walk_class_includes(child, qualified_prefix, current_class, accumulator)
+        end
+      end
+
+      def record_mixin_call(node, current_class, accumulator)
+        return unless current_class && node.receiver.nil?
+        return unless MIXIN_CALL_NAMES.include?(node.name)
+
+        node.arguments&.arguments&.each do |arg|
+          mod = qualified_name_for(arg)
+          (accumulator[current_class] ||= []) << mod if mod
+        end
+      end
+
       VISIBILITY_MODIFIERS = %i[public private protected].freeze
 
       # v0.1.2 — per-class method-visibility table for the
@@ -824,6 +957,44 @@ module Rigor
         accumulator.freeze
       end
 
+      # ADR-24 slice 2 — cross-file companion to
+      # `discovered_classes_for_paths`. Walks every project
+      # file once and returns both the merged
+      # `discovered_def_nodes` table (a class reopened across
+      # files has its method tables merged) and the merged
+      # class -> superclass-name map. The engine consults these
+      # so an implicit-self call inside a subclass resolves
+      # against a superclass `def` declared in a sibling file
+      # (`Mastodon::CLI::Accounts` calling a helper defined in
+      # `Mastodon::CLI::Base`).
+      #
+      # @param paths  [Array<String>] project file paths.
+      # @param buffer [Rigor::Analysis::BufferBinding, nil]
+      # @return [Hash{Symbol => Hash}] `{ def_nodes:, superclasses: }`
+      def discovered_def_index_for_paths(paths, buffer: nil)
+        def_nodes = {}
+        superclasses = {}
+        includes = {}
+        paths.each do |path|
+          physical = buffer ? buffer.resolve(path) : path
+          root = Prism.parse(File.read(physical), filepath: path).value
+          build_discovered_def_nodes(root).each do |class_name, methods|
+            (def_nodes[class_name] ||= {}).merge!(methods)
+          end
+          superclasses.merge!(build_discovered_superclasses(root))
+          build_discovered_includes(root).each do |class_name, mods|
+            includes[class_name] = ((includes[class_name] || []) + mods).uniq
+          end
+        rescue StandardError
+          # Skip files that fail to parse or read; the per-file
+          # analyzer surfaces the parse error separately.
+          next
+        end
+        def_nodes.each_value(&:freeze)
+        includes.each_value(&:freeze)
+        { def_nodes: def_nodes.freeze, superclasses: superclasses.freeze, includes: includes.freeze }
+      end
+
       # Class-only variant of `record_declarations` — descends
       # into nested module bodies (so `module Foo; class Bar`
       # registers `Foo::Bar`) but never registers the module
@@ -946,6 +1117,31 @@ module Rigor
         positional.all?(Prism::SymbolNode)
       end
 
+      # Recognises `Module.new` and `Module.new(&block)` /
+      # `Module.new do ... end` at constant-write rvalue
+      # position. The block body is the anonymous module's
+      # `module_eval` body; defs inside it bind methods on the
+      # named constant (`Const = Module.new do ...; def foo; ...; end; end`).
+      # Arguments are NOT inspected because `Module.new` accepts
+      # no positionals — Ruby raises ArgumentError if any are
+      # passed — so a malformed call falls through the walker
+      # without affecting analysis.
+      def module_new_call?(node)
+        meta_call_with_name?(node, :Module, :new)
+      end
+
+      # Recognises `Class.new`, `Class.new(super_class)`, and the
+      # block form `Class.new { ... }`. Like `module_new_call?`,
+      # the block body is walked as the anonymous class's body.
+      # The optional `super_class` positional is accepted but does
+      # NOT route through `ancestor` discovery in this slice — the
+      # synthesised class still answers method lookups via its
+      # own body's defs, mirroring how `Struct.new` / `Data.define`
+      # are handled.
+      def class_new_call?(node)
+        meta_call_with_name?(node, :Class, :new)
+      end
+
       def meta_call_with_name?(node, receiver_name, method_name)
         return false unless node.is_a?(Prism::CallNode)
         return false unless node.name == method_name

data/lib/rigor/inference/statement_evaluator.rb

@@ -358,9 +358,9 @@ module Rigor
         # is the falsey edge of the predicate (subsequent
         # statements observe the predicate-was-false world).
         return [Type::Combinator.union(then_type, else_type), falsey_scope] \
-          if branch_unconditionally_exits?(node.statements) && node.subsequent.nil?
+          if branch_terminates?(node.statements, then_type) && node.subsequent.nil?
         return [Type::Combinator.union(then_type, else_type), truthy_scope] \
-          if branch_unconditionally_exits?(node.subsequent) && node.statements
+          if branch_terminates?(node.subsequent, else_type) && node.statements
 
         [
           Type::Combinator.union(then_type, else_type),
@@ -385,9 +385,9 @@ module Rigor
         # `if`: when the body unconditionally exits and there
         # is no else, the post-scope is the truthy edge.
         return [Type::Combinator.union(then_type, else_type), truthy_scope] \
-          if branch_unconditionally_exits?(node.statements) && node.else_clause.nil?
+          if branch_terminates?(node.statements, then_type) && node.else_clause.nil?
         return [Type::Combinator.union(then_type, else_type), falsey_scope] \
-          if branch_unconditionally_exits?(node.else_clause) && node.statements
+          if branch_terminates?(node.else_clause, else_type) && node.statements
 
         [
           Type::Combinator.union(then_type, else_type),
@@ -497,13 +497,25 @@ module Rigor
       def eval_begin(node)
         primary_type, primary_scope = eval_begin_primary(node)
         rescue_chain = collect_rescue_chain_results(node.rescue_clause, scope)
-
-        if rescue_chain.empty?
+        # Rescue arms whose body unconditionally exits (`return`,
+        # `next`, `break`, `raise`, `throw`, `exit`, `abort`,
+        # `fail`) contribute neither a type fragment NOR a scope
+        # to the post-begin flow — control left the `begin` via
+        # that arm. Mirrors the `eval_if` / `eval_unless` /
+        # `eval_and_or` early-return narrowing. Without this
+        # filter, a `rescue ... return` on a local bound only in
+        # the primary body nil-injects that local across the
+        # join, defeating the rescue arm's whole point of guaranteeing
+        # the primary local is in scope for downstream statements.
+        live_rescues = rescue_chain.reject { |_pair, arm_node| branch_unconditionally_exits?(arm_node.statements) }
+                                   .map(&:first)
+
+        if live_rescues.empty?
           exit_type = primary_type
           exit_scope = primary_scope
         else
-          exit_type = Type::Combinator.union(primary_type, *rescue_chain.map(&:first))
-          exit_scope = reduce_scopes_with_nil_injection([primary_scope, *rescue_chain.map(&:last)])
+          exit_type = Type::Combinator.union(primary_type, *live_rescues.map(&:first))
+          exit_scope = reduce_scopes_with_nil_injection([primary_scope, *live_rescues.map(&:last)])
         end
 
         if node.ensure_clause
@@ -540,7 +552,7 @@ module Rigor
         current = rescue_node
         while current
           rescue_scope = bind_rescue_reference(current, entry_scope)
-          results << eval_branch_or_nil(current.statements, rescue_scope)
+          results << [eval_branch_or_nil(current.statements, rescue_scope), current]
           current = current.subsequent
         end
         results
@@ -696,11 +708,36 @@ module Rigor
       # edge-aware: `a && b` can only produce the falsey fragment of
       # `a` when the RHS is skipped, while `a || b` can only produce
       # the truthy fragment of `a` when the RHS is skipped.
+      #
+      # When the RHS is a terminating branch — it `raise`s /
+      # `return`s / `throw`s / `exit`s / `break`s / `next`s, OR its
+      # inferred type is `Bot` (ADR-24 WD6: a divergent helper such
+      # as `a or fail_with_message(...)`, recognised via
+      # `branch_terminates?`) — the post-OR / post-AND scope is the
+      # LHS-skipped edge alone: `a or raise` only survives when `a`
+      # was truthy, so subsequent statements observe `a` narrowed to
+      # its truthy fragment; the symmetric `a and raise` survives
+      # only when `a` was falsey. Same shape as the `eval_if` /
+      # `eval_unless` early-return narrowing.
       def eval_and_or(node)
         left_type, left_scope = sub_eval(node.left, scope)
         truthy_left, falsey_left = Narrowing.predicate_scopes(node.left, left_scope)
         rhs_entry = node.is_a?(Prism::AndNode) ? truthy_left : falsey_left
         right_type, right_scope = sub_eval(node.right, rhs_entry)
+
+        if branch_terminates?(node.right, right_type)
+          # Control never reaches any statement after `a or raise`
+          # via the RHS edge — the RHS scope is discarded.
+          surviving_type =
+            if node.is_a?(Prism::AndNode)
+              Narrowing.narrow_falsey(left_type)
+            else
+              Narrowing.narrow_truthy(left_type)
+            end
+          surviving_scope = node.is_a?(Prism::AndNode) ? falsey_left : truthy_left
+          return [surviving_type, surviving_scope]
+        end
+
         skipped_type =
           if node.is_a?(Prism::AndNode)
             Narrowing.narrow_falsey(left_type)
@@ -1106,7 +1143,16 @@ module Rigor
       # narrowing logic via `Narrowing.narrow_for_fact` so the
       # predicate / assert / plugin paths all converge on the
       # same hierarchy-aware narrowing rules.
+      #
+      # v0.1.8 Pillar 2 Slice 1 added the `:local` target_kind
+      # branch so plugins recognising bespoke call shapes
+      # (`expect(x).to be_a(T)`) can directly narrow a named
+      # local in the surrounding scope, bypassing the
+      # parameter-name lookup that requires an authoritative RBS
+      # sig on the called method (which RSpec matchers lack).
       def apply_post_return_fact(fact, call_node, current_scope, method_def)
+        return apply_local_post_return_fact(fact, current_scope) if fact.target_kind == :local
+
         target_node = fact_target_node(fact, call_node, method_def)
         return apply_self_post_return_fact(fact, target_node, current_scope) if fact.target_kind == :self
         return current_scope unless target_node.is_a?(Prism::LocalVariableReadNode)
@@ -1119,6 +1165,21 @@ module Rigor
         current_scope.with_local(local_name, narrowed)
       end
 
+      # v0.1.8 Pillar 2 Slice 1 — narrows the named local directly
+      # without consulting the call node's argument list. The fact's
+      # `target_name` is the local-variable name as written in
+      # source. Silently no-ops when the local is unbound in the
+      # current scope (the plugin's named local may have already
+      # gone out of scope when the contribution fires).
+      def apply_local_post_return_fact(fact, current_scope)
+        local_name = fact.target_name
+        current_type = current_scope.local(local_name)
+        return current_scope if current_type.nil?
+
+        narrowed = Narrowing.narrow_for_fact(current_type, fact, current_scope.environment)
+        current_scope.with_local(local_name, narrowed)
+      end
+
       # v0.1.1 Track 1 slice 3 — `assert self is T` post-return
       # narrowing for the four supported receiver shapes (mirrors
       # `Narrowing#apply_self_fact`).
@@ -1423,7 +1484,7 @@ module Rigor
       # ScopeIndexer-populated declaration overrides
       # (`Prism::ConstantReadNode` for `module Foo` headers, etc.)
       # remain reachable from inside nested bodies.
-      def build_fresh_body_scope
+      def build_fresh_body_scope # rubocop:disable Metrics/AbcSize
         Scope.empty(environment: scope.environment)
              .with_declared_types(scope.declared_types)
              .with_discovered_classes(scope.discovered_classes)
@@ -1432,6 +1493,9 @@ module Rigor
              .with_class_cvars(scope.class_cvars)
              .with_program_globals(scope.program_globals)
              .with_discovered_methods(scope.discovered_methods)
+             .with_discovered_def_nodes(scope.discovered_def_nodes)
+             .with_discovered_superclasses(scope.discovered_superclasses)
+             .with_discovered_includes(scope.discovered_includes)
              .with_discovered_method_visibilities(scope.discovered_method_visibilities)
       end
 
@@ -1631,6 +1695,23 @@ module Rigor
         end
       end
 
+      # ADR-24 WD6 / slice 3 — generalised terminating-branch
+      # detection. `branch_unconditionally_exits?` recognises a
+      # branch SYNTACTICALLY (return / next / break / a call
+      # named raise / throw / exit / abort / fail). A branch
+      # whose *inferred type is `Bot`* also terminates — it
+      # cannot produce a value, so control never falls through
+      # it — regardless of how it is spelled. The canonical
+      # case is a resolved guard helper (`fail_with_message(...)`)
+      # whose body always raises: ADR-24 slice 1 types the call
+      # `bot`, and this OR-test makes `helper(...) if x.nil?`
+      # narrow exactly like `raise ... if x.nil?`. The branch
+      # type is already computed by `eval_if` / `eval_unless`.
+      def branch_terminates?(branch_node, branch_type)
+        branch_unconditionally_exits?(branch_node) ||
+          branch_type.is_a?(Type::Bot)
+      end
+
       def eval_branch_or_nil(branch_node, branch_scope)
         return [Type::Combinator.constant_of(nil), branch_scope] if branch_node.nil?
 

data/lib/rigor/plugin/macro/heredoc_template.rb

@@ -73,8 +73,8 @@ module Rigor
       # This file ships the value class only. Slice 2b wires the
       # pre-pass that scans Tier C call sites + the
       # `SyntheticMethodIndex` the dispatcher consults; slice 2c
-      # authors `examples/rigor-dry-struct/` and
-      # `examples/rigor-dry-types/` as the worked consumers.
+      # authors `plugins/rigor-dry-struct/` and
+      # `plugins/rigor-dry-types/` as the worked consumers.
       class HeredocTemplate
         NAME_PLACEHOLDER = "\#{name}"
 

data/lib/rigor/plugin/macro/trait_registry.rb

@@ -83,7 +83,7 @@ module Rigor
       # This file ships the value class only. Slice 3b wires the
       # scanner that walks Tier B call sites + the per-method
       # explosion via `SyntheticMethodIndex`; slice 3c authors
-      # `examples/rigor-devise/` model side as the worked consumer.
+      # `plugins/rigor-devise/` model side as the worked consumer.
       class TraitRegistry
         REST_POSITION = :rest