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
@@ -10,12 +10,10 @@ module Mutineer
10
10
  # timeout - the parent SIGKILLed a child that overran its wall clock.
11
11
  # skipped - the mutated source failed to re-parse (invalid); no fork.
12
12
  # no_coverage - no test exercises the mutated line; not run, not scored.
13
- # Also a mutant on a later line of a multi-line statement,
14
- # in code that runs only sometimes, that the statement's
15
- # tests ran but did not kill (#254): they may not reach it.
16
- # Also a mutant on a later line of a statement whose first
17
- # or last line holds other code (a call inside a one-line
18
- # block), that the tests of that line did not kill (#289).
13
+ # Also a mutant on a later line of a multi-line statement
14
+ # (#254, #289) whose tests ran and did not kill it, when a
15
+ # probe on the mutated expression did not see it run (#345).
16
+ # A survivor the probe saw run is survived, and counts.
19
17
  # uncapturable - the line's would-be covering test errored during capture,
20
18
  # so coverage was lost. Excluded from the denominator exactly
21
19
  # like no_coverage, but reported separately: it signals a
@@ -212,7 +210,8 @@ module Mutineer
212
210
  # @return [Integer] ignored count.
213
211
  def ignored_count = count(:ignored)
214
212
  # Mutants that exist but did not run: unplaceable plus skipped invalid.
215
- # Neither is in the score; the reporter warns when they pass a share of the run.
213
+ # Neither is in the score. The reporter adds unpaired mutants to the
214
+ # unrun share unless `--fail-fast` is set. `unrun_count` excludes them.
216
215
  #
217
216
  # @return [Integer] unplaceable plus skipped-invalid count.
218
217
  def unrun_count = unplaceable_count + skipped_invalid_count
@@ -0,0 +1,16 @@
1
+ # frozen_string_literal: true
2
+
3
+ module Mutineer
4
+ # The seed every Minitest and RSpec run Mutineer starts itself uses, unless
5
+ # the user sets one (#282). Coverage capture, the clean checks and the
6
+ # mutant runs share it, so a green clean check is green in the order a
7
+ # mutant run of the same files uses. `--test-command` runs the user's
8
+ # command and does not use this seed (#338).
9
+ module RunSeed
10
+ # Default seed. Minitest reads `SEED` instead when that variable is set.
11
+ # A random RSpec order uses this seed unless the suite sets its own.
12
+ #
13
+ # @api private
14
+ PINNED_SEED = 1
15
+ end
16
+ end
@@ -16,9 +16,12 @@ require_relative "project_path"
16
16
  require_relative "file_swap"
17
17
  require_relative "external_backend"
18
18
  require_relative "daemon_backend"
19
+ require_relative "reach_probe"
19
20
  require_relative "job_plan"
20
21
  require_relative "rails_run_env"
21
22
  require_relative "redaction"
23
+ require_relative "database_urls"
24
+ require_relative "output_filter"
22
25
 
23
26
  module Mutineer
24
27
  # Raised when the tool process cannot load a project file: the boot file, a
@@ -30,12 +33,20 @@ module Mutineer
30
33
  # in the original `cause` chain, outermost first.
31
34
  attr_reader :causes
32
35
 
36
+ # @return [String, nil] an extra line when a source raises NameError
37
+ # (including NoMethodError) and the run has no boot file. Nil for
38
+ # every other load failure, including a NameError in the boot file
39
+ # or a `require:` file.
40
+ attr_reader :hint
41
+
33
42
  # @param message [String] the redacted message.
34
43
  # @param causes [Array<String>] see {#causes}.
44
+ # @param hint [String, nil] see {#hint}.
35
45
  # @return [ProjectLoadError]
36
- def initialize(message, causes: [])
46
+ def initialize(message, causes: [], hint: nil)
37
47
  super(message)
38
48
  @causes = causes
49
+ @hint = hint
39
50
  end
40
51
  end
41
52
 
@@ -53,7 +64,8 @@ module Mutineer
53
64
  # coverage map, run every mutation, and aggregate. Returns
54
65
  # [AggregateResult, source_map, extras], where extras is the hash
55
66
  # {JobPlan.collect_jobs} returns (`:legacy_ignore_matches`, `:id_map`,
56
- # `:dropped_id_map`, `:declined`), plus `:unscoped_mutants` under `--since`.
67
+ # `:dropped_id_map`, `:copies`, `:declined`, `:subjects`, `:unmutated_subjects`), plus
68
+ # `:unscoped_mutants` under `--since`.
57
69
  # The CLI then reports + applies the exit code; the integration test asserts
58
70
  # directly on the AggregateResult.
59
71
  #
@@ -67,8 +79,24 @@ module Mutineer
67
79
  def self.execute(config)
68
80
  # Rails reads PARALLEL_WORKERS when a test helper calls parallelize.
69
81
  # Set it before any boot or child spawn, then put the caller's value back.
82
+ # The ensure below reads these. Set them before anything that can raise.
83
+ filter_owned = false
84
+ urls_owned = false
70
85
  previous_parallel_workers = ENV["PARALLEL_WORKERS"]
71
86
  RailsRunEnv.pin_process!
87
+ # The CLI installs the filter first and owns it for the report that
88
+ # follows this method. A library caller owns it for the run itself.
89
+ # Direct writes from a fork or a subprocess then go through the pipe (#341).
90
+ case OutputFilter.install
91
+ when :started
92
+ filter_owned = true
93
+ when :failed
94
+ raise "cannot redirect stdout and stderr for redaction"
95
+ end
96
+ if Redaction.extra_urls.empty?
97
+ Redaction.extra_urls = DatabaseUrls.from_files(config.project_root)
98
+ urls_owned = true
99
+ end
72
100
  operator_classes = MutatorRegistry.resolve(config.operators || MutatorRegistry::DEFAULT_NAMES)
73
101
 
74
102
  # External backend: run the suite as a subprocess in the app's own runtime.
@@ -83,29 +111,48 @@ module Mutineer
83
111
  # The daemon loads these files itself and would report a missing one as
84
112
  # a boot failure (exit 1). Check here so it stays a usage error (exit 2),
85
113
  # as it is in process.
86
- [config.boot, *config.require_paths].compact.each { |f| project_file!(config.project_root, f) }
114
+ check_boot_files!(config)
87
115
  return DaemonBackend.execute(config, operator_classes)
88
116
  end
89
117
 
90
118
  # Both strategies (whole-file reload and redefine, #279) write
91
- # .mutineer_mutant*.rb into each source dir (so require_relative and
92
- # __dir__ resolve). Redefine falls back to the system temp dir for a
93
- # read-only source dir, which this sweep does not reach; the OS cleans
94
- # it, as in 1.x. A SIGKILL'd child skips the tempfile's
95
- # ensure-unlink, orphaning it. `ensure` is unreliable vs SIGKILL, so the
96
- # PARENT sweeps each source dir before and after the run. Orphans are
97
- # impossible after a normal run. The first sweep runs before the boot: a
98
- # file an older version left without the dot would stop Zeitwerk (#253).
119
+ # .mutineer_mutant*.rb into each source dir. Redefine falls back to the
120
+ # system temp dir for a read-only source dir, which this sweep does not
121
+ # reach; the OS cleans it, as in 1.x. The snippet rewrites `__dir__`,
122
+ # `__FILE__`, and `require_relative` to the original file, so that
123
+ # fallback does not false-kill (#339). A SIGKILL'd child skips the
124
+ # tempfile's ensure-unlink, orphaning it. `ensure` is unreliable vs
125
+ # SIGKILL, so the PARENT sweeps each source dir before and after the run.
126
+ # Orphans are impossible after a normal run. The first sweep runs before
127
+ # the boot: a file an older version left without the dot would stop
128
+ # Zeitwerk (#253).
99
129
  dirs = JobPlan.source_dirs(config)
100
130
  JobPlan.sweep_orphans(dirs)
101
- if config.strategy == "redefine"
102
- dirs.reject { |d| File.writable?(d) }.each do |d|
103
- warn "[mutineer] #{d} is not writable: redefine loads its mutants from the system temp dir, " \
104
- "so a method there that uses __dir__ or require_relative can be falsely killed. " \
105
- "Make the directory writable to avoid this (#339)."
131
+ # A `--since` run with no changed mutant has nothing to execute. Collect
132
+ # and scope once before loading the app or capturing coverage so an empty
133
+ # scope can return without paying for a full clean-suite run. Nonempty
134
+ # scopes reuse this work after coverage capture instead of repeating source
135
+ # discovery, parsing, and git diff.
136
+ since_scope = nil
137
+ if config.since
138
+ # The empty-scope return skips the later require calls, so keep missing
139
+ # boot and --require paths as usage errors on that path too.
140
+ check_boot_files!(config)
141
+
142
+ since_jobs, since_ignored, since_source_map, since_extras =
143
+ JobPlan.collect_jobs(config, operator_classes)
144
+ since_jobs, since_ignored, since_extras[:unscoped_mutants] =
145
+ JobPlan.scope_since(since_jobs, since_ignored, since_source_map, config, extras: since_extras)
146
+ if since_jobs.empty?
147
+ return [AggregateResult.new(since_ignored), since_source_map, since_extras]
106
148
  end
149
+ since_scope = [since_jobs, since_ignored, since_source_map, since_extras]
107
150
  end
108
151
 
152
+ # Before boot and `--require`, so a `config.seed=` in those files is
153
+ # recorded and every forked child keeps it (#282).
154
+ prepare_rspec_seed!(config)
155
+
109
156
  # Boot mode: require the boot file ONCE so the app env (e.g. Rails) is booted
110
157
  # in the parent and inherited by every fork. Do NOT manually require the
111
158
  # sources. Under Zeitwerk a manual require of an autoloadable file raises;
@@ -131,7 +178,13 @@ module Mutineer
131
178
  end
132
179
  require_project_file(config.project_root, config.boot)
133
180
  else
134
- config.sources.each { |f| require_project_file(config.project_root, f) }
181
+ # No boot file, so each source loads here, and require: files load
182
+ # after this loop (#217). A NameError means the source named
183
+ # something that is not loaded yet; the hint points at boot:, which
184
+ # loads first (#376).
185
+ config.sources.each do |f|
186
+ require_project_file(config.project_root, f, on_name_error: SOURCE_NEEDS_BOOT_HINT)
187
+ end
135
188
  end
136
189
  config.require_paths.each { |f| require_project_file(config.project_root, f) }
137
190
  preload_owners(config) if config.boot && config.strategy == "redefine"
@@ -177,9 +230,13 @@ module Mutineer
177
230
  JobPlan.abort_if_unclean!(coverage_map, framework: config.framework)
178
231
 
179
232
  # Collect every (subject, mutation) up front so the pool can fan them out.
180
- jobs, ignored_results, source_map, extras = JobPlan.collect_jobs(config, operator_classes)
181
-
182
- jobs, ignored_results, extras[:unscoped_mutants] = JobPlan.scope_since(jobs, ignored_results, source_map, config)
233
+ if since_scope
234
+ jobs, ignored_results, source_map, extras = since_scope
235
+ else
236
+ jobs, ignored_results, source_map, extras = JobPlan.collect_jobs(config, operator_classes)
237
+ jobs, ignored_results, extras[:unscoped_mutants] =
238
+ JobPlan.scope_since(jobs, ignored_results, source_map, config, extras: extras)
239
+ end
183
240
 
184
241
  strategy = config.strategy
185
242
  # Fail-fast must be serial: a parallel stop_when fires on the first survivor
@@ -212,6 +269,10 @@ module Mutineer
212
269
  ensure
213
270
  # A caller that set PARALLEL_WORKERS keeps that value after the run.
214
271
  RailsRunEnv.restore_process!(previous_parallel_workers)
272
+ OutputFilter.uninstall if filter_owned
273
+ # The CLI set its own list before this method and restores it. Clear
274
+ # only the list this call loaded.
275
+ Redaction.extra_urls = [] if urls_owned
215
276
  end
216
277
 
217
278
  # A `--matrix` error that carries no {Kills} row (the worker crashed, or its
@@ -253,7 +314,8 @@ module Mutineer
253
314
  FileSwap.restore_orphans(dirs)
254
315
 
255
316
  jobs, ignored_results, source_map, extras = JobPlan.collect_jobs(config, operator_classes)
256
- jobs, ignored_results, extras[:unscoped_mutants] = JobPlan.scope_since(jobs, ignored_results, source_map, config)
317
+ jobs, ignored_results, extras[:unscoped_mutants] =
318
+ JobPlan.scope_since(jobs, ignored_results, source_map, config, extras: extras)
257
319
 
258
320
  # Nothing to mutate: return before the smoke check, which runs the whole
259
321
  # --test set to calibrate a timeout no mutant would use (#76).
@@ -264,7 +326,7 @@ module Mutineer
264
326
  # 3x the clean run, floor 30s, ceiling 300s: a heuristic. The floor covers
265
327
  # a fast suite; the ceiling bounds a hung mutant (infinite loop) so a
266
328
  # handful cannot stall a serial run for ~45min on a slow suite.
267
- smoke_elapsed, check_summary = ExternalBackend.smoke_check!(config.test_command, abs_tests)
329
+ smoke_elapsed, check_summary, random_order = ExternalBackend.smoke_check!(config.test_command, abs_tests)
268
330
  timeout = [[smoke_elapsed * 3, 30].max, 300].min.ceil
269
331
  # #292: the summary check needs a summary line to look for. Without one
270
332
  # on the clean run, keep the exit-code rule and say what that costs.
@@ -274,6 +336,22 @@ module Mutineer
274
336
  "so the crash check is off: an exit 1 counts as a kill even when the suite crashed " \
275
337
  "before its tests ran. Use the default Minitest or RSpec progress output to turn it on."
276
338
  end
339
+ # #338: each mutant run picks its own order, so an order-dependent
340
+ # suite can fail a mutant run for a reason the mutant did not cause.
341
+ if random_order
342
+ runner, seed = random_order
343
+ fix = if runner == :minitest
344
+ "set SEED=#{seed} before the mutineer command (SEED=#{seed} mutineer run ...), " \
345
+ "not inside --test-command"
346
+ else
347
+ # SPEC_OPTS is read after the command line, so it would undo the fix.
348
+ "add --order defined to the rspec command in --test-command and keep " \
349
+ "--order rand out of SPEC_OPTS"
350
+ end
351
+ warn "[mutineer] the clean run of --test-command printed a #{runner == :minitest ? 'Minitest' : 'RSpec'} " \
352
+ "seed (#{seed}) and Mutineer found no fixed seed, so each mutant run may use a new test " \
353
+ "order and an order-dependent suite can give a false kill. To fix the order, #{fix}."
354
+ end
277
355
 
278
356
  results = []
279
357
  progress = Progress.new(jobs.size)
@@ -302,9 +380,9 @@ module Mutineer
302
380
  # @param check_summary [Boolean] passed to {ExternalBackend.run}.
303
381
  # @return [Mutineer::Result] verdict for this mutant.
304
382
  def self.run_external(subject, mutation, command, abs_tests, timeout:, verbose:, check_summary:)
305
- source = File.read(subject.file, encoding: "UTF-8")
383
+ source = Parser.read(subject.file)
306
384
  mutated = mutation.apply(source)
307
- return Result.skipped if Parser.parse_string(mutated).errors.any?
385
+ return Result.skipped if Parser.invalid?(mutated)
308
386
 
309
387
  FileSwap.with(subject.file, mutated) do
310
388
  ExternalBackend.run(command, abs_tests, timeout: timeout, verbose: verbose, check_summary: check_summary)
@@ -361,11 +439,11 @@ module Mutineer
361
439
  # @return [Mutineer::Result] mutant result.
362
440
  def self.run(mutation, source_file:, coverage_map: nil, subject: nil, strategy: "reload",
363
441
  timeout: Isolation::DEFAULT_TIMEOUT, rails: false, framework: "minitest", matrix: false)
364
- source = File.read(source_file, encoding: "UTF-8")
442
+ source = Parser.read(source_file)
365
443
  mutated = mutation.apply(source)
366
444
 
367
445
  # Validity rule: a mutant that does not re-parse is skipped before forking.
368
- return Result.skipped if Parser.parse_string(mutated).errors.any?
446
+ return Result.skipped if Parser.invalid?(mutated)
369
447
 
370
448
  # Coverage selection (both standalone and boot mode): a mutation on a line
371
449
  # no test exercises is :no_coverage (no fork); otherwise exactly the
@@ -377,36 +455,49 @@ module Mutineer
377
455
  return kind == :maybe ? Result.no_coverage : Result.unplaceable if subject&.unplaceable?(strategy)
378
456
 
379
457
  abs_tests = payload
458
+ # A :maybe mutant records whether the mutated expression ran (#345).
459
+ sentinel = kind == :maybe ? ReachProbe.sentinel : nil
460
+ reach_key = sentinel && ReachProbe.reach_key
380
461
 
381
- result = Isolation.run(timeout: timeout, channel: matrix) do |channel|
382
- # Forking inherits the parent's live DB connection; sharing one socket
383
- # across processes corrupts it. Drop it so AR reconnects per child.
384
- reconnect_active_record if rails
385
- if strategy == "redefine"
386
- # Load each enclosing def too: its body holds the original nested def,
387
- # which a call to it would define again over the mutant (#290).
388
- Isolation.apply_surgical(mutation, subject, source)
389
- s = subject
390
- Isolation.apply_surgical(mutation, s, source) while (s = s.enclosing_subject)
391
- elsif subject&.reload_hook_call
392
- # #297: a def in a concern's hook block reaches each class that has it.
393
- code, hook_def = JobPlan.hook_mutant(mutated, mutation, subject, source)
394
- Isolation.apply_whole_file(code, source_file)
395
- ConcernBlocks.place_hook_def(source_file: source_file, **hook_def)
396
- else
397
- Isolation.apply_whole_file(mutated, source_file)
398
- end
399
- if channel
400
- # --matrix: every covering test runs, and each outcome goes to the parent.
401
- TestRunners.for(framework).run(abs_tests, record_to: channel)
402
- else
403
- # One failing test already kills the mutant, so the child stops there.
404
- TestRunners.for(framework).run(abs_tests, stop_at_first_failure: true)
462
+ begin
463
+ result = Isolation.run(timeout: timeout, channel: matrix) do |channel|
464
+ # Forking inherits the parent's live DB connection; sharing one socket
465
+ # across processes corrupts it. Drop it so AR reconnects per child.
466
+ reconnect_active_record if rails
467
+ if strategy == "redefine"
468
+ # Load each enclosing def too: its body holds the original nested def,
469
+ # which a call to it would define again over the mutant (#290).
470
+ Isolation.apply_surgical(mutation, subject, source, reach_path: sentinel&.path, reach_key: reach_key)
471
+ s = subject
472
+ while (s = s.enclosing_subject)
473
+ Isolation.apply_surgical(mutation, s, source, reach_path: sentinel&.path, reach_key: reach_key)
474
+ end
475
+ elsif subject&.reload_hook_call
476
+ # #297: a def in a concern's hook block reaches each class that has it.
477
+ code, hook_def = JobPlan.hook_mutant(mutated, mutation, subject, source, reach_path: sentinel&.path,
478
+ reach_key: reach_key)
479
+ Isolation.apply_whole_file(code, source_file, hook_def: hook_def)
480
+ else
481
+ Isolation.apply_whole_file(ReachProbe.wrap_mutation(mutated, mutation, sentinel&.path, reach_key),
482
+ source_file)
483
+ end
484
+ # A reload can run the expression while the file loads. That is not
485
+ # a test reaching it (#345).
486
+ ReachProbe.forget_load(sentinel.path, reach_key) if sentinel
487
+ if channel
488
+ # --matrix: every covering test runs, and each outcome goes to the parent.
489
+ TestRunners.for(framework).run(abs_tests, record_to: channel)
490
+ else
491
+ # One failing test already kills the mutant, so the child stops there.
492
+ TestRunners.for(framework).run(abs_tests, stop_at_first_failure: true)
493
+ end
405
494
  end
495
+ result = relative_kills(result, coverage_map.project_root)
496
+ result = JobPlan.load_verdict(result, source_file, mutation, subject, source, coverage_map)
497
+ JobPlan.selection_verdict(kind, result, reached: ReachProbe.reached?(sentinel))
498
+ ensure
499
+ ReachProbe.close_sentinel(sentinel)
406
500
  end
407
- result = relative_kills(result, coverage_map.project_root)
408
- result = JobPlan.load_verdict(result, source_file, mutation, subject, source, coverage_map)
409
- JobPlan.selection_verdict(kind, result)
410
501
  end
411
502
 
412
503
  # Rewrites the test files of a result's {Kills} row relative to the project
@@ -489,6 +580,45 @@ module Mutineer
489
580
  end
490
581
  private_class_method :project_file!
491
582
 
583
+ # Checks that the boot file and every --require file exist, so a missing
584
+ # one stays a usage error (exit 2) on paths that skip the later require.
585
+ #
586
+ # @api private
587
+ # @param config [Config]
588
+ # @raise [Errno::ENOENT] when a file does not exist.
589
+ # @return [void]
590
+ def self.check_boot_files!(config)
591
+ [config.boot, *config.require_paths].compact.each { |f| project_file!(config.project_root, f) }
592
+ end
593
+ private_class_method :check_boot_files!
594
+
595
+ # Installs the RSpec seed watcher in this process when the run uses
596
+ # RSpec. Boot and `--require` files then load with the watcher on, and
597
+ # forks inherit the record of a seed they set. A project without rspec
598
+ # is left for the child to report, as before.
599
+ #
600
+ # @api private
601
+ # @param config [Mutineer::Config]
602
+ # @return [void]
603
+ def self.prepare_rspec_seed!(config)
604
+ return unless config.framework == "rspec"
605
+
606
+ require "rspec/core"
607
+ ::RSpec::Core::Runner.disable_autorun!
608
+ TestRunners::RSpecSeed.install!
609
+ rescue LoadError
610
+ nil
611
+ end
612
+ private_class_method :prepare_rspec_seed!
613
+
614
+ # Extra line when a source raises NameError and the run has no boot file.
615
+ # `require:` files load after the sources, so they cannot define names the
616
+ # source needs while it loads (#376, #217).
617
+ SOURCE_NEEDS_BOOT_HINT = "a source that needs other files loaded first takes them from " \
618
+ "`boot:` (or `--boot`), which loads before the sources; " \
619
+ "`require:` files load after them"
620
+ private_constant :SOURCE_NEEDS_BOOT_HINT
621
+
492
622
  # Require one project file in the tool process. A failure becomes a
493
623
  # {ProjectLoadError} whose message, and each cause in its list, is
494
624
  # redacted. The original backtrace is kept; the cause is not, because
@@ -497,10 +627,13 @@ module Mutineer
497
627
  # @api private
498
628
  # @param root [String] the project root.
499
629
  # @param path [String] the path as the user gave it.
630
+ # @param on_name_error [String, nil] {ProjectLoadError#hint} when the file
631
+ # raises NameError. Sources pass {SOURCE_NEEDS_BOOT_HINT}. The boot
632
+ # file and `require:` files pass nil: those errors are not this case.
500
633
  # @raise [Errno::ENOENT] when the requested file does not exist.
501
634
  # @raise [ProjectLoadError] when the file raises while it loads.
502
635
  # @return [void]
503
- def self.require_project_file(root, path)
636
+ def self.require_project_file(root, path, on_name_error: nil)
504
637
  # Outside the rescue: a path Ruby cannot expand (`~nosuchuser/boot.rb`)
505
638
  # stays a usage error (exit 2), not a load failure.
506
639
  file = project_file!(root, path)
@@ -516,7 +649,13 @@ module Mutineer
516
649
  causes << Redaction.describe(cause)
517
650
  cause = cause.cause
518
651
  end
519
- error = ProjectLoadError.new("cannot load #{Redaction.text(path)}: #{Redaction.describe(e)}", causes: causes)
652
+ # The exception that escaped, not an exception it wrapped. A
653
+ # RuntimeError whose cause is a NameError is a different failure.
654
+ hint = on_name_error if e.is_a?(NameError)
655
+ error = ProjectLoadError.new(
656
+ "cannot load #{Redaction.text(path)}: #{Redaction.describe(e)}",
657
+ causes: causes, hint: hint
658
+ )
520
659
  error.set_backtrace(e.backtrace)
521
660
  raise error, cause: nil
522
661
  end
@@ -0,0 +1,187 @@
1
+ # frozen_string_literal: true
2
+
3
+ module Mutineer
4
+ # Bytes to write for a mutant file so they match its magic comment.
5
+ #
6
+ # The in-process string is already in that encoding. The daemon receives
7
+ # the same text through JSON, which turns it into UTF-8. Writing those
8
+ # UTF-8 bytes under an `encoding: EUC-JP` comment would make Ruby misread
9
+ # the file. This encodes the text back to the comment's encoding. No
10
+ # Prism: the daemon loads on the app's Ruby (#346).
11
+ #
12
+ # The comment forms are Ruby's, not Prism's. Ruby ignores
13
+ # `# encoding=NAME` with no space, and it ignores a coding word that is
14
+ # not in a comment. Prism 2 accepts the first of those.
15
+ module SourceBytes
16
+ # How much of the file can hold the comment. Real comments are short.
17
+ # The cap only bounds a pathological first line.
18
+ HEADER_BYTES = 4096
19
+
20
+ # `code` as the bytes its magic comment names, or its own bytes when it
21
+ # names none or an unknown encoding. A snippet that is already in
22
+ # another encoding and has no comment gets one, so `load` uses that
23
+ # encoding. A redefine snippet is such a snippet (#346).
24
+ #
25
+ # @param code [String] mutant source, in its encoding or in UTF-8.
26
+ # @return [String] binary string of the bytes to write.
27
+ def self.for_file(code)
28
+ text = code.to_s
29
+ name = encoding_name(text)
30
+ if name.nil? && foreign?(text)
31
+ text = with_magic_comment(text)
32
+ name = text.encoding.name
33
+ end
34
+ encode(text, name).b
35
+ end
36
+
37
+ # Encoding Ruby assigns to `bytes` from its magic comment, or UTF-8.
38
+ #
39
+ # @param bytes [String] file contents.
40
+ # @return [Encoding]
41
+ def self.encoding_for(bytes)
42
+ name = encoding_name(bytes)
43
+ return Encoding::UTF_8 if name.nil?
44
+
45
+ Encoding.find(name)
46
+ rescue ArgumentError
47
+ Encoding::UTF_8
48
+ end
49
+
50
+ # The encoding name in the first comment line, or the second when the
51
+ # first is a shebang. Nil when Ruby would ignore the line.
52
+ #
53
+ # @param code [String]
54
+ # @return [String, nil]
55
+ def self.encoding_name(code)
56
+ first, second = header_lines(code)
57
+ chosen = shebang?(first) ? second : first
58
+ comment = comment_body(chosen)
59
+ return nil if comment.nil?
60
+
61
+ name_in(comment)
62
+ end
63
+ private_class_method :encoding_name
64
+
65
+ # True when `text` holds characters UTF-8 would not already store.
66
+ #
67
+ # @param text [String]
68
+ # @return [Boolean]
69
+ def self.foreign?(text)
70
+ return false if text.encoding == Encoding::UTF_8 || text.encoding == Encoding::US_ASCII
71
+
72
+ !text.ascii_only?
73
+ rescue ArgumentError
74
+ true
75
+ end
76
+ private_class_method :foreign?
77
+
78
+ # `text` with a magic comment naming its encoding.
79
+ #
80
+ # @param text [String]
81
+ # @return [String]
82
+ def self.with_magic_comment(text)
83
+ comment = "# encoding: #{text.encoding.name}\n".dup.force_encoding(text.encoding)
84
+ comment + text
85
+ end
86
+ private_class_method :with_magic_comment
87
+
88
+ # `text` in `name`'s encoding, or `text` when that encoding is unknown
89
+ # or cannot hold a character.
90
+ #
91
+ # @param text [String]
92
+ # @param name [String, nil]
93
+ # @return [String]
94
+ def self.encode(text, name)
95
+ return text if name.nil? || name.empty?
96
+
97
+ encoding = Encoding.find(name)
98
+ return text if encoding == text.encoding
99
+
100
+ text.encode(encoding)
101
+ rescue ArgumentError, Encoding::UndefinedConversionError
102
+ text
103
+ end
104
+ private_class_method :encode
105
+
106
+ # The first line and the second, without their endings. CRLF is one
107
+ # ending. Only the first {HEADER_BYTES} bytes are read.
108
+ #
109
+ # @param code [String]
110
+ # @return [Array(String, String)]
111
+ def self.header_lines(code)
112
+ raw = code.to_s.b.byteslice(0, HEADER_BYTES) || "".b
113
+ first, rest = take_line(raw)
114
+ second, = take_line(rest)
115
+ [first, second]
116
+ end
117
+ private_class_method :header_lines
118
+
119
+ # One line and what follows it.
120
+ #
121
+ # @param raw [String] binary text.
122
+ # @return [Array(String, String)]
123
+ def self.take_line(raw)
124
+ return ["", ""] if raw.nil? || raw.empty?
125
+
126
+ crlf = raw.index("\r\n".b)
127
+ lf = raw.index("\n".b)
128
+ cr = raw.index("\r".b)
129
+ if crlf && (lf.nil? || crlf <= lf) && (cr.nil? || crlf <= cr)
130
+ [raw.byteslice(0, crlf), raw.byteslice((crlf + 2)..)]
131
+ elsif lf && (cr.nil? || lf <= cr)
132
+ [raw.byteslice(0, lf), raw.byteslice((lf + 1)..)]
133
+ elsif cr
134
+ [raw.byteslice(0, cr), raw.byteslice((cr + 1)..)]
135
+ else
136
+ [raw, ""]
137
+ end
138
+ end
139
+ private_class_method :take_line
140
+
141
+ # True when `line` is a shebang. Ruby then reads the encoding from the
142
+ # next line.
143
+ #
144
+ # @param line [String]
145
+ # @return [Boolean]
146
+ def self.shebang?(line)
147
+ line.to_s.b.start_with?("#!".b)
148
+ end
149
+ private_class_method :shebang?
150
+
151
+ # `line` from its `#`, or nil when the line is code. Leading spaces
152
+ # and tabs are allowed. A trailing comment on a code line is not.
153
+ #
154
+ # @param line [String, nil]
155
+ # @return [String, nil] binary comment text.
156
+ def self.comment_body(line)
157
+ return nil if line.nil?
158
+
159
+ raw = line.to_s.b
160
+ index = 0
161
+ index += 1 while raw.getbyte(index) == 32 || raw.getbyte(index) == 9
162
+ return nil unless raw.getbyte(index) == 35
163
+
164
+ raw.byteslice(index..)
165
+ end
166
+ private_class_method :comment_body
167
+
168
+ # The encoding name in a comment line, or nil. A colon may have no
169
+ # space. An equals sign needs whitespace on both sides. A vim modeline
170
+ # counts only as `set fileencoding=`.
171
+ #
172
+ # @param comment [String]
173
+ # @return [String, nil]
174
+ def self.name_in(comment)
175
+ text = comment.to_s.b
176
+ vim = text.match(/vim:\s*set\b[^\n\r]*\bfileencoding\s*=\s*([^\s:]+)/i)
177
+ return vim[1] if vim
178
+
179
+ named = text.match(/\b(?:en)?coding\s*:\s*([^\s;#]+)/i) ||
180
+ text.match(/\b(?:en)?coding\s+=\s*([^\s;#]+)/i)
181
+ named&.[](1)
182
+ rescue ArgumentError
183
+ nil
184
+ end
185
+ private_class_method :name_in
186
+ end
187
+ end