# mutare v0.3.1 - Table of Contents

> A compile-once mutation testing tool for Elixir.

## Pages

- [Mutare](readme.md)
- [Extending Mutare](extending.md)
- [Changelog](changelog.md)
- [LICENSE](license.md)

## Modules

- Core API
  - [Mutare](Mutare.md): Mutare is a mutation testing system for Elixir, that mutates the source you actually write, and compiles once.
  - [Mutare.Ignore](Mutare.Ignore.md): Suppresses selected mutants with a source comment. Ignored mutants remain in the report but are excluded from the mutation score. Their generated code is omitted from the metamutant, reducing compiler input and preventing their replacements from poisoning the build. They retain their IDs, reasons, and positions within `:max_mutants`.
  - [Mutare.Options](Mutare.Options.md): Validated configuration for a mutation run.
  - [Mutare.Result](Mutare.Result.md): The outcome of running the suite against one mutant.
  - [Mutare.Run](Mutare.Run.md): The completed result of a mutation-testing run.
  - [Mutare.Runner](Mutare.Runner.md): Compile once, then run the suite once per mutant in a fresh OS process.
  - [Mutare.Score](Mutare.Score.md): The mutation score and the CI gates computed over a run's results.
  - [Mutare.Site](Mutare.Site.md): One mutant: a single mutation applied at a single source location.

- Writing mutators
  - [Mutare.AST](Mutare.AST.md): Small constructors and predicates for Sourceror AST nodes.
  - [Mutare.Analyze](Mutare.Analyze.md): Expression-level mutant generation for selector hosts and integrations.
  - [Mutare.Calls](Mutare.Calls.md): Call-resolution readers for custom mutators and macro integrations.
  - [Mutare.Mutator](Mutare.Mutator.md): Behaviour for mutators: modules that produce AST replacements.
  - [Mutare.Mutator.MacroHost](Mutare.Mutator.MacroHost.md): Capability behaviour for a mutator that hosts mutations inside a compile-time DSL.
  - [Mutare.Mutator.Mutation](Mutare.Mutator.Mutation.md): A replacement AST node with optional report metadata.
  - [Mutare.Mutator.Spec](Mutare.Mutator.Spec.md): A resolved mutator module, report name, and per-instance options.
  - [Mutare.Mutator.Structural](Mutare.Mutator.Structural.md): Behaviour for mutating positions that are larger than a single AST node: clause return values, `if`/`unless`/`cond` conditions, and structural pattern positions.
  - [Mutare.Test](Mutare.Test.md): Test helpers for projects that implement their own `Mutare.Mutator`.
  - [Mutare.Test.RoutingExtension](Mutare.Test.RoutingExtension.md): A shipped routing-only extension for testing composition with foreign macro routing.

- Writing extensions
  - [Mutare.CallRouting](Mutare.CallRouting.md): Behaviour for describing how Mutare should treat particular calls.
  - [Mutare.Extension](Mutare.Extension.md): Non-mutating extensions for call routing and `use` expansion.
  - [Mutare.Extension.Spec](Mutare.Extension.Spec.md): A resolved non-mutating extension module and its per-instance options.
  - [Mutare.UseExpansion](Mutare.UseExpansion.md): Capability behaviour for overriding a `use` that Mutare cannot expand safely in-process.
  - [Mutare.UseExpansion.ContractError](Mutare.UseExpansion.ContractError.md): Raised when an enabled `Mutare.UseExpansion` handler returns an invalid result or fails.
  - [Mutare.UseExpansion.Expansion](Mutare.UseExpansion.Expansion.md): The directives and behaviours supplied by `c:Mutare.UseExpansion.expand_use/3`.

- Built-in mutators
  - [Mutare.Mutators](Mutare.Mutators.md): The registry and resolver for Mutare's built-in mutator families.
  - [Mutare.Mutators.AliasLiteral](Mutare.Mutators.AliasLiteral.md): Module-alias mutations: replace a literal alias used as a value with a distinct sentinel alias (`Mutare.Mutant`), dropping it when the original already equals the sentinel.
  - [Mutare.Mutators.Arithmetic](Mutare.Mutators.Arithmetic.md): Mutates arithmetic operators
  - [Mutare.Mutators.AtomLiteral](Mutare.Mutators.AtomLiteral.md): Replaces a literal atom with `:mutare`. The replacement is omitted when the original atom is already `:mutare`.
  - [Mutare.Mutators.BitstringLiteral](Mutare.Mutators.BitstringLiteral.md): Bitstring-literal mutation: collapse a non-empty `<<…>>` literal to the empty bitstring `<<>>`. Like the corresponding list, map, and tuple mutations, this tests whether the binary's contents affect the test results. A binary that is built but whose bytes no test pins down lets `<<>>` survive.
  - [Mutare.Mutators.BitstringSpec](Mutare.Mutators.BitstringSpec.md): Mutates Unicode encoding and byte-order specifiers in bitstring constructors. Each mutant changes one segment along one of these axes.
  - [Mutare.Mutators.Bitwise](Mutare.Mutators.Bitwise.md): Mutates bitwise operators and their `Bitwise` function forms
  - [Mutare.Mutators.BooleanLiteral](Mutare.Mutators.BooleanLiteral.md): Boolean-literal mutation: `true` ↔ `false`.
  - [Mutare.Mutators.CallRemoval](Mutare.Mutators.CallRemoval.md): Removes a call that transforms its first argument and returns that argument instead.
  - [Mutare.Mutators.CharlistLiteral](Mutare.Mutators.CharlistLiteral.md): Charlist-sigil mutations: replace a `~c"…"` (or `~C"…"`) charlist with both the empty charlist `~c""` and a non-empty sentinel (`~c"mutare"`), dropping whichever already equals the original and preserving the sigil head (`~C` stays `~C`). The charlist counterpart of `Mutare.Mutators.StringLiteral`.
  - [Mutare.Mutators.ClauseDrop](Mutare.Mutators.ClauseDrop.md): Removes one clause of a multi-clause function, so inputs it handled fall through to a later clause (or raise `FunctionClauseError`)
  - [Mutare.Mutators.Collection](Mutare.Mutators.Collection.md): Renames collection calls to a complementary operation
  - [Mutare.Mutators.CollectionArity](Mutare.Mutators.CollectionArity.md): Changes collection calls to a related operation with fewer arguments
  - [Mutare.Mutators.Conditional](Mutare.Mutators.Conditional.md): Replace a boolean-valued expression with the constants `true` and `false` — the "remove conditionals" mutation. Forcing a decision to one side checks that *both* branches it guards are actually exercised by the suite.
  - [Mutare.Mutators.ConventionAtom](Mutare.Mutators.ConventionAtom.md): Replaces convention atoms with a compatible alternative
  - [Mutare.Mutators.DateTimeLiteral](Mutare.Mutators.DateTimeLiteral.md): Calendar-sigil mutations: shift a date/time literal by one unit.
  - [Mutare.Mutators.DefaultDrop](Mutare.Mutators.DefaultDrop.md): Drops a trailing optional argument so the call uses its default value.
  - [Mutare.Mutators.FloatLiteral](Mutare.Mutators.FloatLiteral.md): Float-literal mutations: `x` → `x + 1.0`, `x - 1.0`, and `0.0`, deduplicated and never equal to `x`.
  - [Mutare.Mutators.GenServer](Mutare.Mutators.GenServer.md): Changes a `GenServer` callback return into another valid OTP return tuple. It runs only in modules that use or declare the `GenServer` behaviour.
  - [Mutare.Mutators.GuardDrop](Mutare.Mutators.GuardDrop.md): Removes a clause guard so the clause matches without its `when` condition
  - [Mutare.Mutators.IfCondition](Mutare.Mutators.IfCondition.md): Replaces each eligible `if`, `unless`, and `cond` condition with `true` and `false`.
  - [Mutare.Mutators.IntegerCall](Mutare.Mutators.IntegerCall.md): Swap complementary `Integer` calls for their opposite
  - [Mutare.Mutators.IntegerLiteral](Mutare.Mutators.IntegerLiteral.md): Integer-literal mutations: `n` → `n + 1`, `n - 1`, and `0` (the "off-by-one" boundary plus the zero sentinel), deduplicated and never equal to `n`.
  - [Mutare.Mutators.KeywordDelete](Mutare.Mutators.KeywordDelete.md): Exchanges the two duplicate-key deletion operations for keyword lists
  - [Mutare.Mutators.List](Mutare.Mutators.List.md): List operator and literal mutations
  - [Mutare.Mutators.Logical](Mutare.Mutators.Logical.md): Logical/boolean operator mutations: `and`↔`or`, `&&`↔`||`, and negation stripping (`not x` → `x`, `!x` → `x`).
  - [Mutare.Mutators.MapKeyword](Mutare.Mutators.MapKeyword.md): Renames `Map` and `Keyword` writes according to how they handle present and absent keys
  - [Mutare.Mutators.MapLiteral](Mutare.Mutators.MapLiteral.md): Map-literal mutation: collapse a non-empty map literal `%{…}` to the empty map `%{}`. Like the non-empty-list collapse in `Mutare.Mutators.List`, this tests whether the map's contents affect the test results. A weak suite that builds a map but never reads a key it carries lets the empty map survive.
  - [Mutare.Mutators.MapSet](Mutare.Mutators.MapSet.md): Swap a `MapSet` set-combination call for its complement
  - [Mutare.Mutators.Math](Mutare.Mutators.Math.md): Mutate calls to the Erlang `:math` module — the floating-point cousin of `Mutare.Mutators.Numeric`, asking: does any test actually depend on *which* trigonometric/logarithmic function (or constant) this call computes?
  - [Mutare.Mutators.ModeSwap](Mutare.Mutators.ModeSwap.md): Replaces mode and unit atoms in supported standard-library calls. Each replacement is valid for that function and argument position.
  - [Mutare.Mutators.Numeric](Mutare.Mutators.Numeric.md): Renames numeric selection and rounding calls to a complementary function
  - [Mutare.Mutators.OperandSwap](Mutare.Mutators.OperandSwap.md): Reverses the first two operands of non-commutative operators and calls.
  - [Mutare.Mutators.PatternSwap](Mutare.Mutators.PatternSwap.md): Exchanges two variables within a container in a structural pattern position
  - [Mutare.Mutators.PatternWildcard](Mutare.Mutators.PatternWildcard.md): Replaces repeated variables in a pattern with `_`, removing the equality constraint created by the repetition
  - [Mutare.Mutators.PeriodBoundary](Mutare.Mutators.PeriodBoundary.md): Exchanges the beginning and end of a calendar period
  - [Mutare.Mutators.RegexLiteral](Mutare.Mutators.RegexLiteral.md): Mutates non-interpolated `~r` sigils. Each changed token or modifier produces a separate mutant.
  - [Mutare.Mutators.RegexLiteral.Flags](Mutare.Mutators.RegexLiteral.Flags.md): Positional flag-scope tracking for a regex pattern.
  - [Mutare.Mutators.Relational](Mutare.Mutators.Relational.md): Relational/equality operator swaps
  - [Mutare.Mutators.RescueType](Mutare.Mutators.RescueType.md): Narrows the exceptions handled by a `rescue`.
  - [Mutare.Mutators.ReturnValue](Mutare.Mutators.ReturnValue.md): Replaces function return expressions with fixed constants.
  - [Mutare.Mutators.StrictEquality](Mutare.Mutators.StrictEquality.md): Relaxes strict equality without changing polarity
  - [Mutare.Mutators.StringByte](Mutare.Mutators.StringByte.md): Narrow the grapheme-aware `String.length` to the byte-level `byte_size` — the question "does this code actually depend on Unicode/grapheme semantics, or would raw byte semantics pass the suite?"
  - [Mutare.Mutators.StringCall](Mutare.Mutators.StringCall.md): Renames string calls to a complementary operation
  - [Mutare.Mutators.StringLiteral](Mutare.Mutators.StringLiteral.md): String-literal mutations: replace a string with both the empty string `""` and a non-empty sentinel (`"mutare"`), dropping whichever already equals the original. So a typical non-empty string yields *two* mutants (empties it and swaps its content); `""` yields just the sentinel; `"mutare"` yields just `""`.
  - [Mutare.Mutators.StringSigilLiteral](Mutare.Mutators.StringSigilLiteral.md): Replaces a `~s` or `~S` sigil with the plain string literals `""` and `"mutare"`. A replacement equal to a static sigil value is omitted
  - [Mutare.Mutators.TemporalOrder](Mutare.Mutators.TemporalOrder.md): Exchanges temporal ordering predicates
  - [Mutare.Mutators.TupleLiteral](Mutare.Mutators.TupleLiteral.md): Tuple-literal mutation: collapse a non-empty tuple literal to the empty tuple `{}`. Like the corresponding list and map mutations, this tests whether the suite depends on the tuple's structure or contents. A `{:ok, value}` that is built but never pattern-matched (or whose shape no test pins down) lets `{}` survive; anywhere the shape *is* used, the mutant is killed.
  - [Mutare.Mutators.WordListLiteral](Mutare.Mutators.WordListLiteral.md): Replaces a non-interpolated `~w` or `~W` word list with an empty list and a one-element sentinel list

- Reporters
  - [Mutare.Report](Mutare.Report.md): Renders mutation results for the human report.
  - [Mutare.Report.Html](Mutare.Report.Html.md): Renders an HTML page that hosts the interactive mutation report.
  - [Mutare.Report.Json](Mutare.Report.Json.md): Renders a mutation run as a mutation-testing-elements report-schema JSON document (the schema used by Stryker and its viewer/dashboard).
  - [Mutare.Report.Live](Mutare.Report.Live.md): Live progress for the human report.
  - [Mutare.Report.Live.Lines](Mutare.Report.Live.Lines.md): The text of the live display, rendered from the reporter's state.
  - [Mutare.Report.Sarif](Mutare.Report.Sarif.md): Renders surviving mutants as a SARIF 2.1.0 log.

- Internal
  - [Mutare.CallRouting.ArgumentRoutes](Mutare.CallRouting.ArgumentRoutes.md): The resolved argument treatments returned by
`c:Mutare.CallRouting.route_arguments/2`.
  - [Mutare.CallRouting.Call](Mutare.CallRouting.Call.md): Stable, resolved view of a known-macro call passed to routing and hosting callbacks.
  - [Mutare.CallRouting.ContractError](Mutare.CallRouting.ContractError.md): Raised when a macro-routing provider violates the extension contract.
  - [Mutare.Changes](Mutare.Changes.md): Source *lines* changed versus a git ref — the basis for `mix mutare --since`,
the CI mode that mutation-tests only what a branch touched.
  - [Mutare.Config](Mutare.Config.md): Translate Mutare options from an optional `.mutare.exs` file and CLI flags.
  - [Mutare.Coverage](Mutare.Coverage.md): Read back the coverage the metamutant recorded during the probe run.
  - [Mutare.Coverage.Recorder](Mutare.Coverage.Recorder.md): The generated-code side of coverage capture: the contract the metamutant and
the test bootstrap share to record coverage **synchronously, in the test
process**, with no race.
  - [Mutare.Duration](Mutare.Duration.md): Parse a human duration string (`"10m"`, `"90s"`, `"1h30m"`) into milliseconds.
  - [Mutare.EnvironmentError](Mutare.EnvironmentError.md): A plugin's declared environment is not satisfied: a module it listed in
`c:Mutare.Mutator.required_modules/0` is not loadable in the Mutare process.
  - [Mutare.Ignore.SpecError](Mutare.Ignore.SpecError.md): Raised when a `# mutare:ignore` directive is provably wrong — a **variant qualifier** that
can't be honoured, or a broken `-start`/`-end` region pairing — surfaced by `mix mutare` as a
clean abort with a fix-it message, before any mutant runs.
  - [Mutare.InvariantError](Mutare.InvariantError.md): Raised under `verify_invariants: true` (`mix mutare --verify-invariants`) when a rendered
metamutant breaks a property the run's results depend on.
  - [Mutare.Manifest](Mutare.Manifest.md): A map from mutant ids to their generated line ranges in a rendered metamutant,
and a list of every place the generated code names a mutant id.
  - [Mutare.Metamutant](Mutare.Metamutant.md): The shape of a selector `case` subject in the metamutant.
  - [Mutare.MutationSite](Mutare.MutationSite.md): Stable public description of one generated mutant.
  - [Mutare.Mutator.Families](Mutare.Mutator.Families.md): A declarative family catalog for a family-rich mutator's configuration.
  - [Mutare.Mutator.MacroHost.Target](Mutare.Mutator.MacroHost.Target.md): One logical fragment and its mutations returned by a macro host.
  - [Mutare.Mutator.Mutation.Attribution](Mutare.Mutator.Mutation.Attribution.md): A report-location override for a `Mutare.Mutator.Mutation` (see its `:attribution` field).
  - [Mutare.Poison](Mutare.Poison.md): Identify compile-poisoning mutants from a failed metamutant compile.
  - [Mutare.Poison.Hint](Mutare.Poison.Hint.md): Turns one unrecoverable compile failure into advice the user can act on.
  - [Mutare.Project](Mutare.Project.md): Resolve the *shape* of the target into a copy-root and a mutate-scope.
  - [Mutare.Report.HarnessDiagnostic](Mutare.Report.HarnessDiagnostic.md): Compact diagnostics for mutants that ended as `:harness_error`.
  - [Mutare.Result.Status](Mutare.Result.Status.md): The single descriptor registry for the `Mutare.Result` status vocabulary.
  - [Mutare.Run.Context](Mutare.Run.Context.md): The **runtime wiring** for a mutation run: the validated `Mutare.Options`
(configuration) bundled with the things that are *not* configuration — the
resolved `Mutare.Project` (copy-root + mutate-scope, derived from the target
path and `--app`/`--workspace`) and the four optional live-progress hooks
(`reporter`, `on_phase`, `on_start`, `on_scan`).
  - [Mutare.Runner.AppGraph](Mutare.Runner.AppGraph.md): Read an umbrella's **declared** inter-app dependency graph out of the sandbox.
  - [Mutare.Runner.Baseline](Mutare.Runner.Baseline.md): Run the complete test suite green-checked against the baseline mutant
(`MUTARE_ACTIVE_MUTANT=0`) — once, several times to catch a flaky suite, or
with retries to survive an occasionally red startup run.
  - [Mutare.Runner.CoverageProbe](Mutare.Runner.CoverageProbe.md): Select the test files to run for each mutant — coverage-driven test selection.
  - [Mutare.Runner.Partitions](Mutare.Runner.Partitions.md): Per-worker partition slots, for DB (or any resource) isolation across the
concurrent mutant runs.
  - [Mutare.RuntimeId](Mutare.RuntimeId.md): The identity embedded in a metamutant, separate from its report number.
  - [Mutare.Sandbox](Mutare.Sandbox.md): Materialise a schema as a runnable copy of the target project.
  - [Mutare.Sandbox.Command](Mutare.Sandbox.Command.md): Decode what a `mix test` mutant run *did*, and orchestrate one typed run.
  - [Mutare.Sandbox.Command.Exit](Mutare.Sandbox.Command.Exit.md): The exit codes a sandbox `mix` run can end with, and what each one means.
  - [Mutare.Sandbox.Command.Invocation](Mutare.Sandbox.Command.Invocation.md): Spawn `mix` against a materialised sandbox as a fresh OS process.
  - [Mutare.Sandbox.Command.Output](Mutare.Sandbox.Command.Output.md): Read shapes out of a `mix` run's captured output.
  - [Mutare.Sandbox.Command.Result](Mutare.Sandbox.Command.Result.md): The typed outcome of one `mix test` mutant run.
  - [Mutare.Sandbox.CompilerOptions](Mutare.Sandbox.CompilerOptions.md): The switches that tune the **one** metamutant compile for speed.
  - [Mutare.Sandbox.DependencyDiagnostic](Mutare.Sandbox.DependencyDiagnostic.md): Render actionable guidance for a sandbox dependency-check failure.
  - [Mutare.Sandbox.ProjectEvaluation](Mutare.Sandbox.ProjectEvaluation.md): Preserve evidence of failures while evaluating the sandbox's `mix.exs` files.
  - [Mutare.Sandbox.RuntimeConfig](Mutare.Sandbox.RuntimeConfig.md): Preserve evidence of errors, exits, and throws during runtime configuration.
  - [Mutare.Schema](Mutare.Schema.md): The mutant schema for a whole project: every in-scope source transformed into
its metamutant, with globally-unique report ids and stable per-file runtime ids.
  - [Mutare.Selector](Mutare.Selector.md): Runtime selection of the active mutant.
  - [Mutare.Transform](Mutare.Transform.md): Source → metamutant transform, expressed as an explicit pipeline over a small
intermediate representation.
  - [Mutare.Transform.NodeRange](Mutare.Transform.NodeRange.md): `Sourceror.get_range/1` with a correction for one upstream quirk that would
otherwise corrupt a survivor's reported location.
  - [Mutare.Transform.Result](Mutare.Transform.Result.md): Public result returned by `Mutare.transform_string/2`.

## Mix Tasks

- Core API
  - [mix mutare](Mix.Tasks.Mutare.md): Mutation-test the current project.

- Internal
  - [mix mutare.install](Mix.Tasks.Mutare.Install.md): Install Mutare and auto-configure its framework integrations.

