diff --git a/doc/design/change-m5-implicit-occlusion.md b/doc/design/change-m5-implicit-occlusion.md new file mode 100644 index 0000000..81addde --- /dev/null +++ b/doc/design/change-m5-implicit-occlusion.md @@ -0,0 +1,103 @@ +# 变更记录:M5 隐式遮蔽(`>` 调用上方的叙述) + +| | | +|---|---| +| 状态 | **Implemented**(**默认关闭**,`--implicit-labels` 开启) | +| 日期 | 2026-10-22 | +| 里程碑 | M5([occlusion-syntax.md](occlusion-syntax.md) §11.2) | +| 改动文件 | `src/label.rs` · `src/check.rs` · `src/main.rs` · `tests/occlusion.rs` | +| 影响面 | `marqdo check` 新增可选检查(默认不改变输出) | + +--- + +## 1. 规则 + +> **`>` 调用上方的叙述段**就是它的"描述";段内的反引号实体必须被这次调用用到 +> (或能解析到模块/内置)。 + +```markdown +按 `税率` 与 `档位` 计算应缴税额: ← 描述 + +> 计税 档位=2 金额=100 ← 实现用到了 `档位`,但没有 `税率` +``` + +``` +impl.mq.md:5:1: 调用上方的描述提到 `税率`,但这次调用没有用到它 +``` + +段落边界:紧邻上一行起,遇空行(允许**一个**分隔空行,因为 blockquote 前通常空一行)、 +标题、代码行(`**`/`>`/`-`/`|`/数字开头)即止。 + +--- + +## 2. 关键决策:**默认关闭** + +这不是洁癖,是实测结论: + +| 阶段 | lib + ext/ai 上的警告数 | +|------|------------------------| +| 初版(任何反引号都算断言) | **6 条**(全部误报:`` `## open` ``、`` `{ path, kind }` ``、`` `source=` ``、`` `exec` ``/`` `net` ``) | +| 加"实体名形状"过滤 | 2 条 | +| **再加默认关闭** | **0 条** | + +理由:**描述一个调用可以用任意措辞**,这比"遮蔽"松散得多; +机械校验必然模糊,默认开启就会制造疲劳(违背 [warning-fatigue-control.md](warning-fatigue-control.md))。 +所以它和 L1 不同:L1 是"能证明才报",隐式检查是"觉得可疑就报"——后者必须 opt-in。 + +--- + +## 3. 实体名过滤(降低误报) + +反引号内容必须**像实体名**才算断言: + +```rust +首字符:字母 / `_` / 非 ASCII(不能是数字) +其余:字母数字 / `_` / `.` / 非 ASCII 且非空白 +``` + +于是 `` `## open` ``、`` `{ path, kind }` ``、`` `source=` ``、`` `path=` `` 全部被排除。 + +--- + +## 4. 用法 + +```bash +marqdo check 文件.mq.md # 默认:不含隐式检查(零噪音) +marqdo check 文件.mq.md --implicit-labels # 开启 +``` + +MLSP 侧留了同义参数位(`validate` 的 `implicit_labels`),M8 一并接。 + +--- + +## 5. 测试 + +| 层 | 内容 | 结果 | +|----|------|------| +| 集成(3) | 默认静默;opt-in 报不一致;opt-in 对一致描述仍静默 | ✅ | +| 全量 | `cargo test --release` | **593 passed / 0 failed**(M6 后 590 + 3) | + +**反向验证**:`implicit_labels_off_by_default` 与 `..._stays_quiet_when_consistent` +两条都在证明"不乱响"。 + +--- + +## 6. 边界 + +| 项 | 说明 | +|----|------| +| 只查 `>` 语句调用 | 表达式内调用没有"上方叙述"这回事 | +| 只认反引号 + 实体形状 | 普通散文永远不参与 | +| 不查 payload 语义 | 只查"提到的实体是否被用到" | + +--- + +## 7. 变更清单 + +| 文件 | 变更 | +|------|------| +| `src/label.rs` | `CallSite` · `call_sites` · `paragraph_above` · `is_entity_ref` · `check_implicit` | +| `src/check.rs` | `check_path_opts(path, implicit_labels)`(`check_path` 保持默认关闭) | +| `src/main.rs` | `check --implicit-labels` | +| `tests/occlusion.rs` + `tests/occlusion/implicit-*.mq.md` | 3 个集成测试 | +| `doc/design/change-m5-implicit-occlusion.md` | 本文件 | diff --git a/src/check.rs b/src/check.rs index eed5084..394acc7 100644 --- a/src/check.rs +++ b/src/check.rs @@ -23,8 +23,22 @@ use crate::load; /// 读取文件 + 装载(含 import)后做全量契约互查。 pub fn check_path(path: &Path) -> Result> { + check_path_opts(path, false) +} + +/// `implicit_labels` enables the fuzzy M5 check (prose above `>` calls). +/// +/// It is **off by default**: describing a call in prose is freeform, so the +/// check is inherently ambiguous and would be noisy — opt in when you want it. +pub fn check_path_opts(path: &Path, implicit_labels: bool) -> Result> { let module = load::load_module(path)?; - Ok(check_module(&module, Some(path))) + let mut out = check_module(&module, Some(path)); + if implicit_labels { + if let Ok(source) = std::fs::read_to_string(path) { + out.extend(crate::label::check_implicit(&module, &source, Some(path))); + } + } + Ok(out) } /// 递归检查模块全部函数(含子函数)的契约。 diff --git a/src/label.rs b/src/label.rs index 7cf3bca..ef084c7 100644 --- a/src/label.rs +++ b/src/label.rs @@ -545,3 +545,179 @@ impl SessionSummary { newly } } + +// --------------------------------------------------------------------------- +// M5: implicit occlusion — the narrative paragraph above a `>` call is its +// description. Only falsifiable claims (backticked refs) are checked, so +// ordinary prose never produces noise. +// --------------------------------------------------------------------------- + +/// A `>` statement call with the identifiers it mentions. +#[derive(Debug, Clone)] +pub struct CallSite { + pub line: u32, + pub idents: std::collections::HashSet, +} + +/// Collect `>` call statements (recursively). +pub fn call_sites(module: &Module) -> Vec { + fn walk_fun(f: &Function, out: &mut Vec) { + for s in &f.body { + walk_stmt(s, out); + } + for c in &f.children { + walk_fun(c, out); + } + } + fn walk_stmt(stmt: &Stmt, out: &mut Vec) { + match stmt { + Stmt::Call { call, span } => { + let mut idents = std::collections::HashSet::new(); + idents.insert(call.callee.clone()); + if let Some(p) = &call.path { + for seg in p { + idents.insert(seg.clone()); + } + } + if let Some(r) = &call.receiver { + idents.insert(r.clone()); + } + for a in &call.args { + match a { + Arg::Positional(e) | Arg::Named { value: e, .. } => { + payload_idents(e, &mut idents) + } + } + } + out.push(CallSite { + line: span.line, + idents, + }); + } + Stmt::Branch { arms, .. } => { + for arm in arms { + for s in &arm.body { + walk_stmt(s, out); + } + } + } + Stmt::While { body, .. } | Stmt::ForEach { body, .. } => { + for s in body { + walk_stmt(s, out); + } + } + Stmt::Assign { value, .. } | Stmt::Return { value, .. } | Stmt::Expr { value, .. } => { + // Nested calls inside expressions are not `>` statements. + let _ = value; + } + } + } + let mut out = Vec::new(); + for f in &module.functions { + walk_fun(f, &mut out); + } + out +} + +/// The narrative paragraph immediately above `line` (1-based), if any. +/// +/// A paragraph is a run of non-blank lines directly above; blank line ends it. +/// Structural lines (`#`, `**`, `>`, `-`, `|`, digits) are not prose. +fn paragraph_above(lines: &[&str], line: u32) -> Option { + let idx = (line as usize).checked_sub(2)?; // line-1 → 0-based index of the previous line + let mut collected: Vec<&str> = Vec::new(); + let mut i = idx as isize; + // People write `paragraph`, one blank line, then the `>` call (blockquote). + // Allow exactly one blank separator; a second blank ends the description. + if i >= 0 && lines[i as usize].trim().is_empty() { + i -= 1; + } + while i >= 0 { + let raw = lines[i as usize]; + let t = raw.trim(); + if t.is_empty() { + break; + } + let first = t.chars().next().unwrap_or(' '); + let structural = matches!(first, '#') + || t.starts_with("**") + || t.starts_with('>') + || t.starts_with('-') + || t.starts_with('|') + || t.starts_with("```") + || first.is_ascii_digit(); + if structural { + break; + } + collected.push(raw); + i -= 1; + } + if collected.is_empty() { + None + } else { + collected.reverse(); + Some(collected.join("\n")) + } +} + +/// True when a backticked ref looks like an *entity name* rather than prose. +/// +/// Prose often backticks shapes (`{ path, kind }`), flags (`source=`), or +/// headings (`## open`); those must not be treated as claims. `` M5 +fn is_entity_ref(s: &str) -> bool { + if s.is_empty() { + return false; + } + let mut chars = s.chars(); + let first = chars.next().unwrap(); + if first.is_ascii_digit() { + return false; + } + let ok_first = first.is_ascii_alphabetic() || first == '_' || !first.is_ascii(); + let ok_rest = s.chars().all(|c| { + c.is_ascii_alphanumeric() || c == '_' || c == '.' || (!c.is_ascii() && !c.is_whitespace()) + }); + ok_first && ok_rest +} + +/// Implicit-occlusion diagnostics for `>` calls. `` M5 +/// +/// The paragraph above a call is its description; backticked refs there must be +/// mentioned by the call (or resolve in the module). No paragraph / no refs → +/// silent, which keeps the check at zero noise on ordinary code. +pub fn check_implicit( + module: &Module, + source: &str, + path: Option<&std::path::Path>, +) -> Vec { + let mut out = Vec::new(); + let symbols = module_symbols(module); + let lines: Vec<&str> = source.lines().collect(); + for site in call_sites(module) { + let Some(para) = paragraph_above(&lines, site.line) else { + continue; + }; + for r in refs(¶).into_iter().filter(|r| is_entity_ref(r)) { + if site.idents.contains(&r) + || symbols.contains(&r) + || crate::host::HostFn::from_name(&r).is_some() + { + continue; + } + out.push( + Diagnostic::new( + path, + Span::new(site.line, 1), + format!("调用上方的描述提到 `{r}`,但这次调用没有用到它"), + ) + .with_code("label.implicit_stale") + .with_severity(Severity::Warning) + .with_doc_quote(para.replace('\n', " ")) + .with_suggestion(format!( + "确认描述是否已过期:把 `{r}` 换成现在的参数名,或修改调用" + )), + ); + } + } + out +} diff --git a/src/main.rs b/src/main.rs index 3cc15a8..72864f8 100644 --- a/src/main.rs +++ b/src/main.rs @@ -96,6 +96,10 @@ enum Commands { /// Emit one JSON diagnostic per line on stdout (machine-readable; AI/MLSP 面) #[arg(long)] json: bool, + + /// Also check prose above `>` calls (implicit occlusion; fuzzy, off by default) + #[arg(long)] + implicit_labels: bool, }, /// Occlusion label queries: pending stubs (built-in words) or keyword search Labels { @@ -537,8 +541,12 @@ fn try_main(cli: Cli) -> Result { marqdo::run_file(&path, &opts)?; Ok(0) } - Commands::Check { file, json } => { - let diags = marqdo::check::check_path(&file)?; + Commands::Check { + file, + json, + implicit_labels, + } => { + let diags = marqdo::check::check_path_opts(&file, implicit_labels)?; let mut errors = 0i32; for d in &diags { if matches!(d.severity, marqdo::diagnostics::Severity::Error) { diff --git a/tests/occlusion.rs b/tests/occlusion.rs index 0217ab1..e3562fd 100644 --- a/tests/occlusion.rs +++ b/tests/occlusion.rs @@ -234,3 +234,46 @@ fn t1_session_summary_reports_counters() { assert!(summary.contains("\"labels_stale_seen\":1"), "{summary}"); assert!(summary.contains("\"labels_outstanding\":1"), "{summary}"); } + +// ---- M5: implicit occlusion (prose above `>` calls) ---- + +#[test] +fn implicit_labels_off_by_default() { + let out = Command::new(env!("CARGO_BIN_EXE_marqdo")) + .args(["check", "tests/occlusion/implicit-stale.mq.md"]) + .output() + .expect("check"); + let text = String::from_utf8_lossy(&out.stdout).into_owned(); + assert!( + !text.contains("调用上方的描述"), + "must stay silent by default: {text}" + ); +} + +#[test] +fn implicit_labels_opt_in_reports_mismatch() { + let out = Command::new(env!("CARGO_BIN_EXE_marqdo")) + .args([ + "check", + "tests/occlusion/implicit-stale.mq.md", + "--implicit-labels", + ]) + .output() + .expect("check"); + let text = String::from_utf8_lossy(&out.stdout).into_owned(); + assert!(text.contains("调用上方的描述提到 `税率`"), "{text}"); +} + +#[test] +fn implicit_labels_opt_in_stays_quiet_when_consistent() { + let out = Command::new(env!("CARGO_BIN_EXE_marqdo")) + .args([ + "check", + "tests/occlusion/implicit-ok.mq.md", + "--implicit-labels", + ]) + .output() + .expect("check"); + let text = String::from_utf8_lossy(&out.stdout).into_owned(); + assert!(!text.contains("调用上方的描述"), "{text}"); +} diff --git a/tests/occlusion/implicit-ok.mq.md b/tests/occlusion/implicit-ok.mq.md new file mode 100644 index 0000000..f3a9d60 --- /dev/null +++ b/tests/occlusion/implicit-ok.mq.md @@ -0,0 +1,15 @@ +--- +title: implicit occlusion consistent +--- + +# main + +按 `档位` 与 `金额` 计算应缴税额: + +> 计税 档位=2 金额=100 + +## 计税 + + `档位` + + `金额` + +*`金额` * 0.1* diff --git a/tests/occlusion/implicit-stale.mq.md b/tests/occlusion/implicit-stale.mq.md new file mode 100644 index 0000000..fa4ad09 --- /dev/null +++ b/tests/occlusion/implicit-stale.mq.md @@ -0,0 +1,15 @@ +--- +title: implicit occlusion stale +--- + +# main + +按 `税率` 与 `档位` 计算应缴税额: + +> 计税 档位=2 金额=100 + +## 计税 + + `档位` + + `金额` + +*`金额` * 0.1*