astgrep

astgrep — ast-grep + ripgrep

Step 1: 初始化

对话中仅执行一次。检测方式：which sg-check 非空则已加载。

use skills/astgrep/astgrep.nu *
sg-check

sg-check 返回 {sg: {installed, version}, rg: {installed, version}}。需要 sg（ast-grep）和 rg（ripgrep）已安装。

Step 2: 搜索

1. sg-search — AST 结构化搜索（精确模式匹配）
2. rg-search — 文本搜索（通用 fallback）
3. 远程 GitHub 代码搜索 → 使用 github skill 的 gh-search-code

Step 3: 重写

sg-rewrite 默认 dry-run（预览 diff），加 --apply 真正写入。

命令速查

搜索

命令	说明
sg-search <query> [--lang] [--path] [--rule] [--kind] [--globs]	AST 结构化搜索
rg-search <query> [--path] [--glob] [--type] [-C]	文本搜索

重写

命令	说明
sg-rewrite <query> <replacement> [--lang] [--path]	AST 重写预览（dry-run）
sg-rewrite <query> <replacement> --apply	AST 重写（写入文件）

辅助

命令	说明
sg-langs	支持的语言 + 扩展名映射
sg-check	检查 sg/rg 安装状态

sg-search 三种模式

sg-search "console.log($A)" --lang js          # Pattern 模式
sg-search --rule rule.yml --path ./src         # Rule 模式（YAML 规则）
sg-search --kind function_declaration --lang rs # Kind 模式（节点类型）

→ 元变量语法（$VAR / $$$ARGS / $_）、YAML rule 关系约束（inside/has/not）深度示例见 patterns.md。

返回值

sg-search / rg-search

字段	类型	说明
engine	string	"sg" 或 "rg"
file	string	文件路径
line	int	行号（1-based）
text	string	匹配文本
metavars	record?	sg 元变量 {$VAR: "value"}，rg 为 null

sg-rewrite (dry-run)

同 sg-search，额外字段：

字段	类型	说明
replacement	string	替换后的文本

sg-rewrite (--apply)

字段	类型	说明
applied	bool	true
file	string	搜索路径
changes	int	变更数量

sg-check

字段	类型	说明
sg.installed	bool	ast-grep 是否安装
sg.version	string	版本号
rg.installed	bool	ripgrep 是否安装
rg.version	string	版本号

错误恢复

场景	做法
sg pattern 语法错误	简化 pattern 或用 --kind 替代
sg 语言不支持（如 .nu）	切换 rg-search
无结果	尝试简化 pattern、切换引擎、添加 --globs
rewrite 没改文件	默认 dry-run，需加 --apply
rg exit 1 无 stderr	正常无匹配，返回空列表

典型用法

# AST 搜索：找到所有 console.log 调用
sg-search "console.log($MSG)" --lang js --path ./src

# AST 搜索：YAML 规则
sg-search --rule rules/no-await-in-promise.yml --path ./src

# AST 搜索：按节点类型
sg-search --kind function_declaration --lang rust --path ./crates

# 重写预览（不修改文件）
sg-rewrite "oldApi($PARAM)" "newApi($PARAM)" --lang ts --path ./src

# 确认后应用
sg-rewrite "oldApi($PARAM)" "newApi($PARAM)" --lang ts --path ./src --apply

# 文本搜索
rg-search "TODO:" --path ./src --glob "*.ts"

# 查看支持语言
sg-langs

# 混合管道：sg + rg 结果合并后分析
let sg = (sg-search "fetch($URL)" --lang ts --path ./src)
let rg = (rg-search "fetch(" --path ./src --glob "*.ts")
$sg | append $rg | group-by file | to nuon

注意事项

• sg line 是 0-based，Nu 层已统一 +1 转为 1-based
• rewrite 安全：默认 dry-run 不修改任何文件，--apply 才真正写入
• 远程搜索请使用 github skill 的 gh-search-code
• 语言陷阱：.tsx 用 Tsx 非 TypeScript；--globs（sg）vs --glob（rg）；.nu/Dart/Zig/SQL 不支持 → 用 rg-search。→ 完整语言-扩展映射 + 陷阱见 langs.md
• $history.N：见下方 ## $history 用法 小节

$history 与数据处理

通用规则见 browse SKILL.md 的 ## $history 用法。

搜索结果是同构列表，直接管道操作

sg-search / rg-search 返回 list<{engine, file, line, text, metavars}>，可直接筛选：

# 赋值给变量（跨命令安全）
let result = (sg-search "$A && $B" --lang typescript --path sdk/src/)
$result | where file =~ 'twitter'

# 或 MCP 截断时赋值捕获完整结果
sg-search "$A && $B" --lang typescript --path sdk/src/
# 输出截断 → 第一条 evaluate 中赋值
let result = ($history.N)
$result | where engine == 'sg' | length
$result | where metavars != null | get metavars

→ 更多 Nu 分析模式（sg+rg 混合去重、metavar 聚合统计、按 file 分组热点定位）见 patterns.md。

模块结构

astgrep/
  astgrep.nu    — 导出命令（sg-search/sg-rewrite/rg-search/sg-langs/sg-check）
  references/
    patterns.md — pattern 语法 / YAML rule / Nu 分析模式
    langs.md    — 语言-扩展映射表 + 语言陷阱
  SKILL.md      — 本文档