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

+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) {