rigortype 0.3.5 → 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,10 @@
 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"
@@ -94,7 +97,7 @@ module Rigor
         return list_labels(configuration) if options.fetch(:list_labels)
 
         scope = @argv.dup
-        table, sources = analyze(configuration, scope)
+        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)
@@ -231,6 +234,7 @@ module Rigor
       # @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),
@@ -240,6 +244,27 @@ module Rigor
         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
 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
 
@@ -41,9 +44,23 @@ module Rigor
       CLOSING_LINE = "Run `rigor effects explain` to see what caused this, and `rigor effects update` to " \
                      "accept it."
 
-      def initialize(out:, path:)
+      # 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
@@ -67,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)
@@ -81,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)
@@ -99,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_snapshot_command.rb

@@ -3,7 +3,9 @@
 require "did_you_mean"
 require "optionparser"
 
-require_relative "../analysis/runner"
+# ADR-104 — `analysis/runner` is required lazily (in `#analyze`): a warm snapshot verb served by the
+# probe must reach its answer without `rigor/inference` in `$LOADED_FEATURES`.
+require_relative "../analysis/effects_cache_probe"
 require_relative "../cache/store"
 require_relative "../configuration"
 require_relative "../effects/discharge"
@@ -111,7 +113,8 @@ module Rigor
         )
         return explain(diff, options) if @verb == "explain"
 
-        EffectsDiffRenderer.new(out: @out, path: path).render(diff, format: options.fetch(:format))
+        EffectsDiffRenderer.new(out: @out, path: path, sources: @sources)
+                           .render(diff, format: options.fetch(:format))
         @verb == "check" && diff.drift? ? 1 : 0
       end
 
@@ -163,6 +166,9 @@ module Rigor
       # `methods:` change gets the origin in the method's own body.
       def rows_for_changes(diff)
         diff.events.flat_map do |event|
+          next exhaustiveness_rows(event) if
+            event.category == Effects::SnapshotDiff::EXHAUSTIVE_LOST
+
           labels = labels_of(event)
           next [] if labels.empty?
 
@@ -178,13 +184,29 @@ module Rigor
         entry ? entry.proven.to_a : []
       end
 
+      # `exhaustive → not` is the drift row a reader is least equipped to interpret, and it was the one
+      # row `explain` could not expand (#435): it carries no label, so {#labels_of} answered with nothing
+      # and the event produced no explanation at all. What explains it is the taint causes — the calls
+      # the analyzer could not follow — which is the detail the snapshot stopped recording per row
+      # (#434). The two halves meet here: the record keeps the stable count, and this names them.
+      def exhaustiveness_rows(event)
+        entry = @table[event.symbol]
+        return [] if entry.nil?
+
+        causes = Effects::Snapshot.render_causes(entry.causes)
+        return [] if causes.empty?
+
+        [EffectsExplainRenderer::Row.new(table: event.table, symbol: event.symbol, label: nil,
+                                         path: [].freeze, origin: nil, causes: causes)]
+      end
+
       def reach_rows(symbol, labels)
         labels.filter_map do |label|
           path = Effects::PathFinder.shortest(@table, symbol: symbol, label: label)
           next if path.nil?
 
           EffectsExplainRenderer::Row.new(table: "reach", symbol: symbol, label: label,
-                                          path: path.to_a, origin: path.origin)
+                                          path: path.to_a, origin: path.origin, causes: [].freeze)
         end
       end
 
@@ -197,7 +219,7 @@ module Rigor
           next if origin.nil?
 
           EffectsExplainRenderer::Row.new(table: "methods", symbol: symbol, label: label,
-                                          path: [].freeze, origin: origin.to_s)
+                                          path: [].freeze, origin: origin.to_s, causes: [].freeze)
         end
       end
 
@@ -207,7 +229,20 @@ module Rigor
       # the ADR-45 whole-run result cache like `rigor check` — the diagnostics entry plus the #382 effects
       # sidecar keyed beside it, so `rigor effects check` after `rigor check` under a configured `effects:`
       # block is a warm hit plus the fixpoint.
+      # ADR-104 — a snapshot is built from the table, the sources and the vocabulary, all three of which
+      # the #482 summary entry (plus the plugins' own declarations) carries, so a warm run takes the
+      # probe and never loads the engine. A decline is the runner path below, unchanged.
       def build_snapshot(configuration, full:)
+        served = Analysis::EffectsCacheProbe.new(
+          configuration: configuration, cache_root: configuration.cache_path
+        ).serve(configuration.paths)
+        return snapshot_from(configuration, full, served) if served
+
+        snapshot_from(configuration, full, analyze(configuration))
+      end
+
+      def analyze(configuration)
+        require_relative "../analysis/runner"
         runner = Analysis::Runner.new(
           configuration: configuration,
           cache_store: Cache::Store.new(root: configuration.cache_path),
@@ -215,14 +250,24 @@ module Rigor
           workers: 0
         )
         runner.run(configuration.paths)
-        @table = runner.effect_table
-        Effects::Snapshot.build(
-          table: @table, configuration: configuration, sources: runner.effect_sources, full: full,
+        Analysis::EffectsCacheProbe::Served.new(
+          table: runner.effect_table, sources: runner.effect_sources, plugin_facts: nil,
           registry: Effects::Registry.for_configuration(configuration,
                                                         plugin_facts: runner.effect_plugin_facts)
         )
       end
 
+      # WD3 — one build, whichever lane produced the inputs, so a served snapshot and an analysed one
+      # cannot drift in how they are assembled.
+      def snapshot_from(configuration, full, served)
+        @table = served.table
+        @sources = served.sources
+        Effects::Snapshot.build(
+          table: @table, configuration: configuration, sources: served.sources, full: full,
+          registry: served.registry
+        )
+      end
+
       # ---- options ------------------------------------------------
 
       def parse_options