mutineer 1.5.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.6"
+    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 "========================="
@@ -167,6 +180,8 @@ module Mutineer
           total: @agg.total, killed: killed, survived: survived,
           no_coverage: @agg.no_coverage_count,
           uncapturable: @agg.uncapturable_count,
+          unplaceable: @agg.unplaceable_count,
+          ran_at_load: @agg.ran_at_load_count,
           skipped_invalid: @agg.skipped_invalid_count,
           errored: @agg.errored_count, timeout: @agg.timeout_count,
           ignored: @agg.ignored_count,
@@ -194,6 +209,12 @@ module Mutineer
         # Same shape as no_coverage; additive key.
         uncapturable: @agg.results.select(&:uncapturable?).map { |r| mutant_json(r) }
                           .sort_by { |h| [h[:file], h[:line], h[:operator], h[:id].to_s] },
+        # Additive (1.7): owner-unknown mutants redefine did not run. Not in no_verdict.
+        unplaceable: @agg.results.select(&:unplaceable?).map { |r| mutant_json(r) }
+                         .sort_by { |h| [h[:file], h[:line], h[:operator], h[:id].to_s] },
+        # Additive (1.7, #187): mutants on a line that ran at load. Not in no_verdict.
+        ran_at_load: @agg.results.select(&:ran_at_load?).map { |r| mutant_json(r) }
+                         .sort_by { |h| [h[:file], h[:line], h[:operator], h[:id].to_s] },
         # Every mutant that was attempted and produced no verdict, whatever the
         # reason — the set the --threshold completeness gate counts. Named for the
         # condition rather than one status, because summary.errored means :error
@@ -212,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.
@@ -276,6 +297,7 @@ module Mutineer
         #{summary_html}
         #{per_source_html(per_source)}
         #{survivors_html(survivors)}
+        #{ignored_html}
         #{matrix_html}
         </body>
         </html>
@@ -287,7 +309,8 @@ module Mutineer
       counts = {
         "total" => @agg.total, "killed" => @agg.killed_count,
         "survived" => @agg.survived_count, "no_coverage" => @agg.no_coverage_count,
-        "uncapturable" => @agg.uncapturable_count, "ignored" => @agg.ignored_count,
+        "uncapturable" => @agg.uncapturable_count, "unplaceable" => @agg.unplaceable_count,
+        "ran_at_load" => @agg.ran_at_load_count, "ignored" => @agg.ignored_count,
         "skipped" => @agg.skipped_invalid_count,
         "errored" => @agg.errored_count, "timeout" => @agg.timeout_count
       }
@@ -336,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.
     #
@@ -622,8 +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`, `ignored` and `baseline.new_survivors`.
+    # `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
@@ -690,6 +752,13 @@ 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: 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; " \
+                      "verify with --test-command)", @agg.ran_at_load_count)
       # Equivalent mutants the user suppressed; excluded from the denominator.
       out.puts format("Ignored:      %-6d  (equivalent, suppressed)", @agg.ignored_count)
     end
@@ -702,6 +771,7 @@ module Mutineer
     def score_line(out, err)
       score = @agg.mutation_score
       excluded = "#{@agg.no_coverage_count} no-coverage, #{@agg.uncapturable_count} uncapturable, " \
+                 "#{@agg.unplaceable_count} unplaceable, #{@agg.ran_at_load_count} ran at load, " \
                  "#{@agg.skipped_invalid_count} skipped, " \
                  "#{@agg.errored_count} errored, #{@agg.timeout_count} timeout, " \
                  "#{@agg.ignored_count} ignored excluded"
@@ -748,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

@@ -1,18 +1,38 @@
 # frozen_string_literal: true
 
 module Mutineer
-  # Immutable outcome of running one mutant. Eight distinct states:
+  # Immutable outcome of running one mutant. Ten distinct states:
   #   killed       - a test failed/errored, so the mutation was caught.
   #   survived     - every test passed, so the mutation went undetected.
   #   error        - the child crashed (unhandled exception): exit status 2.
   #   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  - 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.
+  #                  A survivor on such a line, and a line that ran only at
+  #                  load, get this status; a kill stays killed. Excluded from
+  #                  the denominator and from the no-verdict gate, like
+  #                  unplaceable. `--test-command` verifies these mutants.
   #   ignored      - a known-equivalent mutant the user suppressed, via an
   #                  inline `# mutineer:disable-line` comment or a
   #                  `.mutineer.yml` `ignore:` id. A pre-fork classification
@@ -21,9 +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` and
-  # `uncapturable` are pre-fork selection results: both 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
@@ -39,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.
@@ -48,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
 
@@ -89,6 +112,16 @@ module Mutineer
     # @return [Mutineer::Result] uncapturable result.
     def self.uncapturable = new(status: :uncapturable, details: nil, subject: nil, mutation: nil, id: nil)
 
+    # Builds an unplaceable result.
+    #
+    # @return [Mutineer::Result] unplaceable result.
+    def self.unplaceable = new(status: :unplaceable, details: nil, subject: nil, mutation: nil, id: nil)
+
+    # Builds a ran_at_load result.
+    #
+    # @return [Mutineer::Result] ran-at-load result.
+    def self.ran_at_load = new(status: :ran_at_load, details: nil, subject: nil, mutation: nil, id: nil)
+
     # Builds an ignored result.
     #
     # @return [Mutineer::Result] ignored result.
@@ -108,6 +141,10 @@ module Mutineer
     def no_coverage?  = status == :no_coverage
     # @return [Boolean] true when the status is uncapturable.
     def uncapturable? = status == :uncapturable
+    # @return [Boolean] true when the status is unplaceable.
+    def unplaceable?  = status == :unplaceable
+    # @return [Boolean] true when the status is ran_at_load.
+    def ran_at_load?  = status == :ran_at_load
     # @return [Boolean] true when the status is ignored.
     def ignored?      = status == :ignored
 
@@ -130,7 +167,7 @@ module Mutineer
 
   # Aggregates a flat list of Results into counts, the mutation score, and the
   # surviving-mutant list. The score denominator is killed + survived ONLY:
-  # no-coverage, uncapturable, skipped (invalid), errored, timeout, and ignored
+  # no-coverage, uncapturable, unplaceable, ran-at-load, skipped (invalid), errored, timeout, and ignored
   # (equivalent-mutant suppression) are each excluded and surfaced separately,
   # so suppressing every survivor reaches 100%. An empty denominator yields a
   # nil score (rendered "N/A"), never 0.0, distinguishing "no testable mutants"
@@ -154,6 +191,10 @@ module Mutineer
     def no_coverage_count     = count(:no_coverage)
     # @return [Integer] uncapturable count.
     def uncapturable_count    = count(:uncapturable)
+    # @return [Integer] unplaceable count.
+    def unplaceable_count     = count(:unplaceable)
+    # @return [Integer] ran-at-load count.
+    def ran_at_load_count     = count(:ran_at_load)
     # @return [Integer] skipped-invalid count.
     def skipped_invalid_count = count(:skipped)
     # @return [Integer] errored count.