rigortype 0.1.1 → 0.1.2

data/lib/rigor/analysis/rule_catalog.rb

@@ -0,0 +1,343 @@
+# frozen_string_literal: true
+
+require_relative "check_rules"
+
+module Rigor
+  module Analysis
+    # Single-source-of-truth metadata table for every CheckRule
+    # the analyzer ships. Consumed by `rigor explain <rule>` so
+    # users can read the same information the docs site eventually
+    # publishes without leaving the terminal.
+    #
+    # Each entry carries:
+    #
+    # - `id` — canonical rule id (`call.undefined-method`).
+    # - `summary` — single-line headline (≤ 80 chars).
+    # - `fires_when` — bullet-shaped list of conditions that
+    #   trigger the rule, in the order a reader can scan
+    #   top-to-bottom.
+    # - `does_not_fire_when` — explicit list of cases the rule
+    #   intentionally skips. Useful for "why am I NOT seeing
+    #   this diagnostic?" questions.
+    # - `suppression` — short note on how to suppress (in-source
+    #   `# rigor:disable` and the v0.1.2 file-scope variant
+    #   `# rigor:disable-file`, plus `.rigor.yml` `disable:`,
+    #   apply to every rule, so the note covers any rule-specific
+    #   nuance — e.g. unreachable-branch lives on the dead-branch
+    #   line, not the predicate line).
+    # - `severity_authored` — Symbol the rule emits with.
+    # - `severity_by_profile` — Hash of `:lenient` / `:balanced`
+    #   / `:strict` to the configured severity per profile, taken
+    #   from `Configuration::SeverityProfile::PROFILES`.
+    # - `since` — first version the rule shipped in.
+    module RuleCatalog # rubocop:disable Metrics/ModuleLength
+      Entry = Data.define(:id, :summary, :fires_when, :does_not_fire_when,
+                          :suppression, :severity_authored, :severity_by_profile, :since) do
+        def aliases
+          CheckRules::LEGACY_RULE_ALIASES.select { |_legacy, canonical| canonical == id }.keys
+        end
+
+        # Hash-shaped form for `--format=json` consumers. Keys are
+        # Strings so the payload is JSON-stable without a transform
+        # pass.
+        def to_h
+          {
+            "id" => id,
+            "aliases" => aliases,
+            "summary" => summary,
+            "fires_when" => fires_when,
+            "does_not_fire_when" => does_not_fire_when,
+            "suppression" => suppression,
+            "severity_authored" => severity_authored.to_s,
+            "severity_by_profile" => severity_by_profile.transform_keys(&:to_s).transform_values(&:to_s),
+            "since" => since
+          }
+        end
+      end
+
+      ENTRIES = {
+        CheckRules::RULE_UNDEFINED_METHOD => Entry.new(
+          id: CheckRules::RULE_UNDEFINED_METHOD,
+          summary: "Method does not exist on the receiver's statically-known class.",
+          fires_when: [
+            "The call is `receiver.method(...)` with an explicit receiver.",
+            "The receiver type resolves to `Type::Nominal` / `Singleton` / `Constant` / `Tuple` / `HashShape`.",
+            "The receiver class is RBS-known (declared in the loaded environment).",
+            "The user has not declared the method via `def` or recognised `define_method`.",
+            "Neither the receiver class nor an ancestor's RBS sig declares the method."
+          ],
+          does_not_fire_when: [
+            "Implicit-self calls (no receiver) — too noisy without per-method RBS for every helper.",
+            "Receiver is `Dynamic[T]` / `Top` / `Union` — by definition the method set isn't enumerable.",
+            "Receiver class is in the loader but its RBS definition cannot be built (constant aliases)."
+          ],
+          suppression: "`# rigor:disable call.undefined-method` on the call line, " \
+                       "or `disable: [\"call.undefined-method\"]` in `.rigor.yml`.",
+          severity_authored: :error,
+          severity_by_profile: { lenient: :error, balanced: :error, strict: :error },
+          since: "0.0.1"
+        ),
+
+        CheckRules::RULE_WRONG_ARITY => Entry.new(
+          id: CheckRules::RULE_WRONG_ARITY,
+          summary: "Call's positional argument count is outside the declared overloads' envelope.",
+          fires_when: [
+            "Call is `receiver.method(args...)` with explicit receiver + plain positional args.",
+            "Receiver class is RBS-known and the method has a definition.",
+            "Actual positional count is below the min or above the max across all overloads."
+          ],
+          does_not_fire_when: [
+            "Call uses `*splat`, keyword arguments, block-pass, or forwarded arguments.",
+            "Method declares required keyword arguments (caller must pass kwargs the rule doesn't model).",
+            "Method has a `*rest` positional parameter (max arity is unbounded)."
+          ],
+          suppression: "`# rigor:disable call.wrong-arity`.",
+          severity_authored: :error,
+          severity_by_profile: { lenient: :error, balanced: :error, strict: :error },
+          since: "0.0.1"
+        ),
+
+        CheckRules::RULE_ARGUMENT_TYPE => Entry.new(
+          id: CheckRules::RULE_ARGUMENT_TYPE,
+          summary: "Call passes an argument whose type the parameter cannot accept.",
+          fires_when: [
+            "The parameter type rejects the argument under `accepts(arg, mode: :gradual)`.",
+            "Method has a single overload (multi-overload checking is deferred).",
+            "Both sides have a non-Dynamic concrete type."
+          ],
+          does_not_fire_when: [
+            "Either the parameter or the argument is `Dynamic[T]`.",
+            "Method has multiple overloads.",
+            "Method has `*rest_positionals`, required keywords, or trailing positionals."
+          ],
+          suppression: "`# rigor:disable call.argument-type-mismatch`.",
+          severity_authored: :error,
+          severity_by_profile: { lenient: :warning, balanced: :error, strict: :error },
+          since: "0.0.2"
+        ),
+
+        CheckRules::RULE_NIL_RECEIVER => Entry.new(
+          id: CheckRules::RULE_NIL_RECEIVER,
+          summary: "Receiver may be nil and the method is not defined on NilClass.",
+          fires_when: [
+            "Receiver type is `Type::Union` containing `Constant<nil>` (or `nil` from the RBS Optional).",
+            "The non-nil branch has the method, but `NilClass` does not.",
+            "Call is not safe-navigation (`x&.method`)."
+          ],
+          does_not_fire_when: [
+            "Method exists on every member of the union (including NilClass).",
+            "Receiver was narrowed via `return if x.nil?` / similar early-return guard.",
+            "Call uses safe-navigation (`x&.method`)."
+          ],
+          suppression: "`# rigor:disable call.possible-nil-receiver`.",
+          severity_authored: :error,
+          severity_by_profile: { lenient: :warning, balanced: :error, strict: :error },
+          since: "0.0.2"
+        ),
+
+        CheckRules::RULE_DUMP_TYPE => Entry.new(
+          id: CheckRules::RULE_DUMP_TYPE,
+          summary: "`dump_type(expr)` from Rigor::Testing — informational type print.",
+          fires_when: [
+            "Top-level / DSL-block call to `dump_type(expr)` after `include Rigor::Testing`."
+          ],
+          does_not_fire_when: [
+            "Outside a context that includes Rigor::Testing.",
+            "Argument is not a single expression."
+          ],
+          suppression: "Remove the `dump_type` call (it's a debug helper, not a real diagnostic).",
+          severity_authored: :info,
+          severity_by_profile: { lenient: :info, balanced: :info, strict: :error },
+          since: "0.0.1"
+        ),
+
+        CheckRules::RULE_ASSERT_TYPE => Entry.new(
+          id: CheckRules::RULE_ASSERT_TYPE,
+          summary: "`assert_type(\"<expected>\", expr)` from Rigor::Testing — type-equality check.",
+          fires_when: [
+            "Inferred type's display does not match the asserted string.",
+            "Useful in fixture self-assertions (every `spec/integration/fixtures/*.rb` uses it)."
+          ],
+          does_not_fire_when: [
+            "Inferred type matches the assertion exactly."
+          ],
+          suppression: "Update the assertion to the actual inferred type, or correct the source.",
+          severity_authored: :error,
+          severity_by_profile: { lenient: :error, balanced: :error, strict: :error },
+          since: "0.0.1"
+        ),
+
+        CheckRules::RULE_ALWAYS_RAISES => Entry.new(
+          id: CheckRules::RULE_ALWAYS_RAISES,
+          summary: "Call provably raises (today: Integer division-by-zero).",
+          fires_when: [
+            "Receiver is `Integer` / `IntegerRange` / `Constant<Integer>`.",
+            "Operator is `/` / `%` / `div` / `modulo` / `divmod`.",
+            "Argument is a `Constant<Integer>` whose value is exactly zero."
+          ],
+          does_not_fire_when: [
+            "Receiver is Float / Rational (those return Infinity / NaN, not an exception).",
+            "Argument is a Union containing zero (\"may raise\" not \"always raises\")."
+          ],
+          suppression: "`# rigor:disable flow.always-raises`.",
+          severity_authored: :error,
+          severity_by_profile: { lenient: :warning, balanced: :error, strict: :error },
+          since: "0.0.3"
+        ),
+
+        CheckRules::RULE_UNREACHABLE_BRANCH => Entry.new(
+          id: CheckRules::RULE_UNREACHABLE_BRANCH,
+          summary: "An if / unless / ternary's literal predicate makes one branch dead.",
+          fires_when: [
+            "Predicate is a syntactic literal: `true` / `false` / `nil` / Integer / Float / String / Symbol / Regexp.",
+            "The corresponding dead branch carries a non-empty body."
+          ],
+          does_not_fire_when: [
+            "Predicate is an inferred-constant expression (not a literal). The literal-only envelope avoids " \
+            "false positives from Rigor's incomplete loop / mutation / RBS-strictness modelling.",
+            "The dead branch is empty (no useful location to point at)."
+          ],
+          suppression: "`# rigor:disable unreachable-branch` on the dead-branch line (the diagnostic " \
+                       "points at the dead branch, not the predicate, so the suppression goes there).",
+          severity_authored: :warning,
+          severity_by_profile: { lenient: :info, balanced: :warning, strict: :error },
+          since: "0.1.2"
+        ),
+
+        CheckRules::RULE_ALWAYS_TRUTHY_CONDITION => Entry.new(
+          id: CheckRules::RULE_ALWAYS_TRUTHY_CONDITION,
+          summary: "An if / unless / ternary predicate's inferred type folds to a constant.",
+          fires_when: [
+            "Predicate's inferred type is `Type::Constant<true | false | nil | ...>`.",
+            "Predicate is NOT a syntactic literal (the literal-only `flow.unreachable-branch` rule covers those)."
+          ],
+          does_not_fire_when: [
+            "Predicate sits inside a `WhileNode` / `UntilNode` / `ForNode` / `BlockNode` ancestor — " \
+            "Rigor's mutation tracking through loop bodies is incomplete enough that an inferred " \
+            "`Constant<bool>` can be a false positive.",
+            "Predicate is a defensive `.nil?` / `.empty?` / `.zero?` / `.any?` / `.none?` / `.all?` / " \
+            "`.respond_to?` call — these typically fire when the user is being more cautious than the " \
+            "RBS strict-on-returns sig admits.",
+            "Predicate folds to a non-Constant type (Union / Nominal / Dynamic / etc.)."
+          ],
+          suppression: "`# rigor:disable always-truthy-condition` on the predicate line.",
+          severity_authored: :warning,
+          severity_by_profile: { lenient: :info, balanced: :warning, strict: :error },
+          since: "0.1.2"
+        ),
+
+        CheckRules::RULE_DEAD_ASSIGNMENT => Entry.new(
+          id: CheckRules::RULE_DEAD_ASSIGNMENT,
+          summary: "Local variable assigned in a method body but never read.",
+          fires_when: [
+            "Plain `LocalVariableWriteNode` (not `+=` / `||=` / multi-assign) inside a `DefNode` body.",
+            "The target name does not appear as a `LocalVariableReadNode` anywhere in the same body, " \
+            "including nested blocks / lambdas.",
+            "The write is not the last statement of the body (Ruby's implicit return)."
+          ],
+          does_not_fire_when: [
+            "Top-level / class-body assignments (their reachability spans the file's introspection / require surface).",
+            "The target name starts with `_` (Ruby convention for intentionally-unused).",
+            "The write is a destructure (`a, b = foo`) or operator-write (`x += 1` / `x ||= 1`).",
+            "The write is the last statement of the method body (assignments return their rvalue)."
+          ],
+          suppression: "`# rigor:disable dead-assignment` on the offending line, or rename the local to `_<name>`.",
+          severity_authored: :warning,
+          severity_by_profile: { lenient: :info, balanced: :warning, strict: :error },
+          since: "0.1.2"
+        ),
+
+        CheckRules::RULE_RETURN_TYPE => Entry.new(
+          id: CheckRules::RULE_RETURN_TYPE,
+          summary: "Method body's last-expression type is incompatible with the declared return type.",
+          fires_when: [
+            "Method has a `def` body the engine can re-type.",
+            "Method's RBS sig declares a non-`untyped` return type.",
+            "Body's inferred return type does not flow into the declared type under gradual acceptance.",
+            "When the RBS sig carries `%a{rigor:v1:return: <refinement>}` (v0.1.2), the refinement " \
+            "carrier — `non-empty-string`, `positive-int`, etc. — replaces the bare RBS class for the " \
+            "comparison, so a body the bare class would accept may still fail the refinement."
+          ],
+          does_not_fire_when: [
+            "Method's declared return is `untyped` / `void`.",
+            "Body's last expression is `Dynamic[T]` (the engine cannot rule out the declared type)."
+          ],
+          suppression: "`# rigor:disable def.return-type-mismatch`.",
+          severity_authored: :warning,
+          severity_by_profile: { lenient: :warning, balanced: :warning, strict: :error },
+          since: "0.1.0"
+        ),
+
+        CheckRules::RULE_VISIBILITY_MISMATCH => Entry.new(
+          id: CheckRules::RULE_VISIBILITY_MISMATCH,
+          summary: "Explicit-receiver call to a method declared `private` in source.",
+          fires_when: [
+            "Call is `receiver.method(...)` with explicit non-self receiver.",
+            "Receiver type resolves to `Type::Nominal[X]`.",
+            "X is a user-defined class whose source carries the method under `private`."
+          ],
+          does_not_fire_when: [
+            "Implicit-self call (no receiver) — always allowed for private.",
+            "Receiver is `self` (Ruby 2.7+ permits `self.private_method`).",
+            "Receiver class is RBS-known but not user-source-defined (RBS-side visibility is deferred).",
+            "Method is `:protected` (subclass tracking is deferred)."
+          ],
+          suppression: "`# rigor:disable method-visibility-mismatch`.",
+          severity_authored: :error,
+          severity_by_profile: { lenient: :warning, balanced: :error, strict: :error },
+          since: "0.1.2"
+        ),
+
+        CheckRules::RULE_IVAR_WRITE_MISMATCH => Entry.new(
+          id: CheckRules::RULE_IVAR_WRITE_MISMATCH,
+          summary: "Same instance variable assigned a different concrete class within one class.",
+          fires_when: [
+            "Two or more `@var = ...` writes occur in instance methods of the same class.",
+            "First write's rvalue resolves to a concrete class (Nominal / Singleton / Constant / Tuple → " \
+            "\"Array\" / HashShape → \"Hash\").",
+            "A later write's rvalue resolves to a different concrete class."
+          ],
+          does_not_fire_when: [
+            "Later write is `nil` — the `@cache = nil` clear-idiom is allowlisted.",
+            "Either side is Union / Dynamic / IntegerRange / a shape-varied carrier.",
+            "Writes live in different classes that happen to share an ivar name.",
+            "Writes are in `def self.foo` (singleton) bodies — those track separately."
+          ],
+          suppression: "`# rigor:disable ivar-write-mismatch` on the offending write.",
+          severity_authored: :error,
+          severity_by_profile: { lenient: :warning, balanced: :warning, strict: :error },
+          since: "0.1.2"
+        )
+      }.freeze
+
+      module_function
+
+      # Looks up a rule by canonical id, legacy alias, or family
+      # wildcard. Returns an Array<Entry>:
+      #
+      # - canonical id → 1-element array,
+      # - legacy alias → 1-element array (resolved to canonical),
+      # - family token (`call`) → every entry under that family,
+      # - unknown token → empty array.
+      def resolve(token)
+        token = token.to_s
+        return [ENTRIES.fetch(token)] if ENTRIES.key?(token)
+
+        if CheckRules::LEGACY_RULE_ALIASES.key?(token)
+          canonical = CheckRules::LEGACY_RULE_ALIASES.fetch(token)
+          return [ENTRIES.fetch(canonical)]
+        end
+
+        if CheckRules::RULE_FAMILIES.include?(token)
+          return ENTRIES.values.select { |entry| entry.id.start_with?("#{token}.") }.sort_by(&:id)
+        end
+
+        []
+      end
+
+      def all
+        ENTRIES.values.sort_by(&:id)
+      end
+    end
+  end
+end

data/lib/rigor/analysis/runner.rb

@@ -140,7 +140,8 @@ module Rigor
         Plugin::TrustPolicy.new(
           trusted_gems: trusted_gems,
           allowed_read_roots: roots,
-          network_policy: @configuration.plugins_io_network
+          network_policy: @configuration.plugins_io_network,
+          allowed_url_hosts: @configuration.plugins_io_allowed_url_hosts
         )
       end
 

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