evilution 1.4.0 → 1.5.0

data/lib/evilution/mutator/operator/visibility_removal.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require "prism"
+
+require_relative "../operator"
+require_relative "../../ast/class_body"
+
+# Drop a visibility declaration from a class or module body: `private`,
+# `protected` and `module_function`, bare or naming methods. A definition the
+# declaration wraps is kept: `private def a; end` becomes `def a; end`.
+#
+# A survivor means no example checks what the declaration decides: that a
+# private method cannot be called from outside, or that a module function
+# can.
+#
+# Declarations sit in the class body, outside every method, where no subject
+# reaches them. They are attributed to the method anchoring the enclosing
+# body (see Evilution::AST::ClassBody); a top-level declaration has no body
+# to be attributed to. A call inside a method, or one sent to another
+# receiver, is not a declaration.
+class Evilution::Mutator::Operator::VisibilityRemoval < Evilution::Mutator::Base
+  DECLARATIONS = %i[private protected module_function].freeze
+
+  # What a declaration can wrap and has to leave behind: a method definition,
+  # or a call (`private attr_reader :name`, `private helper_names`). The call
+  # runs with or without the declaration, so it stays.
+  WRAPPED = [Prism::DefNode, Prism::CallNode].freeze
+
+  def call(subject, filter: nil)
+    @subject = subject
+    @file_source = File.read(subject.file_path)
+    @mutations = []
+    @filter = filter
+
+    declarations_for(subject).each { |declaration| remove(declaration) }
+    @mutations
+  end
+
+  private
+
+  def remove(declaration)
+    replacement = replacement_for(argument_nodes(declaration))
+    return if replacement.nil?
+
+    add_mutation(
+      offset: declaration.location.start_offset,
+      length: declaration.location.length,
+      replacement: replacement,
+      node: declaration
+    )
+  end
+
+  # What is left of the declaration: nothing when it only names methods, the
+  # definition when it wraps one. A definition among several arguments
+  # (`private attr_reader(:a), :b`) cannot be left behind on its own, so that
+  # declaration is not mutated.
+  def replacement_for(arguments)
+    return "" if arguments.none? { |argument| WRAPPED.include?(argument.class) }
+
+    arguments.first.slice if arguments.one?
+  end
+
+  def declarations_for(subject)
+    tree = self.class.parsed_tree_for(subject.file_path, @file_source)
+
+    Evilution::AST::ClassBody.anchored_at(tree, subject.line_number).flat_map do |body|
+      body.declarations { |node| declaration?(node) }
+    end
+  end
+
+  def declaration?(node)
+    node.is_a?(Prism::CallNode) && node.receiver.nil? && DECLARATIONS.include?(node.name)
+  end
+end

data/lib/evilution/mutator/primitives.rb

@@ -3,8 +3,9 @@
 require_relative "../mutator"
 
 # Mutation shapes shared across the operator families: replacing an
-# expression with `nil`, and replacing an expression with the source of one
-# of its children. Both are built on Base#add_mutation, so the
+# expression with `nil`, replacing an expression with the source of one of
+# its children, and deleting one element of a list. All are built on
+# Base#add_mutation, so the
 # equivalent-mutant filter and the heredoc-span guards still apply.
 #
 # Unlike a bare add_mutation call, these skip rather than emit when the
@@ -30,6 +31,20 @@ module Evilution::Mutator::Primitives
     replace_span(node: node, target: target, replacement: source_of(child))
   end
 
+  # Delete the element at `index` from a list written in source order (the
+  # elements of an array or hash literal), attributing the mutation to the
+  # element. It goes with the separator after it; the last one goes with the
+  # separator before it, so a trailing comma stays where it was. The list
+  # must hold another element to take the separator from.
+  def delete_element(elements, index)
+    element = elements[index]
+    following = elements[index + 1]
+    offset = following ? element.location.start_offset : elements[index - 1].location.end_offset
+    stop = following ? following.location.start_offset : element.location.end_offset
+
+    add_mutation(offset:, length: stop - offset, replacement: "", node: element, skip_unparseable: true)
+  end
+
   def replace_span(node:, target:, replacement:)
     return nil if target.nil?
 
@@ -45,6 +60,13 @@ module Evilution::Mutator::Primitives
     )
   end
 
+  # The arguments of a call, `super`, `yield` or the like, in source order.
+  # Prism gives nil, not an empty list, where there are none; this gives the
+  # empty list, so a reader can count or iterate without asking first.
+  def argument_nodes(node)
+    node.arguments ? node.arguments.arguments : []
+  end
+
   def source_of(child)
     location = child.location
     byteslice_source(location.start_offset, location.length)

data/lib/evilution/mutator/receiver_positions.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+require_relative "../mutator"
+
+# Visits every node that sends a message to a receiver, or defines
+# something on one, and hands that receiver to #receiver_found before the
+# receiver itself is visited.
+#
+# A plain call is one such node, but not the only one. An operator or
+# logical write on an attribute or an index (`a.b += c`, `a[b] ||= c`) and
+# an attribute or index target of a multiple assignment (`a.b, c[d] = e`)
+# each hold their receiver in a node of their own. An operator that treats
+# "the receiver of a call" specially — replacing it with `nil` only earns a
+# NoMethodError — has to mean all of them.
+#
+# A definition has a receiver too: the object a singleton method is defined
+# on (`def self.build`, `def helper.extra`) and the one a singleton class is
+# opened on (`class << self`). Replacing it does not change the method that
+# is already there — `def nil.build` defines another one, on `nil` — so the
+# mutant could never be killed.
+#
+# The includer defines #receiver_found(node). `node` is nil where the
+# message or the definition has no explicit receiver.
+module Evilution::Mutator::ReceiverPositions
+  def visit_call_node(node)
+    receiver_found(node.receiver)
+    super
+  end
+
+  def visit_call_operator_write_node(node)
+    receiver_found(node.receiver)
+    super
+  end
+
+  def visit_call_or_write_node(node)
+    receiver_found(node.receiver)
+    super
+  end
+
+  def visit_call_and_write_node(node)
+    receiver_found(node.receiver)
+    super
+  end
+
+  def visit_index_operator_write_node(node)
+    receiver_found(node.receiver)
+    super
+  end
+
+  def visit_index_or_write_node(node)
+    receiver_found(node.receiver)
+    super
+  end
+
+  def visit_index_and_write_node(node)
+    receiver_found(node.receiver)
+    super
+  end
+
+  def visit_call_target_node(node)
+    receiver_found(node.receiver)
+    super
+  end
+
+  def visit_index_target_node(node)
+    receiver_found(node.receiver)
+    super
+  end
+
+  def visit_def_node(node)
+    receiver_found(node.receiver)
+    super
+  end
+
+  def visit_singleton_class_node(node)
+    receiver_found(node.expression)
+    super
+  end
+end

data/lib/evilution/mutator/registry.rb

@@ -6,7 +6,8 @@ class Evilution::Mutator::Registry
   STRICT_EXTRA_OPERATORS = [
     Evilution::Mutator::Operator::PredicateToNil,
     Evilution::Mutator::Operator::ExceptionSwallow,
-    Evilution::Mutator::Operator::StatementReorder
+    Evilution::Mutator::Operator::StatementReorder,
+    Evilution::Mutator::Operator::SafeNavigationInsertion
   ].freeze
 
   def self.for_profile(profile)
@@ -37,6 +38,8 @@ class Evilution::Mutator::Registry
       Evilution::Mutator::Operator::NilReplacement,
       Evilution::Mutator::Operator::IntegerLiteral,
       Evilution::Mutator::Operator::FloatLiteral,
+      Evilution::Mutator::Operator::ComplexLiteral,
+      Evilution::Mutator::Operator::RationalLiteral,
       Evilution::Mutator::Operator::StringLiteral,
       Evilution::Mutator::Operator::ArrayLiteral,
       Evilution::Mutator::Operator::HashLiteral,
@@ -150,6 +153,7 @@ class Evilution::Mutator::Registry
       Evilution::Mutator::Operator::KeywordValueSwap,
       Evilution::Mutator::Operator::ComparisonOperandSwap,
       Evilution::Mutator::Operator::IntegerDivisionToFdiv,
+      Evilution::Mutator::Operator::RoundHalfModeSwap,
       Evilution::Mutator::Operator::OffByOneBoundary,
       Evilution::Mutator::Operator::FormatSpecifierSwap,
       Evilution::Mutator::Operator::AliasRemoval,
@@ -163,7 +167,23 @@ class Evilution::Mutator::Registry
       Evilution::Mutator::Operator::RescueHandlerPromotion,
       Evilution::Mutator::Operator::RescueHandlerConcatenation,
       Evilution::Mutator::Operator::RescueElseConcatenation,
-      Evilution::Mutator::Operator::ReturnKeywordRemoval
+      Evilution::Mutator::Operator::ReturnKeywordRemoval,
+      Evilution::Mutator::Operator::MemoizationBreak,
+      Evilution::Mutator::Operator::ShortCircuitToEager,
+      Evilution::Mutator::Operator::FreezeRemoval,
+      Evilution::Mutator::Operator::RescueClassWidening,
+      Evilution::Mutator::Operator::VisibilityRemoval,
+      Evilution::Mutator::Operator::AttrAccessorSwap,
+      Evilution::Mutator::Operator::SleepToZero,
+      Evilution::Mutator::Operator::IndexReceiverToSelf,
+      Evilution::Mutator::Operator::IndexToKeyPredicate,
+      Evilution::Mutator::Operator::IndexRangeToDrop,
+      Evilution::Mutator::Operator::IndexWriteToValue,
+      Evilution::Mutator::Operator::ConstantReadToNil,
+      Evilution::Mutator::Operator::ConstantNamespaceStrip,
+      Evilution::Mutator::Operator::ConstantWriteToNil,
+      Evilution::Mutator::Operator::VariableReadToNil,
+      Evilution::Mutator::Operator::OperatorWriteReceiverPromotion
     ].each { |op| registry.register(op) }
     registry
   end
@@ -186,6 +206,13 @@ class Evilution::Mutator::Registry
     end
   end
 
+  # Whether any registered operator mutates subjects of this one's kind. A
+  # subject none does would only ever be listed with no mutations to its
+  # name.
+  def accepts?(subject)
+    @operators.any? { |operator_class| operator_class.subject_kinds.include?(subject.kind) }
+  end
+
   def operator_count
     @operators.length
   end

data/lib/evilution/parallel/work_queue/channel/frame.rb

@@ -14,6 +14,10 @@ module Evilution::Parallel::WorkQueue::Channel::Frame
   # parent itself forked, transferred over a private pipe inside our process
   # tree. No external/untrusted input ever reaches this code. See
   # .rubocop.yml (Security/MarshalLoad) for the full rationale.
+  #
+  # Trusted is not the same as well-formed: a process the worker forked holds
+  # the pipe too. A frame of the announced length that does not load is a
+  # BadFrame; one shorter than announced is the end of the stream, nil.
   def decode(header, payload)
     return nil if header.nil? || header.bytesize < 4
 
@@ -21,5 +25,7 @@ module Evilution::Parallel::WorkQueue::Channel::Frame
     return nil if payload.nil? || payload.bytesize < length
 
     Marshal.load(payload)
+  rescue TypeError, ArgumentError => e
+    raise Evilution::Parallel::WorkQueue::Channel::BadFrame, "#{e.class}: #{e.message.gsub(/\s+/, " ")}"
   end
 end

data/lib/evilution/parallel/work_queue/channel.rb

@@ -1,8 +1,24 @@
 # frozen_string_literal: true
 
+require "io/wait"
 require_relative "../work_queue"
 
 module Evilution::Parallel::WorkQueue::Channel
+  # A frame that arrived but is not one the peer wrote: bytes that do not
+  # decode, or a frame that stops before the length its header announced.
+  #
+  # The pipes of the pool are inherited by the processes a worker forks, so
+  # the code under test can write into them. After such a frame the stream is
+  # out of step and nothing read from it later can be trusted; the reader
+  # gives the peer up. The end of the stream is not this: it reads as nil.
+  class BadFrame < StandardError; end
+
+  # Seconds a frame may take to arrive once its first byte has, header and
+  # payload together. A writer sends a frame in one call, so the rest follows
+  # at once; a header that announces bytes nobody will send must not hold the
+  # reader for ever.
+  FRAME_TIMEOUT = 10
+
   module_function
 
   def write(io, object)
@@ -10,14 +26,51 @@ module Evilution::Parallel::WorkQueue::Channel
     io.flush
   end
 
-  def read(io)
-    header = io.read(4)
-    return nil if header.nil? || header.bytesize < 4
+  # Waits for a frame without a limit, since an idle peer is no fault, and
+  # for the rest of one that has begun no longer than `frame_timeout`: one
+  # allowance for the whole frame.
+  def read(io, frame_timeout: FRAME_TIMEOUT)
+    io.wait_readable
+    allowance = Allowance.new(deadline: now + frame_timeout, seconds: frame_timeout)
+    header = read_exactly(io, 4, allowance)
+    return nil if header.bytesize < 4
 
-    length = header.unpack1("N")
-    payload = io.read(length)
+    payload = read_exactly(io, header.unpack1("N"), allowance)
     Frame.decode(header, payload)
   end
+
+  # What is left of the time a frame is given, and the figure it was given,
+  # which the message of a frame cut short names.
+  Allowance = Data.define(:deadline, :seconds)
+  private_constant :Allowance
+
+  # Up to `count` bytes: fewer only when the stream ended first.
+  def read_exactly(io, count, allowance)
+    buffer = String.new
+
+    while buffer.bytesize < count
+      chunk = io.read_nonblock(count - buffer.bytesize, exception: false)
+      return buffer if chunk.nil?
+
+      if chunk == :wait_readable
+        await(io, allowance, buffer.bytesize, count)
+      else
+        buffer << chunk
+      end
+    end
+    buffer
+  end
+
+  def await(io, allowance, arrived, count)
+    remaining = allowance.deadline - now
+    return if remaining.positive? && io.wait_readable(remaining)
+
+    raise BadFrame, "frame cut short: #{arrived} of #{count} bytes arrived within #{allowance.seconds}s"
+  end
+
+  def now
+    Process.clock_gettime(Process::CLOCK_MONOTONIC)
+  end
 end
 
 require_relative "channel/frame"

data/lib/evilution/parallel/work_queue/dispatcher/reply.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require_relative "../dispatcher"
+require_relative "../channel"
+
+# Reads what a worker sent and says what it is: a result of an item the worker
+# holds, the end of its stream (nil), or something that cannot be trusted.
+#
+# The result pipe is inherited by the processes a worker forks, so a frame on
+# it is not always the worker's. One that does not decode is UNREADABLE, and
+# so is one that decodes to something other than a result: what a stray
+# process writes may happen to be a marshal dump, and taken at its word it
+# would move the Dispatcher's counters or be raised as the error of the run.
+# After either, the stream is out of step, and the Dispatcher gives the worker
+# up.
+#
+# Keeping the wire-level judgement here leaves the Dispatcher with what to do
+# about each answer.
+module Evilution::Parallel::WorkQueue::Dispatcher::Reply
+  UNREADABLE = Object.new.freeze
+
+  module_function
+
+  def from(worker)
+    message = worker.read_result
+    return nil if message.nil?
+
+    result_of?(worker, message) ? message : UNREADABLE
+  rescue Evilution::Parallel::WorkQueue::Channel::BadFrame
+    UNREADABLE
+  end
+
+  def result_of?(worker, message)
+    return false unless message.is_a?(Array) && message.length == 3
+
+    index, status, value = message
+    return false unless worker.in_flight_indices.include?(index)
+
+    status == :ok || (status == :error && value.is_a?(Exception))
+  end
+end

data/lib/evilution/parallel/work_queue/dispatcher.rb

@@ -74,8 +74,9 @@ class Evilution::Parallel::WorkQueue::Dispatcher
   end
 
   def handle(worker, io_to_worker, result_ios)
-    message = worker.read_result
+    message = Reply.from(worker)
     return handle_dead(worker, io_to_worker, result_ios) if message.nil?
+    return handle_unreadable(worker, io_to_worker, result_ios) if message.equal?(Reply::UNREADABLE)
 
     record(message, worker)
     return false if recycle_and_dispatch(worker, io_to_worker, result_ios)
@@ -96,6 +97,17 @@ class Evilution::Parallel::WorkQueue::Dispatcher
     @deadlines.refresh(worker)
   end
 
+  # After a frame that is not the worker's, nothing read from its pipe later
+  # can be trusted: the stream is out of step. The worker is given up the way
+  # a dead one is, after being killed, since it may well be alive. Only the
+  # items it held lose their result.
+  def handle_unreadable(worker, io_to_worker, result_ios)
+    worker.kill
+    mark_unfinished(worker, Evilution::Parallel::WorkQueue::UNREADABLE)
+    retire_or_replace(worker, io_to_worker, result_ios)
+    false
+  end
+
   # A worker that exited without replying loses only its in-flight item(s)
   # (marked :died) and is recycled; the run continues rather than aborting.
   def handle_dead(worker, io_to_worker, result_ios)
@@ -183,3 +195,4 @@ class Evilution::Parallel::WorkQueue::Dispatcher
 end
 
 require_relative "dispatcher/deadline_tracker"
+require_relative "dispatcher/reply"

data/lib/evilution/parallel/work_queue/worker/loop.rb

@@ -23,6 +23,11 @@ module Evilution::Parallel::WorkQueue::Worker::Loop
     Evilution::Parallel::WorkQueue::Channel.write(
       res_io, [Evilution::Parallel::WorkQueue::STATS, busy, wall]
     )
+  rescue Evilution::Parallel::WorkQueue::Channel::BadFrame
+    # A command that does not decode leaves a stream this worker cannot follow.
+    # It ends without the stats frame, which the parent, still waiting for a
+    # result, would take for one; the closed pipe tells the parent to replace it.
+    nil
   ensure
     cmd_io.close unless cmd_io.closed?
     res_io.close unless res_io.closed?

data/lib/evilution/parallel/work_queue/worker.rb

@@ -91,8 +91,8 @@ class Evilution::Parallel::WorkQueue::Worker
     @in_flight_indices << index
   end
 
-  def read_result
-    Evilution::Parallel::WorkQueue::Channel.read(@res_read)
+  def read_result(frame_timeout: Evilution::Parallel::WorkQueue::Channel::FRAME_TIMEOUT)
+    Evilution::Parallel::WorkQueue::Channel.read(@res_read, frame_timeout: frame_timeout)
   end
 
   def shutdown
@@ -138,16 +138,25 @@ class Evilution::Parallel::WorkQueue::Worker
 
   private
 
+  # The grace period covers the read as well as the wait for it: a stats frame
+  # that begins inside it and never completes must not outlast it.
   def drain_stats
     zero = Timing.new(busy: 0.0, wall: 0.0)
+    deadline = monotonic_now + Evilution::Parallel::WorkQueue::TIMING_GRACE_PERIOD
     return zero unless @res_read.wait_readable(Evilution::Parallel::WorkQueue::TIMING_GRACE_PERIOD)
 
-    message = read_result
-    return zero if message.nil?
+    message = read_result(frame_timeout: [deadline - monotonic_now, 0].max)
+    return zero unless message.is_a?(Array)
 
     tag, busy, wall = message
     return zero unless tag == Evilution::Parallel::WorkQueue::STATS
 
     Timing.new(busy: busy, wall: wall)
+  rescue Evilution::Parallel::WorkQueue::Channel::BadFrame
+    zero
+  end
+
+  def monotonic_now
+    Process.clock_gettime(Process::CLOCK_MONOTONIC)
   end
 end

data/lib/evilution/parallel/work_queue.rb

@@ -16,6 +16,7 @@ class Evilution::Parallel::WorkQueue
   Unfinished = Data.define(:reason)
   TIMED_OUT = Unfinished.new(reason: :timeout)
   DIED = Unfinished.new(reason: :died)
+  UNREADABLE = Unfinished.new(reason: :unreadable)
 
   def initialize(size:, hooks: nil, prefetch: 1, item_timeout: nil, worker_max_items: nil)
     Validators::PositiveInt.call!(:size, size)
@@ -80,17 +81,16 @@ class Evilution::Parallel::WorkQueue
     deadline = monotonic_now + TIMING_GRACE_PERIOD
 
     until io_to_worker.empty?
-      remaining = deadline - monotonic_now
-      break if remaining <= 0
-      break unless poll_and_apply(io_to_worker, remaining)
+      break if deadline - monotonic_now <= 0
+      break unless poll_and_apply(io_to_worker, deadline)
     end
   end
 
-  def poll_and_apply(io_to_worker, remaining)
-    readable, = IO.select(io_to_worker.keys, nil, nil, remaining)
+  def poll_and_apply(io_to_worker, deadline)
+    readable, = IO.select(io_to_worker.keys, nil, nil, deadline - monotonic_now)
     return false unless readable
 
-    readable.each { |io| apply_final_timing(io_to_worker.delete(io), io) }
+    readable.each { |io| apply_final_timing(io_to_worker.delete(io), io, deadline) }
     true
   end
 
@@ -98,15 +98,21 @@ class Evilution::Parallel::WorkQueue
     Process.clock_gettime(Process::CLOCK_MONOTONIC)
   end
 
-  def apply_final_timing(worker, io)
-    message = Evilution::Parallel::WorkQueue::Channel.read(io)
-    return if message.nil?
+  # The timings are a courtesy: a frame that cannot be read here costs the
+  # figures and nothing else. The read gets what is left of the grace period,
+  # so a frame that begins inside it and never completes does not outlast it.
+  def apply_final_timing(worker, io, deadline)
+    allowed = [deadline - monotonic_now, 0].max
+    message = Evilution::Parallel::WorkQueue::Channel.read(io, frame_timeout: allowed)
+    return unless message.is_a?(Array)
 
     tag, busy_time, wall_time = message
     return unless tag == STATS
 
     worker.busy_time = busy_time
     worker.wall_time = wall_time
+  rescue Evilution::Parallel::WorkQueue::Channel::BadFrame
+    nil
   end
 end
 

data/lib/evilution/runner/mutation_executor/strategy/parallel.rb

@@ -13,6 +13,15 @@ class Evilution::Runner::MutationExecutor::Strategy::Parallel
     error_class: "Evilution::Error"
   }.freeze
 
+  # Compact result for an item whose worker sent a frame that was not its own:
+  # the worker was given up, and what it had to say about the item with it.
+  UNREADABLE_COMPACT = {
+    status: :error,
+    duration: 0.0,
+    error_message: "worker's result could not be read; the worker was replaced",
+    error_class: "Evilution::Error"
+  }.freeze
+
   def initialize(cache:, isolator:, packer:, pipeline:, notifier:, pool_factory:, config:, diagnostics: nil)
     @cache = cache
     @isolator = isolator
@@ -113,6 +122,7 @@ class Evilution::Runner::MutationExecutor::Strategy::Parallel
     case result.reason
     when :timeout then timeout_compact
     when :died then DIED_COMPACT
+    when :unreadable then UNREADABLE_COMPACT
     end
   end
 

data/lib/evilution/runner/subject_pipeline/target.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+require_relative "../subject_pipeline"
+
+# What `--target` asks for, read once from the text the user gave:
+#
+#   source:lib/**/*.rb   the files of a glob
+#   descendants:Base     a class and everything inheriting from it
+#   User#adult?          a method; `User`, `User#`, `Billing::*` for several
+#
+# NONE stands in when no target was given: it is no kind of target and
+# selects every subject, so the pipeline never has to ask whether there is
+# one.
+class Evilution::Runner::SubjectPipeline::Target
+  PREFIXES = { "source:" => :source_glob, "descendants:" => :descendants }.freeze
+  private_constant :PREFIXES
+
+  def self.parse(text)
+    return NONE if text.nil?
+
+    prefix, kind = PREFIXES.find { |candidate, _| text.start_with?(candidate) }
+    return new(kind: :method, text: text, value: text) if prefix.nil?
+
+    new(kind: kind, text: text, value: text.delete_prefix(prefix))
+  end
+
+  # The part after the prefix: the glob, the base class name, or the method
+  # name as written.
+  attr_reader :value
+
+  def initialize(kind:, text:, value:)
+    @kind = kind
+    @text = text
+    @value = value
+  end
+
+  def source_glob?
+    @kind == :source_glob
+  end
+
+  def descendants?
+    @kind == :descendants
+  end
+
+  def method?
+    @kind == :method
+  end
+
+  # The target as the user wrote it, for messages.
+  def to_s
+    @text.to_s
+  end
+
+  # Only a method target narrows subjects by name.
+  def selects?(subject)
+    !method? || matcher.call(subject.name)
+  end
+
+  NONE = new(kind: :none, text: nil, value: nil)
+
+  private
+
+  def matcher
+    @matcher ||= build_matcher
+  end
+
+  def build_matcher
+    return wildcard_matcher(value.chomp("*")) if value.end_with?("*")
+    return prefix_matcher(value) if value.end_with?("#", ".")
+
+    name_matcher(value)
+  end
+
+  def wildcard_matcher(prefix)
+    ->(name) { name.split(/[#.]/).first.start_with?(prefix) }
+  end
+
+  def prefix_matcher(prefix)
+    ->(name) { name.start_with?(prefix) }
+  end
+
+  # A full method name matches itself; a class name, each of its methods.
+  def name_matcher(target)
+    ->(name) { name == target || name.start_with?("#{target}#") || name.start_with?("#{target}.") }
+  end
+end