Mutare.Mutators (mutare v0.4.1)

Copy Markdown View Source

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.

Summary

Functions

all()

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

built_in?(module)

Whether module is one of the built-in mutators — as opposed to a custom module a project lists under :mutators.

families()

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

registry()

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

resolve(mutators)

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

transform_managed()

Returns built-in families implemented directly by the transform.

Functions

all()

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

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

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

built_in?(module)

@spec built_in?(module()) :: boolean()

Whether module is one of the built-in mutators — as opposed to a custom module a project lists under :mutators.

Built-in swaps are compile-safe by construction (they reuse the source's operands), which a custom mutator's replacement need not be. The transform reads this where that difference decides a delivery: see Mutare.Transform.LiftedEmit.

iex> Mutare.Mutators.built_in?(Mutare.Mutators.Relational)
true
iex> Mutare.Mutators.built_in?(String)
false

families()

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

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

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

registry()

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

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

resolve(mutators)

@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()

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