rigortype 0.3.2 → 0.3.4

data/lib/rigor/effects/label_set.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+require_relative "label"
+
+module Rigor
+  module Effects
+    # An immutable, sorted, de-duplicated set of effect labels — the carrier of a summary lane and
+    # of an envelope's bound (ADR-103 WD1).
+    #
+    # Two sentinels bracket the lattice. {EMPTY} is the empty set: "no effects", the reading of
+    # `%a{pure}` modulo `mutate.local`. {TOP} is the unbounded / unspecified reading: it admits
+    # every label, it absorbs every join, and it is what a tag carrying an unknown label degrades
+    # to (the fail-open rule). {TOP} is NOT the set of all registered labels and is deliberately
+    # not enumerable — `top?` is the only way to tell it from {EMPTY} through `to_a`.
+    #
+    # Instances are frozen on construction and hold a frozen array, so they cross a Ractor boundary
+    # and go into a cache entry as they are.
+    class LabelSet
+      NO_LABELS = [].freeze
+      private_constant :NO_LABELS
+
+      # Build a set from any enumerable of label strings. Members are normalised (de-duplicated and
+      # sorted) so equality is structural and a snapshot rendering is deterministic.
+      #
+      # Raises `ArgumentError` on a member that does not satisfy {Label::PATTERN}: a LabelSet is a
+      # value object over the grammar, and the fail-open handling of an unrecognised *spelling* is
+      # the reader's job (it yields {TOP}), not this constructor's.
+      #
+      # `top:` is internal — it exists to build {TOP} and is not part of the surface later slices
+      # build on.
+      def initialize(labels = NO_LABELS, top: false)
+        @top = top
+        @labels = NO_LABELS
+        unless top
+          members = labels.to_a
+          members.each do |label|
+            raise ArgumentError, "not a well-formed effect label: #{label.inspect}" unless Label.valid?(label)
+          end
+          @labels = members.uniq.sort.freeze
+        end
+        freeze
+      end
+
+      # The unbounded set. Everything is subsumed by it; joining it with anything yields it.
+      TOP = new(NO_LABELS, top: true)
+
+      # The empty set — no effects at all.
+      EMPTY = new(NO_LABELS)
+
+      # Whether this is the unbounded sentinel {TOP}.
+      def top?
+        @top
+      end
+
+      # Whether this set records no labels. {TOP} is not empty: it records nothing because it
+      # stands for everything.
+      def empty?
+        !@top && @labels.empty?
+      end
+
+      # The members, sorted, as a frozen array. {TOP} yields `[]` — consult {top?} first.
+      def to_a
+        @labels
+      end
+
+      # Exact membership among the recorded labels. `LabelSet.new(["io"]).include?("io.net")` is
+      # false — that question is {admits?}. {TOP} records no members, so it includes none.
+      def include?(label)
+        @labels.include?(label)
+      end
+
+      # Whether some member of this set subsumes `label`. {TOP} admits every well-formed label.
+      def admits?(label)
+        return Label.valid?(label) if @top
+
+        @labels.any? { |member| Label.subsumes?(member, label) }
+      end
+
+      # Union. {TOP} absorbs: a join involving it is {TOP}.
+      #
+      # A join that adds nothing returns `self` **without allocating**. That is the common case wherever
+      # sets are joined in a loop — the propagator's fixpoint re-joins every edge on every visit — and the
+      # sets are single-digit-sized, so the containment scan is cheaper than the construction it avoids.
+      def join(other)
+        return TOP if @top || other.top?
+        return other if @labels.empty?
+
+        others = other.to_a
+        return self if others.empty?
+        return self if others.all? { |label| @labels.include?(label) }
+
+        self.class.new(@labels + others)
+      end
+
+      # The members `other` does not already admit — the **declared lane's rendering rule**. A declared
+      # `io.net.http` beside a proven `io.net` says nothing the proven lane did not already say more
+      # strongly, so a renderer drops it rather than printing `[io.net] ≤ [io.net.http]`, which reads as
+      # two facts where there is one. Applied where output is produced, never to the table: the lanes
+      # themselves stay raw, because a later join has to see what was actually declared.
+      def excluding_subsumed_by(other)
+        return self if @top || other.empty?
+
+        kept = @labels.reject { |label| other.admits?(label) }
+        return self if kept.length == @labels.length
+
+        kept.empty? ? EMPTY : self.class.new(kept)
+      end
+
+      # Whether every member of this set is admitted by `bound_set` — the envelope check, modulo
+      # the policy discharge that happens at judgment time. {TOP} is bounded only by {TOP}.
+      def subsumed_by?(bound_set)
+        return true if bound_set.top?
+        return false if @top
+
+        @labels.all? { |label| bound_set.admits?(label) }
+      end
+
+      def ==(other)
+        return true if equal?(other)
+
+        other.is_a?(LabelSet) && other.top? == @top && other.to_a == @labels
+      end
+      alias eql? ==
+
+      def hash
+        [self.class, @top, @labels].hash
+      end
+
+      def inspect
+        return "#<Rigor::Effects::LabelSet TOP>" if @top
+
+        "#<Rigor::Effects::LabelSet #{@labels.join(', ')}>"
+      end
+    end
+  end
+end

data/lib/rigor/effects/liskov_check.rb

@@ -0,0 +1,167 @@
+# frozen_string_literal: true
+
+require_relative "envelope"
+require_relative "envelope_check"
+require_relative "method_key"
+require_relative "path_finder"
+
+module Rigor
+  module Effects
+    # Judges an override against the envelope it inherits (ADR-103 WD1 / WD14; #386). The one place
+    # `effect.liskov-widened` is decided.
+    #
+    # An envelope is a contract about a method, and Ruby's `class PgRepo < Repo` says a `PgRepo` is
+    # usable wherever a `Repo` is. So a bound written on `Repo#find` binds `PgRepo#find` too:
+    # **implementations may be purer than the bound they inherit, never less pure.** That is Liskov
+    # inclusion applied to the second dimension, and it is what makes the declared lane's nominal carrier
+    # (#386, {EnvelopeIndex}) honest — a caller that imports `≤ io.db` from a `Repo`-typed receiver is
+    # entitled to that bound whichever subclass actually arrives.
+    #
+    # Two comparisons, and an override is subject to exactly one of them:
+    #
+    # - **Proven against the inherited bound** — the override declares nothing of its own, so what it
+    #   *does* is what the ancestor's bound has to admit. It reads the same lane
+    #   {EnvelopeCheck} reads, for the same reasons: the proven closure, undischarged per policy,
+    #   `mutate.local` tolerated, taint ignored.
+    # - **Declared against the inherited bound** — the override declares its own envelope, and a bound
+    #   wider than the one it inherits is a Liskov violation in the *declaration*, before any body is
+    #   consulted. Two authored bounds compared by subsumption; nothing proven enters it.
+    #
+    # The split is exclusive on purpose. An override that declares its own envelope is already held to
+    # that envelope by `effect.envelope-exceeded`, so running the proven comparison too would put two
+    # diagnostics on one line for one label. What the author asserted is the thing Liskov has to judge;
+    # whether the body honours the assertion is the other rule's question.
+    #
+    # Both-sides-authored, in the [ADR-35](../../../docs/adr/35-override-signature-compatibility.md)
+    # sense: nothing fires unless an author wrote an envelope on the ancestor. That is the accepted
+    # construction the false-positive budget is spent under — a firing is never unsolicited.
+    #
+    # **Nominal subclassing only.** An included module's method is not an override in this slice: Ruby's
+    # ancestry puts an includer's own `def` *ahead* of the module's rather than under it, and the
+    # substitutability argument that licenses the check is the subclass one. The `superclasses` table is
+    # the collector's own, as-written and resolved here exactly as {Propagator} resolves it, so the
+    # relation the check reads and the closed world the proven lane travels can never disagree.
+    module LiskovCheck
+      # One (override, exceeding label) pair.
+      #
+      # `own_envelope` is the override's own bound when there is one, which is also what selects the
+      # message variant: present means the declaration-level comparison produced this finding, nil means
+      # the proven one. `chain` / `origin` explain the proven variant and are nil for the other, which
+      # has no path to walk — a declaration is not proved by anything.
+      Finding = Data.define(:key, :label, :ancestor_key, :ancestor_envelope, :own_envelope, :path, :line,
+                            :chain, :origin)
+
+      NO_FINDINGS = [].freeze
+      private_constant :NO_FINDINGS
+
+      module_function
+
+      # @param table [EffectTable] the run's propagated graph.
+      # @param superclasses [Hash{String => Array<String>}] the collector's as-written superclass
+      #   candidate lists (`FileCollection#superclasses`).
+      # @param method_envelopes [Hash{String => Envelope}] per-method envelopes, as written.
+      # @param class_envelopes [Hash{String => Envelope}] class- / module-level envelopes, to distribute.
+      # @param config_envelopes [Hash{String => Envelope}] `effects.envelopes:` entries already resolved
+      #   to the classes they select.
+      # @param positions [EnvelopeCheck::Positions] where the override's `def` is.
+      # @param apply_tolerated [Boolean] false judges against `proven` — `--no-tolerated-effects`.
+      # @return [Array<Finding>] sorted by position then key then label.
+      def run(table:, superclasses:, method_envelopes:, class_envelopes:, config_envelopes: {},
+              positions: EnvelopeCheck::Positions.empty, apply_tolerated: true)
+        # The distributed strata, over a base of the raw per-method annotations: a base class whose method
+        # exists only in `.rbs` — an abstract `def find: (Integer) -> User` with no Ruby body — has no
+        # key in the table and so no distributed entry, and its bound is exactly the one an override
+        # inherits. Distribution wins on collision, which is the same value for a key that has both.
+        envelopes = method_envelopes.merge(
+          EnvelopeCheck.distribute(table, method_envelopes, class_envelopes, config_envelopes)
+        )
+        return NO_FINDINGS if envelopes.empty?
+
+        parents = parent_map(table, superclasses)
+        return NO_FINDINGS if parents.empty?
+
+        findings = []
+        keys = table.keys
+        keys.each { |key| collect(findings, table, key, envelopes, parents, positions, apply_tolerated) }
+        findings.sort_by { |f| [f.path.to_s, f.line, f.key, f.label] }.freeze
+      end
+
+      # `{child class => parent class}`, one parent per child.
+      #
+      # An ancestry name is recorded as written, so `class Loud < Base` inside `module Tracer` arrives as
+      # the candidate list Ruby's own lexical lookup would try, most-qualified first. The most-qualified
+      # candidate the project actually defines wins — the same rule {Propagator::Index#build_descendants}
+      # applies, and for the same reason: without it `A::Base` and `B::Base` would share the bare spelling
+      # `Base` and an unrelated class's envelope would bind an override that never inherited it.
+      def parent_map(table, superclasses)
+        return {} if superclasses.nil? || superclasses.empty?
+
+        known = table.keys.filter_map { |key| MethodKey.owner(key) }.to_set
+        superclasses.each_with_object({}) do |(child, candidates), out|
+          parent = Array(candidates).find { |candidate| known.include?(candidate) }
+          out[child] = parent if parent && parent != child
+        end
+      end
+
+      def collect(findings, table, key, envelopes, parents, positions, apply_tolerated)
+        class_name, separator, selector = MethodKey.split(key)
+        return if class_name.nil?
+
+        ancestor_key = inherited_key(class_name, separator, selector, envelopes, parents)
+        return if ancestor_key.nil?
+
+        inherited = envelopes.fetch(ancestor_key)
+        own = envelopes[key]
+        position = positions.for(key)
+        if own && !own.top?
+          collect_declared(findings, key, ancestor_key, inherited, own, position)
+        else
+          collect_proven(findings, table, key, ancestor_key, inherited, position, apply_tolerated)
+        end
+      end
+
+      # The nearest ancestor whose own method key carries an envelope. Nearest wins for the same reason
+      # it does among strata: a bound written closer to the override is the more specific statement about
+      # it, and a grandparent's bound is already binding on the parent that sits between them.
+      def inherited_key(class_name, separator, selector, envelopes, parents)
+        seen = Set.new([class_name])
+        current = parents[class_name]
+        while current && seen.add?(current)
+          candidate = "#{current}#{separator}#{selector}"
+          return candidate if envelopes.key?(candidate) && !envelopes.fetch(candidate).top?
+
+          current = parents[current]
+        end
+        nil
+      end
+
+      def collect_proven(findings, table, key, ancestor_key, inherited, position, apply_tolerated)
+        entry = table[key]
+        return if entry.nil?
+
+        exceeding = inherited.exceeded_by(apply_tolerated ? entry.undischarged : entry.proven)
+        exceeding.each do |label|
+          trail = PathFinder.shortest(table, symbol: key, label: label)
+          findings << Finding.new(
+            key: key, label: label, ancestor_key: ancestor_key, ancestor_envelope: inherited,
+            own_envelope: nil, path: position.first, line: position.last,
+            chain: trail&.chain || [key].freeze, origin: trail&.origin
+          )
+        end
+      end
+
+      # Two authored bounds, compared by subsumption alone. `mutate.local` is tolerated here as it is
+      # everywhere, so declaring it under an inherited `%a{pure}` is not a widening.
+      def collect_declared(findings, key, ancestor_key, inherited, own, position)
+        own.bound.to_a.reject { |label| inherited.tolerates?(label) }.each do |label|
+          findings << Finding.new(
+            key: key, label: label, ancestor_key: ancestor_key, ancestor_envelope: inherited,
+            own_envelope: own, path: position.first, line: position.last, chain: nil, origin: nil
+          )
+        end
+      end
+
+      private_class_method :parent_map, :collect, :inherited_key, :collect_proven, :collect_declared
+    end
+  end
+end

data/lib/rigor/effects/local_ownership.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+require "prism"
+
+require_relative "../source/node_children"
+
+module Rigor
+  module Effects
+    # Which of a method body's locals the frame **owns** — freshly allocated here and never let out
+    # (ADR-103 WD4; the proof obligations are `control-flow-analysis.md` § Proof obligations).
+    #
+    # Ruby has no by-ref parameters, so `mutate.local` cannot mean "a write into an out-parameter" as it
+    # does in PHP. It means the mutated receiver is invisible to the caller, and that is an ownership
+    # question: a local whose every assignment allocates (`[]`, `{}`, `""`, `.new`, `.dup`) and which never
+    # escapes the body is one no caller can observe being mutated.
+    #
+    # The analysis is deliberately **flow-insensitive and whole-body**: a local that escapes anywhere
+    # disqualifies, even if the escape happens after the mutation. That is strictly more conservative than
+    # the "escaped before the mutating call" reading, which is the direction false positives are budgeted
+    # in ([ADR-5](../adr/5-robustness-principle.md)) — an unproven local mutation becomes an
+    # `unknown-ownership` taint, never a proven `mutate` label.
+    #
+    # This is the tracer slice's approximation, not the eventual answer. `ClosureEscapeAnalyzer` answers a
+    # different question (fact retention, not "does the code contain") and is deliberately left alone.
+    module LocalOwnership
+      # Assignment right-hand sides that witness a fresh allocation. `.new` and `.dup` / `.clone` follow
+      # [ADR-76](../adr/76-effect-modeling-freeze-dup-shape-preservation.md)'s reading of `dup` as the
+      # allocation witness.
+      ALLOCATING_SELECTORS = %i[new dup clone].to_set.freeze
+
+      module_function
+
+      # The set of frame-owned local names in `body`, given the method's parameter names (a parameter is
+      # never frame-owned — the caller holds the same object, so mutating it is `mutate.instance`).
+      def owned(body, parameter_names)
+        return Set.new if body.nil?
+
+        assignments = {}
+        escaped = Set.new
+        collect(body, assignments, escaped)
+        escaped.merge(trailing_reads(body))
+        assignments.filter_map do |name, values|
+          next if escaped.include?(name) || parameter_names.include?(name)
+
+          name if values.all? { |value| allocation?(value) }
+        end.to_set
+      end
+
+      # Whether `node` is an expression that allocates a fresh object this frame is the sole holder of.
+      def allocation?(node)
+        case node
+        when Prism::ArrayNode, Prism::HashNode, Prism::StringNode, Prism::InterpolatedStringNode,
+             Prism::LambdaNode
+          true
+        when Prism::CallNode
+          ALLOCATING_SELECTORS.include?(node.name) || unary_plus_string?(node)
+        else
+          false
+        end
+      end
+
+      # `+""` — the frozen-string-literal era's spelling of "a fresh mutable String".
+      def unary_plus_string?(node)
+        node.name == :+@ && node.receiver.is_a?(Prism::StringNode)
+      end
+
+      def collect(node, assignments, escaped)
+        return unless node.is_a?(Prism::Node)
+
+        record_assignment(node, assignments, escaped)
+        record_escapes(node, escaped)
+        node.rigor_each_child { |child| collect(child, assignments, escaped) }
+      end
+
+      def record_assignment(node, assignments, escaped)
+        case node
+        when Prism::LocalVariableWriteNode
+          (assignments[node.name.to_s] ||= []) << node.value
+          # `y = x` hands the same object to a second name; neither can be proven frame-private cheaply.
+          escaped << node.value.name.to_s if node.value.is_a?(Prism::LocalVariableReadNode)
+        when Prism::LocalVariableOperatorWriteNode, Prism::LocalVariableOrWriteNode,
+             Prism::LocalVariableAndWriteNode, Prism::LocalVariableTargetNode
+          # Not an allocation, and a multi-assign target's value is not statically one either: record a
+          # nil right-hand side so the all-allocations test fails.
+          (assignments[node.name.to_s] ||= []) << nil
+        end
+      end
+
+      # An escape is any position from which a caller could later reach the object: a call argument (the
+      # callee may store it), the right-hand side of a write to state that outlives the frame, an element
+      # of a constructed collection, or an explicit `return`.
+      def record_escapes(node, escaped)
+        case node
+        when Prism::CallNode
+          node.arguments&.arguments&.each { |argument| note_read(argument, escaped) }
+          note_read(node.block.expression, escaped) if node.block.is_a?(Prism::BlockArgumentNode)
+        when Prism::ReturnNode
+          node.arguments&.arguments&.each { |argument| note_read(argument, escaped) }
+        when Prism::ArrayNode
+          node.elements.each { |element| note_read(element, escaped) }
+        else
+          note_read(stored_value(node), escaped)
+        end
+      end
+
+      # The value half of a write into state that outlives the frame, or of a hash entry. nil for every
+      # other node, which {note_read} ignores.
+      def stored_value(node)
+        case node
+        when Prism::AssocNode, Prism::InstanceVariableWriteNode, Prism::ClassVariableWriteNode,
+             Prism::GlobalVariableWriteNode, Prism::ConstantWriteNode
+          node.value
+        end
+      end
+
+      def note_read(node, escaped)
+        escaped << node.name.to_s if node.is_a?(Prism::LocalVariableReadNode)
+      end
+
+      # A body whose value is a bare local read hands that local to the caller. Only the tail matters —
+      # every other position is covered by {record_escapes}.
+      def trailing_reads(body)
+        statements = body.is_a?(Prism::StatementsNode) ? body.body : [body]
+        last = statements.last
+        last.is_a?(Prism::LocalVariableReadNode) ? [last.name.to_s] : []
+      end
+
+      private_class_method :collect, :record_assignment, :record_escapes, :stored_value, :note_read,
+                           :trailing_reads
+    end
+  end
+end

data/lib/rigor/effects/method_key.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Rigor
+  module Effects
+    # The spelling of an effect unit's key, in one place (ADR-103 WD14).
+    #
+    # `Owner#instance_method`, `Owner.singleton_method`, `<toplevel>#bare_def`. The separator is the FIRST
+    # `#` or `.` in the string, which is what makes `Net::HTTP.get` split at the dot rather than inside the
+    # namespace — a namespace carries `::`, never a bare dot, and a selector carries neither.
+    #
+    # This module exists because the split is now written on both sides of a contract: the scanner spells a
+    # key, and `effects.attribution:` in `.rigor.yml` names one. A key the loader accepts and the scanner
+    # would never produce is a table that silently matches nothing.
+    module MethodKey
+      module_function
+
+      # @return [Array(String, String, String), nil] `[owner, separator, selector]`, or nil when `key` is
+      #   not a method key at all.
+      def split(key)
+        text = key.to_s
+        index = text.index("#") || text.index(".")
+        return nil if index.nil? || index.zero? || index == text.length - 1
+
+        [text[0, index], text[index], text[(index + 1)..]]
+      end
+
+      def valid?(key)
+        parts = split(key)
+        return false if parts.nil?
+
+        parts.none? { |part| part.match?(/\s/) }
+      end
+
+      # The owner half, or nil. What `keys_by_class`-shaped groupings ask for.
+      def owner(key)
+        split(key)&.first
+      end
+    end
+  end
+end

data/lib/rigor/effects/mutation_classifier.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+require "prism"
+
+require_relative "../inference/mutation_widening"
+require_relative "label_set"
+
+module Rigor
+  module Effects
+    # Decides whether a call mutates its receiver, and — when it does — which `mutate.*` label that earns
+    # (ADR-103 WD4 / WD14).
+    #
+    # Two independent questions, both answered conservatively:
+    #
+    # 1. **Is this a mutation?** Only when the selector says so beyond doubt. `[]=` and an attribute writer
+    #    are writes on every receiver; `<<` and the bang family are claimed only when the typer named the
+    #    receiver's class, because `n << 2` is a bit shift and `io << "x"` is output. A wrong label in the
+    #    proven lane is worse than a missing one — the proven lane is the one a verdict may read (ADR-5).
+    # 2. **Who owns the receiver?** `self` and its ivars are `mutate.self` (`mutate.static` in singleton
+    #    context), a class variable is `mutate.static`, a parameter is `mutate.instance`, a frame-owned
+    #    local is `mutate.local`. **Anything else answers nil**, and the caller records an
+    #    `unknown-ownership` taint rather than a proven bare `mutate`: Ruby's ownership is a dataflow
+    #    question, and a proven parent label on a fresh-but-unproven receiver would put findings on correct
+    #    code (WD14).
+    class MutationClassifier
+      # The only selectors a mutation may be claimed from without knowing the receiver's class.
+      UNIVERSAL_MUTATORS = %i[[]=].to_set.freeze
+
+      # `String`'s receiver-mutating surface. `Array` / `Hash` reuse the hand-audited sets the widening
+      # rules already maintain, cited rather than re-derived (ADR-103 WD3).
+      STRING_MUTATORS = %i[
+        << concat replace insert prepend clear
+        upcase! downcase! capitalize! swapcase! reverse!
+        strip! lstrip! rstrip! chomp! chop! squeeze! succ! next!
+        sub! gsub! tr! tr_s! delete! slice! []=
+      ].to_set.freeze
+
+      # `foo=`, and deliberately not `==` / `<=` / `!=` / `===`.
+      ATTRIBUTE_WRITER = /\A[a-z_][A-Za-z0-9_]*=\z/
+
+      LABELS = {
+        self_state: LabelSet.new(["mutate.self"]),
+        static: LabelSet.new(["mutate.static"]),
+        instance: LabelSet.new(["mutate.instance"]),
+        local: LabelSet.new(["mutate.local"])
+      }.freeze
+
+      def initialize(singleton:, parameters:, owned_locals:)
+        @singleton = singleton
+        @parameters = parameters
+        @owned_locals = owned_locals
+      end
+
+      # Whether `node` mutates its receiver. `receiver_class` is the class the typer projected the
+      # receiver's type to, or nil when it projected to none.
+      def mutating?(node, receiver_class)
+        name = node.name
+        return true if UNIVERSAL_MUTATORS.include?(name) || ATTRIBUTE_WRITER.match?(name.to_s)
+
+        case receiver_class
+        when "Array" then Inference::MutationWidening::ARRAY_MUTATORS.include?(name)
+        when "Hash" then Inference::MutationWidening::HASH_MUTATORS.include?(name)
+        when "String" then STRING_MUTATORS.include?(name)
+        else false
+        end
+      end
+
+      # The label a mutation of `receiver` earns, or nil when ownership is not provable.
+      def label_for(receiver)
+        LABELS[ownership(receiver)]
+      end
+
+      private
+
+      def ownership(receiver)
+        case receiver
+        when nil, Prism::SelfNode, Prism::InstanceVariableReadNode
+          @singleton ? :static : :self_state
+        when Prism::ClassVariableReadNode then :static
+        when Prism::LocalVariableReadNode then local_ownership(receiver.name.to_s)
+        end
+      end
+
+      def local_ownership(name)
+        return :instance if @parameters.include?(name)
+        return :local if @owned_locals.include?(name)
+
+        nil
+      end
+    end
+  end
+end