mutineer 1.6.0 → 1.7.0

data/lib/mutineer/redaction.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+require "uri"
+
+module Mutineer
+  # Hides database credentials in text bound for a terminal: an error reply,
+  # a log line, a warning. Rails parses DATABASE_URL itself, so an error about
+  # a malformed one can quote the whole URL.
+  #
+  # Stdlib only: the app-side daemon loads this file without the rest of
+  # mutineer.
+  module Redaction
+    # The password in a `scheme://user:password@host` URL. Greedy up to the last
+    # `@` before an unescaped quote or line end, so a malformed password with a
+    # space, an unescaped `@`, or a quote `inspect` escaped (`\"`) is hidden too.
+    URL_PASSWORD = %r{([a-z][a-z0-9+.\-]*://[^\s:/@"'\\]*):(?:\\.|[^"'\r\n\\])*@}i
+    # What replaces a hidden password.
+    REDACTED = "[REDACTED]"
+
+    module_function
+
+    # Hide the password in any URL, and the DATABASE_URL password wherever it
+    # appears: whole, percent-decoded, `inspect` escaped, or cut short after
+    # its `scheme://user:` prefix.
+    #
+    # @param text [#to_s]
+    # @param env [Hash{String => String}] where DATABASE_URL is read.
+    # @return [String]
+    def text(text, env: ENV)
+      out = text.to_s
+      head, raw = database_url_parts(env["DATABASE_URL"].to_s)
+      secrets = raw ? password_forms(raw) : []
+      # Prefixes first, on the caller's text, so no replacement made here can
+      # be mistaken for part of a password.
+      [head, head&.inspect&.[](1...-1)].compact.uniq.each do |prefix|
+        out = secrets.reduce(out) { |acc, secret| redact_prefixes(acc, prefix, secret) }
+      end
+      out = out.gsub(URL_PASSWORD) { "#{Regexp.last_match(1)}:#{REDACTED}@" }
+      secrets.reduce(out) { |acc, secret| acc.gsub(secret, REDACTED) }
+    end
+
+    # Split DATABASE_URL into its `scheme://user:` head and its raw password.
+    # Read by position, not URI or a pattern, because the URL may be the
+    # malformed one and its password may hold any character: the password runs
+    # from the first `:` after `scheme://` to the last `@`.
+    #
+    # @param url [String]
+    # @return [Array(String, String), nil]
+    def database_url_parts(url)
+      start = url.index("://")
+      at = url.rindex("@")
+      return unless start && at
+
+      colon = url.index(":", start + 3)
+      return unless colon && colon < at
+
+      raw = url[(colon + 1)...at]
+      [url[0..colon], raw] unless raw.empty?
+    end
+
+    # The password as it may appear in a message: raw, percent-decoded, and
+    # each `inspect` escaped. Longest first, so a longer form is replaced
+    # before a form it contains.
+    #
+    # @param raw [String]
+    # @return [Array<String>]
+    def password_forms(raw)
+      decoded = begin
+        URI.decode_www_form_component(raw.gsub("+", "%2B"))
+      rescue ArgumentError
+        raw
+      end
+      [raw, decoded].flat_map { |form| [form, form.inspect[1...-1]] }
+                    .uniq.reject(&:empty?).sort_by { |form| -form.length }
+    end
+
+    # Hide what follows each `head` while it matches the start of `secret`,
+    # for a message that cut the URL short inside the password.
+    #
+    # @param text [String]
+    # @param head [String] the DATABASE_URL `scheme://user:` prefix, raw or
+    #   `inspect` escaped.
+    # @param secret [String]
+    # @return [String]
+    def redact_prefixes(text, head, secret)
+      out = +""
+      pos = 0
+      while (found = text.index(head, pos))
+        start = found + head.length
+        length = 0
+        length += 1 while length < secret.length && text[start + length] == secret[length]
+        out << text[pos...start] << (length.positive? ? REDACTED : "")
+        pos = start + length
+      end
+      out << text[pos..]
+    end
+  end
+end

data/lib/mutineer/reporter.rb

@@ -26,7 +26,7 @@ module Mutineer
     BROKEN_FLOOR = 1
 
     # The JSON report's `schema_version` (see docs/json-schema.md).
-    SCHEMA_VERSION = "1.7"
+    SCHEMA_VERSION = "1.8"
 
     # The warning both matrix renderers give under the redundant tests.
     MATRIX_REDUNDANT_NOTE = "Delete redundant tests one at a time: two of them can be the only killers of one mutant."
@@ -74,11 +74,11 @@ module Mutineer
         out.print rendered
       end
 
+      return warn_errors_without_gate(err) unless threshold&.positive?
+
       # Both ways a run can fail the gate on completeness, said here rather than in
       # the human renderer: --format json is the documented CI path, and a run that
       # exits 1 must say why on every format, not only the one a person reads.
-      return unless threshold&.positive?
-
       if @agg.mutation_score.nil? && broken_nil_score?
         err.puts "[mutineer] nothing could be scored (#{broken_counts_detail}), so the " \
                  "--threshold gate fails. See no_verdict[] in --format json for the cause of each."
@@ -89,6 +89,22 @@ module Mutineer
       end
     end
 
+    # Errors are out of the score, so a run with no --threshold passes however
+    # many mutants errored. Say so, and say what --threshold would enforce.
+    #
+    # @api private
+    # @param err [IO] error stream.
+    # @return [void]
+    def warn_errors_without_gate(err)
+      count = @agg.errored_count
+      return unless count.positive?
+
+      err.puts "[mutineer] #{count} #{count == 1 ? 'mutant' : 'mutants'} errored. Errors are not in the " \
+               "score, so they do not fail a run without a positive --threshold. With one, the run fails " \
+               "when nothing can be scored, or when more than one mutant has no verdict and they exceed " \
+               "#{(BROKEN_SHARE_LIMIT * 100).round}% of those attempted (no_verdict[] in --format json)."
+    end
+
     # Renders the human report.
     #
     # @param out [IO] output stream.
@@ -96,11 +112,8 @@ module Mutineer
     # @param threshold [Float] score threshold.
     # @return [void]
     def human_report(out, err, threshold)
-      if @agg.total.zero?
-        err.puts "No mutations generated — verify target files contain in-scope " \
-                 "operators and are reached by the suite."
-        return
-      end
+      # The CLI explains an empty run for every format (CLI.warn_empty_run).
+      return if @agg.total.zero?
 
       out.puts "Mutineer — Mutation Results"
       out.puts "========================="
@@ -220,7 +233,7 @@ module Mutineer
         # Equivalent mutants the user suppressed: emitted with their stable id so
         # the user can audit what is silenced (and copy ids for survivors they
         # want to add). Excluded from the score; never in `survivors`.
-        ignored: @agg.results.select(&:ignored?).map { |r| mutant_json(r) }
+        ignored: @agg.results.select(&:ignored?).map { |r| ignored_json(r) }
                      .sort_by { |h| [h[:file], h[:line], h[:operator], h[:id].to_s] },
         # Per-source breakdown (additive; baseline consumes it). Sorted by file so
         # output is byte-stable. Reuses AggregateResult via by_source.
@@ -284,6 +297,7 @@ module Mutineer
         #{summary_html}
         #{per_source_html(per_source)}
         #{survivors_html(survivors)}
+        #{ignored_html}
         #{matrix_html}
         </body>
         </html>
@@ -345,6 +359,28 @@ module Mutineer
       "<h2>Surviving Mutants</h2>\n#{cards}"
     end
 
+    # Ignored mutants, each with its id and its reason when the user gave one.
+    #
+    # @api private
+    # @return [String] HTML, or "" when none were ignored.
+    def ignored_html
+      rows = @agg.results.select(&:ignored?).map { |r| ignored_json(r) }
+                 .sort_by { |h| [h[:file], h[:line], h[:operator], h[:id].to_s] }
+      return "" if rows.empty?
+
+      cards = rows.map do |row|
+        reason = row[:reason] ? "<div class=\"meta\">#{esc(row[:reason])}</div>" : ""
+        <<~CARD.chomp
+          <div class="survivor">
+          <h3>#{esc(row[:subject])}</h3>
+          <div class="meta">#{esc(row[:file])}:#{row[:line]} &middot; #{esc(row[:operator])} &middot; <span class="id">#{esc(row[:id])}</span></div>
+          #{reason}
+          </div>
+        CARD
+      end.join("\n")
+      "<h2>Ignored mutants</h2>\n#{cards}"
+    end
+
     # The kill-matrix section of the HTML report: the counts, then the blind and
     # redundant tests. Empty without --matrix.
     #
@@ -631,9 +667,25 @@ module Mutineer
       lines.size == 1 ? start_line.to_s : "#{start_line},#{lines.size}"
     end
 
+    # One ignored mutant. `reason` is present only when the user wrote one.
+    #
+    # @api private
+    # @param result [Mutineer::Result] an ignored result.
+    # @return [Hash]
+    def ignored_json(result)
+      row = mutant_json(result)
+      text = result.reason
+      row[:reason] = text if text.is_a?(String) && !text.strip.empty?
+      row
+    end
+
     # The fields that name one mutant, for the lists that point at mutants:
     # `no_coverage`, `uncapturable`, `unplaceable`, `ran_at_load`, `ignored` and
     # `baseline.new_survivors`.
+    #
+    # @api private
+    # @param result [Mutineer::Result] the mutant result.
+    # @return [Hash] subject, file, line, operator, token, and id.
     def mutant_json(result)
       m = result.mutation
       file = result.subject.file
@@ -700,8 +752,9 @@ module Mutineer
       out.puts format("Timeout:      %-6d  (over the per-mutant time limit)", @agg.timeout_count)
       # A broken harness, not a coverage gap: report it distinctly from No coverage.
       out.puts format("Uncapturable: %-6d  (tests failed to run)", @agg.uncapturable_count)
-      # Not broken: redefine has no named class to load these onto; reload runs them.
-      out.puts format("Unplaceable:  %-6d  (class cannot be named statically; --strategy reload runs these)",
+      # Not broken: the strategy cannot load these where the tests call them (no
+      # named class under redefine, or a concern's `included` or `prepended` block).
+      out.puts format("Unplaceable:  %-6d  (not loadable where the tests call it; verify with --test-command)",
                       @agg.unplaceable_count)
       # Not a verdict: the line ran before the mutant was applied (#187).
       out.puts format("Ran at load:  %-6d  (ran while the app or class loaded; mutineer cannot re-run that; " \
@@ -765,7 +818,8 @@ module Mutineer
     end
 
     # Mutants that were actually run. Deliberately not `total`: no_coverage,
-    # skipped-invalid and ignored mutants were never attempted, so counting them
+    # skipped-invalid and ignored mutants are not counted (a #254 no_coverage
+    # mutant ran its statement's tests but is not a verdict), so counting them
     # would dilute the share and let a broken run slip under the limit.
     #
     # skipped-invalid is excluded from both sides: it means a mutant did not

data/lib/mutineer/result.rb

@@ -8,17 +8,24 @@ module Mutineer
   #   timeout      - the parent SIGKILLed a child that overran its wall clock.
   #   skipped      - the mutated source failed to re-parse (invalid); no fork.
   #   no_coverage  - no test exercises the mutated line; not run, not scored.
+  #                  Also a mutant on a later line of a multi-line statement,
+  #                  in code that runs only sometimes, that the statement's
+  #                  tests ran but did not kill (#254): they may not reach it.
   #   uncapturable - the line's would-be covering test errored during capture,
   #                  so coverage was lost. Excluded from the denominator exactly
   #                  like no_coverage, but reported separately: it signals a
   #                  broken harness (a test that failed to run), not a genuine
   #                  coverage gap.
-  #   unplaceable  - under `--strategy redefine`, the method belongs to a class
-  #                  or module that cannot be named statically, so it has no
-  #                  owner to be loaded onto and is not run. Excluded from the
-  #                  denominator and, unlike uncapturable, from the
-  #                  no-verdict gate: nothing is broken. `--strategy reload`
-  #                  runs these mutants.
+  #   unplaceable  - the strategy cannot load the mutant where the tests call
+  #                  it, so it is not run. Under `--strategy redefine` the
+  #                  method belongs to a class or module that cannot be named
+  #                  statically (for example each class that includes a
+  #                  concern). Under either strategy the method is in a
+  #                  concern's `included` or `prepended` block, which does not
+  #                  run again in a class that already includes it (#256).
+  #                  Excluded from the denominator and, unlike uncapturable,
+  #                  from the no-verdict gate: nothing is broken.
+  #                  `--test-command` runs these mutants.
   #   ran_at_load  - the mutated line ran while the app booted or its class
   #                  loaded. That run happened before the mutant was applied,
   #                  so a test can check a value the original code computed.
@@ -34,10 +41,10 @@ module Mutineer
   #
   # `error` and `skipped` are deliberately distinct: skipped is a pre-fork
   # validity failure (counted separately by the reporter), error is a runtime
-  # crash. Never conflate them via `details` string parsing. `no_coverage`,
-  # `uncapturable` and `unplaceable` are pre-fork results, and `ran_at_load` is
-  # pre-fork or a reclassified survivor: all excluded from the score
-  # denominator.
+  # crash. Never conflate them via `details` string parsing. `uncapturable` and
+  # `unplaceable` are pre-fork results, and `no_coverage` and `ran_at_load` are
+  # pre-fork or a reclassified result (JobPlan.selection_verdict,
+  # JobPlan.load_verdict): all excluded from the score denominator.
   #
   # `subject`, `mutation`, and `id` are nil when the Result is built by
   # Isolation/Runner (which only know the outcome); the orchestrator attaches
@@ -53,8 +60,9 @@ module Mutineer
   # from a fork back to the process that forked it, so both ends always run the
   # same code. Nothing persists a marshaled Result (reports, baselines and the
   # coverage cache are JSON), so a new field needs no Marshal compatibility.
-  Result = Data.define(:status, :details, :subject, :mutation, :id, :kills) do
-    # Every field but `status` defaults to nil.
+  Result = Data.define(:status, :details, :subject, :mutation, :id, :kills, :reason) do
+    # Every field but `status` defaults to nil. `reason` is the text a user
+    # gave for an ignored mutant, from an inline marker or an `ignore:` mapping.
     #
     # @param status [Symbol] the outcome.
     # @param details [String, nil] error or skip details.
@@ -62,7 +70,8 @@ module Mutineer
     # @param mutation [Mutineer::Mutation, nil] the mutation.
     # @param id [String, nil] the stable mutant id.
     # @param kills [Mutineer::Kills, nil] the matrix row of a `--matrix` run.
-    def initialize(status:, details: nil, subject: nil, mutation: nil, id: nil, kills: nil)
+    # @param reason [String, nil] why an ignored mutant was suppressed.
+    def initialize(status:, details: nil, subject: nil, mutation: nil, id: nil, kills: nil, reason: nil)
       super
     end
 

data/lib/mutineer/runner.rb

@@ -16,6 +16,7 @@ require_relative "file_swap"
 require_relative "external_backend"
 require_relative "daemon_backend"
 require_relative "job_plan"
+require_relative "rails_run_env"
 
 module Mutineer
   # Orchestrates one mutation end-to-end: apply it textually, validate the
@@ -43,6 +44,10 @@ module Mutineer
     # @return [Array(Mutineer::AggregateResult, Hash<String, String>, Hash)] aggregate,
     #   source map, and run extras.
     def self.execute(config)
+      # Rails reads PARALLEL_WORKERS when a test helper calls parallelize.
+      # Set it before any boot or child spawn, then put the caller's value back.
+      previous_parallel_workers = ENV["PARALLEL_WORKERS"]
+      RailsRunEnv.pin_process!
       operator_classes = MutatorRegistry.resolve(config.operators || MutatorRegistry::DEFAULT_NAMES)
 
       # External backend: run the suite as a subprocess in the app's own runtime.
@@ -55,6 +60,15 @@ module Mutineer
       # payloads (Prism), so branch before any in-process boot.
       return DaemonBackend.execute(config, operator_classes) if config.daemon
 
+      # Whole-file reload writes .mutineer_mutant*.rb into each source dir (so
+      # require_relative resolves). A SIGKILL'd child skips the tempfile's
+      # ensure-unlink, orphaning it. `ensure` is unreliable vs SIGKILL, so the
+      # PARENT sweeps each source dir before and after the run. Orphans are
+      # impossible after a normal run. The first sweep runs before the boot: a
+      # file an older version left without the dot would stop Zeitwerk (#253).
+      dirs = JobPlan.source_dirs(config)
+      JobPlan.sweep_orphans(dirs)
+
       # Boot mode: require the boot file ONCE so the app env (e.g. Rails) is booted
       # in the parent and inherited by every fork. Do NOT manually require the
       # sources. Under Zeitwerk a manual require of an autoloadable file raises;
@@ -102,6 +116,7 @@ module Mutineer
           boot_path: File.expand_path(config.boot, config.project_root),
           require_paths: config.require_paths, # loaded above; here only for the cache digest
           verbose: config.verbose,
+          coverage_from: config.coverage_from && File.expand_path(config.coverage_from, config.project_root),
           capture_timeout: config.capture_timeout || CoverageMap::DEFAULT_CAPTURE_TIMEOUT
         ).build_via_fork(after_fork: (config.rails ? -> { reconnect_active_record } : nil))
         # Nothing reads Coverage once the map is built (cache hit or not), so
@@ -127,15 +142,7 @@ module Mutineer
       # Collect every (subject, mutation) up front so the pool can fan them out.
       jobs, ignored_results, source_map, extras = JobPlan.collect_jobs(config, operator_classes)
 
-      jobs = JobPlan.filter_since(jobs, source_map, config) if config.since
-
-      # Whole-file reload writes mutineer_mutant*.rb into each source dir (so
-      # require_relative resolves). A SIGKILL'd child skips the tempfile's
-      # ensure-unlink, orphaning it. `ensure` is unreliable vs SIGKILL, so the
-      # PARENT sweeps each source dir before and after the run. Orphans are
-      # impossible after a normal run.
-      dirs = JobPlan.source_dirs(config)
-      JobPlan.sweep_orphans(dirs)
+      jobs, ignored_results, extras[:unscoped_mutants] = JobPlan.scope_since(jobs, ignored_results, source_map, config)
 
       strategy = config.strategy
       # Fail-fast must be serial: a parallel stop_when fires on the first survivor
@@ -165,6 +172,9 @@ module Mutineer
         end
 
       [AggregateResult.new(results + ignored_results), source_map, extras]
+    ensure
+      # A caller that set PARALLEL_WORKERS keeps that value after the run.
+      RailsRunEnv.restore_process!(previous_parallel_workers)
     end
 
     # A `--matrix` error that carries no {Kills} row (the worker crashed, or its
@@ -206,7 +216,7 @@ module Mutineer
         FileSwap.restore_orphans(dirs)
 
         jobs, ignored_results, source_map, extras = JobPlan.collect_jobs(config, operator_classes)
-        jobs = JobPlan.filter_since(jobs, source_map, config) if config.since
+        jobs, ignored_results, extras[:unscoped_mutants] = JobPlan.scope_since(jobs, ignored_results, source_map, config)
 
         # Nothing to mutate: return before the smoke check, which runs the whole
         # --test set to calibrate a timeout no mutant would use (#76).
@@ -316,7 +326,8 @@ module Mutineer
       # narrow identically (score parity).
       kind, payload = JobPlan.coverage_selection(source_file, mutation, subject, source, coverage_map)
       return payload if kind == :verdict
-      return Result.unplaceable if strategy == "redefine" && subject&.owner_unknown
+      # A :maybe mutant that cannot be placed stays no_coverage, as before #254.
+      return kind == :maybe ? Result.no_coverage : Result.unplaceable if subject&.unplaceable?(strategy)
 
       abs_tests = payload
 
@@ -338,7 +349,8 @@ module Mutineer
         end
       end
       result = relative_kills(result, coverage_map.project_root)
-      JobPlan.load_verdict(result, source_file, mutation, subject, source, coverage_map)
+      result = JobPlan.load_verdict(result, source_file, mutation, subject, source, coverage_map)
+      JobPlan.selection_verdict(kind, result)
     end
 
     # Rewrites the test files of a result's {Kills} row relative to the project

data/lib/mutineer/statement_lines.rb

@@ -12,12 +12,17 @@ module Mutineer
     # @param def_node [Prism::DefNode] the method that holds the position.
     # @param source [String] the source text of the file.
     # @param offset [Integer] byte offset of the position.
+    # @param loose [Boolean] also return the lines when the position is in
+    #   code that runs only sometimes when the statement runs (the right side of
+    #   `a && b`, a branch, the body of `x if c`). The tests that ran the
+    #   statement then include every test that ran the position, but may not
+    #   have run it (#254).
     # @return [Array<Integer>] the lines of the statement, with the body of each
     #   heredoc in it. Empty when no statement in the body holds the position.
     #   A first or last line that holds other code is left out, because Ruby
     #   can count that line without the statement: the `def` line counts when
     #   the file loads, and `x if done; y(` counts when `y` does not run.
-    def self.for(def_node, source, offset)
+    def self.for(def_node, source, offset, loose: false)
       return [] unless def_node.body
 
       path = path_to(def_node.body, offset) || []
@@ -25,13 +30,15 @@ module Mutineer
       return [] unless index
 
       statement = path[index]
-      # Code that runs only sometimes inside the statement: the tests that ran
-      # the statement need not have run it.
-      return [] if path[index..].each_cons(2).any? { |parent, child| sometimes?(parent, child) }
-
-      # Ruby counts the line of `x while c` or `x if c` when it checks `c`,
-      # also when `x` never runs. The path is the modifier, its body, statement.
-      return [] if index >= 2 && modifier?(path[index - 2])
+      unless loose
+        # Code that runs only sometimes inside the statement: the tests that ran
+        # the statement need not have run it.
+        return [] if path[index..].each_cons(2).any? { |parent, child| sometimes?(parent, child) }
+
+        # Ruby counts the line of `x while c` or `x if c` when it checks `c`,
+        # also when `x` never runs. The path is the modifier, its body, statement.
+        return [] if index >= 2 && modifier?(path[index - 2])
+      end
 
       location = statement.location
       lines = (location.start_line..last_line(statement)).to_a

data/lib/mutineer/subject.rb

@@ -8,11 +8,17 @@ module Mutineer
   # (`module ::X` inside `Outer` owns into `X`); `lexical` is the class/module
   # chain as written (`["Outer", "::X"]`), which the redefine strategy needs to
   # rebuild the same Module.nesting as a whole-file reload (#145). `block_owner`
-  # is the constant a `Data.define`-style block is assigned to, as written;
-  # `owner_unknown` is true when the class that block builds cannot be named,
-  # so the redefine strategy cannot load a mutant onto it.
+  # is the constant a `Data.define`-style block is assigned to, as written, or
+  # the `ClassMethods` of a concern's `class_methods` block (#252);
+  # `owner_unknown` is true when the class that owns the method cannot be named
+  # (an unassigned builder block, or a concern block whose class or module no
+  # constant names, such as an `included` block that runs in each includer),
+  # so the redefine strategy cannot load a mutant onto it. `hook_block` is true
+  # for a def anywhere inside a concern's `included` or `prepended` block, which
+  # ActiveSupport runs only when a class first includes the concern, so the
+  # reload strategy cannot load a mutant onto it either (#256).
   Subject = Struct.new(:file, :namespace, :name, :singleton, :def_node, :lexical, :block_owner, :owner_unknown,
-                       keyword_init: true) do
+                       :hook_block, keyword_init: true) do
     # Returns the fully-qualified subject name.
     #
     # @return [String] namespaced method name like `Billing::Invoice#total`.
@@ -28,6 +34,18 @@ module Mutineer
       lexical || namespace
     end
 
+    # True when the strategy cannot load a mutant of this method where the tests
+    # call it, so the mutant is not run. Redefine needs a named owner. Reload
+    # loads the whole file again, which redefines everything except what a
+    # concern's `included` or `prepended` block defines: that block does not run
+    # again in a class that already includes the concern.
+    #
+    # @param strategy [String] `"reload"` or `"redefine"`.
+    # @return [Boolean]
+    def unplaceable?(strategy)
+      strategy == "redefine" ? owner_unknown == true : hook_block == true
+    end
+
     # Returns the body location for the subject, if any.
     #
     # @return [Prism::Location, nil] body location or nil for empty methods.

data/lib/mutineer/test_runners/rspec.rb

@@ -12,7 +12,8 @@ module Mutineer
     # Child-process-only RSpec runner.
     #
     # Mirrors MinitestIntegration's contract: run the given spec files and
-    # return 0 (all passed) or 1 (any failure).
+    # return 0 (all passed), 1 (an example failed) or 2 (only an error
+    # outside examples, such as a spec file that raised while loading).
     module RSpec
       # Runs the given RSpec files.
       #
@@ -21,7 +22,7 @@ module Mutineer
       #   first failing example (RSpec `--fail-fast`).
       # @param record_to [IO, nil] a `--matrix` run: send each example's outcome
       #   to this channel (see {KillFormatter}) and run every example.
-      # @return [Integer] 0 on success, 1 on failure.
+      # @return [Integer] 0 on success, else {.failure_code}.
       # @raise [ArgumentError] when both options are given: a matrix run never stops.
       def self.run(spec_files, stop_at_first_failure: false, record_to: nil)
         if stop_at_first_failure && record_to
@@ -56,11 +57,22 @@ module Mutineer
         # early, so `end` needs a reported outcome for every planned example.
         KillChannel.write_end(record_to) if record_to && KillFormatter.last&.saw_every_example?
 
-        status.zero? ? 0 : 1
+        status.zero? ? 0 : failure_code
       ensure
         FileOrder.rank = nil
       end
 
+      # The exit status of a failed run: 2 when no example failed and RSpec
+      # recorded an error outside examples, else 1.
+      #
+      # @api private
+      # @return [Integer] 1 or 2.
+      def self.failure_code
+        world = ::RSpec.world
+        outside_examples = world.respond_to?(:non_example_failure) && world.non_example_failure
+        outside_examples && ::RSpec.configuration.reporter.failed_examples.empty? ? 2 : 1
+      end
+
       # Runs the top-level example groups in the order of `spec_files` (#203),
       # after RSpec's own ordering, which then decides the order within a file.
       #

data/lib/mutineer/test_runners.rb

@@ -7,8 +7,9 @@ module Mutineer
   # Picks the test-framework runner.
   #
   # Each runner responds to
-  # `.run(files, stop_at_first_failure: false, record_to: nil) -> 0/1`
-  # (0 = all passed, 1 = any failure) and is called only inside a forked child.
+  # `.run(files, stop_at_first_failure: false, record_to: nil) -> 0/1/2`
+  # (0 = all passed, 1 = any failure, 2 = only an error outside tests, which
+  # the RSpec runner reports) and is called only inside a forked child.
   # Only the mutant path passes `stop_at_first_failure: true`; a `--matrix`
   # mutant run passes `record_to:` instead (a {KillChannel} pipe) and runs every
   # test. The fork boundary silences stdout (see ChildStdout); the runners do not.

data/lib/mutineer/triage.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+require "json"
+require "optparse"
+require "yaml"
+
+module Mutineer
+  # Prints `.mutineer.yml` `ignore:` entries for survivors in a JSON report.
+  # The command writes to stdout and does not edit files. The user pastes the
+  # lines under `ignore:`.
+  module Triage
+    # Usage line for a bad invocation.
+    USAGE = "Usage: mutineer triage REPORT.json --reason TEXT (--id ID ... | --all)"
+
+    # Reads argv, prints the entries, and returns the process exit code.
+    # 0 is success. 2 is a usage error.
+    #
+    # @param argv [Array<String>] arguments after the `triage` command.
+    # @param out [IO] where the entries go.
+    # @param err [IO] where usage errors go.
+    # @return [Integer] 0 or 2.
+    def self.run(argv, out: $stdout, err: $stderr)
+      reason = nil
+      ids = []
+      all = false
+      parser = OptionParser.new do |o|
+        o.banner = USAGE
+        o.on("--reason TEXT") { |text| reason = text }
+        o.on("--id ID") { |id| ids << id }
+        o.on("--all") { all = true }
+      end
+      begin
+        parser.parse!(argv)
+      rescue OptionParser::InvalidOption, OptionParser::MissingArgument => e
+        err.puts "mutineer: #{e.message}"
+        return 2
+      end
+
+      report = argv.shift
+      if argv.any?
+        err.puts "mutineer: triage takes one report file"
+        return 2
+      end
+      if report.nil? || report.empty?
+        err.puts "mutineer: triage requires a JSON report file"
+        return 2
+      end
+      text = reason.to_s.strip
+      if reason.nil? || text.empty?
+        err.puts "mutineer: triage requires --reason TEXT"
+        return 2
+      end
+      if all && !ids.empty?
+        err.puts "mutineer: triage takes --id or --all, not both"
+        return 2
+      end
+      if !all && ids.empty?
+        err.puts "mutineer: triage requires --id ID or --all"
+        return 2
+      end
+
+      survivors = survivor_ids(report, err)
+      return 2 if survivors.nil?
+
+      chosen = all ? survivors : ids
+      missing = chosen.reject { |id| survivors.include?(id) }
+      unless missing.empty?
+        err.puts "mutineer: triage id is not a survivor: #{missing.join(', ')}"
+        return 2
+      end
+
+      entries = chosen.uniq.map { |id| { "id" => id, "reason" => text } }
+      if entries.empty?
+        err.puts "mutineer: triage has nothing to paste under ignore:"
+        return 0
+      end
+
+      body = YAML.dump(entries).sub(/\A---\n/, "")
+      out.write(body.end_with?("\n") ? body : "#{body}\n")
+      0
+    end
+
+    # Survivor ids from a JSON report, in report order. Nil when the file
+    # cannot be used, after a message on `err`.
+    #
+    # @param path [String] report path.
+    # @param err [IO] usage errors.
+    # @return [Array<String>, nil]
+    def self.survivor_ids(path, err)
+      unless File.file?(path)
+        err.puts "mutineer: triage report not found: #{path}"
+        return nil
+      end
+
+      doc = JSON.parse(File.read(path))
+      rows = doc.is_a?(Hash) ? doc["survivors"] : nil
+      unless rows.is_a?(Array)
+        err.puts "mutineer: triage report has no survivors list"
+        return nil
+      end
+
+      rows.filter_map { |row| row["id"] if row.is_a?(Hash) && row["id"].is_a?(String) }
+    rescue JSON::ParserError => e
+      err.puts "mutineer: triage report is not JSON: #{e.message}"
+      nil
+    rescue SystemCallError
+      err.puts "mutineer: triage report cannot be read: #{path}"
+      nil
+    end
+  end
+end