mutineer 1.8.1 → 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 (52) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +733 -0
  3. data/README.md +85 -50
  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 +540 -59
  8. data/lib/mutineer/command_redact.rb +38 -0
  9. data/lib/mutineer/concern_blocks.rb +95 -24
  10. data/lib/mutineer/config.rb +112 -6
  11. data/lib/mutineer/coverage_map.rb +1345 -156
  12. data/lib/mutineer/daemon_backend.rb +41 -18
  13. data/lib/mutineer/daemon_client.rb +104 -21
  14. data/lib/mutineer/daemon_server.rb +85 -14
  15. data/lib/mutineer/database_urls.rb +189 -0
  16. data/lib/mutineer/external_backend.rb +93 -6
  17. data/lib/mutineer/fs_path.rb +125 -0
  18. data/lib/mutineer/isolation.rb +380 -25
  19. data/lib/mutineer/job_plan.rb +352 -41
  20. data/lib/mutineer/minitest_integration/file_order.rb +56 -0
  21. data/lib/mutineer/minitest_integration/in_test_database_error.rb +243 -19
  22. data/lib/mutineer/minitest_integration.rb +26 -58
  23. data/lib/mutineer/mutant_id.rb +4 -1
  24. data/lib/mutineer/mutation.rb +10 -4
  25. data/lib/mutineer/mutator_registry.rb +6 -3
  26. data/lib/mutineer/mutators/collection_method.rb +195 -6
  27. data/lib/mutineer/mutators/literal_mutation.rb +33 -3
  28. data/lib/mutineer/mutators/range_literal.rb +78 -29
  29. data/lib/mutineer/mutators/rescue_body.rb +126 -0
  30. data/lib/mutineer/mutators/return_nil.rb +23 -6
  31. data/lib/mutineer/output_filter.rb +451 -0
  32. data/lib/mutineer/pairing.rb +463 -31
  33. data/lib/mutineer/parser.rb +53 -0
  34. data/lib/mutineer/project_path.rb +15 -8
  35. data/lib/mutineer/rails_worker_db.rb +366 -6
  36. data/lib/mutineer/reach_probe.rb +229 -0
  37. data/lib/mutineer/redaction.rb +301 -41
  38. data/lib/mutineer/reload_guards.rb +985 -0
  39. data/lib/mutineer/reporter.rb +467 -58
  40. data/lib/mutineer/result.rb +6 -7
  41. data/lib/mutineer/run_seed.rb +16 -0
  42. data/lib/mutineer/runner.rb +194 -55
  43. data/lib/mutineer/source_bytes.rb +187 -0
  44. data/lib/mutineer/statement_lines.rb +108 -14
  45. data/lib/mutineer/test_runners/rspec.rb +118 -10
  46. data/lib/mutineer/test_runners/rspec_seed.rb +151 -0
  47. data/lib/mutineer/test_runners.rb +3 -2
  48. data/lib/mutineer/triage.rb +55 -10
  49. data/lib/mutineer/version.rb +1 -1
  50. data/lib/mutineer.rb +1 -0
  51. data/skills/mutineer/SKILL.md +12 -4
  52. metadata +13 -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}%). " \
@@ -139,8 +179,10 @@ module Mutineer
139
179
  if @agg.skipped_invalid_count.positive?
140
180
  message << " A mutant skipped (invalid) did not re-parse after mutation. If its source file " \
141
181
  "parses on its own, that is a mutineer bug: please report it at " \
142
- "https://github.com/davidteren/mutineer/issues."
182
+ "https://github.com/davidteren/mutineer/issues, with the source file and " \
183
+ "these versions: Ruby #{RUBY_VERSION}, Prism #{Prism::VERSION}."
143
184
  end
185
+ message << " #{UNPAIRED_SHARE_HINT}" if include_unpaired
144
186
  err.puts message
145
187
  end
146
188
 
@@ -151,15 +193,21 @@ module Mutineer
151
193
  # @param threshold [Float] score threshold.
152
194
  # @param declined [Hash{String => Integer}] operator name => declined count.
153
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.
154
198
  # @return [void]
155
- def human_report(out, err, threshold, declined: {}, scoped: false)
199
+ def human_report(out, err, threshold, declined: {}, scoped: false, subjects: nil, unmutated: nil)
156
200
  # The CLI explains an empty run for every format (CLI.warn_empty_run).
157
- 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
158
206
 
159
207
  out.puts "Mutineer — Mutation Results"
160
208
  out.puts "========================="
161
209
  out.puts
162
- summary(out, declined: declined, scoped: scoped)
210
+ summary(out, declined: declined, scoped: scoped, subjects: subjects, unmutated: unmutated)
163
211
  out.puts
164
212
  score_line(out, err)
165
213
  per_source(out)
@@ -206,11 +254,22 @@ module Mutineer
206
254
  # @param legacy_id_matches [Hash{Symbol => Integer}] `{ignore:, baseline:}`:
207
255
  # old-format ignore entries that matched, and survivors matched in an
208
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.
209
260
  # @return [String] JSON text.
210
261
  # @param declined [Hash{String => Integer}] operator name => count of
211
262
  # candidates that operator did not mutate (additive `summary.declined`
212
263
  # and `summary.declined_by_operator` keys).
213
- 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)
214
273
  killed = @agg.killed_count
215
274
  survived = @agg.survived_count
216
275
  # null (not 0.0) on an empty denominator, matching the nil-vs-0.0
@@ -229,6 +288,9 @@ module Mutineer
229
288
  skipped_invalid: @agg.skipped_invalid_count,
230
289
  errored: @agg.errored_count, timeout: @agg.timeout_count,
231
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,
232
294
  # The gate is computed from these two, so a consumer never re-derives them.
233
295
  attempted: attempted_count, no_verdict: no_verdict_count,
234
296
  score: score,
@@ -244,13 +306,31 @@ module Mutineer
244
306
  # the number of old-format ignore entries that matched; `baseline` the
245
307
  # survivors matched in the baseline only through their old id.
246
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,
247
313
  # Additive (1.9, #291): candidates the operators found and did not
248
314
  # mutate (a heredoc split or an equivalent skip), so not in `total`.
249
315
  declined: declined.values.sum,
250
- 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
251
325
  },
252
326
  survivors: @agg.surviving_mutants.map { |r| survivor_json(r) }
253
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] },
254
334
  # id extends the key to a total order: several mutants share a line.
255
335
  no_coverage: @agg.results.select(&:no_coverage?).map { |r| mutant_json(r) }
256
336
  .sort_by { |h| [h[:file], h[:line], h[:operator], h[:id].to_s] },
@@ -286,14 +366,20 @@ module Mutineer
286
366
  # Per-source breakdown (additive; baseline consumes it). Sorted by file so
287
367
  # output is byte-stable. Reuses AggregateResult via by_source.
288
368
  per_source: @agg.by_source.map { |file, agg| per_source_json(file, agg) }
289
- .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
290
376
  }
291
377
  # Additive (1.5): the kill matrix, present only with --matrix.
292
378
  doc[:matrix] = matrix_json if @matrix
293
379
  # Additive baseline-delta block, present only with --baseline. Existing
294
380
  # consumers ignore the extra key; it does not move schema_version on its own.
295
381
  doc[:baseline] = baseline_json(baseline) if baseline
296
- "#{JSON.generate(doc)}\n"
382
+ "#{JSON.generate(json_safe(doc))}\n"
297
383
  end
298
384
 
299
385
  # One self-contained HTML file (inline CSS, no external assets): the overall
@@ -302,7 +388,12 @@ module Mutineer
302
388
  # (CGI.escapeHTML) so a `<`/`>` in source can never break the markup. Reuses
303
389
  # survivor_json/per_source_json so one run yields one set of facts regardless
304
390
  # of --format.
305
- 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)
306
397
  score = @agg.mutation_score
307
398
  survivors = @agg.surviving_mutants.map { |r| survivor_json(r) }
308
399
  .sort_by { |h| [h[:file], h[:line], h[:operator]] }
@@ -342,7 +433,8 @@ module Mutineer
342
433
  <body>
343
434
  <h1>Mutineer — Mutation Report</h1>
344
435
  <div class="score">Score: #{score.nil? ? 'N/A' : "#{score}%"}</div>
345
- #{summary_html}
436
+ #{summary_html(declined: declined, subjects: subjects, unmutated: unmutated, scoped: scoped)}
437
+ #{unpaired_html}
346
438
  #{per_source_html(per_source)}
347
439
  #{survivors_html(survivors)}
348
440
  #{ignored_html}
@@ -353,15 +445,31 @@ module Mutineer
353
445
  end
354
446
 
355
447
  # The summary counts block for the HTML header.
356
- 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)
357
455
  counts = {
358
456
  "total" => @agg.total, "killed" => @agg.killed_count,
359
457
  "survived" => @agg.survived_count, "no_coverage" => @agg.no_coverage_count,
360
458
  "uncapturable" => @agg.uncapturable_count, "unplaceable" => @agg.unplaceable_count,
361
459
  "ran_at_load" => @agg.ran_at_load_count, "ignored" => @agg.ignored_count,
460
+ "dropped" => dropped_count,
362
461
  "skipped" => @agg.skipped_invalid_count,
363
- "errored" => @agg.errored_count, "timeout" => @agg.timeout_count
462
+ "errored" => @agg.errored_count, "timeout" => @agg.timeout_count,
463
+ "unpaired" => unpaired_mutant_count
364
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
365
473
  spans = counts.map { |k, v| "<span><strong>#{v}</strong> #{esc(k)}</span>" }.join("\n ")
366
474
  "<div class=\"counts\">\n #{spans}\n</div>"
367
475
  end
@@ -400,6 +508,7 @@ module Mutineer
400
508
  <div class="survivor">
401
509
  <h3>#{esc(s[:subject])}</h3>
402
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])}
403
512
  <pre class="diff">#{diff_lines}</pre>
404
513
  </div>
405
514
  CARD
@@ -423,6 +532,7 @@ module Mutineer
423
532
  <h3>#{esc(row[:subject])}</h3>
424
533
  <div class="meta">#{esc(row[:file])}:#{row[:line]} &middot; #{esc(row[:operator])} &middot; <span class="id">#{esc(row[:id])}</span></div>
425
534
  #{reason}
535
+ #{copies_html(row[:copies])}
426
536
  </div>
427
537
  CARD
428
538
  end.join("\n")
@@ -610,7 +720,7 @@ module Mutineer
610
720
  end
611
721
 
612
722
  # HTML-escapes any text destined for the document (stdlib CGI).
613
- def esc(text) = CGI.escapeHTML(text.to_s)
723
+ def esc(text) = CGI.escapeHTML(utf8_text(text))
614
724
 
615
725
  # The same delta facts the human report prints, for dashboards. new_survivors
616
726
  # reuse the mutant_json shape (subject/file/line/operator/token/id) and sort
@@ -663,19 +773,21 @@ module Mutineer
663
773
  at_eof = source.byteindex("\n", m.end_offset).nil?
664
774
  old_lines = side_lines(original_block, at_eof)
665
775
  new_lines = side_lines(mutated_block, at_eof)
666
- {
667
- subject: result.subject.qualified_name,
776
+ shown_file = utf8_text(file)
777
+ row = {
778
+ subject: utf8_text(result.subject.qualified_name.to_s),
668
779
  file: file,
669
780
  line: start_line,
670
781
  operator: m.operator.to_s,
671
782
  # The stable, copy-pasteable id (next to the human-readable token) so a
672
783
  # user can paste it straight into .mutineer.yml `ignore:`.
673
784
  id: result.id,
674
- token: token,
675
- diff: "--- a/#{file}\n+++ b/#{file}\n" \
785
+ token: utf8_text(token),
786
+ diff: "--- a/#{shown_file}\n+++ b/#{shown_file}\n" \
676
787
  "@@ -#{hunk_range(start_line, old_lines)} +#{hunk_range(start_line, new_lines)} @@\n" \
677
788
  "#{diff_body("-", old_lines)}#{diff_body("+", new_lines)}"
678
789
  }
790
+ attach_copies(row, result.id)
679
791
  end
680
792
 
681
793
  # One side of the diff as the file holds it: the {#diff_for} block plus the
@@ -688,7 +800,9 @@ module Mutineer
688
800
  # @param at_eof [Boolean] no newline follows the block in the file.
689
801
  # @return [Array<String>] its lines, with their endings.
690
802
  def side_lines(block, at_eof)
691
- (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) }
692
806
  end
693
807
 
694
808
  # The `-` or `+` lines of one side. A line with no newline is the file's
@@ -728,25 +842,91 @@ module Mutineer
728
842
  end
729
843
 
730
844
  # The fields that name one mutant, for the lists that point at mutants:
731
- # `no_coverage`, `uncapturable`, `unplaceable`, `ran_at_load`, `ignored` and
732
- # `baseline.new_survivors`.
845
+ # `killed`, `no_coverage`, `uncapturable`, `unplaceable`, `ran_at_load`,
846
+ # `ignored` and `baseline.new_survivors`.
733
847
  #
734
848
  # @api private
735
849
  # @param result [Mutineer::Result] the mutant result.
736
850
  # @return [Hash] subject, file, line, operator, token, and id.
737
851
  def mutant_json(result)
738
- m = result.mutation
739
- 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
740
872
  source = source_for(file)
741
- start_line, _orig, _mut, token = diff_for(m, source)
742
- {
743
- subject: result.subject.qualified_name,
873
+ start_line, _orig, _mut, token = diff_for(mutation, source)
874
+ attach_copies({
875
+ subject: subject.qualified_name,
744
876
  file: file,
745
877
  line: start_line,
746
- operator: m.operator.to_s,
878
+ operator: mutation.operator.to_s,
747
879
  token: token,
748
- 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
749
928
  }
929
+ "#{JSON.generate(reporter.__send__(:json_safe, doc))}\n"
750
930
  end
751
931
 
752
932
  # Builds a line-aligned diff for a mutation whose byte range may span several
@@ -761,30 +941,113 @@ module Mutineer
761
941
  before = source.byteslice(line_begin...m.start_offset)
762
942
  after = source.byteslice(m.end_offset...line_end)
763
943
  original_block = source.byteslice(line_begin...line_end)
764
- 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
765
947
  start_line = source.byteslice(0, m.start_offset).count("\n") + 1
766
948
  token = source.byteslice(m.start_offset...m.end_offset).gsub(/\s+/, " ").strip
767
- 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
768
952
  [start_line, original_block, mutated_block, token]
769
953
  end
770
954
 
771
955
  # An entry under the JSON `no_verdict:` key: an attempted mutant with no verdict.
772
956
  # A pre-fork failure has no subject or mutation attached, so those degrade to
773
957
  # nulls rather than dropping the entry — the count must still reconcile with
774
- # `summary.no_verdict`.
958
+ # `summary.no_verdict`. `details` is redacted here too, whatever its source
959
+ # (#388).
775
960
  #
776
961
  # @api private
777
962
  # @param result [Mutineer::Result] an errored or timed-out result.
778
963
  # @return [Hash] no-verdict JSON object.
779
964
  def no_verdict_json(result)
780
- {
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 = {
781
970
  subject: result.subject&.qualified_name,
782
- file: result.subject&.file,
783
- line: result_line(result),
971
+ file: file,
972
+ line: line,
973
+ operator: m&.operator&.to_s,
974
+ token: token,
784
975
  id: result.id,
785
976
  status: result.status.to_s,
786
- details: result.details
977
+ details: result.details && Redaction.text(result.details)
787
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>"
788
1051
  end
789
1052
 
790
1053
  # Writes the summary block.
@@ -792,9 +1055,13 @@ module Mutineer
792
1055
  # @param out [IO] output stream.
793
1056
  # @param declined [Hash{String => Integer}] operator name => declined count.
794
1057
  # @param scoped [Boolean] the run was diff-scoped (`--since`), which does not
795
- # 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.
796
1063
  # @return [void]
797
- def summary(out, declined: {}, scoped: false)
1064
+ def summary(out, declined: {}, scoped: false, subjects: nil, unmutated: nil)
798
1065
  out.puts "Summary"
799
1066
  out.puts "-------"
800
1067
  out.puts format("Total: %-6d Killed: %d", @agg.total, @agg.killed_count)
@@ -814,8 +1081,19 @@ module Mutineer
814
1081
  # Not mutants: candidates an operator chose not to mutate (#291).
815
1082
  out.puts format("Declined: %-6d (candidates an operator did not mutate; --dry-run shows the count " \
816
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
817
1092
  # Equivalent mutants the user suppressed; excluded from the denominator.
818
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)
819
1097
  end
820
1098
 
821
1099
  # Writes the score line.
@@ -829,7 +1107,7 @@ module Mutineer
829
1107
  "#{@agg.unplaceable_count} unplaceable, #{@agg.ran_at_load_count} ran at load, " \
830
1108
  "#{@agg.skipped_invalid_count} skipped, " \
831
1109
  "#{@agg.errored_count} errored, #{@agg.timeout_count} timeout, " \
832
- "#{@agg.ignored_count} ignored excluded"
1110
+ "#{unpaired_mutant_count} unpaired, #{@agg.ignored_count} ignored excluded"
833
1111
  if score.nil?
834
1112
  out.puts "Mutation score: N/A (no covered mutants)"
835
1113
  # Only the benign case here: the gate-failure explanation is emitted once
@@ -888,16 +1166,112 @@ module Mutineer
888
1166
  @agg.killed_count + @agg.survived_count + no_verdict_count
889
1167
  end
890
1168
 
891
- # Whether the unrun mutants (unplaceable plus skipped invalid) are more than
892
- # {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.
893
1172
  #
894
1173
  # @api private
895
1174
  # @return [Boolean] true when the unrun-share warning applies.
896
1175
  def unrun_share_exceeded?
897
- unrun = @agg.unrun_count
1176
+ return false if @agg.total.zero?
1177
+
1178
+ unrun = unrun_for_share
898
1179
  unrun > BROKEN_FLOOR && unrun > UNRUN_SHARE_LIMIT * (attempted_count + unrun)
899
1180
  end
900
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
+
901
1275
  # The sentence both the verdict line and the stderr note are built from, so a
902
1276
  # user cannot read one number in the report and a different one beside it.
903
1277
  #
@@ -1012,26 +1386,61 @@ module Mutineer
1012
1386
  end
1013
1387
 
1014
1388
  # The source text of `file`: the run's copy when it has one, else the file
1015
- # read as UTF-8 whatever the locale (#303).
1389
+ # read in its magic-comment encoding, or UTF-8 (#303, #346).
1016
1390
  #
1017
1391
  # @api private
1018
1392
  # @param file [String] source file path.
1019
1393
  # @return [String] source text.
1020
- def source_for(file) = @source_map[file] || File.read(file, encoding: "UTF-8")
1394
+ def source_for(file) = @source_map[file] || Parser.read(file)
1021
1395
 
1022
1396
  # Source text, a method name or a file path made safe for a terminal (#163):
1023
1397
  # each control character except tab becomes its Ruby escape (ESC prints as
1024
- # `\e`). The text is read as UTF-8 whatever the locale, and each byte that is
1025
- # not valid UTF-8 (a Latin-1 source, say) prints as `\xNN`, so nothing is
1026
- # 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.
1027
1403
  #
1028
1404
  # @api private
1029
1405
  # @param text [String] source text.
1030
1406
  # @return [String] the text with control characters and invalid bytes escaped.
1031
1407
  def printable(text)
1032
- text.dup.force_encoding(Encoding::UTF_8)
1033
- .scrub { |bytes| bytes.unpack("C*").map { |b| format("\\x%02X", b) }.join }
1034
- .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
1035
1444
  end
1036
1445
 
1037
1446
  # Writes the final verdict line.