# `MutagenEx.Mutators`
[🔗](https://github.com/iautom8things/mutagen_ex/blob/v0.2.0/lib/mutagen_ex/mutators.ex#L1)

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."

# `ast_node`

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

AST node as returned by `Code.string_to_quoted/2`.

# `confidence`

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

# `mutator_name`

```elixir
@type mutator_name() :: atom()
```

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

# `validation_result`

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

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

# `confidence`
*optional* 

```elixir
@callback confidence() :: confidence()
```

# `match?`

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

# `mutate`

```elixir
@callback mutate(ast_node()) :: ast_node()
```

# `name`

```elixir
@callback name() :: mutator_name()
```

# `validate`

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

# `all`

```elixir
@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`

```elixir
@spec confidence(mutator_name()) :: confidence()
```

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

Raises `ArgumentError` for an unknown name.

# `fetch`

```elixir
@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`

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

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

# `normalize`

```elixir
@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`

```elixir
@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.

---

*Consult [api-reference.md](api-reference.md) for complete listing*
