# mutare v0.1.0 - 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.
  - [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.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 that help Mutare understand source code.
  - [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 `<<>>`. The binary sibling of `Mutare.Mutators.List`/`MapLiteral`/ `TupleLiteral` — it asks "does anything depend on this binary's contents?". 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 `%{}`. The map counterpart of `Mutare.Mutators.List`'s non-empty-list collapse — it asks "does anything depend on this map's contents?". 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 `{}`. The tuple sibling of `Mutare.Mutators.List`/`MapLiteral` — it asks "does anything destructure or match this tuple?". 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 Stryker and its viewer/dashboard speak).
  - [Mutare.Report.Live](Mutare.Report.Live.md): Live progress for the human report.
  - [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.Manifest](Mutare.Manifest.md): A per-mutant map of where each mutant lives in its rendered metamutant.
  - [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): Decide, per mutant, which test files to run — 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.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.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.Schema](Mutare.Schema.md): The mutant schema for a whole project: every in-scope source transformed into
its metamutant, with globally-unique mutant ids threaded across files.
  - [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 corrections for three upstream quirks 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.

