Files
marqdo/src/view/logic.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

339 lines
18 KiB
Rust
Executable File

//! Read-only presentation of link-shaped descriptions. No evaluation or fetching.
use crate::ast::{Arg, CallExpr, Expr, Literal, Module};
use crate::view::{html::escape, render::expr_display};
use pulldown_cmark::{html, Event, Options, Parser, Tag};
use std::collections::HashMap;
pub(crate) struct Span<'a> {
pub start: usize,
pub end: usize,
pub label: &'a str,
pub payload: &'a str,
}
/// Preserve quoted source data in executable spans and inline code in narration.
pub(crate) fn spans(text: &str, code: bool) -> Vec<Span<'_>> {
let bytes = text.as_bytes();
let mut found = Vec::new();
let mut i = 0;
while i < bytes.len() {
if bytes[i] == b'\\' { i = (i + 2).min(bytes.len()); continue; }
if bytes[i] == b'\x60' || code && matches!(bytes[i], b'"' | b'\'') {
let quote = bytes[i];
let run = if quote == b'\x60' { bytes[i..].iter().take_while(|b| **b == quote).count() } else { 1 };
i += run;
while i < bytes.len() {
if bytes[i] == b'\\' { i = (i + 2).min(bytes.len()); }
else if bytes[i..].starts_with(&vec![quote; run]) { i += run; break; }
else { i += 1; }
}
continue;
}
if bytes[i] != b'[' || bytes.get(i + 1) == Some(&b'^')
|| i > 0 && bytes[i - 1] == b'!' {
i += 1; continue;
}
let start = i;
let mut j = i + 1;
let mut depth = 1;
while j < bytes.len() {
match bytes[j] {
b'\\' => { j += 2; continue; }
b'[' => depth += 1,
b']' => { depth -= 1; if depth == 0 { break; } }
_ => {}
}
j += 1;
}
if depth != 0 || bytes.get(j + 1) != Some(&b'(') { i += 1; continue; }
let label_end = j;
j += 2;
let payload_start = j;
depth = 1;
while j < bytes.len() {
match bytes[j] {
b'\\' => { j += 2; continue; }
b'"' | b'\'' | b'\x60' if code || j == payload_start
|| bytes.get(j.wrapping_sub(1)).is_some_and(|b| b" (=,[{:\t".contains(b)) => {
let quote = bytes[j]; j += 1;
while j < bytes.len() {
if bytes[j] == b'\\' { j += 2; }
else if bytes[j] == quote { j += 1; break; }
else { j += 1; }
}
continue;
}
b'(' => depth += 1,
b')' => { depth -= 1; if depth == 0 { break; } }
_ => {}
}
j += 1;
}
if depth == 0 {
found.push(Span { start, end: j + 1, label: &text[start + 1..label_end], payload: text[payload_start..j].trim() });
i = j + 1;
} else { i += 1; }
}
found
}
pub(crate) fn id(line: u32, at: usize) -> String { format!("logic-{line}-{at}") }
fn markdown(text: &str) -> String {
let parser = Parser::new_ext(text, Options::ENABLE_STRIKETHROUGH).map(|event| match event {
Event::Html(value) | Event::InlineHtml(value) => Event::Text(value),
Event::Start(Tag::Image { .. }) => Event::Html("<span class=\"logic-image-label\">".into()),
Event::End(pulldown_cmark::TagEnd::Image) => Event::Html("</span>".into()),
Event::Start(Tag::Link { dest_url, .. }) => Event::Html(format!("<span title=\"{}\">", escape(&dest_url)).into()),
Event::End(pulldown_cmark::TagEnd::Link) => Event::Html("</span>".into()),
other => other,
});
let mut rendered = String::new();
html::push_html(&mut rendered, parser);
rendered
}
fn label_html(label: &str) -> String {
let label = if label.is_empty() { "未命名内容" } else { label };
let value = markdown(label);
value.strip_prefix("<p>").and_then(|v| v.strip_suffix("</p>\n")).unwrap_or(&value).to_string()
}
fn safe_href(target: &str) -> bool {
let normalized: String = target.chars().filter(|c| !c.is_ascii_whitespace() && !c.is_control()).collect();
let lower = normalized.to_ascii_lowercase();
!lower.starts_with("javascript:") && !lower.starts_with("vbscript:")
&& !lower.starts_with("data:") && !lower.starts_with("file:")
}
fn destination(payload: &str) -> Option<String> {
let candidate = format!("[target]({payload})");
let target = Parser::new(&candidate).find_map(|event| match event {
Event::Start(Tag::Link { dest_url, .. }) => Some(dest_url.into_string()),
_ => None,
}).unwrap_or_else(|| payload.trim_matches(['<', '>']).to_string());
let scheme = target.split_once(':').is_some_and(|(scheme, _)|
scheme.starts_with(|c: char| c.is_ascii_alphabetic())
&& scheme.chars().all(|c| c.is_ascii_alphanumeric() || matches!(c, '+' | '-' | '.')));
let relative_path = target.contains('/') && !target.contains(['(', ')'])
&& !target.chars().any(char::is_whitespace)
&& target.starts_with(|c: char| c.is_alphabetic());
let looks_like_link = scheme || relative_path || target.starts_with('#') || target.starts_with('/')
|| target.starts_with("./") || target.starts_with("../")
|| target.starts_with("mailto:") || target.starts_with("tel:")
|| target.to_ascii_lowercase().starts_with("javascript:")
|| target.to_ascii_lowercase().starts_with("data:")
|| target.to_ascii_lowercase().starts_with("vbscript:")
|| [".mq.md", ".md", ".html", ".pdf", ".txt", ".json", ".svg", ".png"]
.iter().any(|ext| target.split(['?', '#']).next().unwrap_or("").ends_with(ext));
looks_like_link.then_some(target)
}
struct Payload { kind: &'static str, heading: &'static str, body: String, href: Option<String> }
fn payload(text: &str) -> Payload {
if text.trim().is_empty() {
return Payload { kind:"empty", heading:"待补充", body:"<p class=\"logic-empty\">待补充实际逻辑</p>".into(), href:None };
}
let expression = crate::parse::expr::parse_expr_prefer_var(text).ok();
if let Some(target) = destination(text).filter(|_| !matches!(expression, Some(Expr::List(_) | Expr::Map(_) | Expr::Literal(_)))) {
let body = if safe_href(&target) {
let external = target.starts_with("https://") || target.starts_with("http://") || target.starts_with("//");
let attributes = if external { " target=\"_blank\" rel=\"noopener noreferrer\"" } else { "" };
format!("<a class=\"logic-link-target\" href=\"{}\" data-document-href=\"{}\"{attributes}><span class=\"logic-link-address\">{}</span><span class=\"logic-link-open\">打开链接 ↗</span></a>", escape(&target), escape(&target), escape(&target))
} else {
format!("<p class=\"logic-link-address\">{}</p><p class=\"logic-hint\">此目标仅作为文字显示,不启用跳转。</p>", escape(&target))
};
return Payload { kind:"link", heading:"跳转链接", body, href:safe_href(&target).then_some(target) };
}
if text.starts_with(['[', '{']) {
if let Ok(value) = serde_json::from_str::<serde_json::Value>(text) {
return Payload { kind:"value", heading:"内容与值", body:json_html(&value, 0), href:None };
}
}
if let Some(expression) = expression {
let (kind, heading) = match expression {
Expr::Call(_) => ("call", "函数调用"),
Expr::List(_) | Expr::Map(_) | Expr::Literal(_) => ("value", "内容与值"),
Expr::Var(_) => ("reference", "引用"),
_ => ("expression", "表达式"),
};
return Payload { kind, heading, body:expression_html(&expression, 0), href:None };
}
Payload { kind:"content", heading:"内容说明", body:format!("<div class=\"logic-content\">{}</div>", markdown(text)), href:None }
}
/// JSON is document content here, never passed to the evaluator as an expression.
fn json_html(value: &serde_json::Value, depth: usize) -> String {
if depth > 5 { return format!("<code class=\"logic-expression\">{}</code>", escape(&value.to_string())); }
match value {
serde_json::Value::Array(values) => {
if values.is_empty() { return "<span class=\"logic-empty-value\">空列表</span>".into(); }
format!("<ol class=\"logic-values\">{}</ol>", values.iter()
.map(|v| format!("<li>{}</li>", json_html(v, depth + 1))).collect::<String>())
}
serde_json::Value::Object(values) => {
if values.is_empty() { return "<span class=\"logic-empty-value\">空记录</span>".into(); }
format!("<dl class=\"logic-arguments\">{}</dl>", values.iter()
.map(|(key, v)| format!("<div class=\"logic-argument\"><dt>{}</dt><dd>{}</dd></div>", escape(key), json_html(v, depth + 1))).collect::<String>())
}
serde_json::Value::String(value) => format!("<span class=\"logic-string\">{}</span>", escape(value)),
_ => format!("<code class=\"logic-expression\">{}</code>", escape(&value.to_string())),
}
}
fn call_name(call: &CallExpr) -> String {
if let Some(receiver) = &call.receiver { format!("{receiver}.{}", call.callee) }
else if let Some(path) = &call.path { path.join(".") }
else { call.callee.clone() }
}
fn expression_html(expression: &Expr, depth: usize) -> String {
if depth > 5 { return format!("<code class=\"logic-expression\">{}</code>", escape(&expr_display(expression))); }
match expression {
Expr::Call(call) => {
let name = call_name(call);
let mut out = format!("<div class=\"logic-call\"><code class=\"logic-call-name\" data-call-name=\"{}\">{}</code>", escape(&name), escape(&name));
if !call.pre_modifiers.is_empty() { out.push_str(&format!("<small class=\"logic-hint\">{}</small>", escape(&call.pre_modifiers.join(" ")))); }
if call.args.is_empty() { out.push_str("<p class=\"logic-no-args\">无需传入参数</p>"); }
else {
out.push_str("<dl class=\"logic-arguments\">");
for (index, argument) in call.args.iter().enumerate() {
let (name, value) = match argument {
Arg::Named { name, value } => (name.clone(), value),
Arg::Positional(value) => (format!("参数 {}", index + 1), value),
};
out.push_str(&format!("<div class=\"logic-argument\"><dt>{}</dt><dd>{}</dd></div>", escape(&name), expression_html(value, depth + 1)));
}
out.push_str("</dl>");
}
out.push_str("</div>"); out
}
Expr::Literal(Literal::Text(value)) =>
format!("<span class=\"logic-string\">{}</span>", escape(value)),
Expr::Literal(_) | Expr::Var(_) =>
format!("<code class=\"logic-expression\">{}</code>", escape(&expr_display(expression))),
Expr::List(values) => {
if values.is_empty() { return "<span class=\"logic-empty-value\">空列表</span>".into(); }
let rows = values.iter().map(|v| format!("<li>{}</li>", expression_html(v, depth + 1))).collect::<String>();
format!("<ol class=\"logic-values\">{rows}</ol>")
}
Expr::Map(values) => {
if values.is_empty() { return "<span class=\"logic-empty-value\">空记录</span>".into(); }
let rows = values.iter().map(|(key, value)| format!("<div class=\"logic-argument\"><dt>{}</dt><dd>{}</dd></div>", escape(key), expression_html(value, depth + 1))).collect::<String>();
format!("<dl class=\"logic-arguments\">{rows}</dl>")
}
Expr::Occluded { label, payload } => format!("<div class=\"logic-nested\"><span class=\"logic-nested-label\">{}</span>{}</div>", escape(label), payload.as_deref().map(|v|expression_html(v,depth+1)).unwrap_or_else(||"<span class=\"logic-empty-value\">待补充实际逻辑</span>".into())),
_ => format!("<code class=\"logic-expression\">{}</code>", escape(&expr_display(expression))),
}
}
pub(crate) fn source(line: u32, span: &Span<'_>, base: usize) -> String {
let id = id(line, base + span.start);
let item = payload(span.payload);
let attrs = format!("id=\"{id}-source\" data-logic-id=\"{id}\" data-line=\"{line}\" data-byte-start=\"{}\" data-byte-end=\"{}\" aria-describedby=\"{id}-note\"", base+span.start,base+span.end);
let label = label_html(span.label);
let mut out = if let Some(href) = item.href {
format!("<a href=\"{}\" data-document-href=\"{}\" class=\"occl-label logic-link-label mq-anchor\" {attrs}>{label}</a>", escape(&href), escape(&href))
} else {
format!("<button type=\"button\" class=\"occl-label mq-anchor\" {attrs} aria-controls=\"{id}-note\" title=\"查看{}(阅读不会执行)\">{label}</button>", item.heading)
};
if item.kind == "empty" { out.push_str("<span class=\"occl-stub\">待补充实际逻辑</span>"); }
out
}
pub(crate) fn note(line: u32, span: &Span<'_>, base: usize, executable: bool) -> String {
let id = id(line, base+span.start);
let item = payload(span.payload);
let hint = if executable { "源码说明 · 不是运行结果" } else { "文档引用 · 阅读不会执行" };
let original = if span.payload.is_empty() && executable { "待补充实际逻辑;当前空遮蔽返回 None。" } else { span.payload };
format!(r#"<details class="annot-chip annot-implementation" id="{id}-note" data-annot-id="{id}" data-annot-kind="implementation" data-logic-kind="{kind}" data-anchor-line="{line}" data-anchor-byte-start="{start}" data-anchor-byte-end="{end}"><summary class="annot-label"><span class="logic-kind">{heading}</span><span class="logic-note-label">{label}</span></summary><div class="annot-value logic-body">{body}<details class="logic-source"><summary>原始写法</summary><pre><code class="occl-code">{original}</code></pre></details></div><small class="logic-hint">{hint}</small></details>"#,
kind=item.kind, start=base+span.start, end=base+span.end, heading=item.heading,
label=label_html(span.label), body=item.body, original=escape(original))
}
pub(crate) struct Narrative {
pub markdown: String,
pub replacements: Vec<(String,String)>,
pub notes: String,
}
pub(crate) fn narrative(line: u32, text: &str, base: usize) -> Narrative {
let mut result = Narrative { markdown:String::new(), replacements:Vec::new(), notes:String::new() };
let mut prefix = format!("MQVIEWLINK{line}X{base}Q");
while text.contains(&prefix) { prefix.push('Q'); }
let mut cursor = 0;
for (index, span) in spans(text, false).into_iter().enumerate() {
let token = format!("{prefix}{index}END");
result.markdown.push_str(&text[cursor..span.start]);
result.markdown.push_str(&token);
result.replacements.push((token,source(line,&span,base)));
result.notes.push_str(&note(line,&span,base,false));
cursor=span.end;
}
result.markdown.push_str(&text[cursor..]);
result
}
pub(crate) fn replace(mut html: String, replacements: &[(String,String)]) -> String {
for (token,value) in replacements { html=html.replace(token,value); }
html
}
/// Link only unambiguous definitions in this document.
pub(crate) fn link_definitions(mut html: String, module: &Module) -> String {
fn walk(functions: &[crate::ast::Function], prefix:&str, names:&mut HashMap<String,Vec<u32>>) {
for function in functions {
let path=if prefix.is_empty(){function.name.clone()}else{format!("{prefix}.{}",function.name)};
names.entry(path.clone()).or_default().push(function.span.line);
if !prefix.is_empty(){names.entry(function.name.clone()).or_default().push(function.span.line);}
walk(&function.children,&path,names);
}
}
let mut names=HashMap::new();walk(&module.functions,"",&mut names);
for (name,lines) in names {
if lines.len()!=1 {continue;}
let escaped=escape(&name);
html=html.replace(&format!("<code class=\"logic-call-name\" data-call-name=\"{escaped}\">{escaped}</code>"),
&format!("<a class=\"logic-definition\" href=\"#fn-{}\" title=\"查看本页函数定义\"><code class=\"logic-call-name\">{escaped}</code><span aria-hidden=\"true\"> ↗</span></a>",lines[0]));
}
html
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn calls_and_collections_containing_urls_remain_structured_values() {
let call = payload("fetch(url=\"https://example.com/file.mq.md\", options={retry: 2})");
assert_eq!(call.kind, "call");
assert!(call.body.contains("logic-call-name") && call.body.contains("<dt>url</dt>"));
assert!(call.body.contains("<dt>options</dt>"));
assert!(!call.body.contains("logic-link-target"));
for text in ["[\"https://example.com\", 2]", "{\"url\": \"https://example.com\"}", "\"guide.mq.md\""] {
assert_eq!(payload(text).kind, "value", "{text}");
}
}
#[test]
fn balanced_scanning_preserves_inline_code_quotes_and_byte_anchors() {
let code = "\"[data](untouched)\" [操作](f(value=\")\", nested=g(2))) [空]()";
let found = spans(code, true);
assert_eq!(found.len(), 2);
assert_eq!(found[0].payload, "f(value=\")\", nested=g(2))");
assert_eq!(&code[found[0].start..found[0].end], "[操作](f(value=\")\", nested=g(2)))");
let narrative = "don't hide [链接](https://example.com/a(b)) or `[代码](opaque)`";
let found = spans(narrative, false);
assert_eq!(found.len(), 1);
assert_eq!(found[0].label, "链接");
}
#[test]
fn unsafe_targets_and_html_are_displayed_without_navigation_or_execution() {
for text in ["javascript:alert(1)", "data:text/html,<svg/onload=alert(1)>", "vbscript:evil"] {
let item = payload(text);
assert_eq!(item.kind, "link");
assert!(item.href.is_none());
assert!(!item.body.contains("<a "));
}
let item = payload("<script>alert(1)</script> beautiful prose");
assert!(!item.body.contains("<script>"));
assert!(item.body.contains("&lt;script&gt;"));
}
#[test]
fn markdown_link_titles_and_nested_parentheses_keep_the_destination() {
for (text, target) in [("https://example.com/a(b)", "https://example.com/a(b)"),
("<guide.mq.md> \"说明\"", "guide.mq.md"), ("#fn-7", "#fn-7")] {
assert_eq!(payload(text).href.as_deref(), Some(target));
}
}
}