Skip to content

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

Code Gene Graph(代码基因图谱)

在线演示: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["大模型消费端"]
Loading

一句话分层原则:静态分析负责「抽」,JSON 负责「传」,前端只消费不重复解析——graph.json 是分析引擎与前端之间唯一的交接物。schema 设计时预留了第二个消费者(函数节点自带 signature / body,可作为替代全量代码的结构化上下文),实验尚未实施。

scanner 内部流程

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"]
Loading

为什么版本链和读不在扫描时顺手做:建版本节点需要先知道一个变量总共被写几次(扫描到一半不知道);读要连到「读那一刻的最新版本」(得等所有版本节点建完才能查)。每一拍的完整细节见 docs/3. 解析引擎开发流程.md ⓪ 节。

前端渲染流程

flowchart LR
    G["读入 graph.json"] --> M["拼数据流<br/>「变量→函数→变量」两段<br/>按操作编号拼回一段"] --> L["算坐标<br/>数据流越深的变量越靠右<br/>同文件的变量排同一条水平带"] --> N["组装节点<br/>变量/文件 + 函数节点<br/>类型子节点按需出现"] --> R["渲染与交互<br/>点击展开信息卡片<br/>拖动微调、缩放看全貌"]
Loading

完整版(含函数节点放置与手动微调的覆盖时机)见 docs/1. 图谱页面开发流程.md ⓪ 节。

核心能力

静态分析引擎(src/scanner.ts)

  • 底座能力分层:ts-morph 并非单纯一棵语法树,而是三层能力叠放:纯 AST 语法树仅处理本文件节点遍历;类型推断依赖 TypeChecker;跨文件查找变量全项目引用必须调动最底层的语言服务(Language Service)。厘清物理开销,各扫描趟的落点才得以稳定
  • 统一数据流模型:任何一条赋值语句都按「输入 → 操作 → 输出」建模,新声明与改写共用同一套边语言(transforms / produces 两段式),全图只有一种数据流语义;图谱 schema 历经六代演进,每一代的推翻理由与排除项留档于架构演进日志
  • 操作编号配对(opId):函数一次执行多次写操作时,早期因缺乏操作归属字段,前端单值表覆盖引发严重缺陷:渲染看着完全正常,但 128 条输入边静默错配。排查定位后,给同一次操作的所有边(链边、产出边、读边)绑定共享递增编号进行严格配对,并用 fixture 锁死断言;当前快照 46 个操作组、98 条带编号边
  • 变量版本链:每次写产出一个版本节点、按行号排链;每次读对版本链查询表二分,定位「读时活着的那个版本」(读早于首次写落回基节点)。当前为平衡交付速度的工程化近似(行号序在循环、跨函数下失真);其通向显式控制流图(CFG)的多种语法解耦图纸已完整推导闭环,留档于 想法/6. 数据流分析终局认知与工程落地指南.md
  • 建节点口径收敛:最初对所有局部变量建模,图瞬间膨胀至 245 节点且同名冲突不断。后收敛为只有函数体顶层与模块顶层的声明建节点——嵌套块临时变量出块即死、跨块流动必经外层变量,同名冲突在词法上自然消除;口径变更使图从 245 节点干净收敛至 74
  • 统一读解析趟:读的发现、解析、连线收敛为版本链建成后的一趟;for-of 迭代对象、方法调用实参、return 读、非函数调用 RHS 的输入统一收集

图布局与交互(React Flow 前端)

  • 零布局库依赖(两轴分治):早期直接依赖通用 Dagre 全托管布局,在真实大图上遭遇严重的连线横穿与节点重叠。「文件归属水平带 / 数据流从左往右深度 / 尽量不交叉」三项约束在二维平面存在天然几何矛盾,通用分层布局库无法表达带内局部排序。最终彻底移除外部布局库,改为纯手写两轴分治(X 轴按 import 阶梯管数据流深度,Y 轴每文件一条水平带管归属)
  • 函数节点纯预测放置:固定节点尺寸使渲染前预测线 = React Flow 真实 Handle 连线(绕开「渲染→测量→重算」的循环与闪烁);四档 x × 七档纵向滑动的矩形碰撞检测,全撞则取重叠面积最小的兜底——锚点红点永远钉在用户看到的那条线上
  • 两级展开:点节点弹信息框(签名 / 类型名),点类型名弹出 type 子节点(按需出现、父动子跟、点自身收起)
  • 交互:节点拖动微调 + 坐标导出、点击 / 拖动手势分流、缩放到全貌可见

测试工程(52 用例全绿)

  • 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)深度结合的实用价值。

1. 从“行号二分近似”到“显式控制流(CFG)的 22 种语法闭环”

  • 现状与瓶颈:当前引擎在处理分支、循环与回环时采用行号二分近似(resolveReadSource),导致面对复杂语法需针对 for-of、return 等逐个打补丁。
  • 已推导演进蓝图(详见 想法/6):
    • 正交解耦:将“语法结构拓扑(轨道工)”与“变量读写识别(水管工)”彻底分离;
    • 22 种语法标准拆解:对齐 ESLint CodePathAnalyzer 与 CodeQL 工业规范,建立包含 If、While、三元、短路、for-of 等 22 种全量控制流的下一步(Next)连接规则;
    • 循环三条线模型:确立“初值进、自身改(反馈回环)、结果出”的极简因果模型,无需按次数展开循环,在 150 行轻量 Visitor 下即可实现对循环与分支读写的 100% 精确对齐。

2. 面向 LLM / Code Agent 的结构化代码上下文引擎

  • 核心痛点:当前 AI 编程(如 Cursor、Devin、代码智能体)处理大型仓库时,将整个文件倾倒进上下文,既浪费大量 Token,又极易在长文本中迷失、产生幻觉(读错变量定义、改错函数调用)。
  • 图谱落地价值:
    • 精确因果剪枝:当 Agent 试图修改或理解某个变量时,无需通读几千行代码,直接沿着图谱的 transforms / produces 链向前追溯它的“基因血统”(谁产生、谁修改);
    • 轻量级结构化 Prompt:以高信息密度的拓扑 JSON 替代原始文本,实现 Token 消耗降低,同时提供确定性的依赖导航;
    • 两端消费架构落地:打通 graph.json 向大模型消费端的输入接口,使图谱不仅能“给人看(React Flow)”,更能“给 Agent 用”。

3. 读捕获与作用域扩展

  • 闭包跨作用域捕获:将闭包函数体构建为独立子图,把外部变量读取标记为自由变量(Free Variable)引用;
  • 语句级调用实参消费 与 if 条件读收集:补齐非赋值位的数据消费,消除伪最终产出。

项目状态(2026-09-07)

里程碑 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 测试框架

前端(reactflow-preview)

依赖 版本 用途
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 历史草稿污染;碰壁后彻底断舍离,收敛为以代码实测为第一基准的“四级真理阶梯”与“因果脱水先行”沟通准则。

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages