rigortype 0.1.1 → 0.1.3

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.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)
@@ -207,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.
         #
@@ -264,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"
@@ -301,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/dependencies.rb

@@ -0,0 +1,235 @@
+# frozen_string_literal: true
+
+module Rigor
+  class Configuration
+    # Parsed `dependencies:` section of `.rigor.yml`. Per
+    # [ADR-10](../../../docs/adr/10-dependency-source-inference.md),
+    # the only nested key today is `source_inference:`, listing
+    # gems whose Ruby implementation Rigor MAY walk during
+    # inference instead of degrading to `Dynamic[top]` at the
+    # dependency boundary.
+    #
+    # Slice 1 lands the parser only — `Configuration#dependencies`
+    # is read, but no analyzer machinery consumes it yet. Slice 2
+    # wires `Analysis::DependencySourceInference` against this
+    # value object.
+    class Dependencies # rubocop:disable Metrics/ClassLength
+      # Walking modes per
+      # [ADR-10 § "Decision"](../../../docs/adr/10-dependency-source-inference.md#decision).
+      VALID_MODES = %i[disabled when_missing full].freeze
+
+      # Default `roots:` for an entry that does not supply one.
+      # The hard-excluded directories (`spec/` / `test/` / `bin/`
+      # / C extensions) are enforced by the walker, not the
+      # parser — see ADR-10 § "Hard exclusions".
+      DEFAULT_ROOTS = %w[lib].freeze
+
+      # Default per-gem catalog cap. ADR-10 slice 4 picks
+      # 5000 method definitions: it covers Rack (~1500),
+      # Faraday (~500), Sidekiq (~800) and other realistic
+      # opt-in targets, while still surfacing a diagnostic for
+      # ActiveSupport-class libraries (~10 000+ methods) where
+      # the user should ship RBS or de-list the gem instead.
+      DEFAULT_BUDGET_PER_GEM = 5000
+
+      # Range bounds per ADR-10 § "Budget interaction"
+      # ("range 0.25× – 4×"). Configured against the default,
+      # this lands at 1250 – 20 000.
+      MIN_BUDGET_PER_GEM = (DEFAULT_BUDGET_PER_GEM * 0.25).to_i
+      MAX_BUDGET_PER_GEM = (DEFAULT_BUDGET_PER_GEM * 4).to_i
+
+      # ADR-10 5b — budget-overrun strategy enum.
+      #
+      # - `:walker_cap` (default): the (α) semantics. The
+      #   walker stops harvesting at the cap; methods past the
+      #   cap fall through to the existing user-class fallback
+      #   path. Existing v0.1.3 behaviour.
+      # - `:dependency_silence`: the (β) semantics. Same
+      #   walker behaviour, but the dispatcher additionally
+      #   consults `Index#class_to_gem` after a catalog miss.
+      #   When the receiver's class belongs to a budget-
+      #   exceeded gem, the call resolves to `Dynamic[top]`
+      #   rather than falling through to user-class fallback.
+      #   This silences `call.undefined-method` for unrecorded
+      #   methods at the cost of weaker static checking on
+      #   that gem's surface.
+      VALID_BUDGET_OVERRUN_STRATEGIES = %i[walker_cap dependency_silence].freeze
+      DEFAULT_BUDGET_OVERRUN_STRATEGY = :walker_cap
+
+      # Frozen value object describing a single per-gem opt-in.
+      # `gem:` is the gem name (matched against the bundle at
+      # walk time); `mode:` is one of {VALID_MODES}; `roots:` is
+      # the list of subdirectories within the gem's installation
+      # directory to walk (defaults to `["lib"]`).
+      Entry = Data.define(:gem, :mode, :roots) do
+        def disabled? = mode == :disabled
+        def when_missing? = mode == :when_missing
+        def full? = mode == :full
+      end
+
+      attr_reader :source_inference, :budget_per_gem, :budget_overrun_strategy, :warnings
+
+      # Parse the YAML-shaped `dependencies:` value into a
+      # frozen {Dependencies}. Accepts `nil` / `{}` / a Hash with
+      # `source_inference:` and / or `budget_per_gem:` /
+      # `budget_overrun_strategy:` present.
+      def self.from_h(data)
+        return new([]) if data.nil?
+        raise ArgumentError, "dependencies: must be a Hash, got #{data.inspect}" unless data.is_a?(Hash)
+
+        raw_entries = Array(data["source_inference"]).map { |raw| coerce_entry(raw) }
+        entries, warnings = dedupe_entries(raw_entries)
+        budget = coerce_budget_per_gem(data.fetch("budget_per_gem", DEFAULT_BUDGET_PER_GEM))
+        strategy = coerce_budget_overrun_strategy(
+          data.fetch("budget_overrun_strategy", DEFAULT_BUDGET_OVERRUN_STRATEGY)
+        )
+        new(entries, budget, warnings, strategy)
+      end
+
+      def initialize(source_inference, budget_per_gem = DEFAULT_BUDGET_PER_GEM,
+                     warnings = [], budget_overrun_strategy = DEFAULT_BUDGET_OVERRUN_STRATEGY)
+        @source_inference = source_inference.freeze
+        @budget_per_gem = budget_per_gem
+        @warnings = warnings.freeze
+        @budget_overrun_strategy = budget_overrun_strategy
+        freeze
+      end
+
+      def to_h
+        {
+          "source_inference" => @source_inference.map do |entry|
+            {
+              "gem" => entry.gem,
+              "mode" => entry.mode.to_s,
+              "roots" => entry.roots
+            }
+          end,
+          "budget_per_gem" => @budget_per_gem,
+          "budget_overrun_strategy" => @budget_overrun_strategy.to_s
+        }
+      end
+
+      def empty? = @source_inference.empty?
+
+      class << self
+        # ADR-10 § "config-conflict diagnostic" — merges a
+        # potentially-duplicated entry list (the `includes:`
+        # chain produces concatenated arrays via
+        # `Configuration.deep_merge`'s special-case for
+        # `dependencies.source_inference`) into a single
+        # canonical entry per gem name. The merge rules:
+        #
+        # - Same gem, same all fields → idempotent collapse
+        #   (no warning).
+        # - Same gem, different `mode:` → keep the LAST entry
+        #   (matches existing right-wins semantics elsewhere)
+        #   AND emit a `:warning` so the user knows their
+        #   `includes:` chain is ambiguous.
+        # - Same gem, different `roots:` → union the roots
+        #   silently (no warning). The walker is happy to
+        #   visit the union.
+        #
+        # Returns `[entries, warnings]` so the caller can
+        # plumb the warning list through to the Runner for
+        # diagnostic emission.
+        def dedupe_entries(entries)
+          warnings = []
+          by_gem = {}
+          entries.each do |entry|
+            existing = by_gem[entry.gem]
+            by_gem[entry.gem] = if existing.nil?
+                                  entry
+                                else
+                                  merge_entry_pair(existing, entry, warnings)
+                                end
+          end
+          [by_gem.values, warnings]
+        end
+
+        def merge_entry_pair(existing, incoming, warnings)
+          if existing.mode != incoming.mode
+            warnings << "dependencies.source_inference[].gem #{incoming.gem.inspect} declared with " \
+                        "conflicting modes (#{existing.mode.inspect} vs #{incoming.mode.inspect}); " \
+                        "the later (#{incoming.mode.inspect}) wins."
+          end
+          merged_roots = (existing.roots + incoming.roots).uniq.freeze
+          Entry.new(gem: incoming.gem, mode: incoming.mode, roots: merged_roots)
+        end
+
+        private
+
+        def coerce_entry(raw)
+          unless raw.is_a?(Hash)
+            raise ArgumentError,
+                  "dependencies.source_inference[] entry must be a Hash, got #{raw.inspect}"
+          end
+
+          Entry.new(
+            gem: coerce_gem(raw["gem"]),
+            mode: coerce_mode(raw["mode"]),
+            roots: coerce_roots(raw)
+          )
+        end
+
+        def coerce_gem(value)
+          unless value.is_a?(String) && !value.empty?
+            raise ArgumentError,
+                  "dependencies.source_inference[].gem must be a non-empty String, got #{value.inspect}"
+          end
+
+          value.dup.freeze
+        end
+
+        def coerce_mode(value)
+          mode = (value || "when_missing").to_sym
+          return mode if VALID_MODES.include?(mode)
+
+          raise ArgumentError,
+                "dependencies.source_inference[].mode must be one of " \
+                "#{VALID_MODES.inspect}, got #{value.inspect}"
+        end
+
+        def coerce_roots(raw)
+          roots = Array(raw.fetch("roots", DEFAULT_ROOTS)).map(&:to_s).freeze
+          return roots unless roots.empty?
+
+          raise ArgumentError,
+                "dependencies.source_inference[].roots must not be empty when supplied " \
+                "(omit the key to fall back to the default #{DEFAULT_ROOTS.inspect})"
+        end
+
+        def coerce_budget_overrun_strategy(value)
+          symbol = value.to_sym
+          return symbol if VALID_BUDGET_OVERRUN_STRATEGIES.include?(symbol)
+
+          raise ArgumentError,
+                "dependencies.budget_overrun_strategy must be one of " \
+                "#{VALID_BUDGET_OVERRUN_STRATEGIES.inspect}, got #{value.inspect}"
+        end
+
+        # ADR-10 slice 4. Per-gem catalog cap is mandatory
+        # (the parser supplies the default before this is
+        # called, so `nil` only reaches here on an explicit
+        # `budget_per_gem: ~`). Range bounds match
+        # MIN_BUDGET_PER_GEM .. MAX_BUDGET_PER_GEM
+        # (i.e. 0.25× – 4× of the default).
+        def coerce_budget_per_gem(value)
+          unless value.is_a?(Integer)
+            raise ArgumentError,
+                  "dependencies.budget_per_gem must be an Integer, " \
+                  "got #{value.inspect}"
+          end
+
+          unless value.between?(MIN_BUDGET_PER_GEM, MAX_BUDGET_PER_GEM)
+            raise ArgumentError,
+                  "dependencies.budget_per_gem must be in the range " \
+                  "#{MIN_BUDGET_PER_GEM}..#{MAX_BUDGET_PER_GEM}, " \
+                  "got #{value.inspect}"
+          end
+
+          value
+        end
+      end
+    end
+  end
+end

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