Module: Mutineer::ReachProbe

Defined in:
lib/mutineer/reach_probe.rb

Overview

Records whether the expression that holds a mutation ran in the child.

Ruby counts one line of a statement. A mutant on another line is selected as :maybe (#254, #289): the tests of the statement may not have reached it. A kill is still a kill. A survivor used to stay no_coverage, because the line count cannot tell "ran" from "did not run". The wrapper below writes a sentinel when that expression runs, so a survivor that ran counts as survived and one that did not stays no_coverage (#345).

The inserted text is stdlib only (File). The daemon loads it as source, so the app process needs no Prism and no Mutineer constant.

Constant Summary collapse

KEY_FORMAT =

A fiber-local key for one sentinel: mutineer_r plus 16 hex digits. Thread.current[] is fiber-local, not one value for the whole thread. The generated source and forget_load use this key, not a fixed global, so an application variable of the same shape is not read or overwritten. The daemon checks the same pattern; it cannot load this file.

/\Amutineer_r[0-9a-f]{16}\z/
CLIMB_STOP =

Nodes that must not be wrapped. Wrapping one records every run of the method or file, not the mutated expression.

[Prism::DefNode, Prism::ClassNode, Prism::ModuleNode, Prism::ProgramNode,
Prism::SingletonClassNode].freeze

Class Method Summary collapse

Class Method Details

.climb_stops?(parent, child) ⇒ Boolean (private)

True when wrapping parent would record a run of code that can run without child: a conditional child, or a node that is a whole def, class, or file.

Parameters:

  • parent (Prism::Node)
  • child (Prism::Node)

Returns:

  • (Boolean)


142
143
144
145
146
# File 'lib/mutineer/reach_probe.rb', line 142

def self.climb_stops?(parent, child)
  return true if CLIMB_STOP.any? { |klass| parent.is_a?(klass) }

  StatementLines.sometimes?(parent, child)
end

.close_sentinel(sentinel) ⇒ void

This method returns an undefined value.

Removes the sentinel file. A missing file is already gone.

Parameters:

  • sentinel (Tempfile, nil)


73
74
75
76
77
78
79
80
# File 'lib/mutineer/reach_probe.rb', line 73

def self.close_sentinel(sentinel)
  return unless sentinel

  sentinel.close unless sentinel.closed?
  sentinel.unlink
rescue Errno::ENOENT
  nil
end

.forget_load(path, key) ⇒ void

This method returns an undefined value.

Empties the sentinel after the mutant has loaded and before its tests run. A reload runs top-level calls, and those can reach the expression before any test does. That load is not a test reaching it (#345). The daemon does the same clear itself, because this file pulls in Prism and the daemon cannot.

Parameters:

  • path (String, nil) —

    sentinel path.

  • key (String, nil) —

    fiber-local key from reach_key.



62
63
64
65
66
67
# File 'lib/mutineer/reach_probe.rb', line 62

def self.forget_load(path, key)
  return unless path

  Thread.current[key.to_sym] = nil if key.to_s.match?(KEY_FORMAT)
  File.write(path, "")
end

.parent_map(root) ⇒ Hash{Prism::Node => Prism::Node} (private)

Parent of each node, by identity. A heredoc body is a child that lies outside its opener, so every child is recorded.

Parameters:

  • root (Prism::Node)

Returns:

  • (Hash{Prism::Node => Prism::Node})


159
160
161
162
163
164
165
166
167
168
169
170
171
# File 'lib/mutineer/reach_probe.rb', line 159

def self.parent_map(root)
  map = {}.compare_by_identity
  walk = lambda do |node|
    return unless node.is_a?(Prism::Node)

    node.compact_child_nodes.each do |child|
      map[child] = node
      walk.call(child)
    end
  end
  walk.call(root)
  map
end

.reach_key ⇒ String

A new key for one mutant's sentinel.

Returns:

  • (String)


31
32
33
# File 'lib/mutineer/reach_probe.rb', line 31

def self.reach_key
  "mutineer_r#{SecureRandom.hex(8)}"
end

.reached?(sentinel) ⇒ Boolean

Whether a test wrote the sentinel after forget_load. False when there is no sentinel, or the expression did not return during a test.

Parameters:

  • sentinel (Tempfile, nil)

Returns:

  • (Boolean)


49
50
51
# File 'lib/mutineer/reach_probe.rb', line 49

def self.reached?(sentinel)
  !sentinel.nil? && File.size(sentinel.path).positive?
end

.sentinel ⇒ Tempfile

An empty sentinel file. The child writes "1" when the expression runs. The caller checks reached? and then close_sentinel.

Returns:

  • (Tempfile)


38
39
40
41
42
# File 'lib/mutineer/reach_probe.rb', line 38

def self.sentinel
  file = Tempfile.new(["mutineer-reach-", ".touch"])
  file.close
  file
end

.smallest(node, start_offset, end_offset, best = nil) ⇒ Prism::Node? (private)

The deepest node whose location holds the range. A child replaces a parent of the same span, so a one-statement body wraps the statement and not the statement list around it. A heredoc body is a child that lies outside its opener, so every child is searched.

Parameters:

  • node (Prism::Node, Object)
  • start_offset (Integer)
  • end_offset (Integer)
  • best (Prism::Node, nil) (defaults to: nil)

Returns:

  • (Prism::Node, nil)


184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
# File 'lib/mutineer/reach_probe.rb', line 184

def self.smallest(node, start_offset, end_offset, best = nil)
  return best unless node.is_a?(Prism::Node)

  loc = node.location
  span = loc.end_offset - loc.start_offset
  covers = if start_offset == end_offset
             loc.start_offset <= start_offset && start_offset < loc.end_offset
           else
             span.positive? && loc.start_offset <= start_offset && end_offset <= loc.end_offset
           end
  best = node if covers && (best.nil? || span <= (best.location.end_offset - best.location.start_offset))
  node.compact_child_nodes.each do |child|
    best = smallest(child, start_offset, end_offset, best)
  end
  best
end

.splice(source, node, path, key) ⇒ String (private)

Replaces node with an expression that writes path only when node returns. The mark is the second element of an array, so it does not run when node raises. A one-line node stays one line. A node that spans lines keeps its text and puts the array on the following lines, so the indent warning stays quiet.

Parameters:

  • source (String)
  • node (Prism::Node)
  • path (String)
  • key (String) —

    fiber-local key from reach_key.

Returns:

  • (String)


213
214
215
216
217
218
219
220
221
222
223
224
225
226
# File 'lib/mutineer/reach_probe.rb', line 213

def self.splice(source, node, path, key)
  loc = node.location
  inner = source.byteslice(loc.start_offset, loc.end_offset - loc.start_offset)
  quoted = path.dump
  # The fiber-local skips the write after the first return on this
  # fiber. A stat on every later pass would hit a loop.
  mark = "(Thread.current[:#{key}] ||= (::File.write(#{quoted}, \"1\"); true))"
  replacement = if inner.include?("\n")
                  "\n[(#{inner}), #{mark}][0]"
                else
                  "[(#{inner}), #{mark}][0]"
                end
  source.byteslice(0, loc.start_offset) + replacement + source.byteslice(loc.end_offset..)
end

.wrap(source, start_offset, end_offset, path, key) ⇒ String?

Wraps the smallest expression that holds the byte range [start_offset, end_offset). An empty range is the point where a deletion used to be. Returns nil when no expression holds it, or the wrapped text does not parse: a wrap that does not parse is not used.

The wrapper returns the expression's value. It writes the sentinel only after that value has come back, so a raise inside the expression — an operand that fails before a mutated operator runs — does not count as a run. Later returns on the same thread do not touch the file.

Parameters:

  • source (String)
  • start_offset (Integer) —

    byte offset of the replacement.

  • end_offset (Integer) —

    byte offset just after the replacement.

  • path (String) —

    absolute sentinel path.

  • key (String) —

    fiber-local key from reach_key.

Returns:

  • (String, nil)


116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
# File 'lib/mutineer/reach_probe.rb', line 116

def self.wrap(source, start_offset, end_offset, path, key)
  return nil unless key.to_s.match?(KEY_FORMAT)
  root = Parser.parse_string(source).value
  node = smallest(root, start_offset, end_offset)
  return nil unless node

  parents = parent_map(root)
  while node
    wrapped = splice(source, node, path, key)
    return wrapped unless Parser.invalid?(wrapped)

    parent = parents[node]
    break if parent.nil? || climb_stops?(parent, node)

    node = parent
  end
  nil
end

.wrap_mutation(source, mutation, path, key) ⇒ String

The mutated source with a probe around the expression that holds the replacement, or source when path is nil. The original source when the expression cannot be wrapped without changing how it parses: the caller then has no evidence the expression ran, and a survivor stays no_coverage.

Parameters:

  • source (String) —

    mutated source.

  • mutation (Mutineer::Mutation) —

    the edit, already applied to source.

  • path (String, nil) —

    sentinel path, or nil to leave source alone.

  • key (String, nil) —

    fiber-local key from reach_key.

Returns:

  • (String)


93
94
95
96
97
98
# File 'lib/mutineer/reach_probe.rb', line 93

def self.wrap_mutation(source, mutation, path, key)
  return source if path.nil? || !key.to_s.match?(KEY_FORMAT)

  start = mutation.start_offset
  wrap(source, start, start + mutation.replacement.bytesize, path, key) || source
end