rigortype 0.1.18 → 0.2.0

data/lib/rigor/cli/check_command.rb

@@ -6,6 +6,8 @@ require "optionparser"
 
 require_relative "../configuration"
 require_relative "../analysis/result"
+require_relative "../analysis/rule_catalog"
+require_relative "coverage_scan"
 require_relative "command"
 require_relative "options"
 require_relative "diagnostic_formats"
@@ -35,6 +37,7 @@ module Rigor
         return CLI::EXIT_USAGE if buffer == :usage_error
 
         configuration = load_check_configuration(options)
+        configuration = apply_bleeding_edge_override(configuration, options)
         cache_root = configuration.cache_path
         handle_clear_cache(cache_root) if options.fetch(:clear_cache)
 
@@ -48,7 +51,8 @@ module Rigor
         raw_result = runner.run(@argv.empty? ? configuration.paths : @argv)
         result = apply_baseline_filter(raw_result, configuration, options)
 
-        write_result(result, options.fetch(:format))
+        coverage = compute_coverage(runner, configuration, options)
+        write_result(result, options.fetch(:format), coverage: coverage)
         emit_ci_detected_output(result, options)
         write_run_stats(result.stats) if result.stats
         write_trace_appendices
@@ -276,29 +280,18 @@ module Rigor
 
       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
@@ -335,17 +328,34 @@ module Rigor
           # the human output; for GitLab / reviewdog-routed CIs, print a
           # one-line hint. On by default; `--no-ci-detect` (or
           # `RIGOR_CI_DETECT=0`) disables it.
-          ci_detect: true
+          ci_detect: true,
+          # ADR-50 § WD2 — the `--bleeding-edge[=ids]` / `--no-bleeding-edge`
+          # CLI mirror of the `bleeding_edge:` config key. `:unset` means "no
+          # flag — use the configured selection"; `true` adopts the whole
+          # overlay, `false` adopts none, and an Array of ids adopts only
+          # those (see `apply_bleeding_edge_override`).
+          bleeding_edge: :unset,
+          # Type-precision coverage block. Off by default — it is a
+          # second precision pass over the analyzed files (the same scan
+          # `rigor coverage` runs), so it is opt-in to keep the default
+          # check path's cost unchanged. When set, `--format json` gains
+          # a `coverage` object (scan_files + precision tiers) and the
+          # text output prints a one-line coverage summary.
+          coverage: 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 }
+          Options.add_config(opts, options)
           opts.on("--format=FORMAT",
                   "Output format: text, json, sarif, github, gitlab, checkstyle, junit, teamcity") do |value|
             options[:format] = value
           end
           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("--coverage",
+                  "Add a type-precision coverage block (an extra precision pass over the analyzed files)") do
+            options[:coverage] = true
+          end
           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",
@@ -385,6 +395,18 @@ module Rigor
                   "ADR-51: do not auto-emit CI-native output when a CI environment is detected") do
             options[:ci_detect] = false
           end
+          # ADR-50 § WD2 — `=[LIST]` (not ` [LIST]`) so a bare `--bleeding-edge`
+          # never swallows a following positional path: `rigor check
+          # --bleeding-edge lib` adopts the whole overlay and checks `lib`.
+          opts.on("--bleeding-edge=[LIST]",
+                  "ADR-50: adopt the bleeding-edge overlay for this run " \
+                  "(all features, or a comma-separated feature-id list)") do |value|
+            options[:bleeding_edge] = value.nil? || value.split(",").map(&:strip).reject(&:empty?)
+          end
+          opts.on("--no-bleeding-edge",
+                  "ADR-50: ignore any configured bleeding_edge: selection for this run") do
+            options[:bleeding_edge] = false
+          end
         end
         parser.parse!(@argv)
         options
@@ -410,6 +432,20 @@ module Rigor
         Configuration.new(Configuration::DEFAULTS.merge(data))
       end
 
+      # ADR-50 § WD2 — applies the `--bleeding-edge[=ids]` / `--no-bleeding-edge`
+      # CLI selection over the configured `bleeding_edge:` value, mirroring the
+      # CLI-over-config precedence `--workers` and `--no-cache` follow. `:unset`
+      # (no flag) leaves the loaded configuration untouched; any other value is
+      # normalised by {Configuration#with_bleeding_edge}, so the two
+      # `SeverityProfile.resolve` sites (and the worker path, which receives the
+      # whole frozen Configuration) see the run's selection.
+      def apply_bleeding_edge_override(configuration, options)
+        selection = options.fetch(:bleeding_edge)
+        return configuration if selection == :unset
+
+        configuration.with_bleeding_edge(selection)
+      end
+
       def inject_treat_all_as_inline_rbs(entries)
         filtered = entries.reject { |entry| rigor_rbs_inline_entry?(entry) }
         filtered + [{
@@ -473,6 +509,9 @@ module Rigor
         @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]}")
+        @err.puts("  recursion-unroll-fuel hits: #{counts[Inference::BudgetTrace::RECURSION_UNROLL_FUEL]}")
+        @err.puts("  recursion-fixpoint-cap hits: #{counts[Inference::BudgetTrace::RECURSION_FIXPOINT_CAP]}")
+        @err.puts("  block-writeback-cap hits:  #{counts[Inference::BudgetTrace::BLOCK_WRITEBACK_CAP]}")
         write_budget_distributions
       end
 
@@ -632,12 +671,15 @@ module Rigor
         format("%.1f MiB", bytes / (1024.0 * 1024.0))
       end
 
-      def write_result(result, format)
+      def write_result(result, format, coverage: nil)
         case format
         when "json"
-          @out.puts(JSON.pretty_generate(result.to_h))
+          payload = enrich_json(result.to_h)
+          payload["coverage"] = coverage_payload(coverage) if coverage
+          @out.puts(JSON.pretty_generate(payload))
         when "text"
           write_text_result(result)
+          write_coverage_summary(coverage) if coverage
         when ->(fmt) { CLI::DiagnosticFormats.supports?(fmt) }
           # ADR-51 — CI-native renderings (SARIF / GitHub Actions commands /
           # GitLab Code Quality). The `github` form is empty when there are no
@@ -649,6 +691,66 @@ module Rigor
         end
       end
 
+      # Runs the type-precision scan (`--coverage`) over the same file set
+      # the check analyzed and returns a `CoverageReport`, or nil when the
+      # flag is off. It is a second pass — the same scan `rigor coverage`
+      # runs, reused via {CoverageScan} — so it is opt-in to keep the
+      # default check path's cost unchanged.
+      def compute_coverage(runner, configuration, options)
+        return nil unless options.fetch(:coverage)
+
+        files = @argv.empty? ? runner.analysis_file_set : runner.analysis_file_set(@argv)
+        CoverageScan.precision_report(files: files, configuration: configuration)
+      end
+
+      # The `coverage` block embedded in `--format json`. Mirrors the
+      # `summary` of `rigor coverage --format json` (the same vocabulary —
+      # `precise_ratio`, not a separate `typed_ratio`) plus `scan_files`,
+      # so a consumer reads one stream to learn both what fired and how
+      # much of the analyzed surface Rigor could type.
+      def coverage_payload(report)
+        {
+          "scan_files" => report.files.size - report.parse_errors.size,
+          "parse_errors" => report.parse_errors.size,
+          "expressions_typed" => report.grand_total,
+          "precise_count" => report.precise_count,
+          "precise_ratio" => report.precision_ratio.round(4),
+          "dynamic_opaque_count" => report.opaque_count,
+          "dynamic_opaque_ratio" => report.opaque_ratio.round(4)
+        }
+      end
+
+      def write_coverage_summary(report)
+        files = report.files.size - report.parse_errors.size
+        pct = (report.precision_ratio * 100).round(1)
+        @out.puts("Type coverage: #{files} file(s), #{pct}% precise " \
+                  "(#{report.precise_count}/#{report.grand_total} expressions). " \
+                  "Run `rigor coverage` for the full per-file / per-tier breakdown.")
+      end
+
+      # Adds the per-rule `evidence_tier` and `documentation_url` fields
+      # to each diagnostic in the `--format json` payload. Both are pure
+      # functions of the rule id (the rule catalogue, ADR-61 / the
+      # 2026-06-15 feedback §4 + §5.1), so they enrich the presentation
+      # layer here rather than threading through every diagnostic
+      # construction site. Only built-in rules carry catalogue metadata;
+      # plugin / `rbs_extended` / parse-error diagnostics are left
+      # untouched (they host their own documentation and confidence).
+      def enrich_json(payload)
+        Array(payload["diagnostics"]).each do |diag|
+          next unless diag["source_family"] == Analysis::Diagnostic::DEFAULT_SOURCE_FAMILY.to_s
+
+          rule = diag["rule"]
+          next unless rule
+
+          tier = Analysis::RuleCatalog.evidence_tier(rule)
+          diag["evidence_tier"] = tier.to_s if tier
+          url = Analysis::RuleCatalog.documentation_url(rule)
+          diag["documentation_url"] = url if url
+        end
+        payload
+      end
+
       # ADR-51 WD7 — CI auto-detection. Only augments the default human
       # (`text`) output: an explicit `--format` means the caller is in control
       # and is left untouched. For a first-class stdout-native CI (GitHub

data/lib/rigor/cli/coverage_command.rb

@@ -1,14 +1,25 @@
 # frozen_string_literal: true
 
+require "English"
 require "optionparser"
 require "prism"
 
 require_relative "../configuration"
+require_relative "options"
 require_relative "../environment"
 require_relative "../inference/precision_scanner"
+require_relative "../inference/protection_scanner"
+require_relative "../inference/parameter_inference_collector"
+require_relative "../protection/mutation_scanner"
+require_relative "../language_server/project_context"
 require_relative "../scope"
 require_relative "coverage_report"
 require_relative "coverage_renderer"
+require_relative "coverage_scan"
+require_relative "protection_report"
+require_relative "protection_renderer"
+require_relative "mutation_protection_report"
+require_relative "mutation_protection_renderer"
 require_relative "command"
 
 module Rigor
@@ -32,10 +43,15 @@ module Rigor
       # @return [Integer] CLI exit status.
       def run
         options = parse_options
+        return mutation_misuse_error if options[:mutation] && !options[:protection]
+        return run_mutation_protection(options) if options[:mutation]
+
         paths = collect_paths(@argv, command_name: "coverage")
         return CLI::EXIT_USAGE if paths.nil?
         return usage_error if paths.empty?
 
+        return run_protection(paths, options) if options[:protection]
+
         report = scan_paths(paths, options)
         CoverageRenderer.new(out: @out).render(report, format: options.fetch(:format))
         determine_exit(report, options)
@@ -44,45 +60,112 @@ module Rigor
       private
 
       def parse_options
-        options = { format: "text", threshold: nil, config: nil }
+        options = { format: "text", threshold: nil, config: nil, protection: false, mutation: false }
 
         OptionParser.new do |opts|
           opts.banner = USAGE
           opts.on("--format=FORMAT", "Output format: text or json") { |v| options[:format] = v }
-          opts.on("--config=PATH", "Path to the Rigor configuration file") { |v| options[:config] = v }
+          Options.add_config(opts, options)
+          opts.on(
+            "--protection",
+            "Report type-protection coverage (ADR-63 Tier 1) instead of type precision"
+          ) { options[:protection] = true }
+          opts.on(
+            "--mutation",
+            "With --protection: measure actual mutation effectiveness (ADR-63 Tier 2). " \
+            "Scopes to git-changed files when no paths are given; explicit paths override."
+          ) { options[:mutation] = true }
           opts.on(
             "--threshold=RATIO", Float,
-            "Exit 1 when precision ratio is below RATIO (0.0–1.0)"
+            "Exit 1 when the precision (or, with --protection, protection/effectiveness) ratio is below RATIO (0.0–1.0)"
           ) { |v| options[:threshold] = v }
         end.parse!(@argv)
 
         options
       end
 
-      def usage_error
-        @err.puts("coverage: at least one path is required")
+      def mutation_misuse_error
+        @err.puts("coverage: --mutation requires --protection")
         @err.puts(USAGE)
         CLI::EXIT_USAGE
       end
 
-      def scan_paths(paths, options)
+      def run_protection(paths, options)
+        report = scan_protection(paths, options)
+        ProtectionRenderer.new(out: @out).render(report, format: options.fetch(:format))
+        determine_protection_exit(report, options)
+      end
+
+      def scan_protection(paths, options)
         configuration = Configuration.load(options.fetch(:config))
-        scope = Scope.empty(environment: project_environment(configuration))
-        scanner = Inference::PrecisionScanner.new(scope: scope)
-        accumulator = CoverageAccumulator.new
+        environment = project_environment(configuration)
+        scope = scope_with_inferred_params(paths, configuration, environment)
+        scanner = Inference::ProtectionScanner.new(scope: scope)
+        accumulator = ProtectionAccumulator.new
 
         paths.each { |path| scan_one(path, scanner, accumulator, configuration) }
-        accumulator.to_report(paths, options)
+        accumulator.to_report
       end
 
-      def project_environment(configuration)
-        Environment.for_project(
-          libraries: configuration.libraries,
-          signature_paths: configuration.signature_paths
+      # ADR-67 WD3 — seed the call-site parameter-inference table so the
+      # protection scan counts an inferred-parameter receiver (e.g. `node.loc`
+      # where `node` is a `def compile(node)` parameter) as protected when its
+      # call sites resolve to concrete argument types. ONLY the parameter table
+      # is seeded — no cross-file discovery — so every site that does not gain
+      # an inferred parameter type is classified byte-identically to the
+      # un-inferred baseline. Collection spans the scanned `paths`.
+      def scope_with_inferred_params(paths, configuration, environment)
+        base = Scope.empty(environment: environment)
+        table = Inference::ParameterInferenceCollector.collect(
+          files: paths, environment: environment, target_ruby: configuration.target_ruby
         )
+        return base if table.empty?
+
+        base.with_discovery(base.discovery.with(param_inferred_types: table))
       end
 
-      def scan_one(path, scanner, accumulator, configuration)
+      def determine_protection_exit(report, options)
+        return 1 unless report.parse_errors.empty?
+
+        threshold = options[:threshold]
+        return 0 if threshold.nil?
+
+        report.ratio < threshold ? 1 : 0
+      end
+
+      # ADR-63 Tier 2 — the mutation-effectiveness deep dive. Builds the RBS
+      # environment + project pre-pass once (the warm loop), then re-analyses
+      # each target file's mutants against its clean baseline. Defaults to the
+      # git-changed `.rb` files; explicit paths override (and enable the
+      # whole-project opt-in, which is minutes).
+      def run_mutation_protection(options)
+        explicit = collect_paths(@argv, command_name: "coverage")
+        return CLI::EXIT_USAGE if explicit.nil?
+
+        target_files = explicit.empty? ? changed_ruby_files : explicit
+        if target_files.empty?
+          @out.puts("No changed Ruby files to measure — pass paths to measure explicitly.")
+          return 0
+        end
+
+        report = scan_mutation_protection(target_files, options)
+        MutationProtectionRenderer.new(out: @out).render(report, format: options.fetch(:format))
+        determine_protection_exit(report, options)
+      end
+
+      def scan_mutation_protection(paths, options)
+        configuration = Configuration.load(options.fetch(:config))
+        context = LanguageServer::ProjectContext.new(configuration: configuration)
+        scanner = Protection::MutationScanner.new(
+          configuration: configuration, environment: context.environment, project_scan: context.project_scan
+        )
+        accumulator = MutationProtectionAccumulator.new
+
+        paths.each { |path| scan_mutation_one(path, scanner, accumulator, configuration) }
+        accumulator.to_report
+      end
+
+      def scan_mutation_one(path, scanner, accumulator, configuration)
         source = File.read(path)
         parse_result = Prism.parse(source, filepath: path, version: configuration.target_ruby)
         if parse_result.errors.any?
@@ -90,7 +173,56 @@ module Rigor
           return
         end
 
-        accumulator.absorb(path, scanner.scan(parse_result.value))
+        accumulator.absorb(scanner.scan_file(path, source: source))
+      end
+
+      # The git-changed (modified / added / untracked) `.rb` files that exist on
+      # disk — the default Tier 2 scope. Returns [] outside a git work tree or
+      # when git is unavailable; the caller then reports "nothing to measure".
+      def changed_ruby_files
+        output = git_status_porcelain
+        return [] if output.nil?
+
+        output.each_line.filter_map { |line| changed_path(line) }.uniq.select { |p| File.file?(p) }
+      end
+
+      # Parse one `git status --porcelain` line (`XY <path>`, or `R  old -> new`)
+      # into a candidate `.rb` path, or nil.
+      def changed_path(line)
+        path = line[3..]&.chomp
+        return nil if path.nil? || path.empty?
+
+        path = path.split(" -> ", 2).last if path.include?(" -> ")
+        path = path.delete_prefix('"').delete_suffix('"')
+        path.end_with?(".rb") ? path : nil
+      end
+
+      def git_status_porcelain
+        output = IO.popen(%w[git status --porcelain --untracked-files=all], err: File::NULL, &:read)
+        $CHILD_STATUS&.success? ? output : nil
+      rescue SystemCallError
+        nil
+      end
+
+      def usage_error
+        @err.puts("coverage: at least one path is required")
+        @err.puts(USAGE)
+        CLI::EXIT_USAGE
+      end
+
+      def scan_paths(paths, options)
+        CoverageScan.precision_report(files: paths, configuration: Configuration.load(options.fetch(:config)))
+      end
+
+      # Delegated to the shared scan module (see {CoverageScan}); the
+      # protection path below reuses both, and `rigor check --coverage`
+      # reuses `precision_report` over the same machinery.
+      def project_environment(configuration)
+        CoverageScan.project_environment(configuration)
+      end
+
+      def scan_one(path, scanner, accumulator, configuration)
+        CoverageScan.scan_into(path, scanner, accumulator, configuration)
       end
 
       def determine_exit(report, options)

data/lib/rigor/cli/coverage_scan.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require "prism"
+
+require_relative "../configuration"
+require_relative "../environment"
+require_relative "../inference/precision_scanner"
+require_relative "../scope"
+require_relative "coverage_report"
+
+module Rigor
+  class CLI
+    # Shared type-precision scan behind both `rigor coverage` (the
+    # dedicated command) and `rigor check --coverage` (the in-run
+    # coverage block). Walks each file's AST, types every expression via
+    # `Scope#type_of`, and accumulates the precision-tier breakdown into a
+    # `CoverageReport`. Extracted so the two surfaces stay byte-identical
+    # on the same file set.
+    module CoverageScan
+      module_function
+
+      # @param files [Array<String>] explicit `.rb` file paths to scan.
+      # @param configuration [Rigor::Configuration]
+      # @return [Rigor::CLI::CoverageReport]
+      def precision_report(files:, configuration:)
+        scope = Scope.empty(environment: project_environment(configuration))
+        scanner = Inference::PrecisionScanner.new(scope: scope)
+        accumulator = CoverageAccumulator.new
+        files.each { |path| scan_into(path, scanner, accumulator, configuration) }
+        accumulator.to_report(files, {})
+      end
+
+      def project_environment(configuration)
+        Environment.for_project(
+          libraries: configuration.libraries,
+          signature_paths: configuration.signature_paths
+        )
+      end
+
+      # Parses one file and feeds the scan result (or a parse-error
+      # record) into `accumulator`. `scanner` / `accumulator` are a
+      # matched pair — a `PrecisionScanner` + `CoverageAccumulator`, or a
+      # `ProtectionScanner` + `ProtectionAccumulator` — both of which
+      # respond to `scan(node)` and `absorb(path, result)`.
+      def scan_into(path, scanner, accumulator, configuration)
+        source = File.read(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
+        end
+
+        accumulator.absorb(path, scanner.scan(parse_result.value))
+      end
+    end
+  end
+end

data/lib/rigor/cli/explain_command.rb

@@ -95,6 +95,7 @@ module Rigor
         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("Documentation: #{entry.documentation_url}")
         @out.puts("Since: rigor #{entry.since}")
       end
 
@@ -109,6 +110,7 @@ module Rigor
         @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("Evidence tier: #{entry.evidence_tier || 'n/a (informational)'}")
         @out.puts("")
       end
 

data/lib/rigor/cli/lsp_command.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "command"
+require_relative "options"
 
 require "optionparser"
 
@@ -8,11 +9,8 @@ module Rigor
   class CLI
     # Executes the `rigor lsp` command.
     #
+    # Starts a long-running LSP server over stdio (JSON-RPC).
     # See `docs/design/20260517-language-server.md` for the design.
-    # Slice 1 (this commit) ships the CLI subcommand entry point.
-    # The actual stdio JSON-RPC reader / writer is queued for slice 2;
-    # invoking `rigor lsp` at slice 1 returns immediately after
-    # validating the transport flag.
     class LspCommand < Command
       USAGE = "Usage: rigor lsp [options]"
 
@@ -109,9 +107,7 @@ module Rigor
           opts.on("--log=PATH", "Write LSP wire log + server debug to PATH (default: stderr)") do |value|
             options[:log] = value
           end
-          opts.on("--config=PATH", "Path to the Rigor configuration file") do |value|
-            options[:config] = value
-          end
+          Options.add_config(opts, options)
         end
         parser.parse!(@argv)
         options

data/lib/rigor/cli/mutation_protection_renderer.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Rigor
+  class CLI
+    # Renders a {MutationProtectionReport} (ADR-63 Tier 2) as text or JSON. The
+    # text form leads with the effectiveness ratio (caught breakages), then the
+    # breakages Rigor missed ("add a type here"), then the least-effective files.
+    # The framing is always *where to add a type*, never "your code is broken".
+    class MutationProtectionRenderer
+      TOP_CALLS = 15
+      TOP_FILES = 10
+
+      def initialize(out:)
+        @out = out
+      end
+
+      def render(report, format:)
+        format == "json" ? render_json(report) : render_text(report)
+      end
+
+      private
+
+      def render_json(report)
+        @out.puts(JSON.pretty_generate(report.to_h))
+      end
+
+      def render_text(report)
+        pct = (report.ratio * 100).round(1)
+        @out.puts "Type-protection effectiveness (Tier 2 — mutation kill rate)"
+        @out.puts "  caught breakages: #{report.total_killed} / #{report.grand_total}  (#{pct}%)"
+        @out.puts "  (effectiveness = when a type-visible bug was introduced, Rigor caught it)"
+        render_missed(report)
+        render_files(report)
+      end
+
+      def render_missed(report)
+        missed = report.missed
+        return if missed.empty?
+
+        @out.puts "\nAdd a type here — breakages Rigor missed (a wrong call that stayed silent):"
+        missed.first(TOP_CALLS).each do |call|
+          @out.puts format("  %<count>-5d #%<method>s   e.g. %<sites>s",
+                           count: call.count, method: call.method_name, sites: call.examples.join("  "))
+        end
+        @out.puts "  (#{missed.size - TOP_CALLS} more)" if missed.size > TOP_CALLS
+      end
+
+      def render_files(report)
+        worst = report.files.reject { |f| f.survived.zero? }.sort_by(&:ratio).first(TOP_FILES)
+        return if worst.empty?
+
+        @out.puts "\nLeast-effective files:"
+        worst.each do |file|
+          total = file.killed + file.survived
+          @out.puts format("  %<pct>5.1f%%  %<path>s  (%<n>d/%<total>d breakages caught)",
+                           pct: file.ratio * 100, path: file.path, n: file.killed, total: total)
+        end
+      end
+    end
+  end
+end