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
+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) {
|
||||
|
||||
Reference in new issue
Block a user