rigortype 0.1.8 → 0.1.9

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

@@ -87,7 +87,11 @@ module Rigor
           zip: :tuple_zip,
           :[] => :tuple_index,
           fetch: :tuple_index,
-          dig: :tuple_dig
+          dig: :tuple_dig,
+          values_at: :tuple_values_at,
+          :+ => :tuple_concat,
+          compact: :tuple_compact,
+          take: :tuple_take
         }.freeze
 
         HASH_SHAPE_HANDLERS = {
@@ -96,19 +100,41 @@ module Rigor
           count: :hash_size,
           empty?: :hash_empty?,
           any?: :hash_any?,
+          none?: :hash_none?,
+          one?: :hash_one?,
           keys: :hash_keys,
           values: :hash_values,
           first: :hash_first,
           flatten: :hash_flatten,
           compact: :hash_compact,
           to_a: :hash_to_a,
+          entries: :hash_to_a,
           to_h: :hash_to_h,
+          to_hash: :hash_to_h,
+          deconstruct_keys: :hash_deconstruct_keys,
           invert: :hash_invert,
           merge: :hash_merge,
+          slice: :hash_slice,
+          except: :hash_except,
           :[] => :hash_lookup,
           fetch: :hash_lookup,
           dig: :hash_dig,
-          values_at: :hash_values_at
+          values_at: :hash_values_at,
+          fetch_values: :hash_fetch_values,
+          assoc: :hash_assoc,
+          key: :hash_key,
+          has_key?: :hash_has_key?,
+          key?: :hash_has_key?,
+          member?: :hash_has_key?,
+          include?: :hash_has_key?,
+          has_value?: :hash_has_value?,
+          value?: :hash_has_value?,
+          default: :hash_default,
+          default_proc: :hash_default,
+          :< => :hash_compare,
+          :<= => :hash_compare,
+          :> => :hash_compare,
+          :>= => :hash_compare
         }.freeze
 
         # @return [Rigor::Type, nil] the precise element/value type, or
@@ -654,6 +680,67 @@ module Rigor
             [key.value, value]
           end
 
+          # `tuple.values_at(i1, i2, ...)` — returns a Tuple of
+          # per-index elements. Each argument must be a
+          # `Constant[Integer]`. Out-of-range indices fill with
+          # `Constant[nil]`, mirroring Ruby's runtime behaviour.
+          # Declines when any argument is non-static.
+          def tuple_values_at(tuple, _method_name, args)
+            return nil if args.empty?
+
+            values = args.map do |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)
+              idx ? tuple.elements[idx] : Type::Combinator.constant_of(nil)
+            end
+
+            Type::Combinator.tuple_of(*values)
+          end
+
+          # `tuple + other` — concatenates two Tuples. Both sides
+          # must be `Type::Tuple`. Returns a new Tuple whose
+          # elements are those of the receiver followed by those
+          # of the argument.
+          def tuple_concat(tuple, _method_name, args)
+            return nil unless args.size == 1
+
+            other = args.first
+            return nil unless other.is_a?(Type::Tuple)
+
+            Type::Combinator.tuple_of(*tuple.elements, *other.elements)
+          end
+
+          # `tuple.compact` — removes every element that is
+          # `Constant[nil]`. Folds only when every element is a
+          # `Constant` (so the nil set is decidable). Mixed-shape
+          # elements decline so the RBS tier widens.
+          def tuple_compact(tuple, _method_name, args)
+            return nil unless args.empty?
+            return nil unless tuple.elements.all?(Type::Constant)
+
+            kept = tuple.elements.reject { |e| e.is_a?(Type::Constant) && e.value.nil? }
+            Type::Combinator.tuple_of(*kept)
+          end
+
+          # `tuple.take(n)` — returns the first n elements as a
+          # new Tuple. The argument must be a `Constant[Integer]`.
+          # n <= 0 returns the empty Tuple; n >= size returns the
+          # full receiver.
+          def tuple_take(tuple, _method_name, args)
+            return nil unless args.size == 1
+
+            arg = args.first
+            return nil unless arg.is_a?(Type::Constant)
+            return nil unless arg.value.is_a?(Integer)
+
+            n = arg.value
+            return Type::Combinator.tuple_of if n <= 0
+
+            Type::Combinator.tuple_of(*tuple.elements.take(n))
+          end
+
           # Returns `true` / `false` if every element's truthiness
           # agrees, nil for mixed-or-unknown shapes. `all: true`
           # checks every element is truthy; `all: false` checks
@@ -817,6 +904,185 @@ module Rigor
 
             Type::Combinator.constant_of(!shape.pairs.empty?)
           end
+
+          # `shape.none?` (no block, no arg) — mirror of `any?`.
+          # Folds to `Constant[shape.pairs.empty?]` for closed
+          # shapes with no optional keys.
+          def hash_none?(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.empty?)
+          end
+
+          # `shape.one?` (no block, no arg) — folds to
+          # `Constant[shape.pairs.size == 1]` for a closed shape
+          # with no optional keys.
+          def hash_one?(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 == 1)
+          end
+
+          # `shape.deconstruct_keys(keys)` — Ruby's `Hash#deconstruct_keys`
+          # returns the receiver itself regardless of the `keys`
+          # argument, so the precise answer is the shape unchanged.
+          def hash_deconstruct_keys(shape, _method_name, args)
+            return nil unless args.size == 1
+
+            shape
+          end
+
+          # `shape.fetch_values(:a, :b, ...)` — like `values_at` but
+          # raises `KeyError` on a missing key. Folds to `Tuple[V…]`
+          # only when every requested key is present; a missing key
+          # declines so the RBS tier reflects the raise.
+          def hash_fetch_values(shape, _method_name, args)
+            return nil if args.empty?
+            return nil unless shape.closed?
+            return nil unless shape.optional_keys.empty?
+
+            values = []
+            args.each do |arg|
+              return nil unless arg.is_a?(Type::Constant)
+
+              key = arg.value
+              return nil unless key.is_a?(Symbol) || key.is_a?(String)
+              return nil unless shape.pairs.key?(key)
+
+              values << shape.pairs[key]
+            end
+            Type::Combinator.tuple_of(*values)
+          end
+
+          # `shape.assoc(key)` — returns `Tuple[Constant[k], V]` for a
+          # known key, `Constant[nil]` for a missing key.
+          def hash_assoc(shape, _method_name, args)
+            return nil unless args.size == 1
+            return nil unless shape.closed?
+            return nil unless shape.optional_keys.empty?
+
+            arg = args.first
+            return nil unless arg.is_a?(Type::Constant)
+
+            key = arg.value
+            return nil unless key.is_a?(Symbol) || key.is_a?(String)
+            return Type::Combinator.constant_of(nil) unless shape.pairs.key?(key)
+
+            Type::Combinator.tuple_of(Type::Combinator.constant_of(key), shape.pairs[key])
+          end
+
+          # `shape.key(value)` — reverse lookup. Folds when every
+          # value is a `Constant` so equality is decidable: returns
+          # `Constant[k]` for the first matching key, `Constant[nil]`
+          # when no value matches.
+          def hash_key(shape, _method_name, args)
+            return nil unless args.size == 1
+            return nil unless shape.closed?
+            return nil unless shape.optional_keys.empty?
+            return nil unless shape.pairs.values.all?(Type::Constant)
+
+            arg = args.first
+            return nil unless arg.is_a?(Type::Constant)
+
+            pair = shape.pairs.find { |_k, v| v.value == arg.value }
+            Type::Combinator.constant_of(pair&.first)
+          end
+
+          # `shape.has_value?(v)` / `value?(v)` — folds to
+          # `Constant[true/false]` when every value is a `Constant`
+          # (so equality is decidable) and the argument is a
+          # `Constant`.
+          def hash_has_value?(shape, _method_name, args)
+            return nil unless args.size == 1
+            return nil unless shape.closed?
+            return nil unless shape.optional_keys.empty?
+            return nil unless shape.pairs.values.all?(Type::Constant)
+
+            arg = args.first
+            return nil unless arg.is_a?(Type::Constant)
+
+            found = shape.pairs.values.any? { |v| v.value == arg.value }
+            Type::Combinator.constant_of(found)
+          end
+
+          # `shape.default` / `default_proc` — a literal `HashShape`
+          # carries no default value or proc, so both fold to
+          # `Constant[nil]`. `default` accepts an optional key
+          # argument (still returns the default), `default_proc`
+          # takes none — the `args.size <= 1` guard covers both.
+          def hash_default(shape, _method_name, args)
+            return nil unless args.size <= 1
+            return nil unless shape.closed?
+
+            Type::Combinator.constant_of(nil)
+          end
+
+          # `shape < other` / `<=` / `>` / `>=` — Hash containment
+          # comparison. Both sides must be closed `HashShape`s whose
+          # values are all `Constant` (so pair equality is
+          # decidable). `<` / `>` are proper-subset / -superset.
+          def hash_compare(shape, method_name, args)
+            return nil unless args.size == 1
+            return nil unless shape.closed? && shape.optional_keys.empty?
+
+            other = args.first
+            return nil unless other.is_a?(Type::HashShape)
+            return nil unless other.closed? && other.optional_keys.empty?
+
+            left = constant_pairs(shape)
+            right = constant_pairs(other)
+            return nil if left.nil? || right.nil?
+
+            Type::Combinator.constant_of(hash_containment(method_name, left, right))
+          end
+
+          # Unwraps a closed shape's pairs to a plain Ruby Hash of
+          # `key => value` for value-equality comparison. Returns nil
+          # when any value is not a `Constant`.
+          def constant_pairs(shape)
+            return nil unless shape.pairs.values.all?(Type::Constant)
+
+            shape.pairs.transform_values(&:value)
+          end
+
+          def hash_containment(method_name, left, right)
+            case method_name
+            when :<  then hash_proper_subset?(left, right)
+            when :<= then hash_subset?(left, right)
+            when :>  then hash_proper_subset?(right, left)
+            when :>= then hash_subset?(right, left)
+            end
+          end
+
+          def hash_subset?(left, right)
+            left.all? { |k, v| right.key?(k) && right[k] == v }
+          end
+
+          def hash_proper_subset?(left, right)
+            left.size < right.size && hash_subset?(left, right)
+          end
+
+          # `shape.has_key?(k)` / `key?(k)` / `member?(k)` /
+          # `include?(k)` — folds to `Constant[true/false]` when
+          # the argument is a `Constant[Symbol|String]` and the
+          # shape is closed with no optional keys.
+          def hash_has_key?(shape, _method_name, args)
+            return nil unless args.size == 1
+            return nil unless shape.closed?
+            return nil unless shape.optional_keys.empty?
+
+            arg = args.first
+            return nil unless arg.is_a?(Type::Constant)
+
+            key = arg.value
+            return nil unless key.is_a?(Symbol) || key.is_a?(String)
+
+            Type::Combinator.constant_of(shape.pairs.key?(key))
+          end
           # rubocop:enable Style/ReturnNilInPredicateMethodDefinition
 
           # `shape.keys` — returns a `Tuple[Constant<k>…]` for a
@@ -1027,6 +1293,54 @@ module Rigor
             Type::Combinator.tuple_of(*values)
           end
 
+          # `shape.slice(:a, :b, ...)` — returns a sub-HashShape
+          # containing only the specified keys. All arguments must
+          # be `Constant[Symbol|String]`. Keys not present in the
+          # shape are silently omitted (matching Ruby's runtime
+          # semantics — no nil padding). Declines on open shapes
+          # or when any argument is not a static key.
+          def hash_slice(shape, _method_name, args)
+            return nil if args.empty?
+            return nil unless shape.closed?
+            return nil unless shape.optional_keys.empty?
+
+            requested = []
+            args.each do |arg|
+              return nil unless arg.is_a?(Type::Constant)
+
+              key = arg.value
+              return nil unless key.is_a?(Symbol) || key.is_a?(String)
+
+              requested << key
+            end
+
+            Type::Combinator.hash_shape_of(shape.pairs.slice(*requested))
+          end
+
+          # `shape.except(:a, :b, ...)` — returns a sub-HashShape
+          # with the specified keys removed. All arguments must be
+          # `Constant[Symbol|String]`. Keys not present in the shape
+          # are silently ignored. Declines on open shapes or when
+          # any argument is not a static key.
+          def hash_except(shape, _method_name, args)
+            return nil if args.empty?
+            return nil unless shape.closed?
+            return nil unless shape.optional_keys.empty?
+
+            excluded = {}
+            args.each do |arg|
+              return nil unless arg.is_a?(Type::Constant)
+
+              key = arg.value
+              return nil unless key.is_a?(Symbol) || key.is_a?(String)
+
+              excluded[key] = true
+            end
+
+            kept = shape.pairs.reject { |k, _v| excluded.key?(k) }
+            Type::Combinator.hash_shape_of(kept)
+          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

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

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+require "shellwords"
+require_relative "../../type"
+
+module Rigor
+  module Inference
+    module MethodDispatcher
+      # Folds `Shellwords` module-function calls on statically known
+      # string constants.
+      #
+      # `Shellwords` is a pure, side-effect-free module whose functions
+      # are deterministic over their inputs — the same string always
+      # produces the same escaped / split / joined result. When all
+      # relevant arguments are `Constant[String]` (or `Tuple` of them
+      # for `join`), the analyzer can evaluate the call at inference
+      # time and return the concrete `Constant<T>` result.
+      #
+      # === Supported methods
+      #
+      # * `escape` / `shellescape(str)` — returns `Constant[String]`.
+      #   `Shellwords.escape("")` → `"''"`, so the result is always
+      #   non-empty; callers that care about the `non-empty-string`
+      #   refinement will get it for free once that carrier is wired
+      #   to scalar-constant returns.
+      #
+      # * `split` / `shellsplit` / `shellwords(line)` — splits the
+      #   shell command line into tokens, returns
+      #   `Tuple[Constant[String], …]`. Raises `ArgumentError` on
+      #   unmatched quotes; the handler declines (returns `nil`) so
+      #   the RBS tier widens gracefully.
+      #
+      # * `join` / `shelljoin(array)` — joins an array of tokens into
+      #   a shell-safe string. Requires a `Tuple` whose every element
+      #   is a `Constant[String]`; returns `Constant[String]`.
+      #
+      # === Non-constant / unsupported cases
+      #
+      # Any call where:
+      # - the receiver is not `Singleton[Shellwords]`,
+      # - the required argument is not a `Constant[String]` (or
+      #   `Tuple[Constant[String]…]` for `join`),
+      # - the method is not in the supported set, or
+      # - `Shellwords.split` raises on malformed input
+      #
+      # returns `nil`, deferring to the next dispatcher tier.
+      module ShellwordsFolding
+        SHELLWORDS_ESCAPE_METHODS = Set[:escape, :shellescape].freeze
+        SHELLWORDS_SPLIT_METHODS  = Set[:split, :shellsplit, :shellwords].freeze
+        SHELLWORDS_JOIN_METHODS   = Set[:join, :shelljoin].freeze
+        SHELLWORDS_ALL_METHODS    = (
+          SHELLWORDS_ESCAPE_METHODS | SHELLWORDS_SPLIT_METHODS | SHELLWORDS_JOIN_METHODS
+        ).freeze
+
+        # Maximum number of tokens `split` may produce before we
+        # decline the fold (same rationale as STRING_ARRAY_LIFT_LIMIT
+        # in ConstantFolding — keep the result Tuple manageable).
+        SHELLWORDS_SPLIT_LIMIT = 64
+
+        private_constant :SHELLWORDS_ESCAPE_METHODS, :SHELLWORDS_SPLIT_METHODS,
+                         :SHELLWORDS_JOIN_METHODS, :SHELLWORDS_ALL_METHODS,
+                         :SHELLWORDS_SPLIT_LIMIT
+
+        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 SHELLWORDS_ALL_METHODS.include?(method_name)
+
+          if SHELLWORDS_ESCAPE_METHODS.include?(method_name)
+            fold_escape(args)
+          elsif SHELLWORDS_SPLIT_METHODS.include?(method_name)
+            fold_split(args)
+          else
+            fold_join(args)
+          end
+        end
+
+        def dispatch_target?(receiver)
+          receiver.is_a?(Type::Singleton) && receiver.class_name == "Shellwords"
+        end
+
+        # `Shellwords.escape(str)` / `.shellescape(str)` — one String arg.
+        def fold_escape(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(Shellwords.escape(arg.value))
+        end
+
+        # `Shellwords.split(line)` / `.shellsplit` / `.shellwords` —
+        # one String arg, result lifted to Tuple[Constant[String]…].
+        def fold_split(args)
+          return nil unless args.size == 1
+
+          arg = args.first
+          return nil unless arg.is_a?(Type::Constant) && arg.value.is_a?(String)
+
+          tokens = Shellwords.split(arg.value)
+          return nil if tokens.size > SHELLWORDS_SPLIT_LIMIT
+
+          Type::Combinator.tuple_of(*tokens.map { |t| Type::Combinator.constant_of(t) })
+        rescue ArgumentError
+          # Unmatched quotes / invalid shell syntax — decline so the
+          # RBS tier returns the widened Array[String] envelope.
+          nil
+        end
+
+        # `Shellwords.join(array)` / `.shelljoin` — one Tuple arg
+        # whose every element is `Constant[String]`.
+        def fold_join(args)
+          return nil unless args.size == 1
+
+          arg = args.first
+          return nil unless arg.is_a?(Type::Tuple)
+          return nil unless arg.elements.all? { |e| e.is_a?(Type::Constant) && e.value.is_a?(String) }
+
+          Type::Combinator.constant_of(Shellwords.join(arg.elements.map(&:value)))
+        end
+      end
+    end
+  end
+end

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