让测试规范活起来：lat.md 用 require-code-mention 强制 spec 与测试代码双向引用
【免费下载链接】lat.mdAgent Lattice: a knowledge graph for your codebase, written in markdown.项目地址: https://gitcode.com/gh_mirrors/la/lat.md
lat.md是一个"用 Markdown 写成的代码库知识图谱"工具：它在项目根目录维护一个lat.md/文档目录，通过 wiki 链接把文档章节、源码符号和测试代码串成一张网，再用lat check命令持续校验这张网不会"断链"。其中最有意思的能力是require-code-mention——一个 frontmatter 开关，可以强制要求每一条测试规范（spec）都必须被测试代码中的注释真实引用，从而让 spec 与测试代码形成双向引用，任何一边被遗忘都会立刻报错。
痛点：写在文档里的测试规范，为什么总是没人管？
很多团队把测试规范写在文档里：这个场景要覆盖什么、边界条件怎么断言、异常路径怎么处理。但文档写完就"沉睡"了：
- 代码重构了，文档里的 spec 没人更新，逐渐失真；
- 某条 spec 一直没人写对应测试，但没有任何机制提醒你；
- 新人接手时，分不清哪些规范有测试、哪些只是"写在纸上的愿望"。
lat.md 的思路是：与其指望人自觉，不如把"规范必须有代码实现"变成一条可以被机器校验的约束。
核心机制：一个 frontmatter 开关 + 一行代码注释
整个功能只需要两步，规则在 lat.md/knowledge/markdown.md 中有完整说明。
第 1 步：在 specs 文件头部打开开关
把测试规范写成lat.md/下的 Markdown 文件，每个测试用例就是一个章节（section），然后在文件头部加上 YAML frontmatter：
--- lat: require-code-mention: true --- # Specs ## Must Do X Description. ## Must Do Y Description.这个开关的解析逻辑在 packages/core/src/lattice.ts 中实现——只要检测到require-code-mention: true，该文件的所有叶子章节（没有子章节的章节）就都被视为"必须有代码引用"的规范。
第 2 步：在测试代码里写一条// @lat:注释
在对应的测试代码中，用注释指向规范章节：
// @lat: [[specs#Must Do X]]（Python、PHP 等语言用# @lat:注释。）这样，文档章节和测试代码就互相"认识"了。
双向引用是怎么工作的？
lat check code-refs会做两个方向的校验（见 lat.md/knowledge/cli.md）：
| 方向 | 校验内容 | 抓什么问题 |
|---|---|---|
| 代码 → 文档 | 每条// @lat: [[...]]注释必须指向lat.md/中真实存在的章节 | 注释指向了已删除/写错名字的规范（悬空引用） |
| 文档 → 代码 | 开启require-code-mention的文件中，每个叶子章节必须被至少一条// @lat:注释引用 | 写了规范却从来没人写测试 |
反向校验的核心实现就在 packages/core/src/cli/check.ts：收集全代码库的@lat:引用，再遍历开了开关的文件的每个叶子章节，发现没有任何引用覆盖时，报错：
section "Must Do Y" requires a code mention but none found也就是说：你写了 spec 却没写测试，CI 会直接红给你看；反过来，测试里指向一条不存在的规范，同样报错。这正是"双向"的含义——两边都不敢悄悄漂移。
lat.md 自己的 View 测试规范 lat.md/knowledge/view/specs.md 就是这个机制的活例子：文件头开启开关，几十条 UI 行为规范全部被测试代码中的@lat:注释钉住。该功能的测试用例定义在 lat.md/knowledge/tests/check-code-refs.md，配套的报错场景 fixture 可以直接查看 tests/cases/error-require-code-mention/lat.md/specs.md。
落地三步走：让现有项目的 spec 文件"活"起来
- 安装并初始化：
npm install -g lat.md，在项目里运行lat init生成lat.md/目录（轻量校验场景也可只用@lat.md/core的lat-core check）。 - 把测试规范写成章节：新建
lat.md/specs.md，一个## 标题对应一条规范，头部加上require-code-mention: true。 - 让代码引用规范：在每条测试用例旁加
// @lat: [[specs#规范标题]]注释，然后运行lat check确认全绿。
之后把lat check放进 pre-commit 钩子或 CI（项目自带 GitHub Action，见 action.yml），规范覆盖率就成了每次提交都能看见的指标。
小结
require-code-mention的设计非常克制：一个布尔开关 + 一行注释，就把"文档说有测试、代码里有测试"从口头约定变成了可校验的引用关系。对新手来说，它是理解 lat.md "知识图谱"理念的最佳切入点——知识的价值不在于写在文档里，而在于被持续验证、持续连接。
【免费下载链接】lat.mdAgent Lattice: a knowledge graph for your codebase, written in markdown.项目地址: https://gitcode.com/gh_mirrors/la/lat.md
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
