github-pr-diff-tree 的 print.ts 完整详解:递归函数如何一步步渲染 PR 目录树
github-pr-diff-tree 的 print.ts 完整详解:递归函数如何一步步渲染 PR 目录树
github-pr-diff-tree 是一款 GitHub Action 工具:它在 Pull Request 下自动评论一条 diff 目录树,把新增、修改、删除、重命名的文件按目录结构可视化展示出来,帮评审者一眼看清变更范围。本文聚焦其渲染核心 src/print.ts,带你完整看懂一个递归函数如何把扁平的文件列表"长"成一棵漂亮的目录树。
上图是 screenshot.png 所示的真实效果:每行文件前带
+/-/空格 标记,目录用├──、└──串联,修改文件还会标注M +37, -2这样的增删行数。
一、print.ts 在整个项目中的位置
整个工具的数据流非常简单,共三步:
| 步骤 | 模块 | 职责 |
|---|---|---|
| 1. 获取 diff | src/main.ts | 调用 GitHub API 拉取 PR 的原始 diff 文本 |
| 2. 解析 | src/parse.ts | 把 diff 文本解析成 File[] 数组 |
| 3. 渲染 | src/print.ts | 把 File[] 渲染成目录树字符串 |
其中 File 的结构定义在 src/types.ts,每个文件记录 added / deleted / modified / renamed 四种类型、源路径、目标路径以及增删行数。print.ts 的任务就是:拿到一份扁平的 File[],输出一棵可阅读的文件目录树。
入口函数只有 5 行(src/print.ts):先调用 build() 把文件列表组装成树,再调用 formatEach() 递归渲染成字符串。
二、树形数据模型:两种节点
print.ts 用 TypeScript 的类型系统优雅地描述了树节点(src/print.ts):
- FileNode:
type: 'file',带有mark(行首标记符号)和meta(括号里的元信息,如M +1, -0); - DirectoryNode:
type: 'directory',带有parent和children,可以自嵌套,天然形成树结构。
两种节点通过联合类型 TreeNode 合并。文件还配了两个"工厂函数" createDirectoryNode / createFileNode,用默认值展开的方式创建节点,保证字段齐全。
💡 这种"文件 + 目录"两种节点的建模方式,是渲染目录树类工具的经典范式,值得新手记住。
三、build():把扁平列表组装成树
build()(src/print.ts)负责"建树",核心思路非常朴素:
- 创建一个名为
.的根目录节点; - 遍历每个
File,取其路径(删除文件用from,其余用to)按/切成段; - 用
while循环从根节点逐层向下找(或创建)同名子目录,最后把文件节点挂到当前父节点上。
这里有三个值得学习的细节:
- 懒创建目录:只有当
children里找不到同名目录时才新建(src/print.ts),天然实现"目录去重"; - 路径最后一段是文件名:先用
parts.pop()取出,剩下的才是目录层级; - 元信息在此刻生成:调用
formatFileMeta()和formatFileMark()计算好meta与mark,渲染阶段就不用再关心业务逻辑。
四、核心亮点:formatEach 递归渲染
真正"渲染"的是 formatEach()(src/print.ts),这是全文递归函数的灵魂:
const formatEach = (nodes: TreeNode[], prefix: string): string => {
// 遍历当前层每个节点,拼接 "标记 + 连线 + 名称"
// 遇到目录节点时:递归调用 formatEach(node.children, next)
}
递归拆解:三个关键变量
| 变量 | 含义 | 说明 |
|---|---|---|
prefix |
本层缩进前缀 | 递归时逐层累加,控制深度缩进 |
edge |
是否为最后一个子节点 | 决定用 └── 还是 ├── 连线 |
next |
下一层的前缀 | 末位节点补 4 个空格,否则补 │ 竖线 |
递归终止条件在哪里?
新手学递归最怕"什么时候停"。这里的终止条件是隐式的:循环只对 node.type === 'directory' 的节点递归(src/print.ts),而文件节点没有 children,递归到文件这一层自然停止。整个 formatEach 没有 base case 判断,靠"文件不再递归"这一数据特性收束——这是递归渲染树形结构的惯用技巧。
递归展开示例
以测试用例中的目录结构(tests/print.test.ts)为例,递归调用过程如下:
formatEach(根节点.children, '')
├─ dir1/ → 目录,递归 formatEach(dir1.children, '│ ')
│ └─ file1 → 文件,停止
└─ dir2/ → 目录,递归 formatEach(dir2.children, ' ')
最终拼接出:
.
├── dir1/
│ └── file1 (M +1, -0)
└── dir2/
└── file2 (A)
🎯 记住这个模式:遍历当前层 → 输出自己 → 把"更深的前缀"交给递归处理下一层。缩进、连线全部由
prefix参数传递,函数本身保持无状态,极易测试。
五、标记与元信息:行首符号从哪来
渲染出的每个文件行都由两部分组成,分别在两个小函数中计算:
- formatFileMark:新增文件
+、删除文件-、其余空格——对应截图里绿/红高亮的第一列; - formatFileMeta:
- 新增 →
A,删除 →D - 修改 →
M +N, -N(二进制文件只显示M) - 重命名 →
R ../old/oldname,用path.relative算出相对原位置的旧路径
- 新增 →
这两个函数把"业务判断"从"字符串拼接"中剥离出来,是典型的职责分离写法。
六、测试如何守护这段递归逻辑
tests/print.test.ts 用两个用例覆盖了核心路径:
- simple:混合修改/新增/删除/重命名 5 个文件,断言整棵树的文本输出逐字符相等,验证了
│竖线续接、└──收尾、缩进对齐等所有递归细节; - binary:单个二进制修改文件,验证元信息降级为
M的分支(src/print.ts)。
纯函数 + 字符串输出的设计,让 print() 可以脱离 GitHub API 直接做快照式断言,这也是该仓库 package.json 中 npm test(jest)能稳定跑通的原因。
七、总结:从这棵目录树能学到什么
- 建树(build)与渲染(formatEach)彻底分离:前者处理数据组织,后者只管字符串拼接,互不污染;
- 递归的核心是"传递更深的上下文":
prefix参数携带缩进信息,让每一层代码都极简; - 终止条件可以藏在数据结构里:文件节点无子节点,递归自然停止,无需显式判空;
- 工厂函数 + 联合类型让节点创建与类型约束清晰可靠。
配合 action.yml 配置与 README.md 中的工作流示例,这个不到 150 行的文件就是一个"小工具如何把复杂输出写清楚"的教科书级范例——值得每一个写 CLI、写渲染模块的同学读一读 src/print.ts。
