cxc-ast-grep

# ast-grep `sg` (also installed as `ast-grep`) is an **AST-aware search and rewrite tool** across 25 languages. It treats your pattern as code, parses it the same way it parses your project, and matches structurally. Reach for it whenever the question depends on **code shape** rather than text bytes. This skill ships a Python wrapper at `scripts/ast_grep_helper.py` and an install reference at `references/install.md`. The helper adds offline pattern validation, the two-pass write trick, and binary auto-resolution. Use it as the default entry point. ## rg first — do not use ast-grep for ordinary grep Plain filename, literal text, regex, comment, and simple callsite searches use `rg` / `rg --files` first. ast-grep is for syntax-tree questions only. The test: "does the answer depend on the language's syntax tree, or just on the file's bytes?" Tree → ast-grep. Bytes → `rg`. For a whole-repo structure OVERVIEW (which files own which symbols, ranked), use `cxc map` (repo-map skill) instead; ast-grep is for shape SEARCH within known scope. ## When to use this skill - "Find every function that takes a `Request` parameter." - "Rewrite every `console.log(x)` to `logger.info(x)`." - "Strip every `as any` cast." - "Replace `require(...)` with `import` across the repo." - "Find empty catch blocks" / "find missing `await`." - "Apply this codemod across these 200 files." - "Run our YAML lint rules and surface violations." ## Three things to internalize ### 1. ast-grep is NOT regex The wildcards are `$VAR` (one AST node) and `$$$` (zero or more nodes). Regex syntax (`|`, `.*`, `\w`, `[a-z]`) fails silently — the helper's `validate` subcommand catches the common misuses offline before you run a search. ### 2. Always preview before you write `replace` is a dry-run by default and prints the would-change diff. Add `--apply` only after you have inspected the preview. The helper runs a two-pass write (JSON match pass, then a separate `--update-all` pass) because ast-grep ignores `--update-all` when `--json` is set. ### 3. Language matters Pass `--lang` so the correct parser is used; the same pattern parses differently across languages. `langs` lists the 25 supported languages with extensions. ## Verification loop (MUST) Never trust a pattern you have not seen match. The loop: 1. `validate PATTERN --lang LANG` — offline sanity check (catches regex syntax and other common misuses; it can NOT catch every silent miss — see step 3). 2. `search PATTERN --lang LANG` — read the match list: is the COUNT plausible, and do 2-3 spot-checked sites look right? 3. **0 matches where you expected some = pattern bug first**, not "no occurrences". The two reproduced causes: a glued metavariable (`use$HOOK(...)` — a metavar must be a whole token) and a pattern that does not parse as ONE node (`catch ($E) {}`). Consult `references/patterns.md` (verified examples + pitfalls) and refine. 4. `replace PATTERN REWRITE` — inspect the dry-run diff for every file, or at minimum every distinct shape in it. 5. Only then `--apply`. Never `--apply` a pattern whose match list you have not read. ## Helper usage ``` ast_grep_helper.py search PATTERN [PATH...] [--lang LANG] [--globs GLOB ...] [-C N] ast_grep_helper.py replace PATTERN REWRITE [PATH...] [--lang LANG] [--apply] ast_grep_helper.py scan [PATH...] --rule RULE_FILE [--apply] # rule file via --rule, NOT positional ast_grep_helper.py validate PATTERN [--lang LANG] # offline pattern check ast_grep_helper.py langs # list languages ast_grep_helper.py doctor # binary availability + version ast_grep_helper.py install # lazy-provision sg ``` Verified per-language pattern examples (call rewrite, cast strip, CJS→ESM, empty catch, bare except, relational YAML rules) and the reproduced pitfall table live in `references/patterns.md` — read it before writing a non-trivial pattern. ## Binary resolution + lazy provisioning The helper resolves `sg` in priority order: `CODEXCLAW_AST_GREP_SG_PATH` override (`OMO_AST_GREP_SG_PATH` fallback) → codexclaw runtime (`$CODEX_HOME/runtime/ast-grep` or `~/.codexclaw/runtime/ast-grep`) → a cached binary under the skill `bin/` → `PATH` → Homebrew defaults. When `sg` is missing, `doctor`/`install` exit with a clear install hint rather than crashing. See `references/install.md`. Provisioning is lazy, evidence-bound, and idempotent. ## Notes - On-demand skill (`allow_implicit_invocation: false`); reached by trigger or `dev`-hub routing. - No MCP server, no daemon, no workspace side-effects — this honors the core no-server contract. LSP and codegraph are deferred to a separate, isolated post-MVP extension and are deliberately not shipped here.