AST代码分析超能力
AST Code Analysis Superpower
基于AST的代码模式分析工具，用于检测安全漏洞、性能问题和结构缺陷。
適用平台：
ChatGPTClaudeGemini
---
name: ast-code-analysis-superpower
description: 使用 ast-grep 进行基于 AST 的代码模式分析，以发现安全、性能和结构问题。在以下情况使用：(1) 审查代码是否存在安全漏洞，(2) 分析 React Hook 依赖或性能模式，(3) 在大型代码库中检测结构性反模式，(4) 需要超越手动检查的系统性模式匹配。
---
# AST-Grep 代码分析
AST 模式匹配通过结构识别而非逐行阅读来识别代码问题。代码结构揭示了表面检查遗漏的隐藏关系、漏洞和反模式。
## 配置
- **目标语言**：${language:javascript}
- **分析重点**：${analysis_focus:security}
- **严重级别**：${severity_level:ERROR}
- **框架**：${framework:React}
- **最大嵌套深度**：${max_nesting:3}
## 前提条件
```bash
# 安装 ast-grep（如果尚未安装）
npm install -g @ast-grep/cli
# 或者：mise install -g ast-grep
```
## 决策树：何时使用 AST 分析
```
需要代码审查吗？
|
+-- 简单代码（<${simple_code_lines:50} 行，结构清晰）--> 手动审查
|
+-- 复杂代码（嵌套、多文件、抽象层）
|
+-- 需要安全审查？--> 使用安全模式
+-- 性能分析？--> 使用性能模式
+-- 结构质量？--> 使用结构模式
+-- 跨文件模式？--> 使用 --include glob 运行
```
## 模式类别
| 类别 | 重点 | 常见发现 |
|----------|-------|-----------------|
| 安全 | 加密函数、认证流程 | 硬编码密钥、弱令牌 |
| 性能 | Hook、循环、异步 | 无限重渲染、内存泄漏 |
| 结构 | 嵌套、复杂度 | 深层条件、可维护性 |
## 基本模式
### 安全：硬编码密钥
```yaml
# sg-rules/security/hardcoded-secrets.yml
id: hardcoded-secrets
language: ${language:javascript}
rule:
pattern: |
const $VAR = '$LITERAL';
$FUNC($VAR, ...)
meta:
severity: ${severity_level:ERROR}
message: "检测到潜在的硬编码密钥"
```
### 安全：不安全的令牌生成
```yaml
# sg-rules/security/insecure-tokens.yml
id: insecure-token-generation
language: ${language:javascript}
rule:
pattern: |
btoa(JSON.stringify($OBJ) + '.' + $SECRET)
meta:
severity: ${severity_level:ERROR}
message: "使用 base64 生成不安全的令牌"
```
### 性能：${framework:React} Hook 依赖
```yaml
# sg-rules/performance/react-hook-deps.yml
id: react-hook-dependency-array
language: typescript
rule:
pattern: |
useEffect(() => {
$BODY
}, [$FUNC])
meta:
severity: WARNING
message: "函数依赖可能导致无限重渲染"
```
### 结构：深层嵌套
```yaml
# sg-rules/structure/deep-nesting.yml
id: deep-nesting
language: ${language:javascript}
rule:
any:
- pattern: |
if ($COND1) {
if ($COND2) {
if ($COND3) {
$BODY
}
}
}
- pattern: |
for ($INIT) {
for ($INIT2) {
for ($INIT3) {
$BODY
}
}
}
meta:
severity: WARNING
message: "深层嵌套（>${max_nesting:3} 级）- 考虑重构"
```
## 运行分析
```bash
# 安全扫描
ast-grep run -r sg-rules/security/
# 对 ${framework:React} 文件进行性能扫描
ast-grep run -r sg-rules/performance/ --include="*.tsx,*.jsx"
# 完整扫描并输出 JSON 格式
ast-grep run -r sg-rules/ --format=json > analysis-report.json
# 交互模式进行调查
ast-grep run -r sg-rules/ --interactive
```
## 模式编写清单
- [ ] 模式匹配特定的反模式，而非通用代码
- [ ] 使用 `inside` 或 `has` 进行上下文约束
- [ ] 包含 `not` 约束以减少误报
- [ ] 每种语言（JS vs TS）单独规则
- [ ] 适当的严重级别（${severity_level:ERROR}/WARNING/INFO）
## 常见错误
| 错误 | 症状 | 修复 |
|---------|---------|-----|
| 模式过于通用 | 许多误报 | 添加上下文约束 |
| 缺少 `inside` | 匹配错误位置 | 使用父上下文进行范围限定 |
| 没有 `not` 子句 | 匹配有效模式 | 排除已知良好情况 |
| JS 模式用于 TS | 类型注解破坏匹配 | 创建特定语言的规则 |
## 验证步骤
1. **测试模式准确性**：在已知易受攻击的代码样本上运行
2. **检查误报率**：手动审查前 ${sample_size:10} 个匹配项
3. **验证严重性**：确认 ${severity_level:ERROR} 级别的发现是可操作的
4. **跨文件覆盖**：验证模式在预期范围内运行
## 示例输出
```
$ ast-grep run -r sg-rules/
src/components/UserProfile.jsx:15: ${severity_level:ERROR} [insecure-tokens] 不安全的令牌生成
src/hooks/useAuth.js:8: ${severity_level:ERROR} [hardcoded-secrets] 潜在的硬编码密钥
src/components/Dashboard.tsx:23: WARNING [react-hook-deps] 函数依赖
src/utils/processData.js:45: WARNING [deep-nesting] 检测到深层嵌套
发现 4 个问题（2 个错误，2 个警告）
```
## 项目设置
```bash
# 在项目中初始化 ast-grep
ast-grep init
# 创建规则目录
mkdir -p sg-rules/{security,performance,structure}
# 添加到 CI 流水线
# .github/workflows/lint.yml
# - run: ast-grep run -r sg-rules/ --format=json
```
## 自定义模式模板
### ${framework:React} 特定模式
```yaml
# 列表渲染中缺少 key
id: missing-list-key
language: typescript
rule:
pattern: |
$ARRAY.map(($ITEM) => <$COMPONENT $$$PROPS />)
constraints:
$PROPS:
not:
has:
pattern: 'key={$_}'
meta:
severity: WARNING
message: "列表渲染中缺少 key 属性"
```
### Async/Await 模式
```yaml
# 异步中缺少错误处理
id: unhandled-async
language: ${language:javascript}
rule:
pattern: |
async function $NAME($$$) {
$$$BODY
}
constraints:
$BODY:
not:
has:
pattern: 'try { $$$ } catch'
meta:
severity: WARNING
message: "异步函数没有 try-catch 错误处理"
```
## 与 CI/CD 集成
```yaml
# GitHub Actions 示例
name: AST 分析
on: [push, pull_request]
jobs:
analyze:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: 安装 ast-grep
run: npm install -g @ast-grep/cli
- name: 运行分析
run: |
ast-grep run -r sg-rules/ --format=json > report.json
if grep -q '"severity": "${severity_level:ERROR}"' report.json; then
echo "发现严重问题！"
exit 1
fi
```