rigortype 0.3.5 → 0.3.7

data/lib/rigor/cli/check_command.rb

@@ -11,7 +11,6 @@ require_relative "../analysis/rule_catalog"
 # The baseline filter runs on EVERY exit path — including the ADR-87 WD4 cache-HIT fast path, which skips
 # `load_check_dependencies` — so it must be a load-time require. It pulls only YAML, never the engine.
 require_relative "../analysis/baseline"
-require_relative "../runtime/jit"
 require_relative "command"
 require_relative "options"
 require_relative "diagnostic_formats"
@@ -34,12 +33,10 @@ module Rigor
     # concerns that are clearer read together than split across micro-classes.
     class CheckCommand < Command # rubocop:disable Metrics/ClassLength
       # @return [Integer] CLI exit status.
-      def run # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
-        # Arm deferred YJIT enablement before any analysis work: the deadline
-        # thread only fires once a run outlasts the amortization window, so a
-        # short check finishes before it ever pays JIT compile cost while a
-        # long run JITs its dominant tail (Runtime::Jit).
-        Runtime::Jit.enable_after(Runtime::Jit.deadline_seconds)
+      #
+      # Deferred YJIT enablement (Runtime::Jit) is armed by `CLI#dispatch` for every command, this
+      # one included, before any analysis work runs.
+      def run # rubocop:disable Metrics/AbcSize
         # ADR-87 WD4 — parse options + resolve config WITHOUT the inference engine, so the run-cache hit probe
         # can run first. The heavy engine (`load_check_dependencies`) loads only on a miss / non-cacheable run.
         options = parse_check_options
@@ -50,7 +47,7 @@ module Rigor
         configuration = apply_bleeding_edge_override(configuration, options)
         config_warnings = warn_unresolved_config(configuration)
         cache_root = configuration.cache_path
-        handle_clear_cache(cache_root) if options.fetch(:clear_cache)
+        handle_clear_cache(cache_root, options.fetch(:format)) if options.fetch(:clear_cache)
 
         # ADR-87 WD4 — try to serve the whole run from the ADR-45 cache before booting the engine. A hit boots
         # only CLI + config + cache + digest code (no `rigor/inference`), skipping the plugin prepass + env
@@ -76,7 +73,7 @@ module Rigor
         write_run_stats(result.stats) if result.stats
         write_trace_appendices
         runner.cache_store&.evict!
-        write_cache_stats(cache_root, runner.cache_store) if options.fetch(:cache_stats)
+        write_cache_stats(cache_root, runner.cache_store, options.fetch(:format)) if options.fetch(:cache_stats)
 
         exit_code = result.success? ? 0 : 1
         exit_code = 1 if baseline_strict_violation?(raw_result.diagnostics, configuration, options)
@@ -195,7 +192,8 @@ module Rigor
         incremental = normalize_diagnostics(session.reanalyze_subset(subset))
         full = normalize_diagnostics(verify_full_diagnostics(configuration, paths))
 
-        report_verify_incremental(incremental, full, subset_size: subset.size, total: analyzed.size)
+        report_verify_incremental(incremental, full, subset_size: subset.size, total: analyzed.size,
+                                                     format: options.fetch(:format))
       end
 
       # ADR-46 — cross-process incremental analysis (`--incremental`). Derives the global fingerprint cheaply (no RBS
@@ -230,7 +228,8 @@ module Rigor
         @err.puts("rigor: --incremental #{warm ? 'warm — reused cached diagnostics' : 'cold — full analysis'} " \
                   "(#{session.analyzed_files.size} files)")
         emit_incremental_fact_surface_notes(session)
-        write_incremental_cache_stats(session, cache_root, store) if options.fetch(:cache_stats)
+        write_incremental_cache_stats(session, cache_root, store, options.fetch(:format)) if
+          options.fetch(:cache_stats)
 
         result = apply_baseline_filter(Analysis::Result.new(diagnostics: diagnostics, stats: nil), configuration,
                                        options)
@@ -286,8 +285,8 @@ module Rigor
       # does) plus the fact-surface status line, so an operator can see whether a full run was fact-surface
       # driven. The plain `check` cache-stats path is bypassed by the incremental short-circuit, so it is
       # emitted here.
-      def write_incremental_cache_stats(session, cache_root, store)
-        write_cache_stats(cache_root, store)
+      def write_incremental_cache_stats(session, cache_root, store, format)
+        write_cache_stats(cache_root, store, format)
         status =
           if !session.opaque_plugin_ids.empty?
             "opaque (#{session.opaque_plugin_ids.sort.join(', ')})"
@@ -296,7 +295,7 @@ module Rigor
           else
             "unchanged"
           end
-        @out.puts("  plugin fact surface: #{status}")
+        side_output(format).puts("  plugin fact surface: #{status}")
       end
 
       def verify_full_diagnostics(configuration, paths)
@@ -310,11 +309,14 @@ module Rigor
         end
       end
 
-      def report_verify_incremental(incremental, full, subset_size:, total:)
+      # The OK line follows the same rule as the other side outputs (#493) — stdout under `text`, stderr
+      # under a machine format. The FAILED branch below has always gone to stderr: it is a failure
+      # report, and a run that produced one has no valid document to protect anyway.
+      def report_verify_incremental(incremental, full, subset_size:, total:, format: "text")
         if incremental == full
-          @out.puts("rigor: --verify-incremental OK — incremental " \
-                    "(#{subset_size}/#{total} files re-analyzed, rest from cache) " \
-                    "matches full (#{full.size} diagnostics)")
+          side_output(format).puts("rigor: --verify-incremental OK — incremental " \
+                                   "(#{subset_size}/#{total} files re-analyzed, rest from cache) " \
+                                   "matches full (#{full.size} diagnostics)")
           return 0
         end
 
@@ -495,46 +497,46 @@ module Rigor
           end
           Options.add_editor_mode(opts, options)
           opts.on("--baseline=PATH",
-                  "ADR-22: load baseline from PATH (overrides .rigor.yml `baseline:`)") do |value|
+                  "load baseline from PATH (overrides .rigor.yml `baseline:`)") do |value|
             options[:baseline] = value
           end
           opts.on("--no-baseline",
-                  "ADR-22: ignore any configured baseline for this run") do
+                  "ignore any configured baseline for this run") do
             options[:baseline] = false
           end
           opts.on("--baseline-strict",
-                  "ADR-22: fail the run on any baseline drift (CI gate)") do
+                  "fail the run on any baseline drift (CI gate)") do
             options[:baseline_strict] = true
           end
           opts.on("--treat-all-as-inline-rbs",
-                  "ADR-32: force-load rigor-rbs-inline with require_magic_comment: false") do
+                  "force-load rigor-rbs-inline with require_magic_comment: false") do
             options[:treat_all_as_inline_rbs] = true
           end
           opts.on("--verify-incremental",
-                  "ADR-46: assert incremental analysis matches a full run, then exit") do
+                  "assert incremental analysis matches a full run, then exit") do
             options[:verify_incremental] = true
           end
           opts.on("--incremental",
-                  "ADR-46: re-analyze only files changed since the last run (cross-process cache)") do
+                  "re-analyze only files changed since the last run (cross-process cache)") do
             options[:incremental] = true
           end
           opts.on("--no-ci-detect",
-                  "ADR-51: do not auto-emit CI-native output when a CI environment is detected") do
+                  "do not auto-emit CI-native output when a CI environment is detected") do
             options[:ci_detect] = false
           end
           # ADR-50 § WD2 — `=[LIST]` (not ` [LIST]`) so a bare `--bleeding-edge` never swallows a following positional
           # path: `rigor check --bleeding-edge lib` adopts the whole overlay and checks `lib`.
           opts.on("--bleeding-edge=[LIST]",
-                  "ADR-50: adopt the bleeding-edge overlay for this run " \
+                  "adopt the bleeding-edge overlay for this run " \
                   "(all features, or a comma-separated feature-id list)") do |value|
             options[:bleeding_edge] = value.nil? || value.split(",").map(&:strip).reject(&:empty?)
           end
           opts.on("--no-bleeding-edge",
-                  "ADR-50: ignore any configured bleeding_edge: selection for this run") do
+                  "ignore any configured bleeding_edge: selection for this run") do
             options[:bleeding_edge] = false
           end
           opts.on("--no-tolerated-effects",
-                  "ADR-103: check effect envelopes as if effects.tolerated: were empty") do
+                  "check effect envelopes as if effects.tolerated: were empty") do
             options[:no_tolerated_effects] = true
           end
         end
@@ -599,12 +601,13 @@ module Rigor
         }]
       end
 
-      def handle_clear_cache(cache_root)
+      def handle_clear_cache(cache_root, format)
+        out = side_output(format)
         if File.directory?(cache_root)
           FileUtils.rm_rf(cache_root)
-          @out.puts("Cleared cache: #{cache_root}")
+          out.puts("Cleared cache: #{cache_root}")
         else
-          @out.puts("Cache already empty: #{cache_root}")
+          out.puts("Cache already empty: #{cache_root}")
         end
       end
 
@@ -772,42 +775,43 @@ module Rigor
         Kernel.format("%.1f MB", bytes / 1_048_576.0)
       end
 
-      def write_cache_stats(cache_root, runtime_store)
+      def write_cache_stats(cache_root, runtime_store, format)
         inv = Cache::Store.disk_inventory(root: cache_root)
+        out = side_output(format)
 
-        @out.puts("")
-        @out.puts("Cache (root: #{inv.fetch(:root)})")
+        out.puts("")
+        out.puts("Cache (root: #{inv.fetch(:root)})")
         schema = inv.fetch(:schema_version)
-        @out.puts("  schema_version: #{schema.nil? ? 'absent' : schema}")
-        write_disk_inventory(inv)
-        write_runtime_stats(runtime_store) if runtime_store
+        out.puts("  schema_version: #{schema.nil? ? 'absent' : schema}")
+        write_disk_inventory(inv, out)
+        write_runtime_stats(runtime_store, out) if runtime_store
       end
 
-      def write_disk_inventory(inv)
+      def write_disk_inventory(inv, out)
         if inv.fetch(:total_entries).zero?
-          @out.puts("  (empty)")
+          out.puts("  (empty)")
           return
         end
 
-        @out.puts("  #{inv.fetch(:total_entries)} entries, #{format_bytes(inv.fetch(:total_bytes))}")
+        out.puts("  #{inv.fetch(:total_entries)} entries, #{format_bytes(inv.fetch(:total_bytes))}")
         inv.fetch(:producers).each do |producer|
           bytes = format_bytes(producer.fetch(:bytes))
-          @out.puts("    #{producer.fetch(:id)}: #{producer.fetch(:entries)} entries, #{bytes}")
+          out.puts("    #{producer.fetch(:id)}: #{producer.fetch(:entries)} entries, #{bytes}")
         end
       end
 
-      def write_runtime_stats(store)
+      def write_runtime_stats(store, out)
         stats = store.stats
         hits = stats.fetch(:hits)
         misses = stats.fetch(:misses)
         writes = stats.fetch(:writes)
-        @out.puts("  this run: #{hits} #{plural(hits, 'hit')}, " \
-                  "#{misses} #{plural(misses, 'miss', 'misses')}, " \
-                  "#{writes} #{plural(writes, 'write')}")
+        out.puts("  this run: #{hits} #{plural(hits, 'hit')}, " \
+                 "#{misses} #{plural(misses, 'miss', 'misses')}, " \
+                 "#{writes} #{plural(writes, 'write')}")
         stats.fetch(:by_producer).each do |id, counts|
-          @out.puts("    #{id}: #{counts.fetch(:hits)} #{plural(counts.fetch(:hits), 'hit')}, " \
-                    "#{counts.fetch(:misses)} #{plural(counts.fetch(:misses), 'miss', 'misses')}, " \
-                    "#{counts.fetch(:writes)} #{plural(counts.fetch(:writes), 'write')}")
+          out.puts("    #{id}: #{counts.fetch(:hits)} #{plural(counts.fetch(:hits), 'hit')}, " \
+                   "#{counts.fetch(:misses)} #{plural(counts.fetch(:misses), 'miss', 'misses')}, " \
+                   "#{counts.fetch(:writes)} #{plural(counts.fetch(:writes), 'write')}")
         end
       end
 
@@ -822,6 +826,21 @@ module Rigor
         format("%.1f MiB", bytes / (1024.0 * 1024.0))
       end
 
+      # Where a human-readable side output goes (#493).
+      #
+      # `--format text` is prose already, so an extra block after the diagnostics is just more prose. Every
+      # other format is a machine contract — a SARIF document a code-scanning upload parses, a Checkstyle
+      # or JUnit XML tree, a GitLab Code Quality array — and appending `Cache (root: …)` to it produces a
+      # document the consumer rejects. Measured: all seven non-text formats were corrupted by
+      # `--cache-stats`, and JSON / SARIF / GitLab failed to parse at all.
+      #
+      # The information is not dropped, because it is what the user asked for by passing the flag; it moves
+      # to stderr, which is where this command already routes everything it says about a run rather than
+      # about the code.
+      def side_output(format)
+        format == "text" ? @out : @err
+      end
+
       def write_result(result, format, coverage: nil, config_warnings: [])
         case format
         when "json"

data/lib/rigor/cli/coverage_command.rb

@@ -14,7 +14,6 @@ require_relative "../inference/parameter_inference_collector"
 require_relative "../protection/mutation_scanner"
 require_relative "../protection/test_suite_oracle"
 require_relative "../language_server/project_context"
-require_relative "../runtime/jit"
 require_relative "../scope"
 require_relative "coverage_report"
 require_relative "coverage_renderer"
@@ -55,11 +54,11 @@ module Rigor
       DEFAULT_TEST_COMMAND = %w[bundle exec rake].freeze
 
       # @return [Integer] CLI exit status.
-      def run # rubocop:disable Metrics/AbcSize
-        # Arm deferred YJIT enablement (Runtime::Jit): a scan long enough to
-        # amortize JIT compile cost enables mid-flight; a short one finishes
-        # first and never pays it. Same seam as `rigor check`.
-        Runtime::Jit.enable_after(Runtime::Jit.deadline_seconds)
+      #
+      # Deferred YJIT enablement (Runtime::Jit) is armed by `CLI#dispatch` for every command, this
+      # one included: a scan long enough to amortize JIT compile cost enables mid-flight; a short one
+      # finishes first and never pays it.
+      def run
         options = parse_options
         return mutation_misuse_error if options[:mutation] && !options[:protection]
         return with_tests_misuse_error if options[:with_tests] && !options[:mutation]
@@ -218,24 +217,23 @@ module Rigor
       # class. Tier 1 seeds unconditionally because it only reclassifies sites it already counted; Tier 2 adds
       # sites to a denominator `--threshold` gates CI on, which is why only the latter is gated on a feature id.
       def scope_with_inferred_params(paths, configuration, environment, workers)
-        base = Scope.empty(environment: environment)
-        seed = {}
-
-        discovered = Inference::ScopeIndexer.discovered_classes_for_paths(paths)
-        seed[:discovered_classes] = discovered unless discovered.empty?
-
-        table = Inference::ParameterInferenceCollector.collect(
-          files: paths, environment: environment, target_ruby: configuration.target_ruby, workers: workers
+        CoverageScan.discovery_seeded_scope(
+          files: paths, configuration: configuration, environment: environment,
+          parameter_inference: true, workers: workers
         )
-        seed[:param_inferred_types] = table unless table.empty?
-
-        return base if seed.empty?
-
-        base.with_discovery(base.discovery.with(**seed))
       end
 
+      # Issue #686 — an unmeasured file fails the build the way a parse error already does, and for the same
+      # reason: the command could not measure part of what it was asked about, so its ratio is an answer to
+      # a smaller question than the user asked. Deliberately NOT routed through `--threshold`, which the
+      # line below applies to a ratio: a crashed file's mutants leave `killed + survived` at zero, the
+      # project ratio is then computed over the files that DID work, and a run that measured nothing at all
+      # came out at 1.0 and passed every threshold. It is also deliberately not the `harness_errors` count,
+      # which #264 keeps out of the exit code on purpose — a few rescued mutants are the transient that
+      # bucket exists to make visible, while a wholly unmeasured FILE is not a transient.
       def determine_protection_exit(report, options)
         return 1 unless report.parse_errors.empty?
+        return 1 if unmeasured_files_in(report).positive?
 
         threshold = options[:threshold]
         return 0 if threshold.nil?
@@ -243,6 +241,12 @@ module Rigor
         report.ratio < threshold ? 1 : 0
       end
 
+      # Issue #686 — the one reader of the count, shared with the stderr warning. The Tier-1 protection
+      # report has no such notion, so a report without the field reads as zero rather than erroring.
+      def unmeasured_files_in(report)
+        report.respond_to?(:unmeasured_files) ? report.unmeasured_files : 0
+      end
+
       def usage_error
         @err.puts("coverage: at least one path is required")
         @err.puts(USAGE)
@@ -255,11 +259,11 @@ module Rigor
 
       # The protection scan must see the same receiver types `rigor check` does — including plugin-contributed
       # `dynamic_return` types (a controller's `params` → `ActionController::Parameters`, a `Model.where` →
-      # `ActiveRecord::Relation[Model]`). The bare `CoverageScan.project_environment` carries only the RBS environment
-      # (no plugin registry), so every plugin-typed receiver reads `Dynamic` and its dispatch site is miscounted as
-      # *unprotected* — a systematic undercount of what Rigor actually types on a plugin-using project.
-      # `ProjectContext` builds the plugin-aware environment (registry materialised + the per-run prepare pass that
-      # primes producers like the controller / model index) exactly as the LSP and the runner do.
+      # `ActiveRecord::Relation[Model]`). A bare RBS environment carries no plugin registry, so every plugin-typed
+      # receiver reads `Dynamic` and its dispatch site is miscounted as *unprotected* — a systematic undercount of
+      # what Rigor actually types on a plugin-using project. `ProjectContext` builds the plugin-aware environment
+      # (registry materialised + the per-run prepare pass that primes producers like the controller / model index)
+      # exactly as the LSP, the runner, and — since #513 — the precision path all do.
       def plugin_aware_environment(configuration)
         LanguageServer::ProjectContext.new(configuration: configuration).environment
       end

data/lib/rigor/cli/coverage_mutation.rb

@@ -9,6 +9,8 @@ require_relative "../protection/dependency_closure"
 require_relative "../protection/discovery_seed"
 require_relative "../protection/mutation_cache"
 
+require_relative "measurement_integrity_warning"
+
 module Rigor
   class CLI
     # ADR-63 Tier 2 + ADR-70 — the mutation-effectiveness and fused static∪dynamic protection paths, factored out of
@@ -43,17 +45,13 @@ module Rigor
 
       private
 
-      # @param report [MutationProtectionReport, FusedProtectionReport] — both expose `total_harness_errors`.
+      # Both measurement-integrity warnings, and the escalation rule between them, live in
+      # {MeasurementIntegrityWarning}. Only the floor stays here: it is this command's policy, and
+      # `coverage_command_spec` reads it off this module.
+      #
+      # @param report [MutationProtectionReport, FusedProtectionReport]
       def warn_harness_errors(report)
-        count = report.total_harness_errors
-        return if count < HARNESS_ERROR_WARN_FLOOR
-
-        @err.puts(
-          "coverage: #{count} mutants failed inside the measurement harness (\"harness_errors\", " \
-          "at/above the #{HARNESS_ERROR_WARN_FLOOR}-mutant floor) — excluded from the ratio like a " \
-          "parse-invalid mutant, but this many suggests a harness defect rather than one-off noise. " \
-          "Investigate before trusting --threshold on this run."
-        )
+        MeasurementIntegrityWarning.emit(report, err: @err, floor: HARNESS_ERROR_WARN_FLOOR)
       end
 
       # The cross-file knowledge Tier 2 measures with — the #253 gate, and the ONLY place in this feature that
@@ -262,13 +260,11 @@ module Rigor
       # the two sets were assembled.
       #
       # The two cache phases each get their OWN {Cache::FileDigest.with_run} scope and the MEASUREMENT sits
-      # between them, deliberately: that scope installs a per-path digest memo, and {Protection::ClosureKillOracle}
-      # rewrites one process-private temp file per mutant and digests it through a buffer binding. A memo
-      # spanning the measurement would hand every mutant after the first the FIRST one's digest, the mutated
-      # file's discovery bundle would never be re-walked, and the run would report zero cross-file kills — a
-      # plausible-looking number rather than an error. The oracle's own comment states the same invariant from
-      # the other side. The cost of two scopes is one extra SHA-256 per cached file, against a measurement
-      # that is hundreds of analyses.
+      # between them, deliberately: that scope installs a per-path digest memo. {Protection::ClosureKillOracle}
+      # now writes each mutant to a fresh block-scoped path, so a memo spanning the measurement could no
+      # longer serve one mutant another's digest — but keeping the measurement outside any memo scope stays
+      # correct by construction rather than by the oracle's path discipline, and costs only one extra
+      # SHA-256 per cached file against a measurement that is hundreds of analyses.
       def measure_mutation_files(paths, cache:, scanner:, context:, configuration:, workers:)
         cached = with_digest_run(configuration) { paths.to_h { |path| [path, cache.fetch(path)] }.compact }
         pending = paths - cached.keys

data/lib/rigor/cli/coverage_scan.rb

@@ -4,7 +4,11 @@ require "prism"
 
 require_relative "../configuration"
 require_relative "../environment"
+require_relative "../inference/parameter_inference_collector"
 require_relative "../inference/precision_scanner"
+require_relative "../inference/scope_indexer"
+require_relative "../language_server/project_context"
+require_relative "../protection/discovery_seed"
 require_relative "../scope"
 require_relative "coverage_report"
 
@@ -20,19 +24,56 @@ module Rigor
       # @param files [Array<String>] explicit `.rb` file paths to scan.
       # @param configuration [Rigor::Configuration]
       # @return [Rigor::CLI::CoverageReport]
+      #
+      # Issue #513 — the environment is PLUGIN-AWARE (`LanguageServer::ProjectContext`, the same builder
+      # `--protection` uses), not the bare RBS environment this path carried until 2026-09-01. Without the
+      # plugin registry every plugin-typed receiver read `Dynamic` and the precision ratio understated the
+      # engine by ~1.2 points on a Rails target — the defect the protection path documented and fixed for
+      # itself on 2026-07-04, never applied here.
       def precision_report(files:, configuration:)
-        scope = Scope.empty(environment: project_environment(configuration))
+        scope = discovery_seeded_scope(
+          files: files,
+          configuration: configuration,
+          environment: LanguageServer::ProjectContext.new(configuration: configuration).environment,
+          parameter_inference: configuration.parameter_inference
+        )
         scanner = Inference::PrecisionScanner.new(scope: scope)
         accumulator = CoverageAccumulator.new
         files.each { |path| scan_into(path, scanner, accumulator, configuration) }
         accumulator.to_report(files, {})
       end
 
-      def project_environment(configuration)
-        Environment.for_project(
-          libraries: configuration.libraries,
-          signature_paths: configuration.signature_paths
-        )
+      # The cross-file facts a scan must see to report the types the engine actually infers, rather than the types a
+      # file-at-a-time walk can reach on its own.
+      #
+      # Issue #513 — the seed is the FULL check-walk bundle (`Protection::DiscoverySeed.discovery_tables`: classes,
+      # def nodes and sources for both kinds, superclasses, includes, visibilities, methods, and the Data / Struct
+      # member layouts), not just `discovered_classes`. The two-table seed #505 introduced closed the biggest part of
+      # the gap and left the rest: without the def-node / ancestry tables every cross-file call to a source-inferred
+      # project method measured as unresolved while `rigor check` resolves it — +0.27pp on redmine, +0.77pp on
+      # mastodon from the tables alone.
+      #
+      # `parameter_inference` is a parameter rather than a config read because the two callers want different answers:
+      # the precision lens must mirror the walk it describes (`check` leaves the table empty unless
+      # `parameter_inference:` is on, ADR-67 WD6a), while `--protection` seeds it unconditionally by ADR-67's own
+      # wiring — it only ever reclassifies sites it already counted.
+      #
+      # @return [Rigor::Scope]
+      def discovery_seeded_scope(files:, configuration:, environment:, parameter_inference:, workers: nil)
+        base = Scope.empty(environment: environment)
+        seed = Protection::DiscoverySeed.discovery_tables(files).dup
+
+        if parameter_inference
+          table = Inference::ParameterInferenceCollector.collect(
+            files: files, environment: environment, target_ruby: configuration.target_ruby,
+            workers: workers || configuration.parallel_workers
+          )
+          seed[:param_inferred_types] = table unless table.empty?
+        end
+
+        return base if seed.empty?
+
+        base.with_discovery(base.discovery.with(**seed))
       end
 
       # Parses one file and feeds the scan result (or a parse-error record) into `accumulator`. `scanner` /

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