rigortype 0.0.9 → 0.1.0

data/lib/rigor/flow_contribution/element.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Rigor
+  class FlowContribution
+    # Tagged element flattening of a {FlowContribution} bundle —
+    # the analyzer-internal representation [ADR-2 § "Flow
+    # Contribution Bundle"](../../../docs/adr/2-extension-api.md)
+    # routes through the {Merger}.
+    #
+    # The flattening is **mechanical, deterministic, and round-
+    # trippable** with the bundle: every non-empty slot expands
+    # into one or more elements keyed by `(target, edge, kind)`,
+    # and an array of elements rebuilds an equivalent bundle when
+    # routed through `Merger.merge`.
+    #
+    # Plugin authors should not depend on the element shape — the
+    # bundle is the public contract; the element list is the
+    # implementation surface the merge policy operates over.
+    ELEMENT_VALID_EDGES = %i[normal truthy falsey post_return exceptional].freeze
+    ELEMENT_VALID_KINDS = %i[
+      return_type
+      truthy_fact
+      falsey_fact
+      post_return_fact
+      mutation
+      invalidation
+      exception
+      role
+    ].freeze
+
+    Element = Data.define(:target, :edge, :kind, :payload, :provenance) do
+      def initialize(target:, edge:, kind:, payload:, provenance:)
+        unless ELEMENT_VALID_EDGES.include?(edge)
+          raise ArgumentError,
+                "FlowContribution::Element edge must be one of " \
+                "#{ELEMENT_VALID_EDGES.inspect}, got #{edge.inspect}"
+        end
+
+        unless ELEMENT_VALID_KINDS.include?(kind)
+          raise ArgumentError,
+                "FlowContribution::Element kind must be one of " \
+                "#{ELEMENT_VALID_KINDS.inspect}, got #{kind.inspect}"
+        end
+
+        super
+      end
+
+      def merge_key
+        [target, edge, kind]
+      end
+    end
+  end
+end

data/lib/rigor/flow_contribution/fact.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module Rigor
+  class FlowContribution
+    # Canonical slot payload for the four edge-aware fact slots
+    # (`truthy_facts`, `falsey_facts`, `post_return_facts`, plus
+    # the equivalent under `mutations` / `invalidations` /
+    # `role_conformance` once those carriers grow Fact-shaped
+    # variants).
+    #
+    # ADR-7 § "Slice 4-A" pins this object as the **single
+    # canonical translation target** for the four parallel
+    # contribution carriers the engine has carried so far:
+    #
+    # 1. Built-in narrowing rules' direct fact emission
+    #    (Inference::Narrowing#predicate_scopes).
+    # 2. RBS::Extended `predicate-if-*` directives
+    #    (`Rigor::RbsExtended::PredicateEffect`).
+    # 3. RBS::Extended `assert*` directives
+    #    (`Rigor::RbsExtended::AssertEffect`).
+    # 4. Future plugin contributions (slice 5 emission protocol).
+    #
+    # Each of those four carriers translates to / from Fact at
+    # its boundary; downstream of {Rigor::FlowContribution#to_element_list}
+    # and {Rigor::FlowContribution::Merger.merge}, every slot
+    # payload is a Fact (or a value that the merger compares by
+    # equality and never inspects). The typed `RbsExtended::*Effect`
+    # carriers stay internal to the parser side — they hold the
+    # source-text shape, but lose their identity at the
+    # `read_flow_contribution` boundary.
+    #
+    # ## Field set
+    #
+    # - `target_kind`: `:parameter` (call-site argument) or
+    #   `:self` (receiver). Future slices may extend the set
+    #   (`:local`, `:ivar`, `:result`); the merger is agnostic
+    #   to the concrete kinds and only requires equality.
+    # - `target_name`: a `Symbol`. For `:parameter` it's the
+    #   declared parameter name. For `:self` it is the literal
+    #   `:self` symbol so the field stays non-nil and the merge
+    #   key is well-defined.
+    # - `type`: a `Rigor::Type::*` (Nominal, Refined,
+    #   IntegerRange, Difference, …) the fact narrows the
+    #   target toward (when `negative` is false) or away from
+    #   (when `negative` is true).
+    # - `negative`: `true` for the `~T` negation form
+    #   (`predicate-if-true x is ~Integer`), `false` for the
+    #   plain positive form. Mirrors the `negative` field on
+    #   `PredicateEffect` / `AssertEffect`.
+    #
+    # The `target` accessor returns `:self` for self-targeted
+    # facts and `[:parameter, name]` otherwise — that's the
+    # value {Element#target} keys on, so two facts that narrow
+    # the same parameter from different contribution sources
+    # land in the same merge bucket.
+    FACT_VALID_TARGET_KINDS = %i[parameter self].freeze
+
+    Fact = Data.define(:target_kind, :target_name, :type, :negative) do
+      def initialize(target_kind:, target_name:, type:, negative: false)
+        unless FACT_VALID_TARGET_KINDS.include?(target_kind)
+          raise ArgumentError,
+                "FlowContribution::Fact target_kind must be one of " \
+                "#{FACT_VALID_TARGET_KINDS.inspect}, got #{target_kind.inspect}"
+        end
+
+        unless target_name.is_a?(Symbol)
+          raise ArgumentError,
+                "FlowContribution::Fact target_name must be a Symbol, got #{target_name.inspect}"
+        end
+
+        super
+      end
+
+      # Composite target identifier the merger keys on. `:self`
+      # for self-targeted facts; otherwise `[:parameter, name]`
+      # so two contributions that narrow the same parameter
+      # (regardless of source family) land in the same merge
+      # bucket.
+      def target
+        target_kind == :self ? :self : [target_kind, target_name]
+      end
+
+      def negative?
+        negative == true
+      end
+    end
+  end
+end

data/lib/rigor/flow_contribution/merge_result.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module Rigor
+  class FlowContribution
+    # Result of folding any number of {FlowContribution} bundles
+    # through {Merger.merge}. Surfaces the merged content slot-by-
+    # slot, the ordered list of contributing provenances, and the
+    # {Conflict} list collected along the way.
+    #
+    # The merge result is a sibling shape of {FlowContribution} —
+    # the analyzer reads from it to drive narrowing / dispatch /
+    # diagnostics, and the formatter reads from it to surface
+    # plugin / RBS::Extended provenance. The shape is derived per
+    # ADR-2 § "Plugin Contribution Merging"; see
+    # [`docs/internal-spec/flow-contribution-merger.md`](../../../docs/internal-spec/flow-contribution-merger.md)
+    # for the slice-3 normative description.
+    class MergeResult
+      attr_reader :return_type, :truthy_facts, :falsey_facts, :post_return_facts,
+                  :mutations, :invalidations, :exceptional, :role_conformance,
+                  :provenances, :conflicts
+
+      # rubocop:disable Metrics/ParameterLists
+      def initialize(return_type: nil, truthy_facts: [], falsey_facts: [],
+                     post_return_facts: [], mutations: [], invalidations: [],
+                     exceptional: nil, role_conformance: [],
+                     provenances: [], conflicts: [])
+        # rubocop:enable Metrics/ParameterLists
+        @return_type = return_type
+        @truthy_facts = truthy_facts.dup.freeze
+        @falsey_facts = falsey_facts.dup.freeze
+        @post_return_facts = post_return_facts.dup.freeze
+        @mutations = mutations.dup.freeze
+        @invalidations = invalidations.dup.freeze
+        @exceptional = exceptional
+        @role_conformance = role_conformance.dup.freeze
+        @provenances = provenances.dup.freeze
+        @conflicts = conflicts.dup.freeze
+        freeze
+      end
+
+      def conflict?
+        !@conflicts.empty?
+      end
+
+      def empty? # rubocop:disable Metrics/CyclomaticComplexity
+        @return_type.nil? && @truthy_facts.empty? && @falsey_facts.empty? &&
+          @post_return_facts.empty? && @mutations.empty? && @invalidations.empty? &&
+          @exceptional.nil? && @role_conformance.empty?
+      end
+
+      def to_h
+        {
+          "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.map { |p| p.respond_to?(:to_h) ? p.to_h : p },
+          "conflicts" => conflicts.map(&:to_h)
+        }
+      end
+    end
+  end
+end

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?