rigortype 0.4.5 → 0.4.7

data/lib/rigor/cli/catalogue.rb

@@ -0,0 +1,256 @@
+# frozen_string_literal: true
+
+require "optparse"
+
+require_relative "options"
+require_relative "../version"
+require_relative "json_document"
+
+module Rigor
+  class CLI
+    # The machine-readable description of the CLI surface (ADR-126 WD3): one entry per command, with the one-line
+    # summary, usage, subcommands, flags, accepted formats and the MCP tool that mirrors it.
+    #
+    # Nothing here is a second hand-written list of flags. The commands that parse with an `OptionParser` expose the
+    # parser they build (`#option_parser`, built without parsing anything) and the catalogue reads its switches; the
+    # commands that read `argv` by hand declare theirs in {DECLARED}. The only prose kept here is the one-line
+    # {SUMMARIES}, which `rigor help` prints, so the text help and `rigor help --format=json` cannot disagree about
+    # which commands exist. `spec/rigor/cli/catalogue_spec.rb` gates the names against `CLI::HANDLERS`.
+    module Catalogue
+      SCHEMA_VERSION = JsonDocument::SCHEMA_VERSION
+
+      # `help` and `version` are dispatched by `CLI#run` itself, outside `CLI::HANDLERS`.
+      BUILTINS = %w[help version].freeze
+
+      # The `rigor help` listing, in print order.
+      SUMMARIES = {
+        "check" => "Analyze Ruby source files",
+        "init" => "Create a starter .rigor.yml",
+        "annotate" => "Print FILE with each line's last-expression type",
+        "type-of" => "Print inferred types at FILE:LINE[:COL] positions",
+        "lens" => "Map a file's declarations with their types and provenance (experimental)",
+        "trace" => "Replay how the engine typed FILE as a terminal animation",
+        "type-scan" => "Report Scope#type_of coverage across PATHs",
+        "effects" => "Report each method's effect labels, and the committed effect snapshot " \
+                     "(opt-in; effects update/check/diff/explain)",
+        "explain" => "Print the description of one or all CheckRules",
+        "diff" => "Compare current diagnostics to a saved `rigor check --format=json` result",
+        "baseline" => "Manage the baseline file (baseline generate/regenerate/dump/drift/prune)",
+        "sig-gen" => "Emit RBS skeletons inferred from .rb sources",
+        "lsp" => "Run the Rigor Language Server (LSP) over stdio",
+        "mcp" => "Run the Rigor MCP server over stdio",
+        "triage" => "Summarise diagnostics: distribution, hotspots, hints",
+        "coverage" => "Report type-precision coverage (precise vs Dynamic ratio)",
+        "unused" => "Report unreferenced classes, modules and constants as removal candidates",
+        "plugins" => "Report activation status of every configured plugin",
+        "plugin" => "Browse bundled plugin source as worked examples (plugin <name>, plugin --list)",
+        "playground" => "Start the browser playground (requires rigor-playground gem)",
+        "describe" => "Recommend the next skill for this project (alias for `skill describe`)",
+        "skill" => "Recommend the next skill + list/print bundled Agent Skills (skill describe, skill <name>)",
+        "docs" => "Print the bundled docs offline (docs <name>, docs --list)",
+        "show-bleedingedge" => "Show the bleeding-edge overlay + what your config adopts",
+        "doctor" => "Classify setup problems vs clean run with routed next actions",
+        "upgrade" => "Migration command skeleton (queued)",
+        "version" => "Print the Rigor version",
+        "help" => "Print this help, or a command's help (help <command>, help --format=json)"
+      }.freeze
+
+      # The commands whose `argv` is read by hand, so there is no parser to read: their switches, subcommands and
+      # formats are stated here. `playground` is delegated to the optional `rigor-playground` gem and is listed without
+      # flags.
+      DECLARED = {
+        "describe" => {
+          usage: "Usage: rigor describe [--deep]",
+          flags: [
+            { name: "--deep", arg: nil, desc: "Run `rigor check` first and route the recommendation on its result" }
+          ]
+        },
+        "docs" => {
+          usage: "Usage: rigor docs [<name>] [--path <name>] [--list [<category>]]",
+          flags: [
+            { name: "--path", arg: "NAME", desc: "Print the absolute path of a doc" },
+            { name: "--list", arg: "CATEGORY", optional: true, desc: "List bundled docs (optionally one category)" }
+          ]
+        },
+        "playground" => { usage: "Usage: rigor playground [options]" },
+        "version" => { usage: "Usage: rigor version" }
+      }.freeze
+
+      # The command files that build an `OptionParser`; the command class is the file's name in camel case.
+      PARSER_FILES = %w[
+        check annotate type_of lens trace type_scan effects explain diff sig_gen lsp mcp baseline triage coverage unused
+        plugins show_bleedingedge doctor skill plugin
+      ].to_h { |file| [file.tr("_", "-"), "#{file}_command"] }.freeze
+
+      # The commands that have no parser of their own at the top, so their usage is their `USAGE` constant.
+      USAGE_FILES = { "baseline" => "baseline_command", "upgrade" => "upgrade_command" }.freeze
+
+      Ractor.make_shareable(SUMMARIES)
+      Ractor.make_shareable(USAGE_FILES)
+      Ractor.make_shareable(DECLARED)
+      Ractor.make_shareable(PARSER_FILES)
+
+      module_function
+
+      # Every command name the CLI dispatches, in `rigor help` order.
+      def names
+        SUMMARIES.keys - BUILTINS + BUILTINS
+      end
+
+      # The `rigor help` text, rendered from {SUMMARIES} so its list is the catalogue's.
+      def help_text
+        width = names.map(&:length).max + 2
+        lines = names.map { |name| "  #{name.ljust(width)}#{SUMMARIES.fetch(name)}" }
+        <<~HELP
+          Usage: rigor <command> [options]
+
+          Commands:
+          #{lines.join("\n")}
+
+          Run `rigor help <command>` (or `rigor <command> --help`) for a command's options.
+          Run `rigor describe` for the next step on this project, or `rigor help --format=json` for the full surface.
+        HELP
+      end
+
+      # All entries, as plain hashes ready for JSON.
+      def entries
+        names.map { |name| entry(name) }
+      end
+
+      # The document `rigor help --format=json` prints.
+      def document
+        { "schema_version" => SCHEMA_VERSION, "version" => Rigor::VERSION, "commands" => entries }
+      end
+
+      def entry(name)
+        declared = DECLARED.fetch(name, {})
+        parsed = parsed_entry(name)
+        {
+          "name" => name,
+          "summary" => SUMMARIES.fetch(name),
+          "usage" => declared[:usage] || parsed[:usage] || command_usage(name),
+          "subcommands" => parsed[:subcommands] || declared_subcommands(declared),
+          "flags" => parsed[:flags] || declared_flags(declared),
+          "formats" => parsed[:formats] || [],
+          "mcp_tool" => mcp_tool(name)
+        }
+      end
+
+      # The `OptionParser` view of a command: its own flags and formats at the top, and under `subcommands` the same
+      # shape for each subcommand's parser. A command with no parser of its own (`baseline`) has empty top-level
+      # `flags` and `formats`; none of them is a union over its subcommands.
+      def parsed_entry(name)
+        pairs = parser_pairs(name)
+        return {} if pairs.nil?
+
+        own = pairs.find { |sub, _| sub.nil? }&.last
+        subs = pairs.reject { |sub, _| sub.nil? }
+        top = own ? describe_parser(own) : { flags: [], formats: [] }
+        return top if subs.empty?
+
+        top.merge(subcommands: subs.map do |sub, parser|
+          { "name" => sub }.merge(stringify_keys(describe_parser(parser)))
+        end)
+      end
+
+      # The `[subcommand, parser]` pairs of a command (no name for its own parser), or nil when it has no parser.
+      def parser_pairs(name)
+        case name
+        when "init" then [[nil, CLI.init_option_parser]]
+        when "help" then [[nil, CLI.help_option_parser]]
+        else command_parser_pairs(name)
+        end
+      end
+
+      def command_parser_pairs(name)
+        file = PARSER_FILES[name]
+        return nil unless file
+
+        require_relative file
+        klass = CLI.const_get(file.split("_").map(&:capitalize).join)
+        case name
+        when "effects" then effects_parser_pairs(klass)
+        when "skill"
+          [[nil, klass.new(argv: []).option_parser],
+           ["describe", klass.describe_option_parser("Usage: rigor skill describe [--deep]")]]
+        when "baseline"
+          command = klass.new(argv: [])
+          klass::SUBCOMMANDS.map { |sub| [sub, command.option_parser(sub)] }
+        else [[nil, klass.new(argv: []).option_parser]]
+        end
+      end
+
+      def effects_parser_pairs(klass)
+        [[nil, klass.new(argv: []).option_parser]] +
+          EffectsSnapshotCommand::VERBS.map do |verb|
+            [verb, EffectsSnapshotCommand.new(argv: [], verb: verb).option_parser]
+          end
+      end
+
+      # The usage line of a command with no parser to take a banner from, read from the command's own `USAGE`.
+      def command_usage(name)
+        file = USAGE_FILES[name]
+        return nil unless file
+
+        require_relative file
+        CLI.const_get(file.split("_").map(&:capitalize).join)::USAGE
+      end
+
+      def declared_flags(declared)
+        (declared[:flags] || []).map do |flag|
+          { "name" => flag.fetch(:name), "arg" => flag.fetch(:arg), "optional" => flag.fetch(:optional, false),
+            "desc" => flag.fetch(:desc) }
+        end
+      end
+
+      def declared_subcommands(declared)
+        (declared[:subcommands] || []).map do |sub|
+          { "name" => sub.fetch(:name), "usage" => sub.fetch(:usage), "flags" => [], "formats" => [] }
+        end
+      end
+
+      # Reads usage, flags and formats from the switches of `parser`.
+      def describe_parser(parser)
+        flags = parser.top.list.flat_map { |switch| flags_of(switch) }
+        format_switch = parser.top.list.any? { |switch| switch.long.first == "--format" }
+        { usage: parser.banner.to_s.lines.first&.strip, flags: flags,
+          formats: format_switch ? Options.accepted_formats(parser) || [] : [] }
+      end
+
+      # A switch's literal flags: `--[no-]color` is the two flags `--color` and `--no-color`.
+      def flags_of(switch)
+        long = switch.long.first
+        return [] unless long
+
+        arg, optional = arg_of(switch.arg)
+        desc = switch.desc.join(" ")
+        flag_names(long).map { |flag| { "name" => flag, "arg" => arg, "optional" => optional, "desc" => desc } }
+      end
+
+      # `[arg, optional]`: `=[LIST]` is the argument `LIST`, optional.
+      def arg_of(raw)
+        arg = raw&.sub(/\A[= ]/, "")
+        optional = !arg.nil? && arg.start_with?("[") && arg.end_with?("]")
+        [optional ? arg[1..-2] : arg, optional]
+      end
+
+      def flag_names(long)
+        return [long] unless long.start_with?("--[no-]")
+
+        bare = long.delete_prefix("--[no-]")
+        ["--#{bare}", "--no-#{bare}"]
+      end
+
+      # `rigor_check` mirrors `check`, `rigor_sig_gen` mirrors `sig-gen`: a tool is named for its command.
+      def mcp_tool(name)
+        require_relative "../mcp/server"
+        tool = "rigor_#{name.tr('-', '_')}"
+        tool if MCP::Server::TOOLS.any? { |candidate| candidate.fetch(:name) == tool }
+      end
+
+      def stringify_keys(hash)
+        hash.transform_keys(&:to_s)
+      end
+    end
+  end
+end

data/lib/rigor/cli/check_command.rb

@@ -3,6 +3,7 @@
 require "fileutils"
 require "json"
 require "optionparser"
+require "tempfile"
 
 require_relative "../configuration"
 require_relative "../config_audit"
@@ -11,12 +12,14 @@ 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 "../analysis/edit_replay"
 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
@@ -90,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
@@ -217,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
@@ -272,8 +365,85 @@ module Rigor
         incremental = session.reanalyze_subset(subset).map(&:to_h)
         full = verify_full_diagnostics(configuration, paths, collect_stats: options.fetch(:stats)).map(&:to_h)
 
-        report_verify_incremental(incremental, full, subset_size: subset.size, total: analyzed.size,
-                                                     format: options.fetch(:format))
+        status = report_verify_incremental(incremental, full, subset_size: subset.size, total: analyzed.size,
+                                                              format: options.fetch(:format))
+        return status unless status.zero? && options.fetch(:verify_incremental_edits).positive?
+
+        verify_edit_replays(session, configuration, paths, options)
+      end
+
+      # 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, 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)
+        sample = edit_replay_sample(session.analyzed_files, options.fetch(:verify_incremental_edits))
+        replayed = 0
+        declined = 0
+        sample.each do |path|
+          Analysis::EditReplay.edits(File.read(path)).each do |edit|
+            incremental, full = replay_edit(session, configuration, paths, path, edit)
+            next declined += 1 if incremental.nil?
+
+            replayed += 1
+            next if incremental == full
+
+            return report_edit_replay_mismatch(path, edit, incremental, full)
+          end
+        end
+        report_edit_replays(replayed, declined, options.fetch(:format))
+      end
+
+      def report_edit_replay_mismatch(path, edit, incremental, full)
+        @err.puts("rigor: --verify-incremental FAILED — the recheck after #{edit.label} #{path} " \
+                  "differs from a full run.")
+        return report_verify_order_mismatch(incremental, full) if incremental.tally == full.tally
+
+        report_verify_set_mismatch(incremental, full, header: false)
+      end
+
+      # `count` files spread evenly over the analysed list, so a small count still reaches both ends of it.
+      def edit_replay_sample(analyzed, count)
+        return analyzed if count >= analyzed.size
+
+        Array.new(count) { |index| analyzed[index * analyzed.size / count] }
+      end
+
+      # The warm recheck's rows and a full run's, both with `path` replaced by `edit`; `[nil, nil]` when the recheck
+      # declined.
+      def replay_edit(session, configuration, paths, path, edit)
+        Tempfile.create(["rigor-verify-edit-", ".rb"]) do |file|
+          file.write(edit.source)
+          file.close
+          buffer = Analysis::BufferBinding.new(logical_path: path, physical_path: file.path)
+          recheck = session.replay_edit(buffer)
+          return [nil, nil] if recheck.nil?
+
+          # `analyze_only:` with the buffer selects editor mode option B, a whole-project run reading the buffer at
+          # its logical path; the buffer alone would analyse that one file.
+          runner = Analysis::Runner.new(configuration: configuration, cache_store: nil, collect_stats: false,
+                                        buffer: buffer, analyze_only: session.analyzed_files.to_set)
+          full = paths ? runner.run(paths) : runner.run
+          [recheck.diagnostics.map(&:to_h), full.diagnostics.map(&:to_h)]
+        end
+      end
+
+      def report_edit_replays(replayed, declined, format)
+        if replayed.zero? && declined.positive?
+          @err.puts("rigor: --verify-incremental FAILED — every edit replay (#{declined}) declined, " \
+                    "since the recheck would have been a full analysis, so no edit was compared.")
+          return 1
+        end
+
+        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
       end
 
       # ADR-46 — cross-process incremental analysis (`--incremental`). Derives the global fingerprint cheaply (no RBS
@@ -309,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)
@@ -490,10 +658,10 @@ module Rigor
         end
       end
 
-      def report_verify_set_mismatch(incremental, full)
+      def report_verify_set_mismatch(incremental, full, header: true)
         only_incremental = multiset_difference(incremental, full)
         only_full = multiset_difference(full, incremental)
-        @err.puts("rigor: --verify-incremental FAILED — incremental and full diagnostics differ.")
+        @err.puts("rigor: --verify-incremental FAILED — incremental and full diagnostics differ.") if header
         @err.puts("  incremental-only: #{only_incremental.size}, full-only: #{only_full.size}")
         (only_incremental + only_full).first(10).each do |hash|
           @err.puts("    #{diagnostic_location(hash)}")
@@ -611,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",
@@ -621,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,
@@ -643,6 +811,9 @@ module Rigor
           # the rest from the per-file cache, and asserts the merged diagnostics are byte-identical to a full
           # `--no-cache` run. Exits non-zero on any mismatch. Off by default.
           verify_incremental: false,
+          # Issue #1967 — the number of files `--verify-incremental` replays an edit on (each emptied through an editor
+          # buffer) after the partition check. 0 replays none.
+          verify_incremental_edits: 0,
           # ADR-46 — cross-process incremental analysis. With a disk snapshot of the prior run's per-file diagnostics +
           # dependency graph, re-analyzes only the changed closure and serves the rest from the snapshot. Off by
           # default.
@@ -667,84 +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("--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
 
@@ -854,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
@@ -1064,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