MutagenEx.MutationEnumerator (mutagen_ex v0.2.0)

Copy Markdown View Source

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

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

error()

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

Enumeration error: site cap exceeded (r7).

fingerprint_input()

@opaque fingerprint_input()

planned_entry()

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

planned_result()

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

result()

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

Enumeration result.

skipped_entry()

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

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

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

Functions

enumerate(ast_cache, scope_records, covered_lines, opts \\ [])

@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(entries, source)

@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(entries, map)

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

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