@callback extract_children(native_ast()) :: [native_ast()]

Extract children from a language-specific AST node.

Given a language-specific AST node (M1), return a list of its child nodes that should be traversed during analysis.

This is used by analyzers that need to traverse language-specific nodes embedded in :language_specific MetaAST nodes.

Default Implementation

If not implemented, the runner will use a generic fallback that attempts to extract children based on common AST patterns.

Examples

# Elixir adapter
extract_children({:defmodule, _meta, [_name, [do: body]]})
# => [body]

# Python adapter  
extract_children(%{"_type" => "FunctionDef", "body" => statements})
# => statements

@callback file_extensions() :: [String.t()]

Return the file extensions this adapter handles.

Used for automatic language detection.

Examples

# Python adapter
file_extensions()
# => [".py"]

# JavaScript/TypeScript adapter
file_extensions()
# => [".js", ".jsx", ".ts", ".tsx"]

@callback from_meta(meta_ast(), metadata()) ::
  {:ok, native_ast()} | {:error, reason :: term()}

Transform MetaAST back to native AST (M2 → M1 reification).

This is the reification operation that instantiates the meta-model (M2) into a concrete language AST (M1).

Uses metadata to restore M1-specific information that was preserved during abstraction (e.g., formatting, type annotations, etc.).

Conformance Validation

Implementation must ensure the resulting M1 AST:

1. Is valid for the target language
2. Preserves the semantics of the M2 instance
3. Can be round-tripped (M1 → M2 → M1 ≈ M1)

Examples

# MetaAST to Python BinOp
from_meta(
  {:binary_op, :arithmetic, :+, {:variable, "x"}, {:literal, :integer, 5}},
  %{native_lang: :python}
)
# => {:ok, %{"_type" => "BinOp", "op" => %{"_type" => "Add"}, ...}}

@callback parse(source()) :: {:ok, native_ast()} | {:error, reason :: term()}

Parse source code to native AST (Source → M1).

This is a language-specific operation that produces the M1 representation.

Implementation Notes

• May spawn external processes (Python, Node.js, etc.)
• May use native Elixir parsing (for Elixir adapter)
• Should validate syntax and return clear error messages

Examples

# Python adapter
parse("x + 5")
# => {:ok, %{"_type" => "BinOp", "op" => %{"_type" => "Add"}, ...}}

# JavaScript adapter
parse("x + 5")
# => {:ok, %{"type" => "BinaryExpression", "operator" => "+", ...}}

@callback to_meta(native_ast()) ::
  {:ok, meta_ast(), metadata()} | {:error, reason :: term()}

Transform native AST to MetaAST (M1 → M2 abstraction).

This is the abstraction operation that lifts language-specific AST (M1) to the meta-level (M2).

Semantic Equivalence

Different M1 models may map to the same M2 instance:

• Python: BinOp(op=Add) → {:binary_op, :arithmetic, :+, ...}
• JavaScript: BinaryExpression(operator: '+') → same M2 instance
• Elixir: {:+, [], [...]} → same M2 instance

Return Value

Returns a tuple of {meta_ast, metadata} where:

• meta_ast is the M2 representation
• metadata preserves M1-specific information for round-tripping

Examples

# Python BinOp to MetaAST
to_meta(%{"_type" => "BinOp", "op" => %{"_type" => "Add"}, ...})
# => {:ok,
#     {:binary_op, :arithmetic, :+, {:variable, "x"}, {:literal, :integer, 5}},
#     %{native_lang: :python, ...}}

@callback unparse(native_ast()) :: {:ok, source()} | {:error, reason :: term()}

Convert native AST back to source code (M1 → Source).

This is the final step in the M2 → M1 → Source pipeline.

Implementation Notes

• May use language-specific unparsers/pretty-printers
• Should attempt to preserve formatting where possible
• May normalize formatting to language conventions

Examples

# Python AST to source
unparse(%{"_type" => "BinOp", ...})
# => {:ok, "x + 5"}

@callback validate_mutation(meta_ast(), metadata()) ::
  :ok | {:error, validation_error :: String.t()}

Validate that an M2 transformation produces valid M1.

After a mutation at M2 level, validate that the result:

1. Conforms to M2 meta-model structurally
2. Can be instantiated in this language (M1 conformance)
3. Satisfies language-specific constraints

Examples

• Rust: Reject mutations that violate ownership/borrowing
• TypeScript: Reject mutations that violate type constraints
• Python: Most mutations valid (dynamic typing)

This is M2 → M1 semantic conformance validation.

Default Implementation

If not implemented, assumes all M2-valid transformations are M1-valid.