rigortype 0.1.17 → 0.1.18

data/lib/rigor/cli.rb

@@ -10,13 +10,14 @@ require_relative "version"
 require_relative "analysis/diagnostic"
 require_relative "analysis/result"
 require_relative "cli/options"
+require_relative "cli/diagnostic_formats"
+require_relative "cli/ci_detector"
 
 module Rigor
   # The CLI class is a dispatcher: each `run_*` method delegates to a
   # command-specific class once the command grows beyond a few lines (see
-  # {CLI::TypeOfCommand}). The class-length budget is intentionally relaxed
-  # here so dispatch wiring can live alongside still-inlined commands.
-  class CLI # rubocop:disable Metrics/ClassLength
+  # {CLI::TypeOfCommand} and {CLI::CheckCommand}).
+  class CLI
     EXIT_USAGE = 64
 
     HANDLERS = {
@@ -24,6 +25,7 @@ module Rigor
       "init" => :run_init,
       "annotate" => :run_annotate,
       "type-of" => :run_type_of,
+      "trace" => :run_trace,
       "type-scan" => :run_type_scan,
       "explain" => :run_explain,
       "diff" => :run_diff,
@@ -78,590 +80,10 @@ module Rigor
       EXIT_USAGE
     end
 
-    def run_check # rubocop:disable Metrics/AbcSize
-      load_check_dependencies
-      options = parse_check_options
-      buffer = Options.resolve_buffer_binding(options, err: @err)
-      return EXIT_USAGE if buffer == :usage_error
-
-      configuration = load_check_configuration(options)
-      cache_root = configuration.cache_path
-      handle_clear_cache(cache_root) if options.fetch(:clear_cache)
-
-      special = dispatch_special_check_mode(configuration, options, cache_root)
-      return special unless special.nil?
-
-      runner = build_check_runner(
-        configuration: configuration, options: options,
-        buffer: buffer, cache_root: cache_root
-      )
-      raw_result = runner.run(@argv.empty? ? configuration.paths : @argv)
-      result = apply_baseline_filter(raw_result, configuration, options)
-
-      write_result(result, options.fetch(:format))
-      write_run_stats(result.stats) if result.stats
-      write_trace_appendices
-      runner.cache_store&.evict!
-      write_cache_stats(cache_root, runner.cache_store) if options.fetch(:cache_stats)
-
-      exit_code = result.success? ? 0 : 1
-      exit_code = 1 if baseline_strict_violation?(raw_result.diagnostics, configuration, options)
-      exit_code
-    end
-
-    # ADR-46 — the two incremental-analysis check modes both fully handle
-    # the run and return an exit code (so `run_check` short-circuits);
-    # returns nil for an ordinary check.
-    def dispatch_special_check_mode(configuration, options, cache_root)
-      return run_verify_incremental(configuration) if options.fetch(:verify_incremental)
-      return run_incremental_check(configuration, options, cache_root) if options.fetch(:incremental)
-
-      nil
-    end
-
-    # ADR-46 — the incremental-analysis acceptance gate. Runs a baseline
-    # analysis (recording cross-file dependencies), then re-analyzes a
-    # representative subset of files and serves the rest from the per-file
-    # cache (the body tier), and asserts the merged diagnostics are
-    # byte-identical to a full `--no-cache` analysis. A mismatch means the
-    # incremental machinery would serve a stale — manufactured —
-    # diagnostic, the soundness failure this gate exists to catch. Prints a
-    # one-line PASS (exit 0) or the differing diagnostics (exit 1).
-    def run_verify_incremental(configuration)
-      paths = @argv.empty? ? nil : @argv
-      session = Analysis::IncrementalSession.new(configuration: configuration, paths: paths)
-      session.baseline
-      analyzed = session.analyzed_files
-
-      # Every other file forms the re-analyzed subset, so the run exercises
-      # BOTH the subset-analysis path and the cache-serving path.
-      subset = analyzed.each_with_index.select { |_, index| index.even? }.map(&:first)
-      incremental = normalize_diagnostics(session.reanalyze_subset(subset))
-      full = normalize_diagnostics(verify_full_diagnostics(configuration, paths))
-
-      report_verify_incremental(incremental, full, subset_size: subset.size, total: analyzed.size)
-    end
-
-    # ADR-46 — cross-process incremental analysis (`--incremental`). Derives
-    # the global fingerprint cheaply (no RBS env build), loads the disk
-    # snapshot, and on a fingerprint hit re-analyzes only the files changed
-    # since the last run (plus their dependents), serving the rest from the
-    # snapshot; on a miss runs a full baseline. Persists the updated
-    # snapshot for the next invocation. Diagnostics are identical to a full
-    # run (the `--verify-incremental` gate enforces this); the win is
-    # skipping per-file inference for unchanged files.
-    def run_incremental_check(configuration, options, cache_root)
-      paths = @argv.empty? ? nil : @argv
-      probe = Analysis::Runner.new(configuration: configuration, cache_store: nil)
-      files = paths ? probe.analysis_file_set(paths) : probe.analysis_file_set
-      fingerprint = Cache::IncrementalSnapshot.fingerprint(
-        configuration: configuration, roots: paths || configuration.paths
-      )
-      snapshot = Cache::IncrementalSnapshot.new(root: cache_root)
-      session = Analysis::IncrementalSession.new(configuration: configuration, paths: paths)
-
-      diagnostics, warm = session.run_incremental(snapshot: snapshot, fingerprint: fingerprint)
-      @err.puts("rigor: --incremental #{warm ? 'warm — reused cached diagnostics' : 'cold — full analysis'} " \
-                "(#{files.size} files)")
-
-      result = apply_baseline_filter(Analysis::Result.new(diagnostics: diagnostics, stats: nil), configuration, options)
-      write_result(result, options.fetch(:format))
-      result.success? ? 0 : 1
-    end
-
-    def verify_full_diagnostics(configuration, paths)
-      runner = Analysis::Runner.new(configuration: configuration, cache_store: nil)
-      (paths ? runner.run(paths) : runner.run).diagnostics
-    end
-
-    def normalize_diagnostics(diagnostics)
-      diagnostics.map(&:to_h).sort_by do |hash|
-        [hash["path"].to_s, hash["line"].to_i, hash["column"].to_i, hash["rule"].to_s, hash["message"].to_s]
-      end
-    end
-
-    def report_verify_incremental(incremental, full, subset_size:, total:)
-      if incremental == full
-        @out.puts("rigor: --verify-incremental OK — incremental " \
-                  "(#{subset_size}/#{total} files re-analyzed, rest from cache) " \
-                  "matches full (#{full.size} diagnostics)")
-        return 0
-      end
-
-      only_incremental = incremental - full
-      only_full = full - incremental
-      @err.puts("rigor: --verify-incremental FAILED — incremental and full diagnostics differ.")
-      @err.puts("  incremental-only: #{only_incremental.size}, full-only: #{only_full.size}")
-      (only_incremental + only_full).first(10).each do |hash|
-        @err.puts("    #{hash['path']}:#{hash['line']}:#{hash['column']}: [#{hash['rule']}] #{hash['message']}")
-      end
-      1
-    end
-
-    # ADR-22 slice 5 — the `--baseline-strict` CI gate. When the
-    # flag is set, ANY baseline drift fails the run — not only
-    # excess drift (a bucket over threshold, which already fails
-    # via the surfaced diagnostics) but also DEFICIT drift
-    # (`actual < count`: the baseline has grown looser than the
-    # code and should be regenerated). A no-op, with a stderr
-    # note, when no baseline is active — the flag never
-    # implicitly loads a baseline the config did not name (WD2).
-    def baseline_strict_violation?(raw_diagnostics, configuration, options)
-      return false unless options.fetch(:baseline_strict)
-
-      path = resolve_baseline_path(configuration, options)
-      if path.nil?
-        @err.puts("rigor: --baseline-strict given but no baseline is active; nothing to gate.")
-        return false
-      end
-
-      baseline = Analysis::Baseline.load(path, project_root: Dir.pwd)
-      return false if baseline.nil? || baseline.empty?
+    def run_check
+      require_relative "cli/check_command"
 
-      drifted = baseline.audit(raw_diagnostics).reject { |row| row.status == :within }
-      return false if drifted.empty?
-
-      report_strict_drift(drifted, path)
-      true
-    rescue Analysis::Baseline::LoadError => e
-      @err.puts("rigor: baseline load failed: #{e.message} (--baseline-strict gate skipped)")
-      false
-    end
-
-    def report_strict_drift(rows, path)
-      @err.puts("rigor: --baseline-strict — #{rows.size} bucket(s) drifted from #{path}:")
-      rows.sort_by { |r| [r.bucket.file, r.bucket.rule] }.each do |row|
-        delta = row.delta.positive? ? "+#{row.delta}" : row.delta.to_s
-        @err.puts("  #{row.bucket.file}  [#{row.bucket.rule}]  " \
-                  "#{row.bucket.count} → #{row.actual_count}  (Δ#{delta}, #{row.status})")
-      end
-      @err.puts("rigor: run `rigor baseline regenerate` to refresh the baseline.")
-    end
-
-    # ADR-22 — apply the baseline filter as the LAST step of
-    # the diagnostic pipeline (after `# rigor:disable`,
-    # `severity_profile`, etc. — WD6). Resolution order
-    # follows WD2 (b):
-    #
-    #   1. --no-baseline on the CLI → no baseline.
-    #   2. --baseline=PATH on the CLI → load that path.
-    #   3. .rigor.yml's `baseline: <path>` → load that path.
-    #   4. otherwise → no baseline.
-    #
-    # When the path resolves and loads successfully, the filter
-    # replaces `result.diagnostics` with the surfaced set and
-    # writes a one-line summary to stderr (WD7) when any
-    # diagnostics were silenced. Load failures emit a warning
-    # to stderr and fall through to "no baseline" (graceful
-    # degradation).
-    def apply_baseline_filter(result, configuration, options)
-      path = resolve_baseline_path(configuration, options)
-      return result if path.nil?
-
-      baseline = Analysis::Baseline.load(path, project_root: Dir.pwd)
-      return result if baseline.nil?
-
-      surfaced, silenced_count = baseline.filter(result.diagnostics)
-      report_baseline_summary(silenced_count, path) if silenced_count.positive?
-      Analysis::Result.new(diagnostics: surfaced, stats: result.stats)
-    rescue Analysis::Baseline::LoadError => e
-      @err.puts("rigor: baseline load failed: #{e.message} (continuing without baseline)")
-      result
-    end
-
-    # WD2 (b) — resolve effective baseline path.
-    def resolve_baseline_path(configuration, options)
-      cli_value = options.fetch(:baseline)
-      case cli_value
-      when false then nil # --no-baseline
-      when :unset then configuration.baseline_path # fall through to config
-      else cli_value # --baseline=PATH
-      end
-    end
-
-    def report_baseline_summary(silenced_count, baseline_path)
-      @err.puts("rigor: #{silenced_count} diagnostic(s) silenced by baseline #{baseline_path}")
-    end
-
-    def build_check_runner(configuration:, options:, buffer:, cache_root:)
-      cache_store = if options.fetch(:no_cache)
-                      nil
-                    else
-                      Cache::Store.new(
-                        root: cache_root,
-                        max_bytes: configuration.cache_max_bytes
-                      )
-                    end
-      Analysis::Runner.new(
-        configuration: configuration,
-        explain: options.fetch(:explain),
-        cache_store: cache_store,
-        collect_stats: options.fetch(:stats),
-        workers: resolve_workers(options, configuration),
-        buffer: buffer
-      )
-    end
-
-    # ADR-15 Phase 4c — resolves the worker count by
-    # precedence: CLI `--workers=N` (most explicit) > env
-    # `RIGOR_RACTOR_WORKERS` > config `.rigor.yml`
-    # `parallel.workers:` > 0 (sequential default). Returns
-    # an Integer; non-numeric values raise so typos fail
-    # loudly. CLI / env may pass a negative value — clamped
-    # to 0 (sequential) so a stray `-1` doesn't crash the
-    # pool spawn loop.
-    def resolve_workers(options, configuration)
-      cli_value = options[:workers]
-      return [Integer(cli_value), 0].max if cli_value
-
-      env_value = ENV.fetch("RIGOR_RACTOR_WORKERS", nil)
-      return [Integer(env_value), 0].max if env_value && !env_value.empty?
-
-      configuration.parallel_workers
-    end
-
-    def parse_check_options # rubocop:disable Metrics/AbcSize,Metrics/MethodLength
-      options = {
-        # `nil` triggers `Configuration.discover` (`.rigor.yml` then
-        # `.rigor.dist.yml`); an explicit `--config=PATH` overrides.
-        config: nil,
-        format: "text",
-        explain: false,
-        cache_stats: false,
-        clear_cache: false,
-        no_cache: false,
-        # Run-stats summary (target files, RBS class universe
-        # breakdown, wall time, peak RSS) is on by default
-        # because collection is ~free (single syscall for RSS,
-        # one walk of `class_decl_paths` for the breakdown).
-        # `--no-stats` suppresses it for callers that want a
-        # diagnostic-only output stream.
-        stats: true,
-        # ADR-15 Phase 4c — when nil, falls back to
-        # `RIGOR_RACTOR_WORKERS` then `.rigor.yml`
-        # `parallel.workers:` then 0 (sequential). See
-        # `resolve_workers` for the precedence chain.
-        workers: nil,
-        # Editor mode (`docs/design/20260516-editor-mode.md`).
-        # Both must appear together; the runner uses the pair
-        # to bind an in-flight buffer file to its logical path.
-        tmp_file: nil,
-        instead_of: nil,
-        # ADR-22 — baseline filter. `:unset` means "fall through
-        # to `.rigor.yml`'s `baseline:` key"; a String overrides
-        # the config; `false` (from `--no-baseline`) suppresses
-        # any baseline that the config might name.
-        baseline: :unset,
-        # ADR-22 slice 5 — `--baseline-strict` CI gate: fail the
-        # run on any baseline drift, in either direction.
-        baseline_strict: false,
-        # ADR-32 WD10 carry-over — `--treat-all-as-inline-rbs`
-        # forces the `rigor-rbs-inline` plugin into the loaded
-        # plugin set with `require_magic_comment: false` so a
-        # single ad-hoc `rigor check` invocation treats every
-        # analysed file as inline-RBS without the user editing
-        # `.rigor.yml`. Intended for single-file / ad-hoc CI use;
-        # ordinary projects should configure the plugin in
-        # `.rigor.yml`.
-        treat_all_as_inline_rbs: false,
-        # ADR-46 — the incremental-analysis acceptance gate. Runs a
-        # baseline analysis, re-analyzes a subset and serves the rest from
-        # the per-file cache, and asserts the merged diagnostics are
-        # byte-identical to a full `--no-cache` run. Exits non-zero on any
-        # mismatch. Off by default.
-        verify_incremental: false,
-        # ADR-46 — cross-process incremental analysis. With a disk snapshot
-        # of the prior run's per-file diagnostics + dependency graph,
-        # re-analyzes only the changed closure and serves the rest from the
-        # snapshot. Off by default.
-        incremental: false
-      }
-      parser = OptionParser.new do |opts| # rubocop:disable Metrics/BlockLength
-        opts.banner = "Usage: rigor check [options] [paths]"
-        opts.on("--config=PATH", "Path to the Rigor configuration file") { |value| options[:config] = value }
-        opts.on("--format=FORMAT", "Output format: text or json") { |value| options[:format] = value }
-        opts.on("--explain", "Surface fail-soft fallback events as :info diagnostics") { options[:explain] = true }
-        opts.on("--cache-stats", "Print on-disk cache inventory at end of run") { options[:cache_stats] = true }
-        opts.on("--clear-cache", "Remove the .rigor/cache directory before running") { options[:clear_cache] = true }
-        opts.on("--no-cache", "Disable the persistent cache for this run") { options[:no_cache] = true }
-        opts.on("--[no-]stats",
-                "Print run summary (files, classes, memory, wall time) to stderr (default: on)") do |value|
-          options[:stats] = value
-        end
-        opts.on("--workers=N", Integer,
-                "Dispatch per-file analysis across N Ractor workers (default: 0; sequential)") do |value|
-          options[:workers] = value
-        end
-        Options.add_editor_mode(opts, options)
-        opts.on("--baseline=PATH",
-                "ADR-22: load baseline from PATH (overrides .rigor.yml `baseline:`)") do |value|
-          options[:baseline] = value
-        end
-        opts.on("--no-baseline",
-                "ADR-22: ignore any configured baseline for this run") do
-          options[:baseline] = false
-        end
-        opts.on("--baseline-strict",
-                "ADR-22: fail the run on any baseline drift (CI gate)") do
-          options[:baseline_strict] = true
-        end
-        opts.on("--treat-all-as-inline-rbs",
-                "ADR-32: force-load rigor-rbs-inline with require_magic_comment: false") do
-          options[:treat_all_as_inline_rbs] = true
-        end
-        opts.on("--verify-incremental",
-                "ADR-46: assert incremental analysis matches a full run, then exit") do
-          options[:verify_incremental] = true
-        end
-        opts.on("--incremental",
-                "ADR-46: re-analyze only files changed since the last run (cross-process cache)") do
-          options[:incremental] = true
-        end
-      end
-      parser.parse!(@argv)
-      options
-    end
-
-    # ADR-32 WD10 carry-over — wraps `Configuration.load` so the
-    # CLI's `--treat-all-as-inline-rbs` flag can inject a
-    # `rigor-rbs-inline` plugin entry with
-    # `require_magic_comment: false` into the loaded plugin
-    # set. Re-runs the include-aware YAML load and applies the
-    # injection before `Configuration.new` so the new entry
-    # follows the normal coercion path. A pre-existing
-    # `rigor-rbs-inline` entry (by gem name or `id: rbs-inline`)
-    # is removed first so the synthesised entry's
-    # `require_magic_comment: false` wins unconditionally.
-    def load_check_configuration(options)
-      return Configuration.load(options.fetch(:config)) unless options.fetch(:treat_all_as_inline_rbs)
-
-      path = options.fetch(:config) || Configuration.discover
-      data = path && File.exist?(path) ? Configuration.load_with_includes(path) : {}
-      data = data.dup
-      data["plugins"] = inject_treat_all_as_inline_rbs(Array(data["plugins"]))
-      Configuration.new(Configuration::DEFAULTS.merge(data))
-    end
-
-    def inject_treat_all_as_inline_rbs(entries)
-      filtered = entries.reject { |entry| rigor_rbs_inline_entry?(entry) }
-      filtered + [{
-        "gem" => "rigor-rbs-inline",
-        "id" => "rbs-inline",
-        "config" => { "require_magic_comment" => false }
-      }]
-    end
-
-    def rigor_rbs_inline_entry?(entry)
-      case entry
-      when String
-        entry == "rigor-rbs-inline"
-      when Hash
-        string_keyed = entry.to_h { |k, v| [k.to_s, v] }
-        string_keyed["gem"] == "rigor-rbs-inline" || string_keyed["id"] == "rbs-inline"
-      else
-        false
-      end
-    end
-
-    def handle_clear_cache(cache_root)
-      if File.directory?(cache_root)
-        FileUtils.rm_rf(cache_root)
-        @out.puts("Cleared cache: #{cache_root}")
-      else
-        @out.puts("Cache already empty: #{cache_root}")
-      end
-    end
-
-    # Emits the {Analysis::RunStats} summary to STDERR so it
-    # doesn't interleave with the diagnostic stream (text or
-    # JSON) on STDOUT. JSON consumers can pipe stdout cleanly;
-    # interactive users still see the summary on their tty.
-    def write_run_stats(stats)
-      @err.puts("")
-      stats.format(@err)
-    end
-
-    # Opt-in developer diagnostics printed after the run: the
-    # inference-cutoff trace (RIGOR_BUDGET_TRACE) and the heap-attribution
-    # profile (RIGOR_HEAP_PROFILE). Each gates itself, so this is a no-op
-    # on a normal run.
-    def write_trace_appendices
-      write_budget_trace
-      write_heap_profile
-    end
-
-    # Dumps the opt-in inference-cutoff counters (RIGOR_BUDGET_TRACE).
-    # These are the hard-coded "budget" guards that silently degrade
-    # to `Dynamic[top]` / a fallback bound — counting them shows where
-    # inference actually stopped. Process-global counters: meaningful
-    # only on a single-process run (`--workers 0`), since they do not
-    # cross fork boundaries.
-    def write_budget_trace
-      return unless Inference::BudgetTrace.enabled?
-
-      counts = Inference::BudgetTrace.snapshot
-      @err.puts("")
-      @err.puts("Inference cutoffs (RIGOR_BUDGET_TRACE; --workers 0 for an exact count)")
-      @err.puts("  recursion-guard hits:      #{counts[Inference::BudgetTrace::RECURSION_GUARD]}")
-      @err.puts("  ancestor-walk-limit hits:  #{counts[Inference::BudgetTrace::ANCESTOR_WALK_LIMIT]}")
-      @err.puts("  hkt-fuel-exhausted hits:   #{counts[Inference::BudgetTrace::HKT_FUEL_EXHAUSTED]}")
-      write_budget_distributions
-    end
-
-    # Dumps the read-only size distributions (ADR-41 Slice 2a). These
-    # observe how large unions actually get, with no cap enforced — the
-    # data the `union_size` budget default should be chosen from. The
-    # `over` thresholds bracket the TypeProf prior (10) and Rigor's spec
-    # default (24).
-    def write_budget_distributions
-      summary = Inference::BudgetTrace.summarize(Inference::BudgetTrace::UNION_ARITY, over: [10, 24, 40])
-      pct = summary[:percentiles]
-      @err.puts("  union arity:  n=#{summary[:count]} max=#{summary[:max]} " \
-                "p50=#{pct[:p50]} p90=#{pct[:p90]} p99=#{pct[:p99]}")
-      over = summary[:over]
-      @err.puts("    unions ≥10: #{over[10]}  ≥24: #{over[24]}  ≥40: #{over[40]}")
-    end
-
-    # Dumps a live-heap class breakdown (RIGOR_HEAP_PROFILE) — retained
-    # objects by class after a forced GC, ranked by total memsize. The
-    # tool for attributing where the analyzer's resident memory goes
-    # (ADR-41 Slice 2b): it answers whether the heap is type carriers,
-    # RBS objects, Prism nodes, or fact-store Hashes/Strings. Walking the
-    # whole heap is slow — a dev probe, not a normal diagnostic. Run
-    # single-process (`--workers 0`) so the parent heap is the analysis
-    # heap; the gem is required lazily so a normal run never loads it.
-    def write_heap_profile
-      return if ENV["RIGOR_HEAP_PROFILE"].to_s.empty?
-
-      by_class, total = tally_live_heap
-      @err.puts("")
-      @err.puts("Heap profile (RIGOR_HEAP_PROFILE; live objects after GC, by class)")
-      @err.puts("  total tracked: #{heap_mb(total)} across #{by_class.size} classes")
-      by_class.sort_by { |_, (_, bytes)| -bytes }.first(30).each do |name, (count, bytes)|
-        @err.puts("  #{heap_mb(bytes).rjust(10)}  #{count.to_s.rjust(9)} obj  #{name}")
-      end
-      write_string_allocation_sites
-    end
-
-    # Loads the analysis-path dependencies lazily (so non-check commands
-    # stay light) and starts heap-allocation tracing if requested, before
-    # any analysis object is allocated.
-    def load_check_dependencies
-      require_relative "analysis/runner"
-      require_relative "analysis/buffer_binding"
-      require_relative "analysis/baseline"
-      require_relative "cache/store"
-      start_heap_trace_if_requested
-    end
-
-    # Starts allocation tracing (RIGOR_HEAP_TRACE) as early as possible so
-    # the heap profile can attribute retained Strings to their allocation
-    # `file:line`. Very high overhead — run on a small file subset only.
-    def start_heap_trace_if_requested
-      return if ENV["RIGOR_HEAP_TRACE"].to_s.empty?
-
-      require "objspace"
-      ObjectSpace.trace_object_allocations_start
-    end
-
-    # When RIGOR_HEAP_TRACE is on, groups the live String objects by their
-    # allocation site (`sourcefile:sourceline`) and prints the top sites by
-    # count — pinpointing which engine code retains the millions of strings
-    # that dominate the large-app heap (ADR-41 Slice 2b). Strings allocated
-    # before tracing started report `(pre-trace)`.
-    def write_string_allocation_sites
-      return if ENV["RIGOR_HEAP_TRACE"].to_s.empty?
-
-      by_site = Hash.new(0)
-      ObjectSpace.each_object(String) do |str|
-        file = ObjectSpace.allocation_sourcefile(str)
-        line = ObjectSpace.allocation_sourceline(str)
-        by_site[file ? "#{file}:#{line}" : "(pre-trace)"] += 1
-      end
-      @err.puts("")
-      @err.puts("  String allocation sites (top 25 by live count)")
-      by_site.sort_by { |_, n| -n }.first(25).each do |site, n|
-        @err.puts("  #{n.to_s.rjust(9)}  #{site}")
-      end
-    end
-
-    # Walks the whole live heap (after a forced GC) and tallies
-    # `{class_name => [count, memsize]}` plus the grand total. Returns
-    # `[by_class, total]`. Slow — a dev probe only.
-    def tally_live_heap
-      require "objspace"
-      GC.start
-      by_class = Hash.new { |h, k| h[k] = [0, 0] }
-      total = 0
-      ObjectSpace.each_object do |obj|
-        size = ObjectSpace.memsize_of(obj)
-        entry = by_class[heap_class_name(obj)]
-        entry[0] += 1
-        entry[1] += size
-        total += size
-      end
-      [by_class, total]
-    end
-
-    def heap_class_name(obj)
-      klass = Object.instance_method(:class).bind_call(obj)
-      klass.name || klass.inspect
-    rescue StandardError
-      "(unknown)"
-    end
-
-    def heap_mb(bytes)
-      Kernel.format("%.1f MB", bytes / 1_048_576.0)
-    end
-
-    def write_cache_stats(cache_root, runtime_store)
-      inv = Cache::Store.disk_inventory(root: cache_root)
-
-      @out.puts("")
-      @out.puts("Cache (root: #{inv.fetch(:root)})")
-      schema = inv.fetch(:schema_version)
-      @out.puts("  schema_version: #{schema.nil? ? 'absent' : schema}")
-      write_disk_inventory(inv)
-      write_runtime_stats(runtime_store) if runtime_store
-    end
-
-    def write_disk_inventory(inv)
-      if inv.fetch(:total_entries).zero?
-        @out.puts("  (empty)")
-        return
-      end
-
-      @out.puts("  #{inv.fetch(:total_entries)} entries, #{format_bytes(inv.fetch(:total_bytes))}")
-      inv.fetch(:producers).each do |producer|
-        bytes = format_bytes(producer.fetch(:bytes))
-        @out.puts("    #{producer.fetch(:id)}: #{producer.fetch(:entries)} entries, #{bytes}")
-      end
-    end
-
-    def write_runtime_stats(store)
-      stats = store.stats
-      hits = stats.fetch(:hits)
-      misses = stats.fetch(:misses)
-      writes = stats.fetch(:writes)
-      @out.puts("  this run: #{hits} #{plural(hits, 'hit')}, " \
-                "#{misses} #{plural(misses, 'miss', 'misses')}, " \
-                "#{writes} #{plural(writes, 'write')}")
-      stats.fetch(:by_producer).each do |id, counts|
-        @out.puts("    #{id}: #{counts.fetch(:hits)} #{plural(counts.fetch(:hits), 'hit')}, " \
-                  "#{counts.fetch(:misses)} #{plural(counts.fetch(:misses), 'miss', 'misses')}, " \
-                  "#{counts.fetch(:writes)} #{plural(counts.fetch(:writes), 'write')}")
-      end
-    end
-
-    def plural(count, singular, plural = "#{singular}s")
-      count == 1 ? singular : plural
-    end
-
-    def format_bytes(bytes)
-      return "#{bytes} B" if bytes < 1024
-      return format("%.1f KiB", bytes / 1024.0) if bytes < 1024 * 1024
-
-      format("%.1f MiB", bytes / (1024.0 * 1024.0))
+      CheckCommand.new(argv: @argv, out: @out, err: @err).run
     end
 
     def run_init
@@ -778,6 +200,12 @@ module Rigor
       TypeOfCommand.new(argv: @argv, out: @out, err: @err).run
     end
 
+    def run_trace
+      require_relative "cli/trace_command"
+
+      TraceCommand.new(argv: @argv, out: @out, err: @err).run
+    end
+
     def run_type_scan
       require_relative "cli/type_scan_command"
 
@@ -861,34 +289,6 @@ module Rigor
       CLI::PluginCommand.new(argv: @argv, out: @out, err: @err).run
     end
 
-    def write_result(result, format)
-      case format
-      when "json"
-        @out.puts(JSON.pretty_generate(result.to_h))
-      when "text"
-        write_text_result(result)
-      else
-        raise OptionParser::InvalidArgument, "unsupported format: #{format}"
-      end
-    end
-
-    # Text output adds a one-line summary so users see the
-    # diagnostic-count immediately. The summary distinguishes
-    # the success and failure cases and reports the affected
-    # file count for failures.
-    def write_text_result(result)
-      result.diagnostics.each { |diagnostic| @out.puts(diagnostic) }
-
-      if result.success?
-        @out.puts("No diagnostics") if result.diagnostics.empty?
-        return
-      end
-
-      error_files = result.diagnostics.select(&:error?).map(&:path).uniq.size
-      @out.puts("")
-      @out.puts("#{result.error_count} error(s) in #{error_files} file(s)")
-    end
-
     def help
       <<~HELP
         Usage: rigor <command> [options]
@@ -898,6 +298,7 @@ module Rigor
           init       Create a starter .rigor.yml
           annotate   Print FILE with each line's last-expression type
           type-of    Print the inferred type at FILE:LINE:COL
+          trace      Replay how the engine typed FILE as a terminal animation
           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