structural-search

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Structural Search

结构化搜索

Search code by its abstract syntax tree (AST) structure. Finds semantic patterns that regex cannot match reliably.

通过抽象语法树（AST）结构搜索代码。查找正则表达式无法可靠匹配的语义模式。

Tools

工具

Tool	Command	Use For
ast-grep	`sg -p 'pattern'`	AST-aware code search

工具	命令	适用场景
ast-grep	`sg -p 'pattern'`	支持AST的代码搜索

Pattern Syntax

模式语法

Pattern	Matches	Example
`$NAME`	Named identifier	`function $NAME() {}`
`$_`	Any single node	`console.log($_)`
`$$$`	Zero or more nodes	`function $_($$$) {}`

模式	匹配内容	示例
`$NAME`	命名标识符	`function $NAME() {}`
`$_`	任意单个节点	`console.log($_)`
`$$$`	零或多个节点	`function $_($$$) {}`

Top 10 Essential Patterns

10个核心实用模式

bash

undefined

bash

undefined

1. Find console.log calls

1. 查找console.log调用

sg -p 'console.log($_)'

2. Find React hooks

2. 查找React hooks

sg -p 'const [$, $] = useState($)' sg -p 'useEffect($, [$$$])'

3. Find function definitions

3. 查找函数定义

sg -p 'function $NAME($$$) { $$$ }' sg -p 'def $NAME($$$): $$$' --lang python

4. Find imports

4. 查找导入语句

sg -p 'import $_ from "$"' sg -p 'from $ import $_' --lang python

5. Find async patterns

5. 查找异步模式

sg -p 'await $_' sg -p 'async function $NAME($$$) { $$$ }'

6. Find error handling

6. 查找错误处理代码

sg -p 'try { $$$ } catch ($_) { $$$ }' sg -p 'if err != nil { $$$ }' --lang go

7. Find potential issues

7. 查找潜在问题

sg -p '$_ == $' # == instead of === sg -p 'eval($)' # Security risk sg -p '$.innerHTML = $' # XSS vector

sg -p '$_ == $' # 使用==而非=== sg -p 'eval($)' # 安全风险 sg -p '$.innerHTML = $' # XSS风险点

8. Preview refactoring

8. 预览重构效果

sg -p 'console.log($)' -r 'logger.info($)'

9. Apply refactoring

9. 执行重构

sg -p 'var $NAME = $' -r 'const $NAME = $' --rewrite

10. Search specific language

10. 指定语言搜索

sg -p 'pattern' --lang typescript

undefined

sg -p 'pattern' --lang typescript

undefined

Quick Reference

快速参考

Task	Command
Find pattern	`sg -p 'pattern'`
Specific language	`sg -p 'pattern' --lang python`
Replace (preview)	`sg -p 'old' -r 'new'`
Replace (apply)	`sg -p 'old' -r 'new' --rewrite`
Show context	`sg -p 'pattern' -A 3`
JSON output	`sg -p 'pattern' --json`
File list only	`sg -p 'pattern' -l`
Count matches	`sg -p 'pattern' --count`
Run YAML rules	`sg scan`

任务	命令
查找模式	`sg -p 'pattern'`
指定语言	`sg -p 'pattern' --lang python`
替换（预览）	`sg -p 'old' -r 'new'`
替换（执行）	`sg -p 'old' -r 'new' --rewrite`
显示上下文	`sg -p 'pattern' -A 3`
JSON格式输出	`sg -p 'pattern' --json`
仅显示文件列表	`sg -p 'pattern' -l`
统计匹配数量	`sg -p 'pattern' --count`
运行YAML规则	`sg scan`

When to Use

适用场景

Finding all usages of a function/method
Locating specific code patterns (hooks, API calls)
Preparing for large-scale refactoring
When regex would match false positives
Detecting anti-patterns and security issues
Creating custom linting rules

查找某个函数/方法的所有调用位置
定位特定代码模式（hooks、API调用）
为大规模重构做准备
正则表达式会产生误匹配时
检测反模式和安全问题
创建自定义代码检查规则

Additional Resources

额外资源

For complete patterns, load:

```
./references/js-ts-patterns.md
```
- JavaScript/TypeScript patterns
```
./references/python-patterns.md
```
- Python patterns
```
./references/go-rust-patterns.md
```
- Go and Rust patterns
```
./references/security-patterns.md
```
- Security vulnerability detection
```
./references/advanced-usage.md
```
- YAML rules and tool integration
```
./assets/rule-template.yaml
```
- Starter template for custom rules

如需完整模式，请查看：

```
./references/js-ts-patterns.md
```
- JavaScript/TypeScript模式
```
./references/python-patterns.md
```
- Python模式
```
./references/go-rust-patterns.md
```
- Go和Rust模式
```
./references/security-patterns.md
```
- 安全漏洞检测
```
./references/advanced-usage.md
```
- YAML规则与工具集成
```
./assets/rule-template.yaml
```
- 自定义规则入门模板