@callback argument_marks(config :: term()) :: [mark_declaration()]

Asks the transform to mark certain argument positions of certain calls, so this mutator can recognise them at mutate/2 and decline to mutate there (or mutate differently).

This is the general facility behind Mutare's "don't perturb an opaque literal" behaviour: a mutator, not the transform, owns the knowledge of which positions are special. The transform stays domain-agnostic — it stamps label on the resolved position and surfaces it back as context.marks (a MapSet of atoms); Mutare.Mutator.marked?/2 reads it. For example, Mutare.Mutators.IntegerLiteral marks the millisecond/:infinity timeout arguments of Process.sleep, GenServer.call, Task.await, Task.async_stream's :timeout option, … and skips them, so a near-unkillable off-by-one on a duration is never minted.

Called once per resolved instance (like init/1) with that instance's config — so a mutator can extend its built-in marks with positions from its own options. Return a list of declarations, each naming a resolved call and the positions to mark with a label:

@impl true
def argument_marks(_config), do: timeout_marks()

A declaration is {module, function, arity, positions, label}. A position is an effective argument index (a piped receiver counts as index 0) or a {:keyword, key} for a trailing-options key. Arity is effective too, so an option-bearing arity (Task.async_stream/3, /5) can be marked while a same-named arity whose trailing argument is ordinary data (/4, the MFA callback-args list) is left alone. Marks are resolved through the same alias/import machinery as call matching, so aliased and imported forms are covered and a shadowing alias is not. Only the named value node is marked, never an enclosing container, so unrelated mutations there (e.g. List collapsing an options list) are untouched.

Two mutators marking the same position union their labels; the label is a shared vocabulary, so a family can react to a label another declared (declare it too if that must survive the declarer being disabled). Users extend the same tables from configuration — an argument_marks: entry has exactly this shape, and its label must be one some enabled mutator declares (declared_labels/1). A mutator without this callback asks for no marks. argument_marks_from/2 turns a {module, function, arity, positions} list into declarations under a label.

@callback finalize(mutation(), context()) :: mutation() | :skip

Post-processes each produced mutation before it is recorded.

Mutare applies this hook to every mutation the mutator produces, on both delivery paths — each element of a mutate/1/mutate/2 return list and each element of a hosted target's :mutants (Mutare.Mutator.MacroHost.host/2) — with the same context the producing callback received (including context.config, see init/1). Return:

• a mutation/0 — the (possibly rewrapped) mutation to record;
• :skip — drop this mutation.

Because Mutare guarantees the hook runs at every delivery site, a family-rich mutator keeps its producers pure — return Mutare.Mutator.Mutation.tagged(node, [family | finer]) everywhere — and defines the tag → filter → enrich funnel once: finalize/2 reads the leading variant label as the family, drops mutations of disabled families (see Mutare.Mutator.Families), and attaches the family's report note. Delivery code shrinks to pure production, and forgetting a site cannot silently deliver unfiltered, note-less mutants.

Finalization is part of production, not reporting: it runs before overlap suppression and # mutare:ignore filtering, and variant labels carried by the finalized mutation win over variant/2 derivation exactly as at production. Two kinds of mutation are never finalized: a relayed mutation carrying an explicit :producer (see Mutare.Mutator.Mutation — it belongs to the producing family, whose own finalize/2 already ran when the mutation was generated), and a Mutare.Mutator.Structural hook's bare-AST replacements (they carry no metadata to finalize). A target whose mutants all return :skip is dropped entirely.

A mutator without finalize/2 records mutations as returned.

@callback init(opts :: term()) :: term()

Parses the instance's options into its normalized configuration, once per resolved instance.

Called when a :mutators entry is resolved to a Mutare.Mutator.Spec — before the transform reads any file — with the instance's raw options (the opts of a {module, opts} entry, :as already stripped; [] for a bare module). Raise for invalid options: this is where a typo'd option fails loudly, at startup, rather than on the first mutated node.

The return value is delivered to every context-aware callback as context.config — mutate/2, the context-aware Mutare.Mutator.Structural arities, and Mutare.Mutator.MacroHost.host/2. context.opts continues to carry the raw options. A mutator without init/1 gets context.config == context.opts.

A module listed more than once (the documented multi-instance :as pattern) runs init/1 once per instance, each call receiving that entry's own options. Mutare.CallRouting.route_arguments/2 is not config-aware: macro routing is shared by every mutator that meets the routed call, so its classification stays instance-independent by design (see Mutare.CallRouting).

@callback mutate(Macro.t()) :: :skip | [mutation()]

Produces node-level mutations for node.

Return :skip when the mutator does not apply. Otherwise return one mutation/0 entry per mutant. This callback is optional when a mutator produces mutations only through mutate/2 or Mutare.Mutator.Structural.

Transform-managed families such as :guard_drop and :rescue_type are registered for configuration and reporting but do not implement this callback.

@callback mutate(Macro.t(), context()) :: :skip | [mutation()]

Produces context-aware mutations for node.

This callback is used for pipe-aware, configurable, and behaviour-targeted mutators. context.pipe_mode lets a mutator compute effective arity for piped calls; context.opts carries per-instance configuration; context.behaviours carries the enclosing module's behaviour set.

When both mutate/1 and mutate/2 are exported, this callback takes precedence. Mutare does not also call mutate/1. To compose them, call mutate/1 from mutate/2 and combine the results explicitly. The return shape is the same as mutate/1.

@callback mutate_call_option_keys?(opts :: term()) :: boolean()

Controls mutation of trailing keyword-option keys.

The transform calls this after identifying a candidate that mutates a call option key such as timeout: in foo(timeout: 5). Return true to keep the candidate or false to suppress it. A mutator without this callback keeps the candidate.

The callback receives the mutator instance's configured options. It is separate from mutate/2 because option-key detection happens after the key node has already been offered to mutators.

@callback name() :: atom()

Short family name, shown in reports (e.g. :arithmetic).

@callback required_modules() :: [module()]

Declares modules that must be loadable for this mutator's routing and hosting to be valid.

A DSL plugin has a deployment requirement Mutare cannot infer: the library whose macros it routes (Mutare.CallRouting.call_routes/0) or hosts (Mutare.Mutator.MacroHost.hosted_macros/0) must be loadable in the Mutare process — otherwise its routes register against nothing and its mutations silently fail to fire. Declaring those modules here turns the silent degradation into a loud startup error: the check runs once, when the :mutators entry is resolved to a Mutare.Mutator.Spec (before init/1, before any source is read), and a missing module aborts the run with a Mutare.EnvironmentError naming the plugin, the missing modules, and the deployment requirement.

@impl true
def required_modules, do: [Ecto.Schema, Ecto.Query]

Loadability (Code.ensure_loaded?/1) is the whole check — it does not verify that a module's application is started or that its version is compatible. A plugin with a requirement beyond loadability raises its own descriptive error from init/1 (or from Mutare.CallRouting.call_routes/0).

A non-mutating extension may export the same function — capability discovery is by export, so Mutare.Extension.validate!/1 applies the same check to :extensions entries. A module without this callback is assumed environment-independent.

@callback variant(original :: Macro.t(), mutated :: Macro.t()) ::
  String.t() | atom() | [String.t() | atom()] | nil

Derives variant labels from an emitted {original, mutated} pair.

Return one label, a list of labels, or nil. Labels must be members of variants/0 and are matched case-insensitively by ignore directives.

Classify from both nodes, not the mutated node alone. For example, a strip mutation such as -(a + b) → a + b emits a + node but is not an operator swap. Operator families can use op_swap_variant/3 for this pattern:

# in Mutare.Mutators.Relational
@swap_ops [:>, :>=, :<, :<=, :==, :!=, :===, :!==]
def variants, do: Enum.map(@swap_ops, &to_string/1)
def variant(original, mutated),
  do: Mutare.Mutator.op_swap_variant(original, mutated, @swap_ops)

@callback variants() :: [String.t() | atom()]

Declares the variant labels this mutator supports in # mutare:ignore[family:label] filters.

A single source node may produce several sibling mutants. Variant labels allow a directive to suppress one kind without suppressing the whole family.

A mutator that declares variants assigns labels in one of two ways:

• Tag at production — return a Mutare.Mutator.Mutation.tagged(node, label) from mutate/1/mutate/2, attaching the label where the mutant is built. Best when the kind is known at construction (a value family: tagged(AST.literal(0), "zero")).
• Derive afterwards — implement variant/2, which classifies the {original, mutated} pair. Best when the label reads cleanly off the node (an operator family: op_swap_variant/3 over the swapped operator).

A tagging mutator does not need variant/2. A mutator with no variant vocabulary supports only the bare [family] filter; a qualified filter against it is an error.

Labels must be non-empty wire-safe tokens: no whitespace, ,, (, ), ], or ". Treat labels as public API because users write them in source comments.