github-pr-diff-tree 的 print.ts 完整详解:递归函数如何一步步渲染 PR 目录树

原创2026-11-06 14:28:141,876 阅读

github-pr-diff-tree 的 print.ts 完整详解:递归函数如何一步步渲染 PR 目录树

github-pr-diff-tree 是一款 GitHub Action 工具:它在 Pull Request 下自动评论一条 diff 目录树,把新增、修改、删除、重命名的文件按目录结构可视化展示出来,帮评审者一眼看清变更范围。本文聚焦其渲染核心 src/print.ts,带你完整看懂一个递归函数如何把扁平的文件列表"长"成一棵漂亮的目录树。

github-pr-diff-tree 在 PR 评论中渲染的 diff 目录树效果

上图是 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)负责"建树",核心思路非常朴素:

  1. 创建一个名为 . 的根目录节点;
  2. 遍历每个 File,取其路径(删除文件用 from,其余用 to)按 / 切成段;
  3. 用 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 用两个用例覆盖了核心路径:

  1. simple:混合修改/新增/删除/重命名 5 个文件,断言整棵树的文本输出逐字符相等,验证了 │ 竖线续接、└── 收尾、缩进对齐等所有递归细节;
  2. 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。

登录后查看全文
github-pr-diff-tree