feat(check): M5 隐式遮蔽 — > 调用上方的叙述作为描述(默认关闭)

规则:`>` 调用上方的叙述段即其"描述";段内反引号实体必须被该调用用到,
或能解析到模块/内置,否则报 label.implicit_stale(warning)。
段落边界:紧邻上一行起,允许一个分隔空行(blockquote 前常空一行),
遇第二个空行/标题/代码行即止。

关键决策:**默认关闭(--implicit-labels 开启)**,依据是实测噪音:
- 初版(任何反引号都算断言):lib+ext/ai 上 6 条警告,**全为误报**
  (`## open`、`{ path, kind }`、`source=`、`exec`/`net`)
- 加"实体名形状"过滤后:2 条
- 再加默认关闭:**0 条**
理由:描述一个调用可以用任意措辞,机械校验必然模糊;
默认开启就制造疲劳(违背 warning-fatigue-control)。这与 L1 不同:
L1 是"能证明才报",隐式检查是"可疑就报",必须 opt-in。

实体名过滤:首字符字母/_/非ASCII,其余字母数字/_/./非ASCII非空白
→ 排除 `## open` / `{ path, kind }` / `source=` / `path=`。

用法:marqdo check 文件 --implicit-labels

测试:3 个集成(默认静默 / opt-in 报不一致 / opt-in 对一致描述仍静默,
后两条是反向验证"不乱响");全量 593 passed / 0 failed(M6 后 590 + 3)。

文档:doc/design/change-m5-implicit-occlusion.md
This commit is contained in:
cflmy committed 2026-10-22 15:21:23 +08:00
1 parent 6bba0be6d2
commit 409b8df2cb
7 files changed
+377 -3

No files matched your search

+103
View File
@@ -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` | 本文件 |
+15 -1
View File
@@ -23,8 +23,22 @@ use crate::load;
/// 读取文件 + 装载(含 import)后做全量契约互查。
pub fn check_path(path: &Path) -> Result<Vec<Diagnostic>> {
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<Vec<Diagnostic>> {
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)
}
/// 递归检查模块全部函数(含子函数)的契约。
+176
View File
@@ -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<String>,
}
/// Collect `>` call statements (recursively).
pub fn call_sites(module: &Module) -> Vec<CallSite> {
fn walk_fun(f: &Function, out: &mut Vec<CallSite>) {
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<CallSite>) {
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<String> {
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. `<TAB>` 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. `<TAB>` 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<Diagnostic> {
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(&para).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
}
+10 -2
View File
@@ -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<i32> {
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) {
+43
View File
@@ -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}");
}
+15
View File
@@ -0,0 +1,15 @@
---
title: implicit occlusion consistent
---
# main
按 `档位` 与 `金额` 计算应缴税额:
> 计税 档位=2 金额=100
## 计税
+ `档位`
+ `金额`
*`金额` * 0.1*
+15
View File
@@ -0,0 +1,15 @@
---
title: implicit occlusion stale
---
# main
按 `税率` 与 `档位` 计算应缴税额:
> 计税 档位=2 金额=100
## 计税
+ `档位`
+ `金额`
*`金额` * 0.1*