rigortype 0.2.7 → 0.2.8

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

@@ -5,32 +5,25 @@ require_relative "../../type"
 module Rigor
   module Inference
     module MethodDispatcher
-      # `Array#to_h { |x| [k, v] }` (and the no-block-pair tuple form's
-      # block sibling) return-type fold.
+      # `Array#to_h { |x| [k, v] }` (and the no-block-pair tuple form's block sibling) return-type fold.
       #
-      # `Enumerable#to_h` with a block maps every element to a
-      # `[key, value]` pair and collects them into a Hash. When the
-      # block's inferred return type is a recognizable 2-element
-      # `Tuple` (`[K, V]`), this tier projects the pair into a
-      # `Hash[K, V]` nominal whose key/value parameters are the
-      # widened pair types. Without this fold the call hits the RBS
-      # generic and the block's `[K, V]` return is dropped, typing as
+      # `Enumerable#to_h` with a block maps every element to a `[key, value]` pair and collects them into a Hash.
+      # When the block's inferred return type is a recognizable 2-element `Tuple` (`[K, V]`), this tier projects
+      # the pair into a `Hash[K, V]` nominal whose key/value parameters are the widened pair types. Without this
+      # fold the call hits the RBS generic and the block's `[K, V]` return is dropped, typing as
       # `Hash[Dynamic[top], Dynamic[top]]`.
       #
-      # Value-pinned constants in the pair (`Constant[2]`) are widened
-      # to their nominal (`Integer`) for the Hash parameters: the built
-      # hash holds many keys, so pinning the parameter to a single
-      # element's literal would be unsound for the aggregate. The same
-      # widening the loop-body fixpoint applies (`Combinator#
-      # widen_value_pinned`) is reused.
+      # Value-pinned constants in the pair (`Constant[2]`) are widened to their nominal (`Integer`) for the Hash
+      # parameters: the built hash holds many keys, so pinning the parameter to a single element's literal would
+      # be unsound for the aggregate. The same widening the loop-body fixpoint applies
+      # (`Combinator#widen_value_pinned`) is reused.
       #
       # Declines (returns `nil`, leaving today's RBS answer) when:
       #
       # - there is no block at the call site,
       # - the block return type is not a 2-element `Tuple`, or
-      # - the receiver is not an Array-shaped carrier (`Tuple` or
-      #   `Array` nominal). Hash receivers keep their existing
-      #   `ShapeDispatch#hash_to_h` identity fold.
+      # - the receiver is not an Array-shaped carrier (`Tuple` or `Array` nominal). Hash receivers keep their
+      #   existing `ShapeDispatch#hash_to_h` identity fold.
       module ArrayToHFolding
         module_function
 

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

@@ -7,36 +7,25 @@ module Rigor
     module MethodDispatcher
       # Block-shaped fold dispatch (v0.0.6 phase 1).
       #
-      # Sits ahead of `RbsDispatch.try_dispatch` and folds a small
-      # set of block-taking Enumerable methods when the inferred
-      # block return type is a Ruby-truthy or Ruby-falsey
-      # `Type::Constant`. The block-parameter typing for the same
-      # methods continues to be answered by `IteratorDispatch`
-      # (this module concerns the *return* of the call, not the
-      # block-param binding).
+      # Sits ahead of `RbsDispatch.try_dispatch` and folds a small set of block-taking Enumerable methods when
+      # the inferred block return type is a Ruby-truthy or Ruby-falsey `Type::Constant`. The block-parameter
+      # typing for the same methods continues to be answered by `IteratorDispatch` (this module concerns the
+      # *return* of the call, not the block-param binding).
       #
       # The methods covered fall in two families:
       #
-      # - **Filter-shaped** (`select` / `filter` / `reject` /
-      #   `take_while` / `drop_while`): the block's truthiness
-      #   selects the all-or-nothing endpoints — either the
-      #   receiver's full shape (when every element is kept) or
-      #   the empty-tuple carrier (when every element is dropped).
-      # - **Predicate-shaped** (`all?` / `any?` / `none?`): the
-      #   block's truthiness combined with the receiver's
-      #   emptiness collapses the call to a `Constant[bool]` in
-      #   the cases where Ruby's actual semantics make it
-      #   unconditional. Non-empty + truthy `any?` is `true`;
-      #   non-empty + falsey `all?` is `false`; the empty-receiver
-      #   "vacuous" answers (`[].all? { false } == true`,
-      #   `[].any? { true } == false`, `[].none? { true } == true`)
-      #   are likewise honoured.
+      # - **Filter-shaped** (`select` / `filter` / `reject` / `take_while` / `drop_while`): the block's
+      #   truthiness selects the all-or-nothing endpoints — either the receiver's full shape (when every
+      #   element is kept) or the empty-tuple carrier (when every element is dropped).
+      # - **Predicate-shaped** (`all?` / `any?` / `none?`): the block's truthiness combined with the
+      #   receiver's emptiness collapses the call to a `Constant[bool]` in the cases where Ruby's actual
+      #   semantics make it unconditional. Non-empty + truthy `any?` is `true`; non-empty + falsey `all?` is
+      #   `false`; the empty-receiver "vacuous" answers (`[].all? { false } == true`, `[].any? { true } ==
+      #   false`, `[].none? { true } == true`) are likewise honoured.
       #
-      # The dispatcher returns `nil` for any case that cannot be
-      # decided from the (receiver-shape, method, block-truthiness)
-      # tuple — element-wise block re-evaluation against
-      # `Constant<Array>` receivers (the `map` / `filter_map` /
-      # `flat_map` precision tier) is reserved for a later slice.
+      # The dispatcher returns `nil` for any case that cannot be decided from the (receiver-shape, method,
+      # block-truthiness) tuple — element-wise block re-evaluation against `Constant<Array>` receivers (the
+      # `map` / `filter_map` / `flat_map` precision tier) is reserved for a later slice.
       module BlockFolding
         module_function
 
@@ -45,21 +34,16 @@ module Rigor
 
         PREDICATE_METHODS = Set[:all?, :any?, :none?].freeze
 
-        # Methods whose answer is `nil` when the block always
-        # returns Ruby-falsey — `find` / `detect` short-circuit
-        # to nil when nothing matches, `find_index` / `index`
-        # likewise. These methods only fold on the falsey side
-        # for now; the truthy-block side requires per-position
-        # analysis (the index of the first kept element, or the
-        # element itself, depend on the receiver's shape and on
-        # which positions actually evaluate to truthy).
+        # Methods whose answer is `nil` when the block always returns Ruby-falsey — `find` / `detect`
+        # short-circuit to nil when nothing matches, `find_index` / `index` likewise. These methods only fold
+        # on the falsey side for now; the truthy-block side requires per-position analysis (the index of the
+        # first kept element, or the element itself, depend on the receiver's shape and on which positions
+        # actually evaluate to truthy).
         FALSEY_BLOCK_NIL_METHODS = Set[:find, :detect, :find_index, :index].freeze
 
-        # Block-taking `count` returns the number of elements
-        # for which the block is truthy. With a Constant-falsey
-        # block the answer is unconditionally `Constant[0]`;
-        # with a Constant-truthy block on a finitely-sized
-        # receiver it is `Constant[size]`.
+        # Block-taking `count` returns the number of elements for which the block is truthy. With a
+        # Constant-falsey block the answer is unconditionally `Constant[0]`; with a Constant-truthy block on
+        # a finitely-sized receiver it is `Constant[size]`.
         COUNT_METHOD = :count
 
         # @param receiver    [Rigor::Type, nil]
@@ -106,13 +90,10 @@ module Rigor
           block_type.value ? :truthy : :falsey
         end
 
-        # Filter-shaped methods collapse to either the receiver
-        # (every element kept) or the empty tuple (every element
-        # dropped). Tuple-shaped receivers widen to
-        # `Array[union of elements]` on the all-kept side because
-        # we cannot prove WHICH positional subset survives —
-        # Tuple's per-position semantics do not carry over to a
-        # filtered Array.
+        # Filter-shaped methods collapse to either the receiver (every element kept) or the empty tuple
+        # (every element dropped). Tuple-shaped receivers widen to `Array[union of elements]` on the
+        # all-kept side because we cannot prove WHICH positional subset survives — Tuple's per-position
+        # semantics do not carry over to a filtered Array.
         def fold_filter(receiver, method_name, truthiness)
           return nil unless filter_receiver_known?(receiver)
 
@@ -140,8 +121,7 @@ module Rigor
           Type::Combinator.nominal_of("Array", type_args: [element])
         end
 
-        # Predicate folds. The decision table mirrors Ruby's
-        # actual semantics on `Enumerable#all?` / `#any?` /
+        # Predicate folds. The decision table mirrors Ruby's actual semantics on `Enumerable#all?` / `#any?` /
         # `#none?` — see the table at the top of the module.
         def fold_predicate(receiver, method_name, truthiness)
           emptiness = receiver_emptiness(receiver)
@@ -205,12 +185,9 @@ module Rigor
         end
 
         def constant_emptiness(value)
-          # Only `Range` constants reach these folds: `Type::Constant`
-          # rejects Array / Hash literals (they become `Tuple` /
-          # `HashShape` carriers), and the remaining scalar
-          # constants (Integer / Float / Symbol / String / …)
-          # are not Enumerable receivers for the filter or
-          # predicate methods folded here.
+          # Only `Range` constants reach these folds: `Type::Constant` rejects Array / Hash literals (they
+          # become `Tuple` / `HashShape` carriers), and the remaining scalar constants (Integer / Float /
+          # Symbol / String / …) are not Enumerable receivers for the filter or predicate methods folded here.
           return range_emptiness(value) if value.is_a?(Range)
 
           :unknown
@@ -228,12 +205,9 @@ module Rigor
           end
         end
 
-        # `non-empty-array[T]` is encoded as
-        # `Difference[Array[T], Tuple[]]` — the imported built-in
-        # carrier for non-emptiness. Recognising it here lets
-        # `arr.any? { true }` fold to `Constant[true]` for
-        # callers who threaded the non-emptiness through their
-        # type signature.
+        # `non-empty-array[T]` is encoded as `Difference[Array[T], Tuple[]]` — the imported built-in carrier
+        # for non-emptiness. Recognising it here lets `arr.any? { true }` fold to `Constant[true]` for
+        # callers who threaded the non-emptiness through their type signature.
         def difference_emptiness(diff)
           base = diff.base
           removed = diff.removed
@@ -247,11 +221,9 @@ module Rigor
           type.is_a?(Type::Nominal) && %w[Array Hash Set].include?(type.class_name)
         end
 
-        # Filter folds need at least a recognised collection
-        # carrier; `Top` / `Dynamic` / arbitrary nominals decline
-        # so the RBS tier answers (its `Array#select { … } -> Array[T]`
-        # projection is correct, just less precise on the empty
-        # endpoint).
+        # Filter folds need at least a recognised collection carrier; `Top` / `Dynamic` / arbitrary nominals
+        # decline so the RBS tier answers (its `Array#select { … } -> Array[T]` projection is correct, just
+        # less precise on the empty endpoint).
         def filter_receiver_known?(receiver)
           case receiver
           when Type::Tuple, Type::HashShape, Type::Constant, Type::Difference then true
@@ -260,12 +232,10 @@ module Rigor
           end
         end
 
-        # `find` / `detect` / `find_index` / `index` (block form)
-        # short-circuit to nil when the block is provably falsey.
-        # `index` and `find_index` also accept a non-block argument
-        # form (`arr.index(value)`); we decline whenever the call
-        # carries a positional argument so the RBS tier still
-        # answers the value-search variant correctly.
+        # `find` / `detect` / `find_index` / `index` (block form) short-circuit to nil when the block is
+        # provably falsey. `index` and `find_index` also accept a non-block argument form
+        # (`arr.index(value)`); we decline whenever the call carries a positional argument so the RBS tier
+        # still answers the value-search variant correctly.
         def fold_falsey_nil_short_circuit(_method_name, truthiness, args)
           return nil unless args.empty?
           return nil unless truthiness == :falsey
@@ -273,11 +243,9 @@ module Rigor
           Type::Combinator.constant_of(nil)
         end
 
-        # `count` with a block returns the count of elements
-        # for which the block is truthy. The non-block forms
-        # (`count` / `count(value)`) carry positional arguments
-        # and are handled by the RBS tier; this fold only fires
-        # when the block is the sole source of selection.
+        # `count` with a block returns the count of elements for which the block is truthy. The non-block
+        # forms (`count` / `count(value)`) carry positional arguments and are handled by the RBS tier; this
+        # fold only fires when the block is the sole source of selection.
         def fold_count(receiver, truthiness, args)
           return nil unless args.empty?
           return Type::Combinator.constant_of(0) if truthiness == :falsey
@@ -292,11 +260,9 @@ module Rigor
           Type::Combinator.constant_of(size)
         end
 
-        # Returns the receiver's known finite element count, or
-        # nil when the carrier does not pin a size. Tuple and
-        # HashShape are pinned by construction; `Constant<…>`
-        # exposes the literal's `.size`. Other shapes (Array[T],
-        # Range[T], Nominal) decline so the RBS tier widens.
+        # Returns the receiver's known finite element count, or nil when the carrier does not pin a size.
+        # Tuple and HashShape are pinned by construction; `Constant<…>` exposes the literal's `.size`. Other
+        # shapes (Array[T], Range[T], Nominal) decline so the RBS tier widens.
         def finite_size(receiver)
           case receiver
           when Type::Tuple then receiver.elements.size
@@ -306,8 +272,8 @@ module Rigor
         end
 
         def constant_size(value)
-          # Mirrors `constant_emptiness` — only `Range` produces
-          # a meaningful finite size for the methods folded here.
+          # Mirrors `constant_emptiness` — only `Range` produces a meaningful finite size for the methods
+          # folded here.
           range_size(value) if value.is_a?(Range)
         end
 

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

@@ -3,22 +3,18 @@
 module Rigor
   module Inference
     module MethodDispatcher
-      # Immutable value object carrying everything a dispatch tier needs
-      # to fold a single call site. Built once per `MethodDispatcher.dispatch`
-      # and threaded — unchanged — through every tier, replacing the
-      # `(receiver:, method_name:, args:, …)` keyword quartet that each
-      # tier used to redeclare (several with `# rubocop:disable
-      # Metrics/ParameterLists`).
+      # Immutable value object carrying everything a dispatch tier needs to fold a single call site. Built
+      # once per `MethodDispatcher.dispatch` and threaded — unchanged — through every tier, replacing the
+      # `(receiver:, method_name:, args:, …)` keyword quartet that each tier used to redeclare (several
+      # needing a Metrics/ParameterLists rubocop exemption).
       #
-      # Every tier satisfies one interface — `try_dispatch(CallContext) ->
-      # Rigor::Type?` (the `_DispatchTier` RBS interface). Pure tiers
-      # (the singleton folders, ConstantFolding, ShapeDispatch, …) read
-      # only `receiver` / `method_name` / `args` and ignore the rest;
-      # the RBS / backward / block-param tiers consult the wider context.
+      # Every tier satisfies one interface — `try_dispatch(CallContext) -> Rigor::Type?` (the `_DispatchTier`
+      # RBS interface). Pure tiers (the singleton folders, ConstantFolding, ShapeDispatch, …) read only
+      # `receiver` / `method_name` / `args` and ignore the rest; the RBS / backward / block-param tiers
+      # consult the wider context.
       #
-      # Derived call sites (the user-class fallback's `public_only` RBS
-      # retry, the Tier-B origin-module redispatch) use `Data#with` to
-      # copy the base context with the few fields that differ rather than
+      # Derived call sites (the user-class fallback's `public_only` RBS retry, the Tier-B origin-module
+      # redispatch) use `Data#with` to copy the base context with the few fields that differ rather than
       # rebuilding the quartet by hand.
       #
       # Fields:
@@ -36,19 +32,16 @@ module Rigor
         :block_type, :environment, :call_node, :scope,
         :self_type_override, :public_only
       ) do
-        # Keyword factory with nil/false defaults for the optional
-        # context fields, so a caller that only has the call quartet
-        # (the common precise-tier path) need not spell out the rest.
+        # Keyword factory with nil/false defaults for the optional context fields, so a caller that only has
+        # the call quartet (the common precise-tier path) need not spell out the rest.
         #
-        # This is the single place the call-context field list is
-        # enumerated — the whole point of the value object is to absorb
-        # the wide keyword list the tiers used to each redeclare.
+        # This is the single place the call-context field list is enumerated — the whole point of the value
+        # object is to absorb the wide keyword list the tiers used to each redeclare.
         def self.build(receiver:, method_name:, args:, # rubocop:disable Metrics/ParameterLists
                        block_type: nil, environment: nil, call_node: nil,
                        scope: nil, self_type_override: nil, public_only: false)
-          # Positional `new` (field-definition order) avoids the keyword
-          # hash a `new(receiver:, …)` call allocates — this runs once per
-          # dispatch and was a top allocation site. Order MUST track the
+          # Positional `new` (field-definition order) avoids the keyword hash a `new(receiver:, …)` call
+          # allocates — this runs once per dispatch and was a top allocation site. Order MUST track the
           # `Data.define` field list above.
           new(
             receiver, method_name, args,

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

@@ -7,31 +7,23 @@ require_relative "singleton_folding"
 module Rigor
   module Inference
     module MethodDispatcher
-      # Folds `CGI` module-function calls on statically known
-      # string constants.
+      # Folds `CGI` module-function calls on statically known string constants.
       #
-      # `CGI.escapeHTML` / `CGI.unescapeHTML` and related methods
-      # 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.
+      # `CGI.escapeHTML` / `CGI.unescapeHTML` and related methods 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
       #
-      # * `escapeHTML(str)` / `escape_html(str)` / `h(str)` —
-      #   HTML-escape. Returns `Constant[String]`.
-      # * `unescapeHTML(str)` / `unescape_html(str)` —
-      #   HTML-unescape. Returns `Constant[String]`.
-      # * `escape(str)` / `unescape(str)` —
-      #   URL-encode / decode (`application/x-www-form-urlencoded`).
+      # * `escapeHTML(str)` / `escape_html(str)` / `h(str)` — HTML-escape. Returns `Constant[String]`.
+      # * `unescapeHTML(str)` / `unescape_html(str)` — HTML-unescape. Returns `Constant[String]`.
+      # * `escape(str)` / `unescape(str)` — URL-encode / decode (`application/x-www-form-urlencoded`).
       #   Returns `Constant[String]`.
-      # * `escapeURIComponent(str)` / `escape_uri_component(str)`,
-      #   `unescapeURIComponent(str)` / `unescape_uri_component(str)` —
-      #   URI-component percent-encode / decode. Returns `Constant[String]`.
+      # * `escapeURIComponent(str)` / `escape_uri_component(str)`, `unescapeURIComponent(str)` /
+      #   `unescape_uri_component(str)` — URI-component percent-encode / decode. Returns `Constant[String]`.
       # * `escapeElement(str, *elements)` / `escape_element(str, *elements)`,
-      #   `unescapeElement(str, *elements)` / `unescape_element(str, *elements)` —
-      #   element-level escape / unescape (first arg is the string,
-      #   remaining args are element names). Returns `Constant[String]`.
+      #   `unescapeElement(str, *elements)` / `unescape_element(str, *elements)` — element-level escape /
+      #   unescape (first arg is the string, remaining args are element names). Returns `Constant[String]`.
       #
       # === Non-constant / unsupported cases
       #
@@ -89,9 +81,8 @@ module Rigor
           nil
         end
 
-        # `CGI.escapeElement(str, "elem1", "elem2", ...)` — element-
-        # level escape / unescape. The remaining args after the first
-        # must be `Constant[String]` element names.
+        # `CGI.escapeElement(str, "elem1", "elem2", ...)` — element-level escape / unescape. The remaining
+        # args after the first must be `Constant[String]` element names.
         def fold_cgi_element(method_name, str, element_args)
           elements = element_args.map do |arg|
             value = SingletonFolding.constant_string(arg)