Files
marqdo/src/diagnostics.rs
T
cflmy 9331af78e2 release(2.8.0): 合入 CHANGELOG/README/发版说明/skills prove 任务;CI 链接指向 doc/releases
- 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。
2026-11-18 10:29:26 +08:00

327 lines
10 KiB
Rust
Executable File
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)
}
}
/// 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:"));
}
}