mutineer 1.6.0 → 1.8.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 +680 -0
  3. data/README.md +210 -499
  4. data/lib/mutineer/baseline.rb +1 -1
  5. data/lib/mutineer/changed_lines.rb +2 -1
  6. data/lib/mutineer/child_coverage.rb +53 -0
  7. data/lib/mutineer/cli.rb +293 -42
  8. data/lib/mutineer/concern_blocks.rb +243 -0
  9. data/lib/mutineer/config.rb +154 -8
  10. data/lib/mutineer/coverage_map.rb +265 -27
  11. data/lib/mutineer/daemon_backend.rb +244 -75
  12. data/lib/mutineer/daemon_client.rb +73 -10
  13. data/lib/mutineer/daemon_server.rb +226 -42
  14. data/lib/mutineer/external_backend.rb +159 -15
  15. data/lib/mutineer/init.rb +124 -0
  16. data/lib/mutineer/isolation.rb +78 -24
  17. data/lib/mutineer/job_plan.rb +234 -44
  18. data/lib/mutineer/kill_channel.rb +24 -14
  19. data/lib/mutineer/migrate.rb +707 -0
  20. data/lib/mutineer/minitest_integration/in_test_database_error.rb +184 -0
  21. data/lib/mutineer/minitest_integration/kill_recorder.rb +25 -17
  22. data/lib/mutineer/minitest_integration.rb +44 -14
  23. data/lib/mutineer/mutator_registry.rb +6 -2
  24. data/lib/mutineer/mutators/array_literal.rb +4 -2
  25. data/lib/mutineer/mutators/base.rb +36 -7
  26. data/lib/mutineer/mutators/call_to_receiver.rb +148 -0
  27. data/lib/mutineer/mutators/chain_link.rb +6 -6
  28. data/lib/mutineer/mutators/condition_forcing.rb +6 -3
  29. data/lib/mutineer/mutators/operand_removal.rb +4 -2
  30. data/lib/mutineer/mutators/range_literal.rb +105 -4
  31. data/lib/mutineer/mutators/return_nil.rb +1 -0
  32. data/lib/mutineer/orphan_guard.rb +84 -0
  33. data/lib/mutineer/pairing.rb +62 -1
  34. data/lib/mutineer/project.rb +302 -14
  35. data/lib/mutineer/rails_run_env.rb +73 -0
  36. data/lib/mutineer/rails_worker_db.rb +1596 -57
  37. data/lib/mutineer/redaction.rb +199 -0
  38. data/lib/mutineer/reporter.rb +173 -31
  39. data/lib/mutineer/result.rb +52 -15
  40. data/lib/mutineer/runner.rb +148 -28
  41. data/lib/mutineer/statement_lines.rb +24 -11
  42. data/lib/mutineer/subject.rb +30 -4
  43. data/lib/mutineer/test_runners/minitest.rb +2 -1
  44. data/lib/mutineer/test_runners/rspec.rb +15 -3
  45. data/lib/mutineer/test_runners.rb +5 -2
  46. data/lib/mutineer/triage.rb +111 -0
  47. data/lib/mutineer/version.rb +1 -1
  48. data/lib/mutineer/worker_pool.rb +2 -1
  49. data/lib/mutineer.rb +4 -0
  50. data/skills/mutineer/SKILL.md +84 -0
  51. metadata +13 -1
@@ -17,20 +17,163 @@ module Mutineer
17
17
  def self.discover(paths, only: nil)
18
18
  subjects = Array(paths).flat_map do |path|
19
19
  result = Parser.parse_file(path)
20
- visitor = SubjectVisitor.new(path)
20
+ visitor = SubjectVisitor.new(path, plain_path_calls(result.value))
21
21
  visitor.visit(result.value)
22
22
  visitor.promote_module_functions!
23
+ exclude_ambiguous_hook_defs!(visitor.subjects, result.value)
23
24
  visitor.subjects
24
25
  end
25
26
  only ? subjects.select { |s| s.qualified_name == only } : subjects
26
27
  end
27
28
 
29
+ # Keeps hook defs unplaceable when the raw AST can define another method
30
+ # with the same name and source line. Count all defs, including bodies that
31
+ # SubjectVisitor does not select, and Ruby's explicit method creators (see
32
+ # {.created_method_locations}). Indirect callable bodies may come from any
33
+ # block or lambda in this file, including a stored hook block. An unknown
34
+ # creator name blocks only those possible source lines. Instance and
35
+ # singleton definitions can both reach singleton-class hosts, so their
36
+ # shared name and line are ambiguous too. Run before `only` so selecting
37
+ # one subject cannot hide a collision.
38
+ #
39
+ # @param subjects [Array<Mutineer::Subject>] subjects from one source file.
40
+ # @param program [Prism::ProgramNode] the complete parsed file.
41
+ # @return [void]
42
+ def self.exclude_ambiguous_hook_defs!(subjects, program)
43
+ return unless subjects.any?(&:reload_hook_call)
44
+
45
+ counts = Hash.new(0)
46
+ body_lines = Set.new
47
+ indirect_names = Set.new
48
+ nodes = [program]
49
+ while (node = nodes.pop)
50
+ nodes.concat(node.compact_child_nodes)
51
+ if node.is_a?(Prism::LambdaNode) || node.is_a?(Prism::BlockNode)
52
+ body_lines << node.location.start_line
53
+ end
54
+ location = if node.is_a?(Prism::DefNode)
55
+ [node.location.start_line, [node.name]]
56
+ elsif node.is_a?(Prism::CallNode)
57
+ created_method_locations(node)
58
+ end
59
+ next unless location
60
+
61
+ line, names = location
62
+ if line
63
+ names.each { |name| counts[[line, name]] += 1 }
64
+ else
65
+ names.each { |name| indirect_names << name }
66
+ end
67
+ end
68
+ indirect_names.each { |name| body_lines.each { |line| counts[[line, name]] += 1 } }
69
+ subjects.each do |subject|
70
+ line = subject.def_node.location.start_line
71
+ subject.reload_hook_call = nil if counts[[line, subject.name]] > 1 || counts[[line, nil]].positive?
72
+ end
73
+ end
74
+ private_class_method :exclude_ambiguous_hook_defs!
75
+
76
+ # The source line and names Ruby assigns to explicit method creators. A
77
+ # block-defined method starts at the block opening and a literal lambda at
78
+ # its arrow. A positional callable takes precedence over a supplied block.
79
+ # Other positional bodies and block passes have an indirect source: the
80
+ # caller checks possible block/lambda lines instead of the call line.
81
+ # An attribute method starts at the message token, not its receiver line.
82
+ # Literal symbol and string names are exact. A dynamic name, splat, or attr
83
+ # writer flag may name any method on that line, represented by nil.
84
+ #
85
+ # @param node [Prism::CallNode] call to inspect.
86
+ # @return [Array, nil] source line and names (a nil line means an indirect
87
+ # callable body), or nil for a call outside this built-in family.
88
+ def self.created_method_locations(node)
89
+ arguments = node.arguments&.arguments || []
90
+ case node.name
91
+ when :define_method, :define_singleton_method
92
+ body = arguments[1] || node.block
93
+ body = body.expression if body.is_a?(Prism::BlockArgumentNode)
94
+ line = body.location.start_line if body.is_a?(Prism::BlockNode) || body.is_a?(Prism::LambdaNode)
95
+ return [line, [literal_method_name(arguments.first)]]
96
+ when :attr_reader, :attr_writer, :attr_accessor, :attr
97
+ mode = { attr_reader: :reader, attr_writer: :writer, attr_accessor: :both, attr: :reader }.fetch(node.name)
98
+ if node.name == :attr && arguments.size == 2 &&
99
+ (arguments.last.is_a?(Prism::TrueNode) || arguments.last.is_a?(Prism::FalseNode))
100
+ mode = arguments.last.is_a?(Prism::TrueNode) ? :both : :reader
101
+ arguments = arguments.first(1)
102
+ end
103
+ names = arguments.flat_map do |argument|
104
+ name = literal_method_name(argument)
105
+ next [nil] unless name
106
+
107
+ case mode
108
+ when :reader then [name]
109
+ when :writer then [:"#{name}="]
110
+ else [name, :"#{name}="]
111
+ end
112
+ end
113
+ [node.message_loc.start_line, names]
114
+ end
115
+ end
116
+ private_class_method :created_method_locations
117
+
118
+ # A literal method name, or nil when it depends on a runtime value.
119
+ #
120
+ # @param node [Prism::Node, nil] name argument.
121
+ # @return [Symbol, nil]
122
+ def self.literal_method_name(node)
123
+ node.unescaped.to_sym if node.is_a?(Prism::SymbolNode) || node.is_a?(Prism::StringNode)
124
+ end
125
+ private_class_method :literal_method_name
126
+
127
+ # The call statements that run each time the file loads, in order: each one
128
+ # sits in the file's top-level statements or in a `module` or `class` body
129
+ # reached only through such statements. A call under any `if`, `unless`,
130
+ # `case`, `&&`, `rescue` or loop, an assignment, an argument, a def or a block
131
+ # is not on this path. A file with a `return` outside any def or block may
132
+ # stop before a call, so it has none (#297).
133
+ #
134
+ # @param program [Prism::ProgramNode] the parsed file.
135
+ # @return [Set<Prism::CallNode>] compared by identity.
136
+ def self.plain_path_calls(program)
137
+ calls = Set.new.compare_by_identity
138
+ return calls if top_level_return?(program)
139
+
140
+ bodies = [program.statements]
141
+ while (body = bodies.pop)
142
+ body.body.each do |node|
143
+ calls << node if node.is_a?(Prism::CallNode)
144
+ bodies << node.body if (node.is_a?(Prism::ModuleNode) || node.is_a?(Prism::ClassNode)) &&
145
+ node.body.is_a?(Prism::StatementsNode)
146
+ end
147
+ end
148
+ calls
149
+ end
150
+ private_class_method :plain_path_calls
151
+
152
+ # True when the node holds a `return` that is not inside a def, a block or a
153
+ # lambda, so loading the file can stop early.
154
+ #
155
+ # @param node [Prism::Node] node to search.
156
+ # @return [Boolean]
157
+ def self.top_level_return?(node)
158
+ return true if node.is_a?(Prism::ReturnNode)
159
+ return false if node.is_a?(Prism::DefNode) || node.is_a?(Prism::BlockNode) || node.is_a?(Prism::LambdaNode)
160
+
161
+ node.compact_child_nodes.any? { |child| top_level_return?(child) }
162
+ end
163
+ private_class_method :top_level_return?
164
+
28
165
  # Walks an AST, maintaining a namespace stack, emitting Subjects.
29
166
  # Nested inside Project to signal its private role.
30
167
  class SubjectVisitor < Prism::Visitor
31
168
  # Calls whose block is the body of the class they build: receiver name => method.
32
169
  CLASS_BUILDERS = { "Data" => :define, "Struct" => :new, "Class" => :new, "Module" => :new }.freeze
33
170
 
171
+ # ActiveSupport::Concern calls whose block another module or class runs (see {#concern_block}).
172
+ CONCERN_BLOCKS = %i[class_methods included prepended].freeze
173
+
174
+ # Calls whose first argument names a method they reach (see {#placeable_hook}).
175
+ NAME_TAKERS = %i[method instance_method send public_send __send__].freeze
176
+
34
177
  # A constant name, or a path of them; Ruby allows Unicode in both.
35
178
  CONSTANT_PATH = /\A[[:upper:]][[:word:]]*(?:::[[:upper:]][[:word:]]*)*\z/
36
179
 
@@ -58,8 +201,11 @@ module Mutineer
58
201
  # Builds a subject visitor.
59
202
  #
60
203
  # @param file [String] source file path being visited.
61
- def initialize(file)
204
+ # @param plain_calls [Set<Prism::CallNode>] the file's call statements on a
205
+ # plain path (see {Project.plain_path_calls}); only these hook calls can be placed.
206
+ def initialize(file, plain_calls = Set.new)
62
207
  @file = file
208
+ @plain_calls = plain_calls
63
209
  @namespace_stack = []
64
210
  @lexical_stack = [] # class/module names as written, `::X` kept (#145)
65
211
  @subjects = []
@@ -78,6 +224,11 @@ module Mutineer
78
224
  @self_unknown = false # inside a def or a block that is not a builder, so `self` is not the namespace
79
225
  @self_scope = nil # the def or block whose `self` the code runs with
80
226
  @singleton_uncertain = false # the open `class << self` was inside a def or a non-builder block
227
+ @concern_modules = Set.new # the {#module_key} of each module that ran `extend ActiveSupport::Concern`
228
+ @hook_block = false # inside a concern's `included` or `prepended` block (see {#hook_block?})
229
+ @enclosing_subject = nil # the subject of the def being visited, for a nested def (#290)
230
+ @hook_call = nil # that block's call node, when reload can place its defs (see {#placeable_hook})
231
+ @hook_uses = Set.new # the names that block calls outside its def bodies
81
232
  super()
82
233
  end
83
234
 
@@ -91,7 +242,12 @@ module Mutineer
91
242
  return if @module_function_names.empty?
92
243
 
93
244
  named = @module_function_names.to_set
94
- @subjects.each_with_index { |s, i| s.singleton = true if named.include?([@subject_keys[i], s.name]) }
245
+ @subjects.each_with_index do |s, i|
246
+ next unless named.include?([@subject_keys[i], s.name])
247
+
248
+ s.singleton = true
249
+ s.reload_hook_call = nil # a module function has a second, private copy no hook def placement makes
250
+ end
95
251
  end
96
252
 
97
253
  # Visits class nodes and tracks namespace nesting.
@@ -117,7 +273,11 @@ module Mutineer
117
273
  # block's defs belong to the class it builds; one not assigned to a
118
274
  # constant has no name, so its subjects are marked `owner_unknown`, and a
119
275
  # `module_function :name` in it promotes nothing. Elsewhere it promotes the
120
- # methods of the same module, matched by {#module_key}.
276
+ # methods of the same module, matched by {#module_key}. A module that runs
277
+ # `extend ActiveSupport::Concern` is a concern from then on in this file. A
278
+ # `class_methods` block in its body (see {#concern_block}) is visited like a
279
+ # builder block that builds the module's `ClassMethods`, so its defs belong to
280
+ # that module (#252). The defs in any other such block have their owner unknown.
121
281
  #
122
282
  # @param node [Prism::CallNode] call node.
123
283
  # @return [void]
@@ -136,10 +296,31 @@ module Mutineer
136
296
  end
137
297
  end
138
298
  end
139
- return super unless builds_class?(node)
140
-
141
- anonymous = !@assigned&.first.equal?(node)
142
- with_block_owner(anonymous ? [nil, @namespace_stack, true] : @assigned.last, anonymous) do
299
+ if node.name == :extend && (node.receiver.nil? || node.receiver.is_a?(Prism::SelfNode)) &&
300
+ !@self_unknown && @singleton_depth.zero?
301
+ args = node.arguments&.arguments || []
302
+ concern = args.any? { |arg| arg.slice.delete_prefix("::") == "ActiveSupport::Concern" }
303
+ @concern_modules << module_key if concern
304
+ end
305
+ case concern_block(node)
306
+ when :owner_unknown
307
+ hook = hook_block?(node)
308
+ return preserving_scope do
309
+ @hook_block ||= hook
310
+ @hook_call, @hook_uses = placeable_hook(node) if hook
311
+ @owner_unknown = true
312
+ super
313
+ end
314
+ when :class_methods
315
+ owner = named_owner((@block_namespace || @namespace_stack) + ["ClassMethods"])
316
+ anonymous = false
317
+ else
318
+ return super unless builds_class?(node)
319
+
320
+ anonymous = !@assigned&.first.equal?(node)
321
+ owner = anonymous ? [nil, @namespace_stack, true] : @assigned.last
322
+ end
323
+ with_block_owner(owner, anonymous) do
143
324
  @self_scope = node.block
144
325
  super
145
326
  end
@@ -215,24 +396,29 @@ module Mutineer
215
396
  # @param node [Prism::DefNode] method definition node.
216
397
  # @return [void]
217
398
  def visit_def_node(node)
218
- @subjects << Subject.new(
399
+ subject = Subject.new(
219
400
  file: @file,
220
401
  namespace: (@block_namespace || @namespace_stack).dup,
221
402
  lexical: @lexical_stack.dup,
222
403
  block_owner: @block_owner,
223
404
  owner_unknown: @owner_unknown,
405
+ hook_block: @hook_block,
406
+ reload_hook_call: reload_hook_call_for(node),
224
407
  name: node.name,
225
408
  singleton: !node.receiver.nil? || @singleton_depth.positive? || @module_function_active,
226
- def_node: node
409
+ def_node: node,
410
+ enclosing_subject: @enclosing_subject
227
411
  )
412
+ @subjects << subject
228
413
  @subject_keys << module_key
229
414
  saved_active = @module_function_active
230
- saved_self = [@self_unknown, @self_scope]
415
+ saved_self = [@self_unknown, @self_scope, @enclosing_subject]
231
416
  @self_unknown = true # `self` in a method body is the receiver it is called on
232
417
  @self_scope = node
418
+ @enclosing_subject = subject
233
419
  super
234
420
  @module_function_active = saved_active # a visibility call in a method body runs only when it is called
235
- @self_unknown, @self_scope = saved_self
421
+ @self_unknown, @self_scope, @enclosing_subject = saved_self
236
422
  end
237
423
 
238
424
  private
@@ -317,7 +503,7 @@ module Mutineer
317
503
  end
318
504
  @lexical_stack += [root ? "::#{name}" : name]
319
505
  @module_function_active = false
320
- @block_owner = @block_namespace = nil
506
+ @block_owner = @block_namespace = @hook_call = nil
321
507
  # redefine reopens the lexical chain, which does not pass through the block's `self`
322
508
  @namespace_unknown = @owner_unknown = in_singleton || self_in_block || @namespace_unknown
323
509
  @singleton_depth = 0
@@ -331,7 +517,7 @@ module Mutineer
331
517
  # Visitor state a class/module body or builder block sets for what it contains.
332
518
  SCOPE_STATE = %i[@namespace_stack @lexical_stack @module_function_active @block_owner @block_namespace
333
519
  @owner_unknown @singleton_depth @singleton_cref @namespace_unknown @anonymous_block @body
334
- @self_unknown @self_scope @singleton_uncertain].freeze
520
+ @self_unknown @self_scope @singleton_uncertain @hook_block @hook_call @hook_uses].freeze
335
521
 
336
522
  # Runs the block and then restores every {SCOPE_STATE} variable, so a
337
523
  # nested body's state never leaks out of it.
@@ -448,6 +634,108 @@ module Mutineer
448
634
  CLASS_BUILDERS[node.receiver&.slice&.delete_prefix("::")] == node.name
449
635
  end
450
636
 
637
+ # Sorts an ActiveSupport::Concern block by where redefine can load its defs.
638
+ # ActiveSupport evaluates a `class_methods` block in the module's `ClassMethods`,
639
+ # which it extends onto every includer, so the test calls `Includer.name` on
640
+ # that module's method, not on the concern (#252). In a class or module body,
641
+ # or a builder block, with a known owner, that module is `<namespace>::ClassMethods`.
642
+ # The block keeps the lexical scope, so redefine reopens the concern's chain and
643
+ # loads the mutant with `::Concern::ClassMethods.class_eval`. In a def, a block
644
+ # that does not build a class (Rails' `concerning :Name do`), `class << self`, or
645
+ # under an owner no constant names (an unassigned `Module.new`), no constant here
646
+ # names that `ClassMethods`. ActiveSupport evaluates an `included` or `prepended`
647
+ # block in each includer, which no constant names either. The call has no
648
+ # receiver or `self`, no arguments, and a block.
649
+ #
650
+ # Another library can define methods with these names and run the block in
651
+ # the module itself. So a `class_methods` block counts only in a module that ran
652
+ # `extend ActiveSupport::Concern` earlier in this file, in this body or an earlier
653
+ # one ({#module_key}). Any other block with these names is unplaceable: guessing
654
+ # its owner would load a mutant where the tests never call it.
655
+ #
656
+ # @param node [Prism::CallNode] call node.
657
+ # @return [Symbol, nil] `:class_methods` when redefine can name the module,
658
+ # `:owner_unknown` for any other Concern block, or nil for any other call.
659
+ def concern_block(node)
660
+ return unless CONCERN_BLOCKS.include?(node.name) && node.arguments.nil? && node.block.is_a?(Prism::BlockNode)
661
+ return unless node.receiver.nil? || node.receiver.is_a?(Prism::SelfNode)
662
+ placeable = node.name == :class_methods && !@self_unknown && @singleton_depth.zero? && !@owner_unknown &&
663
+ @concern_modules.include?(module_key)
664
+ placeable ? :class_methods : :owner_unknown
665
+ end
666
+
667
+ # True for an `included` or `prepended` block of a module that ran `extend
668
+ # ActiveSupport::Concern` earlier in this file (see {#concern_block}).
669
+ # ActiveSupport runs the block only when a class first includes or prepends
670
+ # the concern, so loading the file again stores the new block but never
671
+ # runs it in a class that already has the concern (#256). Reload can still
672
+ # place a def that sits directly in such a block (see {#placeable_hook} and
673
+ # {#reload_hook_call_for}, #297); anything else the block defines, a nested
674
+ # class or a builder block included, stays as the original wrote it.
675
+ #
676
+ # @param node [Prism::CallNode] a call {#concern_block} sorted as a concern block.
677
+ # @return [Boolean]
678
+ def hook_block?(node)
679
+ %i[included prepended].include?(node.name) && @concern_modules.include?(module_key)
680
+ end
681
+
682
+ # The hook call and the names its block calls outside its def bodies, when
683
+ # reload can place the block's defs (#297), else nil and an empty set. The
684
+ # call must be on a plain path ({Project.plain_path_calls}), so the statement
685
+ # the mutant file adds before it runs exactly when the call runs. An alias in
686
+ # the block keeps the original body, so a block with any `alias` or
687
+ # `alias_method` places nothing. The names come from bare calls, `self.`
688
+ # calls and the name given to `method`, `instance_method`, `send`,
689
+ # `public_send` or `__send__`, in every nested block and lambda too:
690
+ # discovery cannot tell a block that runs at once from one that runs
691
+ # later. A name such a call computes at runtime places nothing.
692
+ #
693
+ # @param node [Prism::CallNode] the hook call.
694
+ # @return [Array(Prism::CallNode, Set<Symbol>), Array(nil, Set<Symbol>)]
695
+ def placeable_hook(node)
696
+ uses = Set.new
697
+ return [nil, uses] unless @plain_calls.include?(node)
698
+
699
+ nodes = [node.block.body].compact
700
+ while (current = nodes.pop)
701
+ next if current.is_a?(Prism::DefNode)
702
+ return [nil, Set.new] if current.is_a?(Prism::AliasMethodNode)
703
+
704
+ if current.is_a?(Prism::CallNode) && (current.receiver.nil? || current.receiver.is_a?(Prism::SelfNode))
705
+ return [nil, Set.new] if current.name == :alias_method
706
+
707
+ uses << current.name
708
+ if NAME_TAKERS.include?(current.name) && (name_arg = current.arguments&.arguments&.first)
709
+ # A runtime name may be any def in the block.
710
+ return [nil, Set.new] unless name_arg.is_a?(Prism::SymbolNode) || name_arg.is_a?(Prism::StringNode)
711
+
712
+ uses << name_arg.unescaped.to_sym
713
+ end
714
+ end
715
+ nodes.concat(current.compact_child_nodes)
716
+ end
717
+ [node, uses]
718
+ end
719
+
720
+ # The hook call of the block this def sits in directly, when reload can
721
+ # place the def (#297), else nil. The def must be in the block itself, or
722
+ # in its `class << self` without a receiver: not in a def, a nested class
723
+ # or module, or another block. `module_function` gives the def a second,
724
+ # private copy, and a name the block itself uses kept the original's
725
+ # result, so neither is placeable. An explicit receiver other than `self`
726
+ # can be bound only inside the hook, which the extracted def does not keep.
727
+ #
728
+ # @param node [Prism::DefNode] the def being recorded.
729
+ # @return [Prism::CallNode, nil]
730
+ def reload_hook_call_for(node)
731
+ return unless @hook_call && @self_scope.equal?(@hook_call.block) && !@module_function_active
732
+ return if node.receiver && !node.receiver.is_a?(Prism::SelfNode)
733
+ return if @singleton_depth > 1 || (@singleton_depth == 1 && node.receiver)
734
+ return if @hook_uses.include?(node.name)
735
+
736
+ @hook_call
737
+ end
738
+
451
739
  # Runs the block with the defs it visits owned by the class a builder block builds.
452
740
  # The block body defines instance methods of that class, even inside `class << self`,
453
741
  # but its constants still land where the enclosing `class << self` puts them.
@@ -0,0 +1,73 @@
1
+ # frozen_string_literal: true
2
+
3
+ module Mutineer
4
+ # Pins the environment Rails and Spring read during a mutant run.
5
+ #
6
+ # Rails reads +PARALLEL_WORKERS+ inside +parallelize+ and uses it instead of
7
+ # the +workers:+ argument. A value of 1 keeps that run in one process.
8
+ # +--test-command+ also sets +DISABLE_SPRING+ so the Spring preloader does
9
+ # not start. {pin_process!} prints the replacement line once. The caller
10
+ # puts the process value back with {restore_process!} when the run ends.
11
+ module RailsRunEnv
12
+ # Value of +PARALLEL_WORKERS+ that keeps Rails test workers off.
13
+ PARALLEL_WORKERS = "1"
14
+
15
+ # Value of +DISABLE_SPRING+ that stops the Spring preloader.
16
+ DISABLE_SPRING = "1"
17
+
18
+ # Sets +PARALLEL_WORKERS+ to {PARALLEL_WORKERS} in this process.
19
+ # Prints one line when the previous value is set and is not already 1.
20
+ #
21
+ # @return [void]
22
+ def self.pin_process!
23
+ current = ENV["PARALLEL_WORKERS"]
24
+ warn(replacement_line(current)) if replace?(current)
25
+ ENV["PARALLEL_WORKERS"] = PARALLEL_WORKERS
26
+ nil
27
+ end
28
+
29
+ # Puts the caller's +PARALLEL_WORKERS+ back. +nil+ means it was unset.
30
+ #
31
+ # @param previous [String, nil]
32
+ # @return [void]
33
+ def self.restore_process!(previous)
34
+ if previous.nil?
35
+ ENV.delete("PARALLEL_WORKERS")
36
+ else
37
+ ENV["PARALLEL_WORKERS"] = previous
38
+ end
39
+ nil
40
+ end
41
+
42
+ # Forces +PARALLEL_WORKERS+ on a child environment.
43
+ # +spring+ also sets +DISABLE_SPRING+. The hash is the spawn delta or the
44
+ # full daemon environment. This does not change the parent process.
45
+ #
46
+ # @param env [Hash{String => String, nil}]
47
+ # @param spring [Boolean] set +DISABLE_SPRING+ when true.
48
+ # @return [void]
49
+ def self.pin_child!(env, spring: false)
50
+ env["PARALLEL_WORKERS"] = PARALLEL_WORKERS
51
+ env["DISABLE_SPRING"] = DISABLE_SPRING if spring
52
+ nil
53
+ end
54
+
55
+ # True when Mutineer must replace a +PARALLEL_WORKERS+ value the user set.
56
+ #
57
+ # @param current [String, nil]
58
+ # @return [Boolean]
59
+ def self.replace?(current)
60
+ !current.nil? && current != PARALLEL_WORKERS
61
+ end
62
+
63
+ # The one line printed when {replace?} is true.
64
+ #
65
+ # @param current [String]
66
+ # @return [String]
67
+ def self.replacement_line(current)
68
+ "[mutineer] PARALLEL_WORKERS was #{current.inspect}; using 1 so each mutant's tests run in one process. " \
69
+ "Unset it or set it to 1 to drop this line."
70
+ end
71
+ private_class_method :replace?, :replacement_line
72
+ end
73
+ end