evilution 1.3.0 → 1.4.0

data/lib/evilution/ast/parser.rb

@@ -2,6 +2,11 @@
 
 require "prism"
 require_relative "../ast"
+require_relative "value_object_definition"
+require_relative "scope_declaration"
+require_relative "aasm_declaration"
+require_relative "included_block"
+require_relative "callback_declaration"
 
 module Evilution::AST
   class Parser
@@ -40,55 +45,153 @@ module Evilution::AST
       @file_path = file_path
       @subjects = []
       @context = []
+      @singleton = [false]
     end
 
     def visit_module_node(node)
       @context.push(constant_name(node.constant_path))
-      super
+      IncludedBlock.in_body(node.body).each do |block|
+        add_scope_subjects(block.body)
+        add_aasm_subjects(block.body)
+        add_callback_subjects(block.body)
+      end
+      within_scope(singleton: false) { super }
       @context.pop
     end
 
+    # A class whose superclass is a value-object definition
+    # (`class Coord < Data.define(:lat, :lng)`) makes a constant subject of
+    # that definition, named after the class.
     def visit_class_node(node)
       @context.push(constant_name(node.constant_path))
-      super
+      superclass = node.superclass
+      add_subject(superclass, @context.join("::"), :constant) if ValueObjectDefinition.match?(superclass)
+      add_scope_subjects(node.body)
+      add_aasm_subjects(node.body)
+      add_callback_subjects(node.body)
+      within_scope(singleton: false) { super }
       @context.pop
     end
 
+    # A `def` inside `class << self` defines a method on the enclosing
+    # class's singleton, like `def self.name`; inside `class << Store` it
+    # defines one on Store.
+    def visit_singleton_class_node(node)
+      constant = constant_expression?(node.expression)
+      @context.push(constant_name(node.expression)) if constant
+      within_scope(singleton: true) { super }
+      @context.pop if constant
+    end
+
     def visit_def_node(node)
-      separator = node.receiver ? "." : "#"
-      add_subject(node, separator)
+      separator = node.receiver || @singleton.last ? "." : "#"
+      add_subject(node, "#{@context.join("::")}#{separator}#{node.name}", :method)
       super
     end
 
+    def visit_constant_write_node(node)
+      return super unless ValueObjectDefinition.match?(node.value)
+
+      within_definition(node.value, node.name.to_s) { super }
+    end
+
+    def visit_constant_path_write_node(node)
+      return super unless ValueObjectDefinition.match?(node.value)
+
+      within_definition(node.value, path_name(node.target)) { super }
+    end
+
     private
 
-    def add_subject(node, separator)
-      scope = @context.join("::")
-      name = if scope.empty?
-               "#{separator}#{node.name}"
-             else
-               "#{scope}#{separator}#{node.name}"
-             end
+    def within_scope(singleton:)
+      @singleton.push(singleton)
+      yield
+    ensure
+      @singleton.pop
+    end
+
+    def constant_expression?(node)
+      node.is_a?(Prism::ConstantReadNode) || node.is_a?(Prism::ConstantPathNode)
+    end
+
+    # A value-object definition assigned to a constant is a subject of its
+    # own, and a scope for what its block defines: `def area` in
+    # `Size = Struct.new(:w, :h) do ... end` is `Size#area`.
+    def within_definition(definition, name)
+      @context.push(name)
+      add_subject(definition, @context.join("::"), :constant)
+      yield
+      @context.pop
+    end
+
+    # `scope :recent, -> { ... }` defines the class method `recent`. The
+    # subject spans the whole declaration and mutates its body.
+    # Written in a concern's `included` block it defines that method on every
+    # class including the concern, and is named after the concern.
+    def add_scope_subjects(body)
+      ScopeDeclaration.in_body(body).each do |declaration|
+        name = "#{@context.join("::")}.#{ScopeDeclaration.scope_name(declaration)}"
+        add_subject(ScopeDeclaration.body_of(declaration), name, :scope, span: declaration)
+      end
+    end
+
+    # A guard or callback written out inside `aasm do ... end` runs when the
+    # method its event or state defines is called (`ship`, `paid?`), and is
+    # named after it. The subject spans that declaration and mutates the
+    # callable's body; one event may hold several. A machine declared in a
+    # concern's `included` block is named after the concern.
+    def add_aasm_subjects(body)
+      AasmDeclaration.in_body(body).each do |callable|
+        name = "#{@context.join("::")}##{callable.method_name}"
+        add_subject(callable.body, name, :aasm, span: callable.declaration)
+      end
+    end
 
-      loc = node.location
-      method_source = @source.byteslice(loc.start_offset, loc.end_offset - loc.start_offset)
-                             .force_encoding(@source.encoding)
+    # A condition or a callback written out in a declaration such as
+    # `validate :credit_limit, if: -> { ... }` defines no method to be named
+    # after, so it is named the way the declaration reads:
+    # `Order.validate(:credit_limit)`. The subject spans the declaration and
+    # mutates the callable's body. In a concern's `included` block it is named
+    # after the concern.
+    def add_callback_subjects(body)
+      CallbackDeclaration.in_body(body).each do |callable|
+        add_subject(callable.body, "#{@context.join("::")}.#{callable.label}", :callback, span: callable.declaration)
+      end
+    end
+
+    def add_subject(node, name, kind, span: node)
+      loc = span.location
+      source = @source.byteslice(loc.start_offset, loc.end_offset - loc.start_offset)
+                      .force_encoding(@source.encoding)
 
       @subjects << Evilution::Subject.new(
         name: name,
         file_path: @file_path,
         line_number: loc.start_line,
-        source: method_source,
-        node: node
+        source: source,
+        node: node,
+        kind: kind
       )
     end
 
+    # `self::Unit` has no static full name; it is named within the scope it
+    # is written in, like a plain `Unit`.
+    def path_name(target)
+      target.full_name.delete_prefix("::")
+    rescue Prism::ConstantPathNode::DynamicPartsInConstantPathError
+      target.name.to_s
+    end
+
+    # `class self::Unit` and `class << self::Unit` have no static full name
+    # either; like `path_name`, they are named by their own constant.
     def constant_name(node)
       if node.respond_to?(:full_name)
         node.full_name
       else
         node.name.to_s
       end
+    rescue Prism::ConstantPathNode::DynamicPartsInConstantPathError
+      node.name.to_s
     end
   end
 end

data/lib/evilution/ast/pattern/method_name.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+require_relative "../pattern"
+
+# Reads a method name the way an attribute value spells it: an identifier with
+# an optional `?`, `!` or `=`, a bare operator, or anything else in quotes.
+class Evilution::AST::Pattern::MethodName
+  # Longest first, so `<=>` is not read as `<=`. Operators starting with `!`,
+  # `*` or `|` already mean negation, a wildcard or an alternative in a
+  # pattern, and have to be quoted.
+  OPERATORS = %w[<=> === == =~ []= [] <= << < >= >> > +@ -@ + - / % & ^ ~].freeze
+  IDENTIFIER = /\G[a-zA-Z_][a-zA-Z0-9_]*[?!=]?/
+  QUOTES = %w[' "].freeze
+
+  # The name starting at +pos+ in +input+, and the position just after it.
+  def self.scan(input, pos)
+    new(input, pos).scan
+  end
+
+  def initialize(input, pos)
+    @input = input
+    @pos = pos
+  end
+
+  def scan
+    char = @input[@pos]
+    raise Evilution::ConfigError, "unexpected end of pattern at position #{@pos}" if char.nil?
+
+    name = QUOTES.include?(char) ? quoted(char) : operator || identifier(char)
+    [name, @pos]
+  end
+
+  private
+
+  def quoted(quote)
+    finish = @input.index(quote, @pos + 1)
+    raise Evilution::ConfigError, "unterminated quoted name starting at position #{@pos}" if finish.nil?
+
+    name = @input[(@pos + 1)...finish]
+    raise Evilution::ConfigError, "empty quoted name at position #{@pos}" if name.empty?
+
+    @pos = finish + 1
+    name
+  end
+
+  def operator
+    name = OPERATORS.find { |candidate| @input[@pos, candidate.length] == candidate }
+    @pos += name.length if name
+    name
+  end
+
+  def identifier(char)
+    match = IDENTIFIER.match(@input, @pos)
+    if match.nil?
+      raise Evilution::ConfigError,
+            "invalid name starting with '#{char}' at position #{@pos}; " \
+            "quote names that are not identifiers or operators, e.g. name='|'"
+    end
+
+    @pos = match.end(0)
+    match[0]
+  end
+end

data/lib/evilution/ast/pattern/parser.rb

@@ -2,6 +2,7 @@
 
 require_relative "../pattern"
 require_relative "matcher"
+require_relative "method_name"
 
 class Evilution::AST::Pattern::Parser
   def initialize(input)
@@ -39,17 +40,18 @@ class Evilution::AST::Pattern::Parser
     node_type = consume_identifier
     skip_whitespace
 
-    attributes = {}
-    if current_char == "{"
-      advance(1)
-      attributes = parse_attributes
-      skip_whitespace
-      expect_char("}")
-    end
-
+    attributes = current_char == "{" ? parse_braced_attributes : {}
     Evilution::AST::Pattern::NodeMatcher.new(node_type, attributes)
   end
 
+  def parse_braced_attributes
+    advance(1)
+    attributes = parse_attributes
+    skip_whitespace
+    expect_char("}")
+    attributes
+  end
+
   def parse_attributes
     attrs = {}
     skip_whitespace
@@ -109,15 +111,11 @@ class Evilution::AST::Pattern::Parser
   end
 
   def parse_value_or_nested
-    id = consume_identifier
+    id, @pos = Evilution::AST::Pattern::MethodName.scan(@input, @pos)
     skip_whitespace
 
     if current_char == "{"
-      advance(1)
-      attrs = parse_attributes
-      skip_whitespace
-      expect_char("}")
-      Evilution::AST::Pattern::NodeMatcher.new(id, attrs)
+      Evilution::AST::Pattern::NodeMatcher.new(id, parse_braced_attributes)
     else
       parse_alternatives_from(id)
     end
@@ -133,7 +131,8 @@ class Evilution::AST::Pattern::Parser
         advance(1)
         values << "*"
       else
-        values << consume_identifier
+        name, @pos = Evilution::AST::Pattern::MethodName.scan(@input, @pos)
+        values << name
       end
     end
 

data/lib/evilution/ast/regexp_pattern.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+require "prism"
+require "regexp_parser"
+
+require_relative "../ast"
+
+# The pattern of a regexp literal, parsed with regexp_parser and addressed by
+# byte offsets into the file, for operators that mutate a regexp's structure.
+#
+# Edits are made by offsets into the original source, never by re-emitting the
+# pattern, so everything outside an edit stays byte for byte as written.
+#
+# regexp_parser counts offsets in characters; they are converted to bytes here
+# so they can go straight to source surgery. Prism accepts patterns whose
+# references point nowhere (`/(?:a)\1/`), so an edit has to be compiled before
+# it is emitted: `#compiles?` does that.
+class Evilution::AST::RegexpPattern
+  Token = Data.define(:type, :token, :text, :start_offset, :end_offset)
+
+  attr_reader :tokens
+
+  # Returns nil for anything but a plain regexp literal — interpolated
+  # patterns are only known at runtime — and when regexp_parser cannot read
+  # the pattern (including one that is not valid in its encoding), so callers
+  # simply emit no mutants.
+  def self.parse(node)
+    return nil unless node.is_a?(Prism::RegularExpressionNode)
+
+    new(node)
+  rescue Regexp::Parser::Error
+    nil
+  end
+
+  def initialize(node)
+    @text = node.content_loc.slice
+    @base_offset = node.content_loc.start_offset
+    @options = options_of(node)
+    @byte_offsets = byte_offsets_of(@text)
+    @tokens = scan_tokens
+    @root = Regexp::Parser.parse(@text, options: @options)
+  end
+
+  # Yields every expression of the parsed pattern with its start and end
+  # offsets in the file.
+  def each_expression
+    @root.each_expression do |expression, _index|
+      yield expression, *offsets(expression)
+    end
+  end
+
+  # An expression's start and end offsets in the file, quantifier included.
+  def offsets(expression)
+    [file_offset(expression.ts), file_offset(expression.ts + expression.full_length)]
+  end
+
+  # Whether the pattern still compiles once the span between the two file
+  # offsets is replaced.
+  def compiles?(start_offset, end_offset, replacement)
+    local_start = start_offset - @base_offset
+    mutated = @text.byteslice(0, local_start) + replacement + @text.byteslice((end_offset - @base_offset)..)
+    without_warnings { Regexp.new(mutated, @options) }
+    true
+  rescue RegexpError
+    false
+  end
+
+  private
+
+  # Only extended mode changes how a pattern is read: whitespace and `#`
+  # comments become tokens of their own. Case-insensitivity and multiline
+  # change what a pattern matches, not how it parses or whether it compiles.
+  def options_of(node)
+    node.extended? ? Regexp::EXTENDED : 0
+  end
+
+  # Bytes before each character position, one entry past the last character.
+  def byte_offsets_of(text)
+    offsets = [0]
+    text.each_char { |char| offsets << (offsets.last + char.bytesize) }
+    offsets
+  end
+
+  def file_offset(character_index)
+    @base_offset + @byte_offsets.fetch(character_index)
+  end
+
+  def scan_tokens
+    Regexp::Scanner.scan(@text, options: @options).map do |type, token, text, start_index, end_index|
+      Token.new(type: type, token: token, text: text,
+                start_offset: file_offset(start_index), end_offset: file_offset(end_index))
+    end
+  end
+
+  # Onigmo warns about patterns such as duplicated class ranges; a mutant can
+  # produce them, and the warning would land in the user's output.
+  def without_warnings
+    verbose = $VERBOSE
+    $VERBOSE = nil
+    yield
+  ensure
+    $VERBOSE = verbose
+  end
+end

data/lib/evilution/ast/scope_declaration.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require "prism"
+require_relative "../ast"
+require_relative "literal_callable"
+
+# An ActiveRecord scope declared with a literal body:
+# `scope :recent, -> { where(recent: true) }`, or with `lambda { }` /
+# `proc { }`. The body is what mutations go into; the name is the class
+# method the declaration defines.
+#
+# Only the receiver-less form written directly in a class body counts: that
+# is the call the mutated file re-runs to replace the scope, so the mutated
+# body takes effect. A scope whose body is an object or a variable has no
+# body of its own to mutate.
+module Evilution::AST::ScopeDeclaration
+  # The scope declarations among a class body's direct statements.
+  def self.in_body(body)
+    statements = body.is_a?(Prism::BeginNode) ? body.statements : body
+    return [] unless statements
+
+    statements.body.select { |node| body_of(node) }
+  end
+
+  # The node holding the scope's body -- a LambdaNode, or the BlockNode of a
+  # `lambda` / `proc` call -- or nil when node is not a scope declaration.
+  def self.body_of(node)
+    return nil unless scope_call?(node)
+
+    Evilution::AST::LiteralCallable.body_of(node.arguments.arguments[1])
+  end
+
+  def self.scope_name(node)
+    node.arguments.arguments.first.unescaped
+  end
+
+  def self.scope_call?(node)
+    return false unless node.is_a?(Prism::CallNode) && node.name == :scope && node.receiver.nil?
+
+    args = node.arguments ? node.arguments.arguments : []
+    args.length == 2 && args.first.is_a?(Prism::SymbolNode)
+  end
+
+  private_class_method :scope_call?
+end

data/lib/evilution/ast/uncovered_code.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+require "prism"
+require_relative "../ast"
+require_relative "included_block"
+
+# The lines of a file that hold code no subject covers: statements written in
+# a class, module or `class << self` body, or at the top level, outside every
+# method -- `scope` lambdas, callback macros, constant lists -- or in a
+# concern's `included` block, which is a class body written elsewhere. Mutations are
+# generated per subject, so a run aimed at these lines generates none of its
+# own, and saying so is the only way a reader can tell "nothing to mutate"
+# from "nothing reached".
+#
+# Visibility keywords without arguments (`private`) carry no behaviour of
+# their own and are left out, as are `require` and `require_relative`: loading
+# a file is not something a mutation of this one could test.
+#
+# A few operators do reach class-body statements -- an `alias_method`, an
+# `include` -- through the first method of the scope. A statement holding a
+# line a mutation was generated for is targeted after all, and is left out
+# whole.
+module Evilution::AST::UncoveredCode
+  SCOPE_NODES = [Prism::ClassNode, Prism::ModuleNode, Prism::SingletonClassNode].freeze
+  VISIBILITY_KEYWORDS = %i[private protected public module_function].freeze
+  LOAD_METHODS = %i[require require_relative].freeze
+  private_constant :SCOPE_NODES, :VISIBILITY_KEYWORDS, :LOAD_METHODS
+
+  # subjects: those parsed from file_path; lines: the Range to keep, or nil
+  # for the whole file; mutated_lines: the lines of file_path that mutations
+  # were generated for. Returns the uncovered lines as merged Ranges, in
+  # source order.
+  def self.call(file_path, subjects, lines:, mutated_lines: [])
+    covered = subjects.flat_map { |subject| subject_lines(subject) }.to_set
+    uncovered = code_lines(File.read(file_path), mutated_lines).reject { |line| covered.include?(line) }
+    uncovered = uncovered.select { |line| lines.cover?(line) } if lines
+    merge(uncovered.uniq)
+  end
+
+  def self.code_lines(source, mutated_lines)
+    statements(Prism.parse(source).value.statements)
+      .reject { |node| mutated_lines.any? { |line| line.between?(node.start_line, node.end_line) } }
+      .flat_map { |node| node_lines(node) }
+  end
+
+  def self.statements(body)
+    nodes = case body
+            when Prism::StatementsNode then body.body
+            when Prism::BeginNode then body.statements ? body.statements.body : []
+            else []
+            end
+    nodes.flat_map { |node| expand(node) }
+  end
+
+  def self.expand(node)
+    return statements(node.body) if SCOPE_NODES.any? { |type| node.is_a?(type) }
+
+    included = Evilution::AST::IncludedBlock.of(node)
+    return statements(included.body) if included
+    return [] if bare_visibility?(node) || load_call?(node)
+
+    [node]
+  end
+
+  def self.load_call?(node)
+    node.is_a?(Prism::CallNode) && node.receiver.nil? && LOAD_METHODS.include?(node.name)
+  end
+
+  def self.bare_visibility?(node)
+    node.is_a?(Prism::CallNode) && node.receiver.nil? && node.arguments.nil? &&
+      VISIBILITY_KEYWORDS.include?(node.name)
+  end
+
+  def self.node_lines(node)
+    (node.start_line..node.end_line).to_a
+  end
+
+  def self.subject_lines(subject)
+    (subject.line_number..(subject.line_number + subject.source.count("\n"))).to_a
+  end
+
+  def self.merge(lines)
+    lines.slice_when { |a, b| b != a + 1 }.map { |run| run.first..run.last }
+  end
+
+  private_class_method :code_lines, :statements, :expand, :bare_visibility?, :load_call?, :node_lines,
+                       :subject_lines, :merge
+end

data/lib/evilution/ast/value_object_definition.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require "prism"
+require_relative "../ast"
+
+# A value-object definition: `Data.define(...)` or `Struct.new(...)` called on
+# the core class itself (`Data` or `::Data`, not `Foo::Data`), with or without
+# a block.
+module Evilution::AST::ValueObjectDefinition
+  DEFINERS = { Data: :define, Struct: :new }.freeze
+
+  def self.match?(node)
+    return false unless node.is_a?(Prism::CallNode) && core_constant?(node.receiver)
+
+    DEFINERS[node.receiver.name] == node.name
+  end
+
+  def self.core_constant?(node)
+    return true if node.is_a?(Prism::ConstantReadNode)
+
+    node.is_a?(Prism::ConstantPathNode) && node.parent.nil?
+  end
+
+  private_class_method :core_constant?
+end

data/lib/evilution/baseline/failure_formatter.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require_relative "../baseline"
+
+# The lines that say why a spec file was red in the baseline, shared by the
+# warning printed during the run and the note in the final report.
+class Evilution::Baseline::FailureFormatter
+  NO_DETAIL = "no failure detail was captured"
+
+  def call(failure)
+    lines = error_lines(failure) + failure.examples.map { |example| example_line(example) }
+    remainder = failure.example_count - failure.examples.length
+    lines << "... and #{remainder} more failing" if remainder.positive?
+    lines.empty? ? [NO_DETAIL] : lines
+  end
+
+  private
+
+  def error_lines(failure)
+    failure.error ? failure.error.lines.map(&:chomp) : []
+  end
+
+  def example_line(example)
+    line = [example.id, example.description].reject(&:empty?).join(" ")
+    example.message.empty? ? line : "#{line} -- #{example.message}"
+  end
+end

data/lib/evilution/baseline/report.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require_relative "../baseline"
+
+# What a baseline run of one spec file sends back across the fork: whether it
+# passed and, when it did not, enough to say why. A plain hash of strings and
+# numbers, so it marshals over the pipe whatever the test framework is.
+#
+# The detail is bounded here, in the child: a spec file with a thousand failing
+# examples has nothing more to say after the first few. Their ids are kept in
+# far greater number, since a mutation run is compared against all of them.
+module Evilution::Baseline::Report
+  MAX_EXAMPLES = 10
+  MAX_IDS = 1000
+  MAX_MESSAGE_LENGTH = 300
+  MESSAGE_LINES = 3
+  ERROR_LINES = 5
+  ELLIPSIS = "..."
+
+  # failed_ids: every failing example, named so a mutation run can recognise
+  # it again (see Integration::RSpec::ExampleIds); empty where the framework
+  # does not provide such names.
+  def self.build(passed:, failures: [], error: nil, failed_ids: [])
+    {
+      passed: passed ? true : false,
+      failure_count: failures.length,
+      failures: failures.first(MAX_EXAMPLES).map { |failure| example(failure) },
+      error: error_excerpt(error),
+      failed_ids: failed_ids.first(MAX_IDS)
+    }
+  end
+
+  # A runner may still answer with a bare pass/fail.
+  def self.from(outcome)
+    outcome.is_a?(Hash) ? outcome : build(passed: outcome)
+  end
+
+  def self.example(failure)
+    {
+      id: failure[:id].to_s,
+      description: failure[:description].to_s,
+      message: truncate(lines_of(failure[:message]).first(MESSAGE_LINES).join(" "))
+    }
+  end
+  private_class_method :example
+
+  # Each line is cut on its own, so one long path does not cost the lines
+  # after it.
+  def self.error_excerpt(error)
+    lines = lines_of(error).first(ERROR_LINES)
+    lines.empty? ? nil : lines.map { |line| truncate(line) }.join("\n")
+  end
+  private_class_method :error_excerpt
+
+  def self.lines_of(text)
+    text.to_s.lines.map(&:strip).reject(&:empty?)
+  end
+  private_class_method :lines_of
+
+  def self.truncate(text)
+    return text if text.length <= MAX_MESSAGE_LENGTH
+
+    "#{text[0, MAX_MESSAGE_LENGTH - ELLIPSIS.length]}#{ELLIPSIS}"
+  end
+  private_class_method :truncate
+end