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.
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).
Summary
Functions
Convert an :__aliases__ AST tuple or bare module atom to a module
atom. Returns nil for any other shape.
Locate the body AST for defmodule <target> do ... end inside ast.
Extract the :line value from a Macro AST node's metadata.
Types
@type ast() :: Macro.t()
An Elixir Macro AST node.
Functions
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 ofpartsis an atom — returnsModule.concat(parts). Note: this callsModule.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-.25donor implementations.A bare module atom (e.g.
Foo.Bar) — returned unchanged.
Shapes that return nil
Aliases whose
partslist 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).
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.
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.