Astgrep
Structural code search and rewrite with ast-grep (tree-sitter AST patterns). NOT for type-aware refactors (use the LSP/language skill) or literal search (use ripgrep). NOT for SQL — no built-in grammar.From its SKILL.md
npx -y skills add kronael/tools --skill astgrepAssembled from the repository path, not quoted from the project. Check it against their README if it does not work.
One thing to look at
- 6 stars6 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.
SKILL.md
5.4 KB, as published. Nobody here has run it
astgrep — structural search & rewrite
Search and rewrite code by its tree-sitter AST, not text. A pattern is real
code with meta-variables; matches respect nesting and skip strings/comments.
Methodology + citations: docs/astgrep/research-astgrep.md.
ALWAYS invoke the binary as ast-grep. NEVER rely on sg — it collides with
shadow-utils' /usr/bin/sg; uv tool upgrade ast-grep-cli recreates the shim.
When to invoke / NOT
- USE for: "every
console.logcall regardless of args", multi-line constructs, a codemod across many files, AST-kind/structure queries. - NOT for semantic edits (scope-aware rename, follow imports, resolve overloads) — ast-grep has no types or cross-file symbol table; use the LSP.
- NOT for a trivial literal string — ripgrep is faster.
- Built-in languages here:
go rust python typescript tsx bash. Usetsx(notts) for any file with JSX. SQL is NOT built in — it needs a compiled tree-sitter grammar undercustomLanguagesinsgconfig.yml(a build step, plusexpandoCharsince$VARisn't valid SQL). Don't pretend-l sqlworks.
Commands
ast-grep run — ad-hoc, pattern-driven. ast-grep scan — runs YAML rules.
# search
ast-grep run -p 'console.log($MSG)' -l ts src/
# rewrite: ALWAYS preview (no -U) first, eyeball the diff, then apply
ast-grep run -p 'print($A)' -r 'logging.info($A)' -l py .
ast-grep run -p 'print($A)' -r 'logging.info($A)' -l py -U . # applies
# rule-based (maintained codemods/lints)
ast-grep scan -r rule.yml --globs '!**/vendor/**' .
Useful flags: -i interactive confirm, -U/--update-all apply all,
--json[=stream] machine output, --debug-query[=ast] show how a pattern
parsed (reach for this the moment a pattern "should match but doesn't").
Pattern syntax
$VAR— exactly one named node. Uppercase/digits/underscore only.$$$/$$$ARGS— zero or more nodes (args, params, statements).$_(or$_X) — single node, not captured.- Reusing a name forces equality:
$A == $Amatchesa == a, nota == b. $$VAR— matches unnamed nodes (operators) that$VARskips.
ALWAYS write a pattern that is syntactically valid code in the target
language — $LEFT $OP $RIGHT and dangling fragments silently fail to match.
For ambiguous or fragment patterns, use a pattern object instead of a bare
string: context: (a larger valid snippet) + selector: (the node kind to
return), or match by kind: directly.
Rewrite safety — the iron rules
A bare run -p/-r over-matches by construction. Codex-verified failures
(see docs/astgrep/codex-critique.md):
console.log($$$) -> ''wrecks expressions:() => console.log(a)becomes() =>. Delete log statements only via a scan rule withinside: { kind: expression_statement }.$E.unwrap() -> $E?fires inlet x = value.unwrap();→ invalid Rust.<Old $$$P />matches only self-closing JSX, never elements with children.
Therefore:
- ALWAYS preview without
-U(or use-i) on a clean git tree first.-Uis destructive with no undo. - ALWAYS scope a real rewrite with
inside/has/kindin ascanYAML rule rather than a broadrun -rone-liner. - ALWAYS run the formatter after (
gofmt/rustfmt/prettier/ruff format). ast-grep substitutes nodes; it does not reformat or fix indentation. - ast-grep has no types — review every hunk a rewrite produces.
YAML rules
id: no-console-log
language: TypeScript
rule:
pattern: console.log($$$A)
inside: { kind: expression_statement }
fix: ''
- Atomic:
pattern,kind,regex(Rust regex — no look-around or backrefs),nthChild,range. - Relational:
inside,has,follows,precedes, each withstopBy(neighbordefault |end| a rule). - Composite:
all,any,not,matches(reference autilsrule). constraints(per meta-var sub-rules),transform(derive vars beforefix),rewriters(recursive sub-rewrites).
Project config sgconfig.yml: ruleDirs, utilDirs, testConfigs,
languageGlobs, customLanguages. scan discovers rules from ruleDirs.
Test rules with ast-grep test (valid: must not match, invalid: must).
Strictness
Default smart skips "trivial" nodes in the target — surprising over-matches
(a dropped async/quote style) mean tighten toward ast or cst. Levels
strict→loose: cst, smart, ast, relaxed, signature, template.
Anti-patterns
- Broad
run -rcodemod applied with-Uunreviewed — corrupts expression contexts and unscoped matches. - Bare pattern for ambiguous code (
a: 123) — usecontext+selector/kind. - Trusting auto-detect on JSX — pass
-l tsxexplicitly. - Skipping the formatter pass — leaves mis-indented output.
- Claiming SQL works — it needs a custom grammar build first.
Reference
docs/astgrep/research-astgrep.md (cited methodology),
docs/astgrep/codex-critique.md (empirical breakage), ast-grep.github.io.