# `MutagenEx.Ast`
[🔗](https://github.com/iautom8things/mutagen_ex/blob/v0.2.0/lib/mutagen_ex/ast.ex#L1)

Canonical shared AST helpers for the mutagen pipeline.

Resolves source module and definition names and extracts
positions for the scope resolver, enumerator, and runner.

Implements the behavioural contract in
[`mutagen.ast`](https://github.com/iautom8things/mutagen_ex/blob/main/.spec/specs/ast.spec.md).

## Atom safety

`find_module_body/2` accepts a `target_mod_str` (a string, NEVER an
atom built from user input). Module matching is performed via string
comparison: `Atom.to_string/1` of each AST-derived module atom is
compared against `target_mod_str` (with the leading `"Elixir."`
prefix stripped from the AST atom's string form). This preserves the
atom-table-bound invariant from `mutagen.scope_resolution.r8`
(mutagen-wrd.20) — no `String.to_atom/1` is ever applied to caller
input.

The previous donor `find_module_body/2` variants in
`MutationEnumerator` and `MutationRunner` accepted a module **atom**
and matched via `^target_mod`. Those donors only ever passed atoms
that already came from the AST (via `ScopeResolver` results), so the
atom-table-DOS contract was already satisfied at the call sites. The
lifted contract switches the input type to `String.t()` to make the
safety boundary explicit at the function signature itself — callers
that hold an atom-typed module pass `Atom.to_string/1` of it (still
safe because the atom came from the AST).

# `ast`

```elixir
@type ast() :: Macro.t()
```

An Elixir Macro AST node.

# `alias_to_module`

```elixir
@spec alias_to_module(ast()) :: module() | nil
```

Convert an `:__aliases__` AST tuple or bare module atom to a module
atom. Returns `nil` for any other shape.

Total: never raises, throws, or exits. Per `mutagen.ast.r1`.

## Shapes accepted

  * `{:__aliases__, _meta, parts}` where every element of `parts` is
    an atom — returns `Module.concat(parts)`. Note: this calls
    `Module.concat/1`, which CAN create a new atom in the atom table
    (the materialized module atom). This is safe in mutagen's use
    because the parts list comes from AST already parsed from
    project source — never directly from caller input. Same trust
    boundary as the pre-`.25` donor implementations.

  * A bare module atom (e.g. `Foo.Bar`) — returned unchanged.

## Shapes that return `nil`

  * Aliases whose `parts` list contains a non-atom element (e.g.
    `{:__aliases__, _, [{:meta, _, _}, :Foo]}` — a dynamic alias).

  * Any other non-atom, non-alias input (integer, string, list,
    tuple of any other shape).

# `find_module_body`

```elixir
@spec find_module_body(ast(), String.t()) :: {:ok, ast()} | :not_found
```

Locate the body AST for `defmodule <target> do ... end` inside `ast`.

Returns `{:ok, body_ast}` if any `:defmodule` node in `ast` matches
the supplied `target_mod_str` (a string). The match is performed via
`Atom.to_string/1` of each AST-derived module atom, with the
`"Elixir."` prefix stripped — so `"Foo.Bar"` matches
`defmodule Foo.Bar do ... end` whose AST module atom is `Foo.Bar`.

Returns `:not_found` if no matching `defmodule` exists.

Total: never raises, throws, or exits. Per `mutagen.ast.r2`.

## Atom safety

`target_mod_str` is a string. This function NEVER passes it through
`String.to_atom/1`. Callers that hold a module atom (e.g. from a
`%MutagenEx.ScopeResolver.Scope{}` record) should pass
`Atom.to_string/1` of it — the atom came from the AST, so its string
form round-trips through `==` correctly. See module doc for the
atom-table-DOS context.

Returns the first unquoted declaration in depth-first source order.
Named protocols and statically resolvable implementations participate.

# `node_line`

```elixir
@spec node_line(ast()) :: integer() | nil
```

Extract the `:line` value from a Macro AST node's metadata.

Returns the integer line number if the node is a 3-tuple `{form,
meta, args}` where `meta` is a keyword list carrying `:line`.
Returns `nil` for any other shape (bare literals, 2-tuples, lists,
or 3-tuples whose meta lacks `:line`).

Total: never raises, throws, or exits. Per `mutagen.ast.r3`.

---

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