rigortype 0.0.9 → 0.1.1

data/lib/rigor/flow_contribution/merger.rb

@@ -0,0 +1,275 @@
+# frozen_string_literal: true
+
+module Rigor
+  class FlowContribution
+    # Composes any number of {FlowContribution} bundles into a
+    # single {MergeResult} per ADR-2 § "Plugin Contribution
+    # Merging". The merger is the **single point of integration**
+    # the analyzer uses to combine contributions from built-in
+    # narrowing rules, `RBS::Extended` annotations, and plugins;
+    # slice 4 routes the existing internal narrowing through it
+    # and slice 6 wires plugin-side cache producers around it.
+    #
+    # ## Authority tiers
+    #
+    # - Tier 0: `:builtin` — Core Ruby semantics and accepted RBS
+    #   contracts. Authoritative; lower tiers may not contradict.
+    # - Tier 1: `:rbs_extended` (`RBS::Extended` directive bundles,
+    #   v0.0.9 group D reference impl) and `:generated` (generated
+    #   signatures / metadata).
+    # - Tier 2: `:plugin` and `plugin.<id>` source families.
+    # - Tier 3: anything else — treated as the lowest tier.
+    #
+    # Within a tier, contributions are merged in deterministic
+    # order: provenance-supplied `plugin_id` alphabetical (nil
+    # plugin ids sort first to keep `:rbs_extended` / `:generated`
+    # pre-plugin contributions stable), then by their original
+    # input position as the final tie-break.
+    #
+    # ## Composition rules (ADR-2)
+    #
+    # - `:return_type` — Intersect via `Type::Combinator.intersection`;
+    #   collapse to bot raises `:return_type_collapse`.
+    # - `:truthy_fact` / `:falsey_fact` / `:post_return_fact` —
+    #   Edge-local; accumulate while deduping by payload equality.
+    # - `:mutation` / `:invalidation` / `:role` — Union; dedupe by
+    #   equality.
+    # - `:exception` — Single-valued. Two non-`nil` non-equal
+    #   exceptional effects raise `:exceptional_disagreement`.
+    #
+    # ## Cross-tier contradictions
+    #
+    # Lower tiers may refine higher tiers but must not weaken them.
+    # Slice 3 surfaces contradictions through `:lower_tier_contradiction`
+    # when:
+    #
+    # - the higher tier already pinned a `return_type` and a lower
+    #   tier's intersection collapses to `bot`;
+    # - the higher tier set `exceptional` to a non-`nil` value and a
+    #   lower tier disagrees.
+    #
+    # In every conflict case the result keeps the higher-tier value
+    # for that slot, records a {Conflict} with both provenances, and
+    # continues processing the remaining slots / contributions.
+    module Merger # rubocop:disable Metrics/ModuleLength
+      AUTHORITY_TIERS = {
+        builtin: 0,
+        rbs_extended: 1,
+        generated: 1
+      }.freeze
+
+      module_function
+
+      # @param contributions [Array<FlowContribution>]
+      # @return [MergeResult]
+      def merge(contributions)
+        contributions = Array(contributions)
+        return MergeResult.new if contributions.empty?
+
+        ordered = order_contributions(contributions)
+        state = MergeState.new
+        ordered.each do |contribution|
+          tier = tier_for(contribution.provenance)
+          fold_into(state, contribution, tier)
+        end
+        state.to_result
+      end
+
+      def tier_for(provenance)
+        family = provenance.respond_to?(:source_family) ? provenance.source_family : nil
+        return AUTHORITY_TIERS[family] if AUTHORITY_TIERS.key?(family)
+        return 2 if family == :plugin || family.to_s.start_with?("plugin.")
+
+        3
+      end
+
+      class << self
+        private
+
+        def order_contributions(contributions)
+          # Stable sort: tier ascending, then provenance plugin_id
+          # alphabetical (nil first), then original input position.
+          contributions.each_with_index
+                       .sort_by { |c, i| [tier_for(c.provenance), plugin_id_key(c.provenance), i] }
+                       .map { |c, _| c }
+        end
+
+        def plugin_id_key(provenance)
+          id = provenance.respond_to?(:plugin_id) ? provenance.plugin_id : nil
+          [id.nil? ? 0 : 1, id.to_s]
+        end
+
+        def fold_into(state, contribution, tier)
+          state.add_provenance(contribution.provenance)
+          fold_return_type(state, contribution, tier)
+          fold_facts(state, contribution)
+          fold_effects(state, contribution)
+          fold_exceptional(state, contribution, tier)
+          fold_role_conformance(state, contribution)
+        end
+
+        def fold_return_type(state, contribution, tier) # rubocop:disable Metrics/AbcSize
+          incoming = contribution.return_type
+          return if incoming.nil?
+
+          if state.return_type.nil?
+            state.return_type = incoming
+            state.return_type_tier = tier
+            state.return_type_provenance = contribution.provenance
+            return
+          end
+
+          if intersection_empty?(state.return_type, incoming)
+            reason = tier > state.return_type_tier ? :lower_tier_contradiction : :return_type_collapse
+            state.conflicts << build_conflict(
+              target: :return,
+              edge: :normal,
+              kind: :return_type,
+              reason: reason,
+              provenances: [state.return_type_provenance, contribution.provenance],
+              message: return_type_conflict_message(reason, state.return_type, incoming)
+            )
+            return
+          end
+
+          state.return_type = Rigor::Type::Combinator.intersection(state.return_type, incoming)
+          state.return_type_tier = [state.return_type_tier, tier].min
+        end
+
+        # Two types' intersection collapses to bot when neither
+        # accepts the other under gradual mode — i.e. the value
+        # domains are disjoint. `Rigor::Type::Combinator.intersection`
+        # itself does not collapse incompatible nominals (`String ∩
+        # Integer` builds a structurally-empty `Intersection`
+        # carrier), so the merger checks the disjointness condition
+        # directly via the `accepts` trinary.
+        def intersection_empty?(lhs, rhs)
+          return false if lhs.equal?(rhs)
+
+          lhs_no = lhs.accepts(rhs).no?
+          rhs_no = rhs.accepts(lhs).no?
+          lhs_no && rhs_no
+        rescue StandardError
+          false
+        end
+
+        def fold_facts(state, contribution)
+          accumulate(state.truthy_facts, contribution.truthy_facts)
+          accumulate(state.falsey_facts, contribution.falsey_facts)
+          accumulate(state.post_return_facts, contribution.post_return_facts)
+        end
+
+        def fold_effects(state, contribution)
+          accumulate(state.mutations, contribution.mutations)
+          accumulate(state.invalidations, contribution.invalidations)
+        end
+
+        def fold_exceptional(state, contribution, tier)
+          incoming = contribution.exceptional
+          return if incoming.nil?
+
+          if state.exceptional.nil?
+            state.exceptional = incoming
+            state.exceptional_tier = tier
+            state.exceptional_provenance = contribution.provenance
+            return
+          end
+
+          return if state.exceptional == incoming
+
+          reason = tier > state.exceptional_tier ? :lower_tier_contradiction : :exceptional_disagreement
+          state.conflicts << build_conflict(
+            target: :raise,
+            edge: :exceptional,
+            kind: :exception,
+            reason: reason,
+            provenances: [state.exceptional_provenance, contribution.provenance],
+            message: "exceptional effect disagreement: #{state.exceptional.inspect} vs #{incoming.inspect}"
+          )
+        end
+
+        def fold_role_conformance(state, contribution)
+          accumulate(state.role_conformance, contribution.role_conformance)
+        end
+
+        def accumulate(target, incoming)
+          Array(incoming).each do |item|
+            target << item unless target.include?(item)
+          end
+        end
+
+        def build_conflict(target:, edge:, kind:, reason:, provenances:, message:) # rubocop:disable Metrics/ParameterLists
+          Conflict.new(target: target, edge: edge, kind: kind, reason: reason,
+                       provenances: provenances, message: message)
+        end
+
+        def return_type_conflict_message(reason, lhs, rhs)
+          case reason
+          when :return_type_collapse
+            "return-type intersection collapses to bot: #{describe(lhs)} vs #{describe(rhs)}"
+          when :lower_tier_contradiction
+            "lower-tier return-type #{describe(rhs)} contradicts higher-tier proof #{describe(lhs)}"
+          end
+        end
+
+        def describe(type)
+          if type.respond_to?(:describe)
+            type.describe(:short)
+          else
+            type.inspect
+          end
+        rescue StandardError
+          type.inspect
+        end
+      end
+
+      # Internal accumulator carried through a single merge call.
+      # Not part of the public API; folds into a {MergeResult} at
+      # the end via {#to_result}.
+      class MergeState
+        attr_accessor :return_type, :return_type_tier, :return_type_provenance,
+                      :exceptional, :exceptional_tier, :exceptional_provenance
+        attr_reader :truthy_facts, :falsey_facts, :post_return_facts,
+                    :mutations, :invalidations, :role_conformance,
+                    :provenances, :conflicts
+
+        def initialize
+          @return_type = nil
+          @return_type_tier = nil
+          @return_type_provenance = nil
+          @truthy_facts = []
+          @falsey_facts = []
+          @post_return_facts = []
+          @mutations = []
+          @invalidations = []
+          @exceptional = nil
+          @exceptional_tier = nil
+          @exceptional_provenance = nil
+          @role_conformance = []
+          @provenances = []
+          @conflicts = []
+        end
+
+        def add_provenance(provenance)
+          @provenances << provenance
+        end
+
+        def to_result
+          MergeResult.new(
+            return_type: @return_type,
+            truthy_facts: @truthy_facts,
+            falsey_facts: @falsey_facts,
+            post_return_facts: @post_return_facts,
+            mutations: @mutations,
+            invalidations: @invalidations,
+            exceptional: @exceptional,
+            role_conformance: @role_conformance,
+            provenances: @provenances,
+            conflicts: @conflicts
+          )
+        end
+      end
+      private_constant :MergeState
+    end
+  end
+end

data/lib/rigor/flow_contribution.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "flow_contribution/element"
+
 module Rigor
   # The public packaging of a flow contribution at a single call edge.
   # Plugins, `RBS::Extended` annotations, and built-in narrowing rules
@@ -101,6 +103,40 @@ module Rigor
       end
     end
 
+    # Flattens this bundle into a tagged element list keyed by
+    # `(target, edge, kind)`. The flattening is mechanical and
+    # round-trippable through {Merger.merge}: feeding the result
+    # back through the merger produces an equivalent bundle.
+    #
+    # Layout:
+    #
+    # | slot                | edge          | kind                | target                  |
+    # | --------------------|---------------|---------------------|-------------------------|
+    # | return_type         | normal        | return_type         | :return                 |
+    # | truthy_facts        | truthy        | truthy_fact         | (per-fact target)       |
+    # | falsey_facts        | falsey        | falsey_fact         | (per-fact target)       |
+    # | post_return_facts   | post_return   | post_return_fact    | (per-fact target)       |
+    # | mutations           | normal        | mutation            | (per-mutation target)   |
+    # | invalidations       | normal        | invalidation        | (per-fact target)       |
+    # | exceptional         | exceptional   | exception           | :raise                  |
+    # | role_conformance    | normal        | role                | (per-role target)       |
+    #
+    # @return [Array<Element>]
+    def to_element_list # rubocop:disable Metrics/AbcSize,Metrics/CyclomaticComplexity,Metrics/PerceivedComplexity
+      elements = []
+      elements << element_for(:return, :normal, :return_type, return_type) unless return_type.nil?
+      Array(truthy_facts).each { |fact| elements << element_for(fact_target(fact), :truthy, :truthy_fact, fact) }
+      Array(falsey_facts).each { |fact| elements << element_for(fact_target(fact), :falsey, :falsey_fact, fact) }
+      Array(post_return_facts).each do |fact|
+        elements << element_for(fact_target(fact), :post_return, :post_return_fact, fact)
+      end
+      Array(mutations).each { |m| elements << element_for(fact_target(m), :normal, :mutation, m) }
+      Array(invalidations).each { |i| elements << element_for(fact_target(i), :normal, :invalidation, i) }
+      elements << element_for(:raise, :exceptional, :exception, exceptional) unless exceptional.nil?
+      Array(role_conformance).each { |r| elements << element_for(fact_target(r), :normal, :role, r) }
+      elements.freeze
+    end
+
     def ==(other)
       other.is_a?(FlowContribution) && to_h == other.to_h
     end
@@ -112,6 +148,21 @@ module Rigor
 
     private
 
+    def element_for(target, edge, kind, payload)
+      Element.new(target: target, edge: edge, kind: kind, payload: payload, provenance: provenance)
+    end
+
+    # Best-effort target extraction. Payloads that expose a
+    # `#target` accessor (typed-fact carriers, mutation effects)
+    # provide their own; everything else falls through with the
+    # payload itself as the merge key, which keeps deduplication
+    # well-defined for opaque entries.
+    def fact_target(payload)
+      return payload.target if payload.respond_to?(:target)
+
+      payload
+    end
+
     def freeze_collection(value)
       return nil if value.nil?
 

data/lib/rigor/inference/block_parameter_binder.rb

@@ -34,6 +34,12 @@ module Rigor
     # `[1, 2, 3].each { _1 + _2 }` sees `_1`/`_2` typed identically
     # to their explicit `|x, y|` counterparts.
     #
+    # The `it` implicit parameter (Ruby 3.4+) is bound from
+    # `Prism::ItParametersNode`. It is the single-argument cousin of
+    # `_1`: the binder produces `{ it: expected_param_types[0] }` so
+    # the body's `Prism::ItLocalVariableReadNode` lookup sees the same
+    # type as the explicit `|x|` form would.
+    #
     # Block-local declarations after `;` (e.g., `|x; y, z|`) are
     # still skipped — they are explicitly block-local, so the outer
     # scope MUST NOT observe them and the binder leaves them unbound.
@@ -65,6 +71,8 @@ module Rigor
         case params_root
         when Prism::NumberedParametersNode
           bind_numbered_parameters(params_root)
+        when Prism::ItParametersNode
+          bind_it_parameter
         when Prism::BlockParametersNode
           bind_block_parameters(params_root)
         else
@@ -88,6 +96,13 @@ module Rigor
         bindings
       end
 
+      # `{ it.foo }` — Ruby 3.4 `it` is a single-argument implicit
+      # parameter. Always binds the symbol `:it`; `ItLocalVariableReadNode`
+      # in the body looks the binding up by name.
+      def bind_it_parameter
+        { it: positional_type_at(0) }
+      end
+
       def bind_block_parameters(params_root)
         params_node = params_root.parameters
         return {} if params_node.nil?

data/lib/rigor/inference/expression_typer.rb

@@ -65,6 +65,7 @@ module Rigor
         Prism::NilNode => :type_of_nil,
         # Locals
         Prism::LocalVariableReadNode => :local_read,
+        Prism::ItLocalVariableReadNode => :it_read,
         Prism::LocalVariableWriteNode => :type_of_assignment_write,
         # Containers and pass-throughs
         Prism::ArrayNode => :array_type_for,
@@ -171,9 +172,11 @@ module Rigor
         Prism::WhileNode => :type_of_loop,
         Prism::UntilNode => :type_of_loop,
         Prism::ForNode => :type_of_dynamic_top,
-        Prism::DefinedNode => :type_of_dynamic_top,
-        Prism::MatchPredicateNode => :type_of_dynamic_top,
-        Prism::MatchRequiredNode => :type_of_dynamic_top,
+        Prism::DefinedNode => :type_of_defined,
+        Prism::NumberedReferenceReadNode => :type_of_string_or_nil,
+        Prism::BackReferenceReadNode => :type_of_string_or_nil,
+        Prism::MatchPredicateNode => :type_of_match_predicate,
+        Prism::MatchRequiredNode => :type_of_match_required,
         Prism::MatchWriteNode => :type_of_dynamic_top,
         # Literal containers
         Prism::LambdaNode => :type_of_lambda,
@@ -298,6 +301,45 @@ module Rigor
         dynamic_top
       end
 
+      # `defined?(expr)` returns `String | nil` per Ruby semantics —
+      # a description of the expression's category (`"local-variable"`,
+      # `"method"`, ...) when defined, or `nil` when not. The argument
+      # is not evaluated (it is statically inspected by the runtime),
+      # so the typer does not recurse into it.
+      def type_of_defined(_node)
+        Type::Combinator.union(
+          Type::Combinator.nominal_of("String"),
+          Type::Combinator.constant_of(nil)
+        )
+      end
+
+      # `$1`, `$&`, `$'`, `$+`, `$\`` — the regex back-reference and
+      # numbered-capture globals each carry `String | nil`. They share
+      # the typer because the typing rule is identical regardless of
+      # which back-reference shape Prism emitted.
+      def type_of_string_or_nil(_node)
+        Type::Combinator.union(
+          Type::Combinator.nominal_of("String"),
+          Type::Combinator.constant_of(nil)
+        )
+      end
+
+      # `expr in pattern` — pattern-match predicate. Returns `true`
+      # when the pattern matches, `false` otherwise.
+      def type_of_match_predicate(_node)
+        Type::Combinator.union(
+          Type::Combinator.constant_of(true),
+          Type::Combinator.constant_of(false)
+        )
+      end
+
+      # `expr => pattern` — one-line pattern-match assertion. Raises
+      # `NoMatchingPatternError` on mismatch; on success the expression
+      # itself evaluates to `nil`.
+      def type_of_match_required(_node)
+        Type::Combinator.constant_of(nil)
+      end
+
       # The expression `Foo` evaluates to the *class object* `Foo`, not
       # an instance. From Slice 4 phase 2b on we therefore type a
       # bare-constant reference as `Singleton[Foo]`; method dispatch on
@@ -723,9 +765,38 @@ module Rigor
       def type_of_range(node)
         left_static, left = static_range_endpoint(node.left)
         right_static, right = static_range_endpoint(node.right)
-        return Type::Combinator.nominal_of(Range) unless left_static && right_static
+        return Type::Combinator.constant_of(Range.new(left, right, node.exclude_end?)) if left_static && right_static
 
-        Type::Combinator.constant_of(Range.new(left, right, node.exclude_end?))
+        nominal_range_for_endpoints(node.left, node.right)
+      end
+
+      # Derives `Nominal[Range, [T]]` from the endpoint expression
+      # types when at least one endpoint is statically typeable. The
+      # element parameter is the union of the endpoint types (lifted
+      # from `Constant<v>` to `Nominal<v.class>` so the carrier matches
+      # what `Range#each` would yield). Falls back to bare
+      # `Nominal[Range]` when no endpoint contributes a typable shape.
+      def nominal_range_for_endpoints(left_node, right_node)
+        endpoints = [left_node, right_node].compact.map { |n| range_endpoint_element_type(n) }
+        endpoints.reject! { |t| t.equal?(Type::Combinator.untyped) }
+        return Type::Combinator.nominal_of("Range") if endpoints.empty?
+
+        Type::Combinator.nominal_of("Range", type_args: [Type::Combinator.union(*endpoints)])
+      end
+
+      def range_endpoint_element_type(node)
+        type = type_of(node)
+        case type
+        when Type::Constant
+          value = type.value
+          return Type::Combinator.untyped if value.nil?
+
+          Type::Combinator.nominal_of(value.class.name)
+        when Type::IntegerRange
+          Type::Combinator.nominal_of("Integer")
+        else
+          type
+        end
       end
 
       # v0.0.7 — non-interpolated regex literals lift to
@@ -746,6 +817,7 @@ module Rigor
       def static_range_endpoint(node)
         return [true, nil] if node.nil?
         return [true, node.value] if node.is_a?(Prism::IntegerNode)
+        return [true, node.unescaped] if node.is_a?(Prism::StringNode) && node.respond_to?(:unescaped)
 
         [false, nil]
       end
@@ -805,6 +877,13 @@ module Rigor
         scope.local(node.name) || dynamic_top
       end
 
+      # `it` (Ruby 3.4) — `ItLocalVariableReadNode` carries no `name`
+      # field; the implicit name is always `:it`, matching the binding
+      # `BlockParameterBinder` installs for `Prism::ItParametersNode`.
+      def it_read(_node)
+        scope.local(:it) || dynamic_top
+      end
+
       # Slice 5 phase 1 upgrades array literals to `Tuple[T1..Tn]`
       # when every element is a non-splat value. Splatted entries
       # (`[*xs, 1]`) preserve the Slice 4 phase 2d behavior: we union
@@ -902,7 +981,9 @@ module Rigor
           method_name: node.name,
           arg_types: arg_types,
           block_type: block_type,
-          environment: scope.environment
+          environment: scope.environment,
+          call_node: node,
+          scope: scope
         )
         return result if result
 

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

@@ -42,14 +42,45 @@ module Rigor
         }.freeze
         private_constant :NUMERIC_CONSTRUCTORS
 
+        # `Kernel#Integer(s)` predicate-aware refinement set
+        # (v0.1.1 Track 1 slice 2b). Both `decimal-int-string` and
+        # `numeric-string` describe digit-only ASCII strings, so
+        # `Integer(s)` is total over the carrier domain and the
+        # result is `>= 0`. The default `base: 10` invocation
+        # accepts the same shape `String#to_i` does for these
+        # predicates; the `Integer(s, base)` overload is left for
+        # a later slice.
+        INTEGER_REFINEMENT_PREDICATES = Set[:decimal_int, :numeric].freeze
+        private_constant :INTEGER_REFINEMENT_PREDICATES
+
         def try_dispatch(receiver:, method_name:, args:)
           return nil if receiver.nil?
           return try_array(args) if method_name == :Array
           return try_numeric_constructor(method_name, args) if NUMERIC_CONSTRUCTORS.key?(method_name)
+          return try_integer_from_refinement(args) if method_name == :Integer
 
           nil
         end
 
+        # `Kernel#Integer(s)` over a `Refined[String, predicate]`
+        # whose predicate is in {INTEGER_REFINEMENT_PREDICATES}.
+        # Mirrors the `String#to_i` projection in `ShapeDispatch`
+        # (v0.1.1 slice 2a) — the result is always
+        # `non-negative-int`. Returns nil for any other arg shape
+        # so the RBS tier handles the generic `Integer(arg)` case.
+        def try_integer_from_refinement(args)
+          return nil unless args.size == 1
+
+          arg = args.first
+          return nil unless arg.is_a?(Type::Refined)
+
+          base = arg.base
+          return nil unless base.is_a?(Type::Nominal) && base.class_name == "String"
+          return nil unless INTEGER_REFINEMENT_PREDICATES.include?(arg.predicate_id)
+
+          Type::Combinator.non_negative_int
+        end
+
         def try_array(args)
           return nil if args.length != 1