rigortype 0.4.6 → 0.4.8

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

@@ -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
 
@@ -861,7 +866,8 @@ module Rigor
         return Configuration.load(options.fetch(:config)) unless options.fetch(:treat_all_as_inline_rbs)
 
         path = options.fetch(:config) || Configuration.discover
-        data = path && File.exist?(path) ? Configuration.load_with_includes(path) : {}
+        config_file = path && File.exist?(path) ? path : nil
+        data = config_file ? Configuration.load_with_includes(config_file) : {}
         # ADR-103 WD15 — captured before `DEFAULTS.merge` below folds "no `effects:` key" and "`effects:
         # false`" into the same value; see `Configuration.load`'s identical capture.
         effects_key_present = data.key?("effects")
@@ -869,7 +875,8 @@ module Rigor
         data = data.dup
         data["plugins"] = inject_treat_all_as_inline_rbs(Array(data["plugins"]))
         Configuration.new(Configuration::DEFAULTS.merge(data), effects_key_present, target_ruby_key_present)
-                     .with_exclude_base(path && File.exist?(path) ? File.dirname(path) : nil)
+                     .with_exclude_base(config_file && File.dirname(config_file))
+                     .with_config_path(config_file)
       end
 
       # ADR-50 § WD2 — applies the `--bleeding-edge[=ids]` / `--no-bleeding-edge` CLI selection over the configured
@@ -943,6 +950,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 +1161,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