# `Mutare.Mutators`
[🔗](https://github.com/foxbenjaminfox/mutare/blob/v0.2.1/lib/mutare/mutators.ex#L1)

The registry and resolver for Mutare's built-in mutator families.

All built-in families run by default. Set `:mutators` to a list of family atoms or custom mutator modules to choose a different set. A `{mutator, opts}` pair configures one entry.

Include `:builtins` to add entries to the default set:

    mutators: [:builtins, MyApp.Mutators.AccessPolicy]

Without that token, the list replaces the defaults. Use `{:builtins, except: [:family]}` to start with all built-ins except selected families. See `resolve/1` for every accepted entry form.

# `all`

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

The default mutator set: every built-in module, in registry order.

    iex> Mutare.Mutators.all() |> List.first()
    Mutare.Mutators.Arithmetic

# `families`

```elixir
@spec families() :: [atom()]
```

Every known built-in family atom, in registry order.

    iex> :arithmetic in Mutare.Mutators.families()
    true

# `registry`

```elixir
@spec registry() :: [{atom(), module()}]
```

The ordered `family => module` registry of every built-in mutator.

# `resolve`

```elixir
@spec resolve([
  atom() | module() | {atom() | module(), term()} | Mutare.Mutator.Spec.t()
]) :: [
  Mutare.Mutator.Spec.t()
]
```

Resolves mutator configuration entries to `Mutare.Mutator.Spec` structs in the
supplied order.

Entries may be:

  * a registered family atom
  * a custom mutator module
  * a configured `{family_or_module, options}` pair
  * `:builtins` for every built-in family
  * `{:builtins, except: families}` to exclude selected built-ins
  * an existing `Mutare.Mutator.Spec`

A group token expands at its position in the list. Without a group token, only
the explicitly listed families are enabled. To reconfigure a built-in, exclude
it from the group and add a configured entry.

Raises `ArgumentError` for unknown families, unsupported group options, or modules
that do not implement the required mutator capability.

    iex> specs = Mutare.Mutators.resolve([:arithmetic, {:integer, as: :ints}])
    iex> Enum.map(specs, &{&1.name, &1.module, &1.opts})
    [{:arithmetic, Mutare.Mutators.Arithmetic, []}, {:ints, Mutare.Mutators.IntegerLiteral, []}]

    iex> Mutare.Mutators.resolve([:builtins]) ==
    ...>   Mutare.Mutators.resolve(Mutare.Mutators.all())
    true

# `transform_managed`

```elixir
@spec transform_managed() :: [module()]
```

Returns built-in families implemented directly by the transform.

These families remain registered and configurable but do not implement the
`Mutare.Mutator` producing callbacks.

---

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