Mutare.Site (mutare v0.1.2)

One mutant: a single mutation applied at a single source location.

One source expression may produce several sites, one for each replacement. Each site records its id, source range, mutator, replacement kind, before/after code, ignore state, and optional variant or advisory note. Mutare.transform_string/2 returns sites alongside the generated metamutant source.

A runner may defer rendering original_code and mutated_code, leaving them nil until the result needs to be displayed. summary may hold a cheaper one-line description for live progress. Mutare.transform_string/2 renders the code fields by default.

Summary

Types

t()

Functions

clause_drop(id, file, range, clause_node, opts \\ [])

Builds a lifted deletion site for a function clause.

describe(site)

Returns a one-line description of a site.

in_place(id, file, range, original_node, mutated_node, mutator, opts \\ [])

Builds a site for a node replacement delivered by an in-place selector.

in_place_drop(id, file, range, clause_node, mutator, opts \\ [])

Builds an in-place deletion site for a rescue clause.

lifted_replace(id, file, range, original_node, mutated_node, mutator, opts \\ [])

Builds a site for a node replacement delivered through function lifting.

return_value(id, file, range, original_node, mutated_node, mutator, opts \\ [])

Builds an in-place site for a return-expression replacement.

summary_line(site)

Returns the live-progress description for a site.

Types

t()

@type t() :: %Mutare.Site{
  block_macro: {atom(), non_neg_integer()} | nil,
  column: pos_integer() | nil,
  file: String.t(),
  id: pos_integer(),
  ignore_reason: String.t() | nil,
  ignored: boolean(),
  kind: :in_place | :lifted,
  line: pos_integer() | nil,
  mutated_code: String.t() | nil,
  mutated_form: atom() | nil,
  mutator: atom(),
  note: String.t() | nil,
  operation: :replace | :delete,
  original_code: String.t() | nil,
  original_form: atom() | nil,
  poisoned: boolean(),
  range: Sourceror.Range.t() | nil,
  summary: String.t() | nil,
  variant: [String.t()]
}

Functions

clause_drop(id, file, range, clause_node, opts \\ [])

@spec clause_drop(
  pos_integer(),
  String.t(),
  Sourceror.Range.t(),
  Macro.t(),
  keyword()
) :: t()

Builds a lifted deletion site for a function clause.

The site is recorded under the clause_drop family. :render? defaults to true; :summary? defaults to false.

describe(site)

@spec describe(t()) :: String.t()

Returns a one-line description of a site.

iex> Mutare.Site.describe(%Mutare.Site{
...>   mutator: :relational,
...>   operation: :replace,
...>   original_code: "a >= b",
...>   mutated_code: "a > b"
...> })
"relational  a >= b → a > b"

iex> Mutare.Site.describe(%Mutare.Site{
...>   mutator: :clause_drop,
...>   operation: :delete,
...>   original_code: "def f(_), do: :ok"
...> })
"clause_drop  (drop) def f(_), do: :ok"

in_place(id, file, range, original_node, mutated_node, mutator, opts \\ [])

@spec in_place(
  pos_integer(),
  String.t(),
  Sourceror.Range.t(),
  Macro.t(),
  Macro.t(),
  Mutare.Mutator.Spec.t(),
  keyword()
) :: t()

Builds a site for a node replacement delivered by an in-place selector.

range identifies the original node. The recorded family name comes from mutator.

Options:

:note — advisory text shown in reports
:variant — one or more ignore labels; when absent, the mutator callback derives the variant
:render? — render original_code and mutated_code immediately; defaults to true
:summary? — build the lightweight live-progress summary; defaults to false

in_place_drop(id, file, range, clause_node, mutator, opts \\ [])

@spec in_place_drop(
  pos_integer(),
  String.t(),
  Sourceror.Range.t(),
  Macro.t(),
  Mutare.Mutator.Spec.t(),
  keyword()
) :: t()

Builds an in-place deletion site for a rescue clause.

mutator supplies the recorded family name. The deleted clause has no mutated AST or replacement code.

lifted_replace(id, file, range, original_node, mutated_node, mutator, opts \\ [])

@spec lifted_replace(
  pos_integer(),
  String.t(),
  Sourceror.Range.t(),
  Macro.t(),
  Macro.t(),
  Mutare.Mutator.Spec.t(),
  keyword()
) :: t()

Builds a site for a node replacement delivered through function lifting.

Lifted delivery is used where an in-place selector is not legal, including guards and clause-head patterns. The site records kind: :lifted. Options are the same as for in_place/7.

return_value(id, file, range, original_node, mutated_node, mutator, opts \\ [])

@spec return_value(
  pos_integer(),
  String.t(),
  Sourceror.Range.t(),
  Macro.t(),
  Macro.t(),
  Mutare.Mutator.Spec.t(),
  keyword()
) :: t()

Builds an in-place site for a return-expression replacement.

The recorded family name comes from mutator. :render? controls immediate source rendering and defaults to true; :summary? controls the live-progress summary and defaults to false.

summary_line(site)

@spec summary_line(t()) :: String.t()

Returns the live-progress description for a site.

Uses the lightweight summary when present and otherwise falls back to describe/1.