rigortype 0.1.0 → 0.1.2

data/lib/rigor/cli/diff_command.rb

@@ -0,0 +1,169 @@
+# frozen_string_literal: true
+
+require "json"
+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:
+    #
+    # - **new** — diagnostics in the current run that were not
+    #   in the baseline (typically a regression introduced in
+    #   this PR).
+    # - **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."
+    #
+    # 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 # rubocop:disable Metrics/ClassLength
+      USAGE = "Usage: rigor diff [options] <baseline.json> [paths...]"
+
+      def initialize(argv:, out:, err:)
+        @argv = argv
+        @out = out
+        @err = err
+      end
+
+      # @return [Integer] CLI exit status.
+      def run
+        options = parse_options
+
+        baseline_path = @argv.shift
+        if baseline_path.nil?
+          @err.puts(USAGE)
+          return CLI::EXIT_USAGE
+        end
+
+        baseline = load_diagnostics(baseline_path)
+        current = options.fetch(:current_path) ? load_diagnostics(options.fetch(:current_path)) : run_current(options)
+        return CLI::EXIT_USAGE if baseline.nil? || current.nil?
+
+        diff = compute_diff(baseline, current)
+        write_diff(
+          diff, options.fetch(:format),
+          baseline_path: baseline_path,
+          baseline_count: baseline.size,
+          current_count: current.size
+        )
+        diff[:new].any? ? 1 : 0
+      end
+
+      private
+
+      def parse_options
+        options = { format: "text", current_path: nil, config: nil }
+        OptionParser.new do |opt|
+          opt.banner = USAGE
+          opt.on("--format=FORMAT", %w[text json], "Output format (text | json). Default: text.") do |fmt|
+            options[:format] = fmt
+          end
+          opt.on("--current=PATH", "Compare to the saved current JSON instead of running `rigor check`.") do |path|
+            options[:current_path] = path
+          end
+          opt.on("--config=PATH", "Path to .rigor.yml. Forwarded to the implicit `rigor check` run.") do |path|
+            options[:config] = path
+          end
+        end.parse!(@argv)
+        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.
+      def run_current(options)
+        require_relative "../analysis/runner"
+        require_relative "../configuration"
+
+        configuration = Configuration.load(options.fetch(:config))
+        paths = @argv.empty? ? configuration.paths : @argv
+        result = Analysis::Runner.new(configuration: configuration).run(paths)
+        result.diagnostics.map(&:to_h)
+      end
+
+      def load_diagnostics(path)
+        unless File.file?(path)
+          @err.puts("Baseline file not found: #{path}")
+          return nil
+        end
+
+        payload = JSON.parse(File.read(path))
+        payload.is_a?(Hash) ? Array(payload["diagnostics"]) : Array(payload)
+      rescue JSON::ParserError => e
+        @err.puts("Invalid JSON in #{path}: #{e.message}")
+        nil
+      end
+
+      KEY_FIELDS = %w[path line column rule source_family message].freeze
+      private_constant :KEY_FIELDS
+
+      def compute_diff(baseline, current)
+        baseline_keys = baseline.to_set { |d| identity_for(d) }
+        current_keys = current.to_set { |d| identity_for(d) }
+
+        new_diags = current.reject { |d| baseline_keys.include?(identity_for(d)) }
+        fixed = baseline.reject { |d| current_keys.include?(identity_for(d)) }
+        { new: new_diags, fixed: fixed }
+      end
+
+      def identity_for(diagnostic)
+        KEY_FIELDS.map { |k| diagnostic[k] }
+      end
+
+      def write_diff(diff, format, baseline_path:, baseline_count:, current_count:)
+        case format
+        when "json"
+          write_diff_json(diff, baseline_path, baseline_count, current_count)
+        else
+          write_diff_text(diff, baseline_path, baseline_count, current_count)
+        end
+      end
+
+      def write_diff_json(diff, baseline_path, baseline_count, current_count)
+        @out.puts(JSON.pretty_generate(
+                    "baseline" => baseline_path,
+                    "baseline_count" => baseline_count,
+                    "current_count" => current_count,
+                    "new" => diff[:new],
+                    "fixed" => diff[:fixed]
+                  ))
+      end
+
+      def write_diff_text(diff, baseline_path, baseline_count, current_count)
+        @out.puts("# diff against #{baseline_path} (#{baseline_count} baseline / #{current_count} current)")
+        diff[:new].each { |d| @out.puts("+ NEW   #{render_diagnostic(d)}") }
+        diff[:fixed].each { |d| @out.puts("- FIXED #{render_diagnostic(d)}") }
+        @out.puts("")
+        @out.puts("#{diff[:new].size} new, #{diff[:fixed].size} fixed")
+      end
+
+      def render_diagnostic(diagnostic)
+        rule = qualified_rule_for(diagnostic)
+        position = "#{diagnostic['path']}:#{diagnostic['line']}:#{diagnostic['column']}"
+        "#{position} [#{rule}] #{diagnostic['message']}"
+      end
+
+      def qualified_rule_for(diagnostic)
+        family = diagnostic["source_family"]
+        rule = diagnostic["rule"]
+        return rule if family.nil? || family == "" || family == "builtin"
+
+        "#{family}.#{rule}"
+      end
+    end
+  end
+end

data/lib/rigor/cli/explain_command.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+require "json"
+require "optionparser"
+
+require_relative "../analysis/rule_catalog"
+
+module Rigor
+  class CLI
+    # Executes `rigor explain <rule>`. Prints the catalog entry for
+    # one canonical rule id, a legacy alias, or a family wildcard
+    # (`call`, `flow`, `assert`, `dump`, `def`).
+    #
+    # Without arguments lists every rule's id and one-line summary.
+    #
+    # The command is read-only: no parser, no analyzer, no I/O
+    # beyond the rendered catalog. Useful when a user sees a
+    # diagnostic in the editor and wants to know what the rule
+    # means without leaving the terminal.
+    class ExplainCommand
+      USAGE = "Usage: rigor explain [options] [<rule>]"
+
+      def initialize(argv:, out:, err:)
+        @argv = argv
+        @out = out
+        @err = err
+      end
+
+      # @return [Integer] CLI exit status.
+      def run
+        options = parse_options
+
+        if @argv.empty?
+          render_index(options.fetch(:format))
+          return 0
+        end
+
+        token = @argv.shift
+        entries = Analysis::RuleCatalog.resolve(token)
+        if entries.empty?
+          @err.puts("Unknown rule: #{token}")
+          @err.puts("Run `rigor explain` with no arguments to list every rule.")
+          return CLI::EXIT_USAGE
+        end
+
+        render_entries(entries, options.fetch(:format))
+        0
+      end
+
+      private
+
+      def parse_options
+        options = { format: "text" }
+        OptionParser.new do |opt|
+          opt.banner = USAGE
+          opt.on("--format=FORMAT", %w[text json], "Output format (text | json). Default: text.") do |fmt|
+            options[:format] = fmt
+          end
+        end.parse!(@argv)
+        options
+      end
+
+      def render_index(format)
+        case format
+        when "json" then @out.puts(JSON.pretty_generate(Analysis::RuleCatalog.all.map(&:to_h)))
+        else render_index_text
+        end
+      end
+
+      def render_index_text
+        @out.puts("Available rules:")
+        @out.puts("")
+        Analysis::RuleCatalog.all.each do |entry|
+          @out.puts("  #{entry.id.ljust(33)} #{entry.summary}")
+        end
+        @out.puts("")
+        @out.puts("Run `rigor explain <rule>` for the full description.")
+        @out.puts("Family wildcards (`call`, `flow`, `assert`, `dump`, `def`) print every rule under that prefix.")
+      end
+
+      def render_entries(entries, format)
+        case format
+        when "json" then @out.puts(JSON.pretty_generate(entries.map(&:to_h)))
+        else
+          entries.each_with_index do |entry, index|
+            @out.puts("") if index.positive?
+            render_entry_text(entry)
+          end
+        end
+      end
+
+      def render_entry_text(entry)
+        @out.puts(entry.id)
+        @out.puts("=" * entry.id.length)
+        @out.puts("")
+        @out.puts(entry.summary)
+        @out.puts("")
+        render_aliases(entry)
+        render_severity(entry)
+        render_section("Fires when:", entry.fires_when)
+        render_section("Does not fire when:", entry.does_not_fire_when)
+        @out.puts("Suppression: #{entry.suppression}")
+        @out.puts("Since: rigor #{entry.since}")
+      end
+
+      def render_aliases(entry)
+        return if entry.aliases.empty?
+
+        @out.puts("Legacy aliases: #{entry.aliases.join(', ')}")
+        @out.puts("")
+      end
+
+      def render_severity(entry)
+        @out.puts("Authored severity: :#{entry.severity_authored}")
+        profile_table = entry.severity_by_profile.map { |profile, sev| "#{profile} → :#{sev}" }.join(", ")
+        @out.puts("Severity by profile: #{profile_table}")
+        @out.puts("")
+      end
+
+      def render_section(heading, items)
+        return if items.empty?
+
+        @out.puts(heading)
+        items.each { |item| @out.puts("  - #{item}") }
+        @out.puts("")
+      end
+    end
+  end
+end

data/lib/rigor/cli/type_of_command.rb

@@ -48,7 +48,7 @@ module Rigor
       private
 
       def parse_options
-        options = { format: "text", trace: false, config: Configuration::DEFAULT_PATH }
+        options = { format: "text", trace: false, config: nil }
 
         parser = OptionParser.new do |opts|
           opts.banner = USAGE
@@ -65,8 +65,9 @@ module Rigor
         file, line, column = target
         return 1 unless file_exists?(file)
 
+        configuration = Configuration.load(options.fetch(:config))
         source = File.read(file)
-        parse_result = Prism.parse(source, filepath: file)
+        parse_result = Prism.parse(source, filepath: file, version: configuration.target_ruby)
         return 1 if parse_errors?(parse_result, file)
 
         node = locate_node(source: source, root: parse_result.value, file: file, line: line, column: column)
@@ -74,7 +75,6 @@ module Rigor
         return 1 if node.nil?
 
         tracer = options[:trace] ? Inference::FallbackTracer.new : nil
-        configuration = Configuration.load(options.fetch(:config))
         base_scope = Scope.empty(environment: project_environment(file, configuration))
 
         # Build a per-node scope index so locals bound earlier in the

data/lib/rigor/cli/type_scan_command.rb

@@ -46,7 +46,7 @@ module Rigor
 
       def parse_options
         options = { format: "text", limit: 10, show_recognized: false, threshold: nil,
-                    config: Configuration::DEFAULT_PATH }
+                    config: nil }
 
         parser = OptionParser.new do |opts|
           opts.banner = USAGE
@@ -93,7 +93,7 @@ module Rigor
         scope = Scope.empty(environment: project_environment(configuration))
         scanner = Inference::CoverageScanner.new(scope: scope)
         accumulator = ScanAccumulator.new
-        paths.each { |path| scan_one(path, scanner, accumulator) }
+        paths.each { |path| scan_one(path, scanner, accumulator, configuration) }
         accumulator.to_report(paths, options)
       end
 
@@ -107,9 +107,9 @@ module Rigor
         )
       end
 
-      def scan_one(path, scanner, accumulator)
+      def scan_one(path, scanner, accumulator, configuration)
         source = File.read(path)
-        parse_result = Prism.parse(source, filepath: path)
+        parse_result = Prism.parse(source, filepath: path, version: configuration.target_ruby)
         if parse_result.errors.any?
           accumulator.record_parse_error(path, parse_result.errors)
           return

data/lib/rigor/cli.rb

@@ -22,7 +22,9 @@ module Rigor
       "check" => :run_check,
       "init" => :run_init,
       "type-of" => :run_type_of,
-      "type-scan" => :run_type_scan
+      "type-scan" => :run_type_scan,
+      "explain" => :run_explain,
+      "diff" => :run_diff
     }.freeze
 
     def self.start(argv = ARGV, out: $stdout, err: $stderr)
@@ -70,11 +72,11 @@ module Rigor
 
       options = parse_check_options
 
-      cache_root = ".rigor/cache"
+      configuration = Configuration.load(options.fetch(:config))
+      cache_root = configuration.cache_path
       handle_clear_cache(cache_root) if options.fetch(:clear_cache)
       cache_store = options.fetch(:no_cache) ? nil : Cache::Store.new(root: cache_root)
 
-      configuration = Configuration.load(options.fetch(:config))
       paths = @argv.empty? ? configuration.paths : @argv
       runner = Analysis::Runner.new(
         configuration: configuration,
@@ -90,7 +92,9 @@ module Rigor
 
     def parse_check_options
       options = {
-        config: Configuration::DEFAULT_PATH,
+        # `nil` triggers `Configuration.discover` (`.rigor.yml` then
+        # `.rigor.dist.yml`); an explicit `--config=PATH` overrides.
+        config: nil,
         format: "text",
         explain: false,
         cache_stats: false,
@@ -170,9 +174,14 @@ module Rigor
     end
 
     def run_init
+      # Default destination is `.rigor.dist.yml` — the
+      # project-default config that gets committed. Developers
+      # who want a personal override layer create `.rigor.yml`
+      # alongside it (auto-discovery prefers `.rigor.yml` when
+      # both are present; no implicit merge).
       options = {
         force: false,
-        path: Configuration::DEFAULT_PATH
+        path: ".rigor.dist.yml"
       }
 
       parser = OptionParser.new do |opts|
@@ -200,6 +209,7 @@ module Rigor
     # most likely to want to edit.
     def init_template
       <<~YAML
+        # yaml-language-server: $schema=https://github.com/zenwerk/rigor/raw/master/schemas/rigor-config.schema.json
         # Rigor configuration. See docs/CURRENT_WORK.md for the
         # full set of features the analyzer ships in this preview.
         #
@@ -257,6 +267,18 @@ module Rigor
       TypeScanCommand.new(argv: @argv, out: @out, err: @err).run
     end
 
+    def run_explain
+      require_relative "cli/explain_command"
+
+      ExplainCommand.new(argv: @argv, out: @out, err: @err).run
+    end
+
+    def run_diff
+      require_relative "cli/diff_command"
+
+      DiffCommand.new(argv: @argv, out: @out, err: @err).run
+    end
+
     def write_result(result, format)
       case format
       when "json"
@@ -294,6 +316,8 @@ module Rigor
           init       Create a starter .rigor.yml
           type-of    Print the inferred type at FILE:LINE:COL
           type-scan  Report Scope#type_of coverage across PATHs
+          explain    Print the description of one or all CheckRules
+          diff       Compare current diagnostics to a saved baseline JSON
           version    Print the Rigor version
           help       Print this help
       HELP

data/lib/rigor/configuration/severity_profile.rb

@@ -43,9 +43,14 @@ module Rigor
           "call.argument-type-mismatch" => :warning,
           "call.possible-nil-receiver" => :warning,
           "flow.always-raises" => :warning,
+          "flow.unreachable-branch" => :info,
+          "flow.dead-assignment" => :info,
+          "flow.always-truthy-condition" => :info,
           "assert.type-mismatch" => :error,
           "dump.type" => :info,
-          "def.return-type-mismatch" => :warning
+          "def.return-type-mismatch" => :warning,
+          "def.method-visibility-mismatch" => :warning,
+          "def.ivar-write-mismatch" => :warning
         }.freeze,
         balanced: {
           "call.undefined-method" => :error,
@@ -53,9 +58,14 @@ module Rigor
           "call.argument-type-mismatch" => :error,
           "call.possible-nil-receiver" => :error,
           "flow.always-raises" => :error,
+          "flow.unreachable-branch" => :warning,
+          "flow.dead-assignment" => :warning,
+          "flow.always-truthy-condition" => :warning,
           "assert.type-mismatch" => :error,
           "dump.type" => :info,
-          "def.return-type-mismatch" => :warning
+          "def.return-type-mismatch" => :warning,
+          "def.method-visibility-mismatch" => :error,
+          "def.ivar-write-mismatch" => :warning
         }.freeze,
         strict: {
           "call.undefined-method" => :error,
@@ -63,9 +73,14 @@ module Rigor
           "call.argument-type-mismatch" => :error,
           "call.possible-nil-receiver" => :error,
           "flow.always-raises" => :error,
+          "flow.unreachable-branch" => :error,
+          "flow.dead-assignment" => :error,
+          "flow.always-truthy-condition" => :error,
           "assert.type-mismatch" => :error,
           "dump.type" => :error,
-          "def.return-type-mismatch" => :error
+          "def.return-type-mismatch" => :error,
+          "def.method-visibility-mismatch" => :error,
+          "def.ivar-write-mismatch" => :error
         }.freeze
       }.freeze