# `MutagenEx.MutationEnumerator`
[🔗](https://github.com/iautom8things/mutagen_ex/blob/v0.2.0/lib/mutagen_ex/mutation_enumerator.ex#L107)

Walks the in-scope ASTs from the AST cache and produces a deterministic,
ordered list of `%MutagenEx.MutationEnumerator.Site{}` records, plus a
parallel `skipped` list and a `warnings` list.

Implements the behavioural contract in
[`mutagen.mutation_enumeration`](https://github.com/iautom8things/mutagen_ex/blob/main/.spec/specs/mutation_enumeration.spec.md).

## Inputs

  * `ast_cache` — the pre-parsed AST for each file, with source text. Per
    r6 this is the **only** source of AST data: the enumerator never
    opens a file. The runner relies on this so the AST that was
    enumerated is the exact AST that gets restored on rollback.
  * `scope_records` — `[%MutagenEx.ScopeResolver.Scope{}]` produced by
    `MutagenEx.ScopeResolver.resolve/2`. Each names a file, an inclusive
    line range, module and optional function to select from the file.
  * `covered_lines` — `%{file => MapSet.t(pos_integer())}`. The set of
    lines the cited tests executed. Sites use coverage on their line
    or, for definition heads and positionless nodes, anywhere in
    their innermost branch body or their own clause body when outside
    a branch. Uncovered candidates are filtered before
    mutator validation.

## Output

Returns `%{sites: [Site.t()], skipped: [skipped_entry()], warnings:
[warning()]}`.

  * `:sites` is the ordered, deterministic list of mutation sites.
    Determinism (r1) is by construction: scope records are processed in
    input order, AST traversal is `Macro.prewalk` (left-to-right depth-
    first), and within a node mutators are tried in
    `MutagenEx.Mutators.all/0`'s canonical order.
  * `:skipped` is the parallel list of `{:skip, reason}` outcomes (r3).
    Each entry is `%{site_id: id, reason: atom, mutator: name, file:
    path}`.
  * `:warnings` carries module-scoped advisories. Currently the only
    warning is `{:no_mutation_candidates, module}` from r5 (a scope that
    produced zero sites AND zero skipped entries — e.g. a behaviour-only
    module).

## Opts

  * `:mutators` — list of mutator modules to consult. Defaults to
    `MutagenEx.Mutators.all/0`. Exposed so unit tests can drive the
    enumerator against a smaller, deterministic subset (e.g. arith-only)
    without bringing the whole catalog into a fixture.
  * `:source` — collect byte spans for source excerpts. Defaults to `true`.

## Determinism contract (r1)

Given a fixed input tuple `{ast_cache, scope_records, covered_lines}`,
the output is byte-identical across runs of the same Elixir/OTP version.
Specifically:

  * scope records are walked in input order;
  * within a scope, sites follow the AST's depth-first walk order;
  * within a node, mutators are tried in `Mutators.all/0` order;
  * a node that matches two mutators produces two sites, in that order;
  * site IDs use lexical occurrence counts and stay stable under formatting
    (`mutagen.decision.mutation_id_scheme_2`).

The property test exercises this on randomly generated input tuples.

# `error`

```elixir
@type error() :: {:error, :too_many_sites, map()}
```

Enumeration error: site cap exceeded (r7).

# `fingerprint_input`

```elixir
@opaque fingerprint_input()
```

# `planned_entry`

```elixir
@type planned_entry() :: %{
  :group_key =&gt; tuple(),
  :fingerprint =&gt; fingerprint_input() | String.t(),
  :runtime? =&gt; boolean(),
  optional(atom()) =&gt; term()
}
```

# `planned_result`

```elixir
@type planned_result() :: %{
  sites: [planned_entry()],
  skipped: [planned_entry()],
  warnings: [warning()]
}
```

# `result`

```elixir
@type result() :: %{
  sites: [MutagenEx.MutationEnumerator.Site.t()],
  skipped: [skipped_entry()],
  warnings: [warning()]
}
```

Enumeration result.

# `skipped_entry`

```elixir
@type skipped_entry() :: %{
  site_id: String.t(),
  reason: atom(),
  mutator: atom(),
  file: String.t()
}
```

Skip-tracked site: see r3 and `mutagen.decision.validate_predicates`.

# `warning`

```elixir
@type warning() :: {:no_mutation_candidates, module()}
```

Enumeration warning. Currently only the empty-scope variant (r5).

# `enumerate`

```elixir
@spec enumerate(map(), [MutagenEx.ScopeResolver.Scope.t()], map(), keyword()) ::
  result() | planned_result() | error()
```

Enumerate mutation sites for `scope_records` against `ast_cache` and
`covered_lines`.

See the module doc for the input/output contract.

## Options

  * `:mutators` — list of mutator modules to consult. Defaults to
    `MutagenEx.Mutators.all/0`.
  * `:planned` — a map from files to lists of ascending, inclusive line ranges
    or `{from, to}` pairs.
    Selects candidates whose spans overlap those ranges and ignores
    `covered_lines`. Sites and skips are plain maps that also carry
    `:group_key`, deferred `:fingerprint` inputs, and `:runtime?`. Planned skips carry
    the source span, function and path as well as the usual skip fields.
  * `:max_sites` — positive integer cap on the produced sites list
    (per `mutagen.mutation_enumeration.r7`). When the cap is exceeded
    the enumerator returns `{:error, :too_many_sites, details}` instead
    of materialising more sites than requested. Default is unbounded
    (callers that want the cap MUST pass it; the Mix task threads
    `Config.max_sites` in).
  * `:dispatch_mode` — `:head_atom` (default) or `:legacy`. Internal
    test seam exposing how the per-node mutator candidate list is
    computed:

      - `:head_atom` consults
        `MutagenEx.Mutators.Dispatch.mutators_for_node/1` to
        pre-filter the catalog by the node's head atom before
        calling `match?/1` on each (per
        `mutagen.decision.static_mutator_dispatch`). This is the
        production path.
      - `:legacy` calls `match?/1` on every mutator in `:mutators`
        for every node — the pre-dispatch behaviour. ONLY used by
        the head-atom equivalence test
        (`test/mutagen_ex/head_atom_dispatch_test.exs`) to prove the
        two paths produce identical output. NOT a public API; the
        Mix task does not expose this knob.

# `fingerprint_scope`

```elixir
@spec fingerprint_scope([planned_entry()], binary() | :absent) ::
  {[planned_entry()], [{:base_parse_error, integer() | :invalid_encoding}]}
```

Keeps planned entries whose group differs from the same group in the base.

Pass the base source, including the old path's source for a rename, or
`:absent` for a new file. Returns `{entries, warnings}`. All entries
remain in scope when the base cannot be parsed. Groups with a
counterpart in the base are hashed once per call. Changed groups
return their resolved fingerprint. Entries with no counterpart keep
deferred fingerprints.

# `partition_planned_runtime_sites`

```elixir
@spec partition_planned_runtime_sites([planned_entry()], map()) :: %{
  evaluated: [planned_entry()],
  uncovered_candidate: [planned_entry()],
  not_run: [planned_entry()]
}
```

Partitions planned runtime entries by ID against the runner output and
validator skips. An entry missing from the output is an uncovered candidate.

# `to_site`

```elixir
@spec to_site(planned_entry()) :: MutagenEx.MutationEnumerator.Site.t()
```

Converts a planned site into the struct accepted by the mutation runner.

---

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