diff --git a/docs/lessons-learned.md b/docs/lessons-learned.md index ee43fd2..6f2ecb1 100644 --- a/docs/lessons-learned.md +++ b/docs/lessons-learned.md @@ -802,3 +802,46 @@ cd e2e && npx playwright test <改动的 spec> --list # Total: N tests in M fi (本轮就是漏改一处 `pageBg` 引用,闸以 `FATAL: 扫描中断(uncaughtException)` 崩掉而非静默通过); 以及闸的退出码分档(0 通过 / 1 判红 / 2 未能度量 + FATAL 独立路径)在这种时刻兑现了价值 —— **崩和"测不到"都不会被读成通过**。 + +### 5.44 并行分工下「提交别人在途的文件」会冻结中间态,而提交信息会跟着说谎(2026-10-17) + +现象:`1c0ce5f4` 的信息写着「package.json 重复键已由 node 回读校验」,但 +`git show HEAD:package.json | grep -c '"type-check:e2e":'` 实取 **2**,且 `test:all` 整条消失。 +根因链有两条,都要记: + +1. **我在别人还在写它 own 的文件时就 `git add`** ⇒ 提交冻结的是他的中间态,他的终稿留在工作树。 + 纪律:**别人的在途文件要等该分工的回执再提交**;若必须提交,提交后立刻 + 用 `git show HEAD:` 复算提交信息里的**每一条**断言(读 HEAD,不是读工作树)。 +2. **按子串取行号再删行 = 危险动作**。我的去重命令是 + `DUP=$(grep -n 'type-check:e2e' pkg | tail -1 | cut -d: -f1); sed -i "${DUP}d" pkg`—— + 而 `test:all` 那一行**也含这个子串**(它引用了该脚本名),于是删掉的是全仓门禁入口。 + 纪律:改 JSON/YAML 走解析器(或至少按"整行精确匹配 + 键名等值"定位), + 永远不要拿 `grep -n` 的行号当地址用;删行前先 `sed -n "<行号>p"` 看一眼要删的是什么。 + +### 5.45 校验仪器必须对「它声称检查的那一维」敏感:三层负对照缺一不可 + +同轮两处自伤,都不是被测对象坏,是**仪器坏**: + +- 我用 `^ "([a-z0-9:_-]+)":` 数 package.json 的重复键 —— 两空格缩进只匹配**顶层**, + 而重复键在 `scripts` 对象里(四空格)⇒ 报 `dups=[]`,对目标那一维根本不敏感, + 却让我据此写下了那条不实的提交信息(见 §5.44)。 +- `npx jest "src/app/(marketing)/products"` 里 `(` 与 `[` 是**正则元字符**, + jest 把位置参数当 testPathPattern ⇒ "No tests found" 的 EXIT=1 被我读成"测试失败"。 + +修成的仪器 `scripts/check-package-keys.mjs` 现在按 **父路径 + 键名** 分组计数,退出码 0/1/2 三档, +并自带三层对照:正对照(真文件无重复 ⇒ 0)、负对照-同层重复必抓(1)、负对照-异父同名不误报(0); +另在真 `package.json` 上做**活体注入**:加一条重复的 `"lint"` 键 ⇒ `EXIT=1` 且点名 `scripts` 里的 "lint",还原 ⇒ 0。 + +⇒ 通用判据(与 §5.42「命中 0 必须配页面健康的正对照」同族): +**当"没问题"与"没测到"共用同一个 0/1 时,仪器必须先自证能取到非空样本,并且对目标维度做过一次故意的破坏**。 + +### 5.46 车道的编排端口必须读脚本自己的默认约定,不能凭习惯 + +我把 axe 车道写成 `PORT=3000` 起 standalone,再跑 `check:axe:routes`/`check:axe`, +结果 `AXE_ROUTES=2`(17 条候选路由全不可达 ⇒ 判"清单不可信,不写出")与 `AXE=1` +(`ERR_CONNECTION_REFUSED`)。这两个脚本按 CI 约定默认 `BASE=http://localhost:3100`(写在文件头注释里)。 +改 `PORT=3100` 后同一条链路 **EXIT=0**(34 路由 ×4 组合、`unexpectedStatus=0`、`non2xxResponses=1` = 期望内的 `/_not-found`)。 + +值得记的是**这次失败没有骗人**:分母为 0 走 EXIT=2 而不是 0,闸崩溃走 FATAL 而不是静默通过 —— +退出码分档(0 通过 / 1 判红 / 2 未能度量 / FATAL)在这里第二次兑现价值。 +纪律:编排脚本前先 `grep -n 'process.env\|BASE\|PORT' <脚本>` 读它自己的默认值。