在线演示:https://code-gene-graph.pages.dev —— scanner 扫描自身源码生成的「项目基因图谱」,交互完整可玩。
市面上的代码图谱大多停留在文件 import 依赖或类与函数调用关系,但排查业务逻辑时,人真正关心的是**“某个核心变量到底在第几行被谁改了、改完后下游又是谁读到了这个版本”**。
本项目用 TypeScript AST 静态分析把源码里的变量数据流抽成一张可交互图谱:谁产出了变量、谁消费了它、经过哪些函数变换、版本如何推进。分析引擎输出结构化 JSON,前端用 React Flow 渲染。
flowchart LR
SRC["TS 源码目录"] -->|ts-morph 静态分析| SCAN["scanner<br/>三轮扫描 + 两步收尾"]
SCAN --> JSON["graph.json<br/>四类节点 · 五种边"]
JSON --> UI["React Flow 前端<br/>可交互图谱"]
JSON -.设计预留,实验未实施.-> LLM["大模型消费端"]
一句话分层原则:静态分析负责「抽」,JSON 负责「传」,前端只消费不重复解析——graph.json 是分析引擎与前端之间唯一的交接物。schema 设计时预留了第二个消费者(函数节点自带 signature / body,可作为替代全量代码的结构化上下文),实验尚未实施。
flowchart LR
R1["第 1 轮 · 扫文件<br/>每个文件一个节点<br/>import 关系连成边"] --> R2["第 2 轮 · 扫函数<br/>每个函数(含嵌套)<br/>各建一个节点,存签名与函数体"]
R2 --> R3["第 3 轮 · 扫变量<br/>顶层的变量各建节点<br/>记录每一次写操作"]
R3 --> V["建版本链<br/>变量每被写一次<br/>产出一个新版本节点"]
V --> P["读解析<br/>每次读连到<br/>读那一刻的最新版本"]
P --> F["打包输出 graph.json"]
为什么版本链和读不在扫描时顺手做:建版本节点需要先知道一个变量总共被写几次(扫描到一半不知道);读要连到「读那一刻的最新版本」(得等所有版本节点建完才能查)。每一拍的完整细节见 docs/3. 解析引擎开发流程.md ⓪ 节。
flowchart LR
G["读入 graph.json"] --> M["拼数据流<br/>「变量→函数→变量」两段<br/>按操作编号拼回一段"] --> L["算坐标<br/>数据流越深的变量越靠右<br/>同文件的变量排同一条水平带"] --> N["组装节点<br/>变量/文件 + 函数节点<br/>类型子节点按需出现"] --> R["渲染与交互<br/>点击展开信息卡片<br/>拖动微调、缩放看全貌"]
完整版(含函数节点放置与手动微调的覆盖时机)见 docs/1. 图谱页面开发流程.md ⓪ 节。
- 底座能力分层:ts-morph 并非单纯一棵语法树,而是三层能力叠放:纯 AST 语法树仅处理本文件节点遍历;类型推断依赖 TypeChecker;跨文件查找变量全项目引用必须调动最底层的语言服务(Language Service)。厘清物理开销,各扫描趟的落点才得以稳定
- 统一数据流模型:任何一条赋值语句都按「输入 → 操作 → 输出」建模,新声明与改写共用同一套边语言(transforms / produces 两段式),全图只有一种数据流语义;图谱 schema 历经六代演进,每一代的推翻理由与排除项留档于架构演进日志
- 操作编号配对(opId):函数一次执行多次写操作时,早期因缺乏操作归属字段,前端单值表覆盖引发严重缺陷:渲染看着完全正常,但 128 条输入边静默错配。排查定位后,给同一次操作的所有边(链边、产出边、读边)绑定共享递增编号进行严格配对,并用 fixture 锁死断言;当前快照 46 个操作组、98 条带编号边
- 变量版本链:每次写产出一个版本节点、按行号排链;每次读对版本链查询表二分,定位「读时活着的那个版本」(读早于首次写落回基节点)。当前为平衡交付速度的工程化近似(行号序在循环、跨函数下失真);其通向显式控制流图(CFG)的多种语法解耦图纸已完整推导闭环,留档于
想法/6. 数据流分析终局认知与工程落地指南.md - 建节点口径收敛:最初对所有局部变量建模,图瞬间膨胀至 245 节点且同名冲突不断。后收敛为只有函数体顶层与模块顶层的声明建节点——嵌套块临时变量出块即死、跨块流动必经外层变量,同名冲突在词法上自然消除;口径变更使图从 245 节点干净收敛至 74
- 统一读解析趟:读的发现、解析、连线收敛为版本链建成后的一趟;for-of 迭代对象、方法调用实参、return 读、非函数调用 RHS 的输入统一收集
- 零布局库依赖(两轴分治):早期直接依赖通用 Dagre 全托管布局,在真实大图上遭遇严重的连线横穿与节点重叠。「文件归属水平带 / 数据流从左往右深度 / 尽量不交叉」三项约束在二维平面存在天然几何矛盾,通用分层布局库无法表达带内局部排序。最终彻底移除外部布局库,改为纯手写两轴分治(X 轴按 import 阶梯管数据流深度,Y 轴每文件一条水平带管归属)
- 函数节点纯预测放置:固定节点尺寸使渲染前预测线 = React Flow 真实 Handle 连线(绕开「渲染→测量→重算」的循环与闪烁);四档 x × 七档纵向滑动的矩形碰撞检测,全撞则取重叠面积最小的兜底——锚点红点永远钉在用户看到的那条线上
- 两级展开:点节点弹信息框(签名 / 类型名),点类型名弹出 type 子节点(按需出现、父动子跟、点自身收起)
- 交互:节点拖动微调 + 坐标导出、点击 / 拖动手势分流、缩放到全貌可见
- Vitest + fixture 分层:复合 fixture 测核心数据流(同组用例共享一次扫描),最小 fixture 测边界场景(空文件、循环 import、复合赋值不捕获…)
- 三条断言原则:断边存在不断言节点存在(边同时锁存在性与时序)、不依赖边 id(顺序随 ts-morph 版本漂移,按 source/target/label 三元组查找)、不断言总数
- fixture 不可变契约:测新场景只增不改,旧锁定被新语义取代走显式流程
- 等值比对验收:行为不变的重构做三层比对(节点集 / 忽略编号的边多重集 / 配对组结构)
- scanner 扫自己的源码:每个新需求用「扫自己」核对节点 / 边 / 版本数 / 断头边,基线变迁全程留痕(201 → 245 → 74 → 103)
- 当前快照 103 节点 / 192 边;纯静态部署(Cloudflare Pages),线上为手动定格快照——不连 git 自动部署,开发中的中间状态不上线
诚实清单——每条有代码注释或文档条目为据。分三类的意义:第一类是取舍不会默认消失,第二三类是未来方向的直接来源。
- 函数体内数据流不展开:操作者粒度是函数级——「这个值是谁创造的」以函数为答;实参→函数体→返回值的完整流程压扁成一条边。连带三个同根场景(形参绑定、return 读的粗糙匹配、函数体内数据流),要突破必须重开调用点粒度决策、三场景一起评估
- 嵌套块临时变量不建模:for 头 / 循环体 / if 块里的声明只建模与外层变量的交换,不展开块内计算链
- 不追外部库:外部函数内部数据流是黑盒,实参读由「向上追溯为包着声明的函数」承载
- 不做指针 / 别名级追踪:容器作实参传入、在被调函数体内经参数修改——名字分析追不进参数别名;数据流完整性目标限定为「凡能用名字追到的搬运都有边」
- 遮蔽粗糙:内层块声明与外层同名临时变量时,按名查表会把内层的读记到外层头上(名字级查表的天生缺陷)
- 异步时序:
await fn()产出 Promise 而非最终值,会造成假边 - 复合赋值(
+=)与下标写入(x[i] = v)未捕获为写 - 匿名函数 / 箭头函数实参会被按全局变量处理
- 部分读姿势未收集:闭包跨作用域引用(会失真漏收)、语句级调用实参(方案已定稿)、if 条件读(挂载语义待推导)、for-of 变异写的迭代对象(修法已知)
- .tsx 内部数据流建模(箭头函数组件 / hooks 闭包):已纳入扫描范围,只出文件骨架
本项目的演进不追求盲目的功能堆砌,而是沿着两条清晰的主线生长:一条通向更严密的静态分析底座,一条通向与大模型(AI Code Agent)深度结合的实用价值。
- 现状与瓶颈:当前引擎在处理分支、循环与回环时采用行号二分近似(
resolveReadSource),导致面对复杂语法需针对for-of、return等逐个打补丁。 - 已推导演进蓝图(详见
想法/6):- 正交解耦:将“语法结构拓扑(轨道工)”与“变量读写识别(水管工)”彻底分离;
- 22 种语法标准拆解:对齐 ESLint
CodePathAnalyzer与 CodeQL 工业规范,建立包含If、While、三元、短路、for-of等 22 种全量控制流的下一步(Next)连接规则; - 循环三条线模型:确立“初值进、自身改(反馈回环)、结果出”的极简因果模型,无需按次数展开循环,在 150 行轻量 Visitor 下即可实现对循环与分支读写的 100% 精确对齐。
- 核心痛点:当前 AI 编程(如 Cursor、Devin、代码智能体)处理大型仓库时,将整个文件倾倒进上下文,既浪费大量 Token,又极易在长文本中迷失、产生幻觉(读错变量定义、改错函数调用)。
- 图谱落地价值:
- 精确因果剪枝:当 Agent 试图修改或理解某个变量时,无需通读几千行代码,直接沿着图谱的
transforms/produces链向前追溯它的“基因血统”(谁产生、谁修改); - 轻量级结构化 Prompt:以高信息密度的拓扑 JSON 替代原始文本,实现 Token 消耗降低,同时提供确定性的依赖导航;
- 两端消费架构落地:打通
graph.json向大模型消费端的输入接口,使图谱不仅能“给人看(React Flow)”,更能“给 Agent 用”。
- 精确因果剪枝:当 Agent 试图修改或理解某个变量时,无需通读几千行代码,直接沿着图谱的
- 闭包跨作用域捕获:将闭包函数体构建为独立子图,把外部变量读取标记为自由变量(Free Variable)引用;
- 语句级调用实参消费 与 if 条件读收集:补齐非赋值位的数据消费,消除伪最终产出。
里程碑 1「自解析演示成形」达成:演示站点上线并经线上验收;分析引擎 52 个测试用例全绿(fixture 锁定核心行为),scanner 封版。详细进度与方向见 docs/2,待办清单不进 README(归 docs)。
环境要求:Node.js ≥ 20(推荐 22 LTS)。
# 安装(两个独立工程,各装一次)
npm install # 根工程:分析引擎 + 测试
cd reactflow-preview && npm install # 前端:可视化
# 使用
npm run scan # 扫 samples 演示数据 → graph.json
npm run scan src # 自解析:扫自己的源码
npm test # 跑全部用例(vitest)
# 前端
cd reactflow-preview
npm run dev # 本地预览图谱
npm run build # 构建静态站点(产物 dist/)| 依赖 | 版本 | 用途 |
|---|---|---|
| ts-morph | ^28.0.0 | AST 分析与语言服务(引用查找、类型推导) |
| tsx | ^4.23.0 | 直接运行 TS 脚本(CLI 入口) |
| typescript | ^7.0.2 | TS 编译与类型检查 |
| vitest | ^2.1.0 | 测试框架 |
| 依赖 | 版本 | 用途 |
|---|---|---|
| react / react-dom | ^18.3.1 | UI 框架 |
| @xyflow/react | ^12.3.5 | 图可视化(React Flow) |
| vite | ^5.4.11 | 构建工具 |
| typescript | ^5.6.3 | 前端 TS 编译 |
src/ 分析引擎(scanner.ts 核心 + cli.ts 入口 + scanner.test.ts)
tests/fixtures/ 测试 fixture(锁定各行为的示例代码,不可变契约)
samples/ 演示样例(独立于测试语料)
reactflow-preview/ 前端可视化工程
docs/ 项目文档(1 图谱页面 / 3 解析引擎 / 8 价值盘点 / 10 回顾讲述 等)
.agent/ 人机协作治理体系(宪法 AGENTS.md + 活文档模板 + 作业流技能)
想法/ 架构演进日志(真实碰壁数据与排除项留档)
设计/ 布局概念图源文件(Excalidraw)
verify-b3/ 等值比对脚本(scanner 重构验收工具)
_归档/ 历史史料(原始手记、旧版协作规则存档等,冻结不动)
docs/10. 回顾讲述.md:全景技术复盘长文——从动机、ts-morph 三层能力、Dagre 几何矛盾、128 条错配排查、到 CFG 蓝图与两轴分治前端演进的完整脉络。docs/:模块活文档体系——1. 图谱页面开发流程.md与3. 解析引擎开发流程.md(顶层定义拍数地面真相与模块红线,下方承载当前需求与待办)。想法/3. 架构演进日志.md:只增不改的编年史——记录每一次碰壁的真实数据、推翻的假设与排除项。.agent/:57 天人机协同中踩坑提炼的通用治理体系——早期设计了 15 个细分规则、检查点和“提交即确认”等教条,实际开发中发现流于官僚且易导致 AI 历史草稿污染;碰壁后彻底断舍离,收敛为以代码实测为第一基准的“四级真理阶梯”与“因果脱水先行”沟通准则。