MutagenEx.Mutators behaviour (mutagen_ex v0.2.0)

Copy Markdown View Source

Registry and behaviour for the ten v1 mutators.

Each mutator is a module implementing MutagenEx.Mutators callbacks:

  • name/0 — the snake_case atom name (e.g. :arith) used in site IDs.
  • match?/1 — predicate over an AST node deciding whether the node is a candidate for this mutator.
  • mutate/1 — produces the swapped AST node. Pure; performs no I/O.
  • validate/1 — runs after mutate/1 and before any compile to decide whether the swap is sensible. Returns :ok or {:skip, reason} with an atom identifying why the mutator rejected the swap.
  • confidence/0 (optional) — qualitative rating of the operator as a signal for test gaps. Defaults to :high for registered mutators.

Catalog

The catalog is closed in v1 (mutagen.mutators.r7): ten mutators, no plugin interface, no user-supplied addition. Adding a new mutator requires a code change here AND a corresponding mutagen.mutators spec revision.

Site IDs

site_id/3 hashes the enclosing definition, normalized node, and occurrence ordinal. The enumerator supplies that identity in file walk order. See mutagen.decision.mutation_id_scheme_2.

Out of scope here

This module enumerates the catalog and computes IDs. It does not walk a source file looking for sites (that is the enumerator's job in S4b) and it does not compile or run mutated code (that is the runner's job in S5). Per the ticket's Out of Scope (intent): "Do not run any mutated code. The catalog is pure AST manipulation."

Summary

Types

AST node as returned by Code.string_to_quoted/2.

Snake_case atom name of a mutator (:arith, :case_drop, …).

Outcome of validate/1. :ok keeps the site; {:skip, reason} drops it.

Functions

Returns the closed list of v1 mutator modules in their canonical order.

Returns a registered mutator's confidence, defaulting to :high.

Looks up a mutator module by its name/0 value. Returns nil if the name is not in the v1 catalog.

Returns the snake_case atom name of every catalog entry, in all/0 order.

Strips :line, :column, :end_line, and :end_column from every metadata keyword in an AST. This comparison helper preserves all other metadata for mutator validation.

Builds a scheme 2 ID from a project-relative path and a normalized identity.

Types

ast_node()

@type ast_node() :: Macro.t()

AST node as returned by Code.string_to_quoted/2.

confidence()

@type confidence() :: :high | :low

mutator_name()

@type mutator_name() :: atom()

Snake_case atom name of a mutator (:arith, :case_drop, …).

validation_result()

@type validation_result() :: :ok | {:skip, atom()}

Outcome of validate/1. :ok keeps the site; {:skip, reason} drops it.

Callbacks

confidence()

(optional)
@callback confidence() :: confidence()

match?(ast_node)

@callback match?(ast_node()) :: boolean()

mutate(ast_node)

@callback mutate(ast_node()) :: ast_node()

name()

@callback name() :: mutator_name()

validate(ast_node)

@callback validate(ast_node()) :: validation_result()

Functions

all()

@spec all() :: [module()]

Returns the closed list of v1 mutator modules in their canonical order.

The order is significant: site enumeration walks mutators in this order so IDs are deterministic when two mutators happen to match the same node.

confidence(name)

@spec confidence(mutator_name()) :: confidence()

Returns a registered mutator's confidence, defaulting to :high.

Raises ArgumentError for an unknown name.

fetch(name)

@spec fetch(mutator_name()) :: module() | nil

Looks up a mutator module by its name/0 value. Returns nil if the name is not in the v1 catalog.

names()

@spec names() :: [mutator_name()]

Returns the snake_case atom name of every catalog entry, in all/0 order.

normalize(ast)

@spec normalize(ast_node()) :: ast_node()

Strips :line, :column, :end_line, and :end_column from every metadata keyword in an AST. This comparison helper preserves all other metadata for mutator validation.

Walks the entire tree, including children inside metadata-bearing tuples and inside lists/tuples of further AST nodes.

site_id(relative_file, arg, mutator_name)

@spec site_id(
  String.t(),
  {tuple() | nil, ast_node(), non_neg_integer()},
  mutator_name()
) :: String.t()

Builds a scheme 2 ID from a project-relative path and a normalized identity.