rigortype 0.3.3 → 0.3.5

data/lib/rigor/effects/propagator.rb

@@ -0,0 +1,335 @@
+# frozen_string_literal: true
+
+require_relative "discharge"
+require_relative "effect_table"
+require_relative "file_collection"
+
+module Rigor
+  module Effects
+    # Closes a run's collected summaries over the call graph (ADR-103 WD12).
+    #
+    # Two jobs, in order:
+    #
+    # 1. **Resolve edges.** The collector records a call as `(receiver class, kind, selector)`; a file
+    #    cannot say which definition that reaches, because the class graph spans the project. Here the
+    #    merged ancestry resolves it — the receiver's own class first, then its includes, then its
+    #    superclass chain — and then the **closed world** joins every project-known override of the same
+    #    selector below the receiver's class (ADR-103 WD4: Ruby has no `final`, and the analyzer already
+    #    takes this posture for types). A call that resolves to nothing in the project is dropped, not
+    #    tainted: the taint for an unresolvable call was already decided per site, from the typer's own
+    #    verdict.
+    # 2. **Reach a fixpoint.** Proven labels join along edges, the exhaustiveness bit ANDs, and causes
+    #    union. The lattice is finite (label sets over a closed vocabulary × one bit × a closed cause
+    #    enum) and every step is monotone, so iteration terminates on its own — a recursive or mutually
+    #    recursive cycle simply converges, and no recursion cap is needed or wanted here.
+    #
+    # Propagation is graph-only: it reads no source, types nothing, and touches no `Scope`. It is
+    # fail-soft as a whole — an exception yields the empty table rather than failing the run.
+    #
+    # **Three label lanes, one fixpoint** (#385), each monotone and each joined along the same edges:
+    #
+    # - `proven` — what the analyzer established.
+    # - `undischarged` — the same closure computed from each unit's *undischarged* direct bundles, i.e.
+    #   with every origin bundle `effects.tolerated:` discharges dropped at the seed ({Discharge}).
+    #   Per-origin discharge needs nothing more than that: an origin belongs to exactly one unit's direct
+    #   summary, so the transitive union of surviving bundles IS the closure of the seeded ones, and the
+    #   judgment never has to materialise a per-method set of transitive origins. With no `tolerated:`
+    #   list the policy is inert, the seed is identical, and the lane costs one `equal?`-true join.
+    # - `declared` — the `≤` lane. It travels call edges **exactly as the proven lane does** (ADR-103
+    #   WD1): a controller two hops above an attributed `Net::HTTP.get` reads `≤ io.net.http`, not merely
+    #   "and possibly more". It is joined into itself and never into `proven`, which is the whole
+    #   separation — a claim stays a claim however far it propagates.
+    module Propagator
+      NO_EDGES = [].freeze
+      private_constant :NO_EDGES
+
+      module_function
+
+      # @param collection [FileCollection] the run's merged per-file collections
+      # @param discharge [Discharge] the `effects.tolerated:` policy the undischarged lane is computed
+      #   under; {Discharge.none} makes the two lanes equal.
+      # @return [EffectTable]
+      def propagate(collection, discharge: Discharge.none)
+        return EffectTable.empty if collection.summaries.empty?
+
+        summaries = collection.summaries
+        state = seed(summaries, discharge)
+        edges = resolve_edges(collection, state)
+        iterate(state, edges)
+        EffectTable.new(build_entries(summaries, edges, state))
+      rescue StandardError
+        EffectTable.empty
+      end
+
+      # `{caller_key => [callee_key]}`, sorted and de-duplicated. Seeds the `unresolved-super` taint in
+      # the same pass, because whether a `super` resolved is exactly what this resolution answers.
+      def resolve_edges(collection, state)
+        index = Index.new(collection)
+        collection.edges.each_with_object({}) do |(caller_key, list), out|
+          targets = list.flat_map do |edge|
+            resolved = index.targets_for(edge)
+            taint_unresolved_super(state, caller_key, edge) if edge.super_call && resolved.empty?
+            resolved
+          end.uniq.sort
+          out[caller_key] = targets.freeze unless targets.empty?
+        end
+      end
+
+      # A `super` the project's own ancestry does not answer — the implementation is in a gem, in Ruby's
+      # core, or in a module prepended at run time — is the case the taint exists for (#446). Silence
+      # would be the one thing the effect model must never say: that the list is complete when a call in
+      # the body was not read. An unresolved ORDINARY edge is dropped instead, because most such calls
+      # are inherited ones the catalogue simply has no row for and the site's own taint was already
+      # decided from the typer's verdict; a `super` has no site verdict to fall back on, and it always
+      # dispatches to something.
+      #
+      # Decided here rather than in the collector because only the merged ancestry can say whether the
+      # parent resolves, and written into the SEED rather than into the direct summary so the fixpoint
+      # carries it to this method's callers exactly as it carries any other cause. A snapshot's
+      # `methods:` table records direct summaries and so does not show it; `reach:`, the report and the
+      # judgment all read the closure and do.
+      def taint_unresolved_super(state, caller_key, edge)
+        entry = state[caller_key]
+        return if entry.nil?
+
+        entry[:exhaustive] = false
+        entry[:causes] << ["unresolved-super", edge.selector].freeze
+      end
+
+      # Causes are carried as a Set through the fixpoint and flattened back to a sorted Array in
+      # {build_entries}. A Set is what {absorb} needs: unioning one along an edge must cost the source's
+      # size and allocate NOTHING when it adds nothing, and the array-concat-and-uniq it replaces
+      # allocated twice on every visit of every edge.
+      def seed(summaries, discharge)
+        summaries.transform_values do |summary|
+          {
+            proven: summary.proven,
+            undischarged: discharge.inert? ? summary.proven : discharge.undischarged(summary.bundles),
+            declared: summary.declared,
+            exhaustive: summary.exhaustive?, causes: Set.new(summary.causes)
+          }
+        end
+      end
+
+      # A worklist to a fixpoint. `state[key]` changing can only change the methods that CALL `key`, so a
+      # pass re-visits exactly those and the round-robin over the whole table is gone — that walk cost
+      # O(passes × edges) and the passes are the graph's depth.
+      #
+      # Each pass still runs in sorted key order, so the answer does not depend on Hash insertion order
+      # and a pooled run agrees with a sequential one bit for bit. (The lattice is finite and every step
+      # monotone, so the least fixpoint is unique and visit order cannot change it; the sorted pass keeps
+      # the *work* reproducible too.)
+      def iterate(state, edges)
+        order = state.keys.sort
+        callers = reverse_edges(edges)
+        pending = nil
+
+        loop do
+          dirty = nil
+          order.each do |key|
+            next if pending && !pending.include?(key)
+
+            list = edges[key]
+            next if list.nil?
+
+            changed = false
+            list.each { |callee| changed = true if absorb(state, key, callee) }
+            next unless changed
+
+            (dirty ||= Set.new).merge(callers[key]) if callers.key?(key)
+          end
+          break if dirty.nil?
+
+          pending = dirty
+        end
+      end
+
+      # `{callee_key => [caller_key]}` — who has to be re-visited when a key's closure moves.
+      def reverse_edges(edges)
+        edges.each_with_object({}) do |(caller_key, list), out|
+          list.each { |callee| (out[callee] ||= []) << caller_key }
+        end
+      end
+
+      def absorb(state, key, callee)
+        target = state[key]
+        source = state[callee]
+        return false if source.nil? || target.equal?(source)
+
+        # Each lane is named literally rather than looped over an array: this runs once per edge per
+        # visit, and a literal array of lane names would allocate one per call for nothing.
+        changed = join_lane(target, source, :proven)
+        changed = true if join_lane(target, source, :undischarged)
+        changed = true if join_lane(target, source, :declared)
+        if target[:exhaustive] && !source[:exhaustive]
+          target[:exhaustive] = false
+          changed = true
+        end
+        causes = target[:causes]
+        source[:causes].each { |cause| changed = true if causes.add?(cause) }
+        changed
+      end
+
+      # Joins one label lane in place along an edge, answering whether it moved. {LabelSet#join} returns
+      # the receiver untouched when the source adds nothing, so a converged region costs a comparison and
+      # no allocation at all.
+      def join_lane(target, source, lane)
+        joined = target[lane].join(source[lane])
+        moved = joined != target[lane]
+        target[lane] = joined if moved
+        moved
+      end
+
+      def build_entries(summaries, edges, state)
+        summaries.each_with_object({}) do |(key, summary), out|
+          closed = state.fetch(key)
+          out[key] = EffectTable::Entry.new(
+            key: key,
+            direct: summary,
+            proven: closed[:proven],
+            undischarged: closed[:undischarged],
+            declared: closed[:declared],
+            exhaustive: closed[:exhaustive],
+            causes: closed[:causes].sort_by { |cause, detail| [cause, detail.to_s] }.freeze,
+            edges: edges.fetch(key, NO_EDGES)
+          )
+        end
+      end
+
+      private_class_method :resolve_edges, :taint_unresolved_super, :seed, :iterate, :reverse_edges,
+                           :absorb, :join_lane, :build_entries
+
+      # The class graph a run's collections describe, and the edge resolution over it. Built once per
+      # propagation; every lookup is a Hash read.
+      class Index
+        def initialize(collection)
+          @summaries = collection.summaries
+          @superclasses = collection.superclasses
+          @includes = collection.includes
+          @classes = build_classes(collection)
+          @descendants = build_descendants(collection.superclasses)
+          @descendant_closures = {}
+          @targets = {}
+        end
+
+        # Every project method key `edge` may reach: the definition its ancestry resolves to, plus every
+        # override of the same selector in a project subclass of the receiver's class.
+        #
+        # Memoised on `(receiver class, kind, selector, super?)` — the answer depends on nothing else, and
+        # one such tuple is asked for once per call site in the project. `ApplicationRecord#save` alone is
+        # thousands of sites on a Rails app, each of which used to re-walk the whole subclass forest.
+        def targets_for(edge)
+          @targets[[edge.receiver_class, edge.kind, edge.selector, edge.super_call]] ||= begin
+            separator = edge.kind == :singleton ? "." : "#"
+            edge.super_call ? super_targets(edge, separator) : call_targets(edge, separator)
+          end
+        end
+
+        private
+
+        def call_targets(edge, separator)
+          targets = []
+          owner = resolve_owner(edge.receiver_class, separator, edge.selector)
+          targets << owner if owner
+          descendant_closure(edge.receiver_class).each do |subclass|
+            key = "#{subclass}#{separator}#{edge.selector}"
+            targets << key if @summaries.key?(key)
+          end
+          targets.freeze
+        end
+
+        # A `super` reaches **one** definition, and the closed-world override join every other edge gets
+        # is deliberately absent from it (#446). `super` in `C#m` dispatches into the ancestry above `C`
+        # in the receiver's chain, and a subclass of `C` is never in it however the receiver was
+        # constructed — so joining `D#m` would put a proven label on `C#m` that no execution of `C#m` can
+        # produce. Ruby's lack of `final` is the argument for the join at an ordinary call site and says
+        # nothing here.
+        def super_targets(edge, separator)
+          target = resolve_super(edge.receiver_class, separator, edge.selector)
+          target ? [target].freeze : NO_TARGETS
+        end
+
+        NO_TARGETS = [].freeze
+        private_constant :NO_TARGETS
+
+        # The transitive subclass closure, memoised per class. A deep hierarchy's root is asked for it
+        # once, not once per selector reaching it.
+        def descendant_closure(class_name)
+          @descendant_closures[class_name] ||= descendants_of(class_name).freeze
+        end
+
+        # Ancestry order mirrors the engine's: the class itself, the modules it includes, then its
+        # superclass, recursively. Cycle-guarded, because a project may declare one. Ancestry names
+        # arrive as as-written candidate lists (see `Scanner#lexical_candidates`); every candidate is
+        # enqueued and the most-qualified one comes first, so the right constant wins the race and a
+        # spelling that names nothing simply matches no key.
+        def resolve_owner(class_name, separator, selector)
+          walk_ancestors([class_name], Set.new, separator, selector)
+        end
+
+        # Where `super` from `class_name#selector` lands: the same ancestor walk, started one step up —
+        # the modules the class includes, then its superclass chain — with the class itself already in
+        # `seen`, because a method never `super`s into itself.
+        #
+        # The includes are instance-side only. `include M` puts `M#m` between the class and its
+        # superclass, which is exactly where `super` looks, while `M.m` is a singleton method `include`
+        # never contributes; a singleton `super` that really does reach a module went through `extend` or
+        # a `class << self` include, neither of which is collected, so it resolves to nothing and taints.
+        def resolve_super(class_name, separator, selector)
+          queue = separator == "#" ? @includes.fetch(class_name, []).dup : []
+          queue.concat(@superclasses.fetch(class_name, []))
+          walk_ancestors(queue, Set.new([class_name]), separator, selector)
+        end
+
+        def walk_ancestors(queue, seen, separator, selector)
+          until queue.empty?
+            current = queue.shift
+            next if current.nil? || !seen.add?(current)
+
+            key = "#{current}#{separator}#{selector}"
+            return key if @summaries.key?(key)
+
+            queue.concat(@includes.fetch(current, []))
+            queue.concat(@superclasses.fetch(current, []))
+          end
+          nil
+        end
+
+        def descendants_of(class_name)
+          collected = []
+          queue = @descendants.fetch(class_name, []).dup
+          seen = Set.new
+          until queue.empty?
+            current = queue.shift
+            next unless seen.add?(current)
+
+            collected << current
+            queue.concat(@descendants.fetch(current, []))
+          end
+          collected
+        end
+
+        # The subclass index the closed-world override join walks. Unlike the ancestor walk, this one
+        # must pick **one** parent per child: enqueuing every candidate would let `A::Base` and `B::Base`
+        # share the short spelling `Base` and join an unrelated class's override into the proven lane.
+        # The most-qualified candidate the project actually defines wins; a child whose parent is outside
+        # the project keeps its first (most-qualified) spelling and simply matches nothing.
+        def build_descendants(superclasses)
+          superclasses.each_with_object({}) do |(child, candidates), out|
+            parent = candidates.find { |candidate| @classes.include?(candidate) } || candidates.first
+            (out[parent] ||= []) << child
+          end
+        end
+
+        # Every class name the project defines a method on — the evidence `build_descendants` resolves an
+        # as-written superclass against.
+        def build_classes(collection)
+          collection.summaries.each_key.with_object(Set.new) do |key, out|
+            index = key.index("#") || key.index(".")
+            out << key[0, index] if index
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rigor/effects/registry.rb

@@ -0,0 +1,200 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+require_relative "label"
+
+module Rigor
+  module Effects
+    # The effect-label vocabulary: which spellings are recognised, which have been retired, and who
+    # may open a new root (ADR-103 WD2; normative in
+    # `docs/type-specification/effect-labels.md`).
+    #
+    # The shared layer is hand-written in `data/effects/registry.yml` — Steins' v1 set verbatim,
+    # Ruby's `mutate` leaves, the proposed shared core leaves and the application-meaning roots —
+    # so a later slice or a plugin extends the data, not this Ruby. Extensions arrive through
+    # {#with}, which is the one place root ownership is enforced.
+    #
+    # A Registry is a frozen value object; {#with} returns a new one rather than mutating.
+    class Registry
+      class Error < StandardError
+      end
+
+      # An added label whose root neither exists already nor belongs to the extender.
+      class OwnershipError < Error
+      end
+
+      # An added label that is not well-formed under {Label::PATTERN}.
+      class InvalidLabelError < Error
+      end
+
+      DATA_PATH = File.expand_path("../../../data/effects/registry.yml", __dir__)
+
+      # How far a misspelling may be from a known label before {#suggest} declines to guess. Two
+      # edits catches a transposition or a dropped segment character ("io.nte", "nondet.tim")
+      # without proposing an unrelated label for a genuinely new spelling.
+      SUGGESTION_DISTANCE_CAP = 2
+
+      # The shared registry as shipped. Memoised: the YAML parse is a once-per-process cost, and
+      # nothing consumes the registry yet, so it stays lazy rather than paying at `require "rigor"`.
+      def self.default
+        @default ||= load_file(DATA_PATH)
+      end
+
+      # The vocabulary one run works in: the shipped registry plus whatever `effects.labels:` opened
+      # (ADR-103 WD2 / #385). The project is the one extender that may open ANY root — listing a label in
+      # its own configuration is the vouching act — so this can only fail on a spelling `Configuration`
+      # already rejected at load, and a failure degrades to the shipped vocabulary rather than taking the
+      # run down.
+      #
+      # Memoised on the label list, because the answer is a frozen value object and every effects surface
+      # in a run asks for the same one: the envelope pass, the unknown-label check, the snapshot header.
+      #
+      # `plugin_facts` (#387) folds in every loaded plugin's `effect_labels:` FIRST, each under its own
+      # owner, so that a project's `effects.labels:` can then name a plugin-opened root and an envelope may
+      # bound `rails.activejob.enqueue` without the project having to re-declare the framework's vocabulary.
+      # The plugin layer is not memoised on its own — {PluginFacts} is already per-process — and the
+      # project layer keeps its memo keyed on the pair.
+      def self.for_configuration(configuration, plugin_facts: nil)
+        base = plugin_facts.nil? || plugin_facts.empty? ? default : plugin_facts.extend_registry(default)
+        labels = configuration.effects_labels
+        return base if labels.nil? || labels.empty?
+
+        (@extended ||= {})[[labels, base.labels]] ||= base.with(labels: labels, owner: nil)
+      rescue Error
+        default
+      end
+
+      # Build a registry from a registry-shaped YAML file. Missing or unreadable data degrades to
+      # an empty vocabulary rather than raising, matching the built-in catalogues' posture for a
+      # bare install that opted data out; every label then reads as unknown, which is fail-open.
+      def self.load_file(path)
+        raw = File.exist?(path) ? YAML.safe_load_file(path) : nil
+        raw = {} unless raw.is_a?(Hash)
+        new(
+          vocabulary_version: raw.fetch("vocabulary", 0),
+          labels: raw.fetch("labels", nil) || [],
+          retired: raw.fetch("retired", nil) || {},
+          descriptions: raw.fetch("descriptions", nil) || {}
+        )
+      end
+
+      attr_reader :vocabulary_version
+
+      def initialize(vocabulary_version:, labels:, retired: {}, descriptions: {})
+        @vocabulary_version = vocabulary_version
+        @descriptions = descriptions.to_h { |root, text| [root.to_s, text.to_s.gsub(/\s+/, " ").strip] }.freeze
+        @labels = labels.map(&:to_s).uniq.sort.freeze
+        @known = build_known(@labels)
+        @roots = @known.select { |label| Label.parent(label).nil? }.sort.freeze
+        @retired = build_retired(retired)
+        freeze
+      end
+
+      # Every declared label, sorted. Implied ancestors (`email`, because `email.send` is declared)
+      # are recognised by {#known?} but are not rows of the vocabulary and are not listed here.
+      attr_reader :labels
+
+      # The roots of the vocabulary — the outermost segments {#with} treats as already owned.
+      attr_reader :roots
+
+      # One line per root, from the data file's `descriptions:` — what `rigor effects --list-labels`
+      # prints beside a root (#429). A root nothing describes (a plugin's, a project's) has no entry.
+      attr_reader :descriptions
+
+      # Whether the vocabulary recognises `label`: an exact row, or an ancestor of one. A declared
+      # `io` is recognised because `io.net` exists, so a bound may name an interior node the data
+      # file never spells out on its own line.
+      def known?(label)
+        @known.include?(label)
+      end
+
+      # The nearest recognised label to a misspelling, within {SUGGESTION_DISTANCE_CAP} edits, or
+      # `nil` when nothing is close enough. A recognised label suggests nothing — ask {#known?}
+      # first.
+      def suggest(label)
+        return nil unless Label.valid?(label)
+        return nil if known?(label)
+
+        best = nil
+        best_distance = SUGGESTION_DISTANCE_CAP + 1
+        @known.each do |candidate|
+          distance = levenshtein(label, candidate, best_distance)
+          next unless distance < best_distance
+
+          best = candidate
+          best_distance = distance
+        end
+        best
+      end
+
+      # The replacement labels for a retired spelling, or `nil` when the spelling was never
+      # retired. A rename or a removal bumps {#vocabulary_version} and records the old spelling
+      # here so a snapshot written by an older Rigor still reads.
+      def retired(label)
+        @retired[label]
+      end
+
+      # A new registry carrying `labels` on top of this one.
+      #
+      # `owner` is the identity opening a root: a plugin id, or — for a first-party plugin that
+      # models a framework — the framework root it owns. `nil` is the project, which may open any
+      # root. Every added label must either descend from a root this registry already knows or
+      # open a root equal to `owner`.
+      def with(labels:, owner:)
+        added = labels.map(&:to_s)
+        added.each do |label|
+          raise InvalidLabelError, "not a well-formed effect label: #{label.inspect}" unless Label.valid?(label)
+
+          check_ownership(label, owner)
+        end
+        self.class.new(vocabulary_version: @vocabulary_version, labels: @labels + added, retired: @retired,
+                       descriptions: @descriptions)
+      end
+
+      private
+
+      def check_ownership(label, owner)
+        root = Label.root(label)
+        return if @roots.include?(root)
+        return if owner.nil?
+        return if owner == root
+
+        raise OwnershipError,
+              "#{owner.inspect} may not open the effect-label root #{root.inspect} (from #{label.inspect}); " \
+              "a non-project extender opens only the root it owns"
+      end
+
+      def build_known(labels)
+        known = labels.to_set
+        labels.each { |label| Label.ancestors(label).each { |ancestor| known << ancestor } }
+        known.freeze
+      end
+
+      def build_retired(retired)
+        retired.to_h { |spelling, replacements| [spelling.to_s, Array(replacements).map(&:to_s).freeze] }.freeze
+      end
+
+      # Bounded Levenshtein. Answers `cap + 1` — "further than the cap" — as soon as the length
+      # difference or a whole row of the matrix rules the candidate out, so scanning the vocabulary
+      # for a suggestion stays cheap.
+      def levenshtein(from, to, cap)
+        beyond = cap + 1
+        return beyond if (from.length - to.length).abs > cap
+
+        previous = (0..to.length).to_a
+        from.each_char.with_index(1) do |char, row|
+          current = [row]
+          to.each_char.with_index(1) do |other, column|
+            cost = char == other ? 0 : 1
+            current << [current[column - 1] + 1, previous[column] + 1, previous[column - 1] + cost].min
+          end
+          return beyond if current.min > cap
+
+          previous = current
+        end
+        previous.last > cap ? beyond : previous.last
+      end
+    end
+  end
+end