mutineer 1.8.2 → 1.9.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (51) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +611 -0
  3. data/README.md +84 -49
  4. data/lib/mutineer/changed_lines.rb +2 -1
  5. data/lib/mutineer/child_cause.rb +149 -0
  6. data/lib/mutineer/child_stdout.rb +12 -1
  7. data/lib/mutineer/cli.rb +536 -58
  8. data/lib/mutineer/command_redact.rb +38 -0
  9. data/lib/mutineer/config.rb +112 -6
  10. data/lib/mutineer/coverage_map.rb +1345 -156
  11. data/lib/mutineer/daemon_backend.rb +40 -17
  12. data/lib/mutineer/daemon_client.rb +63 -15
  13. data/lib/mutineer/daemon_server.rb +75 -5
  14. data/lib/mutineer/database_urls.rb +189 -0
  15. data/lib/mutineer/external_backend.rb +47 -1
  16. data/lib/mutineer/fs_path.rb +125 -0
  17. data/lib/mutineer/isolation.rb +374 -20
  18. data/lib/mutineer/job_plan.rb +349 -39
  19. data/lib/mutineer/minitest_integration/file_order.rb +56 -0
  20. data/lib/mutineer/minitest_integration/in_test_database_error.rb +243 -19
  21. data/lib/mutineer/minitest_integration.rb +26 -58
  22. data/lib/mutineer/mutant_id.rb +4 -1
  23. data/lib/mutineer/mutation.rb +6 -1
  24. data/lib/mutineer/mutator_registry.rb +6 -3
  25. data/lib/mutineer/mutators/collection_method.rb +195 -6
  26. data/lib/mutineer/mutators/literal_mutation.rb +33 -3
  27. data/lib/mutineer/mutators/range_literal.rb +78 -29
  28. data/lib/mutineer/mutators/rescue_body.rb +126 -0
  29. data/lib/mutineer/mutators/return_nil.rb +23 -6
  30. data/lib/mutineer/output_filter.rb +451 -0
  31. data/lib/mutineer/pairing.rb +463 -31
  32. data/lib/mutineer/parser.rb +14 -0
  33. data/lib/mutineer/project_path.rb +15 -8
  34. data/lib/mutineer/rails_worker_db.rb +356 -6
  35. data/lib/mutineer/reach_probe.rb +229 -0
  36. data/lib/mutineer/redaction.rb +264 -32
  37. data/lib/mutineer/reload_guards.rb +460 -39
  38. data/lib/mutineer/reporter.rb +465 -57
  39. data/lib/mutineer/result.rb +6 -7
  40. data/lib/mutineer/run_seed.rb +16 -0
  41. data/lib/mutineer/runner.rb +175 -51
  42. data/lib/mutineer/source_bytes.rb +187 -0
  43. data/lib/mutineer/statement_lines.rb +108 -14
  44. data/lib/mutineer/test_runners/rspec.rb +118 -10
  45. data/lib/mutineer/test_runners/rspec_seed.rb +151 -0
  46. data/lib/mutineer/test_runners.rb +3 -2
  47. data/lib/mutineer/triage.rb +55 -10
  48. data/lib/mutineer/version.rb +1 -1
  49. data/lib/mutineer.rb +1 -0
  50. data/skills/mutineer/SKILL.md +12 -4
  51. metadata +12 -1
@@ -4,6 +4,7 @@ require "json"
4
4
  require "stringio"
5
5
  require "cgi"
6
6
  require_relative "mutation"
7
+ require_relative "redaction"
7
8
 
8
9
  module Mutineer
9
10
  # Renders an AggregateResult: the summary block, mutation score, and per-file
@@ -25,13 +26,22 @@ module Mutineer
25
26
  # workflow, so one bad mutant never fails the gate on its own, at any size.
26
27
  BROKEN_FLOOR = 1
27
28
 
28
- # Share of the mutants a run tried to score that may go unrun (unplaceable or
29
- # skipped invalid) before stderr warns. A warning only: it never changes the
30
- # exit code. {BROKEN_FLOOR} also applies, so one unrun mutant never warns.
29
+ # Share of the mutants a run tried to score that may go unrun (unplaceable,
30
+ # skipped invalid, or unpaired) before stderr warns. A warning only: it
31
+ # never changes the exit code. {BROKEN_FLOOR} also applies, so one unrun
32
+ # mutant never warns. `--fail-fast` leaves unpaired mutants out of this share.
33
+ # Measured on Fizzy at f220e4832 (#349): unplaceable plus skipped invalid were
34
+ # 0.12% with the default operators and at most 2.8% with all 21, so 10% stays.
35
+ # With its unpaired mutants the share was 15.2%. That warning is correct.
31
36
  UNRUN_SHARE_LIMIT = 0.10
32
37
 
33
38
  # The JSON report's `schema_version` (see docs/json-schema.md).
34
- SCHEMA_VERSION = "1.9"
39
+ SCHEMA_VERSION = "1.10"
40
+
41
+ # The unrun-share hint for mutants in sources with no paired test.
42
+ # The CLI keeps a shorter copy for the empty-run message.
43
+ UNPAIRED_SHARE_HINT = "See unpaired_sources[] in --format json. To run them, add a test " \
44
+ "at the conventional path, or run those sources in a separate command with --test."
35
45
 
36
46
  # The warning both matrix renderers give under the redundant tests.
37
47
  MATRIX_REDUNDANT_NOTE = "Delete redundant tests one at a time: two of them can be the only killers of one mutant."
@@ -44,10 +54,17 @@ module Mutineer
44
54
  # @param source_map [Hash{String => String}] source file path => source text.
45
55
  # @param matrix [Mutineer::KillMatrix, nil] the kill matrix of a `--matrix`
46
56
  # run; nil leaves every format exactly as it is without the flag.
47
- def initialize(aggregate, source_map, matrix: nil)
57
+ # @param unpaired [Hash{String => Integer, nil}] file => mutant count for
58
+ # sources pairing skipped. nil means the count failed. Default is empty.
59
+ # @param fail_fast [Boolean] when true, unpaired mutants stay out of the
60
+ # unrun share and the human scope percentage.
61
+ def initialize(aggregate, source_map, matrix: nil, unpaired: {}, fail_fast: false)
48
62
  @agg = aggregate
49
63
  @source_map = source_map
50
64
  @matrix = matrix
65
+ @unpaired = unpaired
66
+ @fail_fast = fail_fast
67
+ @copies = {}
51
68
  end
52
69
 
53
70
  # Single entry point. Branches on `format` ("human" | "json" | "html") and
@@ -57,18 +74,39 @@ module Mutineer
57
74
  # `--baseline` load) knows the score covers only the changed-line mutants.
58
75
  # `legacy_id_matches` (`{ignore:, baseline:}`) counts stored ids still in the
59
76
  # old format (#126); only the JSON report records it (`summary.legacy_id_matches`).
77
+ # `unmatched_ignores` is the `ignore:` ids that matched no mutant in this
78
+ # run (#377); only the JSON report records them (`summary.unmatched_ignores`).
79
+ # An empty list under `--only` means the check was skipped, not that every
80
+ # entry matched.
60
81
  # `declined` (operator name => count, from {JobPlan.collect_jobs}) counts the
61
82
  # candidates the operators did not mutate; the JSON and human reports show it.
83
+ # `subjects` (methods discovered) and `unmutated_subjects` (one
84
+ # `{subject:, file:, line:}` hash per method the operators did not mutate,
85
+ # from {JobPlan.collect_jobs}, #386) feed the same two reports. Left out,
86
+ # they are unknown: JSON reports null and the human report has no row. The
87
+ # two are one unit: when either is left out, both are unknown.
88
+ # `copies` (kept mutant id => dropped repeat ids, from {JobPlan.collect_jobs},
89
+ # #374) is listed on each kept mutant and counted in `summary.dropped`.
90
+ # An empty hash reports zero. The count covers mutants in this report,
91
+ # so `--fail-fast` leaves out copies of mutants it did not schedule.
62
92
  def report(out: $stdout, err: $stderr, threshold: 0.0, format: "human", output: nil,
63
- baseline: nil, scoped: false, legacy_id_matches: { ignore: 0, baseline: 0 }, declined: {})
93
+ baseline: nil, scoped: false, legacy_id_matches: { ignore: 0, baseline: 0 },
94
+ unmatched_ignores: [], declined: {},
95
+ subjects: nil, unmutated_subjects: nil, copies: {})
96
+ @copies = copies || {}
97
+ subjects = unmutated_subjects = nil if subjects.nil? || unmutated_subjects.nil?
64
98
  rendered =
65
99
  if format == "json"
66
- json_report(baseline, scoped: scoped, legacy_id_matches: legacy_id_matches, declined: declined)
100
+ json_report(baseline, scoped: scoped, legacy_id_matches: legacy_id_matches,
101
+ unmatched_ignores: unmatched_ignores, declined: declined,
102
+ subjects: subjects, unmutated_subjects: unmutated_subjects)
67
103
  elsif format == "html"
68
- html_report
104
+ html_report(declined: declined, subjects: subjects, unmutated: unmutated_subjects&.size,
105
+ scoped: scoped)
69
106
  else
70
107
  sio = StringIO.new
71
- human_report(sio, err, threshold, declined: declined, scoped: scoped)
108
+ human_report(sio, err, threshold, declined: declined, scoped: scoped,
109
+ subjects: subjects, unmutated: unmutated_subjects&.size)
72
110
  baseline_section(sio, baseline) if baseline
73
111
  sio.string
74
112
  end
@@ -124,11 +162,13 @@ module Mutineer
124
162
  def warn_unrun_share(err)
125
163
  return unless unrun_share_exceeded?
126
164
 
127
- unrun = @agg.unrun_count
165
+ include_unpaired = unpaired_in_share?
166
+ unrun = unrun_for_share
128
167
  tried = attempted_count + unrun
129
168
  parts = []
130
169
  parts << "#{@agg.unplaceable_count} unplaceable" if @agg.unplaceable_count.positive?
131
170
  parts << "#{@agg.skipped_invalid_count} skipped (invalid)" if @agg.skipped_invalid_count.positive?
171
+ parts << "#{unpaired_mutant_count} in sources with no paired test" if include_unpaired
132
172
  pct = (unrun * 100.0 / tried).round(1)
133
173
  message = +"[mutineer] #{unrun} of the #{tried} mutants mutineer tried to score were not run " \
134
174
  "(#{parts.join(', ')}; #{pct}%, limit #{(UNRUN_SHARE_LIMIT * 100).round}%). " \
@@ -142,6 +182,7 @@ module Mutineer
142
182
  "https://github.com/davidteren/mutineer/issues, with the source file and " \
143
183
  "these versions: Ruby #{RUBY_VERSION}, Prism #{Prism::VERSION}."
144
184
  end
185
+ message << " #{UNPAIRED_SHARE_HINT}" if include_unpaired
145
186
  err.puts message
146
187
  end
147
188
 
@@ -152,15 +193,21 @@ module Mutineer
152
193
  # @param threshold [Float] score threshold.
153
194
  # @param declined [Hash{String => Integer}] operator name => declined count.
154
195
  # @param scoped [Boolean] the run was diff-scoped (`--since`).
196
+ # @param subjects [Integer, nil] methods discovered; nil when unknown.
197
+ # @param unmutated [Integer, nil] methods the selected operators did not mutate; nil when unknown.
155
198
  # @return [void]
156
- def human_report(out, err, threshold, declined: {}, scoped: false)
199
+ def human_report(out, err, threshold, declined: {}, scoped: false, subjects: nil, unmutated: nil)
157
200
  # The CLI explains an empty run for every format (CLI.warn_empty_run).
158
- return if @agg.total.zero?
201
+ # A saved report still carries the unpaired counts.
202
+ if @agg.total.zero?
203
+ out.puts unpaired_line(scoped) unless @unpaired.empty?
204
+ return
205
+ end
159
206
 
160
207
  out.puts "Mutineer — Mutation Results"
161
208
  out.puts "========================="
162
209
  out.puts
163
- summary(out, declined: declined, scoped: scoped)
210
+ summary(out, declined: declined, scoped: scoped, subjects: subjects, unmutated: unmutated)
164
211
  out.puts
165
212
  score_line(out, err)
166
213
  per_source(out)
@@ -207,11 +254,22 @@ module Mutineer
207
254
  # @param legacy_id_matches [Hash{Symbol => Integer}] `{ignore:, baseline:}`:
208
255
  # old-format ignore entries that matched, and survivors matched in an
209
256
  # old-format baseline only through their old id (#126).
257
+ # @param unmatched_ignores [Array<String>] `ignore:` ids that matched no
258
+ # mutant in this run, in file order, each once (#377). Empty under
259
+ # `--only`, which skips the check.
210
260
  # @return [String] JSON text.
211
261
  # @param declined [Hash{String => Integer}] operator name => count of
212
262
  # candidates that operator did not mutate (additive `summary.declined`
213
263
  # and `summary.declined_by_operator` keys).
214
- def json_report(baseline = nil, scoped: false, legacy_id_matches: { ignore: 0, baseline: 0 }, declined: {})
264
+ # @param subjects [Integer, nil] methods discovered (additive `summary.subjects`);
265
+ # nil (JSON null) when the caller did not supply it, never a made-up 0.
266
+ # @param unmutated_subjects [Array<Hash>, nil] `{subject:, file:, line:}` per method
267
+ # the operators did not mutate, already sorted (additive
268
+ # `summary.unmutated_subjects` count and top-level `unmutated_subjects[]`);
269
+ # nil (JSON null for both) when not supplied.
270
+ def json_report(baseline = nil, scoped: false, legacy_id_matches: { ignore: 0, baseline: 0 },
271
+ unmatched_ignores: [], declined: {},
272
+ subjects: nil, unmutated_subjects: nil)
215
273
  killed = @agg.killed_count
216
274
  survived = @agg.survived_count
217
275
  # null (not 0.0) on an empty denominator, matching the nil-vs-0.0
@@ -230,6 +288,9 @@ module Mutineer
230
288
  skipped_invalid: @agg.skipped_invalid_count,
231
289
  errored: @agg.errored_count, timeout: @agg.timeout_count,
232
290
  ignored: @agg.ignored_count,
291
+ # Additive (1.10, #374): repeats of a kept mutant that were not run.
292
+ # Not in `total` and not in the score. The ids sit on `copies`.
293
+ dropped: dropped_count,
233
294
  # The gate is computed from these two, so a consumer never re-derives them.
234
295
  attempted: attempted_count, no_verdict: no_verdict_count,
235
296
  score: score,
@@ -245,13 +306,31 @@ module Mutineer
245
306
  # the number of old-format ignore entries that matched; `baseline` the
246
307
  # survivors matched in the baseline only through their old id.
247
308
  legacy_id_matches: legacy_id_matches,
309
+ # Additive (1.10, #377): ignore ids that matched no mutant in this
310
+ # run's sources and operators. File order, each id once. Empty under
311
+ # --only, because that check is skipped. The exit code stays 0.
312
+ unmatched_ignores: unmatched_ignores,
248
313
  # Additive (1.9, #291): candidates the operators found and did not
249
314
  # mutate (a heredoc split or an equivalent skip), so not in `total`.
250
315
  declined: declined.values.sum,
251
- declined_by_operator: declined
316
+ declined_by_operator: declined,
317
+ # Additive (1.10, #381): sources pairing skipped, and the mutants in
318
+ # them. A nil count is left out of the mutant sum.
319
+ unpaired_sources: @unpaired.size,
320
+ unpaired_mutants: unpaired_mutant_count,
321
+ # Additive (1.10, #386): methods discovered, and how many of them the
322
+ # selected operators did not mutate. Not mutants, so not in `total`.
323
+ subjects: subjects,
324
+ unmutated_subjects: unmutated_subjects&.size
252
325
  },
253
326
  survivors: @agg.surviving_mutants.map { |r| survivor_json(r) }
254
327
  .sort_by { |h| [h[:file], h[:line], h[:operator]] },
328
+ # Additive (1.10, #361): every killed mutant's lean identity so two runs
329
+ # can be joined by id without subtracting every unscored category.
330
+ # to_s/to_i: lean_mutant_json can leave null fields when a stub result
331
+ # lacks a subject (same rule as no_verdict[]).
332
+ killed: @agg.results.select(&:killed?).map { |r| mutant_json(r) }
333
+ .sort_by { |h| [h[:file].to_s, h[:line].to_i, h[:operator].to_s, h[:id].to_s] },
255
334
  # id extends the key to a total order: several mutants share a line.
256
335
  no_coverage: @agg.results.select(&:no_coverage?).map { |r| mutant_json(r) }
257
336
  .sort_by { |h| [h[:file], h[:line], h[:operator], h[:id].to_s] },
@@ -287,14 +366,20 @@ module Mutineer
287
366
  # Per-source breakdown (additive; baseline consumes it). Sorted by file so
288
367
  # output is byte-stable. Reuses AggregateResult via by_source.
289
368
  per_source: @agg.by_source.map { |file, agg| per_source_json(file, agg) }
290
- .sort_by { |h| h[:file] }
369
+ .sort_by { |h| h[:file] },
370
+ # Additive (1.10, #381): every source pairing skipped, sorted by file.
371
+ # `mutants` is null when the count failed.
372
+ unpaired_sources: unpaired_sources_json,
373
+ # Additive (1.10, #386): the methods the selected operators did not
374
+ # mutate, sorted by (file, line, subject) in JobPlan.collect_jobs.
375
+ unmutated_subjects: unmutated_subjects
291
376
  }
292
377
  # Additive (1.5): the kill matrix, present only with --matrix.
293
378
  doc[:matrix] = matrix_json if @matrix
294
379
  # Additive baseline-delta block, present only with --baseline. Existing
295
380
  # consumers ignore the extra key; it does not move schema_version on its own.
296
381
  doc[:baseline] = baseline_json(baseline) if baseline
297
- "#{JSON.generate(doc)}\n"
382
+ "#{JSON.generate(json_safe(doc))}\n"
298
383
  end
299
384
 
300
385
  # One self-contained HTML file (inline CSS, no external assets): the overall
@@ -303,7 +388,12 @@ module Mutineer
303
388
  # (CGI.escapeHTML) so a `<`/`>` in source can never break the markup. Reuses
304
389
  # survivor_json/per_source_json so one run yields one set of facts regardless
305
390
  # of --format.
306
- def html_report
391
+ # @param declined [Hash{String => Integer}] candidates declined by operators.
392
+ # @param subjects [Integer, nil] methods discovered (in scope).
393
+ # @param unmutated [Integer, nil] methods with no mutants (#419).
394
+ # @param scoped [Boolean] the run was diff-scoped (`--since`); declined keeps
395
+ # its full-run count and the HTML label says so.
396
+ def html_report(declined: {}, subjects: nil, unmutated: nil, scoped: false)
307
397
  score = @agg.mutation_score
308
398
  survivors = @agg.surviving_mutants.map { |r| survivor_json(r) }
309
399
  .sort_by { |h| [h[:file], h[:line], h[:operator]] }
@@ -343,7 +433,8 @@ module Mutineer
343
433
  <body>
344
434
  <h1>Mutineer — Mutation Report</h1>
345
435
  <div class="score">Score: #{score.nil? ? 'N/A' : "#{score}%"}</div>
346
- #{summary_html}
436
+ #{summary_html(declined: declined, subjects: subjects, unmutated: unmutated, scoped: scoped)}
437
+ #{unpaired_html}
347
438
  #{per_source_html(per_source)}
348
439
  #{survivors_html(survivors)}
349
440
  #{ignored_html}
@@ -354,15 +445,31 @@ module Mutineer
354
445
  end
355
446
 
356
447
  # The summary counts block for the HTML header.
357
- def summary_html
448
+ #
449
+ # @param declined [Hash{String => Integer}]
450
+ # @param subjects [Integer, nil]
451
+ # @param unmutated [Integer, nil]
452
+ # @param scoped [Boolean] when true, the declined label notes it is not
453
+ # narrowed by `--since` (same wording as the human report).
454
+ def summary_html(declined: {}, subjects: nil, unmutated: nil, scoped: false)
358
455
  counts = {
359
456
  "total" => @agg.total, "killed" => @agg.killed_count,
360
457
  "survived" => @agg.survived_count, "no_coverage" => @agg.no_coverage_count,
361
458
  "uncapturable" => @agg.uncapturable_count, "unplaceable" => @agg.unplaceable_count,
362
459
  "ran_at_load" => @agg.ran_at_load_count, "ignored" => @agg.ignored_count,
460
+ "dropped" => dropped_count,
363
461
  "skipped" => @agg.skipped_invalid_count,
364
- "errored" => @agg.errored_count, "timeout" => @agg.timeout_count
462
+ "errored" => @agg.errored_count, "timeout" => @agg.timeout_count,
463
+ "unpaired" => unpaired_mutant_count
365
464
  }
465
+ if declined.any?
466
+ label = scoped ? "declined (not narrowed by --since)" : "declined"
467
+ counts[label] = declined.values.sum
468
+ end
469
+ if subjects && unmutated
470
+ counts["no_mutants"] = unmutated
471
+ counts["methods"] = subjects
472
+ end
366
473
  spans = counts.map { |k, v| "<span><strong>#{v}</strong> #{esc(k)}</span>" }.join("\n ")
367
474
  "<div class=\"counts\">\n #{spans}\n</div>"
368
475
  end
@@ -401,6 +508,7 @@ module Mutineer
401
508
  <div class="survivor">
402
509
  <h3>#{esc(s[:subject])}</h3>
403
510
  <div class="meta">#{esc(s[:file])}:#{s[:line]} &middot; #{esc(s[:operator])} &middot; <span class="id">#{esc(s[:id])}</span></div>
511
+ #{copies_html(s[:copies])}
404
512
  <pre class="diff">#{diff_lines}</pre>
405
513
  </div>
406
514
  CARD
@@ -424,6 +532,7 @@ module Mutineer
424
532
  <h3>#{esc(row[:subject])}</h3>
425
533
  <div class="meta">#{esc(row[:file])}:#{row[:line]} &middot; #{esc(row[:operator])} &middot; <span class="id">#{esc(row[:id])}</span></div>
426
534
  #{reason}
535
+ #{copies_html(row[:copies])}
427
536
  </div>
428
537
  CARD
429
538
  end.join("\n")
@@ -611,7 +720,7 @@ module Mutineer
611
720
  end
612
721
 
613
722
  # HTML-escapes any text destined for the document (stdlib CGI).
614
- def esc(text) = CGI.escapeHTML(text.to_s)
723
+ def esc(text) = CGI.escapeHTML(utf8_text(text))
615
724
 
616
725
  # The same delta facts the human report prints, for dashboards. new_survivors
617
726
  # reuse the mutant_json shape (subject/file/line/operator/token/id) and sort
@@ -664,19 +773,21 @@ module Mutineer
664
773
  at_eof = source.byteindex("\n", m.end_offset).nil?
665
774
  old_lines = side_lines(original_block, at_eof)
666
775
  new_lines = side_lines(mutated_block, at_eof)
667
- {
668
- subject: result.subject.qualified_name,
776
+ shown_file = utf8_text(file)
777
+ row = {
778
+ subject: utf8_text(result.subject.qualified_name.to_s),
669
779
  file: file,
670
780
  line: start_line,
671
781
  operator: m.operator.to_s,
672
782
  # The stable, copy-pasteable id (next to the human-readable token) so a
673
783
  # user can paste it straight into .mutineer.yml `ignore:`.
674
784
  id: result.id,
675
- token: token,
676
- diff: "--- a/#{file}\n+++ b/#{file}\n" \
785
+ token: utf8_text(token),
786
+ diff: "--- a/#{shown_file}\n+++ b/#{shown_file}\n" \
677
787
  "@@ -#{hunk_range(start_line, old_lines)} +#{hunk_range(start_line, new_lines)} @@\n" \
678
788
  "#{diff_body("-", old_lines)}#{diff_body("+", new_lines)}"
679
789
  }
790
+ attach_copies(row, result.id)
680
791
  end
681
792
 
682
793
  # One side of the diff as the file holds it: the {#diff_for} block plus the
@@ -689,7 +800,9 @@ module Mutineer
689
800
  # @param at_eof [Boolean] no newline follows the block in the file.
690
801
  # @return [Array<String>] its lines, with their endings.
691
802
  def side_lines(block, at_eof)
692
- (at_eof ? block : "#{block}\n").lines
803
+ newline = "\n".dup.force_encoding(block.encoding)
804
+ text = at_eof ? block : block + newline
805
+ text.lines.map { |line| utf8_text(line) }
693
806
  end
694
807
 
695
808
  # The `-` or `+` lines of one side. A line with no newline is the file's
@@ -729,25 +842,91 @@ module Mutineer
729
842
  end
730
843
 
731
844
  # The fields that name one mutant, for the lists that point at mutants:
732
- # `no_coverage`, `uncapturable`, `unplaceable`, `ran_at_load`, `ignored` and
733
- # `baseline.new_survivors`.
845
+ # `killed`, `no_coverage`, `uncapturable`, `unplaceable`, `ran_at_load`,
846
+ # `ignored` and `baseline.new_survivors`.
734
847
  #
735
848
  # @api private
736
849
  # @param result [Mutineer::Result] the mutant result.
737
850
  # @return [Hash] subject, file, line, operator, token, and id.
738
851
  def mutant_json(result)
739
- m = result.mutation
740
- file = result.subject.file
852
+ lean_mutant_json(result.subject, result.mutation, result.id)
853
+ end
854
+
855
+ # Lean mutant identity shared by run-report lists and `--dry-run --format json`.
856
+ #
857
+ # @api private
858
+ # @param subject [Mutineer::Subject] the mutated subject.
859
+ # @param mutation [Mutineer::Mutation] the mutation.
860
+ # @param id [String, nil] the stable mutant id.
861
+ # @return [Hash] subject, file, line, operator, token, and id.
862
+ def lean_mutant_json(subject, mutation, id)
863
+ # Stub results in tests (and rare pre-attach kills) can lack a subject.
864
+ # Match no_verdict_json: null fields rather than raising.
865
+ if subject.nil? || mutation.nil?
866
+ return attach_copies({
867
+ subject: nil, file: nil, line: nil, operator: nil, token: nil, id: id
868
+ }, id)
869
+ end
870
+
871
+ file = subject.file
741
872
  source = source_for(file)
742
- start_line, _orig, _mut, token = diff_for(m, source)
743
- {
744
- subject: result.subject.qualified_name,
873
+ start_line, _orig, _mut, token = diff_for(mutation, source)
874
+ attach_copies({
875
+ subject: subject.qualified_name,
745
876
  file: file,
746
877
  line: start_line,
747
- operator: m.operator.to_s,
878
+ operator: mutation.operator.to_s,
748
879
  token: token,
749
- id: result.id
880
+ id: id
881
+ }, id)
882
+ end
883
+
884
+ # JSON for `--dry-run --format json`: every valid candidate with its stable
885
+ # id, plus summary totals. Ids match a later real run of the same JobPlan.
886
+ # Callers partition with {Mutation#valid?} once and pass only valid jobs;
887
+ # this method does not re-validate.
888
+ #
889
+ # @param jobs [Array<Array>] valid `(subject, mutation, id)` triples from
890
+ # {JobPlan.collect_jobs} (after {JobPlan.scope_since}).
891
+ # @param source_map [Hash{String => String}] source file path => source text.
892
+ # @param declined [Hash{String => Integer}] operator name => declined count.
893
+ # @param skipped_invalid [Integer] candidates that did not re-parse.
894
+ # @param ignored [Integer] suppressed candidates.
895
+ # @param unmatched_ignores [Array<String>] `ignore:` ids that matched no
896
+ # mutant (#377), the same list a real run records.
897
+ # @param copies [Hash{String => Array<String>}] kept id => dropped repeat
898
+ # ids (#374). Each listed mutant gains `copies` when it has any.
899
+ # `summary.dropped` counts every id in `copies`, including a repeat of
900
+ # an ignored mutant, which this document does not list.
901
+ # @return [String] JSON text.
902
+ def self.dry_run_json(jobs, source_map, declined: {}, skipped_invalid: 0, ignored: 0,
903
+ unmatched_ignores: [], copies: {})
904
+ reporter = new(AggregateResult.new([]), source_map)
905
+ reporter.send(:apply_copies, copies)
906
+ by_operator = Hash.new(0)
907
+ mutants = jobs.map do |subject, mutation, id|
908
+ by_operator[mutation.operator.to_s] += 1
909
+ reporter.__send__(:lean_mutant_json, subject, mutation, id)
910
+ end
911
+ mutants.sort_by! { |h| [h[:file].to_s, h[:line].to_i, h[:operator].to_s, h[:id].to_s] }
912
+ doc = {
913
+ schema_version: SCHEMA_VERSION,
914
+ summary: {
915
+ # Same marker as a completed report: absent means the old id format.
916
+ id_format: 2,
917
+ total: mutants.size,
918
+ skipped_invalid: skipped_invalid,
919
+ ignored: ignored,
920
+ # Same list as a completed report (#377). Absent means an older dry run.
921
+ unmatched_ignores: unmatched_ignores,
922
+ dropped: dropped_count_for(copies),
923
+ declined: declined.values.sum,
924
+ declined_by_operator: declined,
925
+ by_operator: by_operator.sort.to_h
926
+ },
927
+ mutants: mutants
750
928
  }
929
+ "#{JSON.generate(reporter.__send__(:json_safe, doc))}\n"
751
930
  end
752
931
 
753
932
  # Builds a line-aligned diff for a mutation whose byte range may span several
@@ -762,30 +941,113 @@ module Mutineer
762
941
  before = source.byteslice(line_begin...m.start_offset)
763
942
  after = source.byteslice(m.end_offset...line_end)
764
943
  original_block = source.byteslice(line_begin...line_end)
765
- mutated_block = "#{before}#{m.replacement}#{after}"
944
+ replacement = m.replacement
945
+ replacement = replacement.dup.force_encoding(before.encoding) if replacement.ascii_only?
946
+ mutated_block = before + replacement + after
766
947
  start_line = source.byteslice(0, m.start_offset).count("\n") + 1
767
948
  token = source.byteslice(m.start_offset...m.end_offset).gsub(/\s+/, " ").strip
768
- token = "#{token[0, 47]}..." if token.length > 50
949
+ if token.length > 50
950
+ token = token[0, 47] + "...".dup.force_encoding(token.encoding)
951
+ end
769
952
  [start_line, original_block, mutated_block, token]
770
953
  end
771
954
 
772
955
  # An entry under the JSON `no_verdict:` key: an attempted mutant with no verdict.
773
956
  # A pre-fork failure has no subject or mutation attached, so those degrade to
774
957
  # nulls rather than dropping the entry — the count must still reconcile with
775
- # `summary.no_verdict`.
958
+ # `summary.no_verdict`. `details` is redacted here too, whatever its source
959
+ # (#388).
776
960
  #
777
961
  # @api private
778
962
  # @param result [Mutineer::Result] an errored or timed-out result.
779
963
  # @return [Hash] no-verdict JSON object.
780
964
  def no_verdict_json(result)
781
- {
965
+ file = result.subject&.file
966
+ # As in result_line: diff_for needs the source, so a mutation needs a file.
967
+ m = result.mutation if file
968
+ line, _orig, _mut, token = diff_for(m, source_for(file)) if m
969
+ row = {
782
970
  subject: result.subject&.qualified_name,
783
- file: result.subject&.file,
784
- line: result_line(result),
971
+ file: file,
972
+ line: line,
973
+ operator: m&.operator&.to_s,
974
+ token: token,
785
975
  id: result.id,
786
976
  status: result.status.to_s,
787
- details: result.details
977
+ details: result.details && Redaction.text(result.details)
788
978
  }
979
+ attach_copies(row, result.id)
980
+ end
981
+
982
+ # Adds `copies` when this mutant has dropped repeats (#374). Absent when
983
+ # it has none, so a report with no repeats keeps the previous keys.
984
+ #
985
+ # @api private
986
+ # @param row [Hash] one mutant's JSON object.
987
+ # @param id [String, nil] the kept mutant's id.
988
+ # @return [Hash] `row`.
989
+ def attach_copies(row, id)
990
+ list = @copies[id] if id
991
+ row[:copies] = list if list&.any?
992
+ row
993
+ end
994
+
995
+ # Stores the copy map for a reporter built outside {#report}, such as the
996
+ # dry-run document.
997
+ #
998
+ # @api private
999
+ # @param copies [Hash, nil] kept id => dropped ids.
1000
+ # @return [void]
1001
+ def apply_copies(copies)
1002
+ @copies = copies || {}
1003
+ end
1004
+
1005
+ # Dropped repeats of mutants this report lists. A skipped mutant has no
1006
+ # row, so its repeats are not counted. `--fail-fast` omits unscheduled
1007
+ # mutants, and their repeats with them.
1008
+ #
1009
+ # @api private
1010
+ # @return [Integer]
1011
+ def dropped_count
1012
+ @agg.results.sum do |result|
1013
+ next 0 if result.skipped? || result.id.nil?
1014
+
1015
+ @copies[result.id]&.size || 0
1016
+ end
1017
+ end
1018
+
1019
+ # The copy lists for `ids`, or every list when `ids` is nil.
1020
+ #
1021
+ # @param copies [Hash, nil] kept id => dropped ids.
1022
+ # @param ids [Array<String>, nil] kept ids to keep.
1023
+ # @return [Hash{String => Array<String>}]
1024
+ def self.copies_for(copies, ids = nil)
1025
+ map = copies || {}
1026
+ return map if ids.nil?
1027
+
1028
+ wanted = ids.to_set
1029
+ map.select { |id, _list| wanted.include?(id) }
1030
+ end
1031
+
1032
+ # How many dropped ids `copies` holds. With `ids`, only those kept mutants.
1033
+ #
1034
+ # @param copies [Hash, nil] kept id => dropped ids.
1035
+ # @param ids [Array<String>, nil] kept ids to count; nil counts every list.
1036
+ # @return [Integer]
1037
+ def self.dropped_count_for(copies, ids = nil)
1038
+ copies_for(copies, ids).each_value.sum { |list| Array(list).size }
1039
+ end
1040
+
1041
+ # The HTML line of dropped-copy ids, or "" when there are none.
1042
+ #
1043
+ # @api private
1044
+ # @param copies [Array<String>, nil]
1045
+ # @return [String]
1046
+ def copies_html(copies)
1047
+ return "" if copies.nil? || copies.empty?
1048
+
1049
+ ids = copies.map { |id| "<span class=\"id\">#{esc(id)}</span>" }.join(", ")
1050
+ "<div class=\"meta\">copies #{ids}</div>"
789
1051
  end
790
1052
 
791
1053
  # Writes the summary block.
@@ -793,9 +1055,13 @@ module Mutineer
793
1055
  # @param out [IO] output stream.
794
1056
  # @param declined [Hash{String => Integer}] operator name => declined count.
795
1057
  # @param scoped [Boolean] the run was diff-scoped (`--since`), which does not
796
- # narrow the declined count.
1058
+ # narrow the declined count (method counts are already narrowed by
1059
+ # {JobPlan.scope_since}, #420).
1060
+ # @param subjects [Integer, nil] methods discovered; nil when unknown.
1061
+ # @param unmutated [Integer, nil] methods the selected operators did not
1062
+ # mutate; nil when unknown, which leaves out the `No mutants:` row.
797
1063
  # @return [void]
798
- def summary(out, declined: {}, scoped: false)
1064
+ def summary(out, declined: {}, scoped: false, subjects: nil, unmutated: nil)
799
1065
  out.puts "Summary"
800
1066
  out.puts "-------"
801
1067
  out.puts format("Total: %-6d Killed: %d", @agg.total, @agg.killed_count)
@@ -815,8 +1081,19 @@ module Mutineer
815
1081
  # Not mutants: candidates an operator chose not to mutate (#291).
816
1082
  out.puts format("Declined: %-6d (candidates an operator did not mutate; --dry-run shows the count " \
817
1083
  "per operator%s)", declined.values.sum, scoped ? "; not narrowed by --since" : "")
1084
+ # Not mutants: methods, which no operator gave a mutant (#386). Unknown
1085
+ # (a caller passed no method counts) prints no row, never a made-up 0.
1086
+ if subjects && unmutated
1087
+ # Under --since the JobPlan already narrowed these counts (#420).
1088
+ out.puts format("No mutants: %-6d (methods of %d that the selected operators did not mutate; " \
1089
+ "--dry-run --verbose and the JSON report list them)",
1090
+ unmutated, subjects)
1091
+ end
818
1092
  # Equivalent mutants the user suppressed; excluded from the denominator.
819
1093
  out.puts format("Ignored: %-6d (equivalent, suppressed)", @agg.ignored_count)
1094
+ # Repeats that were not run (#374). The ids are on `copies` in the JSON.
1095
+ out.puts format("Dropped: %-6d (repeats of a kept mutant; see --format json)", dropped_count)
1096
+ out.puts unpaired_line(scoped)
820
1097
  end
821
1098
 
822
1099
  # Writes the score line.
@@ -830,7 +1107,7 @@ module Mutineer
830
1107
  "#{@agg.unplaceable_count} unplaceable, #{@agg.ran_at_load_count} ran at load, " \
831
1108
  "#{@agg.skipped_invalid_count} skipped, " \
832
1109
  "#{@agg.errored_count} errored, #{@agg.timeout_count} timeout, " \
833
- "#{@agg.ignored_count} ignored excluded"
1110
+ "#{unpaired_mutant_count} unpaired, #{@agg.ignored_count} ignored excluded"
834
1111
  if score.nil?
835
1112
  out.puts "Mutation score: N/A (no covered mutants)"
836
1113
  # Only the benign case here: the gate-failure explanation is emitted once
@@ -889,16 +1166,112 @@ module Mutineer
889
1166
  @agg.killed_count + @agg.survived_count + no_verdict_count
890
1167
  end
891
1168
 
892
- # Whether the unrun mutants (unplaceable plus skipped invalid) are more than
893
- # {BROKEN_FLOOR} and more than {UNRUN_SHARE_LIMIT} of attempted plus unrun.
1169
+ # Whether the unrun mutants are more than {BROKEN_FLOOR} and more than
1170
+ # {UNRUN_SHARE_LIMIT} of attempted plus unrun. A run with no result rows
1171
+ # does not warn here. The empty-run message owns that case.
894
1172
  #
895
1173
  # @api private
896
1174
  # @return [Boolean] true when the unrun-share warning applies.
897
1175
  def unrun_share_exceeded?
898
- unrun = @agg.unrun_count
1176
+ return false if @agg.total.zero?
1177
+
1178
+ unrun = unrun_for_share
899
1179
  unrun > BROKEN_FLOOR && unrun > UNRUN_SHARE_LIMIT * (attempted_count + unrun)
900
1180
  end
901
1181
 
1182
+ # Unrun mutants in the share. `--fail-fast` leaves unpaired mutants out.
1183
+ #
1184
+ # @api private
1185
+ # @return [Integer]
1186
+ def unrun_for_share
1187
+ return @agg.unrun_count unless unpaired_in_share?
1188
+
1189
+ @agg.unrun_count + unpaired_mutant_count
1190
+ end
1191
+
1192
+ # True when unpaired mutants join the unrun share and the human percentage.
1193
+ # A failed count is not in the sum, so it does not join on its own.
1194
+ #
1195
+ # @api private
1196
+ # @return [Boolean]
1197
+ def unpaired_in_share?
1198
+ !@fail_fast && !@agg.total.zero? && unpaired_mutant_count.positive?
1199
+ end
1200
+
1201
+ # Known unpaired mutant counts. A nil count is left out.
1202
+ #
1203
+ # @api private
1204
+ # @return [Integer]
1205
+ def unpaired_mutant_count
1206
+ @unpaired.each_value.sum { |count| count.is_a?(Integer) ? count : 0 }
1207
+ end
1208
+
1209
+ # `unpaired_sources[]` sorted by file. A nil count stays nil, so JSON writes null.
1210
+ #
1211
+ # @api private
1212
+ # @return [Array<Hash>]
1213
+ def unpaired_sources_json
1214
+ @unpaired.map { |file, count| { file: file, mutants: count } }.sort_by { |row| row[:file].to_s }
1215
+ end
1216
+
1217
+ # The human Unpaired line. The percentage is omitted under `--fail-fast`,
1218
+ # when the denominator is empty, and when the mutant count is 0.
1219
+ #
1220
+ # @api private
1221
+ # @param scoped [Boolean] the run was diff-scoped (`--since`).
1222
+ # @return [String]
1223
+ def unpaired_line(scoped)
1224
+ detail = [scoped ? "mutants on changed lines not run" : "mutants not run"]
1225
+ sources = @unpaired.size
1226
+ detail << (sources == 1 ? "1 source has no paired test" : "#{sources} sources have no paired test")
1227
+ unknown = @unpaired.count { |_file, count| count.nil? }
1228
+ if unknown == 1
1229
+ detail << "1 source not counted"
1230
+ elsif unknown > 1
1231
+ detail << "#{unknown} sources not counted"
1232
+ end
1233
+ share = unpaired_scope_share
1234
+ detail << "#{share}% of the mutants in scope" if share
1235
+ format("Unpaired: %-6d (%s)", unpaired_mutant_count, detail.join("; "))
1236
+ end
1237
+
1238
+ # Unpaired mutants over the scope denominator.
1239
+ # The denominator is `total - ignored + unpaired`. nil when it must be omitted.
1240
+ #
1241
+ # @api private
1242
+ # @return [Float, nil]
1243
+ def unpaired_scope_share
1244
+ return if @fail_fast
1245
+
1246
+ count = unpaired_mutant_count
1247
+ return if count.zero?
1248
+
1249
+ denominator = @agg.total - @agg.ignored_count + count
1250
+ return if denominator <= 0
1251
+
1252
+ (count * 100.0 / denominator).round(1)
1253
+ end
1254
+
1255
+ # The HTML table of sources with no paired test. Empty when none were skipped.
1256
+ #
1257
+ # @api private
1258
+ # @return [String]
1259
+ def unpaired_html
1260
+ return "" if @unpaired.empty?
1261
+
1262
+ rows = @unpaired.sort_by { |file, _count| file.to_s }.map do |file, count|
1263
+ shown = count.nil? ? "unknown" : count.to_s
1264
+ "<tr><td>#{esc(file)}</td><td class=\"num\">#{esc(shown)}</td></tr>"
1265
+ end.join("\n ")
1266
+ <<~HTML.chomp
1267
+ <h2>Sources with no paired test</h2>
1268
+ <table>
1269
+ <tr><th>File</th><th>Mutants</th></tr>
1270
+ #{rows}
1271
+ </table>
1272
+ HTML
1273
+ end
1274
+
902
1275
  # The sentence both the verdict line and the stderr note are built from, so a
903
1276
  # user cannot read one number in the report and a different one beside it.
904
1277
  #
@@ -1013,26 +1386,61 @@ module Mutineer
1013
1386
  end
1014
1387
 
1015
1388
  # The source text of `file`: the run's copy when it has one, else the file
1016
- # read as UTF-8 whatever the locale (#303).
1389
+ # read in its magic-comment encoding, or UTF-8 (#303, #346).
1017
1390
  #
1018
1391
  # @api private
1019
1392
  # @param file [String] source file path.
1020
1393
  # @return [String] source text.
1021
- def source_for(file) = @source_map[file] || File.read(file, encoding: "UTF-8")
1394
+ def source_for(file) = @source_map[file] || Parser.read(file)
1022
1395
 
1023
1396
  # Source text, a method name or a file path made safe for a terminal (#163):
1024
1397
  # each control character except tab becomes its Ruby escape (ESC prints as
1025
- # `\e`). The text is read as UTF-8 whatever the locale, and each byte that is
1026
- # not valid UTF-8 (a Latin-1 source, say) prints as `\xNN`, so nothing is
1027
- # lost and the regex never raises. JSON and HTML escape on their own.
1398
+ # `\e`). A valid string in another encoding (EUC-JP, Shift_JIS) is
1399
+ # transcoded to UTF-8. Bytes that are not valid in their encoding are
1400
+ # read as UTF-8 and each bad byte prints as `\xNN`, so nothing is lost
1401
+ # and the regex never raises (#346). JSON and HTML escape on their own,
1402
+ # after the same transcoding.
1028
1403
  #
1029
1404
  # @api private
1030
1405
  # @param text [String] source text.
1031
1406
  # @return [String] the text with control characters and invalid bytes escaped.
1032
1407
  def printable(text)
1033
- text.dup.force_encoding(Encoding::UTF_8)
1034
- .scrub { |bytes| bytes.unpack("C*").map { |b| format("\\x%02X", b) }.join }
1035
- .gsub(/[[:cntrl:]&&[^\t]]/) { |c| c.dump[1..-2] }
1408
+ utf8_text(text).gsub(/[[:cntrl:]&&[^\t]]/) { |c| c.dump[1..-2] }
1409
+ end
1410
+
1411
+ # `text` as valid UTF-8. A valid string in another encoding is
1412
+ # transcoded. Invalid bytes become `\xNN`.
1413
+ #
1414
+ # @api private
1415
+ # @param text [String]
1416
+ # @return [String]
1417
+ def utf8_text(text)
1418
+ str = text.to_s
1419
+ return str if str.encoding == Encoding::UTF_8 && str.valid_encoding?
1420
+ # ASCII-8BIT is "valid" for every byte, and encode raises on a byte
1421
+ # UTF-8 cannot hold. Those bytes fall through and print as \xNN.
1422
+ if str.encoding != Encoding::ASCII_8BIT && str.valid_encoding?
1423
+ return str.encode(Encoding::UTF_8)
1424
+ end
1425
+
1426
+ str.dup.force_encoding(Encoding::UTF_8)
1427
+ .scrub { |bytes| bytes.unpack("C*").map { |b| format("\\x%02X", b) }.join }
1428
+ end
1429
+
1430
+ # A JSON document with every string as UTF-8 (#346). A path whose bytes
1431
+ # are not UTF-8 is binary, and `JSON.generate` refuses it. Such bytes
1432
+ # print as \xNN, as in the human report.
1433
+ #
1434
+ # @api private
1435
+ # @param value [Object] a document built from Hash, Array, String and scalars.
1436
+ # @return [Object] the same shape, its strings passed through {#utf8_text}.
1437
+ def json_safe(value)
1438
+ case value
1439
+ when String then utf8_text(value)
1440
+ when Hash then value.to_h { |k, v| [json_safe(k), json_safe(v)] }
1441
+ when Array then value.map { |v| json_safe(v) }
1442
+ else value
1443
+ end
1036
1444
  end
1037
1445
 
1038
1446
  # Writes the final verdict line.