rigortype 0.4.5 → 0.4.7

data/lib/rigor/cache/rbs_known_class_names.rb

@@ -7,7 +7,7 @@ module Rigor
   module Cache
     # Cache producer that materialises the set of every RBS-declared class / module / alias name (top-level
     # prefixed, e.g. `"::Math"`) currently loaded into the environment. Marshal-clean — the cache value is a
-    # `Set<String>`.
+    # Set of names.
     #
     # The set lets `RbsLoader#class_known?` answer point lookups in O(1) without re-parsing the name on each
     # call, and lets a warm process skip the env walk entirely (the env still has to be built to enumerate

data/lib/rigor/cache/store.rb

@@ -135,14 +135,6 @@ module Rigor
         end
       end
 
-      # Walks the on-disk cache rooted at `root` and reports a producer-level inventory. Used by
-      # `rigor check --cache-stats` to surface cache size and per-producer entry counts without depending on
-      # in-process counters (which only reflect the current run).
-      #
-      # @return `{ root:, schema_version:, total_entries:, total_bytes:, producers: [{ id:, entries:,
-      #   bytes: }, ...] }`. When the root does not exist or has no schema-version marker, `schema_version` is
-      #   nil and the producer list is empty.
-      #
       # The `schema_version.txt` marker content. Covers BOTH invalidation axes: the descriptor schema and the
       # on-disk byte layout ({FORMAT_VERSION}, ADR-54). A format bump leaves the old entries permanently
       # unreadable (header mismatch → miss) but, alone, would never reclaim their bytes — they can sit below
@@ -152,6 +144,13 @@ module Rigor
         "#{PAYLOAD_ABI_VERSION}.#{Descriptor::SCHEMA_VERSION}.#{FORMAT_VERSION}"
       end
 
+      # Walks the on-disk cache rooted at `root` and reports a producer-level inventory. Used by
+      # `rigor check --cache-stats` to surface cache size and per-producer entry counts without depending on
+      # in-process counters (which only reflect the current run).
+      #
+      # @return `{ root:, schema_version:, total_entries:, total_bytes:, producers: [{ id:, entries:,
+      #   bytes: }, ...] }`. When the root does not exist or has no schema-version marker, `schema_version` is
+      #   nil and the producer list is empty.
       def self.disk_inventory(root:)
         root_s = root.to_s
         marker = File.join(root_s, "schema_version.txt")
@@ -360,7 +359,8 @@ module Rigor
       # size-based LRU pass below stays gated on `max_bytes:` being configured: it walks all remaining
       # `.entry` files, sorts by mtime ascending (oldest = least recently used), and unlinks from the oldest
       # until the total is at or below the cap. Touch-on-disk-read ({read_entry}) is the cross-process LRU
-      # signal: every disk hit (not in-process-memo hit) updates the mtime so recently-read entries survive
+      # signal: a disk hit (not an in-process-memo hit) updates the mtime when `max_bytes:` is set, so
+      # recently-read entries survive
       # the eviction pass. Any FS error is swallowed — eviction must never break a run.
       def evict!
         return if @read_only
@@ -591,7 +591,8 @@ module Rigor
       # — one check per Store is enough; a benign double-check under a thread race would just repeat
       # idempotent work.
       #
-      # A writable store clears the cache root and rewrites the marker on a stale/missing marker, then reports
+      # A writable store clears the cache root and rewrites the marker on a stale marker (a missing or empty
+      # one is rewritten without clearing), then reports
       # available. A read-only store never touches the root — no mkdir, no marker write, no destructive clear
       # — so it reports available ONLY when the on-disk marker already matches current exactly; a stale or
       # missing marker (e.g. a Rigor upgrade with no writable run yet, as in LSP / editor mode) reports

data/lib/rigor/ci_detector.rb

@@ -20,7 +20,7 @@ module Rigor
   # non-CLI consumers exist: {Configuration#cache_validation_strict?} resolves the `auto` cache-validation default
   # through it (a fresh CI checkout regenerates every stat tuple, so ADR-87's stat tier cannot work there).
   # Detection is fully testable; callers pass `ENV`.
-  # `RIGOR_CI_DETECT=0` (or `false`/`no`) disables it globally — the seam the spec suite uses for determinism.
+  # `RIGOR_CI_DETECT=0` (or `false`/`no`/`off`) disables it globally — the seam the spec suite uses for determinism.
   module CiDetector
     Platform = Struct.new(:id, :name, :format, :tier, keyword_init: true) do
       def native_stdout? = tier == :native_stdout

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))
@@ -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.