diff --git a/doc/design/change-m4-label-refs.md b/doc/design/change-m4-label-refs.md new file mode 100644 index 0000000..46ab1eb --- /dev/null +++ b/doc/design/change-m4-label-refs.md @@ -0,0 +1,84 @@ +# 变更记录:M4 L1 引用一致性(`label.ref_dangling`) + +| | | +|---|---| +| 状态 | **Implemented** | +| 日期 | 2026-10-22 | +| 里程碑 | M4([label-freshness-and-repair.md](label-freshness-and-repair.md) §3.1 / [occlusion-syntax.md](occlusion-syntax.md) §11.1) | +| 改动文件 | `src/label.rs` · `tests/occlusion.rs` · `tests/occlusion/ref-*.mq.md` | +| 影响面 | `marqdo check`(新增一条 error) | + +--- + +## 1. 规则 + +> 描述里用反引号写出的名字 = **断言**:它必须能解析 +> —— 要么 `()` 的实现用到它,要么文档里定义了它,要么它是内置函数。 + +```markdown +**a = [按 `税率` 计算](100 * 0.1)** # ❌ label.ref_dangling(税率为空悬) +**b = [按 `税率` 算](100 * `税率`)** # ✅ 实现里用到 +**c = [取长度](len("abc"))** # ✅ 内置函数 +**d = [用 `加` 求和](> 加 1 2))** # ✅ 模块内函数 +``` + +实测: + +``` +dangling.mq.md:3:1: 描述引用了不存在的实体:`税率` —— 本段实现没有用到它,模块里也没有定义 +contract check: 1 条诊断(1 error) # exit 1 +``` + +--- + +## 2. 为什么只认反引号(可证伪原则) + +| 写法 | 是否检查 | 原因 | +|------|---------|------| +| `` `税率` `` | ✅ | 显式引用,可证伪 | +| 普通汉字"税率" | ❌ | 自然语言无法机械判定,检查必然假阳性 | + +代价:作者不写反引号就得不到保护。这是刻意的——**机器只校验它看得懂的断言**, +同时反向抑制"为凑数写废话"。 + +--- + +## 3. 实现 + +| 环节 | 做法 | +|------|------| +| 抽取 | `refs(label)`:扫描成对反引号,取内部去空白;未闭合/空串忽略 | +| 作用域 | `payload_idents(payload)`(Var / callee / path / receiver / `[k]` 的变量键 / 插值变量)∪ `module_symbols(module)`(函数与子函数、参数、import/use 绑定、frontmatter 键)∪ `HostFn::from_name` | +| 诊断 | `label.ref_dangling`,**error**,带 `doc_quote`(描述原文)与可执行建议 | + +`OcclusionSite` 增加 `payload_idents` 字段,在 `collect` 阶段一次算好,`check` 只做集合查找。 + +--- + +## 4. 测试 + +| 层 | 内容 | 结果 | +|----|------|------| +| 单元(3) | 单引用 / 多引用与散文混排 / 无引用与未闭合反引号不 panic | ✅ | +| 集成(2) | 悬空引用 exit 1 + 文案;三类可解析引用(payload 变量 / 内置 / 模块函数)零诊断 | ✅ | +| 全量 | `cargo test --release` | **583 passed / 0 failed**(M2.5 后 578 + 5) | + +--- + +## 5. 边界与后续 + +| 项 | 说明 | +|----|------| +| 只查"能否解析" | 不查"语义是否仍成立"——那是 T1(M6)与人工/LLM 复核的活 | +| 不查"能解析但实现没用到" | 该情形在模块级符号时无法区分误报,留待 T1 变更驱动 | +| 描述里的反引号不是变量绑定 | 只是断言,不进入任何作用域 | + +--- + +## 6. 变更清单 + +| 文件 | 变更 | +|------|------| +| `src/label.rs` | `refs()` · `payload_idents()` · `module_symbols()` · `OcclusionSite.payload_idents` · `check` 增 `label.ref_dangling` · 3 个单测 | +| `tests/occlusion.rs` + `tests/occlusion/{ref-dangling,ref-ok}.mq.md` | 2 个集成测试 | +| `doc/design/change-m4-label-refs.md` | 本文件 | diff --git a/src/label.rs b/src/label.rs index a8b8e54..a96209b 100644 --- a/src/label.rs +++ b/src/label.rs @@ -20,6 +20,8 @@ pub struct OcclusionSite { pub line: u32, /// Enclosing function/object name (`# main` → `main`). pub unit: String, + /// Identifiers the payload actually mentions (for L1 ref checks). + pub payload_idents: std::collections::HashSet, } /// Collect every occlusion in `module` (declaration order). @@ -87,11 +89,16 @@ fn walk_arm(arm: &BranchArm, line: u32, unit: &str, out: &mut Vec fn walk_expr(expr: &Expr, line: u32, unit: &str, out: &mut Vec) { match expr { Expr::Occluded { label, payload } => { + let mut idents = std::collections::HashSet::new(); + if let Some(inner) = payload { + payload_idents(inner, &mut idents); + } out.push(OcclusionSite { label: label.clone(), has_payload: payload.is_some(), line, unit: unit.to_string(), + payload_idents: idents, }); if let Some(inner) = payload { walk_expr(inner, line, unit, out); @@ -127,12 +134,120 @@ fn walk_expr(expr: &Expr, line: u32, unit: &str, out: &mut Vec) { } } +/// Backticked entity references inside a label: `` 按 `税率` 计算 `` → `["税率"]`. +/// +/// Only explicit backticks count as claims — plain prose never is. `` M4 +pub fn refs(label: &str) -> Vec { + let mut out = Vec::new(); + let mut rest = label; + while let Some(open) = rest.find('`') { + let after = &rest[open + 1..]; + let Some(close) = after.find('`') else { + break; + }; + let name = after[..close].trim(); + if !name.is_empty() { + out.push(name.to_string()); + } + rest = &after[close + 1..]; + } + out +} + +/// Every identifier the payload actually mentions (variables, callees, path parts). +fn payload_idents(expr: &Expr, out: &mut std::collections::HashSet) { + match expr { + Expr::Var(n) => { + out.insert(n.clone()); + } + Expr::Occluded { payload, .. } => { + if let Some(inner) = payload { + payload_idents(inner, out); + } + } + Expr::Unary { expr, .. } => payload_idents(expr, out), + Expr::Binary { left, right, .. } => { + payload_idents(left, out); + payload_idents(right, out); + } + Expr::Call(call) => { + out.insert(call.callee.clone()); + if let Some(p) = &call.path { + for seg in p { + out.insert(seg.clone()); + } + } + if let Some(r) = &call.receiver { + out.insert(r.clone()); + } + for a in &call.args { + match a { + Arg::Positional(e) | Arg::Named { value: e, .. } => payload_idents(e, out), + } + } + } + Expr::List(items) => { + for e in items { + payload_idents(e, out); + } + } + Expr::Map(pairs) => { + for (_, e) in pairs { + payload_idents(e, out); + } + } + Expr::Index { base, label } => { + payload_idents(base, out); + if let crate::ast::IndexKey::Var(n) = label { + out.insert(n.clone()); + } + } + Expr::Interp(parts) => { + for p in parts { + if let crate::ast::InterpPart::Var(n) = p { + out.insert(n.clone()); + } + } + } + Expr::Literal(_) | Expr::Formula(_) | Expr::Code(_) => {} + } +} + +/// Names that exist in the document scope: functions/objects (recursive), +/// import aliases, frontmatter keys. Builtins are checked separately. +fn module_symbols(module: &Module) -> std::collections::HashSet { + let mut out = std::collections::HashSet::new(); + fn walk_fun(f: &Function, out: &mut std::collections::HashSet) { + out.insert(f.name.clone()); + for p in &f.params { + out.insert(p.name.clone()); + } + for c in &f.children { + walk_fun(c, out); + } + } + for f in &module.functions { + walk_fun(f, &mut out); + } + for imp in &module.imports { + out.insert(imp.bind.clone()); + } + for u in &module.uses { + out.insert(u.bind.clone()); + } + for (k, _) in &module.metadata { + out.insert(k.clone()); + } + out +} + /// Diagnostics for label structure. `` M2.5 /// /// - empty label → `label.missing` (**error**): you wrote a shape without prose /// - empty payload → `label.empty_payload` (**warning**): say what the stub returns pub fn check(module: &Module, path: Option<&std::path::Path>) -> Vec { let mut out = Vec::new(); + let symbols = module_symbols(module); for site in collect(module) { let span = Span::new(site.line, 1); if site.label.is_empty() { @@ -164,6 +279,60 @@ pub fn check(module: &Module, path: Option<&std::path::Path>) -> Vec .with_suggestion("写清桩的返回值(如 `(None)` 或 `(0)`),或补上真实实现"), ); } + + // `` M4 (L1): every backticked ref in the label must resolve — + // either the payload mentions it, or the document defines it, or it is + // a builtin. This is the deterministic half of staleness detection. + for r in refs(&site.label) { + if site.payload_idents.contains(&r) + || symbols.contains(&r) + || crate::host::HostFn::from_name(&r).is_some() + { + continue; + } + out.push( + Diagnostic::new( + path, + span, + format!( + "描述引用了不存在的实体:`{r}` —— 本段实现没有用到它,模块里也没有定义" + ), + ) + .with_code("label.ref_dangling") + .with_severity(Severity::Error) + .with_doc_quote(site.label.clone()) + .with_suggestion(format!( + "检查是否改名/删除;若只是措辞,把 `{r}` 的反引号去掉或改写描述" + )), + ); + } } out } + +#[cfg(test)] +mod tests { + use super::refs; + + #[test] + fn refs_extracts_backticked_names() { + assert_eq!(refs("按 `税率` 计算"), vec!["税率".to_string()]); + } + + #[test] + fn refs_multiple_and_skips_prose() { + assert_eq!( + refs("用 `a` 和 `b`,但 plain words 不算"), + vec!["a".to_string(), "b".to_string()] + ); + } + + #[test] + fn refs_none_and_unmatched_backtick() { + assert!(refs("纯口语描述").is_empty()); + // Unmatched trailing backtick: ignore, do not panic. + assert!(refs("半截 `名字").is_empty()); + // Empty ticks are not refs. + assert!(refs("空 `` 引号").is_empty()); + } +} diff --git a/tests/occlusion.rs b/tests/occlusion.rs index 85324e0..1ab4bd4 100644 --- a/tests/occlusion.rs +++ b/tests/occlusion.rs @@ -83,3 +83,19 @@ fn label_ok_has_no_diagnostics() { assert!(!text.contains("空载荷"), "text={text}"); assert!(!text.contains("缺少描述"), "text={text}"); } + +// ---- M4: L1 reference consistency (`label.ref_dangling`) ---- + +#[test] +fn label_ref_dangling_is_an_error() { + let (code, text) = check("tests/occlusion/ref-dangling.mq.md", "occlusion"); + assert_eq!(code, 1, "text={text}"); + assert!(text.contains("描述引用了不存在的实体"), "text={text}"); +} + +#[test] +fn label_refs_that_resolve_are_fine() { + let (code, text) = check("tests/occlusion/ref-ok.mq.md", "occlusion"); + assert_eq!(code, 0, "text={text}"); + assert!(!text.contains("不存在的实体"), "text={text}"); +} diff --git a/tests/occlusion/ref-dangling.mq.md b/tests/occlusion/ref-dangling.mq.md new file mode 100644 index 0000000..3ab53a6 --- /dev/null +++ b/tests/occlusion/ref-dangling.mq.md @@ -0,0 +1,8 @@ +--- +title: dangling label ref +--- + +# main + +**a = [按 `税率` 计算](100 * 0.1)** +> print text=`a` diff --git a/tests/occlusion/ref-ok.mq.md b/tests/occlusion/ref-ok.mq.md new file mode 100644 index 0000000..943d74a --- /dev/null +++ b/tests/occlusion/ref-ok.mq.md @@ -0,0 +1,20 @@ +--- +title: resolvable label refs +--- + +# main + +`税率` = 0.1 + +**a = [按 `税率` 算](100 * `税率`)** +**b = [取长度](len("abc"))** +**c = [用 `加` 求和](> 加 1 2)** +> print text=`a` +> print text=`b` +> print text=`c` + +## 加 + + `x` + + `y` + +*`x` + `y`*