rigortype 0.2.7 → 0.2.9

data/lib/rigor/cli/command.rb

@@ -4,16 +4,12 @@ module Rigor
   class CLI
     # Base class for the `rigor <subcommand>` command objects.
     #
-    # Every subcommand captured the same invariant wiring — the argument
-    # vector plus the output and error streams — in an identical
-    # `initialize(argv:, out:, err:)`, and defaulted the streams
-    # inconsistently (some to `$stdout` / `$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).
+    # Every subcommand captured the same invariant wiring — the argument vector plus the output and error streams — in
+    # an identical `initialize(argv:, out:, err:)`, and defaulted the streams inconsistently (some to `$stdout` /
+    # `$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, as they did before.
     class Command
       def initialize(argv:, out: $stdout, err: $stderr)
         @argv = argv
@@ -23,11 +19,9 @@ module Rigor
 
       private
 
-      # Expands `args` (a mix of files and directories) into a unique
-      # list of `.rb` paths, recursing into directories. Returns nil —
-      # after writing `<command_name>: not a file or directory: <arg>` to
-      # `@err` — on the first arg that is neither. Shared by the
-      # path-walking commands (`type-scan`, `coverage`).
+      # Expands `args` (a mix of files and directories) into a unique list of `.rb` paths, recursing into directories.
+      # Returns nil — after writing `<command_name>: not a file or directory: <arg>` to `@err` — on the first arg that
+      # is neither. Shared by the path-walking commands (`type-scan`, `coverage`).
       def collect_paths(args, command_name:)
         paths = []
         args.each do |arg|

data/lib/rigor/cli/coverage_command.rb

@@ -25,18 +25,19 @@ require_relative "mutation_protection_renderer"
 require_relative "fused_protection_report"
 require_relative "fused_protection_renderer"
 require_relative "coverage_mutation"
+require_relative "protection_fork_scan"
+require_relative "check_runner_factory"
 require_relative "command"
 
 module Rigor
   class CLI
     # Executes the `rigor coverage` command.
     #
-    # Walks every Prism node in one or more files, infers its type via
-    # `Rigor::Scope#type_of`, and classifies the result into precision tiers
-    # (constant / nominal / shaped / refined / bot / dynamic_specific /
+    # Walks every Prism node in one or more files, infers its type via `Rigor::Scope#type_of`, and classifies the result
+    # into precision tiers (constant / nominal / shaped / refined / bot / dynamic_specific /
     # dynamic_top / top).  Reports aggregate and per-file statistics so
-    # maintainers can track type-precision trends and SKILL pipelines can
-    # measure the impact of adding new constant-fold or shape-dispatch rules.
+    # maintainers can track type-precision trends and SKILL pipelines can measure the impact of adding new constant-fold
+    # or shape-dispatch rules.
     #
     # Exit codes:
     #   0  — scan complete, precision ratio ≥ threshold (or no threshold given)
@@ -47,8 +48,8 @@ module Rigor
 
       USAGE = "Usage: rigor coverage [options] PATH..."
 
-      # ADR-70 — the default test runner hook for `--with-tests`. The
-      # conventional Ruby test task; override with `--test-command`.
+      # ADR-70 — the default test runner hook for `--with-tests`. The conventional Ruby test task; override with
+      # `--test-command`.
       DEFAULT_TEST_COMMAND = %w[bundle exec rake].freeze
 
       # @return [Integer] CLI exit status.
@@ -59,23 +60,32 @@ module Rigor
         return include_dynamic_misuse_error if options[:include_dynamic] && !options[:with_tests]
         return run_mutation_protection(options) if options[:mutation]
 
-        paths = collect_paths(@argv, command_name: "coverage")
+        configuration = Configuration.load(options.fetch(:config))
+        paths = resolve_paths(configuration)
         return CLI::EXIT_USAGE if paths.nil?
         return usage_error if paths.empty?
 
-        return run_protection(paths, options) if options[:protection]
+        return run_protection(paths, options, configuration) if options[:protection]
 
-        report = scan_paths(paths, options)
+        report = scan_paths(paths, configuration)
         CoverageRenderer.new(out: @out).render(report, format: options.fetch(:format))
         determine_exit(report, options)
       end
 
       private
 
+      # Like `rigor check`, fall back to the configured `paths:` when no path is given on the command line
+      # (`coverage` previously required an explicit path — operational friction the two commands should not
+      # differ on). The mutation mode keeps its own git-changed-files default and returns before this.
+      def resolve_paths(configuration)
+        args = @argv.empty? ? configuration.paths : @argv
+        collect_paths(args, command_name: "coverage")
+      end
+
       def parse_options
         options = { format: "text", threshold: nil, config: nil, protection: false, mutation: false,
                     with_tests: false, test_command: DEFAULT_TEST_COMMAND, include_dynamic: false,
-                    limit: nil, seed: 1 }
+                    limit: nil, seed: 1, workers: nil }
         OptionParser.new { |opts| define_options(opts, options) }.parse!(@argv)
         options
       end
@@ -88,6 +98,10 @@ module Rigor
           options[:protection] = true
         end
         define_mutation_options(opts, options)
+        opts.on("--workers=N", Integer, "With --protection: fork N workers over the scanned files " \
+                                        "(default: config parallel.workers / RIGOR_RACTOR_WORKERS / 0)") do |v|
+          options[:workers] = v
+        end
         opts.on("--threshold=RATIO", Float, "Exit 1 when the precision (or, with --protection, " \
                                             "protection/effectiveness) ratio is below RATIO (0.0–1.0)") do |v|
           options[:threshold] = v
@@ -136,26 +150,41 @@ module Rigor
         CLI::EXIT_USAGE
       end
 
-      def run_protection(paths, options)
-        report = scan_protection(paths, options)
+      def run_protection(paths, options, configuration)
+        report = scan_protection(paths, options, configuration)
         ProtectionRenderer.new(out: @out).render(report, format: options.fetch(:format))
         determine_protection_exit(report, options)
       end
 
-      def scan_protection(paths, options)
-        configuration = Configuration.load(options.fetch(:config))
+      # Builds the plugin-aware environment and the seeded scope ONCE on the parent, then fork-pools the
+      # per-file scan across the resolved worker count (P3-10). The scan is pure-read and each file is
+      # independent, so this is a fork-map + ordered reduce: {ProtectionForkScan} returns `{path => result}`
+      # and the parent absorbs in `paths` order so the report is byte-identical to a sequential run.
+      def scan_protection(paths, options, configuration)
         environment = plugin_aware_environment(configuration)
-        scope = scope_with_inferred_params(paths, configuration, environment)
+        workers = CheckRunnerFactory.resolve_workers(options, configuration)
+        scope = scope_with_inferred_params(paths, configuration, environment, workers)
         scanner = Inference::ProtectionScanner.new(scope: scope)
         accumulator = ProtectionAccumulator.new
 
-        paths.each { |path| scan_one(path, scanner, accumulator, configuration) }
+        results = ProtectionForkScan.run(
+          paths: paths, scanner: scanner, environment: environment,
+          configuration: configuration, workers: workers
+        )
+        paths.each { |path| absorb_protection_result(accumulator, path, results.fetch(path)) }
         accumulator.to_report
       end
 
-      # Seed the protection scan's scope with the same cross-file facts
-      # `rigor check` resolves against, so a receiver reads the type it
-      # actually has rather than a stripped-scope `Dynamic`:
+      def absorb_protection_result(accumulator, path, result)
+        if result.is_a?(ProtectionForkScan::ParseError)
+          accumulator.record_parse_error_count(path, result.count)
+        else
+          accumulator.absorb(path, result)
+        end
+      end
+
+      # Seed the protection scan's scope with the same cross-file facts `rigor check` resolves against, so a receiver
+      # reads the type it actually has rather than a stripped-scope `Dynamic`:
       #
       # - `discovered_classes` — a project constant referring to a class
       #   defined in a *sibling* file (`Account`, `User`) types as
@@ -168,9 +197,9 @@ module Rigor
       #   parameter) counts as protected when its call sites resolve to
       #   concrete argument types.
       #
-      # Both span the scanned `paths` only (no whole-project pre-pass) —
-      # a site that gains neither is classified exactly as before.
-      def scope_with_inferred_params(paths, configuration, environment)
+      # Both span the scanned `paths` only (no whole-project pre-pass) — a site that gains neither is classified exactly
+      # as before.
+      def scope_with_inferred_params(paths, configuration, environment, workers)
         base = Scope.empty(environment: environment)
         seed = {}
 
@@ -178,7 +207,7 @@ module Rigor
         seed[:discovered_classes] = discovered unless discovered.empty?
 
         table = Inference::ParameterInferenceCollector.collect(
-          files: paths, environment: environment, target_ruby: configuration.target_ruby
+          files: paths, environment: environment, target_ruby: configuration.target_ruby, workers: workers
         )
         seed[:param_inferred_types] = table unless table.empty?
 
@@ -202,36 +231,21 @@ module Rigor
         CLI::EXIT_USAGE
       end
 
-      def scan_paths(paths, options)
-        CoverageScan.precision_report(files: paths, configuration: Configuration.load(options.fetch(:config)))
-      end
-
-      # Delegated to the shared scan module (see {CoverageScan}); the
-      # protection path below reuses both, and `rigor check --coverage`
-      # reuses `precision_report` over the same machinery.
-      def project_environment(configuration)
-        CoverageScan.project_environment(configuration)
+      def scan_paths(paths, configuration)
+        CoverageScan.precision_report(files: paths, configuration: configuration)
       end
 
-      # The protection scan must see the same receiver types `rigor check`
-      # does — including plugin-contributed `dynamic_return` types (a
-      # controller's `params` → `ActionController::Parameters`, a
-      # `Model.where` → `ActiveRecord::Relation[Model]`). The bare
-      # `project_environment` carries only the RBS environment (no plugin
-      # registry), so every plugin-typed receiver reads `Dynamic` and its
-      # dispatch site is miscounted as *unprotected* — a systematic
-      # undercount of what Rigor actually types on a plugin-using project.
-      # `ProjectContext` builds the plugin-aware environment (registry
-      # materialised + the per-run prepare pass that primes producers like
-      # the controller / model index) exactly as the LSP and the runner do.
+      # The protection scan must see the same receiver types `rigor check` does — including plugin-contributed
+      # `dynamic_return` types (a controller's `params` → `ActionController::Parameters`, a `Model.where` →
+      # `ActiveRecord::Relation[Model]`). The bare `CoverageScan.project_environment` carries only the RBS environment
+      # (no plugin registry), so every plugin-typed receiver reads `Dynamic` and its dispatch site is miscounted as
+      # *unprotected* — a systematic undercount of what Rigor actually types on a plugin-using project.
+      # `ProjectContext` builds the plugin-aware environment (registry materialised + the per-run prepare pass that
+      # primes producers like the controller / model index) exactly as the LSP and the runner do.
       def plugin_aware_environment(configuration)
         LanguageServer::ProjectContext.new(configuration: configuration).environment
       end
 
-      def scan_one(path, scanner, accumulator, configuration)
-        CoverageScan.scan_into(path, scanner, accumulator, configuration)
-      end
-
       def determine_exit(report, options)
         return 1 unless report.parse_errors.empty?
 

data/lib/rigor/cli/coverage_mutation.rb

@@ -5,19 +5,16 @@ require "prism"
 
 module Rigor
   class CLI
-    # ADR-63 Tier 2 + ADR-70 — the mutation-effectiveness and fused static∪dynamic
-    # protection paths, factored out of {CoverageCommand} to keep that command
-    # focused on dispatch. Mixed in, so each method runs in the command instance
-    # (using `@out` / `@err` / `@argv` / `collect_paths` / `determine_protection_exit`
-    # and the Protection + LanguageServer collaborators the command requires).
+    # ADR-63 Tier 2 + ADR-70 — the mutation-effectiveness and fused static∪dynamic protection paths, factored out of
+    # {CoverageCommand} to keep that command focused on dispatch. Mixed in, so each method runs in the command instance
+    # (using `@out` / `@err` / `@argv` / `collect_paths` / `determine_protection_exit` and the Protection +
+    # LanguageServer collaborators the command requires).
     module CoverageMutation
       private
 
-      # ADR-63 Tier 2 — the mutation-effectiveness deep dive. Builds the RBS
-      # environment + project pre-pass once (the warm loop), then re-analyses
-      # each target file's mutants against its clean baseline. Defaults to the
-      # git-changed `.rb` files; explicit paths override (and enable the
-      # whole-project opt-in, which is minutes).
+      # ADR-63 Tier 2 — the mutation-effectiveness deep dive. Builds the RBS environment + project pre-pass once (the
+      # warm loop), then re-analyses each target file's mutants against its clean baseline. Defaults to the git-changed
+      # `.rb` files; explicit paths override (and enable the whole-project opt-in, which is minutes).
       def run_mutation_protection(options)
         explicit = collect_paths(@argv, command_name: "coverage")
         return CLI::EXIT_USAGE if explicit.nil?
@@ -36,8 +33,8 @@ module Rigor
         determine_protection_exit(report, options)
       end
 
-      # A `--limit` sample makes the report an estimate (per-file ratios over a
-      # random N of the mutations). Say so on stderr — stdout stays clean for JSON.
+      # A `--limit` sample makes the report an estimate (per-file ratios over a random N of the mutations). Say so on
+      # stderr — stdout stays clean for JSON.
       def note_sampling(options)
         return unless options[:limit]
 
@@ -47,10 +44,9 @@ module Rigor
         )
       end
 
-      # ADR-70 — the fused static∪dynamic deep dive. The type pass is the ADR-63
-      # Tier 2 warm loop; each type-survivor is then run against the project's
-      # test suite (the runner hook). The suite MUST pass on clean code first, or
-      # "a mutant survived" is meaningless — abort with a clear message if not.
+      # ADR-70 — the fused static∪dynamic deep dive. The type pass is the ADR-63 Tier 2 warm loop; each type-survivor is
+      # then run against the project's test suite (the runner hook). The suite MUST pass on clean code first, or "a
+      # mutant survived" is meaningless — abort with a clear message if not.
       def run_fused_protection(paths, options)
         configuration = Configuration.load(options.fetch(:config))
         test_oracle = Protection::TestSuiteOracle.new(command: options.fetch(:test_command))
@@ -117,9 +113,8 @@ module Rigor
         accumulator.absorb(scanner.scan_file(path, source: source))
       end
 
-      # The git-changed (modified / added / untracked) `.rb` files that exist on
-      # disk — the default Tier 2 scope. Returns [] outside a git work tree or
-      # when git is unavailable; the caller then reports "nothing to measure".
+      # The git-changed (modified / added / untracked) `.rb` files that exist on disk — the default Tier 2 scope.
+      # Returns [] outside a git work tree or when git is unavailable; the caller then reports "nothing to measure".
       def changed_ruby_files
         output = git_status_porcelain
         return [] if output.nil?

data/lib/rigor/cli/coverage_report.rb

@@ -11,7 +11,6 @@ module Rigor
       :per_file,
       :total
     )
-      # Sum of all per-file totals.
       def grand_total
         total.total
       end
@@ -44,7 +43,6 @@ module Rigor
       def initialize
         @per_file = []
         @parse_errors = []
-        # Accumulated totals across all files.
         @total_total = 0
         @total_tier_counts = Inference::PrecisionScanner::TIERS.to_h { |t| [t, 0] }
       end

data/lib/rigor/cli/coverage_scan.rb

@@ -10,12 +10,10 @@ require_relative "coverage_report"
 
 module Rigor
   class CLI
-    # Shared type-precision scan behind both `rigor coverage` (the
-    # dedicated command) and `rigor check --coverage` (the in-run
-    # coverage block). Walks each file's AST, types every expression via
-    # `Scope#type_of`, and accumulates the precision-tier breakdown into a
-    # `CoverageReport`. Extracted so the two surfaces stay byte-identical
-    # on the same file set.
+    # Shared type-precision scan behind both `rigor coverage` (the dedicated command) and `rigor check --coverage` (the
+    # in-run coverage block). Walks each file's AST, types every expression via `Scope#type_of`, and accumulates the
+    # precision-tier breakdown into a `CoverageReport`. Extracted so the two surfaces stay byte-identical on the same
+    # file set.
     module CoverageScan
       module_function
 
@@ -37,11 +35,9 @@ module Rigor
         )
       end
 
-      # Parses one file and feeds the scan result (or a parse-error
-      # record) into `accumulator`. `scanner` / `accumulator` are a
-      # matched pair — a `PrecisionScanner` + `CoverageAccumulator`, or a
-      # `ProtectionScanner` + `ProtectionAccumulator` — both of which
-      # respond to `scan(node)` and `absorb(path, result)`.
+      # Parses one file and feeds the scan result (or a parse-error record) into `accumulator`. `scanner` /
+      # `accumulator` are a matched pair — a `PrecisionScanner` + `CoverageAccumulator`, or a `ProtectionScanner` +
+      # `ProtectionAccumulator` — both of which respond to `scan(node)` and `absorb(path, result)`.
       def scan_into(path, scanner, accumulator, configuration)
         source = File.read(path)
         parse_result = Prism.parse(source, filepath: path, version: configuration.target_ruby)

data/lib/rigor/cli/diagnostic_formats.rb

@@ -6,11 +6,9 @@ require_relative "../version"
 
 module Rigor
   class CLI
-    # CI-native diagnostic output formats (ADR-51). Each renders an
-    # `Analysis::Result` to a string a CI platform consumes to surface
-    # diagnostics inline in a pull / merge request, rather than only in the
-    # job log. They read the same `Diagnostic` fields as `--format json`
-    # (path / line / column / severity / qualified rule / message) and add
+    # CI-native diagnostic output formats (ADR-51). Each renders an `Analysis::Result` to a string a CI platform
+    # consumes to surface diagnostics inline in a pull / merge request, rather than only in the job log. They read the
+    # same `Diagnostic` fields as `--format json` (path / line / column / severity / qualified rule / message) and add
     # no new information — only a platform-native rendering of it.
     #
     #   sarif      — SARIF 2.1.0 (cross-platform; GitHub code-scanning, any
@@ -23,11 +21,9 @@ module Rigor
     #                reviewdog (`-f=checkstyle`) and Jenkins/etc. consume
     #   junit      — JUnit XML, the test-report format many CI systems render
     #
-    # Severity maps once per format from Rigor's `:error` / `:warning` /
-    # `:info`; the qualified rule (`<source_family>.<rule>` or the bare rule
-    # for the builtin family) is the stable identifier, nil only for the
-    # ruleless producers (parse / internal errors), which each format
-    # degrades gracefully.
+    # Severity maps once per format from Rigor's `:error` / `:warning` / `:info`; the qualified rule
+    # (`<source_family>.<rule>` or the bare rule for the builtin family) is the stable identifier, nil only for the
+    # ruleless producers (parse / internal errors), which each format degrades gracefully.
     module DiagnosticFormats
       FORMATS = %w[sarif github gitlab checkstyle junit teamcity].freeze
 
@@ -37,8 +33,9 @@ module Rigor
         FORMATS.include?(format)
       end
 
-      # Renders `result` in the named CI format. Callers gate on
-      # {.supports?} first; an unrecognised format returns nil.
+      # Renders `result` in the named CI format. Callers gate on {.supports?} first, so an unrecognised format means
+      # {FORMATS} and the dispatch below have drifted apart — raise rather than return nil, which every caller would
+      # then have to guard.
       def render(result, format)
         case format
         when "sarif" then Sarif.new(result).render
@@ -47,12 +44,12 @@ module Rigor
         when "checkstyle" then Checkstyle.new(result).render
         when "junit" then Junit.new(result).render
         when "teamcity" then Teamcity.new(result).render
+        else raise ArgumentError, "unsupported format: #{format}"
         end
       end
 
-      # XML attribute / text escaping shared by the Checkstyle and JUnit
-      # formatters. Covers the five predefined XML entities so a diagnostic
-      # message carrying `<`, `&`, or a quote can't break the document.
+      # XML attribute / text escaping shared by the Checkstyle and JUnit formatters. Covers the five predefined XML
+      # entities so a diagnostic message carrying `<`, `&`, or a quote can't break the document.
       module XmlEscaping
         ENTITIES = { "&" => "&amp;", "<" => "&lt;", ">" => "&gt;",
                      '"' => "&quot;", "'" => "&apos;" }.freeze
@@ -62,15 +59,14 @@ module Rigor
         end
       end
 
-      # SARIF 2.1.0 — the OASIS static-analysis interchange format. GitHub's
-      # `codeql-action/upload-sarif` ingests it to render findings on the PR
-      # diff and in the Security tab; it is the cross-platform anchor format.
+      # SARIF 2.1.0 — the OASIS static-analysis interchange format. GitHub's `codeql-action/upload-sarif` ingests it to
+      # render findings on the PR diff and in the Security tab; it is the cross-platform anchor format.
       class Sarif
         SCHEMA = "https://json.schemastore.org/sarif-2.1.0.json"
         INFORMATION_URI = "https://github.com/rigortype/rigor"
 
-        # SARIF defines exactly three result levels; Rigor's `:info` is a
-        # `note` (the SARIF spelling for advisory findings).
+        # SARIF defines exactly three result levels; Rigor's `:info` is a `note` (the SARIF spelling for advisory
+        # findings).
         LEVELS = { error: "error", warning: "warning", info: "note" }.freeze
 
         def initialize(result)
@@ -103,9 +99,8 @@ module Rigor
           }
         end
 
-        # The distinct rule ids seen in this run, declared so consumers can
-        # cross-reference each result's `ruleId`. Id-only is a valid minimal
-        # SARIF rule object; richer per-rule metadata is a later enrichment.
+        # The distinct rule ids seen in this run, declared so consumers can cross-reference each result's `ruleId`.
+        # Id-only is a valid minimal SARIF rule object; richer per-rule metadata is a later enrichment.
         def rules
           @result.diagnostics.filter_map(&:qualified_rule).uniq.map { |id| { "id" => id } }
         end
@@ -121,9 +116,8 @@ module Rigor
           entry
         end
 
-        # Rigor lines / columns are already 1-based, matching SARIF's
-        # 1-based `startLine` / `startColumn`. Paths are project-relative;
-        # SARIF URIs use forward slashes on every platform.
+        # Rigor lines / columns are already 1-based, matching SARIF's 1-based `startLine` / `startColumn`. Paths are
+        # project-relative; SARIF URIs use forward slashes on every platform.
         def location_for(diagnostic)
           {
             "physicalLocation" => {
@@ -134,9 +128,8 @@ module Rigor
         end
       end
 
-      # GitHub Actions workflow commands — `::<level> file=…,line=…,col=…,
-      # title=…::<message>` lines the runner parses out of stdout and turns
-      # into inline PR annotations, with no separate upload step.
+      # GitHub Actions workflow commands — `::<level> file=…,line=…,col=…, title=…::<message>` lines the runner parses
+      # out of stdout and turns into inline PR annotations, with no separate upload step.
       class GithubActions
         # GitHub's annotation levels; Rigor's `:info` is a `notice`.
         LEVELS = { error: "error", warning: "warning", info: "notice" }.freeze
@@ -160,26 +153,24 @@ module Rigor
           "::#{level} #{props.join(',')}::#{escape_data(diagnostic.message)}"
         end
 
-        # GitHub's documented workflow-command escaping: `%` and the CR / LF
-        # that would otherwise terminate the command line, for message data.
+        # GitHub's documented workflow-command escaping: `%` and the CR / LF that would otherwise terminate the command
+        # line, for message data.
         def escape_data(value)
           value.to_s.gsub("%", "%25").gsub("\r", "%0D").gsub("\n", "%0A")
         end
 
-        # Property values additionally escape the `,` (property separator)
-        # and `:` (command terminator) so a path or rule id can carry them.
+        # Property values additionally escape the `,` (property separator) and `:` (command terminator) so a path or
+        # rule id can carry them.
         def escape_property(value)
           escape_data(value).gsub(",", "%2C").gsub(":", "%3A")
         end
       end
 
-      # GitLab Code Quality report — the CodeClimate-subset JSON array GitLab
-      # reads from a `codequality` CI artifact to populate the merge-request
-      # Code Quality widget.
+      # GitLab Code Quality report — the CodeClimate-subset JSON array GitLab reads from a `codequality` CI artifact to
+      # populate the merge-request Code Quality widget.
       class GitlabCodeQuality
-        # GitLab's severity vocabulary (a CodeClimate subset). Rigor maps
-        # error → major, warning → minor, info → info; `critical` / `blocker`
-        # are left for a louder future tier.
+        # GitLab's severity vocabulary (a CodeClimate subset). Rigor maps error → major, warning → minor, info → info;
+        # `critical` / `blocker` are left for a louder future tier.
         SEVERITIES = { error: "major", warning: "minor", info: "info" }.freeze
 
         def initialize(result)
@@ -205,17 +196,16 @@ module Rigor
           }
         end
 
-        # The rule id is folded into the description (the widget shows it)
-        # because Code Quality has no dedicated rule field.
+        # The rule id is folded into the description (the widget shows it) because Code Quality has no dedicated rule
+        # field.
         def description(diagnostic)
           rule_id = diagnostic.qualified_rule
           rule_id ? "#{diagnostic.message} [#{rule_id}]" : diagnostic.message
         end
 
-        # GitLab dedups findings by fingerprint and tracks them across runs
-        # by it, so it must be stable for an unchanged finding and unique per
-        # finding. Hashing the locating tuple (path, rule, line, column,
-        # message) satisfies both — order-independent, no run-volatile input.
+        # GitLab dedups findings by fingerprint and tracks them across runs by it, so it must be stable for an unchanged
+        # finding and unique per finding. Hashing the locating tuple (path, rule, line, column, message) satisfies both
+        # — order-independent, no run-volatile input.
         def fingerprint(diagnostic)
           payload = [diagnostic.path, diagnostic.qualified_rule, diagnostic.line,
                      diagnostic.column, diagnostic.message].join("")
@@ -223,12 +213,10 @@ module Rigor
         end
       end
 
-      # Checkstyle XML — the lint-interchange format a wide range of tools
-      # read, most usefully reviewdog (`-f=checkstyle`), which then posts to
-      # any of its reporters (GitHub PR review, GitLab MR, Gerrit, …). Errors
-      # are grouped by file; the qualified rule rides in `source` (the rule
-      # code reviewdog surfaces). Checkstyle's native severities are
-      # `error` / `warning` / `info`, so Rigor's map through unchanged.
+      # Checkstyle XML — the lint-interchange format a wide range of tools read, most usefully reviewdog
+      # (`-f=checkstyle`), which then posts to any of its reporters (GitHub PR review, GitLab MR, Gerrit, …). Errors are
+      # grouped by file; the qualified rule rides in `source` (the rule code reviewdog surfaces). Checkstyle's native
+      # severities are `error` / `warning` / `info`, so Rigor's map through unchanged.
       class Checkstyle
         include XmlEscaping
 
@@ -258,12 +246,10 @@ module Rigor
         end
       end
 
-      # JUnit XML — the test-report format GitHub's test reporting, GitLab,
-      # Jenkins, and CircleCI render. Following the established linter
-      # convention (rubocop / eslint / PHPStan): every diagnostic is a
-      # `testcase` carrying a `failure` typed by its severity, so all of them
-      # are visible in the report. The exit code (errors only) remains the
-      # gate; this view is for surfacing, not gating.
+      # JUnit XML — the test-report format GitHub's test reporting, GitLab, Jenkins, and CircleCI render. Following the
+      # established linter convention (rubocop / eslint / PHPStan): every diagnostic is a `testcase` carrying a
+      # `failure` typed by its severity, so all of them are visible in the report. The exit code (errors only) remains
+      # the gate; this view is for surfacing, not gating.
       class Junit
         include XmlEscaping
 
@@ -299,11 +285,9 @@ module Rigor
         end
       end
 
-      # TeamCity inspection service messages — the `##teamcity[…]` lines a
-      # TeamCity build agent parses out of the build log into its Inspections
-      # view. The one stdout-native format (besides `github`) that
-      # CI-detection auto-emits. One `inspectionType` declares the category;
-      # each diagnostic is an `inspection` typed by severity.
+      # TeamCity inspection service messages — the `##teamcity[…]` lines a TeamCity build agent parses out of the build
+      # log into its Inspections view. The one stdout-native format (besides `github`) that CI-detection auto-emits. One
+      # `inspectionType` declares the category; each diagnostic is an `inspection` typed by severity.
       class Teamcity
         SEVERITIES = { error: "ERROR", warning: "WARNING", info: "INFO" }.freeze
 

data/lib/rigor/cli/diff_command.rb

@@ -7,10 +7,8 @@ require "optionparser"
 
 module Rigor
   class CLI
-    # Executes `rigor diff <baseline.json> [paths...]`. Compares
-    # the current `rigor check` diagnostics against a saved
-    # baseline JSON (the output of a previous `rigor check
-    # --format=json` run) and prints the delta:
+    # Executes `rigor diff <baseline.json> [paths...]`. Compares the current `rigor check` diagnostics against a saved
+    # baseline JSON (the output of a previous `rigor check --format=json` run) and prints the delta:
     #
     # - **new** — diagnostics in the current run that were not
     #   in the baseline (typically a regression introduced in
@@ -18,19 +16,13 @@ module Rigor
     # - **fixed** — diagnostics in the baseline that no longer
     #   appear in the current run (typically progress).
     #
-    # Identity for matching is the tuple
-    # `(path, line, column, rule, source_family, message)`.
-    # An edit that moves a diagnostic to a new line surfaces as
-    # one fixed + one new pair, which lines up with the user's
-    # mental model of "you changed the line, the analyzer's
-    # position changed too."
+    # Identity for matching is the tuple `(path, line, column, rule, source_family, message)`. An edit that moves a
+    # diagnostic to a new line surfaces as one fixed + one new pair, which lines up with the user's mental model of "you
+    # changed the line, the analyzer's position changed too."
     #
-    # CI usage: commit a `rigor.baseline.json` produced once
-    # with `rigor check --format=json > rigor.baseline.json`,
-    # then run `rigor diff rigor.baseline.json` in CI. Exit code
-    # is `1` when any new diagnostic appears, `0` otherwise —
-    # so adding new errors fails CI but legacy errors recorded
-    # in the baseline don't.
+    # CI usage: commit a `rigor.baseline.json` produced once with `rigor check --format=json > rigor.baseline.json`,
+    # then run `rigor diff rigor.baseline.json` in CI. Exit code is `1` when any new diagnostic appears, `0` otherwise —
+    # so adding new errors fails CI but legacy errors recorded in the baseline don't.
     class DiffCommand < Command
       USAGE = "Usage: rigor diff [options] <baseline.json> [paths...]"
 
@@ -77,10 +69,8 @@ module Rigor
         options
       end
 
-      # Runs `rigor check` against the remaining argv (or the
-      # configured paths) and returns the diagnostics array.
-      # Reuses the analyzer + configuration plumbing the
-      # check-command path uses.
+      # Runs `rigor check` against the remaining argv (or the configured paths) and returns the diagnostics array.
+      # Reuses the analyzer + configuration plumbing the check-command path uses.
       def run_current(options)
         require_relative "../analysis/runner"
         require_relative "../configuration"