ex-ast-refactor

name

ex-ast-refactor

description

Search, analyze, and refactor Elixir code with `ex_ast` AST patterns in projects that already depend on `ex_ast`. Use only when syntax-aware matching, captures, pipe normalization, ancestor/child/sibling filters, multi-pattern scans, or dry-run AST replacements provide a clear benefit over regular grep/search and manual patches. Do not use for simple literal text searches or in projects that do not already contain `ex_ast`.

ExAST Refactor

Overview

Use ex_ast for Elixir refactors and investigations where AST structure matters: call shape, function context, matched captures, equivalent piped/direct calls, or safe batch replacements. Keep normal Glob/Grep/apply_patch as the default for simple text edits.

Activation Gate

1. Confirm the project already has ex_ast before using it. Check mix.exs, mix.lock, or available mix tasks. Do not add ex_ast just to use this skill unless the user explicitly asks.
2. Use this skill only when AST semantics reduce risk or effort. Prefer plain Grep and patches for exact strings, one-off edits, documentation, config text, or non-Elixir files.
3. Prefer the CLI for quick searches and mechanical dry-run replacements. Prefer mix run -e or a scratch Elixir script when queries need ExAST.Query, capture guards, custom output, or multi-pattern analysis.
4. Always preview broad or write operations before modifying files.

Core Workflow

1. Define the code shape in normal Elixir syntax. Use wildcards, captures, ellipsis, or relationship filters only when needed.
2. Run a limited search first, for example mix ex_ast.search --limit 20 'IO.inspect(...)' lib/.
3. Inspect representative matches and refine the pattern. Use --inside, --not-inside, --contains, or a query when context matters.
4. For replacements, run mix ex_ast.replace --dry-run 'PATTERN' 'REPLACEMENT' PATH first.
5. Apply the replacement only after the dry run matches the intended scope.
6. Run mix format or the repository formatting task after replacements because generated formatting may differ.
7. Verify with targeted tests, compile, or the repository's check task.

Common Commands

mix ex_ast.search 'PATTERN' PATH
mix ex_ast.search --limit 20 --inside 'defp _ do ... end' 'Repo.get!(_, _)' lib/
mix ex_ast.replace --dry-run 'PATTERN' 'REPLACEMENT' PATH
mix ex_ast.replace 'dbg(expr)' 'expr' lib/
mix ex_ast.diff lib/old.ex lib/new.ex --summary

Reference Files

• Read Pattern Language when designing or debugging ex_ast patterns.
• Read Querying, CLI, and API when context filters, capture guards, programmatic searches, or command options are needed.
• Read Safe Refactoring Workflow before making project-wide replacements or when deciding whether ex_ast is justified.

Guardrails

• Avoid broad patterns like _ unless using --limit or --allow-broad intentionally.
• Treat generated replacements as code changes, not text substitutions. Review the diff before finalizing.
• Do not rely on semantic alias expansion or macro expansion. ex_ast is syntax-aware, not a compiler.
• Captured remote or field access can render differently in replacements, such as record.field() instead of record.field. Review and clean up generated code.
• Replacement formatting may use Macro.to_string/1; run the project formatter afterward.
• Use apply_patch for manual cleanup around generated changes when the AST replacement is too broad or awkward.