Behaviour for mutation operators that transform AST nodes.

Mutators implement specific mutation strategies (e.g., arithmetic operators, boolean operators, literals) and return a list of possible mutations for a given AST.

Each mutator declares which languages it supports via supported_languages/0. Mutators targeting the same AST family (e.g., Elixir and Erlang both use BEAM AST) can declare support for multiple languages.

Traversal and Pruning

walk/3 performs a context-aware, pre-order traversal of the AST. It threads the nearest enclosing source line through context[:line] and prunes subtrees that should never be mutated (module aliases, use/import/alias/require, documentation and typespec attributes, and keyword/option keys). Callers can prune additional framework DSL calls via context[:skip_calls]. See walk/3 for the full set of rules.

Equivalent Mutations

Mutators can declare that a generated mutation is semantically equivalent to the original code — meaning no test can ever kill it. This avoids polluting mutation scores with false negatives.

There are two ways to mark equivalence:

1. At generation time — set equivalent: true in the mutation map returned by mutate/2. Use this when the mutator knows at generation time that the mutation is equivalent (e.g., swapping arguments to a commutative operator).

2. Via the equivalent?/1 callback — implement this for more complex analysis that needs to inspect the full mutation map. The default implementation checks the :equivalent key.

Example

defmodule Muex.Mutator.MyMutator do
  @behaviour Muex.Mutator

  @impl true
  def mutate(ast, _context) do
    # Return list of mutated AST variants
    [mutated_ast_1, mutated_ast_2]
  end

  @impl true
  def name, do: "My Mutator"

  @impl true
  def description, do: "Mutates specific AST patterns"

  @impl true
  def supported_languages, do: [Muex.Language.Elixir, Muex.Language.Erlang]

  # Optional: override for complex equivalence detection
  @impl true
  def equivalent?(%{description: "swap arguments in +()" <> _}), do: true
  def equivalent?(_mutation), do: false
end