DSH VERTICAL KIT · DEFECT LEDGER

17 个检测器缺陷

这 22 个检查里,有 19 条规则曾经量的是拼写而不是性质:规则要求某一种写法,而真实文档用的是另一种同样合法的写法,于是对每一份真实文档都报错。或者反过来——规则写得永远触发不了,测试却绿着。

下面每一条都写了:复现输入、当时的判定、现在的判定、以及它是怎么被找出来的。这些声称不是自述——test/defects.test.js 会把每条复现输入喂给当前的代码,误报的那条必须不再出现,死规则的那条必须出现,行号必须落在标题上。页面里说的和代码里做的,只能是一件事。

按发现方式

分布值得单独看一眼:16 条靠把检查器指向真实文件发现,3 条靠规则审计扫出。两种方法各自找到的那批,另一种都找不到——语料找"对真实文件误报",审计找"规则本身没被验证过"。

全表

#检查 / 规则当时的判定现在的判定为什么发现方式 / 修复版本
1 commit-msg-check
type-missing
error, on 85 of 102 real commits (83%) warn — the Conventional Commits prefix is a house style, not a git requirement A default error blocked a codebase that was fine, including every Chinese subject, which has no English type word to offer. own history
0.2.0
2 onboarding-check
success-missing
error, on 20 of 23 real READMEs a real-output section counts, and only this check’s own output is masked Every one of those READMEs showed verbatim CLI output under 真实输入输出. The rule wanted a heading that said 你应该看到. own READMEs
0.2.0
3 release-notes-check
version-missing
error, on 3 of 3 real CHANGELOGs `## [1.2.0] - 2026-11-17` is a version heading That is the heading Keep a Changelog prescribes. A format check that rejects the standard format is measuring its own spelling. own CHANGELOGs
0.2.0
4 pr-description-check
what-missing / why-missing / test-missing
errors, on 19 of 19 real merged PRs a bullet list is “what”, a named test count is “how verified”, and motive is a warning because it is not decidable Every body answered all three questions in prose. Requiring the headings reported the whole set as empty. merged catalog PRs
0.2.0
5 adr-check
consequences-unlabelled
warn, on ADRs that labelled the trade on its own line the whole consequences section is read, not just its bullets 「好处:」 written above the bullets is how a real ADR reads. own ADRs
0.2.0
6 ops-runbook-check
steps-missing
error, on 2 runbooks that order their steps as `## 3. …` headings a numbered heading is a step, and it carries its section body Both were reported as having no steps at all. The destructive-command rule also had to learn to read the body under the heading. own runbooks
0.2.0
7 commit-msg-check
subject-empty
dead rule — never fired on any input `feat:` with no subject now reports subject-empty The header pattern required `.+` after the colon, so `feat:` never parsed as a type and the rule could not be reached. The test written to prove it fires proved the opposite. rules audit
0.3.0
8 listing-check
sku-empty
dead rule — an empty SKU cell was reported as a missing column a present-but-empty SKU column reports sku-empty `pick()` deliberately skips empty values so a blank price reads as a missing price; that conflated "no column" with "empty cell". rules audit
0.2.0
9 pr-description-check
breaking-without-migration
error, on 2 PRs whose bodies described a checker only a line-start declaration counts The bodies said «breaking changes announced in a `BREAKING CHANGE:` trailer» — describing the package, not declaring a break. merged catalog PRs
0.2.0
10 env-example-check
literal-value
error on https://remote.example.edu/… — a documented example URL reserved example domains and loopback hosts are placeholders Flagging correct documentation is how a file gets deleted from CI instead of fixed. third-party .env.example
0.2.0
11 onboarding-check
command-missing
error on a README whose only pasteable line was `dsh plugin add dsh-bot` `dsh` is a command 216 files across the ecosystem use that form. A tool for DSH that does not recognise `dsh` is measuring its own vocabulary. third-party READMEs
0.3.0
12 onboarding-check
success-missing
error on a README that states its success cue in a shell comment a shell comment inside an install block is the author speaking The fix for defect 2 masked every fenced block, which threw away what real READMEs actually say. Self-inflicted: the fix for one defect created the next. third-party READMEs
0.3.0
13 outline-lint
empty-heading
dead rule — `##` alone was never parsed as a heading a heading with its text deleted reports empty-heading The rule existed for exactly that case. Found in the second kit, by pointing the same audit at it. rules audit
0.1.4
14 license-check
copyright-year-missing / copyright-holder-missing
errors on 4 correct files, pointing at Apache-2.0’s definitions line a notice has a shape; «the copyright owner» in prose is not one The rule took the first line containing the word. In Apache-2.0 that is `"Licensor" shall mean the copyright owner…`. third-party LICENSE files
0.2.0
15 license-check
placeholder-left
two errors on an unfilled Apache appendix severity follows the license: MIT/BSD/ISC expect the notice filled; Apache/MPL/GPL ship the appendix as a template The first attempt demoted every appendix slot and broke the MIT case, where a missing year is a real defect. The mapping is by license, not by the shape of the line. third-party LICENSE files
0.2.0
16 release-notes-check
order
error on a changelog that re-lists an unreleased alpha in a collapsed `<details>` appendix the appendix is masked; ordering is judged on the main timeline The same repository’s English changelog puts the entry outside any `<details>`, and that one is a genuine ordering break — reported. third-party CHANGELOGs
0.3.0
17 release-notes-check
order (line number)
every finding pointed at the blank line above the heading it complained about the finding lands on the heading The verdict was right and the pointer was wrong. Seventeen rounds of fixtures never caught it, because a fixture author checks whether it fires and never whether the line is right. third-party CHANGELOGs
0.3.0
18 tablelint
empty-header
warn on 4 deliberately headerless tables across 2 repositories an all-blank header row or a blank first header is a layout card / row-label table; any other blank header still warns The rule was not wrong about "a column with no name". It was wrong about which documents use a nameless column on purpose. third-party READMEs
dsh-verify-kit 0.2.0
19 handover-check
receiver-unassigned
`接收人:尚未指定` passed with zero findings — a handover stating that nobody had taken over was accepted a non-answer in the receiver slot is an error; a real name, with or without a team in parentheses, passes The rule looked for the label `接收人:` and never for a name. Found by writing this project’s own handover honestly — the document said exactly that, and the check said everything was fine. own honest handover
0.2.0

最该记的一条

第 17 条:order 报的行号系统性偏上一行。判定是对的,指针是错的——用户按报的行号去找,会落在版本标题上方的空行。这件事写了十七轮都没发现,因为我写 fixture 时只关心"有没有报",从不关心"报的行号对不对"。第一个陌生人写的 changelog 第一次就暴露了它。

还有第 12 条:它是修第 2 条时引入的。为了防止文档引用本检查自己的输出,我把所有代码块都遮蔽了——于是作者写在安装块 shell 注释里的成功提示也被遮蔽。一个修复造出下一个缺陷,而两者在同一个下午被同一份语料找出来。

这些缺陷是靠什么语料找出来的 →

第 18 条(tablelint 的无表头表格误报)属于另一个仓库,记在 dsh-verify-kit 的语料页;第 19 条是写 这个项目自己的交接单时发现的。

← 回到 26 个检查一览