rigortype 0.4.6 → 0.4.7

data/lib/rigor/cli/baseline_command.rb

@@ -2,6 +2,8 @@
 
 require "optparse"
 
+require "did_you_mean"
+
 require_relative "../analysis/baseline"
 require_relative "options"
 require_relative "../analysis/runner"
@@ -24,7 +26,9 @@ module Rigor
     #   rigor baseline prune
     class BaselineCommand < Command # rubocop:disable Metrics/ClassLength
       EXIT_USAGE = 64
+      USAGE = "Usage: rigor baseline <subcommand> [options]"
       DEFAULT_BASELINE_PATH = ".rigor-baseline.yml"
+      MAX_UNBASELINEABLE_FILES = 10
 
       SUBCOMMANDS = %w[generate regenerate dump drift prune].freeze
 
@@ -41,6 +45,8 @@ module Rigor
         when "prune" then run_prune
         else
           @err.puts("Unknown baseline subcommand: #{subcommand.inspect}")
+          nearest = ::DidYouMean::SpellChecker.new(dictionary: SUBCOMMANDS).correct(subcommand.to_s).first
+          @err.puts("Did you mean `rigor baseline #{nearest}`?") if nearest
           @err.puts(help)
           EXIT_USAGE
         end
@@ -49,10 +55,78 @@ module Rigor
         EXIT_USAGE
       end
 
+      # The parser of `subcommand`, built without parsing anything (the catalogue reads it, ADR-126 WD3).
+      def option_parser(subcommand, options = {})
+        case subcommand
+        when "generate", "regenerate" then generate_parser(subcommand, options)
+        when "dump" then dump_parser(options)
+        when "drift" then drift_parser(options)
+        when "prune" then prune_parser(options)
+        else raise ArgumentError, "unknown baseline subcommand: #{subcommand.inspect}"
+        end
+      end
+
       private
 
+      def generate_parser(subcommand, options)
+        OptionParser.new do |opts|
+          opts.banner = "Usage: rigor baseline #{subcommand} [options]"
+          Options.add_config(opts, options)
+          opts.on("--output=PATH", "Write baseline to PATH (default: #{DEFAULT_BASELINE_PATH})") do |v|
+            options[:output] = v
+          end
+          opts.on("--match-mode=MODE", %i[rule message],
+                  "Row form: rule (default) or message") do |v|
+            options[:match_mode] = v
+          end
+          # `regenerate` always overwrites — no `--force` to offer.
+          if subcommand == "generate"
+            opts.on("--force", "Overwrite an existing baseline file") { options[:force] = true }
+          end
+        end
+      end
+
+      def dump_parser(options)
+        OptionParser.new do |opts|
+          opts.banner = "Usage: rigor baseline dump [options]"
+          opts.on("--baseline=PATH", "Path to the baseline file (default: #{DEFAULT_BASELINE_PATH})") do |v|
+            options[:baseline] = v
+          end
+          Options.add_format(opts, options, "Output format: text (default) or json")
+          opts.on("--rule=RULE", "Filter rows by exact rule id") { |v| options[:rule] = v }
+          opts.on("--file=GLOB", "Filter rows by File.fnmatch? glob") { |v| options[:file] = v }
+        end
+      end
+
+      def drift_parser(options)
+        OptionParser.new do |opts|
+          opts.banner = "Usage: rigor baseline drift [options]"
+          Options.add_config(opts, options)
+          opts.on("--baseline=PATH", "Path to the baseline file (default: #{DEFAULT_BASELINE_PATH})") do |v|
+            options[:baseline] = v
+          end
+          opts.on("--only=STATUS", %i[within over cleared reducible],
+                  "Show only buckets with the given status (within|over|cleared|reducible)") do |v|
+            options[:only] = v
+          end
+        end
+      end
+
+      def prune_parser(options)
+        OptionParser.new do |opts|
+          opts.banner = "Usage: rigor baseline prune [options]"
+          Options.add_config(opts, options)
+          opts.on("--baseline=PATH", "Path to the baseline file (default: #{DEFAULT_BASELINE_PATH})") do |v|
+            options[:baseline] = v
+          end
+          opts.on("--dry-run", "Show what would be dropped without writing the file") { options[:dry_run] = true }
+        end
+      end
+
       def run_generate
         options = parse_generate_options
+        return positional_paths_error("generate") unless @argv.empty?
+
         path = options.fetch(:output)
 
         if File.exist?(path) && !options.fetch(:force)
@@ -69,9 +143,32 @@ module Rigor
       # so `rigor baseline regenerate` reads cleanly as "make the baseline match reality again".
       def run_regenerate
         options = parse_generate_options(subcommand: "regenerate")
+        return positional_paths_error("regenerate") unless @argv.empty?
+
         write_baseline(options, verb: "regenerated baseline")
       end
 
+      # Issues #2466 and #2577 — the baseline covers the configured `paths:`, never the positional arguments: a
+      # baseline built over a subset would silently drop the entries of every other file. `drift` and `prune`
+      # analyse the configured `paths:` and `dump` prints the whole file, so none of the five reads a path argument.
+      # Reject them, as `rigor effects update` does (`effects_snapshot_command.rb:54`), rather than honour them.
+      def positional_paths_error(subcommand)
+        @err.puts("rigor baseline #{subcommand}: unexpected argument(s) #{@argv.map(&:inspect).join(' ')}; " \
+                  "#{positional_paths_hint(subcommand)}")
+        EXIT_USAGE
+      end
+
+      def positional_paths_hint(subcommand)
+        case subcommand
+        when "dump"
+          "dump reads the baseline file, so pass none: use --file=GLOB to filter rows or --baseline=PATH to pick a file"
+        when "drift", "prune"
+          "#{subcommand} audits the configured `paths:`, so pass none"
+        else
+          "the baseline is generated from the configured `paths:`, so pass none"
+        end
+      end
+
       def write_baseline(options, verb:)
         path = options.fetch(:output)
         configuration = Configuration.load(options.fetch(:config))
@@ -81,11 +178,13 @@ module Rigor
                                                                     project_root: Dir.pwd)
         File.write(path, baseline.to_yaml)
 
+        covered = baseline.buckets.sum(&:count)
         @err.puts(
           "rigor: #{verb} #{path} " \
-          "(#{baseline.size} bucket(s) covering #{diagnostics.size} diagnostic(s); " \
+          "(#{baseline.size} bucket(s) covering #{covered} diagnostic(s); " \
           "match-mode: #{options.fetch(:match_mode)})"
         )
+        report_unbaselineable(Analysis::Baseline.unkeyable(diagnostics))
         if configuration.baseline_path.nil?
           # Name the config file that actually governs this project (`.rigor.dist.yml` when no local override
           # exists), so the hint points at the file the user must edit.
@@ -98,6 +197,38 @@ module Rigor
         0
       end
 
+      # Diagnostics the baseline cannot key never enter the file, so the next `rigor check` surfaces them. Say so,
+      # with how many, why and where; the exit status stays 0 (the file was written as asked).
+      def report_unbaselineable(unkeyable)
+        return if unkeyable.empty?
+
+        no_rule, no_path = unkeyable.partition { |d| d.qualified_rule.nil? }
+        files = unbaselineable_files(no_rule)
+        parts = []
+        unless no_rule.empty?
+          parts << "#{no_rule.size} diagnostic(s) have no rule (parse, path or internal errors) " \
+                   "in #{files.size} file(s)"
+        end
+        parts << "#{no_path.size} diagnostic(s) have no path" unless no_path.empty?
+        listing = files.empty? ? "" : ":"
+        @err.puts("rigor: #{parts.join('; ')} and cannot be baselined; " \
+                  "fix them, or remove or exclude the files#{listing}")
+        files.first(MAX_UNBASELINEABLE_FILES).each { |f| @err.puts("  #{f}") }
+        extra = files.size - MAX_UNBASELINEABLE_FILES
+        @err.puts("  ... and #{extra} more file(s)") if extra.positive?
+      end
+
+      def unbaselineable_files(diagnostics)
+        root = Pathname.new(Dir.pwd)
+        diagnostics.filter_map(&:path).map { |p| relative_to(root, p) }.uniq.sort
+      end
+
+      def relative_to(root, path)
+        Pathname.new(path).relative_path_from(root).to_s
+      rescue ArgumentError
+        path
+      end
+
       def parse_generate_options(subcommand: "generate")
         options = {
           config: nil,
@@ -105,22 +236,7 @@ module Rigor
           match_mode: :rule,
           force: false
         }
-        parser = OptionParser.new do |opts|
-          opts.banner = "Usage: rigor baseline #{subcommand} [options]"
-          Options.add_config(opts, options)
-          opts.on("--output=PATH", "Write baseline to PATH (default: #{DEFAULT_BASELINE_PATH})") do |v|
-            options[:output] = v
-          end
-          opts.on("--match-mode=MODE", %i[rule message],
-                  "Row form: rule (default) or message") do |v|
-            options[:match_mode] = v
-          end
-          # `regenerate` always overwrites — no `--force` to offer.
-          if subcommand == "generate"
-            opts.on("--force", "Overwrite an existing baseline file") { options[:force] = true }
-          end
-        end
-        parser.parse!(@argv)
+        generate_parser(subcommand, options).parse!(@argv)
         options
       end
 
@@ -139,8 +255,6 @@ module Rigor
         runner.run(configuration_for_generation.paths).diagnostics
       end
 
-      # The loaded configuration with only `baseline` disabled (#1777): any other key can change the
-      # diagnostic set, and the baseline must record the set `rigor check` will then report.
       def override_configuration_baseline_off(configuration)
         configuration.without_baseline
       end
@@ -149,31 +263,22 @@ module Rigor
 
       def run_dump
         options = parse_dump_options
+        return positional_paths_error("dump") unless @argv.empty?
+
         baseline = load_baseline_or_exit(options.fetch(:baseline))
         return EXIT_USAGE if baseline == :error
 
         rows = filter_dump_rows(baseline.buckets, options)
         case options.fetch(:format)
-        when :json then @out.puts(JSON.pretty_generate(dump_to_json(rows)))
+        when "json" then @out.puts(JSON.pretty_generate(dump_to_json(rows)))
         else dump_text(rows, options)
         end
         0
       end
 
       def parse_dump_options
-        options = { baseline: DEFAULT_BASELINE_PATH, format: :text, rule: nil, file: nil }
-        parser = OptionParser.new do |opts|
-          opts.banner = "Usage: rigor baseline dump [options]"
-          opts.on("--baseline=PATH", "Path to the baseline file (default: #{DEFAULT_BASELINE_PATH})") do |v|
-            options[:baseline] = v
-          end
-          opts.on("--format=FORMAT", %i[text json], "Output format: text (default) or json") do |v|
-            options[:format] = v
-          end
-          opts.on("--rule=RULE", "Filter rows by exact rule id") { |v| options[:rule] = v }
-          opts.on("--file=GLOB", "Filter rows by File.fnmatch? glob") { |v| options[:file] = v }
-        end
-        parser.parse!(@argv)
+        options = { baseline: DEFAULT_BASELINE_PATH, format: "text", rule: nil, file: nil }
+        dump_parser(options).parse!(@argv)
         options
       end
 
@@ -226,6 +331,8 @@ module Rigor
 
       def run_drift
         options = parse_drift_options
+        return positional_paths_error("drift") unless @argv.empty?
+
         baseline = load_baseline_or_exit(options.fetch(:baseline))
         return EXIT_USAGE if baseline == :error
 
@@ -254,18 +361,7 @@ module Rigor
           baseline: DEFAULT_BASELINE_PATH,
           only: nil
         }
-        parser = OptionParser.new do |opts|
-          opts.banner = "Usage: rigor baseline drift [options]"
-          Options.add_config(opts, options)
-          opts.on("--baseline=PATH", "Path to the baseline file (default: #{DEFAULT_BASELINE_PATH})") do |v|
-            options[:baseline] = v
-          end
-          opts.on("--only=STATUS", %i[within over cleared reducible],
-                  "Show only buckets with the given status (within|over|cleared|reducible)") do |v|
-            options[:only] = v
-          end
-        end
-        parser.parse!(@argv)
+        drift_parser(options).parse!(@argv)
         options
       end
 
@@ -300,6 +396,8 @@ module Rigor
 
       def run_prune
         options = parse_prune_options
+        return positional_paths_error("prune") unless @argv.empty?
+
         baseline = load_baseline_or_exit(options.fetch(:baseline))
         return EXIT_USAGE if baseline == :error
 
@@ -328,15 +426,7 @@ module Rigor
           baseline: DEFAULT_BASELINE_PATH,
           dry_run: false
         }
-        parser = OptionParser.new do |opts|
-          opts.banner = "Usage: rigor baseline prune [options]"
-          Options.add_config(opts, options)
-          opts.on("--baseline=PATH", "Path to the baseline file (default: #{DEFAULT_BASELINE_PATH})") do |v|
-            options[:baseline] = v
-          end
-          opts.on("--dry-run", "Show what would be dropped without writing the file") { options[:dry_run] = true }
-        end
-        parser.parse!(@argv)
+        prune_parser(options).parse!(@argv)
         options
       end
 
@@ -362,7 +452,7 @@ module Rigor
 
       def help
         <<~HELP
-          Usage: rigor baseline <subcommand> [options]
+          #{USAGE}
 
           Subcommands:
             generate    Write a fresh baseline file from a `rigor check` run.

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