rigortype 0.0.1

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

@@ -0,0 +1,336 @@
+# frozen_string_literal: true
+
+require_relative "../../type"
+
+module Rigor
+  module Inference
+    module MethodDispatcher
+      # Slice 5 phase 2 shape-aware dispatch tier. Sits between
+      # {ConstantFolding} (which folds Constant-on-Constant arithmetic)
+      # and {RbsDispatch} (which projects shape carriers to their
+      # underlying nominal and resolves return types through RBS).
+      #
+      # The tier resolves a curated catalogue of element-access
+      # methods on `Rigor::Type::Tuple` and `Rigor::Type::HashShape`
+      # receivers, returning the *precise* member type rather than the
+      # projected `Array#[]` / `Hash#fetch` result. When the dispatch
+      # cannot prove which element will be returned (non-static key,
+      # out-of-range index, multi-arg `dig`, ...) the tier returns
+      # `nil` so the surrounding pipeline falls through to
+      # {RbsDispatch} and the projection-based answer.
+      #
+      # Catalogue (Slice 5 phase 2):
+      #
+      # - Tuple#`first`, Tuple#`last`, Tuple#`size`/`length`/`count`:
+      #   no-arg, no-block.
+      # - Tuple#`[]`, Tuple#`fetch` with a single `Constant[Integer]`
+      #   argument inside the tuple's bounds (negative indices are
+      #   normalised by length). Tuple#`[]` also handles static
+      #   Range and start-length slices, returning a sliced Tuple or
+      #   `Constant[nil]` for statically nil slices.
+      # - Tuple#`dig` with a chain of `Constant[Integer]` /
+      #   `Constant[Symbol|String]` arguments (Slice 5 phase 2 sub-
+      #   phase 2). Each step recurses through the resolved member; a
+      #   missing key/index along the chain collapses to `Constant[nil]`
+      #   so the carrier surfaces through downstream narrowing. A
+      #   non-shape intermediate falls through to the projection
+      #   answer.
+      # - HashShape#`size`/`length`: no-arg.
+      # - HashShape#`[]`, HashShape#`fetch`, HashShape#`dig` with a
+      #   single `Constant[Symbol|String]` argument matching one of
+      #   the declared keys. `[]` and `dig` resolve missing keys to
+      #   `Constant[nil]`; `fetch` (no default, no block) falls through
+      #   on a miss because Ruby would raise `KeyError` and the
+      #   analyzer prefers the conservative projection answer.
+      # - HashShape#`dig` with multi-arg chains (Slice 5 phase 2 sub-
+      #   phase 2). Same chaining semantics as Tuple#`dig`.
+      # - HashShape#`values_at` with a list of `Constant[Symbol|String]`
+      #   arguments (Slice 5 phase 2 sub-phase 2). The result is a
+      #   `Tuple` whose elements are the per-key values
+      #   (`Constant[nil]` for missing keys, mirroring Ruby's runtime
+      #   behaviour).
+      #
+      # Methods that this tier does NOT yet handle (they fall through):
+      #
+      # - Iteration methods that bind block parameters (`each`, `map`,
+      #   `select`, ...). Those land alongside the BlockNode-aware
+      #   scope builder.
+      # - Tuple/HashShape mutation methods. These land with the future
+      #   effect model so read-only entries and mutation invalidation
+      #   have one place to report diagnostics.
+      #
+      # See docs/internal-spec/inference-engine.md (Slice 5 phase 2)
+      # and docs/adr/4-type-inference-engine.md for the slice
+      # rationale.
+      # rubocop:disable Metrics/ClassLength, Metrics/ModuleLength
+      module ShapeDispatch
+        module_function
+
+        TUPLE_HANDLERS = {
+          first: :tuple_first,
+          last: :tuple_last,
+          size: :tuple_size,
+          length: :tuple_size,
+          count: :tuple_size,
+          :[] => :tuple_index,
+          fetch: :tuple_index,
+          dig: :tuple_dig
+        }.freeze
+
+        HASH_SHAPE_HANDLERS = {
+          size: :hash_size,
+          length: :hash_size,
+          :[] => :hash_lookup,
+          fetch: :hash_lookup,
+          dig: :hash_dig,
+          values_at: :hash_values_at
+        }.freeze
+
+        # @return [Rigor::Type, nil] the precise element/value type, or
+        #   `nil` to defer to the next dispatcher tier.
+        def try_dispatch(receiver:, method_name:, args:)
+          args ||= []
+          case receiver
+          when Type::Tuple then dispatch_tuple(receiver, method_name, args)
+          when Type::HashShape then dispatch_hash_shape(receiver, method_name, args)
+          end
+        end
+
+        class << self
+          private
+
+          def dispatch_tuple(tuple, method_name, args)
+            handler = TUPLE_HANDLERS[method_name]
+            return nil unless handler
+
+            send(handler, tuple, method_name, args)
+          end
+
+          def dispatch_hash_shape(shape, method_name, args)
+            handler = HASH_SHAPE_HANDLERS[method_name]
+            return nil unless handler
+
+            send(handler, shape, method_name, args)
+          end
+
+          def tuple_first(tuple, _method_name, args)
+            return nil unless args.empty?
+            return Type::Combinator.constant_of(nil) if tuple.elements.empty?
+
+            tuple.elements.first
+          end
+
+          def tuple_last(tuple, _method_name, args)
+            return nil unless args.empty?
+            return Type::Combinator.constant_of(nil) if tuple.elements.empty?
+
+            tuple.elements.last
+          end
+
+          def tuple_size(tuple, _method_name, args)
+            return nil unless args.empty?
+
+            Type::Combinator.constant_of(tuple.elements.size)
+          end
+
+          # `tuple[i]`, `tuple[range]`, `tuple[start, length]`, and
+          # `tuple.fetch(i)` for static arguments. Out-of-range single
+          # indices still fall through because the same handler serves
+          # `fetch`, while statically nil slices can be represented
+          # precisely for `[]`.
+          def tuple_index(tuple, method_name, args)
+            case args.size
+            when 1 then tuple_single_index(tuple, method_name, args.first)
+            when 2 then tuple_start_length_slice(tuple, method_name, args)
+            end
+          end
+
+          def tuple_single_index(tuple, method_name, arg)
+            return nil unless arg.is_a?(Type::Constant)
+
+            return tuple_range_slice(tuple, arg.value) if method_name == :[] && arg.value.is_a?(Range)
+            return nil unless arg.value.is_a?(Integer)
+
+            idx = normalise_index(arg.value, tuple.elements.size)
+            return nil unless idx
+
+            tuple.elements[idx]
+          end
+
+          def tuple_start_length_slice(tuple, method_name, args)
+            return nil unless method_name == :[]
+
+            start, length = args
+            return nil unless start.is_a?(Type::Constant) && length.is_a?(Type::Constant)
+            return nil unless start.value.is_a?(Integer) && length.value.is_a?(Integer)
+
+            tuple_slice(tuple.elements[start.value, length.value])
+          end
+
+          def tuple_range_slice(tuple, range)
+            return nil unless integer_range?(range)
+
+            tuple_slice(tuple.elements[range])
+          end
+
+          def tuple_slice(elements)
+            return Type::Combinator.constant_of(nil) if elements.nil?
+
+            Type::Combinator.tuple_of(*elements)
+          end
+
+          def integer_range?(range)
+            [range.begin, range.end].all? { |endpoint| endpoint.nil? || endpoint.is_a?(Integer) }
+          end
+
+          # `tuple.dig(i, ...)` with a chain of static keys/indices.
+          # Each step recurses through the resolved member: a Tuple
+          # member dispatches `dig` on the remaining args, a HashShape
+          # member does the same, and a `Constant[nil]` member ends
+          # the chain at `Constant[nil]` (matching Ruby's `Array#dig`
+          # short-circuit on nil). Anything else along the chain
+          # falls through to the projection answer so the analyzer
+          # never invents a value it cannot prove.
+          def tuple_dig(tuple, _method_name, args)
+            return nil if args.empty?
+
+            step = tuple_dig_step(tuple, args.first)
+            return nil if step.nil?
+
+            chain_dig(step, args.drop(1))
+          end
+
+          def tuple_dig_step(tuple, arg)
+            return nil unless arg.is_a?(Type::Constant)
+            return nil unless arg.value.is_a?(Integer)
+
+            idx = normalise_index(arg.value, tuple.elements.size)
+            return Type::Combinator.constant_of(nil) if idx.nil?
+
+            tuple.elements[idx]
+          end
+
+          # Returns the in-bounds non-negative index, or nil when the
+          # raw index falls outside `[-size, size)`.
+          def normalise_index(raw, size)
+            adjusted = raw.negative? ? raw + size : raw
+            return nil if adjusted.negative? || adjusted >= size
+
+            adjusted
+          end
+
+          def hash_size(shape, _method_name, args)
+            return nil unless args.empty?
+            return nil unless shape.closed?
+            return nil unless shape.optional_keys.empty?
+
+            Type::Combinator.constant_of(shape.pairs.size)
+          end
+
+          # `shape[k]` and `shape.fetch(k)` for a static symbol/string
+          # key. Missing-key resolution depends on the method:
+          #
+          # - `[]` returns `nil` at runtime; we surface `Constant[nil]`
+          #   so the carrier is visible to downstream narrowing.
+          # - `fetch` (no default, no block) raises `KeyError`; we let
+          #   the projection answer apply because the runtime would
+          #   not produce a value.
+          def hash_lookup(shape, method_name, args)
+            return nil unless args.size == 1
+
+            step = hash_dig_step(shape, args.first)
+            return nil if step.nil?
+            return nil if method_name == :fetch && optional_key_step?(shape, args.first)
+            return step unless missing_key_step?(shape, args.first)
+
+            return step if method_name == :[]
+
+            nil
+          end
+
+          # `shape.dig(:a, :b, ...)` with a chain of static keys.
+          # Same recursion semantics as Tuple#`dig`: each step looks
+          # up the key, then `chain_dig` continues with the
+          # resolved value as the new receiver. Missing keys collapse
+          # to `Constant[nil]` (Ruby's `Hash#dig` short-circuits on
+          # nil too).
+          def hash_dig(shape, _method_name, args)
+            return nil if args.empty?
+
+            step = hash_dig_step(shape, args.first)
+            return nil if step.nil?
+
+            chain_dig(step, args.drop(1))
+          end
+
+          # Returns the per-step value type for a HashShape lookup
+          # (or `Constant[nil]` for a known-missing key). Returns
+          # `nil` when the argument is not a static symbol/string
+          # so the caller can fall through to the projection answer.
+          def hash_dig_step(shape, arg)
+            return nil unless arg.is_a?(Type::Constant)
+
+            key = arg.value
+            return nil unless key.is_a?(Symbol) || key.is_a?(String)
+
+            if shape.pairs.key?(key)
+              value = shape.pairs[key]
+              return value unless shape.optional_key?(key)
+
+              return Type::Combinator.union(value, Type::Combinator.constant_of(nil))
+            end
+
+            Type::Combinator.constant_of(nil)
+          end
+
+          def optional_key_step?(shape, arg)
+            return false unless arg.is_a?(Type::Constant)
+
+            shape.optional_key?(arg.value)
+          end
+
+          def missing_key_step?(shape, arg)
+            return false unless arg.is_a?(Type::Constant)
+
+            !shape.pairs.key?(arg.value)
+          end
+
+          # `shape.values_at(:a, :b, ...)` with a list of static
+          # keys. Returns a `Tuple` whose per-position values are
+          # the per-key value types (`Constant[nil]` for missing
+          # keys, mirroring Ruby's runtime behaviour). Falls through
+          # when any argument is not a static symbol/string.
+          def hash_values_at(shape, _method_name, args)
+            return nil if args.empty?
+
+            values = []
+            args.each do |arg|
+              step = hash_dig_step(shape, arg)
+              return nil if step.nil?
+
+              values << step
+            end
+
+            Type::Combinator.tuple_of(*values)
+          end
+
+          # Continues a `dig` chain after the first step. Tuple and
+          # HashShape members re-dispatch into the catalogue;
+          # `Constant[nil]` short-circuits the chain (Hash#dig and
+          # Array#dig do the same at runtime); anything else falls
+          # through so the projection answer applies.
+          def chain_dig(receiver, args)
+            return receiver if args.empty?
+
+            case receiver
+            when Type::Tuple then tuple_dig(receiver, :dig, args)
+            when Type::HashShape then hash_dig(receiver, :dig, args)
+            when Type::Constant then receiver.value.nil? ? Type::Combinator.constant_of(nil) : nil
+            end
+          end
+        end
+      end
+      # rubocop:enable Metrics/ClassLength, Metrics/ModuleLength
+    end
+  end
+end

data/lib/rigor/inference/method_dispatcher.rb

@@ -0,0 +1,213 @@
+# frozen_string_literal: true
+
+require_relative "../type"
+require_relative "method_dispatcher/constant_folding"
+require_relative "method_dispatcher/shape_dispatch"
+require_relative "method_dispatcher/rbs_dispatch"
+
+module Rigor
+  module Inference
+    # Coordinates method dispatch for the inference engine.
+    #
+    # Given `(receiver_type, method_name, arg_types, block_type, environment)`,
+    # the dispatcher returns the inferred result type or `nil` when no
+    # rule matches. `nil` is a deliberately blunt "I don't know" signal:
+    # callers (today only `ExpressionTyper`) own the fail-soft fallback
+    # and decide whether to record a `FallbackTracer` event.
+    #
+    # Tiers (in order):
+    #
+    # 1. {ConstantFolding}: executes the Ruby operation directly when
+    #    the receiver and argument are `Constant` carriers and the
+    #    method is on the curated whitelist. Slice 2.
+    # 2. {ShapeDispatch}: returns the precise element/value type for a
+    #    curated catalogue of `Tuple`/`HashShape` element-access
+    #    methods (`first`, `last`, `[]` with a static integer/key,
+    #    `fetch`, `dig`, `size`/`length`/`count`). Slice 5 phase 2.
+    # 3. {RbsDispatch}: looks up the receiver's class in the RBS
+    #    environment carried by the scope and translates the method's
+    #    return type into a Rigor::Type. Slice 4.
+    #
+    # `ShapeDispatch` deliberately runs *above* {RbsDispatch} so the
+    # precise per-position/per-key answer wins over the projected
+    # `Array#[]`/`Hash#fetch` answer; it falls through (`nil`) when
+    # the call cannot be proved against the static shape, in which
+    # case the projection answer from {RbsDispatch} applies.
+    #
+    # The dispatcher's public signature reserves space for `block_type:`
+    # and ADR-2 plugin extensions (later slices), so call sites added
+    # now do not have to be rewritten when those tiers arrive.
+    module MethodDispatcher
+      module_function
+
+      # @param receiver_type [Rigor::Type, nil] type of the receiver expression, or
+      #   `nil` for an implicit-self call.
+      # @param method_name [Symbol]
+      # @param arg_types [Array<Rigor::Type>] positional argument types.
+      # @param block_type [Rigor::Type, nil] inferred return type of the
+      #   accompanying `do ... end` / `{ ... }` block (Slice 6 phase C
+      #   sub-phase 2). When non-nil, the dispatcher prefers an
+      #   overload that declares a block, and binds the method's
+      #   block-return type variable to `block_type` so a return type
+      #   like `Array[U]` resolves to `Array[block_type]`.
+      # @param environment [Rigor::Environment, nil] required for
+      #   RBS-backed dispatch; when nil only constant folding can fire.
+      # @return [Rigor::Type, nil] inferred result type, or `nil` for "no rule".
+      def dispatch(receiver_type:, method_name:, arg_types:, block_type: nil, environment: nil)
+        return nil if receiver_type.nil?
+
+        meta_result = try_meta_introspection(receiver_type, method_name)
+        return meta_result if meta_result
+
+        constant_result = ConstantFolding.try_fold(
+          receiver: receiver_type,
+          method_name: method_name,
+          args: arg_types
+        )
+        return constant_result if constant_result
+
+        shape_result = ShapeDispatch.try_dispatch(
+          receiver: receiver_type,
+          method_name: method_name,
+          args: arg_types
+        )
+        return shape_result if shape_result
+
+        rbs_result = RbsDispatch.try_dispatch(
+          receiver: receiver_type,
+          method_name: method_name,
+          args: arg_types,
+          environment: environment,
+          block_type: block_type
+        )
+        return rbs_result if rbs_result
+
+        # Slice 7 phase 10 — user-class ancestor fallback. When
+        # the receiver is `Nominal[T]` or `Singleton[T]` for a
+        # class not in the RBS environment (typically a
+        # user-defined class), retry the dispatch against the
+        # implicit ancestor: `Nominal[Object]` for instance
+        # receivers and `Singleton[Object]` for singleton
+        # receivers. This resolves Kernel intrinsics
+        # (`require`, `raise`, `puts`, ...) and Module/Class
+        # introspection (`attr_reader`, `private`, ...) on
+        # user classes without requiring the user to author
+        # their own RBS.
+        try_user_class_fallback(receiver_type, method_name, arg_types, environment, block_type)
+      end
+
+      def try_user_class_fallback(receiver_type, method_name, arg_types, environment, block_type)
+        return nil if environment.nil?
+
+        fallback_receiver = user_class_fallback_receiver(receiver_type, environment)
+        return nil if fallback_receiver.nil?
+
+        RbsDispatch.try_dispatch(
+          receiver: fallback_receiver,
+          method_name: method_name,
+          args: arg_types,
+          environment: environment,
+          block_type: block_type
+        )
+      end
+
+      def user_class_fallback_receiver(receiver_type, environment)
+        loader = environment.rbs_loader
+        return nil if loader.nil?
+
+        case receiver_type
+        when Type::Nominal
+          return nil if loader.class_known?(receiver_type.class_name)
+
+          environment.nominal_for_name("Object")
+        when Type::Singleton
+          return nil if loader.class_known?(receiver_type.class_name)
+
+          environment.singleton_for_name("Class")
+        end
+      end
+
+      # Slice 7 phase 8 — meta-introspection shortcuts. The
+      # default `Object#class` RBS return type is `Class`, but
+      # for a receiver of known nominal identity we can do
+      # better: `instance_of(Foo).class` is `Singleton[Foo]`
+      # (the class object itself), which downstream dispatch
+      # uses to resolve `self.class.some_class_method`. The
+      # same logic answers `Foo.class` as `Singleton[Class]`
+      # (deliberate; calling `.class` on a class object yields
+      # `Class`, the metaclass). We also special-case `is_a?`-
+      # adjacent calls and the trivial `instance_of?(self)`
+      # later as the rule catalogue grows; for now only `class`
+      # is handled.
+      def try_meta_introspection(receiver_type, method_name)
+        case method_name
+        when :class then meta_class(receiver_type)
+        when :new then meta_new(receiver_type)
+        end
+      end
+
+      def meta_class(receiver_type)
+        case receiver_type
+        when Type::Nominal then Type::Combinator.singleton_of(receiver_type.class_name)
+        when Type::Constant then constant_metaclass(receiver_type.value)
+        end
+      end
+
+      # `Singleton[Foo].new` returns `Nominal[Foo]` (a fresh
+      # instance), regardless of whether Foo is in RBS. This
+      # short-circuits the Class.new generic-`instance`
+      # plumbing for user classes, so a discovered-class
+      # `ScanAccumulator.new` types as `Nominal[ScanAccumulator]`
+      # rather than `Class`.
+      def meta_new(receiver_type)
+        return nil unless receiver_type.is_a?(Type::Singleton)
+
+        Type::Combinator.nominal_of(receiver_type.class_name)
+      end
+
+      CONSTANT_METACLASSES = {
+        Integer => "Integer", Float => "Float", String => "String",
+        Symbol => "Symbol", Range => "Range",
+        TrueClass => "TrueClass", FalseClass => "FalseClass",
+        NilClass => "NilClass"
+      }.freeze
+      private_constant :CONSTANT_METACLASSES
+
+      def constant_metaclass(value)
+        CONSTANT_METACLASSES.each do |klass, name|
+          return Type::Combinator.singleton_of(name) if value.is_a?(klass)
+        end
+        nil
+      end
+
+      # Returns the positional block parameter types declared by the
+      # receiving method's selected RBS overload, translated into
+      # `Rigor::Type`. Used by the StatementEvaluator's CallNode
+      # handler to bind block parameter names before evaluating the
+      # block body.
+      #
+      # The probe is best-effort: it returns an empty array whenever
+      # the receiver, environment, method definition, or selected
+      # overload does not provide statically declared block parameter
+      # types. Callers MUST treat the empty array as "no information";
+      # the binder falls back to `Dynamic[Top]` for every parameter
+      # slot in that case.
+      #
+      # @param receiver_type [Rigor::Type, nil]
+      # @param method_name [Symbol]
+      # @param arg_types [Array<Rigor::Type>]
+      # @param environment [Rigor::Environment, nil]
+      # @return [Array<Rigor::Type>]
+      def expected_block_param_types(receiver_type:, method_name:, arg_types:, environment: nil)
+        return [] if receiver_type.nil?
+
+        RbsDispatch.block_param_types(
+          receiver: receiver_type,
+          method_name: method_name,
+          args: arg_types,
+          environment: environment
+        )
+      end
+    end
+  end
+end