rigortype 0.3.3 → 0.3.5

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

data/lib/rigor/effects/narrowing.rb

@@ -0,0 +1,202 @@
+# frozen_string_literal: true
+
+require "prism"
+
+require_relative "label_set"
+
+module Rigor
+  module Effects
+    # Argument-dependent narrowing for catalogue rows (ADR-103 WD3; the row's `narrow:` names one of
+    # these handlers, and `data/effects/core.yml` says why each row wants one).
+    #
+    # A handler reads **the call's own argument literals and nothing else**. There is no dataflow here
+    # on purpose: the effect scan is observational (it never asks the typer for anything it did not
+    # already decide), and a narrowing that depended on inference would make the catalogue's answer a
+    # function of analysis quality rather than of the source in front of it.
+    #
+    # Every handler is total and answers an **upper bound**: when the literal does not settle the
+    # question it returns the row's parent label, never a guess. `open(path)` with a computed argument
+    # is `io` — file, pipe or URI — and that is the honest reading of the classic pipe-injection shape.
+    #
+    # Handlers are module functions dispatched by a `case`, deliberately not a Hash of lambdas: the
+    # catalogue is loaded once per process and inherited across the fork pool, and a table of procs is
+    # neither Marshal-clean nor shareable.
+    module Narrowing
+      IO_ANY = LabelSet.new(["io"]).freeze
+      FS = LabelSet.new(["io.fs"]).freeze
+      FS_READ = LabelSet.new(["io.fs.read"]).freeze
+      FS_WRITE = LabelSet.new(["io.fs.write"]).freeze
+      FS_READ_WRITE = LabelSet.new(["io.fs.read", "io.fs.write"]).freeze
+      PROCESS = LabelSet.new(["io.process"]).freeze
+      HTTP = LabelSet.new(["io.net.http"]).freeze
+      TIME = LabelSet.new(["nondet.time"]).freeze
+      DB = LabelSet.new(["io.db"]).freeze
+      DB_READ = LabelSet.new(["io.db.read"]).freeze
+      DB_WRITE = LabelSet.new(["io.db.write"]).freeze
+      DB_TRANSACTION = LabelSet.new(["io.db.transaction"]).freeze
+      RANDOM = LabelSet.new(["nondet.random"]).freeze
+      NONE = LabelSet::EMPTY
+
+      # Ruby's file modes, minus the encoding suffix (`"r:UTF-8"`) and the `b` / `t` flags. `"r"` is the
+      # only pure read; every `+` form reads and writes.
+      WRITE_MODES = %w[w a w+ a+ r+].freeze
+      private_constant :WRITE_MODES
+
+      # SQL verbs, by what they do to the database. `WITH` heads a CTE whose tail may be either, so it
+      # deliberately does not narrow. Everything not listed answers `io.db`.
+      SQL_READ_VERBS = %w[SELECT SHOW EXPLAIN DESCRIBE DESC PRAGMA].freeze
+      SQL_WRITE_VERBS = %w[
+        INSERT UPDATE DELETE REPLACE UPSERT MERGE TRUNCATE
+        CREATE ALTER DROP RENAME COMMENT GRANT REVOKE REINDEX VACUUM ANALYZE COPY
+      ].freeze
+      SQL_TRANSACTION_VERBS = %w[BEGIN START COMMIT ROLLBACK SAVEPOINT RELEASE SET LOCK].freeze
+      private_constant :SQL_READ_VERBS, :SQL_WRITE_VERBS, :SQL_TRANSACTION_VERBS
+
+      HANDLERS = %w[kernel_open file_open pathname_open time_new random_new uri_open sql_verb].freeze
+
+      module_function
+
+      def known?(name)
+        HANDLERS.include?(name)
+      end
+
+      # The labels `name`'s handler reads off `node`. An unknown handler name answers nil, which the
+      # catalogue loader rejects at load time rather than at call time.
+      def apply(name, node)
+        case name
+        when "kernel_open" then kernel_open(node)
+        when "file_open" then file_open(node)
+        when "pathname_open" then pathname_open(node)
+        when "time_new" then time_new(node)
+        when "random_new" then random_new(node)
+        when "uri_open" then uri_open(node)
+        when "sql_verb" then sql_verb(node)
+        end
+      end
+
+      # `connection.execute(sql)` / `exec_query` / `select_all` — the SQL string's leading verb settles the
+      # direction, which is the argument-dependent narrowing of the design note § 4 applied to SQL. It is
+      # the one place a raw-SQL escape hatch can still be read precisely, and the shape that matters most —
+      # `execute("UPDATE …")` inside a method whose envelope says `io.db.read` — is exactly the one a
+      # literal answers.
+      #
+      # Interpolation is fine as long as the VERB is written out: `execute("SELECT * FROM #{table}")`
+      # narrows, because {literal_prefix} keeps the leading literal run. A fully computed string does not,
+      # and answers the parent `io.db`.
+      def sql_verb(node)
+        head = literal_prefix(argument(node, 0))
+        return DB if head.nil?
+
+        verb = head[/[A-Za-z]+/]&.upcase
+        return DB if verb.nil?
+        return DB_READ if SQL_READ_VERBS.include?(verb)
+        return DB_WRITE if SQL_WRITE_VERBS.include?(verb)
+        return DB_TRANSACTION if SQL_TRANSACTION_VERBS.include?(verb)
+
+        DB
+      end
+
+      # `Kernel#open` — a path, a `|command` pipe, or (with open-uri loaded) a URI. A literal leading
+      # `|` is the pipe form; anything else literal is a path, whose direction the mode literal decides.
+      def kernel_open(node)
+        target = literal_prefix(argument(node, 0))
+        return IO_ANY if target.nil?
+        return PROCESS if target.start_with?("|")
+
+        mode_labels(node, 1)
+      end
+
+      # `File.open(path, mode)` — the mode literal decides the direction. An ABSENT mode is not an
+      # unknown one: Ruby's default is `"r"`, so it reads. A mode the call computes — or an integer flag
+      # such as `File::RDWR`, which the scan deliberately does not resolve — is genuinely unknown and
+      # answers the subsystem parent.
+      def file_open(node)
+        mode_labels(node, 1)
+      end
+
+      # `Pathname#open(mode)` — the same reading one argument to the left, because the receiver is the
+      # path.
+      def pathname_open(node)
+        mode_labels(node, 0)
+      end
+
+      # `Time.new` — with no positional arguments it is `Time.now`; with any it constructs from them and
+      # consults no clock. Keyword arguments (`in:`) do not count: `Time.new(in: "+09:00")` is still now.
+      def time_new(node)
+        positional_count(node).zero? ? TIME : NONE
+      end
+
+      # `Random.new` — a seed argument makes the generator reproducible from the source; without one it
+      # draws the seed from platform entropy.
+      def random_new(node)
+        positional_count(node).zero? ? RANDOM : NONE
+      end
+
+      # `URI.open` / `OpenURI.open_uri` — the scheme literal decides the subsystem. A bare path (no
+      # `scheme://`) is open-uri's filesystem fallback; a scheme nobody rowed answers the parent.
+      def uri_open(node)
+        target = literal_prefix(argument(node, 0))
+        return IO_ANY if target.nil?
+        return HTTP if target.start_with?("http://", "https://")
+        return FS_READ if target.start_with?("file://")
+        return IO_ANY if target.include?("://")
+
+        FS_READ
+      end
+
+      # The direction a mode argument proves. Three states, and the middle one is the reason this is not
+      # a two-way test: **absent** is Ruby's `"r"` default, **present but unreadable** is genuinely
+      # unknown and answers the subsystem parent, and **a literal** narrows.
+      def mode_labels(node, index)
+        mode = argument(node, index) || keyword_argument(node, "mode")
+        return FS_READ if mode.nil?
+
+        canonical = string_literal(mode)&.[](/\A[rwa]\+?/)
+        return FS if canonical.nil?
+        return FS_READ unless WRITE_MODES.include?(canonical)
+
+        canonical.end_with?("+") ? FS_READ_WRITE : FS_WRITE
+      end
+
+      def argument(node, index)
+        positional(node)[index]
+      end
+
+      def positional_count(node)
+        positional(node).length
+      end
+
+      def positional(node)
+        node.arguments&.arguments&.grep_v(Prism::KeywordHashNode) || []
+      end
+
+      def keyword_argument(node, name)
+        hash = node.arguments&.arguments&.find { |argument| argument.is_a?(Prism::KeywordHashNode) }
+        pair = hash&.elements&.find do |element|
+          element.is_a?(Prism::AssocNode) && element.key.is_a?(Prism::SymbolNode) &&
+            element.key.unescaped == name
+        end
+        pair&.value
+      end
+
+      def string_literal(node)
+        node.unescaped if node.is_a?(Prism::StringNode)
+      end
+
+      # The literal head of a string argument: the whole thing for a plain literal, and the leading
+      # literal run for an interpolated one. `open("|#{cmd}")` and `URI.open("https://#{host}/x")` are
+      # the shapes that matter — the part that decides the subsystem is written out even when the rest
+      # is computed.
+      def literal_prefix(node)
+        return node.unescaped if node.is_a?(Prism::StringNode)
+        return nil unless node.is_a?(Prism::InterpolatedStringNode)
+
+        head = node.parts.first
+        head.is_a?(Prism::StringNode) ? head.unescaped : nil
+      end
+
+      private_class_method :sql_verb, :mode_labels, :argument, :positional_count, :positional,
+                           :keyword_argument, :string_literal, :literal_prefix
+    end
+  end
+end

data/lib/rigor/effects/origin.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module Rigor
+  module Effects
+    # Where one bundle of labels in a summary came from (ADR-103 WD14).
+    #
+    # An origin is the pair of **what** coloured the labels and **which source** did the colouring, and it
+    # is deliberately **line-free**: two `puts` calls in one method share one origin, so a summary is stable
+    # under a line move and a snapshot diff shows a change of behaviour rather than a change of formatting.
+    # Call sites are kept separately, per run, for the report only.
+    #
+    # `name` is the callee key (`Kernel#puts`, `Time.now`) for a catalogued row, and the construct's name
+    # (`xstring`, `gvar-write`) for a language construct. `source` says which of the two it is, because the
+    # two namespaces overlap in principle and a later slice discharges policy per origin.
+    class Origin < Data.define(:name, :source)
+      # A Ruby language construct — backticks, a `$gvar` write, an `@ivar` write (§ 5.1 of the design note).
+      CONSTRUCT = :construct
+      # A row of the built-in effect catalogue ({Catalog}; `data/effects/core.yml` from #380).
+      CATALOGUE = :catalogue
+      # A row of the project's own `effects.attribution:` table — a claim about code Rigor did not
+      # analyse. Its labels land in the summary's DECLARED lane and never in the proven one, and the site
+      # keeps its `plugin-attribution` taint (ADR-103 WD6: "declared this, and possibly more").
+      ATTRIBUTION = :attribution
+      # An {Envelope} the callee's own declaration carries — a project annotation, an
+      # `effects.envelopes:` convention, or an accepted signature's `%a{…}` (#386). Its labels land in
+      # the DECLARED lane, like an attribution's, but unlike an attribution the bound is *checked* (or
+      # trusted at the type tier), so the site is exhaustive rather than tainted: ADR-103 WD6's
+      # discharging strata. `name` is the callee key the bound was resolved for.
+      ENVELOPE = :envelope
+      # A row of a loaded plugin's `effect_attributions:` — what the plugin that models a framework says a
+      # call into it does (#387; ADR-103 WD6 / WD10). Its labels land in the DECLARED lane, like an
+      # attribution's and an envelope's, and which of those two it behaves like is decided by the plugin's
+      # standing: a **first-party bundled** plugin's row discharges, so the site is exhaustive, exactly as
+      # an accepted signature's `%a{…}` is; a third-party plugin's does not, and the site keeps its
+      # `plugin-attribution` taint. One origin source for both, because the label came from the same place
+      # either way and `explain` should say so.
+      PLUGIN = :plugin
+
+      def self.construct(name)
+        new(name: name.to_s, source: CONSTRUCT)
+      end
+
+      def self.catalogue(name)
+        new(name: name.to_s, source: CATALOGUE)
+      end
+
+      def self.attribution(name)
+        new(name: name.to_s, source: ATTRIBUTION)
+      end
+
+      def self.envelope(name)
+        new(name: name.to_s, source: ENVELOPE)
+      end
+
+      def self.plugin(name)
+        new(name: name.to_s, source: PLUGIN)
+      end
+
+      # The rendering the report and the JSON payload key on. Sorted lexicographically, so `catalogue:`
+      # rows group before `construct:` ones and the output is deterministic.
+      def to_s
+        "#{source}:#{name}"
+      end
+    end
+  end
+end

data/lib/rigor/effects/path_finder.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+require_relative "effect_table"
+
+module Rigor
+  module Effects
+    # "Why does this entry point reach `io.net.http`?" — the shortest edge path from a method to the
+    # origin that introduced a label (ADR-103 WD7; design note § 9.4, "the review feature that pays for
+    # the fixpoint").
+    #
+    #   OrdersController#create → OrderService#place → PaymentGateway#charge → Net::HTTP.get [io.net.http]
+    #
+    # A breadth-first walk over the {EffectTable}'s resolved edges, so the answer is a *shortest* path
+    # rather than whichever one a depth-first walk stumbled into first — a reviewer wants the tightest
+    # explanation available. Ties break on sorted key order, so two runs explain a change identically.
+    #
+    # The path ends at the **origin**, not at the last method: the catalogue row or language construct
+    # that actually coloured the label is what the reviewer is looking for, and the method that owns it
+    # is the hop before.
+    module PathFinder
+      # One explanation.
+      #
+      # `chain` are the project method keys walked, entry point first; `origin` is the callee key or
+      # construct name that introduced the label, or nil when no method on the path proves it directly
+      # (which happens only when the table is inconsistent, and is rendered as the method chain alone).
+      class Path < Data.define(:symbol, :label, :chain, :origin, :origin_source)
+        # The rendering the text form prints and the JSON payload carries as `path`.
+        def to_a
+          origin.nil? ? chain : chain + [origin]
+        end
+
+        def to_s
+          "#{to_a.join(' → ')} [#{label}]"
+        end
+      end
+
+      module_function
+
+      # The shortest path from `symbol` to a direct origin of `label`, or nil when the table proves the
+      # label nowhere reachable from it.
+      def shortest(table, symbol:, label:)
+        entry = table[symbol]
+        return nil if entry.nil?
+
+        walk(table, symbol, label)
+      end
+
+      # Every label of `symbol`'s transitive summary, explained. Sorted by label, so the output is stable.
+      def explain_all(table, symbol:)
+        entry = table[symbol]
+        return [] if entry.nil?
+
+        entry.proven.to_a.filter_map { |label| shortest(table, symbol: symbol, label: label) }
+      end
+
+      def walk(table, start, label)
+        queue = [[start]]
+        seen = { start => true }
+        until queue.empty?
+          trail = queue.shift
+          entry = table[trail.last]
+          next if entry.nil?
+
+          origin = direct_origin(entry, label)
+          if origin
+            return Path.new(symbol: start, label: label, chain: trail.freeze,
+                            origin: origin.name, origin_source: origin.source)
+          end
+
+          entry.edges.each do |callee|
+            next unless seen[callee].nil?
+
+            seen[callee] = true
+            queue << (trail + [callee])
+          end
+        end
+        nil
+      end
+
+      # Which origin of this method's own summary carries the label. Sorted by rendering, so a method
+      # coloured by two rows explains through the same one every time.
+      def direct_origin(entry, label)
+        entry.direct.bundles.find { |_origin, labels| labels.include?(label) }&.first
+      end
+
+      private_class_method :walk, :direct_origin
+    end
+  end
+end