mutineer 1.5.0 → 1.7.0

data/lib/mutineer/project.rb

@@ -28,6 +28,34 @@ module Mutineer
     # Walks an AST, maintaining a namespace stack, emitting Subjects.
     # Nested inside Project to signal its private role.
     class SubjectVisitor < Prism::Visitor
+      # Calls whose block is the body of the class they build: receiver name => method.
+      CLASS_BUILDERS = { "Data" => :define, "Struct" => :new, "Class" => :new, "Module" => :new }.freeze
+
+      # ActiveSupport::Concern calls whose block another module or class runs (see {#concern_block}).
+      CONCERN_BLOCKS = %i[class_methods included prepended].freeze
+
+      # A constant name, or a path of them; Ruby allows Unicode in both.
+      CONSTANT_PATH = /\A[[:upper:]][[:word:]]*(?:::[[:upper:]][[:word:]]*)*\z/
+
+      # A name that reads like a constant name but may not be one (#216). It is
+      # the singleton class name of a `class << self` opened inside a def or a
+      # block that does not build a class, or built on a written path or
+      # `#<anonymous>` (`#<Class:Foo::X>` from `class Foo::X` inside `class << self`);
+      # or the `X` of `module self::X` or `self::X = ...` in a def or a block. The segment carries that mark (see
+      # {#singleton_name}, {#with_namespace}, {#assigned_owner}), and `scope`, the
+      # def or block whose `self` the name is under, or a new object when unknown.
+      class WrittenName < String
+        # @return [Object] the def or block node whose `self` the name is under.
+        attr_reader :scope
+
+        # @param name [String] the name as built.
+        # @param scope [Object] the def or block node whose `self` the name is under.
+        def initialize(name, scope = Object.new)
+          super(name)
+          @scope = scope
+        end
+      end
+
       attr_reader :subjects
 
       # Builds a subject visitor.
@@ -40,22 +68,35 @@ module Mutineer
         @subjects = []
         @singleton_depth = 0
         @module_function_active = false # bareword `module_function` seen in this module body
-        @module_function_names = []     # [namespace, name] from `module_function :a` / `module_function def` (#98)
+        @module_function_names = []     # [module key, name] from `module_function :a` / `module_function def` (#98)
+        @subject_keys = []              # the module key of each subject, by index
+        @body = Object.new              # identifies the class/module body or builder block being visited
+        @block_owner = nil
+        @block_namespace = nil
+        @owner_unknown = false
+        @assigned = nil
+        @singleton_cref = nil # the singleton class name, in a builder block inside `class << self`
+        @namespace_unknown = false # the namespace is under a singleton class (#208) or a block's `self` (#229)
+        @anonymous_block = false   # inside a builder block not assigned to a constant
+        @self_unknown = false      # inside a def or a block that is not a builder, so `self` is not the namespace
+        @self_scope = nil          # the def or block whose `self` the code runs with
+        @singleton_uncertain = false # the open `class << self` was inside a def or a non-builder block
+        @concern_modules = Set.new   # the {#module_key} of each module that ran `extend ActiveSupport::Concern`
+        @hook_block = false          # inside a concern's `included` or `prepended` block (see {#hook_block?})
         super()
       end
 
       # Promote `module_function :name` / `module_function def name` subjects to
       # singleton after the full walk — the naming call may appear before or after
       # the def, so it can't be decided at visit_def_node time (#20). Only methods
-      # of the module that made the call are promoted (#98); namespaces compare
-      # joined, since `module A::B` and nested `module A; module B` differ as arrays.
+      # of the module that made the call are promoted (#98), matched by {#module_key}.
       #
       # @return [void]
       def promote_module_functions!
         return if @module_function_names.empty?
 
         named = @module_function_names.to_set
-        @subjects.each { |s| s.singleton = true if named.include?([s.namespace.join("::"), s.name]) }
+        @subjects.each_with_index { |s, i| s.singleton = true if named.include?([@subject_keys[i], s.name]) }
       end
 
       # Visits class nodes and tracks namespace nesting.
@@ -77,7 +118,15 @@ module Mutineer
       # Track `module_function` so its methods are recorded as singletons (#20) —
       # the called form is the singleton method on the module object. Bareword
       # `module_function` flips all SUBSEQUENT defs in this body; the argument
-      # forms (`:sym`, `def`) name methods promoted after the walk.
+      # forms (`:sym`, `def`) name methods promoted after the walk. A builder
+      # block's defs belong to the class it builds; one not assigned to a
+      # constant has no name, so its subjects are marked `owner_unknown`, and a
+      # `module_function :name` in it promotes nothing. Elsewhere it promotes the
+      # methods of the same module, matched by {#module_key}. A module that runs
+      # `extend ActiveSupport::Concern` is a concern from then on in this file. A
+      # `class_methods` block in its body (see {#concern_block}) is visited like a
+      # builder block that builds the module's `ClassMethods`, so its defs belong to
+      # that module (#252). The defs in any other such block have their owner unknown.
       #
       # @param node [Prism::CallNode] call node.
       # @return [void]
@@ -89,16 +138,85 @@ module Mutineer
           args = node.arguments&.arguments || []
           if args.empty?
             @module_function_active = true
-          else
-            namespace = @namespace_stack.join("::")
+          elsif !@anonymous_block
             args.each do |arg|
-              @module_function_names << [namespace, arg.value.to_sym] if arg.is_a?(Prism::SymbolNode)
-              @module_function_names << [namespace, arg.name] if arg.is_a?(Prism::DefNode)
+              @module_function_names << [module_key, arg.value.to_sym] if arg.is_a?(Prism::SymbolNode)
+              @module_function_names << [module_key, arg.name] if arg.is_a?(Prism::DefNode)
             end
           end
         end
+        if node.name == :extend && (node.receiver.nil? || node.receiver.is_a?(Prism::SelfNode)) &&
+           !@self_unknown && @singleton_depth.zero?
+          args = node.arguments&.arguments || []
+          concern = args.any? { |arg| arg.slice.delete_prefix("::") == "ActiveSupport::Concern" }
+          @concern_modules << module_key if concern
+        end
+        case concern_block(node)
+        when :owner_unknown
+          hook = hook_block?(node)
+          return preserving_scope do
+            @hook_block ||= hook
+            @owner_unknown = true
+            super
+          end
+        when :class_methods
+          owner = named_owner((@block_namespace || @namespace_stack) + ["ClassMethods"])
+          anonymous = false
+        else
+          return super unless builds_class?(node)
+
+          anonymous = !@assigned&.first.equal?(node)
+          owner = anonymous ? [nil, @namespace_stack, true] : @assigned.last
+        end
+        with_block_owner(owner, anonymous) do
+          @self_scope = node.block
+          super
+        end
+      end
+
+      # A block that does not build a class may run with any `self` (`class_eval`,
+      # `instance_eval`, a callback), so a `class << self` in it names a singleton
+      # class Mutineer cannot be sure of (#216). A lambda is treated the same.
+      #
+      # @param node [Prism::BlockNode, Prism::LambdaNode] block or lambda node.
+      # @return [void]
+      def visit_block_node(node)
+        return super if node.equal?(@self_scope) # a builder block
+
+        saved_self = [@self_unknown, @self_scope]
+        @self_unknown = true
+        @self_scope = node
         super
+        @self_unknown, @self_scope = saved_self
       end
+      alias visit_lambda_node visit_block_node
+
+      # Names the class a builder block assigned to this constant builds (see {#builds_class?}).
+      #
+      # `=`, `||=` and `&&=` store the class, so each names it; `+=` stores what `+`
+      # returns, so its builder is left unnamed.
+      #
+      # @param node [Prism::ConstantWriteNode, Prism::ConstantPathWriteNode, Prism::ConstantOrWriteNode,
+      #   Prism::ConstantAndWriteNode, Prism::ConstantPathOrWriteNode, Prism::ConstantPathAndWriteNode]
+      #   constant assignment.
+      # @return [void]
+      def visit_constant_write_node(node)
+        call = assigned_value(node.value)
+        return super unless builds_class?(call)
+
+        saved = @assigned
+        @assigned = [call, assigned_owner(node)]
+        begin
+          super
+        ensure
+          @assigned = saved
+        end
+      end
+      alias visit_constant_path_write_node visit_constant_write_node
+      alias visit_constant_or_write_node visit_constant_write_node
+      alias visit_constant_and_write_node visit_constant_write_node
+      alias visit_constant_path_or_write_node visit_constant_write_node
+      alias visit_constant_path_and_write_node visit_constant_write_node
 
       # Methods inside `class << self` are class methods of the enclosing
       # namespace, but their def nodes have no receiver — track the singleton
@@ -113,8 +231,11 @@ module Mutineer
 
         @singleton_depth += 1
         saved_active = @module_function_active
+        saved_uncertain = @singleton_uncertain
+        @singleton_uncertain ||= @self_unknown # `self` here may be another object (#216)
         super
         @module_function_active = saved_active # a visibility call in here is not the module body's
+        @singleton_uncertain = saved_uncertain
         @singleton_depth -= 1
       end
 
@@ -125,42 +246,311 @@ module Mutineer
       def visit_def_node(node)
         @subjects << Subject.new(
           file: @file,
-          namespace: @namespace_stack.dup,
+          namespace: (@block_namespace || @namespace_stack).dup,
           lexical: @lexical_stack.dup,
+          block_owner: @block_owner,
+          owner_unknown: @owner_unknown,
+          hook_block: @hook_block,
           name: node.name,
           singleton: !node.receiver.nil? || @singleton_depth.positive? || @module_function_active,
           def_node: node
         )
+        @subject_keys << module_key
         saved_active = @module_function_active
+        saved_self = [@self_unknown, @self_scope]
+        @self_unknown = true # `self` in a method body is the receiver it is called on
+        @self_scope = node
         super
         @module_function_active = saved_active # a visibility call in a method body runs only when it is called
+        @self_unknown, @self_scope = saved_self
       end
 
       private
 
+      # The module a `module_function` call and a def are matched by: its joined
+      # namespace, so a module reopened later in the file matches (#216), and
+      # `module A::B` matches nested `module A; module B`. An unknown owner that an
+      # anonymous builder block owns, or whose name has no {WrittenName} segment
+      # and is not built only from constant names (see {#named_segment?}), may be
+      # shared by another module, so it is matched only within this body (#208).
+      # Otherwise a name with a {WrittenName}
+      # segment is matched by that segment's scope and text, so openings under one
+      # `self` match each other, but not those under another, whether the owner is
+      # known or not (#229).
+      #
+      # @return [String, Object]
+      def module_key
+        namespace = @block_namespace || @namespace_stack
+        written = written?(namespace)
+        return @body if @owner_unknown && (@anonymous_block || !written && !namespace.all? { |s| named_segment?(s) })
+        return namespace.join("::") unless written
+
+        namespace.map { |s| s.is_a?(WrittenName) ? "#{s.scope.object_id}:#{s}" : s }.join("::")
+      end
+
+      # True when any segment of the namespace is a {WrittenName}.
+      #
+      # @param namespace [Array<String>] namespace segments.
+      # @return [Boolean]
+      def written?(namespace)
+        namespace.any?(WrittenName)
+      end
+
+      # True when a namespace segment is a constant name, or a singleton class
+      # (`#<Class:App::M>`) of constant names. A written path or `#<anonymous>` is
+      # not, nor is a singleton class name built on one ({WrittenName}).
+      #
+      # @param segment [String] namespace segment.
+      # @return [Boolean]
+      def named_segment?(segment)
+        !segment.is_a?(WrittenName) && segment.gsub(/#<Class:|>/, "").match?(CONSTANT_PATH) &&
+          (segment.start_with?("#<Class:") || !segment.include?("::"))
+      end
+
       # Runs the block with `path` pushed as the current namespace. A
       # root-anchored path (`module ::X` / `class ::X`) names the top-level X,
       # not X nested in the enclosing scope, so the namespace restarts there.
       # Bareword `module_function` state does not cross a class or module
       # boundary: each body starts without it, and the outer state returns after.
+      # A class or module `X` opened inside `class << self`, even within a builder
+      # block there, is a constant of the singleton class, which has no constant
+      # path. It and everything nested in it is named under `#<Class:...>` with
+      # its owner unknown (#208), and its body defines instance methods again.
+      # A compact `Foo::X` or a top-level `::X` there is named as written, and
+      # its owner is unknown too: redefine reopens the lexical chain without the
+      # singleton class, so constants the body looks up through it would not resolve.
+      # A `self::X` in any block is under the block's `self`, not the namespace
+      # around the block (#229). In a builder block that is the built class, so
+      # it is named under the builder's constant; in any other block (`class_eval`,
+      # a callback) `self` may be any object, so it is named under the innermost
+      # enclosing builder's constant, or else the enclosing namespace. Either way
+      # the last segment is a {WrittenName}, and it and everything nested in it
+      # has its owner unknown. Redefine reopens the lexical chain (`module Outer;
+      # module X`), which never reaches the block's `self`; reopening X through
+      # its constant with `class_eval`, as for `self::X = ...` in a builder block,
+      # would drop X from `Module.nesting`, so constants its body looks up would not resolve.
       #
       # @param path [Prism::Node] the class/module constant path.
       # @yield the class or module body visit.
       # @return [void]
       def with_namespace(path)
-        saved_stack = @namespace_stack
-        saved_lexical = @lexical_stack
-        saved_active = @module_function_active
-        name = extract_constant_name(path)
-        root = root_anchored?(path)
-        @namespace_stack = root ? [name] : saved_stack + [name]
-        @lexical_stack = saved_lexical + [root ? "::#{name}" : name]
-        @module_function_active = false
+        preserving_scope do
+          name = extract_constant_name(path)
+          root = root_anchored?(path)
+          in_singleton = !@singleton_cref.nil? || @singleton_depth.positive?
+          self_in_block = !in_singleton && !root && self_rooted?(path) && (!@block_namespace.nil? || @self_unknown)
+          @namespace_stack =
+            if root then [name]
+            elsif in_singleton then path.is_a?(Prism::ConstantPathNode) ? [path.slice] : [singleton_name, name]
+            elsif self_in_block then (@block_namespace || @namespace_stack) + [WrittenName.new(name, @self_scope)]
+            else @namespace_stack + [name]
+            end
+          @lexical_stack += [root ? "::#{name}" : name]
+          @module_function_active = false
+          @block_owner = @block_namespace = nil
+          # redefine reopens the lexical chain, which does not pass through the block's `self`
+          @namespace_unknown = @owner_unknown = in_singleton || self_in_block || @namespace_unknown
+          @singleton_depth = 0
+          @singleton_cref = nil
+          @anonymous_block = @self_unknown = @singleton_uncertain = false
+          @body = Object.new
+          yield
+        end
+      end
+
+      # Visitor state a class/module body or builder block sets for what it contains.
+      SCOPE_STATE = %i[@namespace_stack @lexical_stack @module_function_active @block_owner @block_namespace
+                       @owner_unknown @singleton_depth @singleton_cref @namespace_unknown @anonymous_block @body
+                       @self_unknown @self_scope @singleton_uncertain @hook_block].freeze
+
+      # Runs the block and then restores every {SCOPE_STATE} variable, so a
+      # nested body's state never leaks out of it.
+      #
+      # @yield the nested visit.
+      # @return [void]
+      def preserving_scope
+        saved = SCOPE_STATE.map { |name| instance_variable_get(name) }
         yield
       ensure
-        @namespace_stack = saved_stack
-        @lexical_stack = saved_lexical
-        @module_function_active = saved_active
+        SCOPE_STATE.zip(saved) { |name, value| instance_variable_set(name, value) }
+      end
+
+      # Resolves the constant an assignment writes the way Ruby does. `X` is in the
+      # current namespace, `::X` and a path at the top level start from Object, and
+      # `self::X` is under the current class (the built class inside a builder
+      # block). In a block that does not build a class, `self` may be any object,
+      # so `self::X` there has its owner unknown (#229). Any other path is
+      # looked up at run time, so its owner is unknown
+      # and the subject is named as written. Lexically inside `class << self`,
+      # even within a builder block there, the constant belongs to the singleton
+      # class, which has no constant path, so its owner is unknown too, as is
+      # `X` or `self::X` in a class or module opened there (#208). A `::X` there
+      # is named `X`, still unknown (see {#with_namespace}).
+      #
+      # @param node [Prism::Node] constant assignment.
+      # @return [Array(String, Array<String>, Boolean)] owner, namespace, unknown.
+      def assigned_owner(node)
+        if @singleton_cref || @singleton_depth.positive?
+          written = node.respond_to?(:target) ? node.target.slice : node.name.to_s
+          return [nil, written.start_with?("::") ? [written.delete_prefix("::")] : [singleton_name, written], true]
+        end
+        unless node.respond_to?(:target)
+          namespace = @namespace_stack + [node.name.to_s]
+          return @namespace_unknown ? [nil, namespace, true] : named_owner(namespace)
+        end
+
+        names = []
+        path = node.target
+        while path.is_a?(Prism::ConstantPathNode)
+          names.unshift(path.name.to_s)
+          path = path.parent
+        end
+        # see {#with_namespace}; in a builder block too, so a later `module self::X` there matches it
+        if path.is_a?(Prism::SelfNode) && (@self_unknown || @block_namespace)
+          names[0] = WrittenName.new(names[0], @self_scope)
+        end
+        if path.is_a?(Prism::SelfNode) && (@self_unknown || @namespace_unknown && !@anonymous_block)
+          return [nil, (@block_namespace || @namespace_stack) + names, true]
+        end
+
+        base =
+          case path
+          when nil then []
+          when Prism::SelfNode then @block_namespace || @namespace_stack unless @owner_unknown
+          when Prism::ConstantReadNode then [path.name.to_s] if @namespace_stack.empty?
+          end
+        return [nil, [node.target.slice], true] unless base
+
+        @namespace_unknown ? [nil, base + names, true] : named_owner(base + names)
+      end
+
+      # Names the singleton class that owns the constants written here: `class << self`
+      # opens that of the current class (the built class inside a builder block),
+      # and a builder block inside `class << self` keeps the enclosing one. A block
+      # not assigned to a constant builds a class with no name, written `#<anonymous>`.
+      # Each nested `class << self` opens the singleton class of the one around it.
+      # A name built on a written path or `#<anonymous>`, or opened where `self` may
+      # be another object (in a def or a non-builder block), is a {WrittenName} (see {#module_key}).
+      #
+      # @return [String] e.g. `#<Class:App>`, or `#<Class:#<Class:App>>` two deep.
+      def singleton_name
+        return @singleton_cref unless @singleton_depth.positive?
+
+        base = @anonymous_block ? @namespace_stack + ["#<anonymous>"] : @block_namespace || @namespace_stack
+        name = @singleton_depth.times.reduce(base.join("::")) { |inner, _| "#<Class:#{inner}>" }
+        named = !@singleton_uncertain && (@owner_unknown ? base.all? { |s| named_segment?(s) } : !written?(base))
+        named ? name : WrittenName.new(name)
+      end
+
+      # The owner for a resolved namespace, root-anchored so the redefine
+      # wrapper loads onto that constant from any nesting.
+      #
+      # @param namespace [Array<String>] resolved namespace.
+      # @return [Array(String, Array<String>, Boolean)]
+      def named_owner(namespace)
+        ["::#{namespace.join("::")}", namespace, false]
+      end
+
+      # The value an assignment stores: the last statement inside parentheses or a
+      # `begin` without `rescue`, which Ruby returns from them.
+      #
+      # @param node [Prism::Node] assigned expression.
+      # @return [Prism::Node, nil]
+      def assigned_value(node)
+        loop do
+          body =
+            case node
+            when Prism::ParenthesesNode then node.body
+            when Prism::BeginNode then node.statements unless node.rescue_clause
+            end
+          return node unless body
+
+          node = body.is_a?(Prism::StatementsNode) ? body.body.last : body
+        end
+      end
+
+      # True when the node is `Data.define`, `Struct.new`, `Class.new` or `Module.new` with a block.
+      #
+      # @param node [Prism::Node, nil] node.
+      # @return [Boolean]
+      def builds_class?(node)
+        node.is_a?(Prism::CallNode) && node.block.is_a?(Prism::BlockNode) &&
+          CLASS_BUILDERS[node.receiver&.slice&.delete_prefix("::")] == node.name
+      end
+
+      # Sorts an ActiveSupport::Concern block by where redefine can load its defs.
+      # ActiveSupport evaluates a `class_methods` block in the module's `ClassMethods`,
+      # which it extends onto every includer, so the test calls `Includer.name` on
+      # that module's method, not on the concern (#252). In a class or module body,
+      # or a builder block, with a known owner, that module is `<namespace>::ClassMethods`.
+      # The block keeps the lexical scope, so redefine reopens the concern's chain and
+      # loads the mutant with `::Concern::ClassMethods.class_eval`. In a def, a block
+      # that does not build a class (Rails' `concerning :Name do`), `class << self`, or
+      # under an owner no constant names (an unassigned `Module.new`), no constant here
+      # names that `ClassMethods`. ActiveSupport evaluates an `included` or `prepended`
+      # block in each includer, which no constant names either. The call has no
+      # receiver or `self`, no arguments, and a block.
+      #
+      # Another library can define methods with these names and run the block in
+      # the module itself. So a `class_methods` block counts only in a module that ran
+      # `extend ActiveSupport::Concern` earlier in this file, in this body or an earlier
+      # one ({#module_key}). Any other block with these names is unplaceable: guessing
+      # its owner would load a mutant where the tests never call it.
+      #
+      # @param node [Prism::CallNode] call node.
+      # @return [Symbol, nil] `:class_methods` when redefine can name the module,
+      #   `:owner_unknown` for any other Concern block, or nil for any other call.
+      def concern_block(node)
+        return unless CONCERN_BLOCKS.include?(node.name) && node.arguments.nil? && node.block.is_a?(Prism::BlockNode)
+        return unless node.receiver.nil? || node.receiver.is_a?(Prism::SelfNode)
+        placeable = node.name == :class_methods && !@self_unknown && @singleton_depth.zero? && !@owner_unknown &&
+                    @concern_modules.include?(module_key)
+        placeable ? :class_methods : :owner_unknown
+      end
+
+      # True for an `included` or `prepended` block of a module that ran `extend
+      # ActiveSupport::Concern` earlier in this file (see {#concern_block}).
+      # ActiveSupport runs the block only when a class first includes or prepends
+      # the concern, so loading the file again stores the new block but never
+      # runs it in a class that already has the concern (#256). Everything the
+      # block defines, a nested class or a builder block included, stays as the
+      # original wrote it under `--strategy reload`.
+      #
+      # @param node [Prism::CallNode] a call {#concern_block} sorted as a concern block.
+      # @return [Boolean]
+      def hook_block?(node)
+        %i[included prepended].include?(node.name) && @concern_modules.include?(module_key)
+      end
+
+      # Runs the block with the defs it visits owned by the class a builder block builds.
+      # The block body defines instance methods of that class, even inside `class << self`,
+      # but its constants still land where the enclosing `class << self` puts them.
+      #
+      # @param owner [Array(String, Array<String>, Boolean)] the owner as written, its namespace,
+      #   and whether that name is unknown.
+      # @param anonymous [Boolean] true when the block is not assigned to a constant.
+      # @yield the builder call visit.
+      # @return [void]
+      def with_block_owner(owner, anonymous)
+        preserving_scope do
+          @singleton_cref = singleton_name if @singleton_depth.positive?
+          @block_owner, @block_namespace, @owner_unknown = owner
+          @anonymous_block = anonymous
+          @self_unknown = @singleton_uncertain = false
+          @module_function_active = false
+          @singleton_depth = 0
+          @body = Object.new
+          yield
+        end
+      end
+
+      # True when a constant path starts with `self` (e.g. `self::X`).
+      #
+      # @param node [Prism::Node] constant path node.
+      # @return [Boolean]
+      def self_rooted?(node)
+        node = node.parent while node.is_a?(Prism::ConstantPathNode)
+        node.is_a?(Prism::SelfNode)
       end
 
       # True when a constant path starts with `::` (e.g. `::X` or `::A::B`).

data/lib/mutineer/rails_run_env.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module Mutineer
+  # Pins the environment Rails and Spring read during a mutant run.
+  #
+  # Rails reads +PARALLEL_WORKERS+ inside +parallelize+ and uses it instead of
+  # the +workers:+ argument. A value of 1 keeps that run in one process.
+  # +--test-command+ also sets +DISABLE_SPRING+ so the Spring preloader does
+  # not start. {pin_process!} prints the replacement line once. The caller
+  # puts the process value back with {restore_process!} when the run ends.
+  module RailsRunEnv
+    # Value of +PARALLEL_WORKERS+ that keeps Rails test workers off.
+    PARALLEL_WORKERS = "1"
+
+    # Value of +DISABLE_SPRING+ that stops the Spring preloader.
+    DISABLE_SPRING = "1"
+
+    # Sets +PARALLEL_WORKERS+ to {PARALLEL_WORKERS} in this process.
+    # Prints one line when the previous value is set and is not already 1.
+    #
+    # @return [void]
+    def self.pin_process!
+      current = ENV["PARALLEL_WORKERS"]
+      warn(replacement_line(current)) if replace?(current)
+      ENV["PARALLEL_WORKERS"] = PARALLEL_WORKERS
+      nil
+    end
+
+    # Puts the caller's +PARALLEL_WORKERS+ back. +nil+ means it was unset.
+    #
+    # @param previous [String, nil]
+    # @return [void]
+    def self.restore_process!(previous)
+      if previous.nil?
+        ENV.delete("PARALLEL_WORKERS")
+      else
+        ENV["PARALLEL_WORKERS"] = previous
+      end
+      nil
+    end
+
+    # Forces +PARALLEL_WORKERS+ on a child environment.
+    # +spring+ also sets +DISABLE_SPRING+. The hash is the spawn delta or the
+    # full daemon environment. This does not change the parent process.
+    #
+    # @param env [Hash{String => String, nil}]
+    # @param spring [Boolean] set +DISABLE_SPRING+ when true.
+    # @return [void]
+    def self.pin_child!(env, spring: false)
+      env["PARALLEL_WORKERS"] = PARALLEL_WORKERS
+      env["DISABLE_SPRING"] = DISABLE_SPRING if spring
+      nil
+    end
+
+    # True when Mutineer must replace a +PARALLEL_WORKERS+ value the user set.
+    #
+    # @param current [String, nil]
+    # @return [Boolean]
+    def self.replace?(current)
+      !current.nil? && current != PARALLEL_WORKERS
+    end
+
+    # The one line printed when {replace?} is true.
+    #
+    # @param current [String]
+    # @return [String]
+    def self.replacement_line(current)
+      "[mutineer] PARALLEL_WORKERS was #{current.inspect}; using 1 so each mutant's tests run in one process. " \
+        "Unset it or set it to 1 to drop this line."
+    end
+    private_class_method :replace?, :replacement_line
+  end
+end