lidge-jun/codexclaw / plugins/codexclaw/skills/ast-grep
cxc-ast-grep
VerifiedUse for AST search and codemods. Triggers: ast-grep, sg, function/call/class/import, empty catch, missing await, YAML rules.
| File | Kind | Size |
|---|---|---|
| LICENSE | other | 1.0 KB |
| SKILL.md | skill md | 5.0 KB |
| agents/openai.yaml | config | 152 B |
| references/install.md | markdown | 1.5 KB |
| references/patterns.md | markdown | 3.4 KB |
| scripts/ast_grep_helper.pyexecutable | script | 26.6 KB |
references/patterns.md
View on GitHub# Verified ast-grep patterns
Every pattern and pitfall below was EXECUTED against fixture files with the shipped
helper (`scripts/ast_grep_helper.py`) — not transcribed from docs. Re-verify after a
major ast-grep upgrade (see Sources footer).
## TypeScript / JavaScript (`--lang ts`)
| Intent | Command | Verified result |
| --- | --- | --- |
| Find call sites | `search 'console.log($$$ARGS)'` | matches `console.log("boot", total)`; does NOT match `console.warn` (exact callee) |
| Rewrite calls | `replace 'console.log($$$ARGS)' 'logger.info($$$ARGS)'` | preview `-> logger.info("boot", total)`; args carried over via `$$$ARGS` |
| Strip casts | `search '$X as any'` | matches `cfg as any` |
| Empty catch | `search 'try { $$$BODY } catch ($E) {}'` | matches — see Pitfall 1 for why bare `catch ($E) {}` fails |
| CJS → ESM | `replace 'const $V = require($M)' 'import $V from $M'` | `const legacy = require("./legacy")` → `import legacy from "./legacy"` |
## Python (`--lang python`)
| Intent | Command | Verified result |
| --- | --- | --- |
| print → logging | `replace 'print($$$ARGS)' 'logging.info($$$ARGS)'` | rewrote both call sites, nested call args preserved |
| Bare except | inline pattern FAILS (Pitfall 1) — use a YAML rule on `kind: except_clause` | `except: $$$BODY` errors with "Multiple AST nodes" |
## YAML relational rule (scan)
Find `fetch()` calls whose result is not awaited:
```yaml
id: unawaited-fetch
language: TypeScript
severity: warning
message: fetch() result is not awaited
rule:
pattern: fetch($$$ARGS)
not:
inside:
kind: await_expression
```
```
ast_grep_helper.py scan <PATH> --rule unawaited-fetch.yml --report-style short
```
Verified: flags `const res = fetch(...)`, correctly skips `await fetch("/health")`.
NOTE: the rule file goes in `--rule`; a bare positional YAML path is treated as a scan
target and sg demands a project config ("No ast-grep project configuration is found").
## Pitfalls (all reproduced live)
1. **A pattern must parse as ONE node.** `catch ($E) {}` and `except: $$$BODY` both
fail with `Multiple AST nodes are detected`. Fix: wrap in enough context to form a
single statement (`try { $$$BODY } catch ($E) {}`) or switch to a YAML `kind:` rule.
2. **Regex syntax fails.** `console\.(log|warn)` — the helper's `validate` flags the
`|` alternation with a hint. Run one call per alternative; there is no regex in
patterns.
3. **Glued metavariables miss SILENTLY.** `use$HOOK($$$A)` passes `validate` (it is
syntactically plausible) but returns **0 matches** on a file containing
`useState(0)`. A metavariable must be the WHOLE token: match `$HOOK($$$A)` and
filter names afterwards, or use a YAML rule with a `regex` constraint on the
metavariable. Treat "0 matches where you expected some" as a pattern bug first.
4. **`--lang` decides the parser.** The same pattern text parses differently (or not
at all) across languages; fixtures in another language are simply not scanned.
## Sources / verification
| What | Evidence |
| --- | --- |
| All rows above | Executed 2026-07-02 against scratch fixtures (`sample.ts`, `sample.py`, `unawaited.yml`), ast-grep 0.44.0 (Homebrew), helper v0.1.0 |
| LLMs mis-write ast-grep patterns (why this file exists) | https://ast-grep.github.io/blog/more-llm-support.html (checked 2026-07-02) |
| Pattern syntax reference | https://ast-grep.github.io/guide/pattern-syntax.html (checked 2026-07-02) |
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementation | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirements | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |