evilution 1.3.0 → 1.5.0

data/lib/evilution/ast/callback_declaration.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+require "prism"
+require_relative "../ast"
+require_relative "literal_callable"
+
+# The callables written out in a callback or validation declaration of a
+# class body:
+#
+#   validate :credit_limit, if: -> { paid? && total.positive? }
+#   validates :title, presence: true, unless: [-> { draft? }, :imported?]
+#   before_save { self.slug = title.parameterize }
+#   after_commit -> { notify }, on: :create
+#
+# That is the condition given to `if:` / `unless:`, and the callback itself
+# when it is a block or a lambda. A condition or callback named by a symbol
+# is a method, and a subject of its own already.
+#
+# Declarations are recognised by name -- `validate`, `validates`,
+# `validates_*`, `before_*`, `after_*`, `around_*` -- and only receiver-less,
+# directly in a class body: that is the call the mutated file re-runs.
+module Evilution::AST::CallbackDeclaration
+  # body: the node holding the callable's body. declaration: the call it is
+  # written in. label: how the declaration reads, for naming the subject.
+  Callable = Data.define(:body, :declaration, :label)
+
+  NAME = /\A(?:validate|validates|validates_\w+|(?:before|after|around)_\w+)\z/
+  CONDITIONS = %w[if unless].freeze
+  private_constant :NAME, :CONDITIONS
+
+  # The callables of every callback declaration among a class body's direct
+  # statements.
+  def self.in_body(body)
+    statements = body.is_a?(Prism::BeginNode) ? body.statements : body
+    return [] unless statements.is_a?(Prism::StatementsNode)
+
+    statements.body.select { |node| match?(node) }.flat_map { |declaration| callables(declaration) }
+  end
+
+  # Whether node is a callback declaration that can be run again on its own.
+  # One holding a heredoc cannot be wrapped on its own lines, and is left out.
+  def self.match?(node)
+    node.is_a?(Prism::CallNode) && node.receiver.nil? && NAME.match?(node.name.to_s) && !heredoc?(node)
+  end
+
+  def self.callables(declaration)
+    label = label_of(declaration)
+    bodies_of(declaration).map { |body| Callable.new(body: body, declaration: declaration, label: label) }
+  end
+
+  # `validate :credit_limit, if: ...` reads as `validate(:credit_limit)`; a
+  # declaration naming nothing, as its own name.
+  def self.label_of(declaration)
+    named = arguments_of(declaration).find { |argument| argument.is_a?(Prism::SymbolNode) }
+    named ? "#{declaration.name}(:#{named.unescaped})" : declaration.name.to_s
+  end
+
+  def self.bodies_of(declaration)
+    arguments = arguments_of(declaration)
+    bodies = arguments.filter_map { |argument| Evilution::AST::LiteralCallable.body_of(argument) }
+    bodies.concat(condition_bodies(arguments.last))
+    bodies << declaration.block if declaration.block.is_a?(Prism::BlockNode)
+    bodies
+  end
+
+  # `if: -> { }` and `unless: [-> { }, :named]` alike.
+  def self.condition_bodies(keywords)
+    return [] unless keywords.is_a?(Prism::KeywordHashNode)
+
+    keywords.elements.select { |pair| condition?(pair) }.flat_map do |pair|
+      values = pair.value.is_a?(Prism::ArrayNode) ? pair.value.elements : [pair.value]
+      values.filter_map { |value| Evilution::AST::LiteralCallable.body_of(value) }
+    end
+  end
+
+  def self.condition?(pair)
+    pair.is_a?(Prism::AssocNode) && pair.key.is_a?(Prism::SymbolNode) && CONDITIONS.include?(pair.key.unescaped)
+  end
+
+  def self.arguments_of(call)
+    call.arguments ? call.arguments.arguments : []
+  end
+
+  def self.heredoc?(node)
+    return true if node.respond_to?(:heredoc?) && node.heredoc?
+
+    node.compact_child_nodes.any? { |child| heredoc?(child) }
+  end
+
+  private_class_method :callables, :label_of, :bodies_of, :condition_bodies, :condition?, :arguments_of, :heredoc?
+end

data/lib/evilution/ast/class_body.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+require "prism"
+require_relative "../ast"
+
+# The body of a class, module or `class << self`: the code written outside
+# every method, where no method subject reaches it.
+#
+# Operators that mutate such code attribute their mutants to one method, so
+# each mutant has exactly one subject. That method is the scope's anchor: the
+# first method written in the scope, in source order. Blocks of the body
+# (`included do ... end`) are searched, nested scopes are not: their methods
+# anchor the inner scope. A scope with no method of its own borrows the anchor
+# of the first singleton class in its body that has one, so a class whose
+# methods all sit in `class << self` is still reached.
+class Evilution::AST::ClassBody
+  SCOPES = [Prism::ClassNode, Prism::ModuleNode, Prism::SingletonClassNode].freeze
+  # Nodes whose children belong to something else: a method, or another scope.
+  OPAQUE = [Prism::DefNode, *SCOPES].freeze
+
+  # The location that closes each kind of conditional or loop.
+  CLOSINGS = {
+    Prism::IfNode => :end_keyword_loc,
+    Prism::UnlessNode => :end_keyword_loc,
+    Prism::ElseNode => :end_keyword_loc,
+    Prism::WhileNode => :closing_loc,
+    Prism::UntilNode => :closing_loc
+  }.freeze
+
+  attr_reader :node
+
+  # The bodies anchored at the method starting on the given line, outermost
+  # first. A method anchors its own scope, and with it any enclosing scope
+  # that borrows from it.
+  def self.anchored_at(tree, line)
+    scopes_in(tree).map { |scope| new(scope) }.select { |body| body.anchor_line == line }
+  end
+
+  def self.scopes_in(node)
+    node.compact_child_nodes.flat_map do |child|
+      nested = scopes_in(child)
+      SCOPES.include?(child.class) ? [child, *nested] : nested
+    end
+  end
+
+  private_class_method :scopes_in
+
+  def initialize(node)
+    @node = node
+  end
+
+  def anchor_line
+    first_method = contents.find { |child| child.is_a?(Prism::DefNode) }
+    return first_method.location.start_line if first_method
+
+    singleton_classes = contents.grep(Prism::SingletonClassNode)
+    singleton_classes.filter_map { |scope| self.class.new(scope).anchor_line }.first
+  end
+
+  # The statements of the body the block selects, each one removable: cut
+  # out, it leaves code that still parses. Methods and nested scopes are
+  # neither offered nor searched, and neither is a statement guarded by a
+  # modifier (`include Foo if legacy?`) or an expression used as a value.
+  def declarations(&)
+    body = @node.body
+    return [] unless body
+
+    statements_in(body, removable: body.is_a?(Prism::StatementsNode)).select(&)
+  end
+
+  private
+
+  # Every node written in the scope, in source order, down to the methods and
+  # nested scopes, which are listed but not entered. The scope's own header
+  # (its name, its superclass expression) is not part of the body.
+  def contents
+    @contents ||= @node.body ? descend(@node.body) : []
+  end
+
+  def statements_in(node, removable:)
+    node.compact_child_nodes.flat_map do |child|
+      next [] if OPAQUE.include?(child.class)
+
+      nested = statements_in(child, removable: child.is_a?(Prism::StatementsNode) && !modifier?(node))
+      removable ? [child, *nested] : nested
+    end
+  end
+
+  # A conditional or loop written without its closing keyword: the modifier
+  # forms and the ternary, whose statements cannot be cut out.
+  def modifier?(node)
+    closing = CLOSINGS[node.class]
+    !closing.nil? && node.public_send(closing).nil?
+  end
+
+  def descend(node)
+    node.compact_child_nodes.flat_map do |child|
+      OPAQUE.include?(child.class) ? [child] : [child, *descend(child)]
+    end
+  end
+end

data/lib/evilution/ast/included_block.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require "prism"
+require_relative "../ast"
+
+# The block of an `ActiveSupport::Concern`'s `included do ... end`: code
+# written in a module body that runs in the body of each class including the
+# module. Only the receiver-less, argument-less form with a literal block
+# counts -- `def self.included(base)` and `included(base) { }` are plain Ruby
+# hooks with rules of their own.
+module Evilution::AST::IncludedBlock
+  # The block node, or nil when node is not an `included` block call.
+  def self.of(node)
+    hook_block(node, :included)
+  end
+
+  # The block node of a `prepended do ... end`, the same hook for the classes
+  # that prepend the module; nil when node is not one.
+  def self.prepended(node)
+    hook_block(node, :prepended)
+  end
+
+  def self.hook_block(node, name)
+    return nil unless node.is_a?(Prism::CallNode) && node.name == name
+    return nil unless node.receiver.nil? && node.arguments.nil?
+
+    node.block if node.block.is_a?(Prism::BlockNode)
+  end
+  private_class_method :hook_block
+
+  # The included and prepended blocks among a module body's direct statements.
+  def self.hooks_in_body(body)
+    direct_statements(body).filter_map { |node| of(node) || prepended(node) }
+  end
+
+  def self.direct_statements(body)
+    statements = body.is_a?(Prism::BeginNode) ? body.statements : body
+    statements.is_a?(Prism::StatementsNode) ? statements.body : []
+  end
+  private_class_method :direct_statements
+end

data/lib/evilution/ast/literal_callable.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require "prism"
+require_relative "../ast"
+
+# A callable written out where it is used: `-> { }`, `lambda { }` or
+# `proc { }`. Its body is what mutations go into. A constant, a variable or
+# `method(:name)` in the same place has no body of its own to mutate.
+module Evilution::AST::LiteralCallable
+  BLOCK_CALLS = %i[lambda proc].freeze
+  private_constant :BLOCK_CALLS
+
+  # The node holding the callable's body -- a LambdaNode, or the BlockNode of
+  # a `lambda` / `proc` call -- or nil when node is not a literal callable.
+  def self.body_of(node)
+    return node if node.is_a?(Prism::LambdaNode)
+    return nil unless node.is_a?(Prism::CallNode) && node.receiver.nil? && BLOCK_CALLS.include?(node.name)
+
+    node.block if node.block.is_a?(Prism::BlockNode)
+  end
+end

data/lib/evilution/ast/never_nil.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require "prism"
+require_relative "../ast"
+
+# Expressions whose value is never nil whatever the program does: `self` and
+# the literals other than `nil`. Anything read or computed (a variable, a
+# constant, a call) is not one.
+module Evilution::AST::NeverNil
+  NODE_TYPES = [
+    Prism::SelfNode,
+    Prism::StringNode,
+    Prism::InterpolatedStringNode,
+    Prism::XStringNode,
+    Prism::InterpolatedXStringNode,
+    Prism::SymbolNode,
+    Prism::InterpolatedSymbolNode,
+    Prism::IntegerNode,
+    Prism::FloatNode,
+    Prism::RationalNode,
+    Prism::ImaginaryNode,
+    Prism::ArrayNode,
+    Prism::HashNode,
+    Prism::RangeNode,
+    Prism::RegularExpressionNode,
+    Prism::InterpolatedRegularExpressionNode,
+    Prism::TrueNode,
+    Prism::FalseNode,
+    Prism::LambdaNode
+  ].freeze
+  private_constant :NODE_TYPES
+
+  def self.node?(node)
+    NODE_TYPES.any? { |type| node.is_a?(type) }
+  end
+end

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,216 @@ module Evilution::AST
       @file_path = file_path
       @subjects = []
       @context = []
+      @singleton = [false]
+      @hooks = []
     end
 
     def visit_module_node(node)
-      @context.push(constant_name(node.constant_path))
-      super
-      @context.pop
+      within_context(constant_name(node.constant_path), rooted: rooted?(node.constant_path)) do
+        hooks = IncludedBlock.hooks_in_body(node.body)
+        within_hooks(hooks) do
+          hooks.each { |block| add_declaration_subjects(block.body) }
+          within_scope(singleton: false) { super }
+        end
+      end
     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
-      @context.pop
+      within_context(constant_name(node.constant_path), rooted: rooted?(node.constant_path)) do
+        superclass = node.superclass
+        add_subject(superclass, @context.join("::"), :constant) if ValueObjectDefinition.match?(superclass)
+        add_declaration_subjects(node.body)
+        within_scope(singleton: false) { super }
+      end
+    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)
+      expression = node.expression
+      return within_scope(singleton: true) { super } unless constant_expression?(expression)
+
+      within_context(constant_name(expression), rooted: rooted?(expression)) do
+        within_scope(singleton: true) { super }
+      end
     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
+
+    # An assignment to a constant cannot be written inside a method, so it is
+    # a subject of its own: the whole assignment, named after the constant. A
+    # value-object definition keeps its narrower constant subject instead.
+    def visit_constant_write_node(node)
+      return within_definition(node.value, node.name.to_s) { super } if ValueObjectDefinition.match?(node.value)
+
+      add_subject(node, scoped_name(node.name), :constant_write)
+      super
+    end
+
+    def visit_constant_path_write_node(node)
+      name = path_name(node.target)
+      rooted = rooted?(node.target)
+      return within_definition(node.value, name, rooted: rooted) { super } if ValueObjectDefinition.match?(node.value)
+
+      add_subject(node, rooted ? name : scoped_name(name), :constant_write)
+      super
+    end
+
+    # `LIMIT += 1` assigns the constant again and is a subject like the
+    # assignment it follows, under the same name.
+    def visit_constant_operator_write_node(node)
+      add_subject(node, scoped_name(node.name), :constant_write)
+      super
+    end
+
+    def visit_constant_path_operator_write_node(node)
+      name = path_name(node.target)
+      add_subject(node, rooted?(node.target) ? name : scoped_name(name), :constant_write)
       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
+
+    # What the block finds inside one of these hook blocks of a concern is
+    # marked as written there.
+    def within_hooks(blocks)
+      enclosing = @hooks
+      @hooks = blocks.map { |block| block.location.start_offset...block.location.end_offset }
+      yield
+    ensure
+      @hooks = enclosing
+    end
 
-      loc = node.location
-      method_source = @source.byteslice(loc.start_offset, loc.end_offset - loc.start_offset)
-                             .force_encoding(@source.encoding)
+    def in_hook?(location)
+      @hooks.any? { |range| range.cover?(location.start_offset) }
+    end
+
+    def scoped_name(name)
+      [*@context, name].join("::")
+    end
+
+    # `::LIMIT` and `::Shared::LIMIT` name a constant from the top level,
+    # whatever scope they are written in.
+    def rooted?(path)
+      path.slice.start_with?("::")
+    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, rooted: false)
+      within_context(name, rooted: rooted) do
+        add_subject(definition, @context.join("::"), :constant)
+        yield
+      end
+    end
+
+    # Names what the block finds under `name`: within the scope being
+    # visited, or from the top level when the name was written rooted.
+    def within_context(name, rooted:)
+      enclosing = @context
+      @context = rooted ? [name] : [*enclosing, name]
+      yield
+    ensure
+      @context = enclosing
+    end
+
+    # The callables handed to the declarations of a class body, or of a
+    # concern's `included` or `prepended` block.
+    def add_declaration_subjects(body)
+      add_scope_subjects(body)
+      add_aasm_subjects(body)
+      add_callback_subjects(body)
+    end
+
+    # `scope :recent, -> { ... }` defines the class method `recent`. The
+    # subject spans the whole declaration and mutates its body.
+    # Written in a concern's `included` or `prepended` block it defines that
+    # method on every class taking 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
+
+    # 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,
+        concern_hook: in_hook?(loc)
       )
     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
+        node.full_name.delete_prefix("::")
       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