Class: Mutineer::Reporter

Inherits:
Object
  • Object
show all
Defined in:
lib/mutineer/reporter.rb

Overview

Renders an AggregateResult: the summary block, mutation score, and per-file survivor diffs. Stream discipline: the report goes to out (stdout), diagnostics/warnings go to err (stderr), so mutineer ... > report.txt captures only the report.

source_map is { file_path => raw source string }, used to extract the containing source line for each survivor diff.

Constant Summary collapse

BROKEN_SHARE_LIMIT =

Share of attempted mutants that may produce no verdict before --threshold stops trusting the score. A handful of flaky mutants in a large run is noise; a mostly-broken run is not a score. Deliberately not a flag: no one has needed a different number yet.

0.10
BROKEN_FLOOR =

A share alone gives a small run no tolerance at all: on a --since PR that yields 8 mutants, one timeout is 12.5%. README recommends exactly that workflow, so one bad mutant never fails the gate on its own, at any size.

1
UNRUN_SHARE_LIMIT =

Share of the mutants a run tried to score that may go unrun (unplaceable, skipped invalid, or unpaired) before stderr warns. A warning only: it never changes the exit code. BROKEN_FLOOR also applies, so one unrun mutant never warns. --fail-fast leaves unpaired mutants out of this share. Measured on Fizzy at f220e4832 (#349): unplaceable plus skipped invalid were 0.12% with the default operators and at most 2.8% with all 21, so 10% stays. With its unpaired mutants the share was 15.2%. That warning is correct.

0.10
SCHEMA_VERSION =

The JSON report's schema_version (see docs/json-schema.md).

"1.10"
UNPAIRED_SHARE_HINT =

The unrun-share hint for mutants in sources with no paired test. The CLI keeps a shorter copy for the empty-run message.

"See unpaired_sources[] in --format json. To run them, add a test " \
"at the conventional path, or run those sources in a separate command with --test."
MATRIX_REDUNDANT_NOTE =

The warning both matrix renderers give under the redundant tests.

"Delete redundant tests one at a time: two of them can be the only killers of one mutant."
MATRIX_LIST_LIMIT =

How many blind or redundant tests the human report lists before it points to --format json for the rest.

20

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(aggregate, source_map, matrix: nil, unpaired: {}, fail_fast: false) ⇒ Reporter

Returns a new instance of Reporter.

Parameters:

  • aggregate (Mutineer::AggregateResult) —

    the run's results.

  • source_map (Hash{String => String}) —

    source file path => source text.

  • matrix (Mutineer::KillMatrix, nil) (defaults to: nil) —

    the kill matrix of a --matrix run; nil leaves every format exactly as it is without the flag.

  • unpaired (Hash{String => Integer, nil}) (defaults to: {}) —

    file => mutant count for sources pairing skipped. nil means the count failed. Default is empty.

  • fail_fast (Boolean) (defaults to: false) —

    when true, unpaired mutants stay out of the unrun share and the human scope percentage.



61
62
63
64
65
66
67
68
# File 'lib/mutineer/reporter.rb', line 61

def initialize(aggregate, source_map, matrix: nil, unpaired: {}, fail_fast: false)
  @agg = aggregate
  @source_map = source_map
  @matrix = matrix
  @unpaired = unpaired
  @fail_fast = fail_fast
  @copies = {}
end

Class Method Details

.copies_for(copies, ids = nil) ⇒ Hash{String => Array<String>}

The copy lists for ids, or every list when ids is nil.

Parameters:

  • copies (Hash, nil) —

    kept id => dropped ids.

  • ids (Array<String>, nil) (defaults to: nil) —

    kept ids to keep.

Returns:

  • (Hash{String => Array<String>})


1024
1025
1026
1027
1028
1029
1030
# File 'lib/mutineer/reporter.rb', line 1024

def self.copies_for(copies, ids = nil)
  map = copies || {}
  return map if ids.nil?

  wanted = ids.to_set
  map.select { |id, _list| wanted.include?(id) }
end

.dropped_count_for(copies, ids = nil) ⇒ Integer

How many dropped ids copies holds. With ids, only those kept mutants.

Parameters:

  • copies (Hash, nil) —

    kept id => dropped ids.

  • ids (Array<String>, nil) (defaults to: nil) —

    kept ids to count; nil counts every list.

Returns:

  • (Integer)


1037
1038
1039
# File 'lib/mutineer/reporter.rb', line 1037

def self.dropped_count_for(copies, ids = nil)
  copies_for(copies, ids).each_value.sum { |list| Array(list).size }
end

.dry_run_json(jobs, source_map, declined: {}, skipped_invalid: 0, ignored: 0, unmatched_ignores: [], copies: {}) ⇒ String

JSON for --dry-run --format json: every valid candidate with its stable id, plus summary totals. Ids match a later real run of the same JobPlan. Callers partition with Mutation#valid? once and pass only valid jobs; this method does not re-validate.

Parameters:

  • jobs (Array<Array>) —

    valid (subject, mutation, id) triples from JobPlan.collect_jobs (after JobPlan.scope_since).

  • source_map (Hash{String => String}) —

    source file path => source text.

  • declined (Hash{String => Integer}) (defaults to: {}) —

    operator name => declined count.

  • skipped_invalid (Integer) (defaults to: 0) —

    candidates that did not re-parse.

  • ignored (Integer) (defaults to: 0) —

    suppressed candidates.

  • unmatched_ignores (Array<String>) (defaults to: []) —

    ignore: ids that matched no mutant (#377), the same list a real run records.

  • copies (Hash{String => Array<String>}) (defaults to: {}) —

    kept id => dropped repeat ids (#374). Each listed mutant gains copies when it has any. summary.dropped counts every id in copies, including a repeat of an ignored mutant, which this document does not list.

Returns:

  • (String) —

    JSON text.



902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
# File 'lib/mutineer/reporter.rb', line 902

def self.dry_run_json(jobs, source_map, declined: {}, skipped_invalid: 0, ignored: 0,
                      unmatched_ignores: [], copies: {})
  reporter = new(AggregateResult.new([]), source_map)
  reporter.send(:apply_copies, copies)
  by_operator = Hash.new(0)
  mutants = jobs.map do |subject, mutation, id|
    by_operator[mutation.operator.to_s] += 1
    reporter.__send__(:lean_mutant_json, subject, mutation, id)
  end
  mutants.sort_by! { |h| [h[:file].to_s, h[:line].to_i, h[:operator].to_s, h[:id].to_s] }
  doc = {
    schema_version: SCHEMA_VERSION,
    summary: {
      # Same marker as a completed report: absent means the old id format.
      id_format: 2,
      total: mutants.size,
      skipped_invalid: skipped_invalid,
      ignored: ignored,
      # Same list as a completed report (#377). Absent means an older dry run.
      unmatched_ignores: unmatched_ignores,
      dropped: dropped_count_for(copies),
      declined: declined.values.sum,
      declined_by_operator: declined,
      by_operator: by_operator.sort.to_h
    },
    mutants: mutants
  }
  "#{JSON.generate(reporter.__send__(:json_safe, doc))}\n"
end

Instance Method Details

#apply_copies(copies) ⇒ void (private)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

This method returns an undefined value.

Stores the copy map for a reporter built outside #report, such as the dry-run document.

Parameters:

  • copies (Hash, nil) —

    kept id => dropped ids.



1001
1002
1003
# File 'lib/mutineer/reporter.rb', line 1001

def apply_copies(copies)
  @copies = copies || {}
end

#attach_copies(row, id) ⇒ Hash (private)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Adds copies when this mutant has dropped repeats (#374). Absent when it has none, so a report with no repeats keeps the previous keys.

Parameters:

  • row (Hash) —

    one mutant's JSON object.

  • id (String, nil) —

    the kept mutant's id.

Returns:

  • (Hash) —

    row.



989
990
991
992
993
# File 'lib/mutineer/reporter.rb', line 989

def attach_copies(row, id)
  list = @copies[id] if id
  row[:copies] = list if list&.any?
  row
end

#attempted_count ⇒ Integer (private)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Mutants that were actually run. Deliberately not total: no_coverage, 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 re-parse and was correctly never run, which is a validity outcome rather than a broken harness. Its own signal is the unrun-share warning (#warn_unrun_share), together with unplaceable.

Returns:

  • (Integer) —

    killed + survived + no-verdict.



1165
1166
1167
# File 'lib/mutineer/reporter.rb', line 1165

def attempted_count
  @agg.killed_count + @agg.survived_count + no_verdict_count
end

#baseline_json(delta) ⇒ Object (private)

The same delta facts the human report prints, for dashboards. new_survivors reuse the mutant_json shape (subject/file/line/operator/token/id) and sort byte-stably so output does not depend on --jobs finish order.



728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
# File 'lib/mutineer/reporter.rb', line 728

def baseline_json(delta)
  {
    regressed: delta.regressed,
    score_before: delta.score_before,
    score_after: delta.score_after,
    score_dropped: delta.score_drop,
    # Additive: false when the score-drop check was skipped (a nil score or
    # a diff-scoped side), so a consumer knows not to render the two scores
    # as a comparison.
    score_comparable: delta.score_comparable,
    new_survivors: delta.new_survivors.map { |r| mutant_json(r) }
                        .sort_by { |h| [h[:file], h[:line], h[:operator], h[:id].to_s] },
    fixed_survivors: delta.fixed_survivors.map do |h|
      { subject: h["subject"], file: h["file"], line: h["line"],
        operator: h["operator"], id: h["id"] }
    end.sort_by { |h| [h[:file].to_s, h[:line].to_i, h[:operator].to_s] }
  }
end

#baseline_section(out, delta) ⇒ Object (private)

The --baseline delta, appended after the normal report. Names every NEW survivor (subject (file:line) operator) and the score delta when it dropped, then a one-line REGRESSION/OK verdict so CI logs show which gate fired.



1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
# File 'lib/mutineer/reporter.rb', line 1323

def baseline_section(out, delta)
  out.puts
  out.puts "Baseline comparison"
  out.puts "-------------------"
  out.puts "killed #{@agg.killed_count}, #{delta.new_survivors.size} new survivors vs baseline"
  delta.new_survivors
       .sort_by { |r| [r.subject.file, *tie_key(r)] }
       .each do |r|
    file = r.subject.file
    source = source_for(file)
    line, = diff_for(r.mutation, source)
    out.puts "  + #{printable(r.subject.qualified_name)} (#{printable(file)}:#{line}) #{r.mutation.operator}"
  end
  out.puts "score dropped #{delta.score_before}% -> #{delta.score_after}%" if delta.score_drop
  # An OK verdict must not imply a check that never ran: say when the score
  # comparison was skipped (a diff-scoped side or a nil score).
  out.puts "score-drop check skipped (scores not comparable)" unless delta.score_comparable
  out.puts(delta.regressed ? "REGRESSION vs baseline" : "OK: no regression vs baseline")
end

#broken_counts_detail ⇒ String (private)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Human-readable counts of the states that produced no verdict. Used by both the nil-score message and the completeness gate, so they agree.

Returns:

  • (String)


1291
1292
1293
1294
1295
1296
1297
# File 'lib/mutineer/reporter.rb', line 1291

def broken_counts_detail
  parts = []
  parts << "#{@agg.errored_count} errored" if @agg.errored_count.positive?
  parts << "#{@agg.timeout_count} timeout" if @agg.timeout_count.positive?
  parts << "#{@agg.uncapturable_count} uncapturable" if @agg.uncapturable_count.positive?
  parts.join(", ")
end

#broken_nil_score? ⇒ Boolean (private)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

True when nil score is due to errors/timeouts/uncapturable (gate must fail).

Returns:

  • (Boolean)


1128
1129
1130
1131
# File 'lib/mutineer/reporter.rb', line 1128

def broken_nil_score?
  @agg.total.positive? &&
    (@agg.errored_count + @agg.timeout_count + @agg.uncapturable_count).positive?
end

#broken_share_exceeded? ⇒ Boolean (private)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Mutants that were attempted but produced no verdict, over everything attempted. Above the limit the score describes too small a slice of the run to gate on. A few flaky mutants in a large run stay under it.

Returns:

  • (Boolean) —

    true when too much of the run failed to produce a verdict.



1139
1140
1141
1142
1143
# File 'lib/mutineer/reporter.rb', line 1139

def broken_share_exceeded?
  attempted = attempted_count
  attempted.positive? && no_verdict_count > BROKEN_FLOOR &&
    no_verdict_count > attempted * BROKEN_SHARE_LIMIT
end

#copies_html(copies) ⇒ String (private)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

The HTML line of dropped-copy ids, or "" when there are none.

Parameters:

  • copies (Array<String>, nil)

Returns:

  • (String)


1046
1047
1048
1049
1050
1051
# File 'lib/mutineer/reporter.rb', line 1046

def copies_html(copies)
  return "" if copies.nil? || copies.empty?

  ids = copies.map { |id| "<span class=\"id\">#{esc(id)}</span>" }.join(", ")
  "<div class=\"meta\">copies #{ids}</div>"
end

#diff_body(sign, lines) ⇒ String (private)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

The - or + lines of one side. A line with no newline is the file's last, so it gets the unified diff's no-newline marker (#106).

Parameters:

  • sign (String) —

    "-" or "+".

  • lines (Array<String>) —

    the side's lines, with their endings.

Returns:

  • (String)


815
816
817
# File 'lib/mutineer/reporter.rb', line 815

def diff_body(sign, lines)
  lines.map { |l| l.end_with?("\n") ? "#{sign}#{l}" : "#{sign}#{l}\n\\ No newline at end of file\n" }.join
end

#diff_for(m, source) ⇒ Object (private)

Builds a line-aligned diff for a mutation whose byte range may span several lines (e.g. statement-removal of a multi-line statement). Returns the mutation's 1-based start line, the full original line-block it touches, the spliced mutated block, and a single-line token label for the header.



936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
# File 'lib/mutineer/reporter.rb', line 936

def diff_for(m, source)
  # Byte math: Prism offsets are byte offsets; byteindex/byterindex/
  # byteslice keep line splicing correct for multibyte sources.
  line_begin = m.start_offset.zero? ? 0 : (source.byterindex("\n", m.start_offset - 1) || -1) + 1
  line_end   = source.byteindex("\n", m.end_offset) || source.bytesize
  before = source.byteslice(line_begin...m.start_offset)
  after  = source.byteslice(m.end_offset...line_end)
  original_block = source.byteslice(line_begin...line_end)
  replacement = m.replacement
  replacement = replacement.dup.force_encoding(before.encoding) if replacement.ascii_only?
  mutated_block = before + replacement + after
  start_line  = source.byteslice(0, m.start_offset).count("\n") + 1
  token       = source.byteslice(m.start_offset...m.end_offset).gsub(/\s+/, " ").strip
  if token.length > 50
    token = token[0, 47] + "...".dup.force_encoding(token.encoding)
  end
  [start_line, original_block, mutated_block, token]
end

#dropped_count ⇒ Integer (private)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Dropped repeats of mutants this report lists. A skipped mutant has no row, so its repeats are not counted. --fail-fast omits unscheduled mutants, and their repeats with them.

Returns:

  • (Integer)


1011
1012
1013
1014
1015
1016
1017
# File 'lib/mutineer/reporter.rb', line 1011

def dropped_count
  @agg.results.sum do |result|
    next 0 if result.skipped? || result.id.nil?

    @copies[result.id]&.size || 0
  end
end

#esc(text) ⇒ Object (private)

HTML-escapes any text destined for the document (stdlib CGI).



723
# File 'lib/mutineer/reporter.rb', line 723

def esc(text) = CGI.escapeHTML(utf8_text(text))

#exit_code(threshold:) ⇒ Object

0 pass / 1 below threshold or untestable-with-errors. Usage errors (exit 2) are the CLI's job. When the score is nil (nothing killed or survived), pure no_coverage / all-ignored / empty still skip the gate; if any mutant was errored, timed out, or uncapturable, fail the gate so a broken harness cannot green CI under --threshold.



225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
# File 'lib/mutineer/reporter.rb', line 225

def exit_code(threshold:)
  return 0 if threshold.nil? || threshold <= 0

  score = @agg.mutation_score
  if score.nil?
    broken = @agg.errored_count + @agg.timeout_count + @agg.uncapturable_count
    return 1 if @agg.total.positive? && broken.positive?

    return 0 # pure no_coverage / ignored / empty — gate skipped
  end

  # A score computed over a small slice of what was attempted is not this
  # suite's score. Without this, 90 errored mutants and 10 that ran (9 killed)
  # reports 90% and exits 0, so CI cannot tell a complete run from a broken one.
  return 1 if broken_share_exceeded?

  @agg.meets_threshold?(threshold) ? 0 : 1
end

#html_report(declined: {}, subjects: nil, unmutated: nil, scoped: false) ⇒ Object (private)

One self-contained HTML file (inline CSS, no external assets): the overall score + summary counts, a per-source table, and every surviving mutant with its stable id and diff. All source/diff/identifier text is HTML-escaped (CGI.escapeHTML) so a </> in source can never break the markup. Reuses survivor_json/per_source_json so one run yields one set of facts regardless of --format.

Parameters:

  • declined (Hash{String => Integer}) (defaults to: {}) —

    candidates declined by operators.

  • subjects (Integer, nil) (defaults to: nil) —

    methods discovered (in scope).

  • unmutated (Integer, nil) (defaults to: nil) —

    methods with no mutants (#419).

  • scoped (Boolean) (defaults to: false) —

    the run was diff-scoped (--since); declined keeps its full-run count and the HTML label says so.



396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
# File 'lib/mutineer/reporter.rb', line 396

def html_report(declined: {}, subjects: nil, unmutated: nil, scoped: false)
  score = @agg.mutation_score
  survivors = @agg.surviving_mutants.map { |r| survivor_json(r) }
                  .sort_by { |h| [h[:file], h[:line], h[:operator]] }
  per_source = @agg.by_source.map { |file, agg| per_source_json(file, agg) }
                   .sort_by { |h| h[:file] }

  <<~HTML
    <!DOCTYPE html>
    <html lang="en">
    <head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <title>Mutineer Mutation Report</title>
    <style>
      body { font-family: -apple-system, Segoe UI, Roboto, Helvetica, Arial, sans-serif;
             margin: 2rem; color: #1b1b1b; background: #fafafa; }
      h1 { margin: 0 0 .25rem; }
      .score { font-size: 2.5rem; font-weight: 700; }
      .counts { color: #444; margin: .5rem 0 1.5rem; }
      .counts span { display: inline-block; margin-right: 1rem; white-space: nowrap; }
      table { border-collapse: collapse; width: 100%; margin-bottom: 2rem; background: #fff; }
      th, td { border: 1px solid #ddd; padding: .4rem .6rem; text-align: left; }
      th { background: #f0f0f0; }
      td.num { text-align: right; font-variant-numeric: tabular-nums; }
      .survivor { background: #fff; border: 1px solid #ddd; border-radius: 4px;
                  padding: .75rem 1rem; margin-bottom: 1rem; }
      .survivor h3 { margin: 0 0 .25rem; font-size: 1rem; }
      .meta { color: #555; font-size: .85rem; margin-bottom: .5rem; }
      .id { font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace; }
      pre.diff { font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
                 background: #f6f8fa; padding: .5rem .75rem; overflow-x: auto;
                 margin: 0; border-radius: 4px; }
      .diff .add { color: #116329; }
      .diff .del { color: #82071e; }
    </style>
    </head>
    <body>
    <h1>Mutineer — Mutation Report</h1>
    <div class="score">Score: #{score.nil? ? 'N/A' : "#{score}%"}</div>
    #{summary_html(declined: declined, subjects: subjects, unmutated: unmutated, scoped: scoped)}
    #{unpaired_html}
    #{per_source_html(per_source)}
    #{survivors_html(survivors)}
    #{ignored_html}
    #{matrix_html}
    </body>
    </html>
  HTML
end

#human_report(out, err, threshold, declined: {}, scoped: false, subjects: nil, unmutated: nil) ⇒ void

This method returns an undefined value.

Renders the human report.

Parameters:

  • out (IO) —

    output stream.

  • err (IO) —

    error stream.

  • threshold (Float) —

    score threshold.

  • declined (Hash{String => Integer}) (defaults to: {}) —

    operator name => declined count.

  • scoped (Boolean) (defaults to: false) —

    the run was diff-scoped (--since).

  • subjects (Integer, nil) (defaults to: nil) —

    methods discovered; nil when unknown.

  • unmutated (Integer, nil) (defaults to: nil) —

    methods the selected operators did not mutate; nil when unknown.



199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
# File 'lib/mutineer/reporter.rb', line 199

def human_report(out, err, threshold, declined: {}, scoped: false, subjects: nil, unmutated: nil)
  # The CLI explains an empty run for every format (CLI.warn_empty_run).
  # A saved report still carries the unpaired counts.
  if @agg.total.zero?
    out.puts unpaired_line(scoped) unless @unpaired.empty?
    return
  end

  out.puts "Mutineer — Mutation Results"
  out.puts "========================="
  out.puts
  summary(out, declined: declined, scoped: scoped, subjects: subjects, unmutated: unmutated)
  out.puts
  score_line(out, err)
  per_source(out)

  survivors(out)
  matrix_section(out) if @matrix
  verdict(out, threshold) if threshold && threshold.positive?
end

#hunk_range(start_line, lines) ⇒ String (private)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

One side of a unified diff hunk header: start for one line, else start,count; an empty side is start-1,0 (#106).

Parameters:

  • start_line (Integer) —

    1-based first line of the block.

  • lines (Array<String>) —

    the block's lines.

Returns:

  • (String) —

    the range, e.g. "3", "3,2" or "2,0".



826
827
828
829
830
# File 'lib/mutineer/reporter.rb', line 826

def hunk_range(start_line, lines)
  return "#{start_line - 1},0" if lines.empty? # an empty side names the line before it

  lines.size == 1 ? start_line.to_s : "#{start_line},#{lines.size}"
end

#ignored_html ⇒ String (private)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Ignored mutants, each with its id and its reason when the user gave one.

Returns:

  • (String) —

    HTML, or "" when none were ignored.



523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
# File 'lib/mutineer/reporter.rb', line 523

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}
      #{copies_html(row[:copies])}
      </div>
    CARD
  end.join("\n")
  "<h2>Ignored mutants</h2>\n#{cards}"
end

#ignored_json(result) ⇒ Hash (private)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

One ignored mutant. reason is present only when the user wrote one.

Parameters:

Returns:

  • (Hash)


837
838
839
840
841
842
# File 'lib/mutineer/reporter.rb', line 837

def ignored_json(result)
  row = mutant_json(result)
  text = result.reason
  row[:reason] = text if text.is_a?(String) && !text.strip.empty?
  row
end

#json_report(baseline = nil, scoped: false, legacy_id_matches: { ignore: 0, baseline: 0 }, unmatched_ignores: [], declined: {}, subjects: nil, unmutated_subjects: nil) ⇒ String (private)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Canonical machine-readable schema. survivors/no_coverage are sorted by (file, line, operator) so output is byte-stable regardless of --jobs worker finish order.

Parameters:

  • baseline (Mutineer::Baseline::Delta, nil) (defaults to: nil) —

    baseline delta.

  • scoped (Boolean) (defaults to: false) —

    the run was diff-scoped (--since), so its score covers only the changed-line mutants (additive summary.scoped key).

  • legacy_id_matches (Hash{Symbol => Integer}) (defaults to: { ignore: 0, baseline: 0 }) —

    {ignore:, baseline:}: old-format ignore entries that matched, and survivors matched in an old-format baseline only through their old id (#126).

  • unmatched_ignores (Array<String>) (defaults to: []) —

    ignore: ids that matched no mutant in this run, in file order, each once (#377). Empty under --only, which skips the check.

  • declined (Hash{String => Integer}) (defaults to: {}) —

    operator name => count of candidates that operator did not mutate (additive summary.declined and summary.declined_by_operator keys).

  • subjects (Integer, nil) (defaults to: nil) —

    methods discovered (additive summary.subjects); nil (JSON null) when the caller did not supply it, never a made-up 0.

  • unmutated_subjects (Array<Hash>, nil) (defaults to: nil) —

    {subject:, file:, line:} per method the operators did not mutate, already sorted (additive summary.unmutated_subjects count and top-level unmutated_subjects[]); nil (JSON null for both) when not supplied.

Returns:

  • (String) —

    JSON text.



270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
# File 'lib/mutineer/reporter.rb', line 270

def json_report(baseline = nil, scoped: false, legacy_id_matches: { ignore: 0, baseline: 0 },
                unmatched_ignores: [], declined: {},
                subjects: nil, unmutated_subjects: nil)
  killed = @agg.killed_count
  survived = @agg.survived_count
  # null (not 0.0) on an empty denominator, matching the nil-vs-0.0
  # discipline in AggregateResult; and the SAME rounding as the human report
  # (one run must not yield two scores by --format).
  score = @agg.mutation_score

  doc = {
    schema_version: SCHEMA_VERSION,
    summary: {
      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,
      # Additive (1.10, #374): repeats of a kept mutant that were not run.
      # Not in `total` and not in the score. The ids sit on `copies`.
      dropped: dropped_count,
      # The gate is computed from these two, so a consumer never re-derives them.
      attempted: attempted_count, no_verdict: no_verdict_count,
      score: score,
      # Additive: true when the run was diff-scoped (--since). The score then
      # covers only the changed-line mutants, so it is not comparable to a
      # full-run score; Baseline#diff reads this to skip the score-drop gate.
      scoped: scoped,
      # Additive (1.4, #126): ids hash the project-relative file path. A
      # baseline without this key stores old-format ids; Baseline#diff then
      # also matches on old ids.
      id_format: 2,
      # Additive (1.4, #126): stored ids still in the old format. `ignore` is
      # the number of old-format ignore entries that matched; `baseline` the
      # survivors matched in the baseline only through their old id.
      legacy_id_matches: legacy_id_matches,
      # Additive (1.10, #377): ignore ids that matched no mutant in this
      # run's sources and operators. File order, each id once. Empty under
      # --only, because that check is skipped. The exit code stays 0.
      unmatched_ignores: unmatched_ignores,
      # Additive (1.9, #291): candidates the operators found and did not
      # mutate (a heredoc split or an equivalent skip), so not in `total`.
      declined: declined.values.sum,
      declined_by_operator: declined,
      # Additive (1.10, #381): sources pairing skipped, and the mutants in
      # them. A nil count is left out of the mutant sum.
      unpaired_sources: @unpaired.size,
      unpaired_mutants: unpaired_mutant_count,
      # Additive (1.10, #386): methods discovered, and how many of them the
      # selected operators did not mutate. Not mutants, so not in `total`.
      subjects: subjects,
      unmutated_subjects: unmutated_subjects&.size
    },
    survivors: @agg.surviving_mutants.map { |r| survivor_json(r) }
                   .sort_by { |h| [h[:file], h[:line], h[:operator]] },
    # Additive (1.10, #361): every killed mutant's lean identity so two runs
    # can be joined by id without subtracting every unscored category.
    # to_s/to_i: lean_mutant_json can leave null fields when a stub result
    # lacks a subject (same rule as no_verdict[]).
    killed: @agg.results.select(&:killed?).map { |r| mutant_json(r) }
                .sort_by { |h| [h[:file].to_s, h[:line].to_i, h[:operator].to_s, h[:id].to_s] },
    # id extends the key to a total order: several mutants share a line.
    no_coverage: @agg.results.select(&:no_coverage?).map { |r| mutant_json(r) }
                     .sort_by { |h| [h[:file], h[:line], h[:operator], h[:id].to_s] },
    # 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
    # alone and a key that reconciled with neither would be worse. `details`
    # carries the cause where there is one. Uncapturable mutants also appear in
    # uncapturable[], which stays for consumers that already read it.
    # to_s/to_i because a pre-fork failure has no subject, so its file and line
    # are null and would not compare against a real entry. id and status extend
    # the key to a total order: these entries collide on (file, line) far more
    # than survivors do — several mutants on one crashy line, every pre-fork
    # entry on ("", 0) — and sort_by is not stable, so equal keys would leave
    # worker finish order in the output and break the byte-stability promise.
    no_verdict: @agg.results.select { |r| r.error? || r.timeout? || r.uncapturable? }
                    .map { |r| no_verdict_json(r) }
                    .sort_by { |h| [h[:file].to_s, h[:line].to_i, h[:id].to_s, h[:status].to_s, h[:details].to_s] },
    # 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| 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.
    per_source: @agg.by_source.map { |file, agg| per_source_json(file, agg) }
                    .sort_by { |h| h[:file] },
    # Additive (1.10, #381): every source pairing skipped, sorted by file.
    # `mutants` is null when the count failed.
    unpaired_sources: unpaired_sources_json,
    # Additive (1.10, #386): the methods the selected operators did not
    # mutate, sorted by (file, line, subject) in JobPlan.collect_jobs.
    unmutated_subjects: unmutated_subjects
  }
  # Additive (1.5): the kill matrix, present only with --matrix.
  doc[:matrix] = matrix_json if @matrix
  # Additive baseline-delta block, present only with --baseline. Existing
  # consumers ignore the extra key; it does not move schema_version on its own.
  doc[:baseline] = baseline_json(baseline) if baseline
  "#{JSON.generate(json_safe(doc))}\n"
end

#json_safe(value) ⇒ Object (private)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

A JSON document with every string as UTF-8 (#346). A path whose bytes are not UTF-8 is binary, and JSON.generate refuses it. Such bytes print as \xNN, as in the human report.

Parameters:

  • value (Object) —

    a document built from Hash, Array, String and scalars.

Returns:

  • (Object) —

    the same shape, its strings passed through #utf8_text.



1437
1438
1439
1440
1441
1442
1443
1444
# File 'lib/mutineer/reporter.rb', line 1437

def json_safe(value)
  case value
  when String then utf8_text(value)
  when Hash then value.to_h { |k, v| [json_safe(k), json_safe(v)] }
  when Array then value.map { |v| json_safe(v) }
  else value
  end
end

#lean_mutant_json(subject, mutation, id) ⇒ Hash (private)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Lean mutant identity shared by run-report lists and --dry-run --format json.

Parameters:

Returns:

  • (Hash) —

    subject, file, line, operator, token, and id.



862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
# File 'lib/mutineer/reporter.rb', line 862

def lean_mutant_json(subject, mutation, id)
  # Stub results in tests (and rare pre-attach kills) can lack a subject.
  # Match no_verdict_json: null fields rather than raising.
  if subject.nil? || mutation.nil?
    return attach_copies({
      subject: nil, file: nil, line: nil, operator: nil, token: nil, id: id
    }, id)
  end

  file = subject.file
  source = source_for(file)
  start_line, _orig, _mut, token = diff_for(mutation, source)
  attach_copies({
    subject: subject.qualified_name,
    file: file,
    line: start_line,
    operator: mutation.operator.to_s,
    token: token,
    id: id
  }, id)
end

#matrix_counts_line ⇒ String (private)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

The counts sentence both matrix renderers open with.

Returns:

  • (String)


706
707
708
709
710
# File 'lib/mutineer/reporter.rb', line 706

def matrix_counts_line
  "#{@matrix.tests.size} tests ran against #{@matrix.rows.size} mutants " \
    "(every test in each mutant's covering files): " \
    "#{@matrix.blind.size} blind, #{@matrix.redundant.size} redundant."
end

#matrix_html ⇒ String (private)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

The kill-matrix section of the HTML report: the counts, then the blind and redundant tests. Empty without --matrix.

Returns:

  • (String) —

    HTML.



547
548
549
550
551
552
553
554
555
556
557
558
# File 'lib/mutineer/reporter.rb', line 547

def matrix_html
  return "" unless @matrix

  lists = { "Blind tests" => @matrix.blind, "Redundant tests" => @matrix.redundant }.map do |title, tests|
    items = tests.map { |test| "<li><span class=\"id\">#{esc(test[0])}</span> #{esc(test_label(test))}</li>" }
    body = items.empty? ? "<p>None.</p>" : "<ul>\n#{items.join("\n")}\n</ul>"
    "<h3>#{esc(title)} (#{tests.size})</h3>\n#{body}"
  end
  note = @matrix.complete? ? "" : "\n<p>#{esc(matrix_incomplete_note)}</p>\n#{matrix_incomplete_html}"
  delete = @matrix.redundant.empty? ? "" : "\n<p>#{esc(MATRIX_REDUNDANT_NOTE)}</p>"
  "<h2>Kill matrix</h2>\n<p>#{esc(matrix_counts_line)}</p>#{note}\n#{lists.join("\n")}#{delete}"
end

#matrix_incomplete_html ⇒ String (private)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Every incomplete row of the HTML kill-matrix section.

Returns:

  • (String) —

    HTML.



564
565
566
567
# File 'lib/mutineer/reporter.rb', line 564

def matrix_incomplete_html
  items = @matrix.incomplete_rows.map { |r| "<li>#{esc(matrix_row_label(r))}</li>" }
  "<h3>Incomplete rows (#{items.size})</h3>\n<ul>\n#{items.join("\n")}\n</ul>"
end

#matrix_incomplete_note ⇒ String (private)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

The warning both matrix renderers give when a row is incomplete.

Returns:

  • (String)


716
717
718
719
720
# File 'lib/mutineer/reporter.rb', line 716

def matrix_incomplete_note
  "#{@matrix.incomplete_rows.size} mutants could not be verified as complete (a timeout, an error, " \
    "an exit, an interrupt or a broken stream), so a blind test may have killed one of them. " \
    "Do not delete a blind test until these rows are complete:"
end

#matrix_incomplete_section(out) ⇒ void (private)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

This method returns an undefined value.

The human report's warning about incomplete rows, with the first MATRIX_LIST_LIMIT of them named.

Parameters:

  • out (IO) —

    output stream.



652
653
654
655
656
657
658
659
# File 'lib/mutineer/reporter.rb', line 652

def matrix_incomplete_section(out)
  rows = @matrix.incomplete_rows
  out.puts matrix_incomplete_note
  rows.first(MATRIX_LIST_LIMIT).each { |r| out.puts "  #{printable(matrix_row_label(r))}" }
  rest = rows.size - MATRIX_LIST_LIMIT
  out.puts "  and #{rest} more" if rest.positive?
  out.puts "The HTML and JSON reports list every incomplete row (JSON: matrix.mutants with complete: false)."
end

#matrix_json ⇒ Hash (private)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

The JSON matrix block: every test with its kill count, one row per mutant that ran (its killers as indexes into tests), and the blind and redundant tests. Rows sort like survivors, then by id, so output is byte-stable regardless of --jobs.

Returns:

  • (Hash) —

    the matrix JSON object.



576
577
578
579
580
581
582
583
584
585
586
587
# File 'lib/mutineer/reporter.rb', line 576

def matrix_json
  tests = @matrix.tests
  index = tests.each_with_index.to_h
  {
    complete: @matrix.complete?,
    tests: tests.map { |test| test_json(test).merge(kills: @matrix.kill_count(test)) },
    mutants: @matrix.rows.map { |r| matrix_row_json(r, index) }
                    .sort_by { |h| [h[:file].to_s, h[:line].to_i, h[:operator].to_s, h[:id].to_s] },
    blind: @matrix.blind.map { |test| test_json(test) },
    redundant: @matrix.redundant.map { |test| test_json(test) }
  }
end

#matrix_list(out, title, tests) ⇒ void (private)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

This method returns an undefined value.

One titled list of tests in the human kill-matrix section, cut at MATRIX_LIST_LIMIT; the JSON report has the whole list.

Parameters:

  • out (IO) —

    output stream.

  • title (String) —

    the list's title.

  • tests (Array<Array(String, String, String)>) —

    [file, name, id] tests.



694
695
696
697
698
699
700
# File 'lib/mutineer/reporter.rb', line 694

def matrix_list(out, title, tests)
  out.puts
  out.puts "#{title}: #{tests.size}"
  tests.first(MATRIX_LIST_LIMIT).each { |test| out.puts "  #{printable(test[0])}  #{printable(test_label(test))}" }
  rest = tests.size - MATRIX_LIST_LIMIT
  out.puts "  and #{rest} more; see --format json" if rest.positive?
end

#matrix_row_json(result, index) ⇒ Hash (private)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

One mutant's row under matrix.mutants.

Parameters:

  • result (Mutineer::Result) —

    a result with a Kills row.

  • index (Hash{Array => Integer}) —

    test => its index in matrix.tests.

Returns:

  • (Hash) —

    the row JSON object.



617
618
619
620
621
622
623
624
625
626
# File 'lib/mutineer/reporter.rb', line 617

def matrix_row_json(result, index)
  file = result.subject&.file
  kills = result.kills
  {
    subject: result.subject&.qualified_name, file: file, line: result_line(result),
    operator: result.mutation&.operator&.to_s, id: result.id, status: result.status.to_s,
    killed_by: kills.killed_by.map { |test| index.fetch(test) }.sort,
    ran: kills.ran.size, complete: kills.complete
  }
end

#matrix_row_label(result) ⇒ String (private)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

A row's label: subject, place, operator, status and id.

Parameters:

Returns:

  • (String)


666
667
668
669
670
# File 'lib/mutineer/reporter.rb', line 666

def matrix_row_label(result)
  place = [result.subject&.file, result_line(result)].compact.join(":")
  [result.subject&.qualified_name, ("(#{place})" unless place.empty?), result.mutation&.operator,
   result.status, result.id].compact.join(" ")
end

#matrix_section(out) ⇒ void (private)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

This method returns an undefined value.

The kill-matrix section of the human report.

Parameters:

  • out (IO) —

    output stream.



633
634
635
636
637
638
639
640
641
642
643
644
# File 'lib/mutineer/reporter.rb', line 633

def matrix_section(out)
  out.puts
  out.puts "Kill matrix"
  out.puts "-----------"
  out.puts matrix_counts_line
  matrix_incomplete_section(out) unless @matrix.complete?
  matrix_list(out, "Blind tests (ran, killed no mutant)", @matrix.blind)
  matrix_list(out, "Redundant tests (each mutant they kill has another killer)", @matrix.redundant)
  return if @matrix.redundant.empty?

  out.puts MATRIX_REDUNDANT_NOTE
end

#mutant_json(result) ⇒ Hash (private)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

The fields that name one mutant, for the lists that point at mutants: killed, no_coverage, uncapturable, unplaceable, ran_at_load, ignored and baseline.new_survivors.

Parameters:

Returns:

  • (Hash) —

    subject, file, line, operator, token, and id.



851
852
853
# File 'lib/mutineer/reporter.rb', line 851

def mutant_json(result)
  lean_mutant_json(result.subject, result.mutation, result.id)
end

#no_verdict_count ⇒ Integer (private)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Mutants that were attempted and produced no verdict, whatever the reason.

Returns:

  • (Integer) —

    errored + timed out + uncapturable.



1149
1150
1151
# File 'lib/mutineer/reporter.rb', line 1149

def no_verdict_count
  @agg.errored_count + @agg.timeout_count + @agg.uncapturable_count
end

#no_verdict_json(result) ⇒ Hash (private)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

An entry under the JSON no_verdict: key: an attempted mutant with no verdict. A pre-fork failure has no subject or mutation attached, so those degrade to nulls rather than dropping the entry — the count must still reconcile with summary.no_verdict. details is redacted here too, whatever its source (#388).

Parameters:

Returns:

  • (Hash) —

    no-verdict JSON object.



964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
# File 'lib/mutineer/reporter.rb', line 964

def no_verdict_json(result)
  file = result.subject&.file
  # As in result_line: diff_for needs the source, so a mutation needs a file.
  m = result.mutation if file
  line, _orig, _mut, token = diff_for(m, source_for(file)) if m
  row = {
    subject: result.subject&.qualified_name,
    file: file,
    line: line,
    operator: m&.operator&.to_s,
    token: token,
    id: result.id,
    status: result.status.to_s,
    details: result.details && Redaction.text(result.details)
  }
  attach_copies(row, result.id)
end

#no_verdict_ratio ⇒ String (private)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

The sentence both the verdict line and the stderr note are built from, so a user cannot read one number in the report and a different one beside it.

Returns:

  • (String) —

    e.g. "90 of 100 attempted mutants produced no verdict (90.0%, limit 10%)".



1280
1281
1282
1283
1284
# File 'lib/mutineer/reporter.rb', line 1280

def no_verdict_ratio
  pct = (no_verdict_count * 100.0 / attempted_count).round(1)
  "#{no_verdict_count} of #{attempted_count} attempted mutants produced no verdict " \
    "(#{pct}%, limit #{(BROKEN_SHARE_LIMIT * 100).round}%)"
end

#per_source(out) ⇒ void (private)

This method returns an undefined value.

One line per source after the global summary, so a multi-source run shows which file is weak. Omitted for a single-source run: the global summary already says everything (no redundant one-line block).

Parameters:

  • out (IO) —

    output stream.



1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
# File 'lib/mutineer/reporter.rb', line 1305

def per_source(out)
  sources = @agg.by_source
  return if sources.size <= 1

  out.puts
  out.puts "Per-source"
  out.puts "----------"
  sources.sort.each do |file, agg|
    score = agg.mutation_score
    out.puts format("%s  %s  (%d killed / %d survived / %d no-cov)",
                    printable(file), score.nil? ? "N/A" : "#{score}%",
                    agg.killed_count, agg.survived_count, agg.no_coverage_count)
  end
end

#per_source_html(per_source) ⇒ Object (private)

The per-source breakdown table.



478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
# File 'lib/mutineer/reporter.rb', line 478

def per_source_html(per_source)
  return "" if per_source.empty?

  rows = per_source.map do |h|
    score = h[:score].nil? ? "N/A" : "#{h[:score]}%"
    "<tr><td>#{esc(h[:file])}</td><td class=\"num\">#{score}</td>" \
      "<td class=\"num\">#{h[:killed]}</td><td class=\"num\">#{h[:survived]}</td>" \
      "<td class=\"num\">#{h[:no_coverage]}</td></tr>"
  end.join("\n  ")
  <<~HTML.chomp
    <h2>Per-source</h2>
    <table>
    <tr><th>File</th><th>Score</th><th>Killed</th><th>Survived</th><th>No coverage</th></tr>
      #{rows}
    </table>
  HTML
end

#per_source_json(file, agg) ⇒ Hash (private)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Builds per-source JSON.

Parameters:

Returns:

  • (Hash) —

    per-source JSON object.



753
754
755
756
757
758
759
# File 'lib/mutineer/reporter.rb', line 753

def per_source_json(file, agg)
  {
    file: file, total: agg.total,
    killed: agg.killed_count, survived: agg.survived_count,
    no_coverage: agg.no_coverage_count, score: agg.mutation_score
  }
end

#printable(text) ⇒ String (private)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Source text, a method name or a file path made safe for a terminal (#163): each control character except tab becomes its Ruby escape (ESC prints as \e). A valid string in another encoding (EUC-JP, Shift_JIS) is transcoded to UTF-8. Bytes that are not valid in their encoding are read as UTF-8 and each bad byte prints as \xNN, so nothing is lost and the regex never raises (#346). JSON and HTML escape on their own, after the same transcoding.

Parameters:

  • text (String) —

    source text.

Returns:

  • (String) —

    the text with control characters and invalid bytes escaped.



1407
1408
1409
# File 'lib/mutineer/reporter.rb', line 1407

def printable(text)
  utf8_text(text).gsub(/[[:cntrl:]&&[^\t]]/) { |c| c.dump[1..-2] }
end

#report(out: $stdout, err: $stderr, threshold: 0.0, format: "human", output: nil, baseline: nil, scoped: false, legacy_id_matches: { ignore: 0, baseline: 0 }, unmatched_ignores: [], declined: {}, subjects: nil, unmutated_subjects: nil, copies: {}) ⇒ Object

Single entry point. Branches on format ("human" | "json" | "html") and routes the rendered report to output (a file, with a stderr confirmation) or to out. Diagnostics always go to err. scoped marks a diff-scoped (--since) run; the JSON report records it so a consumer (or a later --baseline load) knows the score covers only the changed-line mutants. legacy_id_matches ({ignore:, baseline:}) counts stored ids still in the old format (#126); only the JSON report records it (summary.legacy_id_matches). unmatched_ignores is the ignore: ids that matched no mutant in this run (#377); only the JSON report records them (summary.unmatched_ignores). An empty list under --only means the check was skipped, not that every entry matched. declined (operator name => count, from JobPlan.collect_jobs) counts the candidates the operators did not mutate; the JSON and human reports show it. subjects (methods discovered) and unmutated_subjects (one {subject:, file:, line:} hash per method the operators did not mutate, from JobPlan.collect_jobs, #386) feed the same two reports. Left out, they are unknown: JSON reports null and the human report has no row. The two are one unit: when either is left out, both are unknown. copies (kept mutant id => dropped repeat ids, from JobPlan.collect_jobs, #374) is listed on each kept mutant and counted in summary.dropped. An empty hash reports zero. The count covers mutants in this report, so --fail-fast leaves out copies of mutants it did not schedule.



92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
# File 'lib/mutineer/reporter.rb', line 92

def report(out: $stdout, err: $stderr, threshold: 0.0, format: "human", output: nil,
           baseline: nil, scoped: false, legacy_id_matches: { ignore: 0, baseline: 0 },
           unmatched_ignores: [], declined: {},
           subjects: nil, unmutated_subjects: nil, copies: {})
  @copies = copies || {}
  subjects = unmutated_subjects = nil if subjects.nil? || unmutated_subjects.nil?
  rendered =
    if format == "json"
      json_report(baseline, scoped: scoped, legacy_id_matches: legacy_id_matches,
                            unmatched_ignores: unmatched_ignores, declined: declined,
                            subjects: subjects, unmutated_subjects: unmutated_subjects)
    elsif format == "html"
      html_report(declined: declined, subjects: subjects, unmutated: unmutated_subjects&.size,
                  scoped: scoped)
    else
      sio = StringIO.new
      human_report(sio, err, threshold, declined: declined, scoped: scoped,
                                        subjects: subjects, unmutated: unmutated_subjects&.size)
      baseline_section(sio, baseline) if baseline
      sio.string
    end

  if output
    abs = File.expand_path(output)
    File.write(abs, rendered)
    err.puts "Report written to #{abs}"
  else
    out.print rendered
  end

  warn_unrun_share(err)
  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.
  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."
  elsif broken_share_exceeded?
    err.puts "[mutineer] #{no_verdict_ratio}: #{broken_counts_detail}. The score covers " \
             "only part of the run, so the --threshold gate fails. See no_verdict[] in " \
             "--format json for the cause of each."
  end
end

#result_line(result) ⇒ Integer? (private)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

The 1-based line of a result's mutation, or nil without one (a pre-fork failure has no subject or mutation).

Parameters:

Returns:

  • (Integer, nil)


678
679
680
681
682
683
684
# File 'lib/mutineer/reporter.rb', line 678

def result_line(result)
  file = result.subject&.file
  return unless result.mutation && file

  source = source_for(file)
  source.byteslice(0, result.mutation.start_offset).count("\n") + 1
end

#score_line(out, err) ⇒ void (private)

This method returns an undefined value.

Writes the score line.

Parameters:

  • out (IO) —

    output stream.

  • err (IO) —

    error stream.



1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
# File 'lib/mutineer/reporter.rb', line 1104

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, " \
             "#{unpaired_mutant_count} unpaired, #{@agg.ignored_count} ignored excluded"
  if score.nil?
    out.puts "Mutation score: N/A  (no covered mutants)"
    # Only the benign case here: the gate-failure explanation is emitted once
    # from {report}, for every format, so it cannot be said twice or only to
    # the reader of the human report.
    unless broken_nil_score?
      err.puts "[mutineer] no covered mutations; mutation score is N/A and the threshold check is skipped."
    end
  else
    out.puts "Mutation score: #{score}%  (killed / (killed + survived); #{excluded})"
  end
end

#side_lines(block, at_eof) ⇒ Array<String> (private)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

One side of the diff as the file holds it: the #diff_for block plus the newline that follows it, unless the block ends the file. Each line keeps its own ending, so a CRLF line keeps its "\r" and a last line with no newline is told apart from one with a newline.

Parameters:

  • block (String) —

    the block's text.

  • at_eof (Boolean) —

    no newline follows the block in the file.

Returns:

  • (Array<String>) —

    its lines, with their endings.



802
803
804
805
806
# File 'lib/mutineer/reporter.rb', line 802

def side_lines(block, at_eof)
  newline = "\n".dup.force_encoding(block.encoding)
  text = at_eof ? block : block + newline
  text.lines.map { |line| utf8_text(line) }
end

#source_for(file) ⇒ String (private)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

The source text of file: the run's copy when it has one, else the file read in its magic-comment encoding, or UTF-8 (#303, #346).

Parameters:

  • file (String) —

    source file path.

Returns:

  • (String) —

    source text.



1394
# File 'lib/mutineer/reporter.rb', line 1394

def source_for(file) = @source_map[file] || Parser.read(file)

#summary(out, declined: {}, scoped: false, subjects: nil, unmutated: nil) ⇒ void (private)

This method returns an undefined value.

Writes the summary block.

Parameters:

  • out (IO) —

    output stream.

  • declined (Hash{String => Integer}) (defaults to: {}) —

    operator name => declined count.

  • scoped (Boolean) (defaults to: false) —

    the run was diff-scoped (--since), which does not narrow the declined count (method counts are already narrowed by JobPlan.scope_since, #420).

  • subjects (Integer, nil) (defaults to: nil) —

    methods discovered; nil when unknown.

  • unmutated (Integer, nil) (defaults to: nil) —

    methods the selected operators did not mutate; nil when unknown, which leaves out the No mutants: row.



1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
# File 'lib/mutineer/reporter.rb', line 1064

def summary(out, declined: {}, scoped: false, subjects: nil, unmutated: nil)
  out.puts "Summary"
  out.puts "-------"
  out.puts format("Total:        %-6d  Killed:        %d", @agg.total, @agg.killed_count)
  out.puts format("Survived:     %-6d  No coverage:   %d", @agg.survived_count, @agg.no_coverage_count)
  out.puts format("Skipped:      %-6d  Errored:       %d", @agg.skipped_invalid_count, @agg.errored_count)
  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 some methods in a concern's `included` or
  # `prepended` block; see docs/json-schema.md).
  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)
  # Not mutants: candidates an operator chose not to mutate (#291).
  out.puts format("Declined:     %-6d  (candidates an operator did not mutate; --dry-run shows the count " \
                  "per operator%s)", declined.values.sum, scoped ? "; not narrowed by --since" : "")
  # Not mutants: methods, which no operator gave a mutant (#386). Unknown
  # (a caller passed no method counts) prints no row, never a made-up 0.
  if subjects && unmutated
    # Under --since the JobPlan already narrowed these counts (#420).
    out.puts format("No mutants:   %-6d  (methods of %d that the selected operators did not mutate; " \
                    "--dry-run --verbose and the JSON report list them)",
                    unmutated, subjects)
  end
  # Equivalent mutants the user suppressed; excluded from the denominator.
  out.puts format("Ignored:      %-6d  (equivalent, suppressed)", @agg.ignored_count)
  # Repeats that were not run (#374). The ids are on `copies` in the JSON.
  out.puts format("Dropped:      %-6d  (repeats of a kept mutant; see --format json)", dropped_count)
  out.puts unpaired_line(scoped)
end

#summary_html(declined: {}, subjects: nil, unmutated: nil, scoped: false) ⇒ Object (private)

The summary counts block for the HTML header.

Parameters:

  • declined (Hash{String => Integer}) (defaults to: {})
  • subjects (Integer, nil) (defaults to: nil)
  • unmutated (Integer, nil) (defaults to: nil)
  • scoped (Boolean) (defaults to: false) —

    when true, the declined label notes it is not narrowed by --since (same wording as the human report).



454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
# File 'lib/mutineer/reporter.rb', line 454

def summary_html(declined: {}, subjects: nil, unmutated: nil, scoped: false)
  counts = {
    "total" => @agg.total, "killed" => @agg.killed_count,
    "survived" => @agg.survived_count, "no_coverage" => @agg.no_coverage_count,
    "uncapturable" => @agg.uncapturable_count, "unplaceable" => @agg.unplaceable_count,
    "ran_at_load" => @agg.ran_at_load_count, "ignored" => @agg.ignored_count,
    "dropped" => dropped_count,
    "skipped" => @agg.skipped_invalid_count,
    "errored" => @agg.errored_count, "timeout" => @agg.timeout_count,
    "unpaired" => unpaired_mutant_count
  }
  if declined.any?
    label = scoped ? "declined (not narrowed by --since)" : "declined"
    counts[label] = declined.values.sum
  end
  if subjects && unmutated
    counts["no_mutants"] = unmutated
    counts["methods"] = subjects
  end
  spans = counts.map { |k, v| "<span><strong>#{v}</strong> #{esc(k)}</span>" }.join("\n  ")
  "<div class=\"counts\">\n  #{spans}\n</div>"
end

#survivor(out, file, result) ⇒ void (private)

This method returns an undefined value.

Writes one survivor entry.

Parameters:

  • out (IO) —

    output stream.

  • file (String) —

    source file path.

  • result (Mutineer::Result) —

    survivor result.



1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
# File 'lib/mutineer/reporter.rb', line 1377

def survivor(out, file, result)
  m = result.mutation
  source = source_for(file)
  start_line, original_block, mutated_block, token = diff_for(m, source)

  out.puts "  #{printable(result.subject.qualified_name)} (#{printable(File.basename(file))}:#{start_line})"
  out.puts "  Operator: #{m.operator}  (#{printable(token)} -> #{printable(m.replacement)})"
  original_block.each_line { |l| out.puts "  - #{printable(l.chomp)}" }
  mutated_block.each_line  { |l| out.puts "  + #{printable(l.chomp)}" }
end

#survivor_json(result) ⇒ Hash (private)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Builds survivor JSON.

Parameters:

Returns:

  • (Hash) —

    survivor JSON object.



766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
# File 'lib/mutineer/reporter.rb', line 766

def survivor_json(result)
  m = result.mutation
  file = result.subject.file
  source = source_for(file)
  start_line, original_block, mutated_block, token = diff_for(m, source)
  # A block at the end of the file has no newline after it; elsewhere the
  # file's next byte is one. Each side's own text decides its marker.
  at_eof = source.byteindex("\n", m.end_offset).nil?
  old_lines = side_lines(original_block, at_eof)
  new_lines = side_lines(mutated_block, at_eof)
  shown_file = utf8_text(file)
  row = {
    subject: utf8_text(result.subject.qualified_name.to_s),
    file: file,
    line: start_line,
    operator: m.operator.to_s,
    # The stable, copy-pasteable id (next to the human-readable token) so a
    # user can paste it straight into .mutineer.yml `ignore:`.
    id: result.id,
    token: utf8_text(token),
    diff: "--- a/#{shown_file}\n+++ b/#{shown_file}\n" \
          "@@ -#{hunk_range(start_line, old_lines)} +#{hunk_range(start_line, new_lines)} @@\n" \
          "#{diff_body("-", old_lines)}#{diff_body("+", new_lines)}"
  }
  attach_copies(row, result.id)
end

#survivors(out) ⇒ void (private)

This method returns an undefined value.

Writes the survivors block.

Parameters:

  • out (IO) —

    output stream.



1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
# File 'lib/mutineer/reporter.rb', line 1357

def survivors(out)
  mutants = @agg.surviving_mutants
  return if mutants.empty?

  out.puts
  out.puts "Surviving Mutants"
  out.puts "-----------------"
  mutants.group_by { |r| r.subject.file }.sort.each do |file, group|
    out.puts
    out.puts printable(file)
    group.sort_by { |r| tie_key(r) }.each { |r| survivor(out, file, r) }
  end
end

#survivors_html(survivors) ⇒ Object (private)

The surviving-mutants list, each with subject, location, operator, stable id, and a colorized diff. All text is HTML-escaped.



498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
# File 'lib/mutineer/reporter.rb', line 498

def survivors_html(survivors)
  return "<h2>Surviving Mutants</h2>\n<p>None — every covered mutant was killed.</p>" if survivors.empty?

  cards = survivors.map do |s|
    diff_lines = s[:diff].each_line.map do |line|
      cls = line.start_with?("+") ? "add" : (line.start_with?("-") ? "del" : nil)
      text = esc(line.chomp)
      cls ? "<span class=\"#{cls}\">#{text}</span>" : text
    end.join("\n")
    <<~CARD.chomp
      <div class="survivor">
      <h3>#{esc(s[:subject])}</h3>
      <div class="meta">#{esc(s[:file])}:#{s[:line]} &middot; #{esc(s[:operator])} &middot; <span class="id">#{esc(s[:id])}</span></div>
      #{copies_html(s[:copies])}
      <pre class="diff">#{diff_lines}</pre>
      </div>
    CARD
  end.join("\n")
  "<h2>Surviving Mutants</h2>\n#{cards}"
end

#test_json(test) ⇒ Hash (private)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

One test as JSON: its file, display name and id.

Parameters:

  • test (Array(String, String, String)) —

    a [file, name, id] test.

Returns:

  • (Hash)


594
595
596
597
# File 'lib/mutineer/reporter.rb', line 594

def test_json(test)
  file, name, id = test
  { file: file, name: name, id: id }
end

#test_label(test) ⇒ String (private)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

A test's name for people: the display name, plus the id when it differs (an RSpec example id, which tells apart examples that share a name and runs exactly that example with rspec).

Parameters:

  • test (Array(String, String, String)) —

    a [file, name, id] test.

Returns:

  • (String)


606
607
608
609
# File 'lib/mutineer/reporter.rb', line 606

def test_label(test)
  _file, name, id = test
  id == name ? name : "#{name} (#{id})"
end

#tie_key(result) ⇒ Array (private)

Orders mutants in one file: by offset, then operator and replacement, so mutants at the same offset list the same way whatever order they ran in.

Parameters:

Returns:

  • (Array) —

    the sort key.



1348
1349
1350
1351
# File 'lib/mutineer/reporter.rb', line 1348

def tie_key(result)
  m = result.mutation
  [m.start_offset, m.operator.to_s, m.replacement.to_s]
end

#unpaired_html ⇒ String (private)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

The HTML table of sources with no paired test. Empty when none were skipped.

Returns:

  • (String)


1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
# File 'lib/mutineer/reporter.rb', line 1259

def unpaired_html
  return "" if @unpaired.empty?

  rows = @unpaired.sort_by { |file, _count| file.to_s }.map do |file, count|
    shown = count.nil? ? "unknown" : count.to_s
    "<tr><td>#{esc(file)}</td><td class=\"num\">#{esc(shown)}</td></tr>"
  end.join("\n  ")
  <<~HTML.chomp
    <h2>Sources with no paired test</h2>
    <table>
    <tr><th>File</th><th>Mutants</th></tr>
      #{rows}
    </table>
  HTML
end

#unpaired_in_share? ⇒ Boolean (private)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

True when unpaired mutants join the unrun share and the human percentage. A failed count is not in the sum, so it does not join on its own.

Returns:

  • (Boolean)


1197
1198
1199
# File 'lib/mutineer/reporter.rb', line 1197

def unpaired_in_share?
  !@fail_fast && !@agg.total.zero? && unpaired_mutant_count.positive?
end

#unpaired_line(scoped) ⇒ String (private)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

The human Unpaired line. The percentage is omitted under --fail-fast, when the denominator is empty, and when the mutant count is 0.

Parameters:

  • scoped (Boolean) —

    the run was diff-scoped (--since).

Returns:

  • (String)


1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
# File 'lib/mutineer/reporter.rb', line 1223

def unpaired_line(scoped)
  detail = [scoped ? "mutants on changed lines not run" : "mutants not run"]
  sources = @unpaired.size
  detail << (sources == 1 ? "1 source has no paired test" : "#{sources} sources have no paired test")
  unknown = @unpaired.count { |_file, count| count.nil? }
  if unknown == 1
    detail << "1 source not counted"
  elsif unknown > 1
    detail << "#{unknown} sources not counted"
  end
  share = unpaired_scope_share
  detail << "#{share}% of the mutants in scope" if share
  format("Unpaired:     %-6d  (%s)", unpaired_mutant_count, detail.join("; "))
end

#unpaired_mutant_count ⇒ Integer (private)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Known unpaired mutant counts. A nil count is left out.

Returns:

  • (Integer)


1205
1206
1207
# File 'lib/mutineer/reporter.rb', line 1205

def unpaired_mutant_count
  @unpaired.each_value.sum { |count| count.is_a?(Integer) ? count : 0 }
end

#unpaired_scope_share ⇒ Float? (private)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Unpaired mutants over the scope denominator. The denominator is total - ignored + unpaired. nil when it must be omitted.

Returns:

  • (Float, nil)


1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
# File 'lib/mutineer/reporter.rb', line 1243

def unpaired_scope_share
  return if @fail_fast

  count = unpaired_mutant_count
  return if count.zero?

  denominator = @agg.total - @agg.ignored_count + count
  return if denominator <= 0

  (count * 100.0 / denominator).round(1)
end

#unpaired_sources_json ⇒ Array<Hash> (private)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

unpaired_sources[] sorted by file. A nil count stays nil, so JSON writes null.

Returns:

  • (Array<Hash>)


1213
1214
1215
# File 'lib/mutineer/reporter.rb', line 1213

def unpaired_sources_json
  @unpaired.map { |file, count| { file: file, mutants: count } }.sort_by { |row| row[:file].to_s }
end

#unrun_for_share ⇒ Integer (private)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Unrun mutants in the share. --fail-fast leaves unpaired mutants out.

Returns:

  • (Integer)


1186
1187
1188
1189
1190
# File 'lib/mutineer/reporter.rb', line 1186

def unrun_for_share
  return @agg.unrun_count unless unpaired_in_share?

  @agg.unrun_count + unpaired_mutant_count
end

#unrun_share_exceeded? ⇒ Boolean (private)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Whether the unrun mutants are more than BROKEN_FLOOR and more than UNRUN_SHARE_LIMIT of attempted plus unrun. A run with no result rows does not warn here. The empty-run message owns that case.

Returns:

  • (Boolean) —

    true when the unrun-share warning applies.



1175
1176
1177
1178
1179
1180
# File 'lib/mutineer/reporter.rb', line 1175

def unrun_share_exceeded?
  return false if @agg.total.zero?

  unrun = unrun_for_share
  unrun > BROKEN_FLOOR && unrun > UNRUN_SHARE_LIMIT * (attempted_count + unrun)
end

#utf8_text(text) ⇒ String (private)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

text as valid UTF-8. A valid string in another encoding is transcoded. Invalid bytes become \xNN.

Parameters:

  • text (String)

Returns:

  • (String)


1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
# File 'lib/mutineer/reporter.rb', line 1417

def utf8_text(text)
  str = text.to_s
  return str if str.encoding == Encoding::UTF_8 && str.valid_encoding?
  # ASCII-8BIT is "valid" for every byte, and encode raises on a byte
  # UTF-8 cannot hold. Those bytes fall through and print as \xNN.
  if str.encoding != Encoding::ASCII_8BIT && str.valid_encoding?
    return str.encode(Encoding::UTF_8)
  end

  str.dup.force_encoding(Encoding::UTF_8)
     .scrub { |bytes| bytes.unpack("C*").map { |b| format("\\x%02X", b) }.join }
end

#verdict(out, threshold) ⇒ void (private)

This method returns an undefined value.

Writes the final verdict line.

Parameters:

  • out (IO) —

    output stream.

  • threshold (Float) —

    score threshold.



1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
# File 'lib/mutineer/reporter.rb', line 1451

def verdict(out, threshold)
  score = @agg.mutation_score
  if score.nil?
    if broken_nil_score?
      out.puts "FAILED: no covered mutants (#{broken_counts_detail}); " \
               "threshold #{threshold}% cannot pass with a broken harness"
    end
    return
  end

  # Same rule as exit_code, or the report says PASSED on a run that exits 1 —
  # and with --output that wrong verdict is what gets archived.
  passed = @agg.meets_threshold?(threshold)
  if broken_share_exceeded?
    out.puts "FAILED: #{no_verdict_ratio}; #{score}% covers only part of the run"
  elsif passed != (score >= threshold)
    # The rounded score points the other way, so give the exact counts.
    out.puts "#{passed ? 'PASSED' : 'FAILED'}: #{@agg.killed_count} of #{@agg.covered_count} killed " \
             "#{passed ? 'meets' : 'is below'} threshold #{threshold}% (the #{score}% score is rounded)"
  elsif passed
    out.puts "PASSED: #{score}% >= threshold #{threshold}%"
  else
    out.puts "FAILED: #{score}% < threshold #{threshold}%"
  end
end

#warn_errors_without_gate(err) ⇒ void

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

This method returns an undefined value.

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.

Parameters:

  • err (IO) —

    error stream.



144
145
146
147
148
149
150
151
152
# File 'lib/mutineer/reporter.rb', line 144

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

#warn_unrun_share(err) ⇒ void

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

This method returns an undefined value.

Warns when the unrun mutants (unplaceable plus skipped invalid) are more than UNRUN_SHARE_LIMIT of the mutants the run tried to score, and more than BROKEN_FLOOR. Every format, with or without --threshold; the exit code does not change.

Parameters:

  • err (IO) —

    error stream.



162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
# File 'lib/mutineer/reporter.rb', line 162

def warn_unrun_share(err)
  return unless unrun_share_exceeded?

  include_unpaired = unpaired_in_share?
  unrun = unrun_for_share
  tried = attempted_count + unrun
  parts = []
  parts << "#{@agg.unplaceable_count} unplaceable" if @agg.unplaceable_count.positive?
  parts << "#{@agg.skipped_invalid_count} skipped (invalid)" if @agg.skipped_invalid_count.positive?
  parts << "#{unpaired_mutant_count} in sources with no paired test" if include_unpaired
  pct = (unrun * 100.0 / tried).round(1)
  message = +"[mutineer] #{unrun} of the #{tried} mutants mutineer tried to score were not run " \
             "(#{parts.join(', ')}; #{pct}%, limit #{(UNRUN_SHARE_LIMIT * 100).round}%). " \
             "The score leaves them out. This warning does not change the exit code."
  if @agg.unplaceable_count.positive?
    message << " See unplaceable[] in --format json; --test-command runs them."
  end
  if @agg.skipped_invalid_count.positive?
    message << " A mutant skipped (invalid) did not re-parse after mutation. If its source file " \
               "parses on its own, that is a mutineer bug: please report it at " \
               "https://github.com/davidteren/mutineer/issues, with the source file and " \
               "these versions: Ruby #{RUBY_VERSION}, Prism #{Prism::VERSION}."
  end
  message << " #{UNPAIRED_SHARE_HINT}" if include_unpaired
  err.puts message
end