rigortype 0.0.2 → 0.0.4

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

@@ -0,0 +1,144 @@
+# frozen_string_literal: true
+
+require_relative "../../type"
+
+module Rigor
+  module Inference
+    module MethodDispatcher
+      # IO / File support — the pure-path-manipulation tier.
+      #
+      # File and IO carry a lot of side-effecting surface (filesystem
+      # reads, descriptor mutations, line iteration) the analyzer
+      # cannot fold. Several `File` class methods, however, are
+      # functions over their path-string arguments — they do NOT
+      # touch the filesystem and do NOT depend on the current
+      # working directory.
+      #
+      # Folding them is platform-sensitive: every recognised method
+      # ([:basename, :dirname, :extname, :join, :split,
+      # :absolute_path?]) reads `File::SEPARATOR` /
+      # `File::ALT_SEPARATOR` and produces different answers on
+      # Windows vs POSIX hosts. The Ruby process running the
+      # analyzer hosts ONE platform; folding to a `Constant<String>`
+      # would silently bake that platform's answer into the
+      # analyzer's result and mis-report it on a host with a
+      # different separator policy.
+      #
+      # Default policy (`fold_platform_specific_paths == false`):
+      # decline the fold so the RBS tier answers with `Nominal[String]`
+      # / `Tuple[Nominal[String], Nominal[String]]` / `bool`. That is
+      # the platform-agnostic envelope — every concrete answer the
+      # method could legally return on any platform fits inside it.
+      # The future `non-empty-string` refinement carrier (see
+      # [imported-built-in-types.md](../../../../../docs/type-specification/imported-built-in-types.md))
+      # will tighten the basename/dirname/join cases further without
+      # leaking platform specifics; today we leave them at the
+      # nominal envelope.
+      #
+      # Opt-in policy (`fold_platform_specific_paths == true`):
+      # the analyzer trusts that its host platform matches the
+      # callers' deployment target and folds to a precise
+      # `Constant<String>`. Single-platform projects (most internal
+      # tooling, Rails apps deployed to Linux containers) can
+      # enable this in `.rigor.yml`:
+      #
+      #   fold_platform_specific_paths: true
+      #
+      # The runner reads this on startup (`Rigor::Analysis::Runner`)
+      # and writes the flag here. Tests toggle the flag explicitly.
+      #
+      # See [ADR-5 — robustness principle](../../../../../docs/adr/5-robustness-principle.md):
+      # the platform-agnostic default is clause-1 of the principle
+      # applied with the constraint that "as strict as can be
+      # *correctness-preservingly* proved" excludes Constants whose
+      # value is host-specific.
+      module FileFolding
+        # File class methods that the analyzer can fold *when the
+        # fold is platform-safe to perform*. Today every entry is
+        # platform-sensitive (every one observes `File::SEPARATOR`
+        # or `File::ALT_SEPARATOR`); the gate below requires the
+        # opt-in flag for any of them to fire.
+        FILE_PURE_CLASS_METHODS = Set[
+          :basename,
+          :dirname,
+          :extname,
+          :join,
+          :split,
+          :absolute_path?
+        ].freeze
+        private_constant :FILE_PURE_CLASS_METHODS
+
+        # Methods whose result depends on host directory-separator
+        # semantics (`/` on POSIX, `/` AND `\` on Windows, drive
+        # letters, UNC paths). Folding these would bake the
+        # analyzer-host's platform into the inferred type. The opt-
+        # in flag below controls whether to do it anyway.
+        PLATFORM_DEPENDENT_METHODS = Set[
+          :basename, :dirname, :extname, :join, :split, :absolute_path?
+        ].freeze
+        private_constant :PLATFORM_DEPENDENT_METHODS
+
+        class << self
+          # Module-global flag. The runner sets it from
+          # `Rigor::Configuration#fold_platform_specific_paths`.
+          # Tests toggle it directly.
+          attr_accessor :fold_platform_specific_paths
+        end
+        self.fold_platform_specific_paths = false
+
+        module_function
+
+        # @return [Rigor::Type, nil] folded result, or nil to defer
+        #   to the next dispatcher tier.
+        def try_dispatch(receiver:, method_name:, args:)
+          return nil unless dispatch_target?(receiver)
+          return nil unless FILE_PURE_CLASS_METHODS.include?(method_name)
+          return nil if platform_specific_skip?(method_name)
+
+          string_args = constant_string_args(args)
+          return nil if string_args.nil?
+
+          fold_class_method(method_name, string_args)
+        end
+
+        def platform_specific_skip?(method_name)
+          PLATFORM_DEPENDENT_METHODS.include?(method_name) &&
+            !FileFolding.fold_platform_specific_paths
+        end
+
+        def dispatch_target?(receiver)
+          receiver.is_a?(Type::Singleton) && receiver.class_name == "File"
+        end
+
+        def constant_string_args(args)
+          return [] if args.empty?
+          return nil unless args.all? { |arg| constant_string_arg?(arg) }
+
+          args.map { |arg| arg.value.to_s }
+        end
+
+        def constant_string_arg?(arg)
+          arg.is_a?(Type::Constant) && (arg.value.is_a?(String) || arg.value.is_a?(Symbol))
+        end
+
+        def fold_class_method(method_name, string_args)
+          result = File.public_send(method_name, *string_args)
+          wrap_result(result)
+        rescue StandardError
+          nil
+        end
+
+        def wrap_result(result)
+          case result
+          when String, true, false
+            Type::Combinator.constant_of(result)
+          when Array
+            return nil unless result.all?(String)
+
+            Type::Combinator.tuple_of(*result.map { |s| Type::Combinator.constant_of(s) })
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,215 @@
+# frozen_string_literal: true
+
+require_relative "../../type"
+
+module Rigor
+  module Inference
+    module MethodDispatcher
+      # Iterator-style block-parameter typing.
+      #
+      # Sits ahead of `RbsDispatch.block_param_types` so the precise
+      # integer bounds for `Integer#times` / `Integer#upto` /
+      # `Integer#downto` reach the block body's parameter binder.
+      # Without this tier the RBS signature for `Integer#times`
+      # widens the index to `Nominal[Integer]`, dropping every
+      # bound the receiver carries.
+      #
+      # Each rule mirrors Ruby's actual iteration semantics:
+      #
+      # - `n.times { |i| … }` yields `i ∈ [0, n-1]` when `n > 0`,
+      #   nothing otherwise. The block-param type is therefore
+      #   `int<0, n-1>` for a `Constant<Integer>` receiver,
+      #   `int<0, upper-1>` for a finite `IntegerRange`, and
+      #   `non_negative_int` for any unbounded-above shape.
+      # - `a.upto(b) { |i| … }` yields `i ∈ [a, b]` when `a <= b`.
+      #   Lower bound from the receiver, upper bound from the
+      #   argument.
+      # - `a.downto(b) { |i| … }` yields the same domain `[b, a]`,
+      #   just iterated in reverse. Lower bound from the
+      #   argument, upper bound from the receiver.
+      module IteratorDispatch # rubocop:disable Metrics/ModuleLength
+        module_function
+
+        # @return [Array<Rigor::Type>, nil] block-param types, or
+        #   nil to fall through to the next tier.
+        def block_param_types(receiver:, method_name:, args:)
+          case method_name
+          when :times then times_block_params(receiver)
+          when :upto  then upto_block_params(receiver, args.first)
+          when :downto then downto_block_params(receiver, args.first)
+          when :each_with_index then each_with_index_block_params(receiver)
+          end
+        end
+
+        def times_block_params(receiver)
+          return nil unless integer_rooted?(receiver)
+
+          upper = upper_bound_of(receiver)
+          return [Type::Combinator.non_negative_int] unless upper.is_a?(Integer)
+          return [Type::Combinator.non_negative_int] unless upper.positive?
+
+          [build_index_range(0, upper - 1)]
+        end
+
+        def upto_block_params(receiver, end_arg)
+          return nil unless integer_rooted?(receiver) && integer_rooted?(end_arg)
+
+          [build_index_range(lower_bound_of(receiver), upper_bound_of(end_arg))]
+        end
+
+        def downto_block_params(receiver, end_arg)
+          return nil unless integer_rooted?(receiver) && integer_rooted?(end_arg)
+
+          [build_index_range(lower_bound_of(end_arg), upper_bound_of(receiver))]
+        end
+
+        # Generalised iterator: every Enumerable-shaped collection
+        # in v0.0.4 yields `(element, index)` where the index is
+        # always `non-negative-int`. The element comes from the
+        # receiver's shape:
+        #
+        # - `Array[T]` / `Set[T]` / `Range[T]`              → T
+        # - `Tuple[A, B, C]`                                → A | B | C
+        #   (empty tuple cannot iterate, but we conservatively
+        #   fall through to RBS so a missing rule never throws)
+        # - `Hash[K, V]` / `HashShape{...}`                 → Tuple[K, V]
+        #   (Ruby yields `[key, value]` pairs as the element)
+        # - `Constant<Array>` / `Constant<Range>` / `Constant<Set>`
+        #                                                   → corresponding Constant element
+        #
+        # Receivers we cannot project (Top, Dynamic, unknown
+        # nominals, IO, …) decline so the RBS tier still answers
+        # — its element type is correct, only the index would
+        # widen to plain Integer.
+        def each_with_index_block_params(receiver)
+          element = element_type_of(receiver)
+          return nil if element.nil?
+
+          [element, Type::Combinator.non_negative_int]
+        end
+
+        ELEMENT_BY_NOMINAL = {
+          "Array" => :nominal_unary_element,
+          "Set" => :nominal_unary_element,
+          "Range" => :nominal_unary_element,
+          "Hash" => :nominal_hash_pair_element
+        }.freeze
+        private_constant :ELEMENT_BY_NOMINAL
+
+        def element_type_of(receiver)
+          case receiver
+          when Type::Tuple then tuple_element(receiver)
+          when Type::HashShape then hash_shape_pair_element(receiver)
+          when Type::Nominal then nominal_element(receiver)
+          when Type::Constant then constant_element(receiver)
+          end
+        end
+
+        def tuple_element(tuple)
+          return nil if tuple.elements.empty?
+          return tuple.elements.first if tuple.elements.size == 1
+
+          Type::Combinator.union(*tuple.elements)
+        end
+
+        def hash_shape_pair_element(shape)
+          return nil if shape.pairs.empty?
+
+          key = Type::Combinator.union(*shape.pairs.keys.map { |k| Type::Combinator.constant_of(k) })
+          value = Type::Combinator.union(*shape.pairs.values)
+          Type::Combinator.tuple_of(key, value)
+        end
+
+        def nominal_element(nominal)
+          handler = ELEMENT_BY_NOMINAL[nominal.class_name]
+          return nil unless handler
+
+          send(handler, nominal)
+        end
+
+        def nominal_unary_element(nominal)
+          nominal.type_args.first
+        end
+
+        def nominal_hash_pair_element(nominal)
+          key, value = nominal.type_args
+          return nil if key.nil? || value.nil?
+
+          Type::Combinator.tuple_of(key, value)
+        end
+
+        def constant_element(constant)
+          case constant.value
+          when Array
+            return nil if constant.value.empty?
+
+            Type::Combinator.union(*constant.value.map { |v| Type::Combinator.constant_of(v) })
+          when Range
+            range_constant_element(constant.value)
+          end
+        end
+
+        def range_constant_element(range)
+          beg = range.begin
+          en  = range.end
+          return Type::Combinator.constant_of(beg) if beg.is_a?(Integer) && beg == en
+
+          if beg.is_a?(Integer) && en.is_a?(Integer)
+            upper = range.exclude_end? ? en - 1 : en
+            return build_index_range(beg, upper)
+          end
+
+          # Mixed / non-integer ranges decline: the dispatcher
+          # falls through to RBS's element-type answer.
+          nil
+        end
+
+        # `Constant<Integer>`, `IntegerRange`, and `Nominal[Integer]`
+        # all participate. Non-integer types (Float, String, …) and
+        # `Top`/`Dynamic` decline so the RBS tier answers.
+        def integer_rooted?(type)
+          case type
+          when Type::Constant then type.value.is_a?(Integer)
+          when Type::IntegerRange then true
+          when Type::Nominal then type.class_name == "Integer" && type.type_args.empty?
+          else false
+          end
+        end
+
+        def lower_bound_of(type)
+          case type
+          when Type::Constant then type.value
+          when Type::IntegerRange then type.min
+          when Type::Nominal then Type::IntegerRange::NEG_INFINITY
+          end
+        end
+
+        def upper_bound_of(type)
+          case type
+          when Type::Constant then type.value
+          when Type::IntegerRange then type.max
+          when Type::Nominal then Type::IntegerRange::POS_INFINITY
+          end
+        end
+
+        # Builds a `Constant`/`IntegerRange` from possibly-symbolic
+        # bounds. Vacuous ranges (lower > upper, indicating the
+        # iterator does not fire) collapse to `non_negative_int` so
+        # the body still type-checks against a sensible binding.
+        def build_index_range(lower, upper)
+          return Type::Combinator.non_negative_int if vacuous_range?(lower, upper)
+          return Type::Combinator.constant_of(lower) if lower.is_a?(Integer) && lower == upper
+
+          Type::Combinator.integer_range(lower, upper)
+        end
+
+        def vacuous_range?(lower, upper)
+          return false if lower == Type::IntegerRange::NEG_INFINITY
+          return false if upper == Type::IntegerRange::POS_INFINITY
+
+          lower > upper
+        end
+      end
+    end
+  end
+end

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

@@ -53,13 +53,22 @@ module Rigor
           overloads = method_definition.method_types
           return nil if overloads.empty?
 
+          # `rigor:v1:param: <name> <refinement>` annotations on
+          # this method override the RBS-declared parameter type
+          # at the matching name. The map is consumed inside
+          # `accepts_param?` so overload selection sees the
+          # tighter type when filtering candidates by argument
+          # compatibility.
+          param_overrides = RbsExtended.param_type_override_map(method_definition)
+
           match = find_matching_overload(
             overloads,
             arg_types: arg_types,
             self_type: self_type,
             instance_type: instance_type,
             type_vars: type_vars,
-            block_required: block_required
+            block_required: block_required,
+            param_overrides: param_overrides
           )
           return match if match
           return overloads.find { |mt| overload_has_block?(mt) } if block_required
@@ -76,7 +85,8 @@ module Rigor
           private
 
           # rubocop:disable Metrics/ParameterLists
-          def find_matching_overload(overloads, arg_types:, self_type:, instance_type:, type_vars:, block_required:)
+          def find_matching_overload(overloads, arg_types:, self_type:, instance_type:, type_vars:, block_required:,
+                                     param_overrides:)
             overloads.find do |method_type|
               next false if block_required && !OverloadSelector.overload_has_block?(method_type)
 
@@ -85,13 +95,15 @@ module Rigor
                 arg_types,
                 self_type: self_type,
                 instance_type: instance_type,
-                type_vars: type_vars
+                type_vars: type_vars,
+                param_overrides: param_overrides
               )
             end
           end
           # rubocop:enable Metrics/ParameterLists
 
-          def matches?(method_type, arg_types, self_type:, instance_type:, type_vars:)
+          # rubocop:disable Metrics/ParameterLists
+          def matches?(method_type, arg_types, self_type:, instance_type:, type_vars:, param_overrides:)
             return false if method_type.respond_to?(:type_params) && rejects_keyword_required?(method_type)
 
             fun = method_type.type
@@ -104,10 +116,12 @@ module Rigor
                 arg,
                 self_type: self_type,
                 instance_type: instance_type,
-                type_vars: type_vars
+                type_vars: type_vars,
+                param_overrides: param_overrides
               )
             end
           end
+          # rubocop:enable Metrics/ParameterLists
 
           # Slice 4 phase 2c does not pass keyword arguments through the
           # call site (caller passes only positional `arg_types`). An
@@ -152,8 +166,9 @@ module Rigor
             head
           end
 
-          def accepts_param?(param, arg, self_type:, instance_type:, type_vars:)
-            param_type = RbsTypeTranslator.translate(
+          # rubocop:disable Metrics/ParameterLists
+          def accepts_param?(param, arg, self_type:, instance_type:, type_vars:, param_overrides:)
+            param_type = param_overrides[param.name] || RbsTypeTranslator.translate(
               param.type,
               self_type: self_type,
               instance_type: instance_type,
@@ -162,6 +177,7 @@ module Rigor
             result = param_type.accepts(arg, mode: :gradual)
             result.yes? || result.maybe?
           end
+          # rubocop:enable Metrics/ParameterLists
         end
       end
     end

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

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "../../type"
+require_relative "../../rbs_extended"
 require_relative "../rbs_type_translator"
 require_relative "overload_selector"
 
@@ -247,6 +248,9 @@ module Rigor
 
           # rubocop:disable Metrics/ParameterLists
           def translate_return_type(method_definition, class_name:, kind:, args:, type_vars:, block_type:)
+            override = RbsExtended.read_return_type_override(method_definition)
+            return override if override
+
             instance_type = Type::Combinator.nominal_of(class_name)
             self_type =
               case kind