docs: README 补前置准备(干净 clone 直接跑 npm test 会红 4 个文件)
缺口(评审复现,我独立复现确认) git archive HEAD 到空目录、原样 npm test: # tests 34 # pass 30 # fail 4 not ok test/loader.test.js / phase-b-g.test.js / phase-b-h.test.js / plugin.test.js 根因:Cannot find package '@deepseek-ai/cordis'。 而 README 全文对 link-dsh.sh / node_modules / 前置准备零命中 —— 正文只写「npm test 是 how many 的权威」,默认读者已经跑过 link-dsh.sh, 而这个前提谁都没写。 这与本轮刚修的那个缺口同族:判据/文档声称的能力,在没有守卫的地方悄悄不成立。 (刚删掉 README 计数,理由是「没守卫就会漂」;「npm test 是权威」这句话 同样没有守卫 —— 它默认了一个没人写下来的前置。) 修法(按裁定选 ①,不用 pretest 钩子) README §Verify 开头新增「Prerequisite: link the harness packages first」: - 说清本仓零运行时依赖,@deepseek-ai/* 全部是 peer, 必须来自机器上已装的 dsh(vendoring 会与它要运行的 harness 漂开) - 给命令 bash scripts/link-dsh.sh - 明确写出跳过它的症状:四个文件 ERR_MODULE_NOT_FOUND (loader / plugin / guard / http 四套,与实测逐一对齐), 并说明这是缺前置的正常形态,不是树坏了 - 补非默认安装根的可选参数 按裁定的第二条不加判据去测「干净 clone 能跑测试」(成本高于收益),写清楚就够。 顺带一处:README 的计数禁令只匹配数字形态(119 tests / 10 checkpoints / 10/10 passed),新段落用了英文「four files」,不被误报 —— 在守卫里加注释说明这个 scope,以及为什么不去匹配文字形态 (「四个文件报 ERR_MODULE_NOT_FOUND」是合法的散文,再往下写就变成小解析器)。 验证 - 干净 clone 复现:无链接 4 红;bash scripts/link-dsh.sh 之后 120/120、check 10/10 - README 描述的失败文件清单与实测逐一一致 - npm test 连跑 5 次 120/120 - npm run check 3 次,exit=0、10 条全绿 - README 计数禁令仍绿(未误报新段落) - 无 .orig / .rej 残留,未 amend / 未 force push
This commit is contained in:
27
README.md
27
README.md
@ -644,6 +644,33 @@ because they will bite anyone writing a second dsh service plugin.
|
||||
|
||||
## Verify
|
||||
|
||||
### Prerequisite: link the harness packages first
|
||||
|
||||
This repository has **no runtime dependencies** — `lib/` uses only `node:`
|
||||
built-ins. Everything it imports from `@deepseek-ai/*` is a **peer** that must
|
||||
come from the dsh install already on the machine, which is why none of it is
|
||||
bundled here (vendoring a copy would let it drift from the harness it is supposed
|
||||
to run inside).
|
||||
|
||||
So a fresh clone needs one setup step before the suite can run:
|
||||
|
||||
```bash
|
||||
bash scripts/link-dsh.sh # symlinks the installed dsh packages into node_modules
|
||||
```
|
||||
|
||||
**If you skip it, `npm test` fails with four files reporting
|
||||
`ERR_MODULE_NOT_FOUND: Cannot find package '@deepseek-ai/cordis'`** (loader,
|
||||
plugin, guard and http suites). That is the expected symptom of a missing setup
|
||||
step, not a broken tree — run the script and it goes green.
|
||||
|
||||
The script takes an optional argument for a non-default install root:
|
||||
|
||||
```bash
|
||||
bash scripts/link-dsh.sh /path/to/global/node_modules
|
||||
```
|
||||
|
||||
### Run
|
||||
|
||||
```bash
|
||||
npm test # the full suite
|
||||
npm run check # human-readable evidence, one line per checkpoint
|
||||
|
||||
@ -232,6 +232,13 @@ test('scripts/checkpoints.js registers checkpoints AND refuses to pass with zero
|
||||
//
|
||||
// So the invariant is now the opposite: the README must NOT state a count. If
|
||||
// someone re-adds one, this fails and the reason is right here.
|
||||
//
|
||||
// Scope: this matches DIGIT forms ("119 tests", "10 checkpoints", "10/10 …").
|
||||
// It does not try to catch a count spelled out in words ("four files"), because
|
||||
// the README legitimately needs prose like "four files report ERR_MODULE_NOT_FOUND
|
||||
// — that is the missing-setup symptom" and a prose-matching rule would either
|
||||
// fire on that or grow into a mini parser. The rule targets the shape a
|
||||
// maintainer actually writes when pasting a run result, which is digits.
|
||||
test('README states no test or checkpoint counts', () => {
|
||||
const readme = readFileSync(join(new URL('..', import.meta.url).pathname, 'README.md'), 'utf8')
|
||||
|
||||
|
||||
Reference in New Issue
Block a user