rigortype 0.4.6 → 0.4.7

data/lib/rigor/cli/check_command.rb

@@ -17,8 +17,9 @@ require_relative "command"
 require_relative "options"
 require_relative "diagnostic_formats"
 require_relative "../ci_detector"
+require_relative "json_document"
 # ADR-87 WD4 — `coverage_scan` and `check_runner_factory` both pull the inference engine, so they are required
-# lazily (in `compute_coverage` / `build_check_runner`) rather than at load time: an ordinary check whose
+# lazily (in `invoke_check` / `compute_coverage`) rather than at load time: an ordinary check whose
 # result the run-cache probe serves must reach the hit verdict without `rigor/inference` in $LOADED_FEATURES.
 
 module Rigor
@@ -92,6 +93,97 @@ module Rigor
         exit_code
       end
 
+      # The parser this command parses with, built without parsing anything: the catalogue reads the
+      # flags and formats from it (ADR-126 WD3). `options` is only written by the switches' blocks.
+      def option_parser(options = {}) # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
+        OptionParser.new do |opts| # rubocop:disable Metrics/BlockLength
+          opts.banner = "Usage: rigor check [options] [paths]"
+          Options.add_config(opts, options)
+          Options.add_format(opts, options,
+                             "Output format: text, json, sarif, github, gitlab, checkstyle, junit, teamcity",
+                             formats: %w[text json] + DiagnosticFormats::FORMATS)
+          opts.on("--explain", "Surface fail-soft fallback events as :info diagnostics") { options[:explain] = true }
+          opts.on("--cache-stats", "Print on-disk cache inventory at end of run") { options[:cache_stats] = true }
+          opts.on("--coverage",
+                  "Add a type-precision coverage block (an extra precision pass over the analyzed files)") do
+            options[:coverage] = true
+          end
+          opts.on("--clear-cache", "Remove the .rigor/cache directory before running") { options[:clear_cache] = true }
+          opts.on("--no-cache",
+                  "Disable the persistent cache for this run (with --incremental: no snapshot is read or written)") do
+            options[:no_cache] = true
+          end
+          opts.on("--[no-]stats",
+                  "Print run summary (files, classes, memory, wall time) to stderr (default: on)") do |value|
+            options[:stats] = value
+          end
+          opts.on("--workers=N", Integer,
+                  "Dispatch per-file analysis across N Ractor workers (default: 0; sequential)") do |value|
+            options[:workers] = value
+          end
+          Options.add_editor_mode(opts, options)
+          opts.on("--baseline=PATH",
+                  "load baseline from PATH (overrides .rigor.yml `baseline:`)") do |value|
+            options[:baseline] = value
+          end
+          opts.on("--no-baseline",
+                  "ignore any configured baseline for this run") do
+            options[:baseline] = false
+          end
+          opts.on("--baseline-strict",
+                  "fail the run on any baseline drift (CI gate)") do
+            options[:baseline_strict] = true
+          end
+          opts.on("--fail-on=SEVERITY",
+                  "exit non-zero on a diagnostic at or above SEVERITY: error (default), warning, or info") do |value|
+            # Validated post-parse (`valid_fail_on_option?`, called from `run`) rather than here — see its
+            # comment for why an unrecognised value is not raised from inside this block.
+            options[:fail_on] = value.to_s.downcase.to_sym
+          end
+          opts.on("--treat-all-as-inline-rbs",
+                  "force-load rigor-rbs-inline with require_magic_comment: false") do
+            options[:treat_all_as_inline_rbs] = true
+          end
+          opts.on("--verify-incremental",
+                  "assert incremental analysis matches a full run, then exit") do
+            options[:verify_incremental] = true
+          end
+          opts.on("--verify-incremental-edits=N", Integer,
+                  "with --verify-incremental, also replay edits (empty, class/module skeleton, up to 2 " \
+                  "one-statement drops) on N files") do |value|
+            if value.negative?
+              raise OptionParser::InvalidArgument, "--verify-incremental-edits=#{value} (must be 0 or more)"
+            end
+
+            options[:verify_incremental] = true
+            options[:verify_incremental_edits] = value
+          end
+          opts.on("--incremental",
+                  "re-analyze only files changed since the last run (cross-process cache)") do
+            options[:incremental] = true
+          end
+          opts.on("--no-ci-detect",
+                  "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]",
+                  "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",
+                  "ignore any configured bleeding_edge: selection for this run") do
+            options[:bleeding_edge] = false
+          end
+          opts.on("--no-tolerated-effects",
+                  "check effect envelopes as if effects.tolerated: were empty") do
+            options[:no_tolerated_effects] = true
+          end
+        end
+      end
+
       private
 
       # True when `diagnostics` (already baseline-filtered and severity-resolved — the same list
@@ -219,10 +311,9 @@ module Rigor
         exit_code
       end
 
-      # ADR-46 — the two incremental-analysis check modes both fully handle the run and return an exit code (so `run`
-      # short-circuits); returns nil for an ordinary check.
-      # A nil return means "not a special mode" — `run` continues with the ordinary check. Editor mode option B
-      # also returns nil when it declines (no reusable snapshot), so the run falls back to single-file scope.
+      # ADR-46 — the two incremental-analysis check modes handle the run and return its exit code, so `run`
+      # short-circuits. Returns nil for an ordinary check, and for editor mode option B when it declines (no reusable
+      # snapshot), so the run falls back to single-file scope.
       def dispatch_special_check_mode(configuration, options, cache_root, buffer)
         if options.fetch(:verify_incremental)
           # The gate compares an incremental recheck against a full-run oracle, and a buffer makes the two
@@ -283,8 +374,10 @@ module Rigor
 
       # Issue #1967 — the partition check above re-analyses an unchanged tree, so every served row is still right and a
       # missing invalidation edge goes unseen. Here each of `--verify-incremental-edits` sampled files is edited through
-      # an editor buffer (never on disk) by each of {Analysis::EditReplay.edits} — emptied, then reduced to its
-      # `class` / `module` skeleton — and the warm recheck of the baseline ({IncrementalSession#replay_edit}) must equal
+      # an editor buffer (never on disk) by each of {Analysis::EditReplay.edits} — emptied, reduced to its
+      # `class` / `module` skeleton, and (#2277) with one body statement dropped, at most
+      # {Analysis::EditReplay::MAX_DROPS} times — and the warm recheck of the baseline
+      # ({IncrementalSession#replay_edit}) must equal
       # a full analysis of the edited tree: a dependent the recheck failed to re-analyse is served from the baseline and
       # differs. A run in which every replay declined compared nothing, so it fails rather than report OK.
       def verify_edit_replays(session, configuration, paths, options)
@@ -346,8 +439,8 @@ module Rigor
           return 1
         end
 
-        line = "rigor: --verify-incremental OK — #{replayed} edits replayed (files emptied and reduced to their " \
-               "class/module skeleton), every recheck matches full"
+        line = "rigor: --verify-incremental OK — #{replayed} edits replayed (files emptied, reduced to their " \
+               "class/module skeleton, and with a body statement dropped), every recheck matches full"
         line = "#{line}; #{declined} declined (the recheck would have been a full analysis)" if declined.positive?
         side_output(format).puts(line)
         0
@@ -386,9 +479,7 @@ module Rigor
         return run_editor_mode_option_b(session, snapshot, fingerprint, configuration, options) if buffer
 
         diagnostics, warm = session.run_incremental(snapshot: snapshot, fingerprint: fingerprint)
-        # The banner's file count comes from the session's analyzed set (cold analyses all; a warm recheck's
-        # `@analyzed` advances to the current file set), so a dedicated probe Runner + `Dir.glob` is no longer
-        # built just to size the banner (recon §3 — the analysis tree was expanded three times per recheck).
+        # The banner's file count comes from the session's analyzed set, so no probe Runner is built just to size it.
         # A warm banner reports the recheck's own sets (#1526), which only the session knows.
         report_incremental_run(warm, session.analyzed_files.size, recheck: session.last_recheck)
         emit_incremental_fact_surface_notes(session)
@@ -688,7 +779,7 @@ module Rigor
         )
       end
 
-      def parse_check_options # rubocop:disable Metrics/AbcSize,Metrics/MethodLength
+      def parse_check_options
         options = {
           config: nil,
           format: "text",
@@ -698,7 +789,7 @@ module Rigor
           no_cache: false,
           stats: true,
           # ADR-15 Phase 4c — when nil, falls back to `RIGOR_RACTOR_WORKERS` then `.rigor.yml` `parallel.workers:` then
-          # 0 (sequential). See `resolve_workers` for the precedence chain.
+          # 0 (sequential). See `CheckRunnerFactory.resolve_workers` for the precedence chain.
           workers: nil,
           tmp_file: nil,
           instead_of: nil,
@@ -747,93 +838,7 @@ module Rigor
           # one-line coverage summary.
           coverage: false
         }
-        parser = OptionParser.new do |opts| # rubocop:disable Metrics/BlockLength
-          opts.banner = "Usage: rigor check [options] [paths]"
-          Options.add_config(opts, options)
-          opts.on("--format=FORMAT",
-                  "Output format: text, json, sarif, github, gitlab, checkstyle, junit, teamcity") do |value|
-            options[:format] = value
-          end
-          opts.on("--explain", "Surface fail-soft fallback events as :info diagnostics") { options[:explain] = true }
-          opts.on("--cache-stats", "Print on-disk cache inventory at end of run") { options[:cache_stats] = true }
-          opts.on("--coverage",
-                  "Add a type-precision coverage block (an extra precision pass over the analyzed files)") do
-            options[:coverage] = true
-          end
-          opts.on("--clear-cache", "Remove the .rigor/cache directory before running") { options[:clear_cache] = true }
-          opts.on("--no-cache",
-                  "Disable the persistent cache for this run (with --incremental: no snapshot is read or written)") do
-            options[:no_cache] = true
-          end
-          opts.on("--[no-]stats",
-                  "Print run summary (files, classes, memory, wall time) to stderr (default: on)") do |value|
-            options[:stats] = value
-          end
-          opts.on("--workers=N", Integer,
-                  "Dispatch per-file analysis across N Ractor workers (default: 0; sequential)") do |value|
-            options[:workers] = value
-          end
-          Options.add_editor_mode(opts, options)
-          opts.on("--baseline=PATH",
-                  "load baseline from PATH (overrides .rigor.yml `baseline:`)") do |value|
-            options[:baseline] = value
-          end
-          opts.on("--no-baseline",
-                  "ignore any configured baseline for this run") do
-            options[:baseline] = false
-          end
-          opts.on("--baseline-strict",
-                  "fail the run on any baseline drift (CI gate)") do
-            options[:baseline_strict] = true
-          end
-          opts.on("--fail-on=SEVERITY",
-                  "exit non-zero on a diagnostic at or above SEVERITY: error (default), warning, or info") do |value|
-            # Validated post-parse (`valid_fail_on_option?`, called from `run`) rather than here — see its
-            # comment for why an unrecognised value is not raised from inside this block.
-            options[:fail_on] = value.to_s.downcase.to_sym
-          end
-          opts.on("--treat-all-as-inline-rbs",
-                  "force-load rigor-rbs-inline with require_magic_comment: false") do
-            options[:treat_all_as_inline_rbs] = true
-          end
-          opts.on("--verify-incremental",
-                  "assert incremental analysis matches a full run, then exit") do
-            options[:verify_incremental] = true
-          end
-          opts.on("--verify-incremental-edits=N", Integer,
-                  "with --verify-incremental, also replay 2 edits (empty, class/module skeleton) on N files") do |value|
-            if value.negative?
-              raise OptionParser::InvalidArgument, "--verify-incremental-edits=#{value} (must be 0 or more)"
-            end
-
-            options[:verify_incremental] = true
-            options[:verify_incremental_edits] = value
-          end
-          opts.on("--incremental",
-                  "re-analyze only files changed since the last run (cross-process cache)") do
-            options[:incremental] = true
-          end
-          opts.on("--no-ci-detect",
-                  "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]",
-                  "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",
-                  "ignore any configured bleeding_edge: selection for this run") do
-            options[:bleeding_edge] = false
-          end
-          opts.on("--no-tolerated-effects",
-                  "check effect envelopes as if effects.tolerated: were empty") do
-            options[:no_tolerated_effects] = true
-          end
-        end
-        parser.parse!(@argv)
+        option_parser(options).parse!(@argv)
         options
       end
 
@@ -943,6 +948,7 @@ module Rigor
         @err.puts("  recursion-unroll-fuel hits: #{counts[Inference::BudgetTrace::RECURSION_UNROLL_FUEL]}")
         @err.puts("  recursion-fixpoint-cap hits: #{counts[Inference::BudgetTrace::RECURSION_FIXPOINT_CAP]}")
         @err.puts("  block-writeback-cap hits:  #{counts[Inference::BudgetTrace::BLOCK_WRITEBACK_CAP]}")
+        @err.puts("  callee-chain-cap hits:     #{counts[Inference::BudgetTrace::CALLEE_CHAIN_CAP]}")
         write_budget_distributions
         write_memo_profile(counts)
       end
@@ -1153,7 +1159,7 @@ module Rigor
           payload["fail_on"] = fail_on.to_s
           payload["coverage"] = coverage_payload(coverage) if coverage
           payload["config_warnings"] = config_warnings.map(&:to_h) unless config_warnings.empty?
-          @out.puts(JSON.pretty_generate(payload))
+          @out.puts(JSON.pretty_generate(JsonDocument.stamp(payload)))
         when "text"
           write_text_result(result)
           write_coverage_summary(coverage) if coverage

data/lib/rigor/cli/check_runner_factory.rb

@@ -7,8 +7,8 @@ module Rigor
   class CLI
     # Shared factory for building an {Analysis::Runner} from CLI option hashes + a loaded {Configuration}.
     #
-    # Extracted from {CheckCommand} so that `rigor doctor` and future `describe --deep` can reuse the exact same
-    # runner-setup logic (cache, workers, buffer, explain) without diverging from the primary check path (ADR-77 WD3).
+    # Extracted from {CheckCommand} so that other commands (`rigor doctor`, `rigor skill describe --deep`) reuse the
+    # same runner setup (cache, workers, buffer, explain) instead of diverging from the `rigor check` path (ADR-77 WD3).
     module CheckRunnerFactory
       module_function
 

data/lib/rigor/cli/command.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "../rooted_glob"
+require_relative "../analysis/path_expansion"
 
 module Rigor
   class CLI
@@ -11,7 +12,7 @@ module Rigor
     # `$stderr`, most not at all). Centralising it here gives one consistent shape and lets a test instantiate a command
     # with just `argv:` (the streams default so a spec can pass a `StringIO` for one and ignore the other).
     #
-    # Subclasses read the `@argv` / `@out` / `@err` ivars directly, as they did before.
+    # Subclasses read the `@argv` / `@out` / `@err` ivars directly.
     class Command
       def initialize(argv:, out: $stdout, err: $stderr)
         @argv = argv
@@ -38,6 +39,19 @@ module Rigor
         end
         paths.uniq
       end
+
+      # #2206 — the `.rb` paths `args` names, with a path that is neither a directory nor a `.rb` file reported the way
+      # `rigor check` reports it ({Analysis::PathExpansion.diagnostics}): a warning beside files that will be read, an
+      # error when nothing will be. The diagnostics go to stderr. Returns nil when one is an error, so the caller exits.
+      def collect_paths_reporting(args)
+        bad = Analysis::PathExpansion.unusable(args)
+        files = Analysis::PathExpansion.ruby_files(args, [])
+        diagnostics = Analysis::PathExpansion.diagnostics(bad, any_files: files.any?)
+        diagnostics.each { |diagnostic| @err.puts(diagnostic.to_s) }
+        return nil if diagnostics.any?(&:error?)
+
+        files.uniq
+      end
     end
   end
 end

data/lib/rigor/cli/coverage_command.rb

@@ -68,7 +68,7 @@ module Rigor
         configuration = Configuration.load(options.fetch(:config))
         paths = resolve_paths(configuration)
         return CLI::EXIT_USAGE if paths.nil?
-        return usage_error if paths.empty?
+        return no_ruby_files_error(configuration) if paths.empty?
 
         return run_protection(paths, options, configuration) if options[:protection]
 
@@ -77,27 +77,31 @@ module Rigor
         determine_exit(report, options)
       end
 
+      # The parser this command parses with, built without parsing anything (the catalogue reads it, ADR-126 WD3).
+      def option_parser(options = {})
+        OptionParser.new { |opts| define_options(opts, options) }
+      end
+
       private
 
-      # Like `rigor check`, fall back to the configured `paths:` when no path is given on the command line
-      # (`coverage` previously required an explicit path — operational friction the two commands should not
-      # differ on). The mutation mode keeps its own git-changed-files default and returns before this.
+      # Like `rigor check`, fall back to the configured `paths:` when no path is given. The mutation mode keeps its own
+      # git-changed-files default and returns before this.
       def resolve_paths(configuration)
         args = @argv.empty? ? configuration.paths : @argv
-        collect_paths(args, command_name: "coverage")
+        collect_paths_reporting(args)
       end
 
       def parse_options
         options = { format: "text", threshold: nil, config: nil, protection: false, mutation: false,
                     with_tests: false, test_command: DEFAULT_TEST_COMMAND, include_dynamic: false,
                     limit: nil, seed: 1, workers: nil, no_cache: false }
-        OptionParser.new { |opts| define_options(opts, options) }.parse!(@argv)
+        option_parser(options).parse!(@argv)
         options
       end
 
       def define_options(opts, options)
         opts.banner = USAGE
-        opts.on("--format=FORMAT", "Output format: text or json") { |v| options[:format] = v }
+        Options.add_format(opts, options, "Output format: text or json")
         Options.add_config(opts, options)
         opts.on("--protection", "Report type-protection coverage (ADR-63 Tier 1) instead of type precision") do
           options[:protection] = true
@@ -203,7 +207,7 @@ module Rigor
       #   `singleton(Account)` instead of `Dynamic`. Without this, a
       #   single-file scan cannot see a class it does not itself declare,
       #   so every cross-file class-constant dispatch was miscounted as
-      #   unprotected (the model-constant undercount found 2026-07-04).
+      #   unprotected.
       # - `param_inferred_types` (ADR-67 WD3) — an inferred-parameter
       #   receiver (`node.loc` where `node` is a `def compile(node)`
       #   parameter) counts as protected when its call sites resolve to
@@ -253,6 +257,15 @@ module Rigor
         CLI::EXIT_USAGE
       end
 
+      # #2206 — paths were named, or configured, but none holds a Ruby file. Said as such, not as "no path given".
+      def no_ruby_files_error(configuration)
+        return usage_error if @argv.empty? && Array(configuration.paths).empty?
+
+        @err.puts("coverage: no Ruby files under the given paths")
+        @err.puts(USAGE)
+        CLI::EXIT_USAGE
+      end
+
       def scan_paths(paths, configuration)
         CoverageScan.precision_report(files: paths, configuration: configuration)
       end

data/lib/rigor/cli/coverage_mutation.rb

@@ -24,7 +24,6 @@ module Rigor
       DISCOVERY_SEEDED_MUTATION_SITES = "discovery-seeded-mutation-sites"
 
       # ADR-50 § WD2 — the bleeding-edge feature id gating the Tier-2 dependent-closure kill oracle (#254).
-      # Same reason as above for naming it here rather than inlining the string.
       DEPENDENT_CLOSURE_KILL_ORACLE = "dependent-closure-kill-oracle"
 
       # #264 — the "loud" threshold for a rescued-harness-failure count. Below it, a rescued mutant reads as
@@ -52,8 +51,7 @@ module Rigor
         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
-      # knows a feature id exists.
+      # The cross-file knowledge Tier 2 measures with, gated on the #253 feature.
       #
       # Returns nil (today's behaviour: an unseeded per-file view on both halves of the measurement) unless the
       # project has adopted `discovery-seeded-mutation-sites`. With it adopted, returns the table set
@@ -81,7 +79,7 @@ module Rigor
         seed.empty? ? nil : seed
       end
 
-      # The kill oracle Tier 2 measures with — the #254 gate, and the only place that feature id is read.
+      # The kill oracle Tier 2 measures with, gated on the #254 feature.
       #
       # Returns nil (today's behaviour: {Protection::DiagnosticOracle}, which re-analyses the mutated file
       # alone) unless the project has adopted `dependent-closure-kill-oracle`. With it adopted, returns the
@@ -139,7 +137,7 @@ module Rigor
       # warm loop), then re-analyses each target file's mutants against its clean baseline. Defaults to the git-changed
       # `.rb` files; explicit paths override (and enable the whole-project opt-in, which is minutes).
       def run_mutation_protection(options)
-        explicit = collect_paths(@argv, command_name: "coverage")
+        explicit = collect_paths_reporting(@argv)
         return CLI::EXIT_USAGE if explicit.nil?
 
         target_files = explicit.empty? ? changed_ruby_files : explicit
@@ -204,8 +202,8 @@ module Rigor
         determine_protection_exit(report, options)
       end
 
-      # An explicit `--workers=N` on the fused path cannot be honoured, so say so rather than repeat the bug
-      # this slice fixed (a flag accepted and silently dropped). Only the explicit flag warns — a project-wide
+      # An explicit `--workers=N` on the fused path cannot be honoured, so say so rather than drop it silently. Only the
+      # explicit flag warns — a project-wide
       # `parallel.workers:` or `RIGOR_RACTOR_WORKERS` default is not a request about *this* run.
       def warn_workers_ignored_under_tests(options)
         return unless options[:workers].to_i > 1

data/lib/rigor/cli/coverage_renderer.rb

@@ -2,6 +2,7 @@
 
 require "json"
 require_relative "renderable"
+require_relative "json_document"
 
 module Rigor
   class CLI
@@ -93,7 +94,7 @@ module Rigor
       end
 
       def render_json(report)
-        @out.puts(JSON.pretty_generate(json_payload(report)))
+        @out.puts(JSON.pretty_generate(JsonDocument.stamp(json_payload(report), mode: "precision")))
       end
 
       def json_payload(report)

data/lib/rigor/cli/coverage_scan.rb

@@ -23,11 +23,9 @@ module Rigor
 
       # @param files — explicit `.rb` file paths to scan.
       #
-      # 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.
+      # Issue #513 — the environment is plugin-aware (`LanguageServer::ProjectContext`, the same builder
+      # `--protection` uses). A bare RBS environment read every plugin-typed receiver as `Dynamic` and understated
+      # the precision ratio by ~1.2 points on a Rails target.
       def precision_report(files:, configuration:)
         scope = discovery_seeded_scope(
           files: files,

data/lib/rigor/cli/diff_command.rb

@@ -5,11 +5,12 @@ require_relative "options"
 
 require "json"
 require "optionparser"
+require_relative "json_document"
 
 module Rigor
   class CLI
-    # Executes `rigor diff <baseline.json> [paths...]`. Compares the current `rigor check` diagnostics against a saved
-    # baseline JSON (the output of a previous `rigor check --format=json` run) and prints the delta:
+    # Executes `rigor diff <rigor-check.json> [paths...]`. Compares the current `rigor check` diagnostics against a
+    # saved `rigor check --format=json` result and prints the delta:
     #
     # - **new** — diagnostics in the current run that were not
     #   in the baseline (typically a regression introduced in
@@ -21,11 +22,11 @@ module Rigor
     # diagnostic to a new line surfaces as one fixed + one new pair, which lines up with the user's mental model of "you
     # changed the line, the analyzer's position changed too."
     #
-    # CI usage: commit a `rigor.baseline.json` produced once with `rigor check --format=json > rigor.baseline.json`,
-    # then run `rigor diff rigor.baseline.json` in CI. Exit code is `1` when any new diagnostic appears, `0` otherwise —
+    # CI usage: commit a `rigor-check.json` produced once with `rigor check --format=json > rigor-check.json`, then
+    # run `rigor diff rigor-check.json` in CI. Exit code is `1` when any new diagnostic appears, `0` otherwise —
     # so adding new errors fails CI but legacy errors recorded in the baseline don't.
     class DiffCommand < Command
-      USAGE = "Usage: rigor diff [options] <baseline.json> [paths...]"
+      USAGE = "Usage: rigor diff [options] <rigor-check.json> [paths...]"
 
       # @return CLI exit status.
       def run
@@ -51,22 +52,26 @@ module Rigor
         diff[:new].any? ? 1 : 0
       end
 
-      private
-
-      def parse_options
-        options = { format: "text", current_path: nil, config: nil }
+      # The parser this command parses with, built without parsing anything: the catalogue reads the
+      # flags and formats from it (ADR-126 WD3). `options` is only written by the switches' blocks.
+      def option_parser(options = {})
         OptionParser.new do |opt|
           opt.banner = USAGE
-          opt.on("--format=FORMAT", %w[text json], "Output format (text | json). Default: text.") do |fmt|
-            options[:format] = fmt
-          end
+          Options.add_format(opt, options, "Output format (text | json). Default: text.")
           opt.on("--current=PATH", "Compare to the saved current JSON instead of running `rigor check`.") do |path|
             options[:current_path] = path
           end
           opt.on("--config=PATH", "Path to .rigor.yml. Forwarded to the implicit `rigor check` run.") do |path|
             options[:config] = Options.config_path(path)
           end
-        end.parse!(@argv)
+        end
+      end
+
+      private
+
+      def parse_options
+        options = { format: "text", current_path: nil, config: nil }
+        option_parser(options).parse!(@argv)
         options
       end
 
@@ -121,13 +126,13 @@ module Rigor
       end
 
       def write_diff_json(diff, baseline_path, baseline_count, current_count)
-        @out.puts(JSON.pretty_generate(
-                    "baseline" => baseline_path,
-                    "baseline_count" => baseline_count,
-                    "current_count" => current_count,
-                    "new" => diff[:new],
-                    "fixed" => diff[:fixed]
-                  ))
+        @out.puts(JSON.pretty_generate(JsonDocument.stamp({
+                                                            "baseline" => baseline_path,
+                                                            "baseline_count" => baseline_count,
+                                                            "current_count" => current_count,
+                                                            "new" => diff[:new],
+                                                            "fixed" => diff[:fixed]
+                                                          })))
       end
 
       def write_diff_text(diff, baseline_path, baseline_count, current_count)

data/lib/rigor/cli/docs_command.rb

@@ -203,8 +203,7 @@ module Rigor
           relative: relative,
           path: path,
           category: category,
-          # Always-unique addresses: the `docs/`-relative path and the prefixed basename. `handbook/03-narrowing` and
-          # `03-narrowing`.
+          # Always-unique addresses: the `docs/`-relative path and the prefixed basename.
           exact_aliases: [relative, base].uniq,
           # The prefix-stripped short name (`narrowing`); ambiguous when two categories carry the same chapter slug
           # (`plugins`).

data/lib/rigor/cli/doctor_command.rb

@@ -17,6 +17,7 @@ require_relative "../type/combinator"
 require_relative "check_invocation"
 require_relative "command"
 require_relative "options"
+require_relative "json_document"
 
 module Rigor
   class CLI
@@ -86,23 +87,22 @@ module Rigor
         CLI::EXIT_USAGE
       end
 
-      private
-
-      def parse_options
-        options = { config: nil, format: "text" }
+      # The parser this command parses with, built without parsing anything: the catalogue reads the
+      # flags and formats from it (ADR-126 WD3). `options` is only written by the switches' blocks.
+      def option_parser(options = {})
         OptionParser.new do |opts|
           opts.banner = USAGE
           Options.add_config(opts, options)
-          opts.on("--format=FORMAT", "Output format: text (default) or json") { |v| options[:format] = v }
-        end.parse!(@argv)
-        validate!(options)
-        options
+          Options.add_format(opts, options, "Output format: text (default) or json")
+        end
       end
 
-      def validate!(options)
-        return if %w[text json].include?(options.fetch(:format))
+      private
 
-        raise OptionParser::InvalidArgument, "unsupported format: #{options.fetch(:format)}"
+      def parse_options
+        options = { config: nil, format: "text" }
+        option_parser(options).parse!(@argv)
+        options
       end
 
       # ------------------------------------------------------------------
@@ -437,7 +437,7 @@ module Rigor
             }
           end
         }
-        @out.puts(JSON.pretty_generate(payload))
+        @out.puts(JSON.pretty_generate(JsonDocument.stamp(payload)))
       end
 
       def report_text(findings)