rigortype 0.2.0 → 0.2.2

data/lib/rigor/cli/coverage_command.rb

@@ -3,6 +3,7 @@
 require "English"
 require "optionparser"
 require "prism"
+require "shellwords"
 
 require_relative "../configuration"
 require_relative "options"
@@ -11,6 +12,7 @@ require_relative "../inference/precision_scanner"
 require_relative "../inference/protection_scanner"
 require_relative "../inference/parameter_inference_collector"
 require_relative "../protection/mutation_scanner"
+require_relative "../protection/test_suite_oracle"
 require_relative "../language_server/project_context"
 require_relative "../scope"
 require_relative "coverage_report"
@@ -20,6 +22,9 @@ require_relative "protection_report"
 require_relative "protection_renderer"
 require_relative "mutation_protection_report"
 require_relative "mutation_protection_renderer"
+require_relative "fused_protection_report"
+require_relative "fused_protection_renderer"
+require_relative "coverage_mutation"
 require_relative "command"
 
 module Rigor
@@ -38,12 +43,20 @@ module Rigor
     #   1  — precision ratio < threshold, or parse errors encountered
     #   64 — usage error
     class CoverageCommand < Command
+      include CoverageMutation
+
       USAGE = "Usage: rigor coverage [options] PATH..."
 
+      # ADR-70 — the default test runner hook for `--with-tests`. The
+      # conventional Ruby test task; override with `--test-command`.
+      DEFAULT_TEST_COMMAND = %w[bundle exec rake].freeze
+
       # @return [Integer] CLI exit status.
       def run
         options = parse_options
         return mutation_misuse_error if options[:mutation] && !options[:protection]
+        return with_tests_misuse_error if options[:with_tests] && !options[:mutation]
+        return include_dynamic_misuse_error if options[:include_dynamic] && !options[:with_tests]
         return run_mutation_protection(options) if options[:mutation]
 
         paths = collect_paths(@argv, command_name: "coverage")
@@ -60,36 +73,69 @@ module Rigor
       private
 
       def parse_options
-        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 }
-          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 the precision (or, with --protection, protection/effectiveness) ratio is below RATIO (0.0–1.0)"
-          ) { |v| options[:threshold] = v }
-        end.parse!(@argv)
-
+        options = { format: "text", threshold: nil, config: nil, protection: false, mutation: false,
+                    with_tests: false, test_command: DEFAULT_TEST_COMMAND, include_dynamic: false,
+                    limit: nil, seed: 1 }
+        OptionParser.new { |opts| define_options(opts, options) }.parse!(@argv)
         options
       end
 
+      def define_options(opts, options)
+        opts.banner = USAGE
+        opts.on("--format=FORMAT", "Output format: text or json") { |v| options[:format] = v }
+        Options.add_config(opts, options)
+        opts.on("--protection", "Report type-protection coverage (ADR-63 Tier 1) instead of type precision") do
+          options[:protection] = true
+        end
+        define_mutation_options(opts, options)
+        opts.on("--threshold=RATIO", Float, "Exit 1 when the precision (or, with --protection, " \
+                                            "protection/effectiveness) ratio is below RATIO (0.0–1.0)") do |v|
+          options[:threshold] = v
+        end
+      end
+
+      def define_mutation_options(opts, options)
+        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.") do
+          options[:mutation] = true
+        end
+        opts.on("--with-tests", "With --mutation: also measure dynamic (test-suite) protection (ADR-70). " \
+                                "Runs --test-command against each type-survivor; reports the fused map.") do
+          options[:with_tests] = true
+        end
+        opts.on("--test-command=CMD", "The test runner hook for --with-tests " \
+                                      "(default: #{DEFAULT_TEST_COMMAND.join(' ')})") do |v|
+          options[:test_command] = Shellwords.split(v)
+        end
+        opts.on("--include-dynamic", "With --with-tests: also mutate Dynamic-receiver (untyped) sites, where a " \
+                                     "test is the only protection (ADR-69 Seam 2). Completes the map, runs more.") do
+          options[:include_dynamic] = true
+        end
+        opts.on("--limit=N", Integer,
+                "Sample at most N mutations/file under --mutation (caps cost; ratios become estimates)") do |v|
+          options[:limit] = v
+        end
+        opts.on("--seed=N", Integer, "RNG seed for --limit sampling (default 1)") { |v| options[:seed] = v }
+      end
+
       def mutation_misuse_error
         @err.puts("coverage: --mutation requires --protection")
         @err.puts(USAGE)
         CLI::EXIT_USAGE
       end
 
+      def with_tests_misuse_error
+        @err.puts("coverage: --with-tests requires --mutation (and --protection)")
+        @err.puts(USAGE)
+        CLI::EXIT_USAGE
+      end
+
+      def include_dynamic_misuse_error
+        @err.puts("coverage: --include-dynamic requires --with-tests (a Dynamic site's only protection is a test)")
+        @err.puts(USAGE)
+        CLI::EXIT_USAGE
+      end
+
       def run_protection(paths, options)
         report = scan_protection(paths, options)
         ProtectionRenderer.new(out: @out).render(report, format: options.fetch(:format))
@@ -133,77 +179,6 @@ module Rigor
         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?
-          accumulator.record_parse_error(path, parse_result.errors)
-          return
-        end
-
-        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)

data/lib/rigor/cli/coverage_mutation.rb

@@ -0,0 +1,149 @@
+# frozen_string_literal: true
+
+require "English"
+require "prism"
+
+module Rigor
+  class CLI
+    # ADR-63 Tier 2 + ADR-70 — the mutation-effectiveness and fused static∪dynamic
+    # protection paths, factored out of {CoverageCommand} to keep that command
+    # focused on dispatch. Mixed in, so each method runs in the command instance
+    # (using `@out` / `@err` / `@argv` / `collect_paths` / `determine_protection_exit`
+    # and the Protection + LanguageServer collaborators the command requires).
+    module CoverageMutation
+      private
+
+      # 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
+
+        note_sampling(options)
+        return run_fused_protection(target_files, options) if options[:with_tests]
+
+        report = scan_mutation_protection(target_files, options)
+        MutationProtectionRenderer.new(out: @out).render(report, format: options.fetch(:format))
+        determine_protection_exit(report, options)
+      end
+
+      # A `--limit` sample makes the report an estimate (per-file ratios over a
+      # random N of the mutations). Say so on stderr — stdout stays clean for JSON.
+      def note_sampling(options)
+        return unless options[:limit]
+
+        @err.puts(
+          "coverage: sampling at most #{options[:limit]} mutations/file " \
+          "(seed #{options[:seed]}); ratios are estimates."
+        )
+      end
+
+      # ADR-70 — the fused static∪dynamic deep dive. The type pass is the ADR-63
+      # Tier 2 warm loop; each type-survivor is then run against the project's
+      # test suite (the runner hook). The suite MUST pass on clean code first, or
+      # "a mutant survived" is meaningless — abort with a clear message if not.
+      def run_fused_protection(paths, options)
+        configuration = Configuration.load(options.fetch(:config))
+        test_oracle = Protection::TestSuiteOracle.new(command: options.fetch(:test_command))
+        return suite_not_green_error(options) unless test_oracle.green?
+
+        context = LanguageServer::ProjectContext.new(configuration: configuration)
+        scanner = Protection::MutationScanner.new(
+          configuration: configuration, environment: context.environment, project_scan: context.project_scan,
+          limit: options[:limit], seed: options[:seed],
+          site_selector: options[:include_dynamic] ? :all : :biteable
+        )
+        accumulator = FusedProtectionAccumulator.new
+        paths.each { |path| scan_fused_one(path, scanner, accumulator, test_oracle, configuration) }
+        report = accumulator.to_report
+        FusedProtectionRenderer.new(out: @out).render(report, format: options.fetch(:format))
+        determine_protection_exit(report, options)
+      end
+
+      def scan_fused_one(path, scanner, accumulator, test_oracle, 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(scanner.scan_file_fused(path, source: source, test_oracle: test_oracle))
+      end
+
+      def suite_not_green_error(options)
+        @err.puts(
+          "coverage: the test suite must pass on clean code to measure test protection " \
+          "(ran: #{options.fetch(:test_command).join(' ')})"
+        )
+        @err.puts(
+          "  the command must exit 0 on a clean tree. A non-zero exit on otherwise-passing " \
+          "tests also trips this — e.g. a SimpleCov coverage floor on a file-scoped run; " \
+          "point --test-command at a plain pass/fail runner."
+        )
+        1
+      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,
+          limit: options[:limit], seed: options[:seed]
+        )
+        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?
+          accumulator.record_parse_error(path, parse_result.errors)
+          return
+        end
+
+        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
+    end
+  end
+end

data/lib/rigor/cli/docs_command.rb

@@ -0,0 +1,248 @@
+# frozen_string_literal: true
+
+require_relative "command"
+
+module Rigor
+  class CLI
+    # `rigor docs` — serve the documentation bundled with the
+    # `rigortype` gem OFFLINE (ADR-74). The skills (`rigor skill <name>`)
+    # already ride in the gem; this is the doc twin, so once Rigor is
+    # installed an agent can read the guidance the SKILL-driven UX routes
+    # to without the network. The canonical web copy is
+    # rigor.typedduck.fail/llms.txt; the gem ships `docs/install.md`,
+    # `docs/llms.txt`, and the full user-facing **manual** and
+    # **handbook** (the drive-Rigor chapters — the contributor-facing
+    # ADR / spec / notes corpus stays web-only).
+    #
+    # Grammar (mirrors `rigor skill`): the positional slot is always a
+    # doc *name*; alternative outputs are flags, so a page named `list`
+    # or `path` can never be shadowed by a verb.
+    #
+    # - `rigor docs`                  — print the bundled `llms.txt` index.
+    # - `rigor docs <name>`           — print a doc page to stdout.
+    # - `rigor docs --path <name>`    — one-line absolute path, for a Read tool.
+    # - `rigor docs --list [<cat>]`   — table of name + path (optionally one category).
+    #
+    # `<name>` resolves a category-qualified path (`handbook/03-narrowing`),
+    # a prefixed basename (`03-narrowing`), or a short name (`narrowing`,
+    # when it is unique across categories).
+    #
+    # The pre-v0.3.0 verb spellings `rigor docs list` / `rigor docs path
+    # <name>` still work but emit a stderr deprecation notice; they are
+    # removed in v0.3.0 (see docs/ROADMAP.md § "Scheduled CLI
+    # deprecations").
+    class DocsCommand < Command
+      USAGE = <<~USAGE
+        Usage: rigor docs [<name>] [--path <name>] [--list [<category>]]
+
+        With no argument, prints the bundled llms.txt offline doc index.
+
+          rigor docs                      Print the offline doc index (llms.txt)
+          rigor docs <name>               Print a doc page to stdout
+          rigor docs --path <name>        Print the absolute path of a doc
+          rigor docs --list [<category>]  List bundled docs (optionally one category)
+
+        Categories: manual, handbook (plus the top-level install guide).
+        A page is addressable by its category-qualified path
+        (`handbook/03-narrowing`), its prefixed name (`03-narrowing`),
+        or its short name (`narrowing`, when unique across categories).
+
+        Examples:
+          rigor docs
+          rigor docs install
+          rigor docs handbook/03-narrowing
+          rigor docs editor-integration
+          rigor docs --path 17-driving-improvement
+          rigor docs --list handbook
+
+        Deprecated (removed in v0.3.0) — use the flags above:
+          rigor docs list           ->  rigor docs --list
+          rigor docs path <name>    ->  rigor docs --path <name>
+      USAGE
+
+      # The bundled docs live at `<gem_root>/docs/`. From
+      # `lib/rigor/cli/docs_command.rb` that is three directories up.
+      DOCS_ROOT = File.expand_path("../../../docs", __dir__)
+      MANUAL_ROOT = File.join(DOCS_ROOT, "manual")
+      HANDBOOK_ROOT = File.join(DOCS_ROOT, "handbook")
+      LLMS_INDEX = File.join(DOCS_ROOT, "llms.txt")
+
+      # The verb subcommands the flags superseded keep working with a
+      # stderr deprecation notice until this version drops them. Each maps
+      # to the canonical advice printed and the flag it rewrites to.
+      LEGACY_VERB_REMOVAL = "v0.3.0"
+      LEGACY_VERBS = {
+        "list" => { old: "list",        advice: "--list",        flag: "--list" },
+        "path" => { old: "path <name>", advice: "--path <name>", flag: "--path" }
+      }.freeze
+
+      # @return [Integer] CLI exit status.
+      def run
+        rewrite_legacy_verb!
+
+        case @argv.first
+        when nil
+          run_index
+        when "-h", "--help", "help"
+          @out.puts(USAGE)
+          0
+        when "--list"
+          @argv.shift
+          run_list(@argv.shift)
+        when "--path"
+          @argv.shift
+          run_path(@argv.shift)
+        when "--print"
+          @argv.shift
+          run_print(@argv.shift)
+        else
+          run_print(@argv.shift)
+        end
+      end
+
+      private
+
+      # Translate a deprecated verb spelling into its flag form, warning
+      # once on stderr, so the dispatch above only handles canonical forms.
+      def rewrite_legacy_verb!
+        spec = LEGACY_VERBS[@argv.first]
+        return unless spec
+
+        @err.puts(
+          "rigor docs: `#{spec.fetch(:old)}` is deprecated and will be removed in " \
+          "#{LEGACY_VERB_REMOVAL}; use `rigor docs #{spec.fetch(:advice)}` instead."
+        )
+        @argv[0] = spec.fetch(:flag)
+      end
+
+      def run_index
+        if File.file?(LLMS_INDEX)
+          @out.write(File.read(LLMS_INDEX))
+          0
+        else
+          run_list(nil)
+        end
+      end
+
+      def run_list(category)
+        docs = discover_docs
+        if category
+          categories = docs.map { |doc| doc.fetch(:category) }.uniq
+          unless categories.include?(category)
+            @err.puts("Unknown category: #{category}")
+            @err.puts("Available categories: #{categories.join(', ')}")
+            return 1
+          end
+          docs = docs.select { |doc| doc.fetch(:category) == category }
+        end
+
+        if docs.empty?
+          @err.puts("No bundled docs found under #{DOCS_ROOT}")
+          return 1
+        end
+
+        width = docs.map { |doc| doc.fetch(:relative).length }.max
+        docs.each do |doc|
+          @out.puts(format("%-#{width}s  %s", doc.fetch(:relative), doc.fetch(:path)))
+        end
+        0
+      end
+
+      def run_print(name)
+        return usage_error("a doc name is required") if name.nil?
+
+        doc = resolve_doc(name)
+        return doc if doc.is_a?(Integer) # error status, already reported
+
+        # ASCII-only provenance header: the doc body is read with the
+        # external encoding (US-ASCII under a C locale), so a UTF-8 header
+        # would set the output buffer to UTF-8 and clash with the body.
+        @out.puts("<!-- rigor docs #{doc.fetch(:name)} (rigortype #{Rigor::VERSION}, offline) -->")
+        @out.puts
+        @out.write(File.read(doc.fetch(:path)))
+        0
+      end
+
+      def run_path(name)
+        return usage_error("`--path` requires a doc name") if name.nil?
+
+        doc = resolve_doc(name)
+        return doc if doc.is_a?(Integer)
+
+        @out.puts(doc.fetch(:path))
+        0
+      end
+
+      # Resolve a query to a single doc. Exact relative-path and
+      # prefixed-basename aliases are unique; a short (prefix-stripped)
+      # name is accepted only when one category owns it.
+      #
+      # @return [Hash, Integer] the doc entry, or an error exit status
+      #   after the error has been written to `@err`.
+      def resolve_doc(query)
+        docs = discover_docs
+
+        exact = docs.find { |doc| doc.fetch(:exact_aliases).include?(query) }
+        return exact if exact
+
+        short = docs.select { |doc| doc.fetch(:short_name) == query }
+        case short.size
+        when 1 then short.first
+        when 0 then name_error(query)
+        else ambiguous_error(query, short)
+        end
+      end
+
+      # Every bundled doc, each carrying the aliases `rigor docs <name>`
+      # accepts and the category used by `--list`. `install.md` sits at
+      # the docs root (category `guide`); the rest are manual / handbook
+      # chapters.
+      def discover_docs
+        paths = [File.join(DOCS_ROOT, "install.md")]
+        paths += Dir.glob(File.join(MANUAL_ROOT, "**", "*.md")) # Dir.glob is already sorted
+        paths += Dir.glob(File.join(HANDBOOK_ROOT, "**", "*.md"))
+        paths.select { |path| File.file?(path) }.map { |path| doc_entry(path) }
+      end
+
+      def doc_entry(path)
+        relative = path.delete_prefix("#{DOCS_ROOT}/").delete_suffix(".md")
+        base = File.basename(path, ".md")
+        short = base.sub(/\A\d+-/, "")
+        segments = relative.split("/")
+        category = segments.size > 1 ? segments.first : "guide"
+        {
+          name: base,
+          relative: relative,
+          path: path,
+          category: category,
+          # Always-unique addresses: the `docs/`-relative path and the
+          # prefixed basename. `handbook/03-narrowing` and `03-narrowing`.
+          exact_aliases: [relative, base].uniq,
+          # The prefix-stripped short name (`narrowing`); ambiguous when
+          # two categories carry the same chapter slug (`plugins`).
+          short_name: short
+        }
+      end
+
+      def name_error(name)
+        @err.puts("Unknown doc: #{name}")
+        @err.puts("Available docs (try `rigor docs --list`):")
+        discover_docs.each { |doc| @err.puts("  #{doc.fetch(:relative)}") }
+        1
+      end
+
+      def ambiguous_error(query, candidates)
+        @err.puts("Ambiguous doc name: #{query}")
+        @err.puts("Matches several docs — qualify with the category path:")
+        candidates.each { |doc| @err.puts("  #{doc.fetch(:relative)}") }
+        1
+      end
+
+      def usage_error(message)
+        @err.puts(message)
+        @err.puts(USAGE)
+        Rigor::CLI::EXIT_USAGE
+      end
+    end
+  end
+end

data/lib/rigor/cli/fused_protection_renderer.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Rigor
+  class CLI
+    # Renders a {FusedProtectionReport} (ADR-70) as text or JSON. The text form
+    # leads with the fused protected ratio (caught by *either* a type or a test),
+    # splits it into the two axes, then lists the unprotected breakages ("add a
+    # type or a test here") and the least-protected files. The framing is always
+    # *where to add protection*, never "your code is broken".
+    class FusedProtectionRenderer
+      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 "Fused protection (static type ∪ dynamic test)"
+        @out.puts "  protected: #{report.protected_total} / #{report.grand_total}  (#{pct}%)"
+        @out.puts "    by type:  #{report.total_type_killed}"
+        @out.puts "    by test:  #{report.total_test_killed}  (type-survivors a test caught)"
+        @out.puts "  unprotected: #{report.total_unprotected}  (neither — add a type or a test)"
+        render_unprotected(report)
+        render_files(report)
+      end
+
+      def render_unprotected(report)
+        unprotected = report.unprotected
+        return if unprotected.empty?
+
+        @out.puts "\nAdd protection here — breakages neither a type nor a test caught:"
+        unprotected.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 "  (#{unprotected.size - TOP_CALLS} more)" if unprotected.size > TOP_CALLS
+      end
+
+      def render_files(report)
+        worst = report.files.reject { |f| f.unprotected.zero? }.sort_by(&:ratio).first(TOP_FILES)
+        return if worst.empty?
+
+        @out.puts "\nLeast-protected files:"
+        worst.each do |file|
+          total = file.type_killed + file.test_killed + file.unprotected
+          protected_n = file.type_killed + file.test_killed
+          @out.puts format("  %<pct>5.1f%%  %<path>s  (%<n>d/%<total>d protected)",
+                           pct: file.ratio * 100, path: file.path, n: protected_n, total: total)
+        end
+      end
+    end
+  end
+end