ast-grep

# ast-grep ## Contract | Field | Bound contract | |---|---| | Trigger | AST-based modification, structural search, lint, or replacement too fragile for regex. | | Authority | Reversible local: writes only VCS-tracked source files (search is read-only; rewrites apply only through the helper after dry-run review); rollback is version control. No remote mutation. | | Side effect | Local file writes through the helper two-pass validate/dry-run/apply flow; no remote, credential, or published mutation. | | Done | Pattern validated and blast radius reviewed; any rewrite landed at the correct scope (search/lint-only runs are valid). | ## Inputs - An ast-grep pattern, single-quoted in the shell so `$VAR` reaches ast-grep unexpanded. - A language (`--lang`) or a single target path whose extension auto-detects it; required for stdin patterns. - For rewrites: a rewrite template and one or more target paths (defaults to the current directory). - Optional: include/exclude globs (repeatable, prefix `!` to exclude), context lines, JSON output mode. ## Procedure 1. Confirm the task is structural (call, function, class, or import shaped like a pattern), not text/regex/filename matching (use grep) or semantic type/reference lookup (use LSP or the compiler). ast-grep matches syntax, not bytes. Done when: the task is confirmed structural. 2. Validate the pattern before searching: `python3 scripts/ast_grep_helper.py validate '<pattern>' --lang <L>`. Exit 0 means ast-grep parses it cleanly; e...