MutagenEx.Ast (mutagen_ex v0.2.0)

Copy Markdown View Source

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

Types

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.

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

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

Types

ast()

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

An Elixir Macro AST node.

Functions

alias_to_module(mod)

@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(ast, target_mod_str)

@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(arg1)

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