Class: Mutineer::Mutators::CollectionMethod

Inherits:
Base
  • Object
show all
Defined in:
lib/mutineer/mutators/collection_method.rb

Overview

Collection / enumerable method-name mutator (Tier-2).

Swaps the method-name token of a call to its semantic opposite, one mutation per occurrence, exactly like the arithmetic/comparison operators.

each and map are the exception. each returns its receiver and map returns a new array. When that value is discarded, no test can tell the mutant from the original, so the swap is declined. The other swaps stay: all? and any? stop on different elements, so a block can show the change even when the boolean is discarded. See docs/equivalent-skips.md.

Constant Summary collapse

REPLACEMENTS =

Method-name swaps. All targets are core-Ruby Enumerable/Array methods so the mutant exercises real behaviour rather than always raising.

include? -> exclude? is left out: exclude? is not core Ruby, so that mutant would always NoMethodError (a weak mutant).

{
  map: "each", each: "map",
  all?: "any?", any?: "all?",
  first: "last", last: "first",
  min: "max", max: "min",
  select: "reject", reject: "select"
}.freeze
UNUSED_RESULT_NAMES =

Names whose swap changes the returned object and not the walk. A discarded call is declined. The check is the syntax tree only: it does not know the receiver's class.

%i[each map].freeze
VALUE_FLOWS =

Parents that pass a child's value through. The child is observable exactly when that parent is. An assignment, an argument, a receiver, or an explicit return / break / next is not in this list: those parents use the value even when their own result is discarded. Interpolation is not in this list. A string or symbol calls to_s on the value, a backtick command runs, and a regexp is compiled, even when the expression's own result is thrown away. A hash association is not in this list either: its key is hashed on insertion, and its value is handled in #result_used?.

[
  Prism::ParenthesesNode,
  Prism::BeginNode,
  Prism::ElseNode,
  Prism::AndNode,
  Prism::OrNode,
  Prism::RescueModifierNode,
  Prism::ArrayNode,
  Prism::HashNode,
  Prism::KeywordHashNode,
  Prism::AssocSplatNode,
  Prism::SplatNode,
  Prism::RangeNode,
  Prism::EmbeddedStatementsNode
].freeze

Instance Method Summary collapse

Methods inherited from Base

#dangling_heredoc?, #decline, #declined, #drop_dangling_heredocs, #heredoc?, #visit_def_node, #visit_singleton_class_node

Instance Method Details

#index_parents(node, parent) ⇒ void (private)

This method returns an undefined value.

Stores the parent of every node under node.

Parameters:

  • node (Prism::Node, nil) —

    subtree to index.

  • parent (Prism::Node, nil) —

    parent of node, or nil at the root.



104
105
106
107
108
109
# File 'lib/mutineer/mutators/collection_method.rb', line 104

def index_parents(node, parent)
  return unless node.is_a?(Prism::Node)

  @parents[node] = parent
  node.compact_child_nodes.each { |child| index_parents(child, node) }
end

#inside_defined?(node) ⇒ Boolean (private)

Returns whether node is inside a defined? operand.

defined? does not run that operand, so an each or map there does not call to_s, run a command, or compile a regexp.

Parameters:

  • node (Prism::Node) —

    node to inspect.

Returns:

  • (Boolean) —

    true when an ancestor is a DefinedNode.



140
141
142
143
144
145
146
# File 'lib/mutineer/mutators/collection_method.rb', line 140

def inside_defined?(node)
  current = node
  while (current = @parents[current])
    return true if current.is_a?(Prism::DefinedNode)
  end
  false
end

#lazy_chain?(node) ⇒ Boolean (private)

Returns whether a lazy call sits in this call's receiver chain.

xs.lazy.each and xs.lazy.map { }.each both count. A lazy enumerator stored in a variable does not: the tree no longer shows the lazy call.

Parameters:

  • node (Prism::CallNode) —

    each or map call to inspect.

Returns:

  • (Boolean) —

    true when the chain calls lazy.



156
157
158
159
160
161
162
163
164
# File 'lib/mutineer/mutators/collection_method.rb', line 156

def lazy_chain?(node)
  receiver = node.receiver
  while receiver.is_a?(Prism::CallNode)
    return true if receiver.name == :lazy

    receiver = receiver.receiver
  end
  false
end

#mutations_for(subject, source) ⇒ Array<Mutineer::Mutation>

Records parents, then walks the body. The result check needs the parent of each call, and Prism nodes do not store one.

Parameters:

  • subject (Mutineer::Subject) —

    subject whose body is visited.

  • source (String) —

    full source text for byte-based slicing.

Returns:



68
69
70
71
72
# File 'lib/mutineer/mutators/collection_method.rb', line 68

def mutations_for(subject, source)
  @parents = {}.compare_by_identity
  index_parents(subject.def_node.body, nil)
  super
end

#result_used?(node) ⇒ Boolean (private)

Returns whether any syntax reads this node's value.

The method body, a block body, and a lambda body count as read: a caller may use the method's return value, and the method that takes a block may use the block's result. The operator does not guess which methods do. A condition, an assignment, an argument, and a receiver count as read even when the outer expression is discarded. A while or until body does not, and neither does ensure or defined?. A for body does not either: for returns the collection, not the body. A hash key is read on insertion. The value of a hash pair follows the hash. A later rescue clause follows the begin, the same way the first clause does.

Parameters:

  • node (Prism::Node) —

    node whose value may flow outward.

Returns:

  • (Boolean) —

    true when the value is observable.



181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
# File 'lib/mutineer/mutators/collection_method.rb', line 181

def result_used?(node)
  parent = @parents[node]
  return true if parent.nil?

  case parent
  when Prism::StatementsNode
    return false unless parent.body.last.equal?(node)

    result_used?(parent)
  when Prism::IfNode, Prism::UnlessNode
    return true if parent.predicate.equal?(node)

    result_used?(parent)
  when Prism::WhileNode, Prism::UntilNode
    parent.predicate.equal?(node)
  when Prism::ForNode
    # `for` returns the collection, not the body.
    !parent.statements.equal?(node)
  when Prism::EnsureNode, Prism::DefinedNode
    false
  when Prism::AssocNode
    return true if parent.key.equal?(node)

    result_used?(parent)
  when Prism::RescueNode
    if parent.statements.equal?(node) || parent.subsequent.equal?(node)
      result_used?(parent)
    else
      true
    end
  when Prism::WhenNode, Prism::InNode
    return result_used?(parent) if parent.statements.equal?(node)

    true
  when Prism::CaseNode, Prism::CaseMatchNode
    return true if parent.predicate.equal?(node)

    result_used?(parent)
  when Prism::SingletonClassNode
    return true if parent.expression.equal?(node)

    result_used?(parent)
  when Prism::BlockNode, Prism::LambdaNode, Prism::DefNode
    true
  else
    return result_used?(parent) if VALUE_FLOWS.include?(parent.class)

    true
  end
end

#unused_result?(node) ⇒ Boolean (private)

Returns whether this call is an each or map whose value is discarded.

Interpolation is not discarded: a string or symbol calls to_s, a backtick command runs, and a regexp is compiled. A hash key is not discarded either: insertion calls hash and eql?. Those nodes are absent from VALUE_FLOWS, so #result_used? keeps them. A receiver chain that calls lazy is kept too. Enumerator::Lazy#each runs the block and Lazy#map does not, and the syntax tree can see the lazy call. A lazy enumerator stored in a variable has no lazy call left. defined? does not evaluate its operand, so a call inside it is discarded even when the chain calls lazy or the call sits in an interpolation.

Parameters:

  • node (Prism::CallNode) —

    call node to inspect.

Returns:

  • (Boolean) —

    true when the swap would be equivalent.



126
127
128
129
130
131
# File 'lib/mutineer/mutators/collection_method.rb', line 126

def unused_result?(node)
  return false unless UNUSED_RESULT_NAMES.include?(node.name)
  return true if inside_defined?(node)

  !result_used?(node) && !lazy_chain?(node)
end

#visit_call_node(node) ⇒ void

This method returns an undefined value.

Visits call nodes and emits collection-method mutations. An UNUSED_RESULT_NAMES call whose value is discarded is declined.

Parameters:

  • node (Prism::CallNode) —

    call node to inspect.



79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
# File 'lib/mutineer/mutators/collection_method.rb', line 79

def visit_call_node(node)
  replacement = REPLACEMENTS[node.name]
  loc = node.message_loc
  if replacement && loc
    if unused_result?(node)
      decline
    else
      @mutations << Mutation.new(
        start_offset: loc.start_offset,
        end_offset: loc.end_offset,
        replacement: replacement,
        operator: :collection_method
      )
    end
  end
  super
end