anatolykoptev/ox-codes
GitHub: anatolykoptev/ox-codes
将 ripgrep、tree-sitter 和 ast-grep 封装为统一 HTTP API 的代码智能服务，提供语言感知搜索、结构化重写和数据流分析能力。
Stars: 2 | Forks: 0
# ox-codes
[](LICENSE)
[](https://www.rust-lang.org)
[](Dockerfile)
作为 HTTP 服务的代码搜索与结构化重写工具。将 [ripgrep](https://github.com/BurntSushi/ripgrep)、[tree-sitter](https://tree-sitter.github.io) 和 [ast-grep](https://ast-grep.github.io) 封装在一个 JSON API 之后，并在此基础上提供了一个过程内数据流引擎。
## 为什么使用它
- **语言感知搜索** — 支持将正则匹配范围限定在函数体、类块或任何命名的 AST 区域，支持 15 种语言。
- **基于形态的查询** — 根据 AST 结构（如 `func $N($$$) error`）而非文本进行匹配，支持通配符捕获。
- **结构化重写** — 在 AST 层面进行搜索与替换；在应用前以统一 diff 进行预览。
- **数据流分析** — 检测死存储、未使用变量和污点数据流（source→sink），无需启动编译器。
- **零状态、零认证** — 无状态的 HTTP 服务；挂载需要分析的目录即可调用 API。
- **热缓存速度** — scoped-search 和 dataflow 结果按 repo 缓存，以每个文件的 mtime+size 为键，并在发生更改时失效，因此在未更改的树上重复查询将直接从缓存返回（亚毫秒级），而不是重新解析。
## 快速开始
```
git clone https://github.com/anatolykoptev/ox-codes
cd ox-codes
make build # cargo build --workspace (requires Rust 1.97+)
make test # cargo test --workspace
cargo run -p ox-codes -- --port 8902 # start the HTTP service
```
然后发送一个搜索请求：
```
curl -s -X POST http://127.0.0.1:8902/search \
-H 'Content-Type: application/json' \
-d '{"root":"/path/to/repo","pattern":"TODO","language":"go"}' | jq .
```
响应：
```
{
"matches": [
{ "file": "cmd/main.go", "line": 42, "text": "// TODO: handle error" }
],
"total_matches": 1,
"truncated": false,
"duration_ms": 8
}
```
## 端点
| 端点 | 引擎 | 用例 |
|---|---|---|
| `POST /search` | ripgrep | 跨目录树的类 Grep 文本/正则搜索 |
| `POST /search/scoped` | tree-sitter + regex | 限制在命名 AST 区域（函数、类等）内的正则搜索 |
| `POST /search/structural` | ast-grep | 通过带有 `$WILDCARD` 捕获的 AST 结构进行模式匹配 |
| `POST /rewrite` | ast-grep | 结构化搜索与替换；按文件返回统一 diff |
| `POST /dataflow/analyze` | 自定义 IL/CFG | 死存储、未使用变量（Go, Python） |
| `POST /dataflow/taint` | 自定义 IL/CFG | 使用内置或自定义规则进行 source→sink 污点追踪 |
| `GET /health` | — | 存活探针 |
| `GET /cache/stats` | — | scoped 和 dataflow 结果缓存的命中/未命中计数器及条目数 |
所有搜索端点均支持 `expand`（`"none"` / `"function"` / `"block"`）和 `max_tokens` 参数，用于返回完整的封闭 AST 块，而不是单行匹配结果。
## 文档
- **[`docs/API.md`](docs/API.md)** — 每个端点的完整请求/响应 schema 及示例。
- **[`docs/EXAMPLES.md`](docs/EXAMPLES.md)** — 端到端使用场景：认证函数发现、错误模式重构、未使用变量清理、污点追踪。
- **[`docs/INTEGRATION.md`](docs/INTEGRATION.md)** — 消费者契约：文件系统挂载规范、路径陷阱、Docker 卷配置。
- **[`docs/ROADMAP.md`](docs/ROADMAP.md)** — 阶段状态；已完成的工作及后续计划。
## 支持的语言
Scoped 和 structural 搜索：Go, Python, TypeScript, JavaScript, Rust, Java, C, C++, Ruby, C#, PHP, Svelte, Astro, Bash, Lua。
Dataflow（analyze + taint）：Go, Python。其他语言的支持进度见 [`docs/ROADMAP.md`](docs/ROADMAP.md)。
## Crate 结构
| Crate | 角色 |
|---|---|
| [`crates/core`](crates/core) | 搜索引擎：grep, scoped, structural, rewrite, expand |
| [`crates/langs`](crates/langs) | Tree-sitter 语言范围（15 种语言） |
| [`crates/dataflow`](crates/dataflow) | IL 构建器, CFG, def-use 链, 污点引擎 |
| [`crates/server`](crates/server) | axum HTTP handlers |
| [`src/`](src) | 二进制入口点（`ox-codes` CLI） |
## 贡献
请参阅 [CONTRIBUTING.md](CONTRIBUTING.md)。请遵循[行为准则](CODE_OF_CONDUCT.md)。
## 许可证
MIT — 详见 [LICENSE](LICENSE)。
标签：AST解析, Rust, XSS注入, 代码搜索, 可视化界面, 结构化重写, 网络流量审计, 请求拦截, 通知系统, 错误基检测, 静态代码分析