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:
1 parent
6bba0be6d2
commit
409b8df2cb
7 files changed
+377
-3
No files matched your search
@@ -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
@@ -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
@@ -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(¶).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
@@ -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) {
|
||||
|
||||
@@ -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}");
|
||||
}
|
||||
@@ -0,0 +1,15 @@
|
||||
---
|
||||
title: implicit occlusion consistent
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
按 `档位` 与 `金额` 计算应缴税额:
|
||||
|
||||
> 计税 档位=2 金额=100
|
||||
|
||||
## 计税
|
||||
+ `档位`
|
||||
+ `金额`
|
||||
|
||||
*`金额` * 0.1*
|
||||
@@ -0,0 +1,15 @@
|
||||
---
|
||||
title: implicit occlusion stale
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
按 `税率` 与 `档位` 计算应缴税额:
|
||||
|
||||
> 计税 档位=2 金额=100
|
||||
|
||||
## 计税
|
||||
+ `档位`
|
||||
+ `金额`
|
||||
|
||||
*`金额` * 0.1*
|
||||
Reference in new issue
Block a user