rigortype 0.1.7 → 0.1.9

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

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require_relative "../../type"
+
+module Rigor
+  module Inference
+    module MethodDispatcher
+      # Folds the zone-pinned `Time` class constructors on statically
+      # known arguments.
+      #
+      # Only `Time.utc` / `Time.gm` are folded. They pin the result
+      # to UTC, so the literal is machine-independent — every reader
+      # (`year`, `hour`, `utc_offset`, `strftime`, …) yields the same
+      # answer on any analysis host.
+      #
+      # `Time.now` (non-deterministic), `Time.at` / `Time.local` /
+      # `Time.mktime` / `Time.new` (local-zone — the result's wall
+      # clock and `utc_offset` depend on the analysis machine's
+      # timezone) are deliberately NOT folded; they keep their
+      # `Nominal[Time]` RBS answer. For the same reason `Time#getlocal`
+      # is blocklisted in `TIME_CATALOG` so a folded `Constant[Time]`
+      # cannot produce a machine-dependent local-zone copy.
+      module TimeFolding
+        TIME_UTC_METHODS = Set[:utc, :gm].freeze
+        private_constant :TIME_UTC_METHODS
+
+        # `Time.utc` accepts the 1–7 positional (year-first) form and
+        # a 10-arg (sec-first) form; cap the arity so a malformed
+        # call declines cheaply rather than reaching the constructor.
+        MAX_TIME_ARITY = 10
+        private_constant :MAX_TIME_ARITY
+
+        module_function
+
+        # @return [Rigor::Type, nil] folded result, or nil to defer.
+        def try_dispatch(receiver:, method_name:, args:)
+          return nil unless dispatch_target?(receiver)
+          return nil unless TIME_UTC_METHODS.include?(method_name)
+          return nil unless args.size.between?(1, MAX_TIME_ARITY)
+          return nil unless args.all?(Type::Constant)
+
+          values = args.map(&:value)
+          return nil unless values.all? { |v| v.is_a?(Integer) || v.is_a?(String) }
+
+          Type::Combinator.constant_of(Time.utc(*values))
+        rescue StandardError
+          nil
+        end
+
+        def dispatch_target?(receiver)
+          receiver.is_a?(Type::Singleton) && receiver.class_name == "Time"
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require "uri"
+require_relative "../../type"
+
+module Rigor
+  module Inference
+    module MethodDispatcher
+      # Folds `URI` module-function calls on statically known
+      # string constants.
+      #
+      # `URI.encode_www_form_component` / `decode_www_form_component`
+      # and the newer `encode_uri_component` / `decode_uri_component`
+      # are pure, deterministic functions over their string inputs.
+      # When the argument is a `Constant[String]`, the analyzer can
+      # evaluate the call at inference time and return the concrete
+      # `Constant[String]` result.
+      #
+      # === Supported methods
+      #
+      # * `encode_www_form_component(str)` / `decode_www_form_component(str)` —
+      #   RFC 3986 percent-encode / decode. Returns `Constant[String]`.
+      # * `encode_uri_component(str)` / `decode_uri_component(str)` —
+      #   Same encoding but may preserve additional reserved chars
+      #   (Ruby 3.2+). Returns `Constant[String]`.
+      #
+      # === Non-constant / unsupported cases
+      #
+      # Returns `nil` (deferring to the next dispatcher tier) when:
+      # - the receiver is not `Singleton[URI]`,
+      # - the first argument is not a `Constant[String]`,
+      # - the method is not in the supported set.
+      module URIFolding
+        URI_COMPONENT_METHODS = Set[
+          :encode_www_form_component, :decode_www_form_component,
+          :encode_uri_component, :decode_uri_component
+        ].freeze
+        private_constant :URI_COMPONENT_METHODS
+
+        module_function
+
+        # @return [Rigor::Type, nil] folded result, or nil to defer.
+        def try_dispatch(receiver:, method_name:, args:)
+          return nil unless dispatch_target?(receiver)
+          return nil unless URI_COMPONENT_METHODS.include?(method_name)
+
+          fold_uri_call(method_name, args)
+        end
+
+        def dispatch_target?(receiver)
+          receiver.is_a?(Type::Singleton) && receiver.class_name == "URI"
+        end
+
+        def fold_uri_call(method_name, args)
+          return nil unless args.size == 1
+
+          arg = args.first
+          return nil unless arg.is_a?(Type::Constant) && arg.value.is_a?(String)
+
+          Type::Combinator.constant_of(URI.public_send(method_name, arg.value))
+        rescue StandardError
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/rigor/inference/method_dispatcher.rb

@@ -13,6 +13,13 @@ require_relative "method_dispatcher/rbs_dispatch"
 require_relative "method_dispatcher/iterator_dispatch"
 require_relative "method_dispatcher/block_folding"
 require_relative "method_dispatcher/file_folding"
+require_relative "method_dispatcher/shellwords_folding"
+require_relative "method_dispatcher/math_folding"
+require_relative "method_dispatcher/time_folding"
+require_relative "method_dispatcher/regexp_folding"
+require_relative "method_dispatcher/cgi_folding"
+require_relative "method_dispatcher/uri_folding"
+require_relative "method_dispatcher/set_folding"
 require_relative "method_dispatcher/kernel_dispatch"
 require_relative "method_dispatcher/method_folding"
 
@@ -191,7 +198,7 @@ module Rigor
         # 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)
+        try_user_class_fallback(receiver_type, method_name, arg_types, environment, block_type, call_node)
       end
 
       # v0.1.3 — discovered-method dispatch tier. `scope` carries
@@ -643,7 +650,7 @@ module Rigor
         ConstantFolding.try_fold(receiver: receiver_type, method_name: method_name, args: arg_types) ||
           LiteralStringFolding.try_dispatch(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) ||
+          dispatch_stdlib_module_tiers(receiver_type, method_name, arg_types) ||
           KernelDispatch.try_dispatch(receiver: receiver_type, method_name: method_name, args: arg_types) ||
           MethodFolding.try_forward(receiver: receiver_type, method_name: method_name, args: arg_types) ||
           BlockFolding.try_fold(
@@ -651,7 +658,22 @@ module Rigor
           )
       end
 
-      def try_user_class_fallback(receiver_type, method_name, arg_types, environment, block_type)
+      # Stdlib module singleton-folding tiers: File, Shellwords, Math,
+      # Time, Regexp, CGI, URI, Set. Extracted from
+      # `dispatch_precise_tiers` to keep the parent method within the
+      # cyclomatic-complexity limit.
+      def dispatch_stdlib_module_tiers(receiver_type, method_name, arg_types)
+        FileFolding.try_dispatch(receiver: receiver_type, method_name: method_name, args: arg_types) ||
+          ShellwordsFolding.try_dispatch(receiver: receiver_type, method_name: method_name, args: arg_types) ||
+          MathFolding.try_dispatch(receiver: receiver_type, method_name: method_name, args: arg_types) ||
+          TimeFolding.try_dispatch(receiver: receiver_type, method_name: method_name, args: arg_types) ||
+          RegexpFolding.try_dispatch(receiver: receiver_type, method_name: method_name, args: arg_types) ||
+          CGIFolding.try_dispatch(receiver: receiver_type, method_name: method_name, args: arg_types) ||
+          URIFolding.try_dispatch(receiver: receiver_type, method_name: method_name, args: arg_types) ||
+          SetFolding.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, call_node = nil)
         return nil if environment.nil?
 
         fallback_receiver = user_class_fallback_receiver(receiver_type, environment)
@@ -665,16 +687,44 @@ module Rigor
         # `Bundler::URI::Generic` instance method types `base`
         # as `Object` because `Bundler::URI::Generic` is not in
         # RBS and the fallback's `self` resolves to Object.
+        #
+        # `public_only:` — when the call has an EXPLICIT, non-`self`
+        # receiver (`Favourite.select(...)`), suppress the private
+        # `Object`/`Kernel`/`Class` methods the fallback would
+        # otherwise resolve. Ruby raises `NoMethodError` for a
+        # private method called with an explicit receiver, so
+        # resolving `Favourite.select` to the private `Kernel#select`
+        # (`-> Array[String]`) is a confidently-wrong type. Implicit-
+        # self / `self.`-receiver calls (`puts`, `raise`, `require`)
+        # keep resolving — those are the fallback's intended targets.
         RbsDispatch.try_dispatch(
           receiver: fallback_receiver,
           method_name: method_name,
           args: arg_types,
           environment: environment,
           block_type: block_type,
-          self_type_override: receiver_type
+          self_type_override: receiver_type,
+          public_only: explicit_non_self_receiver?(call_node)
         )
       end
 
+      # True when the call node carries an explicit receiver that is
+      # not the literal `self`. Such a call cannot legally dispatch to
+      # a private method, so the user-class fallback must skip private
+      # signatures rather than return a confidently-wrong type. Returns
+      # false for implicit-self calls and `self.`-receiver calls (both
+      # may legally reach a private method in modern Ruby), and false
+      # when no `call_node` is supplied (internal dispatcher callers).
+      def explicit_non_self_receiver?(call_node)
+        return false if call_node.nil?
+        return false unless call_node.respond_to?(:receiver)
+
+        receiver = call_node.receiver
+        return false if receiver.nil?
+
+        !receiver.is_a?(Prism::SelfNode)
+      end
+
       def user_class_fallback_receiver(receiver_type, environment)
         case receiver_type
         when Type::Nominal
@@ -743,6 +793,18 @@ module Rigor
         array_lift = array_new_lift(receiver_type.class_name, arg_types)
         return array_lift if array_lift
 
+        range_lift = range_new_lift(receiver_type.class_name, arg_types)
+        return range_lift if range_lift
+
+        set_lift = set_new_lift(receiver_type.class_name, arg_types)
+        return set_lift if set_lift
+
+        regexp_lift = regexp_new_lift(receiver_type.class_name, arg_types)
+        return regexp_lift if regexp_lift
+
+        date_lift = date_new_lift(receiver_type.class_name, arg_types)
+        return date_lift if date_lift
+
         Type::Combinator.nominal_of(receiver_type.class_name)
       end
 
@@ -812,6 +874,119 @@ module Rigor
         type
       end
 
+      # `Range.new(b, e)` / `Range.new(b, e, excl)` — folds to
+      # `Constant[Range]` when both endpoints are `Constant[Integer]`
+      # or both are `Constant[String]`, and the optional third argument
+      # is a `Constant[true/false]`. Nil endpoints (beginless /
+      # endless ranges) are not folded because the useful instance
+      # methods (`to_a`, `first`, `last`) are not defined for them;
+      # the RBS tier answers `Nominal[Range]` for those forms.
+      def range_new_lift(class_name, arg_types)
+        return nil unless class_name == "Range"
+        return nil if arg_types.size < 2 || arg_types.size > 3
+
+        b_type = arg_types[0]
+        e_type = arg_types[1]
+
+        return nil unless b_type.is_a?(Type::Constant) && e_type.is_a?(Type::Constant)
+
+        b_val = b_type.value
+        e_val = e_type.value
+
+        # Only fold homogeneous Integer or String endpoint pairs.
+        return nil unless b_val.instance_of?(e_val.class)
+        return nil unless b_val.is_a?(Integer) || b_val.is_a?(String)
+
+        excl = range_new_excl(arg_types[2])
+        return nil if excl.nil?
+
+        Type::Combinator.constant_of(Range.new(b_val, e_val, excl))
+      rescue StandardError
+        nil
+      end
+
+      # Resolves the optional `exclude_end` argument for `range_new_lift`.
+      # Returns `false` (no arg), `true`/`false` (Constant[bool] arg),
+      # or `nil` to signal "decline" (wrong type / wrong value class).
+      def range_new_excl(excl_type)
+        case excl_type
+        when nil then false
+        when Type::Constant
+          excl_type.value if [true, false].include?(excl_type.value)
+        end
+      end
+
+      # `Set.new` / `Set.new(tuple_of_constants)` — folds to `Constant[Set]`
+      # when zero arguments are given or the single argument is a `Tuple`
+      # whose every element is a `Constant[T]`. Mirrors `SetFolding#fold_new`
+      # but lives here so the `:new` path in `try_meta_introspection` can
+      # reach it before the RBS tier answers `Nominal[Set]`.
+      def set_new_lift(class_name, arg_types)
+        return nil unless class_name == "Set"
+        return Type::Combinator.constant_of(::Set.new) if arg_types.empty?
+        return nil if arg_types.size > 1
+
+        arg = arg_types.first
+        return nil unless arg.is_a?(Type::Tuple)
+        return nil unless arg.elements.all?(Type::Constant)
+
+        values = arg.elements.map(&:value)
+        Type::Combinator.constant_of(::Set.new(values))
+      rescue StandardError
+        nil
+      end
+
+      # `Regexp.new(pattern)` / `Regexp.new(pattern, opts)` — folds to
+      # `Constant[Regexp]` when the pattern is a `Constant[String]`.
+      # Mirrors `RegexpFolding#fold_new` but lives here so the `:new` path
+      # in `try_meta_introspection` can reach it.
+      def regexp_new_lift(class_name, arg_types)
+        return nil unless class_name == "Regexp"
+        return nil if arg_types.empty? || arg_types.size > 2
+
+        pattern_arg = arg_types.first
+        return nil unless pattern_arg.is_a?(Type::Constant) && pattern_arg.value.is_a?(String)
+
+        opts = if arg_types.size == 2
+                 opt_type = arg_types[1]
+                 return nil unless opt_type.is_a?(Type::Constant)
+
+                 opt_type.value
+               else
+                 0
+               end
+
+        Type::Combinator.constant_of(Regexp.new(pattern_arg.value, opts))
+      rescue StandardError
+        nil
+      end
+
+      # `Date.new(y, m, d)` / `DateTime.new(y, m, d, h, min, s, off)`
+      # — folds to `Constant[Date]` / `Constant[DateTime]` when every
+      # argument is a `Constant` carrying an Integer (or, for the
+      # `DateTime` offset / `start` slots, a Rational or String).
+      # `Date.new` carries no timezone, and `DateTime.new`'s offset
+      # defaults to UTC, so the literal is machine-independent.
+      # `Date.today` / `Date.parse` are not constructors here — they
+      # are non-deterministic / string-dependent and stay
+      # `Nominal[Date]`.
+      DATE_NEW_CLASSES = %w[Date DateTime].freeze
+      private_constant :DATE_NEW_CLASSES
+
+      def date_new_lift(class_name, arg_types)
+        return nil unless DATE_NEW_CLASSES.include?(class_name)
+        return nil unless arg_types.size.between?(1, 8)
+        return nil unless arg_types.all?(Type::Constant)
+
+        values = arg_types.map(&:value)
+        return nil unless values.all? { |v| v.is_a?(Integer) || v.is_a?(Rational) || v.is_a?(String) }
+
+        klass = class_name == "Date" ? Date : DateTime
+        Type::Combinator.constant_of(klass.new(*values))
+      rescue StandardError
+        nil
+      end
+
       CONSTANT_METACLASSES = {
         Integer => "Integer", Float => "Float", String => "String",
         Symbol => "Symbol", Range => "Range",

data/lib/rigor/inference/method_parameter_binder.rb

@@ -43,10 +43,15 @@ module Rigor
       #   method (either `def self.foo` or a `def foo` inside
       #   `class << self`); routes the lookup through
       #   `RbsLoader#singleton_method`.
-      def initialize(environment:, class_path:, singleton:)
+      # @param source_path [String, nil] the project-relative path of
+      #   the file the method is defined in. Used to match ADR-28
+      #   path-scoped protocol contracts; `nil` (the default for
+      #   synthetic / probe scopes) disables the contract tier.
+      def initialize(environment:, class_path:, singleton:, source_path: nil)
         @environment = environment
         @class_path = class_path
         @singleton = singleton
+        @source_path = source_path
       end
 
       # @param def_node [Prism::DefNode]
@@ -58,15 +63,22 @@ module Rigor
         types = default_types_for(slots)
 
         rbs_method = lookup_rbs_method(def_node)
-        return types unless rbs_method
-
-        apply_rbs_overloads(types, slots, rbs_method.method_types) unless rbs_method.method_types.empty?
-        # `rigor:v1:param: <name> <refinement>` annotations
-        # tighten the bound type for matching slots. Applied
-        # after the RBS-overload pass so the override is the
-        # authoritative answer regardless of what the RBS
-        # signature declared.
-        apply_param_overrides(types, slots, rbs_method)
+        if rbs_method
+          apply_rbs_overloads(types, slots, rbs_method.method_types) unless rbs_method.method_types.empty?
+          # `rigor:v1:param: <name> <refinement>` annotations
+          # tighten the bound type for matching slots. Applied
+          # after the RBS-overload pass so the override is the
+          # authoritative answer regardless of what the RBS
+          # signature declared.
+          apply_param_overrides(types, slots, rbs_method)
+        end
+        # ADR-28 — a path-scoped protocol contract supplies the
+        # parameter type for a matching `def`. Applied last (most
+        # authoritative) and regardless of RBS presence: the
+        # methods a contract targets — controller actions and the
+        # like — typically have no RBS signature at all, so this
+        # tier must run even when `rbs_method` is nil.
+        apply_protocol_contract(types, slots, def_node)
         types
       end
 
@@ -75,6 +87,10 @@ module Rigor
       ParamSlot = Data.define(:kind, :name, :index)
       private_constant :ParamSlot
 
+      # Slot kinds a contract's positional `index` can address.
+      POSITIONAL_KINDS = %i[required_positional optional_positional].freeze
+      private_constant :POSITIONAL_KINDS
+
       # Walk the Prism `ParametersNode` and emit one slot per named
       # parameter, in declaration order. Anonymous slots (rest /
       # keyword-rest with no name) are skipped because we have no
@@ -187,6 +203,47 @@ module Rigor
         end
       end
 
+      # ADR-28 — when a path-scoped protocol contract targets this
+      # `def` (file path matches the contract's `path_glob`, method
+      # name + singleton-ness match), replace each contracted
+      # positional slot's binding with the contract's declared type.
+      # The type name resolves against the environment lazily here;
+      # an unresolvable name (the protocol's RBS not loaded) falls
+      # through to whatever the prior tiers bound, fail-soft.
+      def apply_protocol_contract(types, slots, def_node)
+        return if @source_path.nil?
+
+        registry = @environment.respond_to?(:plugin_registry) ? @environment.plugin_registry : nil
+        return if registry.nil?
+
+        contract = matching_contract(registry, def_node)
+        return if contract.nil?
+
+        contract.param_types.each do |param_type|
+          slot = positional_slot_at(slots, param_type.index)
+          next if slot.nil? || slot.name.nil?
+
+          resolved = @environment.nominal_for_name(param_type.type_name)
+          next if resolved.nil?
+
+          types[slot.name] = resolved
+        end
+      end
+
+      def matching_contract(registry, def_node)
+        contracts = registry.contracts_for_path(@source_path)
+        return nil if contracts.empty?
+
+        singleton = def_node.receiver.is_a?(Prism::SelfNode) || @singleton
+        contracts.find do |contract|
+          contract.method_name == def_node.name && contract.singleton == singleton
+        end
+      end
+
+      def positional_slot_at(slots, index)
+        slots.find { |slot| POSITIONAL_KINDS.include?(slot.kind) && slot.index == index }
+      end
+
       def collect_translated_types(method_types, slot)
         rbs_types = method_types.flat_map do |mt|
           t = rbs_type_for_slot(mt.type, slot)

data/lib/rigor/inference/narrowing.rb

@@ -386,8 +386,8 @@ module Rigor
           analyse_local_read(node, scope)
         when Prism::LocalVariableWriteNode
           analyse_local_write(node, scope)
-        when Prism::InstanceVariableWriteNode
-          analyse_ivar_write(node, scope)
+        when Prism::InstanceVariableReadNode, Prism::InstanceVariableWriteNode
+          analyse_ivar(node, scope)
         when Prism::ClassVariableWriteNode
           analyse_cvar_write(node, scope)
         when Prism::GlobalVariableWriteNode
@@ -767,7 +767,17 @@ module Rigor
           ]
         end
 
-        def analyse_ivar_write(node, scope)
+        # Truthy guard on an instance variable. Covers both the bare
+        # read — `if @ivar`, the left arm of `@ivar && @ivar.foo`,
+        # the receiver of `unless @ivar.nil?` once `!` reverses it —
+        # and the assignment-in-condition write `if @ivar = expr`.
+        # Mirrors `analyse_local_read` / `analyse_local_write`: the
+        # truthy edge narrows the ivar by `narrow_truthy` (dropping
+        # `nil` / `false`), the falsey edge by `narrow_falsey`. The
+        # narrowing is scoped to the guarded branch only, so it is
+        # purely additive — it never widens or re-narrows the ivar
+        # binding seen elsewhere.
+        def analyse_ivar(node, scope)
           current = scope.ivar(node.name)
           return nil if current.nil?
 
@@ -2024,15 +2034,24 @@ module Rigor
         end
 
         def analyse_nil_predicate(receiver, scope)
-          return nil unless receiver.is_a?(Prism::LocalVariableReadNode)
+          case receiver
+          when Prism::LocalVariableReadNode
+            current = scope.local(receiver.name)
+            return nil if current.nil?
 
-          current = scope.local(receiver.name)
-          return nil if current.nil?
+            [
+              scope.with_local(receiver.name, narrow_nil(current)),
+              scope.with_local(receiver.name, narrow_non_nil(current))
+            ]
+          when Prism::InstanceVariableReadNode
+            current = scope.ivar(receiver.name)
+            return nil if current.nil?
 
-          [
-            scope.with_local(receiver.name, narrow_nil(current)),
-            scope.with_local(receiver.name, narrow_non_nil(current))
-          ]
+            [
+              scope.with_ivar(receiver.name, narrow_nil(current)),
+              scope.with_ivar(receiver.name, narrow_non_nil(current))
+            ]
+          end
         end
 
         # `a && b` short-circuits: the truthy edge is the truthy edge