rigortype 0.0.2 → 0.0.3

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,113 @@
+# 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
+        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)
+          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
+
+        # `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/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

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

@@ -93,9 +93,35 @@ module Rigor
           case receiver
           when Type::Tuple then dispatch_tuple(receiver, method_name, args)
           when Type::HashShape then dispatch_hash_shape(receiver, method_name, args)
+          when Type::Nominal then dispatch_nominal_size(receiver, method_name, args)
+          when Type::Difference then dispatch_difference(receiver, method_name, args)
           end
         end
 
+        # Tightens `Array#size` / `Array#length` / `String#length` /
+        # `String#bytesize` / `Hash#size` etc. on a `Nominal` receiver
+        # from the RBS-declared `Integer` to `non_negative_int`. The
+        # tier ahead of RBS sees the more precise carrier so
+        # downstream narrowing (`if size > 0; …`) actually has a
+        # range to intersect with.
+        SIZE_RETURNING_NOMINALS = {
+          "Array" => %i[size length count],
+          "String" => %i[length size bytesize],
+          "Hash" => %i[size length count],
+          "Set" => %i[size length count],
+          "Range" => %i[size length count]
+        }.freeze
+        private_constant :SIZE_RETURNING_NOMINALS
+
+        # When the difference removes the empty value of the
+        # base type (`Constant[""]`, `Constant[0]`, an empty
+        # Tuple, an empty HashShape), `size` / `length` /
+        # `count` MUST be `positive-int` (the base's
+        # non-negative range minus the removed point's `0`),
+        # and `empty?` / `zero?` MUST be `Constant[false]`.
+        EMPTY_REMOVAL_BASES = %w[String Array Hash Set].freeze
+        private_constant :EMPTY_REMOVAL_BASES
+
         class << self
           private
 
@@ -113,6 +139,87 @@ module Rigor
             send(handler, shape, method_name, args)
           end
 
+          def dispatch_nominal_size(nominal, method_name, args)
+            return nil unless args.empty?
+
+            selectors = SIZE_RETURNING_NOMINALS[nominal.class_name]
+            return nil unless selectors&.include?(method_name)
+
+            Type::Combinator.non_negative_int
+          end
+
+          # Refinement-aware projections over a `Difference[base,
+          # removed]` receiver. When the removed value is the
+          # empty witness of the base (`Constant[""]` for
+          # String, `Tuple[]` for Array, `HashShape{}` for Hash,
+          # `Constant[0]` for Integer), the catalog tier knows:
+          #
+          #   ns.size                      # positive-int
+          #   ns.size == 0                 # Constant[false]   (via narrowing tier)
+          #   ns.empty?                    # Constant[false]
+          #   nzi.zero?                    # Constant[false]
+          #
+          # For any other base method, the difference is opaque
+          # to ShapeDispatch — we delegate to the base nominal
+          # so the size/length tier still answers the broader
+          # `non_negative_int` envelope where applicable.
+          def dispatch_difference(difference, method_name, args)
+            base = difference.base
+            return nil unless base.is_a?(Type::Nominal)
+
+            if removes_empty_witness?(difference)
+              precise = empty_removal_projection(base, method_name, args)
+              return precise if precise
+            end
+
+            dispatch_nominal_size(base, method_name, args)
+          end
+
+          EMPTY_WITNESS_PREDICATES = {
+            "String" => ->(removed) { removed.is_a?(Type::Constant) && removed.value == "" },
+            "Integer" => lambda { |removed|
+              removed.is_a?(Type::Constant) && removed.value.is_a?(Integer) && removed.value.zero?
+            },
+            "Array" => ->(removed) { removed.is_a?(Type::Tuple) && removed.elements.empty? },
+            "Hash" => ->(removed) { removed.is_a?(Type::HashShape) && removed.pairs.empty? }
+          }.freeze
+          private_constant :EMPTY_WITNESS_PREDICATES
+
+          def removes_empty_witness?(difference)
+            return false unless difference.base.is_a?(Type::Nominal)
+
+            predicate = EMPTY_WITNESS_PREDICATES[difference.base.class_name]
+            !!(predicate && predicate.call(difference.removed))
+          end
+
+          def empty_removal_projection(base, method_name, args)
+            return nil unless args.empty?
+
+            if %i[size length count bytesize].include?(method_name)
+              return size_returning_for_empty_removal(base, method_name)
+            end
+
+            empty_predicate_projection(base, method_name)
+          end
+
+          def empty_predicate_projection(base, method_name)
+            case method_name
+            when :empty?
+              base.class_name == "Integer" ? nil : Type::Combinator.constant_of(false)
+            when :zero?
+              base.class_name == "Integer" ? Type::Combinator.constant_of(false) : nil
+            end
+          end
+
+          def size_returning_for_empty_removal(base, method_name)
+            return nil if base.class_name == "Integer" # Integer has no size method on Difference
+
+            selectors = SIZE_RETURNING_NOMINALS[base.class_name]
+            return nil unless selectors&.include?(method_name)
+
+            Type::Combinator.positive_int
+          end
+
           def tuple_first(tuple, _method_name, args)
             return nil unless args.empty?
             return Type::Combinator.constant_of(nil) if tuple.elements.empty?

data/lib/rigor/inference/method_dispatcher.rb

@@ -4,6 +4,8 @@ require_relative "../type"
 require_relative "method_dispatcher/constant_folding"
 require_relative "method_dispatcher/shape_dispatch"
 require_relative "method_dispatcher/rbs_dispatch"
+require_relative "method_dispatcher/iterator_dispatch"
+require_relative "method_dispatcher/file_folding"
 
 module Rigor
   module Inference
@@ -56,29 +58,12 @@ module Rigor
       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
+        precise = dispatch_precise_tiers(receiver_type, method_name, arg_types)
+        return precise if precise
 
         rbs_result = RbsDispatch.try_dispatch(
-          receiver: receiver_type,
-          method_name: method_name,
-          args: arg_types,
-          environment: environment,
-          block_type: block_type
+          receiver: receiver_type, method_name: method_name, args: arg_types,
+          environment: environment, block_type: block_type
         )
         return rbs_result if rbs_result
 
@@ -96,6 +81,21 @@ module Rigor
         try_user_class_fallback(receiver_type, method_name, arg_types, environment, block_type)
       end
 
+      # Runs the precision tiers (constant fold, shape dispatch,
+      # file-path fold) in order and returns the first non-nil
+      # answer. Each tier owns its own receiver/argument shape
+      # checks; a tier that does not recognise the receiver returns
+      # nil so the next tier can try. The RBS tier sits below this
+      # chain and is invoked by the outer `dispatch` method.
+      def dispatch_precise_tiers(receiver_type, method_name, arg_types)
+        meta_result = try_meta_introspection(receiver_type, method_name)
+        return meta_result if meta_result
+
+        ConstantFolding.try_fold(receiver: receiver_type, method_name: method_name, args: arg_types) ||
+          ShapeDispatch.try_dispatch(receiver: receiver_type, method_name: method_name, args: arg_types) ||
+          FileFolding.try_dispatch(receiver: receiver_type, method_name: method_name, args: arg_types)
+      end
+
       def try_user_class_fallback(receiver_type, method_name, arg_types, environment, block_type)
         return nil if environment.nil?
 
@@ -201,6 +201,13 @@ module Rigor
       def expected_block_param_types(receiver_type:, method_name:, arg_types:, environment: nil)
         return [] if receiver_type.nil?
 
+        iterator_result = IteratorDispatch.block_param_types(
+          receiver: receiver_type,
+          method_name: method_name,
+          args: arg_types
+        )
+        return iterator_result if iterator_result
+
         RbsDispatch.block_param_types(
           receiver: receiver_type,
           method_name: method_name,