MutagenEx.Mutators.Dispatch (mutagen_ex v0.2.0)

Copy Markdown View Source

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 :any for 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

mutators_for_node(arg1)

@spec mutators_for_node(Macro.t()) :: [module()]

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 by mutagen.mutation_enumeration.r1).
  • Every mutator that would match?(node) is included in the result. (The converse is allowed: the result MAY include a mutator whose match?/1 then returns false — mutators_for_node/1 is a cheap pre-filter, not a full classifier. The enumerator still calls match?/1 on 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.