AGENT SKILL

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 Request parameter." → ast-grep
  • "Rewrite every console.log(x) to logger.info(x)." → ast-grep
  • "Migrate Optional[X] to X | None." / "Strip every as 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

  1. 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, then git diff --stat before 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-all when the mutation gate asks.

0 matches but the code is there?

  1. Check the pattern for regex leakage (\w, .*, |)
  2. Check --lang (ts vs tsx)
  3. Debug-parse: echo '<sample>' | sg run -p '<pattern>' --lang ts --debug-query=ast --stdin — ERROR nodes mean a malformed pattern
  4. Inspect the target AST: sg run -p '$_' --lang ts --debug-query=cst file.ts | head -40 to 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

SriAkhilSJ
SriAkhilSJ/PulseAIRepo

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.

★ 0
SriAkhilSJ
SriAkhilSJ/PulseAIRepo

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.

★ 0
SriAkhilSJ
SriAkhilSJ/PulseAIRepo

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.

★ 0
SriAkhilSJ
SriAkhilSJ/PulseAIRepo

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.

★ 0
SriAkhilSJ
SriAkhilSJ/PulseAIRepo

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.

★ 0
SriAkhilSJ
SriAkhilSJ/PulseAIRepo

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.

★ 0