DSH VERTICAL KIT · DEFECT LEDGER
17 个检测器缺陷
这 22 个检查里,有 19 条规则曾经量的是拼写而不是性质:规则要求某一种写法,而真实文档用的是另一种同样合法的写法,于是对每一份真实文档都报错。或者反过来——规则写得永远触发不了,测试却绿着。
下面每一条都写了:复现输入、当时的判定、现在的判定、以及它是怎么被找出来的。这些声称不是自述——test/defects.test.js 会把每条复现输入喂给当前的代码,误报的那条必须不再出现,死规则的那条必须出现,行号必须落在标题上。页面里说的和代码里做的,只能是一件事。
按发现方式
rules audit— 3third-party READMEs— 3merged catalog PRs— 2third-party LICENSE files— 2third-party CHANGELOGs— 2own history— 1own READMEs— 1own CHANGELOGs— 1own ADRs— 1own runbooks— 1third-party .env.example— 1own honest handover— 1
分布值得单独看一眼:16 条靠把检查器指向真实文件发现,3 条靠规则审计扫出。两种方法各自找到的那批,另一种都找不到——语料找"对真实文件误报",审计找"规则本身没被验证过"。
全表
| # | 检查 / 规则 | 当时的判定 | 现在的判定 | 为什么 | 发现方式 / 修复版本 |
|---|---|---|---|---|---|
| 1 | commit-msg-checktype-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 history0.2.0 |
| 2 | onboarding-checksuccess-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 READMEs0.2.0 |
| 3 | release-notes-checkversion-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 CHANGELOGs0.2.0 |
| 4 | pr-description-checkwhat-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 PRs0.2.0 |
| 5 | adr-checkconsequences-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 ADRs0.2.0 |
| 6 | ops-runbook-checksteps-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 runbooks0.2.0 |
| 7 | commit-msg-checksubject-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 audit0.3.0 |
| 8 | listing-checksku-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 audit0.2.0 |
| 9 | pr-description-checkbreaking-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 PRs0.2.0 |
| 10 | env-example-checkliteral-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.example0.2.0 |
| 11 | onboarding-checkcommand-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 READMEs0.3.0 |
| 12 | onboarding-checksuccess-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 READMEs0.3.0 |
| 13 | outline-lintempty-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 audit0.1.4 |
| 14 | license-checkcopyright-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 files0.2.0 |
| 15 | license-checkplaceholder-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 files0.2.0 |
| 16 | release-notes-checkorder |
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 CHANGELOGs0.3.0 |
| 17 | release-notes-checkorder (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 CHANGELOGs0.3.0 |
| 18 | tablelintempty-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 READMEsdsh-verify-kit 0.2.0 |
| 19 | handover-checkreceiver-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 handover0.2.0 |
最该记的一条
第 17 条:order 报的行号系统性偏上一行。判定是对的,指针是错的——用户按报的行号去找,会落在版本标题上方的空行。这件事写了十七轮都没发现,因为我写 fixture 时只关心"有没有报",从不关心"报的行号对不对"。第一个陌生人写的 changelog 第一次就暴露了它。
还有第 12 条:它是修第 2 条时引入的。为了防止文档引用本检查自己的输出,我把所有代码块都遮蔽了——于是作者写在安装块 shell 注释里的成功提示也被遮蔽。一个修复造出下一个缺陷,而两者在同一个下午被同一份语料找出来。
第 18 条(tablelint 的无表头表格误报)属于另一个仓库,记在 dsh-verify-kit 的语料页;第 19 条是写 这个项目自己的交接单时发现的。