rigortype 0.4.6 → 0.4.8

data/lib/rigor/cli/annotate_command.rb

@@ -16,6 +16,7 @@ require_relative "../inference/statement_evaluator"
 require_relative "prism_colorizer"
 require_relative "command"
 require_relative "../project_environment"
+require_relative "json_document"
 
 module Rigor
   class CLI
@@ -32,10 +33,12 @@ module Rigor
     class AnnotateCommand < Command
       USAGE = "Usage: rigor annotate [options] FILE"
 
-      # Trailing `#=> …` annotation comment. Matched and stripped before re-annotating so re-running is idempotent —
-      # this follows xmpfilter's convention of owning the `#=>` marker, and also absorbs the older `#=> dump_type:
-      # <type>` spelling (idempotency across re-runs). The leading `\s` requirement keeps a `#=>` inside a string
-      # literal (no preceding whitespace ambiguity aside) from matching mid-expression.
+      # Trailing `#=> …` annotation comment, matched and stripped before re-annotating so re-running is idempotent.
+      # Follows xmpfilter's convention of owning the `#=>` marker, and also absorbs the older `#=> dump_type: <type>`
+      # spelling.
+      # Strips the first `#=>` that is preceded by whitespace and followed by whitespace or the end of the line,
+      # together with that preceding whitespace, through the end of the line. A string literal is not special-cased,
+      # since the pattern does not parse Ruby; `a#=>b` and `x #=>y` are left alone.
       ANNOTATION_PATTERN = /\s+#=>(?:\s.*)?\z/
 
       # Arguments for highlighting through `bat`: the annotated text arrives on stdin, so the language must be explicit;
@@ -59,19 +62,13 @@ module Rigor
         execute(file, options)
       end
 
-      private
-
-      def parse_options
-        # Default: colour a tty, unless `NO_COLOR` opts out. An explicit `--color` / `--no-color` overrides both.
-        options = { config: nil, color: @out.tty? && !no_color_env?, bat: nil, format: :text }
-
-        parser = OptionParser.new do |opts|
+      # 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", %w[text json],
-                  "Output format: text (default) or json (a { line => type } map)") do |value|
-            options[:format] = value.to_sym
-          end
+          Options.add_format(opts, options, "Output format: text (default) or json (a { line => type } map)")
           opts.on("--[no-]color",
                   "Force or disable ANSI colour (default: auto-detect a tty; honours NO_COLOR)") do |value|
             options[:color] = value
@@ -81,7 +78,15 @@ module Rigor
             options[:bat] = value
           end
         end
-        parser.parse!(@argv)
+      end
+
+      private
+
+      def parse_options
+        # Default: colour a tty, unless `NO_COLOR` opts out. An explicit `--color` / `--no-color` overrides both.
+        options = { config: nil, color: @out.tty? && !no_color_env?, bat: nil, format: "text" }
+
+        option_parser(options).parse!(@argv)
 
         options
       end
@@ -118,7 +123,7 @@ module Rigor
         line_types = LineTypeCollector.new(scope_index).collect(parse_result.value)
 
         case options.fetch(:format)
-        when :json
+        when "json"
           emit_json(line_types)
         else
           @out.puts(render(annotate(source, line_types), color: options.fetch(:color), bat: options.fetch(:bat)))
@@ -132,7 +137,7 @@ module Rigor
       # object keys).
       def emit_json(line_types)
         annotations = line_types.keys.sort.to_h { |line| [line.to_s, line_types[line].describe(:short)] }
-        @out.puts(JSON.generate({ "annotations" => annotations }))
+        @out.puts(JSON.generate(JsonDocument.stamp({ "annotations" => annotations })))
       end
 
       # The plugin-aware environment for the annotated file, so a `#=> <type>` matches what `rigor check`
@@ -225,7 +230,7 @@ module Rigor
         @scope_index = scope_index
       end
 
-      # @return 1-indexed line => type.
+      # @return map of 1-indexed line number to type.
       def collect(program)
         by_line = {}
         each_statement(program) do |statement|

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))
@@ -79,13 +176,15 @@ module Rigor
 
         baseline = Analysis::Baseline.from_diagnostics(diagnostics, match_mode: options.fetch(:match_mode),
                                                                     project_root: Dir.pwd)
-        File.write(path, baseline.to_yaml)
+        return EXIT_USAGE unless write_baseline_file(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
 
@@ -317,7 +415,8 @@ module Rigor
         return 0 if options.fetch(:dry_run)
 
         pruned = baseline.without(cleared.map(&:bucket))
-        File.write(options.fetch(:baseline), pruned.to_yaml)
+        return EXIT_USAGE unless write_baseline_file(options.fetch(:baseline), pruned.to_yaml)
+
         @err.puts("rigor: pruned #{cleared.size} bucket(s); baseline now has #{pruned.size} entries.")
         0
       end
@@ -328,15 +427,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
 
@@ -349,6 +440,18 @@ module Rigor
 
       # ---- shared helpers ----------------------------------------
 
+      # #2576 — an output path that cannot be written is a usage error, the same rule `rigor init
+      # --path` follows (#2562): one `rigor baseline: cannot write PATH: REASON` line on stderr and
+      # exit 64, with no backtrace and no directory created on the way. The bare Errno backtrace read
+      # as an internal crash.
+      def write_baseline_file(path, content)
+        File.write(path, content)
+        true
+      rescue SystemCallError => e
+        @err.puts("rigor baseline: cannot write #{path}: #{e.message.sub(/ @ .*\z/m, '')}")
+        false
+      end
+
       def load_baseline_or_exit(path)
         unless File.exist?(path)
           @err.puts("rigor: baseline file not found: #{path}")
@@ -362,7 +465,7 @@ module Rigor
 
       def help
         <<~HELP
-          Usage: rigor baseline <subcommand> [options]
+          #{USAGE}
 
           Subcommands:
             generate    Write a fresh baseline file from a `rigor check` run.