rigortype 0.3.4 → 0.3.6

data/lib/rigor/cli/doc_links.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+module Rigor
+  class CLI
+    # Turns the documentation's own relative links into keys `rigor docs` can answer (#430).
+    #
+    # The manual and handbook link each other and the design corpus the way any prose does —
+    # `[ADR-103](../adr/103-effect-labels.md)`. Those links are correct in the repository and correct on
+    # GitHub, and they are the coupling between documents: they say which document explains what, and
+    # deleting them to leave a bare `ADR-103` would cost that and give nothing back.
+    #
+    # They are wrong in exactly one place: a reader looking at the file inside an installed gem, where
+    # `docs/adr/` was never packaged. Two earlier attempts fixed the file for that reader and made it
+    # worse for the others — rewriting every link to a `blob/master` URL hardcoded a host, an
+    # organisation and a branch in 297 places and sent a v0.3.5 reader to a document that had moved on;
+    # deleting the markup severed the coupling.
+    #
+    # So the source keeps its links and `rigor docs` rewrites them on the way out:
+    #
+    #     [ADR-103](../adr/103-effect-labels.md)   →   [ADR-103][adr/103-effect-labels]
+    #
+    # The key is the repository path minus `docs/` and `.md`, which for a packaged page is exactly the
+    # name `rigor docs` already takes, so the reader can run what they are shown. For an unpackaged one
+    # the key still resolves — to a routed message naming the path and the repository, from the single
+    # constant below rather than from 297 rewritten links.
+    module DocLinks
+      REPOSITORY = "https://github.com/rigortype/rigor"
+
+      # `[label](target)` and `[label](target#anchor)`, skipping absolute URLs and bare anchors.
+      MARKDOWN_LINK = /\[([^\]]*)\]\((?!https?:|mailto:|#)([^)#\s]+)(#[^)\s]*)?\)/
+      private_constant :MARKDOWN_LINK
+
+      # Where the gem's `docs/` tree sits, so a rendered path can be made repository-relative.
+      GEM_ROOT = File.expand_path("../../..", __dir__)
+      private_constant :GEM_ROOT
+
+      module_function
+
+      # @param body [String] the page as it is stored.
+      # @param from [String] its absolute path, so relative targets resolve.
+      # @return [String] the page with every relative link turned into a `rigor docs` key.
+      def rewrite(body, from:)
+        dir = File.dirname(from)
+        body.gsub(MARKDOWN_LINK) do
+          label = Regexp.last_match(1)
+          target = Regexp.last_match(2)
+          anchor = Regexp.last_match(3)
+          key = key_for(target, dir)
+          key.nil? ? "[#{label}](#{target}#{anchor})" : "[#{label}][#{key}#{anchor}]"
+        end
+      end
+
+      # Splits a key into its page and its section, for a reader who pasted one back.
+      def split_anchor(key)
+        page, anchor = key.to_s.split("#", 2)
+        [page, anchor]
+      end
+
+      # The key naming `target` as written in `dir`, or nil when it points outside the repository.
+      #
+      # A `.md` under `docs/` loses both the prefix and the extension, which is exactly the name
+      # `rigor docs` already answers — that is what lets a rendered page hand the reader something they
+      # can run. Everything else keeps its repository-relative path verbatim: a directory
+      # (`examples/rigor-deprecations/`), a source file (`spec/rigor/environment_spec.rb`), a root
+      # document (`CHANGELOG.md`). Those are equally routable and equally worth naming; only the
+      # round-trip differs, and {.repository_path} reverses both.
+      #
+      # `target` is taken as written rather than expanded, because `File.expand_path` drops the trailing
+      # slash that tells a directory link apart from a page link — prose that writes `[the ADRs](../adr/)`
+      # is pointing at a tree, and a key without the slash would claim there is a page there.
+      def key_for(target, dir)
+        relative = File.expand_path(target, dir).sub("#{GEM_ROOT}/", "")
+        return nil if relative.start_with?("/")
+
+        relative += "/" if target.end_with?("/")
+        return relative unless relative.start_with?("docs/") && relative.end_with?(".md")
+
+        relative.delete_prefix("docs/").delete_suffix(".md")
+      end
+
+      # Repository directories a key may name verbatim. A key that starts with one of these already IS a
+      # path — `docs/adr`, `plugins/rigor-sorbet` — because {.key_for} only rewrites `.md` files under
+      # `docs/`. Anything else is a documentation key and gets its prefix and extension back.
+      #
+      # Keying on the ROOT rather than on "has an extension" is what makes a directory work: prose links
+      # a tree as often without a trailing slash (`../adr`) as with one, and no string test tells an
+      # extensionless file from a directory.
+      REPOSITORY_ROOTS = %w[docs examples plugins spec skills data tool bench apps].freeze
+
+      # The repository path a key names, reversing {.key_for}.
+      def repository_path(key)
+        return nil if key.nil? || key.empty? || key.include?("..")
+        return key if REPOSITORY_ROOTS.include?(key.split("/").first)
+        return key if File.extname(key) != ""
+
+        "docs/#{key}.md"
+      end
+    end
+  end
+end

data/lib/rigor/cli/docs_command.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "command"
+require_relative "doc_links"
 
 module Rigor
   class CLI
@@ -118,7 +119,7 @@ module Rigor
         # a UTF-8 header would set the output buffer to UTF-8 and clash with the body.
         @out.puts("<!-- rigor docs #{doc.fetch(:name)} (rigortype #{Rigor::VERSION}, offline) -->")
         @out.puts
-        @out.write(File.read(doc.fetch(:path)))
+        @out.write(DocLinks.rewrite(File.read(doc.fetch(:path)), from: doc.fetch(:path)))
         0
       end
 
@@ -138,6 +139,10 @@ module Rigor
       # @return [Hash, Integer] the doc entry, or an error exit status
       #   after the error has been written to `@err`.
       def resolve_doc(query)
+        # A key printed by a rendered page may carry the section it pointed at; resolve the page and say
+        # where to look inside it, rather than refusing a key this command handed out.
+        query, anchor = DocLinks.split_anchor(query)
+        @err.puts("rigor: (section `#{anchor}`)") if anchor && !anchor.empty?
         docs = discover_docs
 
         exact = docs.find { |doc| doc.fetch(:exact_aliases).include?(query) }
@@ -146,11 +151,36 @@ module Rigor
         short = docs.select { |doc| doc.fetch(:short_name) == query }
         case short.size
         when 1 then short.first
-        when 0 then name_error(query)
+        when 0 then unpackaged_doc(query) || name_error(query)
         else ambiguous_error(query, short)
         end
       end
 
+      # A key the rendered pages hand out for a document the gem does not carry (ADR-74 ships the manual and
+      # handbook; the ADR / specification / notes corpus and the repository trees stay out). The key is
+      # still answerable — it names a real path — so this routes rather than failing: a reader who followed
+      # `[ADR-103][adr/103-effect-labels]` out of `rigor docs` gets told where that document is, which is the
+      # whole point of handing them the key instead of a dead relative path or a `master` URL.
+      # Categories this command serves itself. A name that fails to resolve inside one of them is a typo,
+      # not an unpackaged document, and must reach the did-you-mean listing rather than be routed to a
+      # repository path that does not exist — `rigor docs list` and `rigor docs pathh` are the cases
+      # that found this.
+      PACKAGED_CATEGORIES = %w[manual handbook].freeze
+      private_constant :PACKAGED_CATEGORIES
+
+      def unpackaged_doc(query)
+        return nil unless query.include?("/")
+        return nil if PACKAGED_CATEGORIES.include?(query.split("/").first)
+
+        path = DocLinks.repository_path(query)
+        return nil if path.nil?
+
+        @err.puts("rigor: `#{query}` is not packaged with this gem — the manual and handbook are, the " \
+                  "design records are not.")
+        @err.puts("rigor: it is `#{path}` in the Rigor repository (#{DocLinks::REPOSITORY}).")
+        1
+      end
+
       # Every bundled doc, each carrying the aliases `rigor docs <name>` accepts and the category used by `--list`.
       # `install.md` sits at the docs root (category `guide`); the rest are manual / handbook chapters.
       def discover_docs

data/lib/rigor/cli/effects_command.rb

@@ -3,7 +3,13 @@
 require "optionparser"
 
 require_relative "../configuration"
-require_relative "../analysis/runner"
+# ADR-104 — `analysis/runner` is required lazily (in `#analyze`), not here: a warm report served by
+# {Analysis::EffectsCacheProbe} must reach its answer without `rigor/inference` in `$LOADED_FEATURES`,
+# which is the whole of the boot saving. The probe pulls only the cache and the effects value layer.
+require_relative "../analysis/effects_cache_probe"
+require_relative "../effects/plugin_facts"
+require_relative "../effects/registry"
+require_relative "../plugin/loader"
 require_relative "../cache/store"
 require_relative "command"
 require_relative "effects_renderer"
@@ -61,7 +67,17 @@ module Rigor
           #{USAGE}
 
           With no subcommand, prints one line per method: its proven effect labels and whether that
-          list is exhaustive.
+          list is exhaustive. A PATH selects which methods are printed, never which are analysed.
+
+          Options:
+            --config=PATH        Path to the Rigor configuration file
+            --format=FORMAT      Output format: text (default) or json
+            --full               List every method, including the ones with nothing to say
+            --label=LABEL        Only methods carrying LABEL (or a label under it), in either lane
+            --pure               Only methods proven to do nothing beyond mutate.local
+            --limit=N            Print at most N methods
+            --why                Expand each method's unresolved reasons and declared-lane sources
+            --list-labels        Print the effect vocabulary this project can name, and exit
 
           Subcommands (the committed effect snapshot, ADR-103 WD7):
             update      Write the snapshot to effects.snapshot.path. Commit it; review its diff.
@@ -78,24 +94,69 @@ module Rigor
         return usage_error("unsupported format: #{options.fetch(:format)}") unless FORMATS.include?(options[:format])
 
         configuration = Configuration.load(options.fetch(:config)).with_effects_enabled
-        table = analyze(configuration)
-        report = EffectsReport.build(table, full: options.fetch(:full))
-        EffectsRenderer.new(out: @out).render(report, format: options.fetch(:format))
+        return list_labels(configuration) if options.fetch(:list_labels)
+
+        scope = @argv.dup
+        table, sources = resolve_table(configuration, scope)
+        report = EffectsReport.build(
+          table, full: options.fetch(:full), sources: sources, scope: scope,
+                 label: options.fetch(:label), pure: options.fetch(:pure), limit: options.fetch(:limit)
+        )
+        note_scope(scope, report, table)
+        EffectsRenderer.new(out: @out, why: options.fetch(:why)).render(report, format: options.fetch(:format))
         0
       end
 
+      # A path argument is a **view**, and the note says so (#439).
+      #
+      # It used to narrow the analysed set, and effect labels are transitive over whatever was analysed —
+      # so `rigor effects app/controllers/issues_controller.rb` reported `IssuesController#create: [] …?`
+      # where the whole-project run reported four labels and a declared lane. The weakened answer was
+      # indistinguishable from a genuinely effect-free method, and a path argument is the only tractability
+      # lever the report has, so it was the thing an adopter reached for first.
+      #
+      # The note goes to stderr rather than into the report: it is about the invocation, not about the
+      # code, and `--format json` and `rigor effects … > report.txt` both stay exactly what they were.
+      def note_scope(scope, report, table)
+        return if scope.empty?
+
+        if report.empty?
+          @err.puts("rigor: no effect unit is defined in #{scope.join(', ')} " \
+                    "(a path selects what is printed, not what is analysed)")
+          return
+        end
+
+        @err.puts("rigor: showing #{report.rows.length} of #{table.size} units, selected by " \
+                  "#{scope.join(', ')}; a path narrows the printing and not the analysis, so every " \
+                  "label is the one the whole-project run reports")
+      end
+
       FORMATS = %w[text json].freeze
       private_constant :FORMATS
 
       def parse_options
-        options = { config: nil, format: "text", full: false, no_tolerated: false }
+        options = { config: nil, format: "text", full: false, no_tolerated: false, label: [], pure: false,
+                    limit: nil, why: false, list_labels: false }
         OptionParser.new do |opts|
           opts.banner = USAGE
           Options.add_config(opts, options)
           opts.on("--format=FORMAT", "Output format: text (default) or json") { |value| options[:format] = value }
-          opts.on("--full", "List every method, including exhaustive ones with no effects beyond mutate.local") do
+          opts.on("--full", "List every method, including the ones with nothing to say") do
             options[:full] = true
           end
+          opts.on("--label=LABEL", "Only methods carrying LABEL (or a label under it), in either lane") do |value|
+            options[:label].concat(value.split(",").map(&:strip).reject(&:empty?))
+          end
+          opts.on("--pure", "Only methods proven to do nothing beyond mutate.local — the %a{pure} set") do
+            options[:pure] = true
+          end
+          opts.on("--limit=N", Integer, "Print at most N methods") { |value| options[:limit] = value }
+          opts.on("--why", "Expand each method's unresolved reasons and declared-lane sources") do
+            options[:why] = true
+          end
+          opts.on("--list-labels", "Print the effect vocabulary this project can name, and exit") do
+            options[:list_labels] = true
+          end
           # Accepted here and deliberately inert, exactly as it is on `update`: the report is an
           # observation, and observations are undischarged. Only a JUDGMENT reads `effects.tolerated:` —
           # `rigor effects check` / `diff`, and `rigor check`'s envelope contract.
@@ -116,15 +177,93 @@ module Rigor
       # the diagnostics entry serves the run and the #382 effects sidecar serves the collections, leaving
       # only the fixpoint. Sequential is not a cache decision — the run-result cache declines pool mode —
       # but a collecting run is pinned to the fork backend anyway, so `workers: 0` costs nothing here.
-      def analyze(configuration)
+      # #429 — the vocabulary, from the product rather than from a document the gem does not ship.
+      #
+      # Four configuration keys and two annotation forms all require typing an effect label, and until
+      # this there was no way to find out what the labels are: the manual's pointers resolve into
+      # `docs/type-specification/`, which `rigortype.gemspec` does not package. The registry is shipped
+      # data and already knows the answer; nothing surfaced it.
+      #
+      # It loads plugins but never analyses, because a plugin is where `rails.flash.write` comes from and
+      # a reader deciding what to write in `effects.envelopes:` needs to see it. A plugin that fails to
+      # load costs its labels and nothing else — `rigor plugins` is where that failure is reported.
+      def list_labels(configuration)
+        registry = project_registry(configuration)
+        @out.puts("Effect vocabulary — #{registry.labels.length} labels (vocabulary #{registry.vocabulary_version})")
+        registry.roots.each do |root|
+          @out.puts
+          @out.puts(root_heading(root, registry))
+          in_root = registry.labels.select { |label| Effects::Label.root(label) == root }
+          in_root.each_slice(4) { |slice| @out.puts("  #{slice.join(', ')}") }
+        end
+        @out.puts
+        @out.puts("A bound naming a label admits everything under it and nothing above it: `io` covers " \
+                  "`io.db.read`, `io.db.read` does not cover `io`.")
+        0
+      end
+
+      # A shipped root carries the registry's own one-liner; a root a plugin or this project opened
+      # carries where it came from instead, which is the more useful thing to say about it.
+      def root_heading(root, registry)
+        description = registry.descriptions[root]
+        return "#{root} — #{description}" if description
+
+        "#{root} — opened by a plugin or by this project's `effects.labels:`"
+      end
+
+      def project_registry(configuration)
+        services = Plugin::Services.new(reflection: Reflection, type: Type::Combinator,
+                                        configuration: configuration, cache_store: nil)
+        plugins = Plugin::Loader.load(configuration: configuration, services: services)
+        Effects::Registry.for_configuration(configuration, plugin_facts: Effects::PluginFacts.build(plugins))
+      rescue StandardError
+        Effects::Registry.for_configuration(configuration)
+      end
+
+      # The analysed set is the configured `paths:` **plus** whatever the arguments name — never the
+      # arguments alone (#439). An effect summary is transitive over whatever was analysed, so analysing
+      # less does not filter the report, it lowers every answer in it: `rigor effects
+      # app/controllers/issues_controller.rb` used to report `IssuesController#create: [] …?` where the
+      # whole-project run reported four labels and a declared lane, with nothing marking the difference.
+      #
+      # The union rather than the configured paths alone, so that pointing the command at a tree the
+      # configuration does not cover — which is what every `rigor effects PATH` invocation from outside a
+      # project does — still analyses it. Inside a project the argument is already under `paths:` and the
+      # union is the configured set unchanged.
+      #
+      # @return [Array(Rigor::Effects::EffectTable, Hash{String=>Array<String>})] the table, and which
+      #   file each unit was defined in — the map {EffectsReport} needs to answer a path argument.
+      def analyze(configuration, scope)
+        require_relative "../analysis/runner"
         runner = Analysis::Runner.new(
           configuration: configuration,
           cache_store: Cache::Store.new(root: configuration.cache_path),
           collect_stats: false,
           workers: 0
         )
-        runner.run(@argv.empty? ? configuration.paths : @argv)
-        runner.effect_table
+        runner.run((configuration.paths + scope).uniq)
+        [runner.effect_table, runner.effect_sources]
+      end
+
+      # ADR-104 — the report before the engine. A warm run's whole answer is the #482 summary entry, so
+      # {Analysis::EffectsCacheProbe} tries to serve it without loading `rigor/inference`; any decline
+      # falls through to the full runner, which behaves exactly as it did.
+      #
+      # The report is a pure function of the table, the sources and the configuration: the envelope
+      # diagnostics the analysing path also computes are discarded here (this method reads the table
+      # and the sources and nothing else), which is what makes the served answer identical rather than
+      # merely similar.
+      def resolve_table(configuration, scope)
+        served = probe(configuration, scope)
+        return [served.table, served.sources] if served
+
+        analyze(configuration, scope)
+      end
+
+      def probe(configuration, scope)
+        Analysis::EffectsCacheProbe.new(
+          configuration: configuration, cache_root: configuration.cache_path
+        ).serve((configuration.paths + scope).uniq)
       end
     end
   end

data/lib/rigor/cli/effects_diff_renderer.rb

@@ -2,6 +2,8 @@
 
 require "json"
 
+require_relative "../effects/definition_lines"
+require_relative "../effects/snapshot"
 require_relative "../effects/snapshot_diff"
 require_relative "renderable"
 
@@ -16,8 +18,9 @@ module Rigor
     # the one line the whole workflow turns on: intent is expressed by regenerating and committing the
     # file, not by annotating the code.
     #
-    # It is deliberately not a diagnostic format: no severities, no positions, no exit-code weight of its
-    # own. The exit code comes from the gate.
+    # It is deliberately not a diagnostic format: no severities and no exit-code weight of its own — the
+    # exit code comes from the gate. A row carries a position for a reader to jump to, never one a
+    # `# rigor:disable` or a baseline could act on.
     class EffectsDiffRenderer
       include Renderable
 
@@ -35,11 +38,29 @@ module Rigor
 
       HEDGED_REMOVAL = "-? %<label>s (current summary is not exhaustive)"
 
-      CLOSING_LINE = "Run `rigor effects update` and commit the result if this change is intended."
-
-      def initialize(out:, path:)
+      # Both commands, because they answer the two questions a drift report raises and a reader almost
+      # always asks them in this order (#435). `explain` is the one the manual's own narrative reaches for
+      # first, and the footer used to name only the one that makes the report go away.
+      CLOSING_LINE = "Run `rigor effects explain` to see what caused this, and `rigor effects update` to " \
+                     "accept it."
+
+      # A regeneration event routes to `update` alone: `explain` answers "what caused this label to
+      # appear", and the answer here is "the record was written under different rules", which explain
+      # cannot expand and the line above already said.
+      REGENERATION_CLOSING_LINE = "Run `rigor effects update` to regenerate the record under the current " \
+                                  "rules."
+
+      # @param sources [Hash{String=>Array<String>}] `Runner#effect_sources` — where each unit is defined.
+      #   A drift row names `file:line` so a reviewer does not have to search for the method (#435). The
+      #   file rides the cached summary entry and is free; the line is resolved by parsing the row's own
+      #   file ({Effects::DefinitionLines}), which is why a fresh report — no rows — still parses nothing
+      #   and the whole-project parse ADR-104 removed from this command stays removed.
+      # @param lines [Effects::DefinitionLines] seam for the specs; the default parses on demand.
+      def initialize(out:, path:, sources: nil, lines: Effects::DefinitionLines.new)
         @out = out
         @path = path
+        @sources = sources || {}
+        @lines = lines
       end
 
       private
@@ -63,10 +84,7 @@ module Rigor
 
         @out.puts("")
         @out.puts("#{section_name(table)}:")
-        events.each do |event|
-          suffix = qualified ? "  (#{event.table})" : ""
-          @out.puts("  #{render_event(event)}#{suffix}")
-        end
+        events.each { |event| @out.puts("  #{render_event(event, qualified: qualified)}") }
       end
 
       def section_name(table)
@@ -77,9 +95,38 @@ module Rigor
         end
       end
 
-      def render_event(event)
+      def render_event(event, qualified: false)
         marker = marker_for(event)
-        event.symbol.nil? ? marker : "#{event.symbol}  #{marker}"
+        return marker if event.symbol.nil?
+
+        "#{event.symbol}  #{marker}#{annotation(event, qualified)}"
+      end
+
+      # One parenthetical, never two: where the unit is defined, and — under `tolerated:`, which pools
+      # both tables — which table the event came from. A row with no known source under `tolerated:`
+      # renders exactly as it did before this suffix existed.
+      #
+      # A unit defined by a reopening spans several files and the row names them all rather than picking
+      # one; which of them a reviewer wants is exactly what the row cannot know.
+      def annotation(event, qualified)
+        parts = sources_of(event.symbol).map { |path, line| line ? "#{path}:#{line}" : path }
+        parts << event.table if qualified
+        parts.empty? ? "" : "  (#{parts.join(', ')})"
+      end
+
+      # Where a symbol is defined, as the two renderings share it — one implementation, so the text form
+      # and the JSON one cannot disagree about a position (WD3's rule).
+      #
+      # **A removed symbol has no entry here at all**, and cannot: `sources` is the CURRENT run's, and a
+      # method that no longer exists was not defined by it. Such a row renders exactly as it did before
+      # this suffix existed.
+      #
+      # @return [Array<Array(String, Integer)>] `[relative path, line]` per file, the line nil when that
+      #   file spells the key with no `def` — an accessor, or a definition the nesting cannot name.
+      def sources_of(symbol)
+        Array(@sources[symbol]).map do |path|
+          [Effects::Snapshot.relativize(path, Dir.pwd), @lines.for(key: symbol, path: path)]
+        end
       end
 
       def marker_for(event)
@@ -95,21 +142,48 @@ module Rigor
       def render_footer(diff)
         footer = diff.footer
         @out.puts("")
+        @out.puts(withheld_line(footer)) if diff.regeneration?
         unless footer[:added_symbols].zero? && footer[:removed_symbols].zero?
           @out.puts("symbols: +#{footer[:added_symbols]} / -#{footer[:removed_symbols]} " \
                     "(a rename is one of each)")
         end
-        @out.puts(CLOSING_LINE)
+        @out.puts(diff.regeneration? ? REGENERATION_CLOSING_LINE : CLOSING_LINE)
+      end
+
+      # What a regeneration withheld, said as a count. The counts below it are still printed, so the
+      # reader sees the scale of the difference without reading it row by row.
+      def withheld_line(footer)
+        suppressed = footer[:suppressed]
+        return "The two records are not comparable, so no per-method difference is shown." if
+          suppressed.zero?
+
+        noun = suppressed == 1 ? "1 per-method difference is" : "#{suppressed} per-method differences are"
+        "The two records were computed under different rules and are not comparable, so #{noun} not shown."
+      end
+
+      # The machine form carries the same position the text one prints (#435): a bot that annotates a pull
+      # request is the consumer with the most use for a line and the least ability to find one itself.
+      # `sources` is omitted rather than emitted empty when the row names nothing — a removed symbol.
+      def event_json(event)
+        row = event.to_h
+        sources = sources_of(event.symbol)
+        return row if sources.empty?
+
+        row.merge("sources" => sources.map do |path, line|
+          line ? { "path" => path, "line" => line } : { "path" => path }
+        end)
       end
 
       def render_json(diff)
         @out.puts(JSON.pretty_generate(
                     "fresh" => diff.fresh?,
-                    "events" => diff.events.map(&:to_h),
+                    "events" => diff.events.map { |event| event_json(event) },
                     "footer" => {
                       "added_symbols" => diff.footer[:added_symbols],
-                      "removed_symbols" => diff.footer[:removed_symbols]
+                      "removed_symbols" => diff.footer[:removed_symbols],
+                      "suppressed" => diff.footer[:suppressed]
                     },
+                    "regeneration" => diff.regeneration?,
                     "header" => {
                       "snapshot" => @path,
                       "gate" => diff.gate.to_s,

data/lib/rigor/cli/effects_explain_renderer.rb

@@ -22,8 +22,9 @@ module Rigor
     class EffectsExplainRenderer
       include Renderable
 
-      # One printed explanation. `path` is empty for a `methods:` row, whose explanation is the origin.
-      Row = Data.define(:table, :symbol, :label, :path, :origin)
+      # One printed explanation. `path` is empty for a `methods:` row, whose explanation is the origin;
+      # `causes` is non-empty only for an exhaustiveness row, which has neither (#435).
+      Row = Data.define(:table, :symbol, :label, :path, :origin, :causes)
 
       def initialize(out:)
         @out = out
@@ -44,6 +45,7 @@ module Rigor
       end
 
       def render_row(row)
+        return "#{row.symbol} stopped being exhaustive ← #{row.causes.join(', ')}" unless row.causes.empty?
         return "#{row.path.join(' → ')} [#{row.label}]" unless row.path.empty?
 
         origin = row.origin ? " ← #{row.origin}" : ""
@@ -58,7 +60,8 @@ module Rigor
                         "symbol" => row.symbol,
                         "label" => row.label,
                         "path" => row.path,
-                        "origin" => row.origin
+                        "origin" => row.origin,
+                        "causes" => row.causes
                       }
                     end
                   ))

data/lib/rigor/cli/effects_renderer.rb

@@ -16,17 +16,53 @@ module Rigor
     class EffectsRenderer
       include Renderable
 
-      def initialize(out:)
+      def initialize(out:, why: false)
         @out = out
+        @why = why
       end
 
       private
 
+      # The reason block is **collapsed to a count** by default (#434). It was 86.5 % of the bytes of a
+      # 31,191-line Redmine run, and it answers a question a reader asks about one row after reading many
+      # — so `--why` expands it, and the count is what stays on the line that made them curious.
       def render_text(report)
         report.rows.each do |row|
-          @out.puts("#{row.key}: [#{row.effects.join(', ')}]#{declared(row)}#{' …?' unless row.exhaustive?}")
+          @out.puts("#{row.key}: [#{row.effects.join(', ')}]#{declared(row)}#{hedge(row)}")
+          next unless @why
+
           row.causes.each { |cause, detail| @out.puts("    #{cause}#{" (#{detail})" if detail}") }
+          row.attribution.each { |origin, labels| @out.puts("    #{origin} → [#{labels.join(', ')}]") }
         end
+        render_footer(report.totals)
+      end
+
+      def hedge(row)
+        return "" if row.exhaustive?
+        return " …?" if @why || row.causes.empty?
+
+        " …? (#{row.causes.length} #{row.causes.length == 1 ? 'reason' : 'reasons'}, --why)"
+      end
+
+      # The footer a 31,191-line report never had, and the reason it counts the two lanes apart: a
+      # declared label can never fail a build (ADR-103 § WD17), so a reader who sees one total cannot tell
+      # which half of the report is a policy surface and which half is a record to review the diff of.
+      def render_footer(totals)
+        return if totals.nil?
+
+        @out.puts("──")
+        @out.puts("#{totals.printed} of #{totals.units} units printed#{omitted(totals)}")
+        @out.puts("#{totals.proven} carry a proven label · #{totals.declared} carry a declared (≤) one " \
+                  "· #{totals.exhaustive} are exhaustive")
+      end
+
+      # Two ways a row can be missing, counted apart because `--full` answers only one of them.
+      def omitted(totals)
+        parts = []
+        parts << "#{totals.omitted} omitted (--full)" if totals.omitted.positive?
+        parts << "#{totals.unselected} not selected" if totals.unselected.positive?
+        parts << "#{totals.truncated} cut by --limit" if totals.truncated.positive?
+        parts.empty? ? "" : "; #{parts.join(', ')}"
       end
 
       # `≤` is the lane's spelling everywhere in the model — an upper bound, not an observation — so the
@@ -43,10 +79,12 @@ module Rigor
               "declared" => row.declared,
               "exhaustive" => row.exhaustive?,
               "causes" => row.causes.map { |cause, detail| [cause, detail] },
-              "direct" => row.direct
+              "direct" => row.direct,
+              "attribution" => row.attribution
             }]
           end
         }
+        payload["totals"] = report.totals.to_h.transform_keys(&:to_s) if report.totals
         @out.puts(JSON.pretty_generate(payload))
       end
     end