Files
marqdo/src/diagnostics.rs
T
cflmyandCursor 7a449c40b1 feat(contract): Phase 2 渐进式契约层 —— 契约表提取 + 四边界校验 + marqdo check 防漂移(T2.1–T2.5)
- src/contract.rs: 类型词汇(渐进标注)、参数/返回/字段三形状契约表解析、合并、四边界校验诊断
- src/parse/mod.rs: extract_function_contract —— 位置+形状双重判定,在升参推断之前提取;
  绑定表/普通文档表绝不吃(P1 零回归),契约表从 body 移除(元数据永不执行)
- src/interp.rs: 四边界校验 —— 调用实参(3 条调用路径)/返回/表绑定/字段访问
- src/check.rs + marqdo check [--json]: 漂移双向互查、未知类型名(附建议)、错位契约
- src/load.rs: label_error 保留结构化诊断(错误出口唯一,不拍平成字符串)
- T2.4: 全部契约诊断带 doc_anchor/doc_quote/contract_ref
- tests/contracts.rs 12 例全绿;全量回归零失败(含 262 gold)

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-22 19:40:08 +08:00

242 lines
7.3 KiB
Rust
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
//! Diagnostics with file/line/column.
use std::fmt;
use std::path::{Path, PathBuf};
use thiserror::Error;
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct Span {
pub line: u32,
pub col: u32,
}
impl Span {
pub fn new(line: u32, col: u32) -> Self {
Self { line, col }
}
}
impl fmt::Display for Span {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
write!(f, "{}:{}", self.line, self.col)
}
}
/// Format a path for user-facing diagnostics.
///
/// Strips the Windows extended-length prefix (`\\?\` / `\\?\UNC\`) that
/// `canonicalize` often adds, so messages stay readable.
pub fn display_path(path: &Path) -> String {
let raw = path.display().to_string();
if let Some(rest) = raw.strip_prefix(r"\\?\UNC\") {
format!(r"\\{rest}")
} else if let Some(rest) = raw.strip_prefix(r"\\?\") {
rest.to_string()
} else if let Some(rest) = raw.strip_prefix("//?/") {
// Some tools emit forward-slash forms
rest.to_string()
} else {
raw
}
}
/// Diagnostic severity.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum Severity {
Error,
Warning,
}
/// Contract reference (Phase 2 填值;schema 源头 = 契约表 / 说明段落).
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ContractRef {
pub unit: String,
pub kind: String,
pub name: String,
pub declared: String,
}
/// Unified diagnostic: `path:line:col: message` (path omitted if unknown).
///
/// 人类文本(`Display`)与机器面([`Diagnostic::to_json`])同源:凡可定位必有
/// `span`;凡契约错必带 `doc_anchor` / `doc_quote` / `contract_ref`
/// (见 `doc/roadmap/three-problems.md` §3.3 诊断协议)。
#[derive(Debug, Error, Clone)]
#[error("{}", self.format_message())]
pub struct Diagnostic {
pub path: Option<PathBuf>,
pub span: Span,
pub message: String,
/// Stable machine code (`parse.*` / `contract.*` / `runtime.*` …).
pub code: String,
pub severity: Severity,
pub suggestion: Option<String>,
pub doc_anchor: Option<String>,
pub doc_quote: Option<String>,
pub contract_ref: Option<ContractRef>,
}
impl Diagnostic {
pub fn new(path: Option<&Path>, span: Span, message: impl Into<String>) -> Self {
Self {
path: path.map(|p| p.to_path_buf()),
span,
message: message.into(),
code: "marqdo.error".to_string(),
severity: Severity::Error,
suggestion: None,
doc_anchor: None,
doc_quote: None,
contract_ref: None,
}
}
pub fn at(path: &Path, span: Span, message: impl Into<String>) -> Self {
Self::new(Some(path), span, message)
}
pub fn with_code(mut self, code: impl Into<String>) -> Self {
self.code = code.into();
self
}
pub fn with_severity(mut self, severity: Severity) -> Self {
self.severity = severity;
self
}
pub fn with_suggestion(mut self, suggestion: impl Into<String>) -> Self {
self.suggestion = Some(suggestion.into());
self
}
pub fn with_doc_anchor(mut self, anchor: impl Into<String>) -> Self {
self.doc_anchor = Some(anchor.into());
self
}
pub fn with_doc_quote(mut self, quote: impl Into<String>) -> Self {
self.doc_quote = Some(quote.into());
self
}
pub fn with_contract_ref(mut self, contract_ref: ContractRef) -> Self {
self.contract_ref = Some(contract_ref);
self
}
/// 从 anyhow 错误链中找回结构化诊断(load/parse 包了 context 也不丢;MLSP 面)。
pub fn find(err: &anyhow::Error) -> Option<&Diagnostic> {
err.chain().find_map(|e| e.downcast_ref::<Diagnostic>())
}
pub fn format_message(&self) -> String {
match &self.path {
Some(p) => format!("{}:{}: {}", display_path(p), self.span, self.message),
None => format!("{}: {}", self.span, self.message),
}
}
/// Machine-readable form(AI/MLSP 面;`run --json` 出口)。
pub fn to_json(&self) -> serde_json::Value {
use serde_json::json;
json!({
"code": self.code,
"severity": match self.severity {
Severity::Error => "error",
Severity::Warning => "warning",
},
"message": self.message,
"span": {
"file": self.path.as_ref().map(|p| display_path(p)),
"line": self.span.line,
"col": self.span.col,
},
"doc_anchor": self.doc_anchor,
"doc_quote": self.doc_quote,
"contract_ref": self.contract_ref.as_ref().map(|c| json!({
"unit": c.unit,
"kind": c.kind,
"name": c.name,
"declared": c.declared,
})),
"suggestion": self.suggestion,
})
}
}
/// Convenience for `anyhow` sites that already have a span.
pub fn bail_at(path: Option<&Path>, span: Span, message: impl Into<String>) -> anyhow::Error {
anyhow::Error::new(Diagnostic::new(path, span, message))
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn strips_windows_extended_prefix() {
let p = PathBuf::from(r"\\?\E:\marqdo\examples\errors\bad-arity.mq.md");
assert_eq!(
display_path(&p),
r"E:\marqdo\examples\errors\bad-arity.mq.md"
);
}
#[test]
fn strips_unc_extended_prefix() {
let p = PathBuf::from(r"\\?\UNC\server\share\file.mq.md");
assert_eq!(display_path(&p), r"\\server\share\file.mq.md");
}
#[test]
fn diagnostic_message_uses_clean_path() {
let d = Diagnostic::at(
Path::new(r"\\?\E:\marqdo\x.mq.md"),
Span::new(7, 1),
"missing argument for parameter `x`",
);
let msg = d.format_message();
assert!(!msg.contains(r"\\?\"));
assert!(msg.contains(r"E:\marqdo\x.mq.md:7:1:"));
}
#[test]
fn json_shape_defaults_nonempty_code_and_span() {
let d = Diagnostic::at(Path::new("x.mq.md"), Span::new(3, 5), "boom");
let v = d.to_json();
assert_eq!(v["code"], "marqdo.error");
assert_eq!(v["severity"], "error");
assert_eq!(v["span"]["line"], 3);
assert_eq!(v["span"]["col"], 5);
assert_eq!(v["span"]["file"], "x.mq.md");
}
#[test]
fn json_carries_doc_anchor_and_contract_ref() {
let d = Diagnostic::at(
Path::new("demo.mq.md"),
Span::new(12, 3),
"参数 `n` 期望 number,实际 text",
)
.with_code("contract.arg_mismatch")
.with_doc_anchor("demo.mq.md#L4-L7")
.with_doc_quote("| `n` | number | 输入值 |")
.with_suggestion("把实参改为数字")
.with_contract_ref(ContractRef {
unit: "加一".to_string(),
kind: "param".to_string(),
name: "n".to_string(),
declared: "number".to_string(),
});
let v = d.to_json();
assert_eq!(v["code"], "contract.arg_mismatch");
assert_eq!(v["doc_anchor"], "demo.mq.md#L4-L7");
assert_eq!(v["contract_ref"]["unit"], "加一");
assert_eq!(v["suggestion"], "把实参改为数字");
// Display 零回归
assert!(d.format_message().contains("demo.mq.md:12:3:"));
}
}