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 aftermutate/1and before any compile to decide whether the swap is sensible. Returns:okor{: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:highfor 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.
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
@type ast_node() :: Macro.t()
AST node as returned by Code.string_to_quoted/2.
@type confidence() :: :high | :low
@type mutator_name() :: atom()
Snake_case atom name of a mutator (:arith, :case_drop, …).
@type validation_result() :: :ok | {:skip, atom()}
Outcome of validate/1. :ok keeps the site; {:skip, reason} drops it.
Callbacks
@callback confidence() :: confidence()
@callback name() :: mutator_name()
@callback validate(ast_node()) :: validation_result()
Functions
@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.
@spec confidence(mutator_name()) :: confidence()
Returns a registered mutator's confidence, defaulting to :high.
Raises ArgumentError for an unknown 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.
@spec names() :: [mutator_name()]
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.
Walks the entire tree, including children inside metadata-bearing tuples and inside lists/tuples of further AST nodes.
@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.