ast-grep
AST-aware structural code search and rewrite via ast-grep.
- License 许可
- MIT
- 最近更新
- 2026-11-13
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- ast-grep
- author
- Yeongyu Kim (code-yeongyu), adapted by Hermes Agent, ported for CrusorAI
- license
- MIT
- version
- 1.1.0
- metadata
- { "hermes": { "tags": [ "ast", "codemod", "refactoring", "structural-search", "code-search", "rewrite", "tree-sitter" ], "related_skills": [ "simplify-code", "systematic-debugging" ] } }
- platforms
- [ "linux", "macos", "windows" ]
- description
- AST-aware structural code search and rewrite via ast-grep.
03 SKILL.md 正文
Triggers: ast-grep, ast grep, codemod, structural search, structural replace, rewrite all, rewrite every, find all functions, every call site, code shape, sg run
ast-grep
ast-grep (binary sg; on Linux prefer ast-grep — sg collides with setgroups) is an AST-aware search and rewrite tool across ~25 languages. It parses your pattern as code and matches structurally. Right tool whenever the question depends on code shape, not text bytes. Install: run_terminal("npm i -g @ast-grep/cli") or cargo install ast-grep / pip install ast-grep-py. Check with sg --version.
When to use (vs search_files)
- "Find every function that takes a
Requestparameter." → ast-grep - "Rewrite every
console.log(x)tologger.info(x)." → ast-grep - "Migrate
Optional[X]toX | None." / "Strip everyas any." → ast-grep - String contents, comments, file names, cross-language regex →
search_files/rg
Ask: "does the answer depend on the syntax tree, or just the file's bytes?"
Three things to internalize
1. ast-grep is NOT regex
Wildcards are $VAR (one AST node) and $$$ (zero or more nodes). Regex syntax fails silently: foo|bar, .*foo, \w+, [a-z] are NOT patterns — run two searches, use $VAR, or switch to search_files.
2. Patterns must be valid code
def $FN($$$): fails (trailing : incomplete) → def $FN($$$): $$$ with a body or def $FN($$$) for signature matching. function $NAME fails → function $NAME($$$) { $$$ }.
3. --update-all and --json are mutually exclusive (silently)
To preview AND apply, run two passes:
sg run -p 'PATTERN' -r 'REWRITE' --json=compact . # pass 1: preview
sg run -p 'PATTERN' -r 'REWRITE' --update-all . # pass 2: apply
Core commands (through run_terminal, single-quote every pattern)
# Search
sg run -p 'console.log($MSG)' --lang ts src/
# Search with JSON for scripting
sg run -p 'console.log($MSG)' --lang ts --json=compact src/
# Rewrite — ALWAYS dry-run first
sg run -p 'console.log($MSG)' -r 'logger.info($MSG)' --lang ts --json=compact src/
# Then apply, then review blast radius
sg run -p 'console.log($MSG)' -r 'logger.info($MSG)' --lang ts --update-all src/
git diff --stat
# YAML lint rules (reusable rules in sgconfig.yml)
sg scan src/
--lang is required when piping via --stdin (no extension to infer). Use tsx for .tsx files — --lang ts will not parse JSX.
Rewriting discipline
- Search to confirm matches. 2. Dry-run rewrite (
--json=compact). 3. Inspect: match count, files affected, per-location preview. 4. Wrong → refine, go to 1. 5. Right →--update-all, thengit diff --statbefore finishing. Report the number of files affected, not just matches — users care about blast radius. In Crusor, bulk rewrites are a mutation: surface the dry-run summary and get approval before--update-allwhen the mutation gate asks.
0 matches but the code is there?
- Check the pattern for regex leakage (
\w,.*,|) - Check
--lang(ts vs tsx) - Debug-parse:
echo '<sample>' | sg run -p '<pattern>' --lang ts --debug-query=ast --stdin—ERRORnodes mean a malformed pattern - Inspect the target AST:
sg run -p '$_' --lang ts --debug-query=cst file.ts | head -40to find the kind to match
Inline pattern vs YAML rules
Inline -p for one-off, simple, exploratory queries. YAML rules (under rules/, sg scan) for reused lint rules, constraints/transforms, auto-fix, snapshot tests.
04 同仓库更多 Skills
interaction-patterns-architect
Architect-level interaction design in code — choosing established patterns over invented ones, feedback and latency behaviour, destructive-action safeguards, navigation and overlay conventions, and the state model behind every interactive surface. Use when a screen has to behave, not just look.
design-system-ops-architect
Architect-level operation of a design system in code — token pipelines and versioning, component API and variant policy, the catalogue as the contract, adoption metrics, and the governance that stops a system from forking into three. Use when a component library must survive several teams.
design-handoff-architect
Architect-level design handoff — what must be specified before implementation starts, tokens over raw values, responsive and content-limit contracts, state matrices, and the review loop that catches drift between design and code. Use when a design is about to become code.
content-microcopy-architect
Architect-level UI content — where strings live, voice and terminology consistency, error and empty-state copy as part of the interface, translation-ready authoring, and the content model a product needs before it multiplies screens. Use when the words in the interface matter as much as the pixels.
ui-ux-implementation-architect
Architect-level direction for turning a design into working UI — the handoff contract, component ownership versus screen-level layout, interaction and state conventions, design QA gates, and the review habits that keep an implementation faithful without frozen pixels. Use before any specific UI implementation skill.
test-strategy-architect
Architect-level test strategy — allocating assertions across unit, integration, contract and end-to-end layers, designing for testability through dependency boundaries, fixture and data strategy, and the flake and coverage policies that keep a suite trustworthy. Use when defining how a codebase is tested.