DataDave-Dev/weftmap
GitHub: DataDave-Dev/weftmap
一个将源代码粘贴后自动生成交互式函数调用关系图的 Web 工具，支持多语言并采用可插拔架构。
Stars: 3 | Forks: 4
# Weftmap
[](LICENSE)
[](https://nextjs.org/)
[](https://www.typescriptlang.org/)
[](https://tree-sitter.github.io/)
**🌐 语言：** **English** · [Español](README.es.md)
Weftmap 将源代码转化为一个可导航的图表，展示函数之间的调用
关系。其核心差异化在于**可插拔的多语言架构**：
后端会针对不同语言适配分析逻辑，而添加一门新语言只需几行代码。
目前没有任何免费工具能够在多语言环境下出色地完成这一任务。
## 目录
- [功能](#features)
- [工作原理](#how-it-works)
- [技术栈](#tech-stack)
- [入门指南](#getting-started)
- [可用脚本](#available-scripts)
- [添加新语言](#adding-a-language)
- [项目结构](#project-structure)
- [路线图](#roadmap)
- [贡献指南](#contributing)
- [许可证](#license)
## 功能
- **多语言** — 所有语言共用一个解析引擎 (Tree-sitter)。
- **可插拔** — 一种语言只需一个 `LangSpec` + 两个 Tree-sitter 查询。
- **交互式图表** — 支持平移、缩放和拖拽节点 (React Flow + dagre 布局)。
- **内部调用图** — 显示代码中定义的函数之间的调用关系；
过滤掉对内置函数/库的调用，以保持图表的实用性。
- **用户无需构建步骤** — 粘贴代码片段并点击 *分析* (Analyze) 即可。
## 工作原理
```
┌──────────┐ POST /api/analyze ┌─────────────────────┐ Graph JSON ┌─────────────┐
│ Browser │ ────────────────────▶ │ Tree-sitter (WASM) │ ─────────────▶ │ React Flow │
│ (textarea)│ { code, language } │ per-language module │ {nodes,edges} │ (dagre) │
└──────────┘ └─────────────────────┘ └─────────────┘
```
1. 你粘贴代码并选择一种语言。
2. 后端 (`src/app/api/analyze/route.ts`) 验证输入，使用
匹配的 Tree-sitter 语法解析代码，并遍历语法树以构建
标准化的图 `{ nodes, edges }`。
3. 前端使用 [dagre](https://github.com/dagrejs/dagre) 对其进行布局，并
使用 [React Flow](https://reactflow.dev/) 进行交互式渲染。
调用图通过**声明式 Tree-sitter 查询**提取（一个用于
函数定义，一个用于调用），而不是手动遍历 AST —— 代码更少、
更易于维护，且相同的方法适用于所有语言。
## 技术栈
| 层级 | 选择 | 理由 |
|-------|--------|-----|
| 框架 | Next.js (App Router) | 前端 + 后端同处一个项目，一次部署搞定 |
| 语言 | TypeScript | 全栈类型安全 |
| 解析 | 通过 `web-tree-sitter` (WASM) 实现的 Tree-sitter | 一套 API 支持约 40 种语言 |
| 语法 | `tree-sitter-wasms` | 预构建的语法定义文件 |
| 图表 | React Flow + dagre | 交互式节点，层级布局 |
| 测试 | Vitest | 针对 analyzer 的快速单元测试 |
| 包管理器 | pnpm | 快速且节省磁盘空间的安装 |
## 入门指南
**前置条件：** Node 20+ 和 [pnpm](https://pnpm.io/)。
```
# 1. 安装依赖项
pnpm install
# 2. 启动 dev server
pnpm dev
# 打开 http://localhost:3000
```
粘贴代码片段，选择 **python** 或 **javascript**，然后点击 **Analyze**。
## 可用脚本
| 命令 | 功能说明 |
|---------|--------------|
| `pnpm dev` | 启动开发服务器 |
| `pnpm build` | 生产构建 |
| `pnpm start` | 运行生产构建 |
| `pnpm test` | 运行 analyzer 测试 (Vitest) |
| `pnpm typecheck` | 使用 `tsc --noEmit` 进行类型检查 |
| `pnpm lint` | 使用 ESLint 进行 Lint |
## 添加新语言
这是最有价值的贡献方式。架构是*可插拔的*：
后端会针对不同语言适配分析逻辑，无需改动其他内容。
1. **添加语法。** 将 `tree-sitter-.wasm` 复制到 `public/wasm/` 目录中
（可从
[`tree-sitter-wasms`](https://www.npmjs.com/package/tree-sitter-wasms)
包中获取）。
2. **创建 analyzer。** 添加 `src/lib/analysis/analyzers/.ts` 并包含
一个 `LangSpec` —— 即两个 Tree-sitter 查询（用于函数定义和调用）以及
构成函数作用域的节点类型集合。请以
[`python.ts`](src/lib/analysis/analyzers/python.ts) 为模板。
3. **注册它。** 在
[`src/lib/analysis/registry.ts`](src/lib/analysis/registry.ts) 中添加一行代码。
4. **添加 UI 选项。** 将该语言的 key 添加到
[`src/app/page.tsx`](src/app/page.tsx) 的 `LANGUAGES` 数组中。
5. **添加测试。** 在
`src/lib/analysis/analyzers/` 中添加代码片段及其对应的预期 nodes/edges 测试。
大功告成。
## 项目结构
```
src/
app/
page.tsx # UI: textarea + language selector + diagram
api/analyze/route.ts # backend: validates input, calls the analyzer
components/
CodeInput.tsx # textarea + selector + analyze button
Diagram.tsx # React Flow + dagre rendering
lib/analysis/
types.ts # Graph + LanguageAnalyzer contract
registry.ts # language registry (the only file that knows them all)
treesitter.ts # loads/caches the Tree-sitter runtime + grammars
analyzers/
shared.ts # common call-graph extraction logic
python.ts # Python LangSpec
javascript.ts # JS/TS LangSpec
analyzers.test.ts # analyzer tests
public/wasm/ # Tree-sitter runtime + grammar .wasm files
```
## 路线图
有想法吗？[提交一个 issue](https://github.com/DataDave-Dev/weftmap/issues/new/choose)。
适合新手的任务已标记为 [`good first issue`](https://github.com/DataDave-Dev/weftmap/issues?q=is%3Aopen+label%3A%22good+first+issue%22)。
**已完成**
- [x] 支持 Python, JavaScript, TypeScript, Go 和 Rust 的调用图
- [x] SQL schema 图表 (ER / UML)：表、列、PK/FK、关系
- [x] 可插拔的按语言扩展架构（仅需几行代码即可添加一门语言）
- [x] 双语 UI (en/es) 及应用内文档
**下一步** — 需要帮助
- [ ] 更多语言：Ruby ([#13](https://github.com/DataDave-Dev/weftmap/issues/13)), Java ([#14](https://github.com/DataDave-Dev/weftmap/issues/14))
- [ ] 从 registry 驱动 Hero 语言选择标签 ([#15](https://github.com/DataDave-Dev/weftmap/issues/15))
- [ ] 扩大 analyzer 的测试覆盖率 ([#16](https://github.com/DataDave-Dev/weftmap/issues/16))
- [ ] 丰富未找到函数时的空状态体验 ([#17](https://github.com/DataDave-Dev/weftmap/issues/17))
**未来计划**
- [ ] 项目模式：将整个文件夹作为一个完整的图进行分析
- [ ] 节点交互：点击高亮调用者/被调用者，以及函数详情面板
- [ ] 更多图表类型：控制流和模块依赖图
- [ ] 导出图表 (PNG/SVG) 以及可分享的永久链接
- [ ] 更多输入方式：ZIP 上传和 GitHub repo URL
- [ ] 针对大型代码库的性能优化
## 贡献指南
欢迎各种贡献 —— 尤其是对新语言的支持。请阅读
[CONTRIBUTING.md](CONTRIBUTING.md) 以及我们的 [行为准则](CODE_OF_CONDUCT.md)。
简要规则：`main` 分支受保护（需提交 PR，CI 必须通过，且需要一位审查者），
提交记录需遵循 [约定式提交](https://www.conventionalcommits.org/)。
## 许可证
[MIT](LICENSE) © DataDave-Dev
标签：SOC Prime, Tree-sitter, 云安全监控, 代码可视化, 开发工具, 自动化攻击, 调用图分析, 静态分析