Files
marqdo/doc/design/change-m25-label-diagnostics.md
cflmy 9331af78e2 release(2.8.0): 合入 CHANGELOG/README/发版说明/skills prove 任务;CI 链接指向 doc/releases
- CHANGELOG.md:v2.8.0 条目(中英双语);
- README.md:版本行 2.7.1→2.8.0 + 愿景第 6 条(知识可证明);
- doc/releases/v2.8.0.md:双语发版说明(亮点/用法/已知限制);
- skills/marqdo-dev/index.mq.md:新增 prove 任务(路径/目录模式/
  require_lean/json;参数用 + 行声明升参,check 与 narrative-ratio 通过);
- 设计文档 §12.5 标记已合入;发版链接统一指向 doc/releases/v2.8.0.md。
2026-11-18 10:29:26 +08:00

3.2 KiB
Executable File
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 本文件