rigortype 0.3.8 → 0.4.0

data/lib/rigor/inference/stored_block_call.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require "prism"
+
+module Rigor
+  module Inference
+    # The calls that keep their literal block to run later instead of running it before they return: the Kernel
+    # functions that wrap it in a Proc (`lambda`, `proc`), the definers that install it as a method body
+    # (`define_method`, `define_singleton_method`, on any receiver), and the constructors that keep it as a proc,
+    # a thread or fiber body, an enumerator's generator or a hash's default proc.
+    #
+    # A `break` in such a block never becomes the call's value — it returns from the lambda or the defined method
+    # when that is called, or raises `LocalJumpError` — so the #853 break-arm union
+    # (`ExpressionTyper#call_break_arm_types`) MUST NOT read it. Unioning the arm typed
+    # `lambda do |t| break if flag; t end` as `Proc | nil`, and the lambda's next `.call` drew
+    # `call.possible-nil-receiver`.
+    #
+    # A project redefinition of one of these names is not excluded: dropping the arm there loses a `break`
+    # value, never invents one.
+    module StoredBlockCall
+      KERNEL_WRAPPERS = %i[lambda proc].freeze
+      DEFINERS = %i[define_method define_singleton_method].freeze
+      CONSTRUCTORS = {
+        Proc: %i[new], Thread: %i[new start fork], Fiber: %i[new], Enumerator: %i[new], Hash: %i[new]
+      }.transform_values(&:freeze).freeze
+      NO_NAMES = [].freeze
+      private_constant :KERNEL_WRAPPERS, :DEFINERS, :CONSTRUCTORS, :NO_NAMES
+
+      module_function
+
+      def stores_block?(call_node)
+        name = call_node.name
+        return kernel_spelled?(call_node.receiver) if KERNEL_WRAPPERS.include?(name)
+        return true if DEFINERS.include?(name)
+
+        constant = root_constant_name(call_node.receiver)
+        !constant.nil? && CONSTRUCTORS.fetch(constant, NO_NAMES).include?(name)
+      end
+
+      # Implicit self, `self.`, or `Kernel.` / `::Kernel.` — the spellings that reach Kernel's function.
+      def kernel_spelled?(receiver)
+        receiver.nil? || receiver.is_a?(Prism::SelfNode) || root_constant_name(receiver) == :Kernel
+      end
+
+      # `Foo` or `::Foo`'s name, else nil.
+      def root_constant_name(receiver)
+        case receiver
+        when Prism::ConstantReadNode then receiver.name
+        when Prism::ConstantPathNode then receiver.name if receiver.parent.nil?
+        end
+      end
+    end
+  end
+end

data/lib/rigor/inference/string_mutation.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+require_relative "../type"
+
+module Rigor
+  module Inference
+    # The String half of {MutationWidening}'s straight-line seam (issue #617 residue (4)).
+    #
+    # `s = +"ab"; s << "c"; s == "ab"` folded `flow.always-truthy-condition` on correct code: the seam
+    # responded to `Tuple` / `HashShape` / empty-witness carriers only, while a `Constant[String]` is just as
+    # falsified by an in-place mutator as a `Tuple` is by `<<`. The ADR-56 block-capture path already widened
+    # the same binding, so the two seams disagreed about one carrier.
+    #
+    # It lives beside `MutationWidening` rather than inside it because the tables here answer a different
+    # question from the Array / Hash ones: those partition a carrier's SHAPE evidence, this one partitions a
+    # VALUE pin and an emptiness proof.
+    module StringMutation
+      # Receiver-mutating String methods only. The non-bang siblings (`upcase` vs `upcase!`, `sub` vs `sub!`)
+      # return a new String and leave the receiver's value intact, so they stay precise.
+      #
+      # This is the one String table: `MutationWidening::SHAPE_MUTATORS` unions it with the Array and Hash ones, and
+      # the effect classifier and the effect catalogue's `mutators: string` cite it rather than keep a list of their
+      # own (ADR-103 WD3). A spec holds it to every bang method `String` defines plus the non-bang mutators reflection
+      # cannot find by name.
+      MUTATORS = %i[
+        << concat insert prepend replace clear []= slice!
+        setbyte bytesplice append_as_bytes force_encoding
+        sub! gsub! tr! tr_s! delete! squeeze! succ! next!
+        upcase! downcase! capitalize! swapcase! reverse!
+        strip! lstrip! rstrip! chomp! chop!
+        delete_prefix! delete_suffix! encode! scrub! unicode_normalize!
+      ].to_set.freeze
+
+      # The {MUTATORS} that CANNOT leave a non-empty receiver empty, and so keep a `non-empty-string` refinement:
+      # appenders (`<<`, `concat`, `insert`, `prepend`, `append_as_bytes`), and rewrites that keep at least one
+      # character (`setbyte`, `force_encoding`, the case mappings, `reverse!`, `succ!` / `next!`, `squeeze!`,
+      # `unicode_normalize!`). A whitelist, as `RefinementMutation::EMPTY_PRESERVING` is for Array and Hash: a mutator
+      # missing here retracts the witness, which costs precision, where a mutator missing from a list of emptiers kept
+      # the witness of a string it had just emptied — `tr!` and `tr_s!` did, since `"a".tr!("a", "")` is `""`.
+      EMPTY_PRESERVING = %i[
+        << concat insert prepend append_as_bytes
+        setbyte force_encoding
+        upcase! downcase! capitalize! swapcase! reverse! succ! next! squeeze! unicode_normalize!
+      ].to_set.freeze
+
+      # `tr!` / `tr_s!` map every character they match to one character of the replacement (padded with its last), so
+      # they empty the buffer only through an EMPTY replacement: `"a".tr!("a", "")` is `""`, `"a".tr!("a", "_")` is
+      # `"_"`. They keep the witness when their second argument is provably a non-empty String.
+      TRANSLATORS = %i[tr! tr_s!].to_set.freeze
+
+      NO_ARG_TYPES = [].freeze
+
+      module_function
+
+      # `Constant["ab"]` under a String mutator → the bare `String` nominal. The pinned value is what the
+      # mutation falsifies, and nothing else about the carrier survives it, so there is no `values: :keep`
+      # half to preserve the way a `Tuple`'s surviving slots have one: an appended, substituted or
+      # case-folded string is a different string.
+      #
+      # Only a String-valued `Constant` widens. Every other literal (`Integer`, `Symbol`, `Range`) can only
+      # reach this arm through a name in the Array or Hash table and not in {MUTATORS}, and answering for it
+      # would erase a value no in-place mutator on that class can change.
+      #
+      # `nil` — no widening — for every other input, which is the contract `MutationWidening#widen_for_mutator`
+      # signals a decline with.
+      def widen_constant(constant, method_name)
+        return nil unless constant?(constant)
+        return nil unless MUTATORS.include?(method_name)
+
+        Type::Combinator.nominal_of("String")
+      end
+
+      def constant?(type)
+        type.is_a?(Type::Constant) && type.value.is_a?(String)
+      end
+
+      # Whether `method_name`, called with `arg_types` (the call's positional argument types, possibly none), can leave
+      # a non-empty receiver empty, and so retract a `non-empty-string` refinement. Every mutator outside
+      # {EMPTY_PRESERVING} can, except a {TRANSLATORS} call whose replacement is provably non-empty.
+      def may_empty?(method_name, arg_types = NO_ARG_TYPES)
+        return false if EMPTY_PRESERVING.include?(method_name)
+        return true unless TRANSLATORS.include?(method_name)
+
+        !non_empty_string?(arg_types[1])
+      end
+
+      def non_empty_string?(type)
+        case type
+        when Type::Constant then constant?(type) && !type.value.empty?
+        when Type::Difference then type.removes_empty_witness? && type.base.class_name == "String"
+        when Type::Union then type.members.all? { |member| non_empty_string?(member) }
+        else false
+        end
+      end
+    end
+  end
+end

data/lib/rigor/inference/struct_fold_safety.rb

@@ -55,10 +55,10 @@ module Rigor
           node.is_a?(Prism::ModuleNode) || node.is_a?(Prism::SingletonClassNode)
       end
 
-      # @param root [Prism::Node, nil] the local-variable scope to scan.
-      # @param layout_lookup [#call] a `String -> Array[Symbol] | nil` resolver mapping a constant receiver name to its
+      # @param root — the local-variable scope to scan.
+      # @param layout_lookup — a `String -> Array[Symbol] | nil` resolver mapping a constant receiver name to its
       #   struct member list.
-      # @return [Set<Symbol>] the fold-safe local names.
+      # @return the fold-safe local names.
       def fold_safe_locals(root, layout_lookup)
         return EMPTY if root.nil?
 
@@ -208,10 +208,9 @@ module Rigor
       # Nested `def` / `class` / `module` bodies are skipped: their statements do not run during THIS body's
       # evaluation. Blocks are descended into — they share `self`.
       #
-      # @param body [Prism::Node, nil]
-      # @param member_names [Enumerable<Symbol>] the receiver carrier's member names.
-      # @yieldparam name [Symbol] an unrecognised self-call selector.
-      # @yieldreturn [Boolean] whether that sibling method is itself self-fold-safe.
+      # @param member_names — the receiver carrier's member names.
+      # @yieldparam name — an unrecognised self-call selector.
+      # @yieldreturn whether that sibling method is itself self-fold-safe.
       def self_fold_safe_body?(body, member_names, &sibling_pure)
         return false if body.nil?
 

data/lib/rigor/inference/synthetic_method_index.rb

@@ -22,8 +22,7 @@ module Rigor
     class SyntheticMethodIndex
       attr_reader :entries, :class_names
 
-      # @param entries [Array<SyntheticMethod>]
-      # @param class_names [Array<String>, Set<String>] names of classes the substrate synthesises wholesale (ADR-36
+      # @param class_names — names of classes the substrate synthesises wholesale (ADR-36
       #   nested-class emission — the variant subclasses that have no RBS/source declaration of their own). Recorded so
       #   `Environment#class_known?` can resolve them as classes (their constant reference + `.new` dispatch) even
       #   though nothing else in the type universe declares them. Tier B/C method emissions leave this empty (their

data/lib/rigor/inference/synthetic_method_scanner.rb

@@ -40,26 +40,24 @@ module Rigor
     module SyntheticMethodScanner # rubocop:disable Metrics/ModuleLength
       module_function
 
-      # @param plugin_registry [Rigor::Plugin::Registry]
-      # @param paths [Array<String>] absolute paths to the project
+      # @param paths — absolute paths to the project
       #   source files to scan.
-      # @param environment [Rigor::Environment, nil] used for
+      # @param environment — used for
       #   inheritance resolution against RBS-known classes
       #   (ActiveRecord::Base, Dry::Struct, etc.) that aren't
       #   declared in project source.
-      # @param fact_store [Rigor::Plugin::FactStore, nil]
+      # @param fact_store —
       #   the per-run cross-plugin fact store. ADR-18 lookups
       #   (`Plugin::Macro::HeredocTemplate::Emit#returns_from_arg`)
       #   consult this at scan time to resolve per-call-site
       #   return types from published facts; without it, those
       #   emit rows fall back to their static `returns:` (or
       #   `"untyped"` → `Dynamic[Top]`).
-      # @param buffer [Rigor::Analysis::BufferBinding, nil]
+      # @param buffer —
       #   editor-mode buffer binding. When set, reads for the
       #   logical path resolve to the buffer's physical path so
       #   the pre-pass sees the in-flight bytes instead of the
       #   on-disk copy.
-      # @return [Rigor::Inference::SyntheticMethodIndex]
       def scan(plugin_registry:, paths:, environment: nil, fact_store: nil, buffer: nil)
         templates = collect_templates(plugin_registry)
         registries = collect_trait_registries(plugin_registry)

data/lib/rigor/inference/unknown_store_widening.rb

@@ -0,0 +1,200 @@
+# frozen_string_literal: true
+
+require "prism"
+
+require_relative "../type"
+require_relative "element_read_widening"
+require_relative "mutation_widening"
+
+module Rigor
+  module Inference
+    # What a binding can hold after each of a set of in-place mutation sites — the nodes
+    # {CapturedLocals.content_mutations} collects — has run any number of times, storing values nothing typed.
+    #
+    # Each site takes its own straight-line widening ({MutationWidening.widen_for_mutator}), fed one
+    # `Dynamic[top]` per argument, and every site that can STORE a value then gives each type argument of the
+    # widened `Array` / `Hash` a `Dynamic[top]` arm: `{ a: 0 }` under `h[k] += 1` reads
+    # `Hash[Dynamic[top] | Symbol, Dynamic[top] | Integer]`. The second step is not redundant. The widening
+    # joins argument evidence only for the plain adders (`<<`, `push`, `[]=`, `store`, …); a site whose stored
+    # values its arguments do not describe — `map!`, a block-form `fill`, `transform_values!`, `merge!`,
+    # `flatten!` — comes back with the seed's element types alone, which is a wrong precise answer once the
+    # block has run: `a = [1]` under `a.map!(&:to_s)` would read `Array[Integer]`. Only a site that removes or
+    # reorders ({VALUE_PRESERVING}) keeps its content as the widening left it, since it cannot put a value
+    # there that was not there before — unless it is the site that CLOSES a literal carrier. A `Tuple` or
+    # `HashShape` knows which slots and keys exist, and the nominal it widens to cannot say that any may be
+    # missing, so it takes the gradual arm too: `{ a: 0 }` under a lone `h.delete(:a)` read `Hash[Symbol, 0]`,
+    # whose `h[:b]` answered `0` where Ruby answers `nil`, and `s = [0]` under `p = s.pop; s.push(x)` closed to
+    # `Array[0]`, a precise nominal the `push` after it then declined, so `p` stayed `0?`. With the arm the
+    # answer for a `Tuple` / `HashShape` seed (alone or in a `Union`) no longer depends on the order the sites are
+    # written in; a refinement seed (`non-empty-array[0]`) still can, since its remover does not close a literal.
+    #
+    # A site whose widening declines leaves the binding as it is, exactly as the straight-line seam does: a
+    # precise nominal (a declared or inferred `Array[String]` is a claim this seam may not grow), a receiver
+    # that is no carrier, or a name the mutator tables do not list for that carrier (`store` on a `Tuple`, a method
+    # its class does not define). The caller MUST therefore not read an unchanged binding as describing later
+    # iterations. An empty-witness refinement under a storing mutator that keeps the witness is not such a decline:
+    # the straight-line widening grows it (issue #936), and gives a site whose arguments describe nothing it stores
+    # (`non-empty-array[String]` under `map!`) the gradual arm itself ({RewriteMutation}),
+    # so the site widens like any other storing site.
+    #
+    # The per-element block fold is the consumer: it types every position from one entry scope, so the binding
+    # it lays under each position has to hold whatever earlier iterations stored. Unknown evidence is the point,
+    # not a shortcut — a stored value typed in that same entry scope (`h[k] = h[k] + 1`) is itself a
+    # first-iteration answer.
+    #
+    # Two more kinds of site change a binding's contents without naming it as the receiver, and each is widened
+    # the way straight-line code widens it:
+    #
+    # - A mutator on an ELEMENT of the binding (`a[0] << e`, `a.first.push(e)`): the site's receiver is an element
+    #   read rooted at the variable ({ElementReadWidening.element_read_path}), and the same widening runs on the
+    #   element the path selects, rebuilding the carrier around it. The other slots keep their types, and a path
+    #   {ElementReadWidening} cannot follow (a `HashShape` slot) declines, as it does on straight-line code.
+    # - A self-call whose callee content-mutates the parameter the binding is passed to (`add_to(a, e)`, a
+    #   {CalleeStore}): nothing at the call says what the callee stores or removes, so each collection the binding
+    #   can hold is floored to its bare carrier ({.content_floor}), as ADR-57's callee floor does after the call.
+    module UnknownStoreWidening
+      # Mutators that only remove or reorder what the receiver already holds.
+      VALUE_PRESERVING = %i[
+        pop shift delete delete_at delete_if reject! select! filter! keep_if clear compact! uniq! slice!
+        sort! sort_by! reverse! rotate! shuffle!
+      ].to_set.freeze
+
+      # A site that mutates a binding through a callee: `call` passes the variable, read by one of `arguments`, to
+      # a parameter the callee content-mutates.
+      CalleeStore = Data.define(:call, :arguments)
+
+      COLLECTION_CLASSES = %w[Array Hash].freeze
+      FLOORED_CLASSES = %w[Array Hash String].freeze
+
+      NO_ARG_NODES = [].freeze
+      private_constant :COLLECTION_CLASSES, :FLOORED_CLASSES, :NO_ARG_NODES
+
+      module_function
+
+      # @param sites — in-place mutation nodes whose receiver, or an element read their receiver starts from, can
+      #   evaluate to the binding `type` describes, and {CalleeStore}s whose call passes that binding.
+      # @return `type` widened through every site; `type` itself when no site's widening applies.
+      def widen(type, sites)
+        sites.reduce(type) { |acc, site| widen_site(acc, site) || acc }
+      end
+
+      # `type` widened through one site, or `nil` when its widening declines.
+      def widen_site(type, site)
+        return content_floor(type) if site.is_a?(CalleeStore)
+
+        method_name, arg_types = unknown_store(site)
+        path = ElementReadWidening.element_read_path(site.receiver)
+        return widen_store(type, method_name, arg_types) if path.nil?
+
+        ElementReadWidening.widen_through_path(type, path.last, method_name, arg_types) do |element|
+          widen_store(element, method_name, arg_types)
+        end
+      end
+
+      # The straight-line widening of `type` under `method_name`, with the gradual arm on every site that can store.
+      def widen_store(type, method_name, arg_types)
+        widened = MutationWidening.widen_for_mutator(type, method_name, arg_types: arg_types)
+        return nil if widened.nil?
+
+        VALUE_PRESERVING.include?(method_name) && !literal_carrier?(type) ? widened : gradual_content(widened)
+      end
+
+      # Every `Array` / `Hash` / `String` carrier `type` can be as its bare carrier: `Array[Dynamic[top]]`,
+      # `Hash[Dynamic[top], Dynamic[top]]`, `String`. A literal, a nominal (a precise one included) and a refinement
+      # over one ({.carrier_class}) all floor; so `non-empty-string`, which a callee can empty, reads `String`.
+      # Unlike the escaping floor (`StatementEvaluator#content_floor_for`), which answers one carrier for a whole
+      # `Union`, this floors a `Union` member by member, so a member no callee can fill (`nil`) stays: the binding
+      # stands where the entry binding stood, and dropping a member would narrow it. Anything else is returned
+      # untouched.
+      def content_floor(type)
+        return Type::Combinator.union(*type.members.map { |member| content_floor(member) }) if type.is_a?(Type::Union)
+
+        carrier = carrier_class(type)
+        carrier ? carrier_floor(carrier) : type
+      end
+
+      # `"Array"`, `"Hash"` or `"String"` when `type` is a form of that carrier — a literal, a nominal, or a
+      # difference, refinement or intersection over one (`non-empty-array[Integer]`, `decimal-int-string`,
+      # `non-empty-uppercase-string`) — else nil.
+      def carrier_class(type)
+        case type
+        when Type::Tuple then "Array"
+        when Type::HashShape then "Hash"
+        when Type::Constant then "String" if type.value.is_a?(String)
+        when Type::Nominal then type.class_name if FLOORED_CLASSES.include?(type.class_name)
+        when Type::Difference, Type::Refined then carrier_class(type.base)
+        when Type::Intersection then intersection_carrier_class(type)
+        end
+      end
+
+      def intersection_carrier_class(type)
+        type.members.each do |member|
+          carrier = carrier_class(member)
+          return carrier if carrier
+        end
+        nil
+      end
+
+      def carrier_floor(class_name)
+        return Type::Combinator.nominal_of("String") if class_name == "String"
+
+        arity = class_name == "Hash" ? 2 : 1
+        Type::Combinator.nominal_of(class_name, type_args: Array.new(arity) { Type::Combinator.untyped })
+      end
+
+      # A carrier that still records its slots or keys: a `Tuple` / `HashShape`, alone or as a `Union` member.
+      def literal_carrier?(type)
+        case type
+        when Type::Tuple, Type::HashShape then true
+        when Type::Union then type.members.any? { |member| literal_carrier?(member) }
+        else false
+        end
+      end
+
+      # `[mutator, arg_types]` for one site: a call stores through its own name and arguments, an index write
+      # through `[]=` with its index arguments ahead of the value. A splat stays the `nil` arity marker the
+      # `[]=` splice classifier reads.
+      def unknown_store(site)
+        arguments = site.arguments&.arguments || NO_ARG_NODES
+        unknown = arguments.map { |arg| arg.is_a?(Prism::SplatNode) ? nil : Type::Combinator.untyped }
+        return [site.name, unknown] if site.is_a?(Prism::CallNode)
+
+        [:[]=, unknown + [Type::Combinator.untyped]]
+      end
+
+      # An `Array` / `Hash` nominal (alone, as a `Union` member, or as a refinement's base) with a value-pinned type
+      # argument. `Type::Combinator.widen_value_pinned` does not look inside type arguments, so each one is asked on
+      # its own. A `bool` or a literal union a signature declared (`Array[:a | :b]`) counts as pinned too; the arm it
+      # takes can only quiet a report, which is the accepted cost of reading every such binding past one iteration.
+      # A class-level argument (`Array[Integer]`) is not pinned: a store of the same class leaves it true, which is
+      # the claim this seam may not grow.
+      def value_pinned_collection?(type)
+        case type
+        when Type::Union then type.members.any? { |member| value_pinned_collection?(member) }
+        when Type::Difference then value_pinned_collection?(type.base)
+        when Type::Nominal
+          COLLECTION_CLASSES.include?(type.class_name) &&
+            type.type_args.any? { |arg| Type::Combinator.widen_value_pinned(arg) != arg }
+        else false
+        end
+      end
+
+      # Every type argument of an `Array` / `Hash` carrier joined with `Dynamic[top]`, member-wise through a
+      # `Union` and through a `Difference`'s base. Anything else is returned untouched.
+      def gradual_content(type)
+        case type
+        when Type::Union then Type::Combinator.union(*type.members.map { |member| gradual_content(member) })
+        when Type::Difference then Type::Combinator.difference(gradual_content(type.base), type.removed)
+        when Type::Nominal
+          return type unless COLLECTION_CLASSES.include?(type.class_name) && !type.type_args.empty?
+
+          Type::Combinator.nominal_of(
+            type.class_name,
+            type_args: type.type_args.map { |arg| Type::Combinator.union(arg, Type::Combinator.untyped) }
+          )
+        else type
+        end
+      end
+    end
+  end
+end