Static, order-preserving head-atom dispatch table for the mutator catalog.
Implements mutagen.decision.static_mutator_dispatch: the
MutagenEx.MutationEnumerator consults mutators_for_node/1 BEFORE
calling match?/1 on each catalog entry. The table maps an AST node's
head atom to the (small) sub-sequence of mutators that could possibly
match a node with that head; mutators that match shapes which are NOT
3-tuples (bare literals, {:ok, _} / {:error, _} 2-tuples) live in a
separate @any_mutators list and are always considered.
Why this exists (and why it is a static table, not a behaviour callback)
The enumerator's try_mutators/6 used to run every mutator's match?/1
against every AST node — O(nodes × catalog_size). For files with even
modest size this means asking ten mutators "do you match this :+ node?"
when only one possibly could. The dispatch table makes it
O(nodes × applicable_mutators).
The scope auditor for mutagen-wrd.25 flagged the alternative design —
an @optional_callback head_atoms/0 on the MutagenEx.Mutators
behaviour — as bloat:
- The mutator catalog is closed (
mutagen.mutators.r7). No external mutator authors. The list of head atoms is small and trivially captured in one place. - An optional callback opens a drift surface: a future mutator could
forget to declare its head atoms, dispatch would silently fall back
to
:anyfor it, and the optimisation would be defeated without anyone noticing.
See .spec/decisions/static_mutator_dispatch.md for the full rationale.
Determinism contract
mutators_for_node/1 returns a sub-sequence of
MutagenEx.Mutators.all/0. The relative order of any two mutators in
the result is identical to their relative order in Mutators.all/0.
This is the property that preserves byte-identity of the JSON output
across runs (mutagen.mutation_enumeration.r1 and the technical
red-team determinism finding called out in the decision file).
Concretely: Dispatch builds the table by filtering
Mutators.all/0 — it never re-orders. The equivalence test
(test/mutagen_ex/head_atom_dispatch_test.exs) locks both the
correctness property (same mutators get tried per node) AND the
order-preserving property (the filtered sub-sequence equals the
result of the legacy "iterate Mutators.all/0" path applied to the
same node).
Summary
Functions
Returns the sub-sequence of MutagenEx.Mutators.all/0 whose match?/1
could possibly match node, preserving Mutators.all/0 order.
Functions
Returns the sub-sequence of MutagenEx.Mutators.all/0 whose match?/1
could possibly match node, preserving Mutators.all/0 order.
The contract is:
- Result is a list of mutator modules.
- Result is a subset of
Mutators.all/0. - The relative order of any two mutators in the result matches their
relative order in
Mutators.all/0(the order-preserving / byte- identity property required bymutagen.mutation_enumeration.r1). - Every mutator that would
match?(node)is included in the result. (The converse is allowed: the result MAY include a mutator whosematch?/1then returnsfalse—mutators_for_node/1is a cheap pre-filter, not a full classifier. The enumerator still callsmatch?/1on each candidate.)
The equivalence test in
test/mutagen_ex/head_atom_dispatch_test.exs locks both properties
against the legacy "iterate Mutators.all/0" path for a corpus of
representative AST nodes.