- CHANGELOG.md:v2.8.0 条目(中英双语); - README.md:版本行 2.7.1→2.8.0 + 愿景第 6 条(知识可证明); - doc/releases/v2.8.0.md:双语发版说明(亮点/用法/已知限制); - skills/marqdo-dev/index.mq.md:新增 prove 任务(路径/目录模式/ require_lean/json;参数用 + 行声明升参,check 与 narrative-ratio 通过); - 设计文档 §12.5 标记已合入;发版链接统一指向 doc/releases/v2.8.0.md。
327 lines
10 KiB
Rust
Executable File
327 lines
10 KiB
Rust
Executable File
//! 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)
|
||
}
|
||
}
|
||
|
||
/// Identity of the exact text that was parsed, including recorded revisions.
|
||
/// A path is a label; the digest is never recomputed from a later disk version.
|
||
#[derive(Debug, Clone, Default, PartialEq, Eq)]
|
||
pub struct SourceIdentity {
|
||
pub path: Option<PathBuf>,
|
||
pub sha256: Option<String>,
|
||
}
|
||
|
||
impl SourceIdentity {
|
||
pub fn from_source(path: Option<&Path>, text: &str) -> Self {
|
||
use sha2::{Digest, Sha256};
|
||
Self {
|
||
path: path.map(Path::to_path_buf),
|
||
sha256: Some(format!("{:x}", Sha256::digest(text.as_bytes()))),
|
||
}
|
||
}
|
||
|
||
pub fn at(&self, span: Span) -> SourceLocation {
|
||
SourceLocation {
|
||
source: self.clone(),
|
||
span,
|
||
}
|
||
}
|
||
}
|
||
|
||
#[derive(Debug, Clone, PartialEq, Eq)]
|
||
pub struct SourceLocation {
|
||
pub source: SourceIdentity,
|
||
pub span: Span,
|
||
}
|
||
|
||
impl SourceLocation {
|
||
pub fn to_json(&self) -> serde_json::Value {
|
||
serde_json::json!({"file": self.source.path.as_ref().map(|p| display_path(p)),
|
||
"source_sha256": self.source.sha256, "line": self.span.line, "col": self.span.col})
|
||
}
|
||
}
|
||
|
||
#[derive(Debug, Clone, PartialEq, Eq)]
|
||
pub struct DiagnosticFrame {
|
||
pub function: String,
|
||
pub declaration: SourceLocation,
|
||
pub call_site: Option<SourceLocation>,
|
||
}
|
||
|
||
impl DiagnosticFrame {
|
||
pub fn to_json(&self) -> serde_json::Value {
|
||
serde_json::json!({"function": self.function, "declaration": self.declaration.to_json(),
|
||
"call_site": self.call_site.as_ref().map(SourceLocation::to_json)})
|
||
}
|
||
}
|
||
|
||
/// 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>,
|
||
pub source_sha256: Option<String>,
|
||
/// Ordered outermost to innermost; every site retains its own source.
|
||
pub frames: Vec<DiagnosticFrame>,
|
||
}
|
||
|
||
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,
|
||
source_sha256: None,
|
||
frames: Vec::new(),
|
||
}
|
||
}
|
||
|
||
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_source(mut self, source: &SourceIdentity) -> Self {
|
||
self.path = source.path.clone();
|
||
self.source_sha256 = source.sha256.clone();
|
||
self
|
||
}
|
||
|
||
pub fn with_frames(mut self, frames: &[DiagnosticFrame]) -> Self {
|
||
self.frames = frames.to_vec();
|
||
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 {
|
||
let mut message = match &self.path {
|
||
Some(p) => format!("{}:{}: {}", display_path(p), self.span, self.message),
|
||
None => format!("{}: {}", self.span, self.message),
|
||
};
|
||
for frame in self.frames.iter().rev() {
|
||
if let Some(site) = &frame.call_site {
|
||
let file = site
|
||
.source
|
||
.path
|
||
.as_ref()
|
||
.map(|p| display_path(p))
|
||
.unwrap_or_else(|| "<unknown>".into());
|
||
message.push_str(&format!(
|
||
"\n called {} from {}:{}",
|
||
frame.function, file, site.span
|
||
));
|
||
}
|
||
}
|
||
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,
|
||
},
|
||
"source_sha256": self.source_sha256,
|
||
"frames": self.frames.iter().map(DiagnosticFrame::to_json).collect::<Vec<_>>(),
|
||
"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:"));
|
||
}
|
||
}
|