让测试规范活起来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.mdlat.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），仅供参考