rigortype 0.1.17 → 0.1.19

data/lib/rigor/inference/flow_tracer.rb

@@ -0,0 +1,180 @@
+# frozen_string_literal: true
+
+module Rigor
+  module Inference
+    # Thread-local event recorder behind `rigor trace`: while a block runs
+    # under {record}, the inference engine emits a flat, ordered event
+    # stream describing HOW it typed the program — expression enter/result
+    # pairs, scope binds, union formation, and method-dispatch outcomes.
+    # The CLI replays that stream as a terminal animation (or dumps it as
+    # JSON); the engine itself never reads the events back, so recording
+    # is purely observational and MUST NOT change any inferred type.
+    #
+    # Modelled on {Analysis::DependencyRecorder}: thread-local state, a
+    # module-level activation count so the disabled fast path ({active?})
+    # is a plain integer read, and a frozen snapshot for consumers. The
+    # instrumented hot paths (`ExpressionTyper#type_of`,
+    # `Scope#with_local`, `Type::Combinator.union`,
+    # `MethodDispatcher.dispatch`) each guard their emit behind {active?},
+    # so a normal (non-tracing) run pays one integer comparison.
+    module FlowTracer
+      KEY = :__rigor_flow_tracer__
+      private_constant :KEY
+
+      # One animation-relevant moment.
+      #
+      # kind     :enter | :result | :bind | :union | :dispatch
+      # depth    expression-recursion depth at emit time (0 = statement level)
+      # location frozen Hash with :start_line/:start_column/:end_line/
+      #          :end_column/:start_offset/:end_offset, or nil. Events
+      #          without a node of their own (:bind, :union) inherit the
+      #          innermost in-flight expression node's location so the
+      #          replayer can still highlight the source being evaluated.
+      # stack    frozen Array of short node-class names, outermost first
+      # data     frozen kind-specific Hash (types pre-rendered as Strings
+      #          via `describe(:short)` so events serialise to JSON as-is)
+      Event = Data.define(:kind, :depth, :location, :stack, :data)
+
+      # Mutable per-thread accumulator; only ever touched by the thread
+      # that activated it, so no locking is needed on the emit path.
+      class Recorder
+        attr_reader :events
+
+        def initialize
+          @events = []
+          @stack = []
+        end
+
+        # Brackets one `ExpressionTyper#type_of` recursion: emits :enter,
+        # runs the real inference, emits :result with the inferred type,
+        # and returns the type unchanged.
+        def node(node)
+          location = location_of(node)
+          name = short_name(node.class)
+          emit(:enter, location: location, data: { node: name })
+          @stack.push(node)
+          result = nil
+          begin
+            result = yield
+          ensure
+            @stack.pop
+          end
+          emit(:result, location: location, data: { node: name, type: FlowTracer.describe(result) })
+          result
+        end
+
+        def emit(kind, location: nil, data: {})
+          @events << Event.new(
+            kind: kind,
+            depth: @stack.size,
+            location: (location || current_location)&.freeze,
+            stack: @stack.map { |n| short_name(n.class) }.freeze,
+            data: data.freeze
+          )
+        end
+
+        private
+
+        def current_location
+          location_of(@stack.last)
+        end
+
+        def location_of(node)
+          return nil unless node.respond_to?(:location) && node.location
+
+          loc = node.location
+          {
+            start_line: loc.start_line, start_column: loc.start_column,
+            end_line: loc.end_line, end_column: loc.end_column,
+            start_offset: loc.start_offset, end_offset: loc.end_offset
+          }
+        end
+
+        def short_name(klass)
+          klass.name.to_s.split("::").last
+        end
+      end
+
+      @active_count = 0
+      @mutex = Mutex.new
+
+      module_function
+
+      # Activates recording on the current thread for the duration of the
+      # block and returns the frozen event list. Nests safely; restores
+      # the previous recorder on exit.
+      def record
+        previous = Thread.current[KEY]
+        recorder = Recorder.new
+        Thread.current[KEY] = recorder
+        @mutex.synchronize { @active_count += 1 }
+        yield
+        recorder.events.freeze
+      ensure
+        Thread.current[KEY] = previous
+        @mutex.synchronize { @active_count -= 1 }
+      end
+
+      # Plain integer read (GVL-atomic) — the disabled fast path.
+      def active?
+        @active_count.positive?
+      end
+
+      # Brackets one expression-typing recursion. Falls through to the
+      # bare block when the current thread is not recording (another
+      # thread may have flipped {active?}).
+      def trace_node(node, &)
+        recorder = Thread.current[KEY]
+        return yield unless recorder
+
+        recorder.node(node, &)
+      end
+
+      # `Scope#with_local` — the moment a local enters the scope.
+      def bind(name, type)
+        Thread.current[KEY]&.emit(:bind, data: { name: name.to_s, type: describe(type) })
+      end
+
+      # `Type::Combinator.union` — the moment branch types merge
+      # (including degenerate collapses like `1 | 1 → 1`).
+      def union(members, result)
+        Thread.current[KEY]&.emit(
+          :union,
+          data: { members: members.map { |m| describe(m) }.freeze, type: describe(result) }
+        )
+      end
+
+      # `MethodDispatcher.dispatch` — resolution or the fail-soft `nil`
+      # ("no rule matched"; the caller will widen to `Dynamic[Top]`).
+      def dispatch(receiver:, method_name:, args:, result:, location: nil)
+        recorder = Thread.current[KEY]
+        return unless recorder
+
+        recorder.emit(
+          :dispatch,
+          location: location && location_hash(location),
+          data: {
+            receiver: describe(receiver), method: method_name.to_s,
+            args: args.map { |a| describe(a) }.freeze,
+            type: result && describe(result), resolved: !result.nil?
+          }
+        )
+      end
+
+      def describe(type)
+        return "nil" if type.nil?
+        return type.describe(:short) if type.respond_to?(:describe)
+
+        type.inspect
+      end
+
+      def location_hash(loc)
+        {
+          start_line: loc.start_line, start_column: loc.start_column,
+          end_line: loc.end_line, end_column: loc.end_column,
+          start_offset: loc.start_offset, end_offset: loc.end_offset
+        }
+      end
+    end
+  end
+end

data/lib/rigor/inference/macro_block_self_type.rb

@@ -17,7 +17,7 @@ module Rigor
     #   `MyApp.get(...)` call);
     # - the underlying class `X` equals or inherits from the
     #   entry's `receiver_constraint`;
-    # - the call's method name is in the entry's `verbs`.
+    # - the call's method name is in the entry's `method_names`.
     #
     # On a match the helper returns the **instance** type of
     # the receiver class (`Nominal[X]`) — the narrowed
@@ -51,11 +51,16 @@ module Rigor
         receiver_class_name = singleton_receiver_class_name(receiver_type)
         return nil if receiver_class_name.nil?
 
-        verb = call_node.name
-        registry.plugins.each do |plugin|
-          plugin.manifest.block_as_methods.each do |entry| # rigor:disable undefined-method
-            return instance_type_for(receiver_class_name, environment) if matches?(entry, verb, receiver_class_name,
-                                                                                   environment)
+        # ADR-52 WD1 — the verb-keyed table compiled at registry build
+        # replaces the per-call plugins × block_as_methods linear scan.
+        # Entries arrive in (plugin registration, declaration) order, so
+        # the first ancestry match below is the same entry the previous
+        # walk returned; the method-name membership the old `matches?` checked
+        # is guaranteed by the table key.
+        entries = registry.contribution_index.block_entries_for(call_node.name)
+        entries.each do |entry|
+          if receiver_class_inherits_from?(receiver_class_name, entry.receiver_constraint, environment)
+            return instance_type_for(receiver_class_name, environment)
           end
         end
         nil
@@ -73,12 +78,6 @@ module Rigor
         receiver_type.class_name
       end
 
-      def matches?(entry, verb, receiver_class_name, environment)
-        return false unless entry.verbs.include?(verb)
-
-        receiver_class_inherits_from?(receiver_class_name, entry.receiver_constraint, environment)
-      end
-
       def receiver_class_inherits_from?(class_name, constraint, environment)
         return true if class_name == constraint
 

data/lib/rigor/inference/method_dispatcher/array_to_h_folding.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require_relative "../../type"
+
+module Rigor
+  module Inference
+    module MethodDispatcher
+      # `Array#to_h { |x| [k, v] }` (and the no-block-pair tuple form's
+      # block sibling) return-type fold.
+      #
+      # `Enumerable#to_h` with a block maps every element to a
+      # `[key, value]` pair and collects them into a Hash. When the
+      # block's inferred return type is a recognizable 2-element
+      # `Tuple` (`[K, V]`), this tier projects the pair into a
+      # `Hash[K, V]` nominal whose key/value parameters are the
+      # widened pair types. Without this fold the call hits the RBS
+      # generic and the block's `[K, V]` return is dropped, typing as
+      # `Hash[Dynamic[top], Dynamic[top]]`.
+      #
+      # Value-pinned constants in the pair (`Constant[2]`) are widened
+      # to their nominal (`Integer`) for the Hash parameters: the built
+      # hash holds many keys, so pinning the parameter to a single
+      # element's literal would be unsound for the aggregate. The same
+      # widening the loop-body fixpoint applies (`Combinator#
+      # widen_value_pinned`) is reused.
+      #
+      # Declines (returns `nil`, leaving today's RBS answer) when:
+      #
+      # - there is no block at the call site,
+      # - the block return type is not a 2-element `Tuple`, or
+      # - the receiver is not an Array-shaped carrier (`Tuple` or
+      #   `Array` nominal). Hash receivers keep their existing
+      #   `ShapeDispatch#hash_to_h` identity fold.
+      module ArrayToHFolding
+        module_function
+
+        def try_dispatch(context)
+          return nil unless context.method_name == :to_h
+
+          block_type = context.block_type
+          return nil unless block_type.is_a?(Type::Tuple)
+          return nil unless block_type.elements.size == 2
+          return nil unless array_shaped?(context.receiver)
+
+          key = Type::Combinator.widen_value_pinned(block_type.elements[0])
+          value = Type::Combinator.widen_value_pinned(block_type.elements[1])
+          Type::Combinator.nominal_of("Hash", type_args: [key, value])
+        end
+
+        def array_shaped?(receiver)
+          case receiver
+          when Type::Tuple then true
+          when Type::Nominal then receiver.class_name == "Array"
+          else false
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rigor/inference/method_dispatcher/constant_folding.rb

@@ -226,13 +226,54 @@ module Rigor
           case type
           when Type::Constant then [type.value]
           when Type::Union
-            return nil unless type.members.all?(Type::Constant)
-
-            type.members.map(&:value)
+            return type.members.map(&:value) if type.members.all?(Type::Constant)
+
+            # A union that mixes `Constant<Integer>` and `IntegerRange`
+            # members (e.g. an accumulator's running fixpoint assumption
+            # `1 | int<1, 6>`) folds as the bounding interval. The
+            # range-arithmetic path (`try_fold_binary_range`) then keeps
+            # the result an `IntegerRange` instead of bailing to Dynamic.
+            union_integer_bounds(type)
           when Type::IntegerRange then type
           end
         end
 
+        # Returns the bounding `IntegerRange` over a union whose members
+        # are each an Integer `Constant` or an `IntegerRange`; `nil`
+        # otherwise (a Float constant or any non-numeric member declines,
+        # so precision is never silently lost).
+        def union_integer_bounds(union)
+          lowers = []
+          uppers = []
+          union.members.each do |member|
+            case member
+            when Type::Constant
+              return nil unless member.value.is_a?(Integer)
+
+              lowers << member.value
+              uppers << member.value
+            when Type::IntegerRange
+              lowers << member.lower
+              uppers << member.upper
+            else
+              return nil
+            end
+          end
+          # `IntegerRange#lower`/`#upper` surface an unbounded edge as
+          # `±Float::INFINITY`; `integer_range` wants the `±∞` *sentinel*,
+          # so map the extremum back.
+          Type::Combinator.integer_range(infinity_to_sentinel(lowers.min),
+                                         infinity_to_sentinel(uppers.max))
+        end
+
+        def infinity_to_sentinel(bound)
+          case bound
+          when -Float::INFINITY then Type::IntegerRange::NEG_INFINITY
+          when Float::INFINITY then Type::IntegerRange::POS_INFINITY
+          else bound
+          end
+        end
+
         def try_fold_unary(set, method_name)
           case set
           when Array              then try_fold_unary_set(set, method_name)
@@ -1265,17 +1306,16 @@ module Rigor
           end
         end
 
-        # `String#reverse` / `#swapcase` etc. produce a
-        # string the same size as the receiver; only the
-        # already-handled binary `:+` / `:*` paths can
-        # explode the output. No unary string method
-        # currently in the catalogue grows beyond the input
-        # size, so this hook is a no-op today — kept as a
-        # placeholder so future additions (e.g. `:succ` on
-        # very long strings) can be guarded without
-        # restructuring.
-        def string_unary_blow_up?(_receiver_value, _method_name)
-          false
+        # `String#reverse` / `#swapcase` / `#succ` etc. produce a string
+        # at least as large as the receiver. The binary `:+` / `:*` paths
+        # have their own `string_blow_up?` output guard; this is the unary
+        # analogue — decline to fold a unary String op whose receiver is
+        # already at or beyond `STRING_FOLD_BYTE_LIMIT`, since the folded
+        # output would be just as large and constant-materialising it buys
+        # no precision worth the bytes. Non-String receivers never blow up
+        # through a unary op, so they pass.
+        def string_unary_blow_up?(receiver_value, _method_name)
+          receiver_value.is_a?(String) && receiver_value.bytesize >= STRING_FOLD_BYTE_LIMIT
         end
 
         # Scalar / String / Symbol values fold; everything

data/lib/rigor/inference/method_dispatcher/overload_selector.rb

@@ -32,7 +32,16 @@ module Rigor
       #    matches, accept the first arity-and-gradual-accept match
       #    (the v0.1.1 behaviour). Alias / Interface / Intersection
       #    params still reach this pass, so call sites whose only
-      #    candidate IS an alias-typed overload keep working.
+      #    candidate IS an alias-typed overload keep working. One
+      #    exclusion: an `untyped` argument does NOT gradually match
+      #    a value-pinning param (`nil` / literal types — carriers
+      #    that admit only specific values). Those overloads carry
+      #    value-precise returns (`Kernel#Array: (nil) -> []`,
+      #    `Regexp#=~: (nil) -> nil`) that would otherwise win purely
+      #    by list position and inject false constants into the flow;
+      #    they remain selectable when the argument PROVES the value
+      #    (strict pass) or when no other overload matches (step 4's
+      #    fallback picks the first overload regardless).
       # 4. If no overload matches at all, fall back to
       #    `method_types.first` so existing call sites keep their
       #    phase 1 / 2b behavior. This preserves the fail-soft
@@ -393,9 +402,32 @@ module Rigor
               instance_type: instance_type,
               type_vars: type_vars
             )
+            # An `untyped` arg gradually accepts against every param,
+            # so a value-pinning param would be "matched" with zero
+            # evidence and its value-precise return (`(nil) -> []`)
+            # would beat broader overloads purely by list position.
+            # Decline the pair; only the strict pass (where the arg
+            # proves the value) or the final first-overload fallback
+            # may select such an overload. (Pass 1 already skips
+            # untyped args entirely, so this only engages pass 2.)
+            return false if untyped_arg?(arg) && value_pinning?(param_type)
+
             result = param_type.accepts(arg, mode: :gradual)
             result.yes? || result.maybe?
           end
+
+          # A type that admits only specific VALUES rather than a
+          # class of values: a `Constant` carrier (RBS `nil` and
+          # literal types both translate to one) or a union made up
+          # entirely of them (`true | false`, `1 | 2`, `nil?`-style
+          # optionals of literals).
+          def value_pinning?(type)
+            case type
+            when Type::Constant then true
+            when Type::Union then type.members.all? { |member| value_pinning?(member) }
+            else false
+            end
+          end
         end
       end
     end