wandering1
dc44c1e54e
用户诉求原话："现在门禁都在干什么，我一概不知。" 原有文档回答"有哪些钩子、怎么配"，回答不了 "这一条到底在拦什么、什么时候会骗我"。本目录按**每种门禁一篇**补齐 23 篇（39 个 hook id 全覆盖： 16 个主机单测是同机制 16 实例合一篇；cppcheck 与 test-cppcheck 是同工具两套范围合一篇）， 文件名用 hook id，与提交输出里的名字一致、可 grep。 八段固定结构：查什么 / 为什么要它（拦下过什么真事）/ 触发面 / 报错怎么读 / 好处 / **限制与盲区** / 豁免与基线口径 / 改门禁本身要注意什么。最后一节是这批文档存在的理由—— 只看"拦了什么"的文档会让人以为绿就是对的；本仓三个增量拦截门禁（layer-deps 6 条、bsp-err 38 条、 id-check 台账 640 处）的绿灯含义只是"没比上次更差"。README 另立"三种拦截姿态"一节：改写型 / 硬拦截 / 增量拦截，分清才知道报错时该改代码还是该还基线。 有实证的地方全部带数字，没实证的地方直接写"预防性、未记录到实际拦截案例"（不编故事）： · cppcheck：把 simulator/ 纳入受检后立刻揪出 sim_syslog.c 真实空指针；test/ 曾有 s_rx_buf 使用先于声明；**并记入两条实测负结果**——它对 14 处丢弃 HAL_SPI_* 返回值与"未初始化局部量 进 P_FAIL 判定"一条不报（这正是 consume-result 的由来）。 · lv-conf-sync：漂移导致 64,576 B 死代码入库（旧镜像的 23.5%），且 golden 跑的是模拟器那份配置。 · cubemx-survival：2026-09-29 一次重生成覆盖 4 处定制（P0×1+P1×2+P2×1），且不报编译错。 · registration-check：rs485_task.c、lftpd_log.c 两处都没注册 = 从不参与编译的死代码；第四类 "页面描述了但没接进 s_defs[] 表"编译链接全过，前三类完全照不出。 · test-suite-switch：实测已提交的 HEAD 里 TEST_SUITE_CH395F 就是开着的，.map 含 34 处 test 代码。 · task-table：2026-09 两张表都比源码落后一大截（写 2048/4096/…/16384，实际 1024…512）。 · mem-numbers：2026-09-26 复核，文档写 82,048 B / 62.6%，实际 87,040 B / 66.4%；Flash 写 249,432 / 23.8%，实际 261,932 / 25.0%。 · ui-golden：注入 .top_y +3 像素 → golden FAIL 点名"1366 px 差异"、退出码 1；并把"有基线 ≠ 有门禁"与"逼人 --no-verify 的门禁等于没有门禁"两条选型依据写进去。 · check-yaml：本仓已移除的 always 键只告警 Unexpected key(s) 然后忽略——配置"看起来生效其实没 生效"而本门全绿，所以验收方式是实跑看目标钩子是 Passed 还是 Skipped。 · no-mojibake：types: [c] 只管 C/H，**文档侧乱码无人管**——覆盖面与需求错配定性写进限制一节。 盲区写法示例（每篇都要求写真实限度，不留空）：layer-deps 只查直接 include、按 basename 匹配、 不查是否真的用到；font-charset 管不到运行期拼出来的字符串与配置文件里的字；host-unit-tests 用宿主 编译器、桩是第二份真相、include_dirs 手写、没有对应钩子的模块等于零回归；mem-budget 的 92% 是管理 阈值不是安全余量、.map 缺失即"通过式跳过"；registration-check 不看条件编译与注册指向是否正确； coding-standard 的 CODE-RULE-17 在无配对头时跳过、规则编号 14 作废不回收。 写文档过程自己被自家门禁拦了两轮，都按规矩改而不是绕过： ① doc-links 拦下我自己——我在解释"写 §数字 而没紧邻文档名会被判成本文自引用"这段话里，正好 就犯了这个写法（两处），另有一处示例输出未标记；改成正例写法 + [示例] 标记。 ② id-check 拦下 7 类新账：示例报错行里的号、档号引用未紧邻文档名、说明"裸形不合规"时自己写了 裸形。全部改成平实描述或补文档名、给样例加 [示例]，没有一条是往台账里塞 reason 解决的。 这两次本身已写进相关篇目的"限制/变更记录"，是这套文档最实在的注脚。 同步：手册 pre-commit使用说明.md 的 §2 顶部加指针（逐项详解已迁往本目录；两处收敛为"通用机制 + 总览 + 指针"排在 docs/门禁说明/README.md §4 的下一步，并注明收敛要按内容重指既有引用——只核编号 存在与否不够）；README 索引 23 行状态全部置为已写、文档列改为可达链接。 验证：纯文档，不动代码与构建产物；check_doc_links --all --sections-strict **171 篇 0 问题** （新目录 24 个文件的内部链接与跨文档引用都纳入判定）；id-check --strict 增量拦截通过；本次受影响 文件 pre-commit run **RC=0**；24 个文件字节卫生 0 异常（无 BOM、无 CR、无 U+FFFD、均有尾换行）。
2.8 KiB
2.8 KiB
check-yaml — YAML 必须能被解析
一句话：只保证 YAML 语法能解析。它不校验 schema，也就挡不住"键名写错导致配置静默失效"。
- 配置：官方
pre-commit-hooksv5.0.0，无额外参数。触发面 = YAML 文件：
1. 它在查什么
- 语法可解析性：缩进一致性、制表符、锚点/别名引用是否存在、重复键等解析层错误。
2. 为什么要它
.pre-commit-config.yaml一旦语法坏掉，整套门禁直接不跑：仓库看起来一切正常，其实 39 个检查全部关着。CI 工作流文件同理（远端不动作、本地也不报错）。- 这是所有静默失效里最坏的一种，值得一条零成本门禁。
3. 触发面 / 看不见什么
- 只跑改动过的 YAML；其它文件里内嵌的 YAML（Markdown 代码块、README 示例）不校验。
- 完全不校验"字段是否符合使用方的预期"。
4. 报错怎么读
check yaml...........................................(no files to check)Skipped
check yaml...............................................................Failed
.pre-commit-config.yaml:88:3: mapping values are not allowed here
Skipped只说明本次没改 YAML，不代表 YAML 是好的。
5. 好处
- 把"门禁整体失效"的概率压到最低；报错定位精确到行列。
6. 限制与盲区（请当正文读）
- 键名写错它不管。本仓有现成教训：pre-commit 4.x 已移除
always: true，实测对local钩子里的这个键只告警Unexpected key(s)然后忽略 —— 配置"看起来生效、其实没生效"， 而check-yaml全绿。所以规则变成：想让某个钩子总是跑，必须让files:覆盖到所有触发面 （已写进AGENTS.md提交门禁一节，并在本目录多篇文档里复述为"触发面"一节）。 - 不校验语义：
args少写一个参数、entry指向一个不存在或不可执行的命令，都不报 （那要等到钩子真正跑起来才炸）。 - 不校验 CI 表达式（
${{ ... }}内容原样当字符串）。 - 多文档 YAML、锚点深合并能过解析但可能与本意相反，它不看。
7. 豁免与基线
- 无基线、无豁免（改到 YAML 就跑）。
8. 改这个门禁本身 / 改配置的正确验证方式
- 改完
.pre-commit-config.yaml，验收不是"过了check-yaml"，而是实跑：& '.venv\Scripts\python.exe' -m pre_commit run --all-files，然后确认目标钩子出现在输出里 且状态是Passed而不是Skipped（Skipped=files:没覆盖到，等于没挂）。 - 新增
repo: local钩子时，language: system+ 相对路径入口是最容易写错的两处。
9. 变更记录
| 日期 | 变更 |
|---|---|
| 2026-10-23 | 首篇逐项文档（含 always: true 只告警不报错这条实测教训） |