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.
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 byMutagenEx.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()]}.
:sitesis the ordered, deterministic list of mutation sites. Determinism (r1) is by construction: scope records are processed in input order, AST traversal isMacro.prewalk(left-to-right depth- first), and within a node mutators are tried inMutagenEx.Mutators.all/0's canonical order.:skippedis the parallel list of{:skip, reason}outcomes (r3). Each entry is%{site_id: id, reason: atom, mutator: name, file: path}.:warningscarries 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 toMutagenEx.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 totrue.
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/0order; - 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.
Summary
Types
Enumeration error: site cap exceeded (r7).
Enumeration result.
Skip-tracked site: see r3 and mutagen.decision.validate_predicates.
Enumeration warning. Currently only the empty-scope variant (r5).
Functions
Enumerate mutation sites for scope_records against ast_cache and
covered_lines.
Keeps planned entries whose group differs from the same group in the base.
Partitions planned runtime entries by ID against the runner output and validator skips. An entry missing from the output is an uncovered candidate.
Converts a planned site into the struct accepted by the mutation runner.
Types
@type error() :: {:error, :too_many_sites, map()}
Enumeration error: site cap exceeded (r7).
@opaque fingerprint_input()
@type planned_result() :: %{ sites: [planned_entry()], skipped: [planned_entry()], warnings: [warning()] }
@type result() :: %{ sites: [MutagenEx.MutationEnumerator.Site.t()], skipped: [skipped_entry()], warnings: [warning()] }
Enumeration result.
@type skipped_entry() :: %{ site_id: String.t(), reason: atom(), mutator: atom(), file: String.t() }
Skip-tracked site: see r3 and mutagen.decision.validate_predicates.
@type warning() :: {:no_mutation_candidates, module()}
Enumeration warning. Currently only the empty-scope variant (r5).
Functions
@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 toMutagenEx.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 ignorescovered_lines. Sites and skips are plain maps that also carry:group_key, deferred:fingerprintinputs, 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 (permutagen.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 threadsConfig.max_sitesin).:dispatch_mode—:head_atom(default) or:legacy. Internal test seam exposing how the per-node mutator candidate list is computed::head_atomconsultsMutagenEx.Mutators.Dispatch.mutators_for_node/1to pre-filter the catalog by the node's head atom before callingmatch?/1on each (permutagen.decision.static_mutator_dispatch). This is the production path.:legacycallsmatch?/1on every mutator in:mutatorsfor 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.
@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.
@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.
@spec to_site(planned_entry()) :: MutagenEx.MutationEnumerator.Site.t()
Converts a planned site into the struct accepted by the mutation runner.