ast-grep-search

ast-grep 结构化代码搜索与重构

使用 ast-grep 进行结构化代码搜索与重构——根据代码的 AST（抽象语法树）而非文本模式进行匹配。

何时使用此技能

在以下情况下使用此技能……	在以下情况下改用其他工具……
模式取决于 AST 结构（函数形态、调用形式、参数数量）	搜索纯文本或正则表达式匹配 → tools-plugin:rg-code-search
在多个文件中重构 API 调用位置，同时保留捕获的变量	执行一次性反模式扫描并生成报告 → code-antipatterns
为临时迁移手动编写结构化搜索/替换	对已知文件/目录进行功能性重构 → code-refactor
为代码库特有的异味构建新的 ast-grep 规则	查找现有代码检查器的 Agent 标志 → code-lint

何时使用 ast-grep 而非 Grep/ripgrep

在以下情况下使用 ast-grep……	在以下情况下使用 grep/rg……
模式取决于代码结构	简单文本或正则表达式匹配
需要匹配任意数量的参数	搜索日志、文档、配置
在多个文件中重构	一次性搜索字面字符串
查找反模式（空的 catch 等）	不关心语言
替换时保留变量	快速检查文件名/行号

判断规则：如果搜索模式中包含表示“任意表达式”“任意参数”或“任意函数名”的通配符，请使用 ast-grep。

模式语法

模式	匹配内容	示例
$VAR	单个 AST 节点	console.log($MSG)
$$$ARGS	零个或多个节点	func($$$ARGS)
$_	单个节点（不捕获）	$_ == $_
$A == $A	重复出现的同一节点	查找 x == x（而非 x == y）

基本命令

搜索模式

# Find structural patterns
ast-grep -p 'console.log($$$)' --lang js
ast-grep -p 'def $FUNC($$$): $$$' --lang py
ast-grep -p 'fn $NAME($$$) -> $RET { $$$ }' --lang rs

# Search in specific directory
ast-grep -p 'import $PKG' --lang js src/

# JSON output for parsing
ast-grep -p 'pattern' --lang js --json=compact

搜索并替换

# Preview changes (default - shows matches)
ast-grep -p 'var $V = $X' -r 'const $V = $X' --lang js

# Apply changes to all files
ast-grep -p 'var $V = $X' -r 'const $V = $X' --lang js -U

# Interactive review
ast-grep -p 'oldAPI($$$ARGS)' -r 'newAPI($$$ARGS)' --lang py -i

# Convert function syntax
ast-grep -p 'function($$$ARGS) { return $EXPR }' \
         -r '($$$ARGS) => $EXPR' --lang js -U

# Update import paths
ast-grep -p "import $NAME from '@old/$PATH'" \
         -r "import $NAME from '@new/$PATH'" --lang ts -U

语言代码

代码	语言	代码	语言
js	JavaScript	py	Python
ts	TypeScript	rs	Rust
jsx	JSX	go	Go
tsx	TSX	java	Java
cpp	C++	rb	Ruby
c	C	php	PHP

各语言的常见模式

JavaScript/TypeScript

# Find React hooks
ast-grep -p 'const [$STATE, $SETTER] = useState($INIT)' --lang jsx

# Find async functions
ast-grep -p 'async function $NAME($$$) { $$$ }' --lang js

# Find type assertions
ast-grep -p '$EXPR as $TYPE' --lang ts

# Find empty catch blocks
ast-grep -p 'try { $$$ } catch ($E) { }' --lang js

# Find eval usage (security)
ast-grep -p 'eval($$$)' --lang js

# Find innerHTML (XSS risk)
ast-grep -p '$ELEM.innerHTML = $$$' --lang js

# Find specific imports
ast-grep -p "import { $$$IMPORTS } from '$PKG'" --lang js

Python

# Find class definitions
ast-grep -p 'class $NAME($$$BASES): $$$' --lang py

# Find decorated functions
ast-grep -p '@$DECORATOR\ndef $FUNC($$$): $$$' --lang py

# Find dangerous shell calls
ast-grep -p 'os.system($$$)' --lang py

# Find SQL concatenation (injection risk)
ast-grep -p '"SELECT * FROM " + $VAR' --lang py

Rust

# Find unsafe blocks
ast-grep -p 'unsafe { $$$ }' --lang rs

# Find impl blocks
ast-grep -p 'impl $TRAIT for $TYPE { $$$ }' --lang rs

# Find public functions
ast-grep -p 'pub fn $NAME($$$) { $$$ }' --lang rs

Go

# Find goroutines
ast-grep -p 'go $FUNC($$$)' --lang go

# Find defer statements
ast-grep -p 'defer $FUNC($$$)' --lang go

# Find error handling
ast-grep -p 'if err != nil { $$$ }' --lang go

常见重构方案

# Replace deprecated API calls
ast-grep -p 'oldAPI.$METHOD($$$)' -r 'newAPI.$METHOD($$$)' --lang js -U

# Rename a function across files
ast-grep -p 'oldName($$$ARGS)' -r 'newName($$$ARGS)' --lang py -U

# Remove console.log statements
ast-grep -p 'console.log($$$)' -r '' --lang js -U

# Convert require to import
ast-grep -p 'const $NAME = require($PKG)' \
         -r 'import $NAME from $PKG' --lang js -i

# Add error handling wrapper
ast-grep -p 'await $EXPR' \
         -r 'await $EXPR.catch(handleError)' --lang ts -i

命令行标志

标志	用途
-p, --pattern	搜索模式
-r, --rewrite	替换模式
-l, --lang	目标语言
-i, --interactive	逐项检查更改
-U, --update-all	应用所有更改
--json	JSON 输出（compact、stream、pretty）
-A N	匹配项之后的行数
-B N	匹配项之前的行数
-C N	匹配项周围的行数
--debug-query	调试模式解析

YAML 规则（扫描模式）

对于可复用的规则，请使用 ast-grep scan 和 YAML 配置：

# Scan with config
ast-grep scan -c sgconfig.yml

# Run specific rule
ast-grep scan -r rule-name

# Initialize a rules project
ast-grep new project my-linter
ast-grep new rule no-console-log

最简规则文件：

id: no-empty-catch
language: JavaScript
severity: warning
message: Empty catch block hides errors
rule:
  pattern: try { $$$ } catch ($E) { }
fix: |
  try { $$$ } catch ($E) { console.error($E) }

有关完整的 YAML 规则语法、约束、转换和测试，请参阅 REFERENCE.md。

Agent 优化

场景	命令
快速结构化搜索	ast-grep -p 'pattern' --lang js --json=compact
统计匹配数	ast-grep -p 'pattern' --lang js --json=stream | wc -l
仅列出文件	ast-grep -p 'pattern' --json=stream | jq -r '.file' | sort -u
批量重构	ast-grep -p 'old' -r 'new' --lang js -U
使用规则扫描	ast-grep scan --json
调试模式	ast-grep -p 'pattern' --debug-query --lang js

快速参考

# 1. Search for pattern
ast-grep -p 'pattern' --lang js src/

# 2. Preview rewrite
ast-grep -p 'old' -r 'new' --lang js

# 3. Apply rewrite
ast-grep -p 'old' -r 'new' --lang js -U

# 4. Scan with rules
ast-grep scan -c sgconfig.yml

# 5. Debug pattern
ast-grep -p 'pattern' --debug-query --lang js