Files
marqdo/doc/design/change-m25-label-diagnostics.md
cflmy 1a94cc8490 feat(check): M2.5 遮蔽标签诊断 — label.missing(error) / label.empty_payload(warning)
新增 src/label.rs:
- OcclusionSite { label, has_payload, line, unit }
- collect(module):遍历函数/分支/循环/表达式收集遮蔽点(描述只读,不产生读引用)
- check(module, path):产出两条诊断

两条诊断:
- label.missing(error):[](...) 描述为空 —— 写一句人话,或改用不带遮蔽的写法
- label.empty_payload(warning):[描述]() 载荷为空 —— 写清桩返回什么(None/0),或补实现
warning 不影响退出码;JSON 出口自动继承既有 schema(含 doc_quote/span/suggestion)。

接入 check_module:walk 之后 extend(crate::label::check(..)),保持一行;
M4(引用一致性)与 M9(检索)都往 label 模块加,check 不再膨胀。

测试:
- 3 个集成(tests/occlusion.rs):空描述 exit 1、空载荷 exit 0、干净样例无诊断
- 全量 cargo test --release:578 passed / 0 failed(M2 后 575 + 3)
反向验证:干净样例必须零输出,证明不会误响。

实测:
  MARQDO_MARKUP=occlusion marqdo check empty-label.mq.md    # 1 error, exit 1
  MARQDO_MARKUP=occlusion marqdo check empty-payload.mq.md  # 1 warning, exit 0

文档:doc/design/change-m25-label-diagnostics.md
2026-10-22 15:13:33 +08:00

3.2 KiB
Raw Permalink Blame History

变更记录:M2.5 遮蔽标签诊断(label.missing / label.empty_payload)

状态 Implemented
日期 2026-10-22
里程碑 M2.5(occlusion-syntax.md §13,诊断规范 §10)
改动文件 新增 src/label.rs · src/check.rs · src/lib.rs · tests/occlusion.rs
影响面 marqdo check(新增两类诊断)

1. 两条诊断

code 级别 触发 文案要点
label.missing error [](实现) 描述为空 「给这段实现写一句人话,或改用不带遮蔽的写法」
label.empty_payload warning [描述]() 载荷为空 「这里没有可执行内容」,建议写 (None) 或补实现

实测:

$ MARQDO_MARKUP=occlusion marqdo check empty-label.mq.md
empty-label.mq.md:3:1: 遮蔽缺少描述:`[](…)` —— 给这段实现写一句人话,或改用不带遮蔽的写法
contract check: 1 条诊断(1 error)      # exit 1

$ MARQDO_MARKUP=occlusion marqdo check empty-payload.mq.md
empty-payload.mq.md:3:1: 空载荷遮蔽:`[某某功能开发中]()` —— 这里没有可执行内容
contract check: 1 条诊断(0 error)      # exit 0(warning 不影响退出码)

JSON 出口(自动继承既有 schema,含 doc_quote):

{"code":"label.empty_payload","severity":"warning","span":{"line":3,"col":1},
 "doc_quote":"某某功能开发中","message":"空载荷遮蔽:…","suggestion":"写清桩的返回值(如 `(None)` 或 `(0)`)…"}

2. 实现

2.1 新增 src/label.rs

  • OcclusionSite { label, has_payload, line, unit }
  • collect(module):遍历函数体与嵌套语句/表达式,收集所有遮蔽点 (描述只读,不产生任何读引用)
  • check(module, path):产出上面两条诊断

2.2 接入 check_module

walk(module, &module.functions, path, &known, &mut out);
out.extend(crate::label::check(module, path));   // M2.5

设计上把"标签诊断"独立成模块,M4(引用一致性)与 M9(检索)都往这里加, check 只做一行汇总。


3. 测试

层 内容 结果
集成(3 新) 空描述 → exit 1 + 文案;空载荷 → exit 0 + 文案;干净样例 → 无诊断 ✅
全量 cargo test --release 578 passed / 0 failed(M2 后 575 + 3)

反向验证:三条断言分别验证"会响"与"不会误响"(干净样例必须无输出)。


4. 边界

项 说明
描述内容不校验 写什么都可以;M4 才校验反引号引用
空载荷仅在 occlusion 模式可能出现 classic 模式下 () 空是语法错
warning 不影响退出码 与既有 Severity 语义一致

5. 变更清单

文件 变更
src/label.rs 新增:遮蔽点收集 + 两类诊断
src/lib.rs pub mod label;
src/check.rs check_module 追加 label 诊断
tests/occlusion.rs + tests/occlusion/{empty-label,empty-payload,clean}.mq.md 新增 3 个集成测试与样例
doc/design/change-m25-label-diagnostics.md 本文件