Plate 仓库覆盖率优先级地图：bun coverage 驱动的单元测试投入排序方法论

Plate 仓库覆盖率优先级地图：bun coverage 驱动的单元测试投入排序方法论

【免费下载链接】plateRich-text editor with AI and shadcn/ui项目地址: https://gitcode.com/GitHub_Trending/pl/plate

本文围绕 Plate 仓库中的一份"覆盖率优先级地图"（Coverage Priority Map）计划文档展开，讲解如何基于bun test --coverage生成的 lcov 覆盖率数据，为富文本编辑器 monorepo 中数十个包、数百个文件排定"下一个最值得补测"的优先级。读完本文，你将掌握一套可复用的测试投入排序方法：既包括评分规则的完整设计，也包括"从原始包总量陷阱中识别真实缝隙文件"的判断标准，以及文档中列出的 12 个高分待测文件对应的源码实态。

这份文档是什么：一张"测试优先级地图"

docs/plans/2026-03-24-coverage-priority-map-post-mixed-utility.md是 Plate 仓库docs/plans/下"测试优先级地图"系列中的一份快照文档，元信息显示其类型为testing、日期为 2026-03-24、状态为completed。它的职责非常单一且明确：在最近一轮混合工具类（mixed utility）覆盖批次之后，回答"下一个最值得补测的文件和包在哪里"。

该文档属于一个持续迭代的文档序列，同目录下还有 2026-03-24-coverage-priority-map.md、2026-03-24-coverage-priority-map-post-check.md、2026-03-24-coverage-priority-map-post-gte-5.md、2026-03-24-coverage-priority-map-post-threshold-5b.md 等。每一份都在上一轮执行后重新对覆盖率数据打分，形成"执行 → 重测 → 重打分"的闭环节奏。与之配套的还有执行类文档，例如 2026-03-24-mixed-utility-coverage-batch.md 与 2026-03-24-non-react-coverage-roadmap.md，前者描述本快照之前的执行批次，后者描述非 React 代码的整体覆盖率路线图。

理解这份文档的关键在于：它不是一份通用测试教程，而是一份针对 Plate 仓库当前测试资产状态的"投资排序建议"——哪些文件补测试的性价比最高，哪些只是低信号碎屑（low-signal crumbs），哪些虽然覆盖率数字难看但不值得 reopen。

输入约束：什么样的覆盖率数据才值得信

文档在最开始就定义了输入，这决定了后续一切判断的有效范围：

• 覆盖率数据源：lcov.info（由--coverage-reporter=lcov生成，输出到.coverage-repo-2026-03-24d/目录）。
• 四项约束：
  1. exclude/react：React 相关目录整体排除，因为组件/钩子层需要的是交互测试或浏览器级测试，不适合混入单元测试评分；
  2. no coverage vanity（不做覆盖率虚荣）：不允许为了把数字刷高而给不值得的文件补测试；
  3. score only files worth real unit or editor-contract tests：只对"值得真实单元测试或编辑器契约测试"的文件打分；
  4. penalize recently swept packages：对刚被清扫过的包施加惩罚分，避免"刚清过的残渣"挤占"从未碰过的缝点"。

这四条约束合在一起，构成了整套评分体系的哲学基础：覆盖率数据是手段，找出"真正有逻辑价值且尚未被覆盖"的确定性代码才是目的。这与 Plate 仓库中大量围绕"editor-contract"（编辑器契约）展开的测试思路一脉相承——例如 2026-03-23-markdown-contract-coverage-pass.md 与 2026-03-17-core-contract-lane.md 都体现了一致的取向。

复现覆盖率快照：bun test --coverage的完整用法

文档给出了生成该快照的原始命令，可以直接复现：

bun test --coverage --coverage-reporter=lcov --coverage-dir=.coverage-repo-2026-03-24d --reporter=dots

逐项拆解：

该快照的实测结果为：2750 pass、0 fail、541 files、2.53s。需要说明的是，这是 2026-03-24 时点的历史数据，适合用于理解方法而非衡量当前仓库状态；覆盖率产物目录属于生成物，未随仓库提交。

快照之后的分析链路是：把 lcov 数据按packages/**/src/**范围聚合到文件和包两级，再套用评分规则打分，最终产出"文件级"与"包级"两张排序清单（详见后文"完整数据"一节）。

评分规则：如何给一个文件打 0～7 分

范围与归零规则

评分作用域是packages/**/src/**。以下类别直接计0 分，因为它们要么不是单元测试的正确作用对象，要么是自动生成的低信号文件：

仓库中可以找到大量这类典型样本：例如 docx 的 utils barrel 首行注释明确写着 "Automatically generated by barrelsby"，是标准的自动生成 barrel；markdown 包的 mdast.ts 则几乎全是mdast相关类型的再导出（export type { ... } from 'mdast'），属于 type-only 文件。

加分特征

相反，以下特征会获得高分：

• 确定性变换（deterministic transforms）：输入输出可预测、无副作用，例如 HTML/RTF 清洗、字符串处理；
• 查询函数（queries）：基于编辑器状态做只读判断的纯逻辑；
• 解析器/序列化器辅助函数（parser or serializer helpers）：如 markdown、docx 的解析辅助；
• 插件覆写（plugin overrides）：createSlatePlugin中注入的parse、query、transformData等确定性缝点；
• 小而纯的工具函数（small pure utilities）：带有未被覆盖的有意义分支逻辑。

归零与惩罚机制

• 微小残留缺口直接归零：当某文件只剩"不值得为它重新打开（reopen）"的极小缺口时，不打分；
• 近期清扫惩罚：刚被 sweep 过的包即使还有零散缺口，也要在排名上让位于从未被清扫的缝点，防止"打扫过的房间里的碎屑"挤掉"从未打扫的房间"。

这套规则的直接产物就是文档中的 12 个"最佳待测文件"，分数范围 4～7 分，全部符合"确定性逻辑 + 有真实未覆盖分支"的特征。

核心判断：不要再做一次大范围包清扫

文档给出一个反直觉的 Strong Take：当前阶段最佳的下一个动作不是又一次大范围包清扫（broad package sweep），而是按以下顺序执行：

1. @udecode/react-hotkeys——仍有未被触碰的纯工具逻辑，且从未接受过同等级的覆盖率清扫；
2. docx二次回访（revisit）——只针对确定性的 cleaner 与插件缝点，属于"回访"而非"新开拓"；
3. 单文件手术式缝点（one-file surgical seams）：
   • toggle/someToggle.ts
   • suggestion/findSuggestionNode.ts
4. 之后才考虑重新打开近期包，如autoformat、markdown、list、list-classic。

理由在文档中写得很直接：大多数其他包的原始总量（raw package totals）被"已清扫残留（already-swept leftovers）、DOM 类粉尘（DOM-ish dust）、低信号碎屑（low-signal crumbs）"所虚增，按总量排名会误导投入方向。下面结合当前仓库源码逐文件验证这条排序。

最佳待测文件逐个拆解（附源码佐证）

@udecode/react-hotkeys：纯逻辑的"处女地"

该包位于packages/udecode/react-hotkeys/，是 monorepo 中维护的 React 快捷键 hook 库，为编辑器表面（工具栏、快捷键绑定）提供按键监听能力。文档认为它"仍有未触碰的纯工具逻辑"，且其src/internal/下确有完整的纯函数层。

1. isHotkeyPressed.ts（@udecode/react-hotkeys，7 分）

这是文档评分最高（7 分）的文件。其核心是一个模块级Set<string>（L30）维护"当前按下的键"：

• 在document上注册keydown/keyup监听，用mapKey(e.code)归一化后推入/移除按键（L3-L28），并忽略e.code === undefined的合成事件（如 Chrome 自动填充）；
• window的blur事件会清空整个按键集合（L23-L27）；
• isHotkeyPressed(key, delimiter = ',')接受字符串或只读数组，按delimiter拆分后全部命中才返回 true，且统一小写比较（L37-L46）；
• pushToCurrentlyPressedKeys处理了一个著名的 macOS 问题：按住 meta 键再按其他键时，浏览器会吞掉 keyup 事件，导致集合残留所有按过的键，因此按下非修饰键时会先清掉集合中的非修饰键（L48-L67）；removeFromCurrentlyPressedKeys在meta抬起时整体清空（L69-L84）。

仓库已经存在针对该文件的测试 isHotkeyPressed.spec.ts，覆盖了逗号分隔字符串/只读数组的大小写不敏感匹配、meta 按住时丢弃陈旧非修饰键、keyup 清理、document 事件驱动、合成事件忽略等 5 个用例——这正是"确定性纯逻辑值得优先补测"的样板。

2. validators.ts（@udecode/react-hotkeys，6 分）

该文件集中了事件合法性的纯判断函数：

• maybePreventDefault：根据preventDefault（布尔或回调）决定是否拦截默认行为（L5-L16）；
• isHotkeyEnabled：enabled为函数时委托调用，否则undefined/true视为启用（L18-L28）；
• isKeyboardEventTriggeredByInput/isHotkeyEnabledOnTag：判断事件是否来自input/textarea/select等表单标签，支持白名单数组或布尔开关（L30-L50）；
• isScopeActive：在没有<HotkeysProvider>却配置了scopes时console.warn并放行，命中活动 scope 或'*'时返回 true（L52-L71）；
• isHotkeyMatchingKeyboardEvent：核心匹配器，支持useKey（按event.key匹配）、修饰键矩阵校验、以及通过isHotkeyPressed(keys)回退到"按键集合"匹配（L73-L136）。

其测试 validators.spec.ts 已覆盖 preventDefault 回调、标签白名单、无 Provider 时的 scope 警告与回退、以及mod/useKey/ignoreModifiers/按键集合回退等匹配分支。这些分支里仍可挖掘的边界（例如keys为空、mappedCode为修饰键时的短路路径）正是 6 分的依据。

3. 底层机制：parseHotkeys.ts 与 useHotkeys.ts

要真正写好上述两个文件的测试，需要理解其依赖链。parseHotkeys.ts提供了键名归一化mapKey（AltLeft→alt、MetaLeft→meta、esc→escape、return→enter等，并剥掉key/digit/numpad前缀，L33-L37）与组合键解析parseHotkey（按+拆分、识别alt/ctrl/meta/mod/shift修饰键，L47-L74）；而 useHotkeys.ts 把以上纯函数接入 React：支持 ref 作用域监听、enableOnFormTags、enableOnContentEditable、ignoreEventWhenPrevented、keyup触发、scope 校验与BoundHotkeysProxy的注册/注销（L45-L248）。由此可以推断：文档把最高分给isHotkeyPressed.ts与validators.ts，是因为它们是这整条事件链中"最纯、最值得单元化"的两块地基。

docx：确定性工具链的二次回访

packages/docx/是 Plate 的 Word 粘贴内容清洗与反序列化插件。文档明确说这是revisit 而非新开拓——"仍有真实的确定性辅助函数价值"。

4. DocxPlugin.ts（docx，6 分）

该插件是缝点集中的地方：

• 通过createSlatePlugin创建，editOnly: true，key 为KEYS.docx（L52-L54）；
• 向KEYS.html插件注入transformData：读取剪贴板text/rtf，调用cleanDocx(data, rtf)清洗后交给 HTML 解析（L55-L73）；
• 覆写p/h1-h6的 HTML 反序列化parse：检测isDocxList后提取indent/listStyleType并重写列表内容 HTML，否则提取getDocxIndent/getDocxTextIndent（L19-L50）；
• 覆写img的parser.query：用DOMParser判断内容是否isDocxContent，决定是否接管图片（L90-L104）。

这些parse/query/transformData都是典型的确定性缝点，且getDocxIndent、getDocxListIndent、getTextListStyleType、isDocxList等辅助函数已位于 docx-cleaner/utils 中，具备独立单元测试的条件。

5. isDocxFootnote.ts（docx，6 分）

一个极简的纯谓词：判断元素是否为 Word 脚注引用——tagName === 'SPAN'且 class 包含MsoFootnoteReference。文档给它 6 分的原因是：它被cleanDocxFootnotes等清洗步骤依赖，是"小而纯、有真实分支"的典型，缺口虽小但值得闭合。

6. cleanDocx.ts（docx，5 分）

清洗管线编排器（L23-L54）：先用preCleanHtml预处理，再按顺序执行cleanDocxFootnotes → cleanDocxImageElements → cleanHtmlEmptyElements → cleanDocxEmptyParagraphs → cleanDocxQuotes → cleanDocxSpans → cleanHtmlTextNodes → cleanDocxBrComments → cleanHtmlBrElements → cleanHtmlLinkElements → cleanHtmlFontElements → cleanDocxListElements → copyBlockMarksToSpanChild，最后用white-space: pre-wrap包裹防止反序列化时折叠空白。它的核心分支是!rtf && !isDocxContent(body)时直接原样返回 HTML（L30-L32）——这个短路分支与整条管线的组合行为，正是 5 分的来源。仓库已存在 cleanDocx.spec.ts 与其慢速对照 cleanDocx.slow.ts，说明该文件处于"已覆盖大部分、剩少量分支"的回访状态。

单文件手术式缝点：toggle 与 suggestion

文档特别强调两个"一个诚实的缝点"（one honest seam），适合做单文件手术而非整包清扫。

7. someToggle.ts（toggle，6 分）

完整实现只有 7 行：editor.selection存在且editor.api.some({ match: n => n.type === KEYS.toggle })时返回 true。这是典型的编辑器查询纯逻辑，其测试 someToggle.spec.ts 已经存在；文档将其列为"仍值得补测的缝点"，说明重点在于围绕selection为 null、范围内含/不含 toggle 节点的分支细化。

8. findSuggestionNode.ts（suggestion，6 分）

findInlineSuggestionNode通过editor.api.node查找第一个带KEYS.suggestion标记的文本节点，并用combineMatchOptions合并调用方传入的附加match过滤（L11-L22）。仓库已有 findSuggestionNode.spec.ts，其用例展示了at: []定位、附加match（如bold）过滤、以及未命中时返回undefined的三种行为——这正是"查询函数 + 真实未覆盖分支"的标准画像。

中低分文件：数据时效性说明

9. autoformat 数学规则（autoformat，5 分×2）

文档列出autoformatSuperscript.ts与autoformatSubscript.ts（packages/autoformat/src/lib/rules/math/下）各得 5 分。需要注意：在当前仓库中，packages/autoformat/仅剩src/index.ts与 src/plugin.ts，后者是一个明确的废弃兼容插件——注释写明AutoformatPlugin"intentionally inert"（刻意空转），建议把 autoformat 行为迁移到各功能插件自身的inputRules上。也就是说，文档引用这两个数学规则文件时它们还存在于源码中，如今已不在。这说明优先级地图是时点快照，引用其文件清单时必须以当前源码为准复核。

10. mdast.ts（markdown，5 分）

文档给它 5 分，但当前仓库中该文件已是纯类型再导出（export type { ... } from 'mdast'、'mdast-util-math'、'mdast-util-mdx'），接近评分规则中的 type-only 类别。这一反差同样说明：快照评分与最新源码可能存在漂移，评分是分析起点而非最终结论。

11. BasePlaceholderPlugin.ts（media，4 分）

基于createTSlatePlugin的 void 元素插件（isElement: true, isVoid: true），通过extendEditorTransforms用bindFirst绑定insertAudioPlaceholder、insertFilePlaceholder、insertImagePlaceholder、insertVideoPlaceholder四个插入变换（L28-L38）。4 分对应"插件覆写缝点但逻辑较薄"的定位。

12. BaseMediaEmbedPlugin.ts（media，4 分）

同样为 void 元素插件，选项层提供transformUrl: parseIframeUrl，并在 HTML 反序列化规则中匹配IFRAME节点、提取src（L13-L40）。其依赖的 parseIframeUrl.ts 是一个小而纯的 URL 解析器：处理非http开头的完整 iframe 嵌入代码（提取 Twitter/X 状态 URL 或src="..."引号内容）——这类纯函数正是评分规则中"parser 辅助"的加分项。

按真实价值排序的包优先级

文档给出的包级排序（按真实价值而非原始总量）：

注意第 5 位autoformat的措辞是"only then reopen"，即它必须排在前面四类工作之后——这与"近期清扫惩罚 + 迁移优先"的约束一致。

原始包汇总数据的陷阱

文档用一节专门警告：原始包总量（raw package totals）会系统性高估以下包的优先级：

• docx
• autoformat
• list
• slate
• list-classic

原因是这些包里"剩下的主要是回访工作、已清扫残留或 DOM 类粉尘"。例如slate包体量大、文件多，原始缺口数自然可观，但其中大量是浏览器重依赖或已被系列文档反复处理过的区域。因此文档的结论是：使用上面按真实价值排序的推荐，而不是裸看总量。这一节是全文方法论上最重要的一课——覆盖率汇总数字必须经过"是否值得真实单元测试"的过滤，否则会把投入引向低信号区域。

暂缓名单：为什么这些现在不值得碰

文档明确列出"现在跳过（Skip For Now）"的对象：

• resizable：结构偏 DOM/交互，单元测试性价比低；
• @udecode/cn：工具链薄，无实质未覆盖逻辑；
• @udecode/utils中的纯类型残留（type-only leftovers）；
• DOM 类的slate/internal/dom-editor：浏览器重依赖缝点；
• 没有真实缝点的情况下，重新打开刚清扫过的core、docx-io、basic-styles、selection、emoji。

这份"负面清单"与评分规则中的归零类别一一对应，是防止"为覆盖率而覆盖率"的第二道闸门。结合 2026-03-24-non-react-coverage-roadmap.md 及其后续执行文档（如 2026-03-25-non-react-coverage-roadmap-phase-3.md）可以看出，这类"跳过清单"会随执行进度滚动更新。

完整数据与系列文档的衔接

文档末尾声明"穷举评分"（exhaustive scoring）存放在两个 TSV 数据文件中：

• 2026-03-24-coverage-priority-packages-post-mixed-utility.tsv：每个包的评分汇总（scored package rollup）；
• 2026-03-24-coverage-priority-files-post-mixed-utility.tsv：每个仍值得测试的文件及其分数、覆盖率、未覆盖行号与评分理由。

这两个文件属于该计划文档引用的生成物，未随当前仓库提交；其内容结构可以从计划文档的描述中还原：包级一张表、文件级一张表，字段包含 score、coverage、uncovered lines 与 scoring reasons。若要在最新源码上复现同等粒度，需要重新执行第二节的命令并套用第四节的全部规则。

这份快照在序列中的位置是"post mixed-utility"——前序是混合工具批次（2026-03-24-mixed-utility-coverage-batch.md），后续则有 2026-03-24-coverage-priority-map-post-check.md 等接续文档，体现了"批次执行 → 快照重打分"的滚动节奏。

方法论提炼：如何在自己的仓库复刻这套流程

综合全文，这套"覆盖率优先级地图"可以抽象为 5 个可复刻的步骤：

1. 采集：用bun test --coverage --coverage-reporter=lcov --coverage-dir=<out> --reporter=dots（或其他运行器的 lcov 输出）生成机器可读的覆盖率数据；
2. 过滤：明确排除 React/浏览器重依赖、barrel、生成文件、纯类型文件与测试文件本身，只保留"值得真实单元或契约测试"的作用域；
3. 打分：对确定性变换、查询、解析/序列化辅助、插件覆写与纯工具函数加分；对微小残留缺口归零；对近期已清扫区域施加惩罚；
4. 排序而非盲扫：产出"包级真实价值排序"与"文件级高分清单"，警惕原始总量被已清扫残留与 DOM 粉尘虚增；
5. 滚动更新：每完成一个批次就重新跑一次快照、重新打分，并同步更新跳过清单——优先级地图是活文档，不是一次性结论。

这套方法对任何以 monorepo 组织、以确定性核心逻辑为主、同时存在大量 DOM/React 表面的编辑器类项目都具有直接参考价值：它把"覆盖率数字"从 KPI 式的虚荣指标，重新定义为"找下一个真实测试缝点"的定位工具。

【免费下载链接】plateRich-text editor with AI and shadcn/ui项目地址: https://gitcode.com/GitHub_Trending/pl/plate