# `Mutare.Site`
[🔗](https://github.com/foxbenjaminfox/mutare/blob/v0.2.1/lib/mutare/site.ex#L1)

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.

`id` is the run's report number. Schema builds also record `runtime_id` as
`{root_relative_file, local_id}`; standalone transforms leave it `nil`, using
`id` for selection too. `Mutare.RuntimeId` implements the boundary conversions. The
public `Mutare.MutationSite` DTO and every reporter retain integer report ids.

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.

# `t`

```elixir
@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,
  runtime_id: Mutare.RuntimeId.t() | nil,
  summary: String.t() | nil,
  variant: [String.t()]
}
```

# `clause_drop`

```elixir
@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`

```elixir
@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`

```elixir
@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`

```elixir
@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`

```elixir
@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`

```elixir
@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`

```elixir
@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`.

---

*Consult [api-reference.md](api-reference.md) for complete listing*