|
| 1 | +# CodeMap CLI Rust 重写计划 |
| 2 | + |
| 3 | +## 背景 |
| 4 | + |
| 5 | +当前 CLI 基于 Node.js + tree-sitter WASM，功能已验证（84 测试全部通过），但存在以下痛点： |
| 6 | +- 用户安装插件后需要额外执行 `cd ccplugin/cli && npm install` |
| 7 | +- 依赖 Node.js >= 18 运行时 |
| 8 | +- tree-sitter 走 WASM 间接层，性能非最优 |
| 9 | +- `node_modules/` 体积大（~30MB+） |
| 10 | + |
| 11 | +## 目标 |
| 12 | + |
| 13 | +将 CLI 工具从 Node.js 重写为 Rust，提供预编译二进制文件，实现零依赖安装。 |
| 14 | + |
| 15 | +## 方案对比 |
| 16 | + |
| 17 | +| 维度 | Node.js (当前) | Rust (目标) | |
| 18 | +|------|--------------|------------| |
| 19 | +| 安装步骤 | clone → npm install → plugin add | clone → plugin add（零配置） | |
| 20 | +| 运行时依赖 | Node.js >= 18 | 无 | |
| 21 | +| tree-sitter | WASM 间接调用 | 原生 C 绑定（tree-sitter 本身是 C/Rust） | |
| 22 | +| 分发体积 | ~30MB node_modules | 单个二进制 ~5-10MB | |
| 23 | +| 跨平台 | 靠 Node 抹平 | 需交叉编译，GitHub Actions 自动化 | |
| 24 | +| 扫描性能 | 可用，中等 | 预期提升 3-5x | |
| 25 | + |
| 26 | +## 架构设计 |
| 27 | + |
| 28 | +### 目录结构变更 |
| 29 | + |
| 30 | +``` |
| 31 | +ccplugin/ |
| 32 | +├── bin/ |
| 33 | +│ ├── codegraph-x86_64-linux # Linux x64 |
| 34 | +│ ├── codegraph-aarch64-linux # Linux ARM64 |
| 35 | +│ ├── codegraph-x86_64-darwin # macOS x64 |
| 36 | +│ ├── codegraph-aarch64-darwin # macOS ARM64 (Apple Silicon) |
| 37 | +│ └── codegraph-x86_64-windows.exe # Windows x64 |
| 38 | +├── skills/ # 不变 |
| 39 | +└── .claude-plugin/plugin.json # 不变 |
| 40 | +``` |
| 41 | + |
| 42 | +### SKILL.md 路径变更 |
| 43 | + |
| 44 | +从： |
| 45 | +```bash |
| 46 | +node "${CLAUDE_PLUGIN_ROOT}/cli/bin/codegraph.js" scan . |
| 47 | +``` |
| 48 | + |
| 49 | +改为（需要平台检测脚本或直接引用）： |
| 50 | +```bash |
| 51 | +"${CLAUDE_PLUGIN_ROOT}/bin/codegraph" scan . |
| 52 | +``` |
| 53 | + |
| 54 | +> 需要一个 wrapper 脚本或在 SKILL 中根据平台选择正确的二进制名。 |
| 55 | +
|
| 56 | +### Rust 项目结构 |
| 57 | + |
| 58 | +``` |
| 59 | +rust-cli/ # 新建 Rust 项目（与 ccplugin 同级或独立仓库） |
| 60 | +├── Cargo.toml |
| 61 | +├── build.rs # 编译时链接 tree-sitter 语法 |
| 62 | +├── src/ |
| 63 | +│ ├── main.rs # CLI 入口（clap） |
| 64 | +│ ├── scanner.rs # 全量扫描引擎（移植自 scanner.js） |
| 65 | +│ ├── parser.rs # tree-sitter 原生解析（移植自 parser.js） |
| 66 | +│ ├── graph.rs # 图谱数据结构（移植自 graph.js） |
| 67 | +│ ├── differ.rs # 增量更新引擎（移植自 differ.js） |
| 68 | +│ ├── query.rs # 查询引擎（移植自 query.js） |
| 69 | +│ ├── slicer.rs # 切片生成（移植自 slicer.js） |
| 70 | +│ ├── impact.rs # 影响分析（移植自 impact.js） |
| 71 | +│ ├── traverser.rs # 文件遍历与语言检测（移植自 traverser.js） |
| 72 | +│ └── languages/ |
| 73 | +│ ├── mod.rs # 语言适配器 trait |
| 74 | +│ ├── typescript.rs |
| 75 | +│ ├── python.rs |
| 76 | +│ ├── go.rs |
| 77 | +│ ├── rust_lang.rs |
| 78 | +│ ├── java.rs |
| 79 | +│ ├── c.rs |
| 80 | +│ └── cpp.rs |
| 81 | +└── tests/ # 移植现有 84 个测试作为验收标准 |
| 82 | +``` |
| 83 | + |
| 84 | +### 关键依赖 |
| 85 | + |
| 86 | +```toml |
| 87 | +[dependencies] |
| 88 | +tree-sitter = "0.24" |
| 89 | +tree-sitter-typescript = "0.23" |
| 90 | +tree-sitter-javascript = "0.23" |
| 91 | +tree-sitter-python = "0.23" |
| 92 | +tree-sitter-go = "0.23" |
| 93 | +tree-sitter-rust = "0.23" |
| 94 | +tree-sitter-java = "0.23" |
| 95 | +tree-sitter-c = "0.23" |
| 96 | +tree-sitter-cpp = "0.23" |
| 97 | +clap = { version = "4", features = ["derive"] } |
| 98 | +serde = { version = "1", features = ["derive"] } |
| 99 | +serde_json = "1" |
| 100 | +walkdir = "2" |
| 101 | +sha2 = "0.10" |
| 102 | +ignore = "0.4" # .gitignore 支持 |
| 103 | +``` |
| 104 | + |
| 105 | +## 实施步骤 |
| 106 | + |
| 107 | +### 阶段 1：Rust 项目脚手架 |
| 108 | +- 初始化 Cargo 项目 |
| 109 | +- 配置 clap CLI 框架，注册所有子命令 |
| 110 | +- 配置 tree-sitter 原生绑定，验证所有 8 种语言语法加载 |
| 111 | +- 实现文件遍历和语言检测（移植 traverser.js） |
| 112 | + |
| 113 | +### 阶段 2：核心引擎移植 |
| 114 | +- 移植 parser.rs（tree-sitter 原生调用替代 WASM） |
| 115 | +- 移植 graph.rs（数据结构，保持 JSON 格式兼容） |
| 116 | +- 移植 scanner.rs（全量扫描） |
| 117 | +- 移植 slicer.rs（切片生成） |
| 118 | + |
| 119 | +### 阶段 3：语言适配器 |
| 120 | +- 定义 `LanguageAdapter` trait |
| 121 | +- 逐个移植 8 种语言适配器 |
| 122 | +- 确保 AST 节点查询逻辑与 JS 版本输出一致 |
| 123 | + |
| 124 | +### 阶段 4：高级功能 |
| 125 | +- 移植 differ.rs（增量更新 + rebuildDependencies） |
| 126 | +- 移植 query.rs（符号查询） |
| 127 | +- 移植 impact.rs（影响分析） |
| 128 | + |
| 129 | +### 阶段 5：测试与兼容性 |
| 130 | +- 移植现有 84 个测试用例作为验收标准 |
| 131 | +- 验证输出 JSON 格式与 Node.js 版本完全兼容（.codemap/ 目录格式不变） |
| 132 | +- 对同一个 sample-project 做交叉验证：Node.js 扫描 vs Rust 扫描，输出应一致 |
| 133 | + |
| 134 | +### 阶段 6：CI/CD 与分发 |
| 135 | +- GitHub Actions 配置交叉编译（使用 cross 或 cargo-zigbuild） |
| 136 | +- 目标平台：x86_64-linux, aarch64-linux, x86_64-darwin, aarch64-darwin, x86_64-windows |
| 137 | +- Release 时自动编译并上传二进制到 GitHub Release |
| 138 | +- 更新 SKILL.md 路径，添加平台检测 wrapper 脚本 |
| 139 | +- 更新 README 安装文档 |
| 140 | + |
| 141 | +### 阶段 7：清理 |
| 142 | +- 移除 ccplugin/cli/ 目录（Node.js 版本） |
| 143 | +- 将预编译二进制放入 ccplugin/bin/ |
| 144 | +- 最终验证插件安装流程 |
| 145 | + |
| 146 | +## 兼容性约束 |
| 147 | + |
| 148 | +- `.codemap/` 输出目录格式必须与 Node.js 版本完全一致 |
| 149 | +- graph.json、meta.json、slices/*.json 的 JSON schema 不变 |
| 150 | +- 现有已生成的 .codemap/ 可被 Rust 版本直接读取和增量更新 |
| 151 | + |
| 152 | +## 风险 |
| 153 | + |
| 154 | +- tree-sitter 语法版本差异可能导致 AST 节点名称不同，需要逐语言验证 |
| 155 | +- 交叉编译可能遇到平台特定问题（尤其是 Windows + tree-sitter C 绑定） |
| 156 | +- 二进制体积需要关注，strip + LTO 优化 |
| 157 | + |
| 158 | +## 状态 |
| 159 | + |
| 160 | +- [ ] 阶段 1：Rust 项目脚手架 |
| 161 | +- [ ] 阶段 2：核心引擎移植 |
| 162 | +- [ ] 阶段 3：语言适配器 |
| 163 | +- [ ] 阶段 4：高级功能 |
| 164 | +- [ ] 阶段 5：测试与兼容性 |
| 165 | +- [ ] 阶段 6：CI/CD 与分发 |
| 166 | +- [ ] 阶段 7：清理 |
0 commit comments