ast-grep

ast-grep

Structural code search and rewrite: a pattern is real code with meta-variables, matched against the syntax tree. A call-expression pattern distinguishes a call from similar text inside a string or comment; string and comment nodes can also be matched deliberately. Use it where rg gives false positives; plain text search stays with rg.

Commands

ast-grep outline -l python src/                                                 # symbols, imports, and members per file
ast-grep run -p 'print($$$ARGS)' -l python src/                                      # scope search to the relevant source
ast-grep run -p 'print($$$ARGS)' -r 'logger.info($$$ARGS)' -l python src/             # dry run: prints the diff, changes nothing
ast-grep run -p 'print($$$ARGS)' -r 'logger.info($$$ARGS)' -l python --update-all src/ # apply after reviewing the dry run (-i to confirm per hunk)
ast-grep run -p 'os.getenv($KEY)' -l python --json=compact src/                       # structured output after narrowing paths
ast-grep scan                                                                    # every rule in sgconfig.yml
ast-grep scan -r rules/no-print.yml --format github                              # one rule file; GitHub annotations in CI

Workflow

1. Write the pattern as code: $NAME matches one node, $$$NAME a sequence (arguments, statements), $_ a node without binding; always pass -l <lang> so the pattern parses in the right grammar, and use --debug-query=ast when a pattern that should match does not.
2. Search first: map unfamiliar files with ast-grep outline before reading full source; pass the relevant path or --globs; use --files-with-matches when only filenames are needed, then read selected matches with -C 2. Use JSON only for structured processing. Widen scope deliberately, and use --no-ignore vcs (or hidden; the flag requires a value) only when skipped files are relevant.
3. Rewrite in two steps: add -r to see the diff, then --update-all (or -i for an interactive session); captured meta-variables are reused in the replacement.
4. Promote to a rule: for a lint or a repeated refactor, ast-grep new project scaffolds sgconfig.yml and rules/; a rule file has id, language, rule (pattern, kind, inside, has, not), optional fix, severity, and message; ast-grep test runs its valid and invalid cases.
5. Wire into the gate: run ast-grep scan inside check:lint (see mise) so hooks and CI apply the same rules.