Module: Mutineer::ConcernBlocks

Defined in:
lib/mutineer/concern_blocks.rb

Overview

Lets the reload strategy load a concern file a second time (#256).

ActiveSupport::Concern stores an included or prepended block once. A second block with another source_location raises MultipleIncludedBlocks (or MultiplePrependBlocks). Rails reloads keep the file's path, but a mutant loads from a temp file beside it, so every mutant of a concern with such a block would error. ConcernBlocks.forget removes the stored blocks that the source file defined, so the mutant's load stores its own. ConcernBlocks.replace wraps the load and puts back any block the load did not store again, such as one under an unless defined? guard.

ActiveSupport does not run the block again in a class that already includes the concern, so that class keeps what the original block defined. For a def in the block, the mutant file also passes the mutated def to ConcernBlocks.store_hook_def, just before the included or prepended call. Under ConcernBlocks.load_mutant with a hook_def, ConcernBlocks.store_hook_def then calls ConcernBlocks.place_hook_def at once, which loads only that def into each class that has the method (#297). It runs before the rest of the file, so a later line of the file that calls the method while the file loads gets the mutant (#348). Nothing else in the block runs again. Discovery decides which defs can be placed this way (see Subject#unplaceable?).

Call it only in a forked child that loads the mutant. Without ActiveSupport, ConcernBlocks.replace and ConcernBlocks.forget do nothing; ConcernBlocks.store_hook_def and ConcernBlocks.place_hook_def work without it.

Stdlib-only, so the app-side daemon can load it.

Constant Summary collapse

STORED_BLOCKS =

Where ActiveSupport::Concern stores each block.

%i[@_included_block @_prepended_block].freeze
KERNEL_CLASS =

Kernel#class, unbound, so a proxy that redefines class cannot answer.

::Kernel.instance_method(:class)

Class Method Summary collapse

Class Method Details

.aliases(modules, source_file:, line:, name:, singleton:) ⇒ Array<Array(Module, Symbol)>

Each other name any module has for the original def: an alias made outside the block. Check independently of owners: a wrapper can replace the original name while its alias keeps the original body, so the mutant could falsely survive even when no current-name owner remains.

Parameters:

  • modules (Array<Module>) —

    every module, including singleton classes.

  • source_file (String) —

    the file the mutant replaces.

  • line (Integer) —

    the original def's first line.

  • name (Symbol) —

    the method name.

  • singleton (Boolean) —

    true for a class method.

Returns:

  • (Array<Array(Module, Symbol)>) —

    each module and its alias name.



224
225
226
227
228
229
230
231
232
# File 'lib/mutineer/concern_blocks.rb', line 224

def self.aliases(modules, source_file:, line:, name:, singleton:)
  path = real_path(source_file)
  modules.flat_map do |mod|
    target = singleton ? mod.singleton_class : mod
    (target.instance_methods(false) + target.private_instance_methods(false)).filter_map do |other|
      [mod, other] if other != name && own_method_at?(target, other, path, line, original_name: name)
    end
  end
end

.deprecation_proxy?(mod) ⇒ Boolean

True for Rails' DeprecatedConstantProxy: a Module that forwards every call to its target and prints a deprecation warning, so asking it for methods would print one per mutant (#387). Kernel#class reads its real class without forwarding.

Parameters:

  • mod (Module) —

    a module from the ObjectSpace walk.

Returns:

  • (Boolean)


313
314
315
316
317
# File 'lib/mutineer/concern_blocks.rb', line 313

def self.deprecation_proxy?(mod)
  return false unless defined?(::ActiveSupport::Deprecation::DeprecatedConstantProxy)

  (KERNEL_CLASS.bind_call(mod) <= ::ActiveSupport::Deprecation::DeprecatedConstantProxy) == true
end

.forget(source_file) ⇒ Array<Array(Module, Symbol, Proc)>

Removes every stored included and prepended block that the source file defined, from every concern. Blocks from other files stay.

Parameters:

  • source_file (String) —

    the file the mutant replaces.

Returns:

  • (Array<Array(Module, Symbol, Proc)>) —

    each concern, where it stored the block, and the block removed.



105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
# File 'lib/mutineer/concern_blocks.rb', line 105

def self.forget(source_file)
  return [] unless defined?(::ActiveSupport::Concern)

  path = real_path(source_file)
  forgotten = []
  ObjectSpace.each_object(::ActiveSupport::Concern) do |concern|
    STORED_BLOCKS.each do |name|
      next unless concern.instance_variable_defined?(name)

      block = concern.instance_variable_get(name)
      file = block.source_location&.first
      next unless file && real_path(file) == path

      concern.remove_instance_variable(name)
      forgotten << [concern, name, block]
    end
  end
  forgotten
end

.load_mutant(source_file, path, hook_def: nil) ⇒ Object

Loads the mutant file at path over source_file, through replace inside ReloadGuards.during_load, so Rails macros in the class body can run a second time (#378, #383, #384). The load assigns each of the file's constants a second time, so Ruby would warn twice per constant, per mutant (#364). Warnings are off for the load only, and back on before the tests run.

With a hook_def, the file's store_hook_def call places the mutated def during the load (#348). A load that never reached that call raises. When a handle to the original is live at placement, the kept-handle check runs again after the load, so a handle the file holds only while it loads does not count. Placement leaves no other way to reach the original, so no handle seen then means none after the load.

Parameters:

  • source_file (String) —

    the file the mutant replaces.

  • path (String) —

    the mutant file to load.

  • hook_def (Hash{Symbol => Object}, nil) (defaults to: nil) —

    the original def's line, name and singleton, from JobPlan.hook_mutant.

Returns:

  • (Object) —

    what load returns.

Raises:



74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
# File 'lib/mutineer/concern_blocks.rb', line 74

def self.load_mutant(source_file, path, hook_def: nil)
  @hook_target = hook_def && { source_file: source_file, **hook_def }
  @hook_def = nil
  @handle_at_placement = false
  loaded = ReloadGuards.during_load(source_file, path) do
    replace(source_file) do
      verbose, $VERBOSE = $VERBOSE, nil
      begin
        load path
      ensure
        $VERBOSE = verbose
      end
    end
  end
  if @hook_target
    # Still set: the load did not reach store_hook_def, so this raises.
    place_hook_def(**@hook_target)
  elsif @handle_at_placement
    refuse_retained_hook_def(source_file: source_file, line: hook_def[:line], name: hook_def[:name])
  end
  loaded
ensure
  @hook_target = nil
end

.method_handle_at?(path, line, name) ⇒ Boolean

True when the heap contains a handle for this original definition. Return only a boolean, so the first check does not itself retain a dead handle across the GC in retained_hook_def?.

Parameters:

  • path (String) —

    the source file's real path.

  • line (Integer) —

    the original def's first line.

  • name (Symbol) —

    the original method name.

Returns:

  • (Boolean)


297
298
299
300
301
302
303
304
# File 'lib/mutineer/concern_blocks.rb', line 297

def self.method_handle_at?(path, line, name)
  [Method, UnboundMethod].any? do |kind|
    ObjectSpace.each_object(kind).any? do |method|
      file, def_line = method.source_location
      method.original_name == name && def_line == line && !file.nil? && real_path(file) == path
    end
  end
end

.own_method_at?(target, name, path, line, original_name: name) ⇒ Boolean

True when the module's own method name starts at this file and line. A prepended method can hide it from instance_method, so follow super until the lookup reaches the method whose owner is the module itself.

Parameters:

  • target (Module) —

    the module or singleton class to read.

  • name (Symbol) —

    the method name.

  • path (String) —

    the source file's real path.

  • line (Integer) —

    the def's first line.

  • original_name (Symbol) (defaults to: name) —

    the name the original definition used; distinguishes an alias from another definition on the same line.

Returns:

  • (Boolean)


245
246
247
248
249
250
251
252
253
254
# File 'lib/mutineer/concern_blocks.rb', line 245

def self.own_method_at?(target, name, path, line, original_name: name)
  return false unless target.method_defined?(name, false) || target.private_method_defined?(name, false)

  method = target.instance_method(name)
  method = method.super_method while method && !method.owner.equal?(target)
  return false unless method

  file, def_line = method.source_location
  method.original_name == original_name && def_line == line && !file.nil? && real_path(file) == path
end

.owners(modules, source_file:, line:, name:, singleton:) ⇒ Array<Module>

Each module whose own method name (its singleton class's, for a class method) has the original def's file and line: every place the original block defined it. A subclass that overrides the method, or a class that only inherits it, is not one.

Parameters:

  • modules (Array<Module>) —

    every module, including singleton classes into which a concern can be included.

  • source_file (String) —

    the file the mutant replaces.

  • line (Integer) —

    the original def's first line.

  • name (Symbol) —

    the method name.

  • singleton (Boolean) —

    true for a class method.

Returns:

  • (Array<Module>)


208
209
210
211
# File 'lib/mutineer/concern_blocks.rb', line 208

def self.owners(modules, source_file:, line:, name:, singleton:)
  path = real_path(source_file)
  modules.select { |mod| own_method_at?(singleton ? mod.singleton_class : mod, name, path, line) }
end

.place_hook_def(source_file:, line:, name:, singleton:, check_retained: true) ⇒ Integer

Takes the def store_hook_def kept, clears it, and runs it with class_eval in each module whose own method came from the original def (see owners), so that module gets the mutated method and nothing else in the block runs again. Each owner keeps the method's visibility. A class that includes the concern later gets the mutant from the stored block.

Parameters:

  • source_file (String) —

    the file the mutant replaces.

  • line (Integer) —

    the original def's first line.

  • name (Symbol) —

    the method name.

  • singleton (Boolean) —

    true for a class method.

  • check_retained (Boolean) (defaults to: true) —

    false when the caller checks for a kept method handle itself, after the load (load_mutant).

Returns:

  • (Integer) —

    how many owners got the mutated def.

Raises:

  • (RuntimeError) —

    when no def was kept (the mutant file did not reach its hook call), or when a module keeps the original under another name (see aliases) or in a live method handle; the child then scores the mutant error.



163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
# File 'lib/mutineer/concern_blocks.rb', line 163

def self.place_hook_def(source_file:, line:, name:, singleton:, check_retained: true)
  block = @hook_def
  @hook_def = nil
  where = "mutineer: could not place the mutant of #{name} (#{source_file}:#{line})"
  unless block
    raise "#{where}: the mutant file did not reach its included or prepended call. " \
          "This is a mutineer bug; please report it."
  end

  # Check before owner and alias lookup create temporary UnboundMethods.
  refuse_retained_hook_def(source_file: source_file, line: line, name: name) if check_retained

  # ponytail: one ObjectSpace walk per mutant (about 11 ms with Rails loaded);
  # index modules by method name if a large app makes it slow.
  modules = ObjectSpace.each_object(Module).reject { |mod| deprecation_proxy?(mod) }
  found = owners(modules, source_file: source_file, line: line, name: name, singleton: singleton)
  mod, other = aliases(modules, source_file: source_file, line: line, name: name, singleton: singleton).first
  if mod
    raise "#{where}: #{mod.inspect}#{singleton ? "." : "#"}#{other} is an alias of it and keeps the " \
          "original method, so the mutant scores error."
  end

  found.each do |owner|
    target = singleton ? owner.singleton_class : owner
    visibility = if target.private_method_defined?(name, false) then :private
                 elsif target.protected_method_defined?(name, false) then :protected
                 end
    owner.class_eval(&block) # a `def` in the block defines public
    target.send(visibility, name) if visibility
  end
  found.size
end

.real_path(file) ⇒ String

The file's real path, so a symlinked or relative path matches the path Ruby recorded when it loaded the file.

Parameters:

  • file (String) —

    a file path.

Returns:

  • (String)


327
328
329
330
331
# File 'lib/mutineer/concern_blocks.rb', line 327

def self.real_path(file)
  File.realpath(file)
rescue SystemCallError
  File.expand_path(file)
end

.refuse_retained_hook_def(source_file:, line:, name:) ⇒ nil

Raises when a live Method or UnboundMethod keeps the original definition (see retained_hook_def?), so the child scores the mutant error.

Parameters:

  • source_file (String) —

    the file the mutant replaces.

  • line (Integer) —

    the original def's first line.

  • name (Symbol) —

    the original method name.

Returns:

  • (nil)

Raises:

  • (RuntimeError) —

    when such a handle is live.



264
265
266
267
268
269
# File 'lib/mutineer/concern_blocks.rb', line 264

def self.refuse_retained_hook_def(source_file:, line:, name:)
  return unless retained_hook_def?(source_file: source_file, line: line, name: name)

  raise "mutineer: could not place the mutant of #{name} (#{source_file}:#{line}): the original is " \
        "retained in a Method or UnboundMethod object, so the mutant scores error."
end

.replace(source_file) { ... } ⇒ Object

Forgets the source file's stored blocks, runs the block that loads the mutant, then puts back each forgotten block the load did not store again. A concern the mutant's load skips (an unless defined? guard) keeps its original block, so a class that includes it during the tests still gets it.

Parameters:

  • source_file (String) —

    the file the mutant replaces.

Yields:

  • the mutant's load.

Returns:

  • (Object) —

    what the block returns.



45
46
47
48
49
50
51
52
# File 'lib/mutineer/concern_blocks.rb', line 45

def self.replace(source_file)
  forgotten = forget(source_file)
  yield
ensure
  forgotten&.each do |concern, name, block|
    concern.instance_variable_set(name, block) unless concern.instance_variable_defined?(name)
  end
end

.retained_hook_def?(source_file:, line:, name:) ⇒ Boolean

True when a live Method or UnboundMethod keeps the original definition. A wrapper can call that handle after the named method was replaced, so loading another def cannot make the wrapper test the mutant. A matching but unreachable reflection result is harmless: collect it, then check again. Most mutants have no matching handle and need no explicit GC.

Parameters:

  • source_file (String) —

    the file the mutant replaces.

  • line (Integer) —

    the original def's first line.

  • name (Symbol) —

    the original method name.

Returns:

  • (Boolean)


281
282
283
284
285
286
287
# File 'lib/mutineer/concern_blocks.rb', line 281

def self.retained_hook_def?(source_file:, line:, name:)
  path = real_path(source_file)
  return false unless method_handle_at?(path, line, name)

  GC.start
  method_handle_at?(path, line, name)
end

.store_hook_def { ... } ⇒ nil

Keeps the mutated hook-block def for place_hook_def. The mutant file calls it in the concern's body, just before the hook call, so the block has the same constant scope as the hook block (#297). Under load_mutant with a hook_def, it places the def now, before the rest of the file runs (#348).

Yields:

  • the mutated def, run with class_eval in each owner.

Returns:

  • (nil)

Raises:



134
135
136
137
138
139
140
141
142
143
144
# File 'lib/mutineer/concern_blocks.rb', line 134

def self.store_hook_def(&block)
  @hook_def = block
  return unless @hook_target

  target = @hook_target
  # A handle may be one the file drops before its load ends: load_mutant checks again then.
  @handle_at_placement = method_handle_at?(real_path(target[:source_file]), target[:line], target[:name])
  place_hook_def(**target, check_retained: false)
  # Cleared only after placement, so a raise the file rescues still errors after the load.
  @hook_target = nil
end