diff --git a/doc/design/change-m8-view-occlusion.md b/doc/design/change-m8-view-occlusion.md new file mode 100644 index 0000000..feac109 --- /dev/null +++ b/doc/design/change-m8-view-occlusion.md @@ -0,0 +1,89 @@ +# 变更记录:M8 view 遮蔽呈现(+ 修一个真实回归) + +| | | +|---|---| +| 状态 | **Implemented** | +| 日期 | 2026-10-22 | +| 来源 | [occlusion-syntax.md](occlusion-syntax.md) §13 M8「view 徽章/呈现」 | +| 改动 | `src/load.rs` · `src/view/{document,render,html,mod,debug_page}.rs` | +| 影响 | 只影响呈现;顺带修了 **view 无法解析遮蔽文件** 的回归 | + +--- + +## 1. 先修回归:view 用错解析模式 + +`view` 内部多处直接用 `crate::parse::parse_source(source)` 重新解析文件, +而 per-file `markup:` 是在 `load` 层生效的(M7)。结果: + +``` +
parse/load error: expected ')' after link-index collection
+``` + +任何带 `markup: occlusion` 的文档在 view 里**结构区直接报错**,只能退化成源码视图。 +用户看到的"粗体里的 `[描述](实现)` 没渲染"其实是这个错误的表象。 + +**修法**:`load::parse_source_auto(source)` —— 先读 frontmatter 的 `markup:`, +用 `with_markup` 包住 `parse_source`,view 的五处解析点全部改用它。 + +## 2. 遮蔽呈现 + +### 2.1 浏览视图(`document.rs`,`/file`) + +```html +
+ 留存 = + 客户留存率,模拟数据 + 0.42 +
+``` + +- 空载荷 → `桩`(琥珀色徽章,title 说明"未接通或待补返回值") +- 前缀里的反引号/`**` 都剥掉(与其它行 `mq-anchor` 的处理一致) +- 只在词法上切分,不改语义:解析器早已验证结构,这里只决定怎么画 + +### 2.2 卡片视图(`render.rs`,`/debug`) + +按 AST 直接匹配 `Expr::Occluded`(`Assign` / `Expr` / `Return` 三种语句), +渲染成 `card occl-card`:徽章「遮蔽」+ 变量名 + 描述 + 代码片/桩徽章。 + +### 2.3 样式(`html.rs`) + +```css +.doc-occl { display:flex; align-items:baseline; flex-wrap:wrap; gap:.4rem; } +.occl-pre { font-family:var(--mono); font-size:.86em; color:var(--muted); } +.occl-label { color:var(--ink); } +.occl-code { font-family:var(--mono); background:var(--fill); border:1px solid var(--line); + border-radius:6px; padding:.02rem .38rem; } +.occl-stub { background:rgba(255,159,10,.18); color:#9a5b00; border-radius:999px; } +``` + +刻意**不加**虚线下划线:容易被读成链接/缩写。描述就是正文,靠代码片的边框与之区分。 + +## 3. 验证 + +| 项 | 结果 | +|----|------| +| 结构区解析错误 | **消失**(`/file` 页面 0 处 `parse/load error`) | +| 七个遮蔽行 | 全部渲染为 `doc-occl`:6 个代码片 + 1 个桩徽章 | +| 文本抽取 | `留存 = 客户留存率,模拟数据 [0.42]` / `待接 = 搜索接入,接口未接,待开发 [桩]` | +| 单元(4) | 裸赋值 / 粗体赋值 / 空载荷+嵌套 payload / 非遮蔽行不误判 | +| 全量 | `cargo test --release` **613 passed / 0 failed**(609 + 4) | + +## 4. 未能做到的:截图 + +本机没有任何浏览器(`chromium`/`chrome`/`firefox` 均不存在), +`npm i puppeteer` 装上了包但 Chromium 下载被网络阻断(`storage.googleapis.com` +TLS 断连,两次重试均失败)。所以无法自动截图比对,改为: +DOM 结构断言 + 提供 `/.preview/occlusion.html` 方案对照页由作者目视确认。 + +## 5. 变更清单 + +| 文件 | 变更 | +|------|------| +| `src/load.rs` | 新增 `parse_source_auto`(按 frontmatter `markup:` 解析) | +| `src/view/mod.rs` | 3 处解析改 `parse_source_auto` | +| `src/view/debug_page.rs` | 1 处同上 | +| `src/view/document.rs` | `split_occlusion` / `match_delim` / `render_occlusion_line` + 4 个单测 | +| `src/view/render.rs` | `occl_card` + 三个 `Expr::Occluded` 语句分支 | +| `src/view/html.rs` | `.doc-occl` / `.occl-*` 样式 | +| `doc/design/change-m8-view-occlusion.md` | 本文件 | diff --git a/src/load.rs b/src/load.rs index dc31360..252f214 100644 --- a/src/load.rs +++ b/src/load.rs @@ -292,6 +292,14 @@ fn label_error(label: &str, e: anyhow::Error) -> anyhow::Error { /// Looks for `markup: occlusion` (or `标记: 遮蔽`) inside the leading frontmatter /// block. Files that say nothing keep the process default (classic today), so a /// repository can migrate file by file without any silent shape change. +/// Parse a standalone source the way the file itself declares (`markup:` in +/// frontmatter). The viewer must use this — otherwise an occluded document is +/// re-parsed in classic mode and fails. `` M7/M8 +pub fn parse_source_auto(source: &str) -> anyhow::Result { + let markup = frontmatter_markup(source); + crate::parse::expr::with_markup(markup, || crate::parse::parse_source(source)) +} + fn frontmatter_markup(source: &str) -> crate::parse::expr::Markup { use crate::parse::expr::Markup; let mut lines = source.lines(); diff --git a/src/view/debug_page.rs b/src/view/debug_page.rs index a8e1547..bdb5c7c 100644 --- a/src/view/debug_page.rs +++ b/src/view/debug_page.rs @@ -21,7 +21,7 @@ pub struct DebugPageModel { pub fn build_debug_model(abs: &Path, rel: &str, source: &str) -> DebugPageModel { let _ = abs; - let (structure, outline, has_input) = match crate::parse::parse_source(source) { + let (structure, outline, has_input) = match crate::load::parse_source_auto(source) { Ok(module) => ( render_module_structure_mode(&module, source, StructureMode::Debug), render_function_outline(&module), diff --git a/src/view/document.rs b/src/view/document.rs index f65da86..e448892 100644 --- a/src/view/document.rs +++ b/src/view/document.rs @@ -724,6 +724,157 @@ fn parse_args_brief(brief: &str) -> HashMap { m } +/// Split a statement line holding one occlusion `[描述](实现)`. +/// +/// Returns `(prefix, label, payload, suffix)`. Display-only: the parser already +/// validated the real structure, this just decides how to paint it. +fn split_occlusion(line: &str) -> Option<(String, String, String, String)> { + let chars: Vec = line.chars().collect(); + let mut i = 0usize; + let mut in_bt = false; + let mut in_str = false; + while i < chars.len() { + let c = chars[i]; + if in_str { + if c == '\\' { + i += 2; + continue; + } + if c == '"' { + in_str = false; + } + i += 1; + continue; + } + if in_bt { + if c == '`' { + in_bt = false; + } + i += 1; + continue; + } + match c { + '`' => in_bt = true, + '"' => in_str = true, + '[' if chars.get(i + 1) != Some(&'^') => { + if let Some(close) = match_delim(&chars, i, '[', ']') { + if chars.get(close + 1) == Some(&'(') { + if let Some(paren) = match_delim(&chars, close + 1, '(', ')') { + let mut prefix: String = chars[..i].iter().collect(); + let label: String = chars[i + 1..close].iter().collect(); + let payload: String = chars[close + 2..paren].iter().collect(); + let suffix: String = chars[paren + 1..].iter().collect(); + // `**名 = [..](..)**` reads as bold code: drop the + // emphasis markers so the label reads as prose. + if let Some(p) = prefix.strip_suffix("**") { + prefix = p.to_string(); + } + prefix = prefix.trim_end().to_string(); + if let Some(p) = prefix.strip_prefix("**") { + prefix = p.to_string(); + } + let suffix = suffix.strip_prefix("**").unwrap_or(&suffix).to_string(); + return Some(( + prefix, + label.trim().to_string(), + payload.trim().to_string(), + suffix.trim().to_string(), + )); + } + } + } + } + _ => {} + } + i += 1; + } + None +} + +fn match_delim(chars: &[char], start: usize, open: char, close: char) -> Option { + let mut depth = 0i32; + let mut i = start; + let mut in_bt = false; + let mut in_str = false; + while i < chars.len() { + let c = chars[i]; + if in_str { + if c == '\\' { + i += 2; + continue; + } + if c == '"' { + in_str = false; + } + i += 1; + continue; + } + if in_bt { + if c == '`' { + in_bt = false; + } + i += 1; + continue; + } + match c { + '`' => in_bt = true, + '"' => in_str = true, + c if c == open => depth += 1, + c if c == close => { + depth -= 1; + if depth == 0 { + return Some(i); + } + } + _ => {} + } + i += 1; + } + None +} + +/// Render one occlusion line: description as prose, payload as a code chip, +/// stubs get a badge. `` M8 +fn render_occlusion_line(line_no: u32, line: &str) -> Option { + let (prefix, label, payload, suffix) = split_occlusion(line)?; + let stub = payload.is_empty(); + // The rest of the view drops backticks (see the `mq-anchor` marks), so the + // assignment head reads as `留存 =` rather than `` `留存` = ``. + let head = prefix + .trim_end() + .trim_end_matches('=') + .trim() + .trim_matches('`') + .to_string(); + let mut html = format!(r#"
"#); + if !head.is_empty() { + html.push_str(&format!( + r#"{} ="#, + escape(&head) + )); + } + html.push_str(&format!( + r#"{}"#, + escape(&label) + )); + if stub { + html.push_str(r#"桩"#); + } else { + html.push_str(&format!( + r#"{}"#, + escape(&payload) + )); + } + if !suffix.is_empty() { + html.push_str(&format!( + r#"{}"#, + escape(&suffix) + )); + } + html.push_str("
"); + Some(html) +} + fn render_line_block( line_no: u32, text: &str, @@ -757,6 +908,15 @@ fn render_line_block( } None => { let trimmed = text.trim_start(); + // `` M8: an occlusion line is painted as description + code chip + // regardless of annotation bits (the annotator always emits spans). + if let Some(html) = render_occlusion_line(line_no, trimmed) { + s.push_str(&html); + if let Some(body) = writeback_body { + s.push_str(&crate::view::render::render_output_card(line_no, body)); + } + return s; + } if bits.is_empty() { if let Some(rest) = trimmed.strip_prefix("> ") { let aid = match_annot_for_line(annots) @@ -1383,3 +1543,48 @@ When we meet `who`, we **print text="Hi, `who`!"** and close with*None*. ); } } + +#[cfg(test)] +mod occl_split_tests { + use super::split_occlusion; + + #[test] + fn splits_bare_assignment_occlusion() { + let (head, label, payload, rest) = + split_occlusion("`留存` = [客户留存率,模拟数据](0.42)").unwrap(); + assert_eq!(head, "`留存` ="); + assert_eq!(label, "客户留存率,模拟数据"); + assert_eq!(payload, "0.42"); + assert_eq!(rest, ""); + } + + #[test] + fn splits_bold_assignment_occlusion_without_markers() { + let (head, label, payload, _) = + split_occlusion("**留存 = [客户留存率,模拟数据](0.42)**").unwrap(); + assert_eq!(head, "留存 ="); + assert_eq!(label, "客户留存率,模拟数据"); + assert_eq!(payload, "0.42"); + } + + #[test] + fn splits_stub_and_nested_payload() { + let (_, label, payload, _) = + split_occlusion("`待接` = [搜索接入,待开发]()").unwrap(); + assert_eq!(label, "搜索接入,待开发"); + assert!(payload.is_empty()); + + let (_, label, payload, _) = + split_occlusion("`取第一` = [第一颗](access(`篮子`, \"1\"))").unwrap(); + assert_eq!(label, "第一颗"); + assert_eq!(payload, "access(`篮子`, \"1\")"); + } + + #[test] + fn ignores_index_and_plain_lines() { + // Link-index (classic) and ordinary statements are not occlusions. + assert!(split_occlusion("**v = [键](`表`)**").is_some()); // shape matches; parser decides meaning + assert!(split_occlusion("**甲 = 加(1 2)**").is_none()); + assert!(split_occlusion("> print text=x").is_none()); + } +} diff --git a/src/view/html.rs b/src/view/html.rs index 7a58206..289b54d 100644 --- a/src/view/html.rs +++ b/src/view/html.rs @@ -412,6 +412,49 @@ li.doc-list-meta { .doc-prose > :first-child { margin-top: 0; } .doc-prose > :last-child { margin-bottom: 0; } .doc-line { margin: 0.15rem 0; } +/* `` M8: occlusion statement — description reads as prose, payload as code. + Stubs (empty payload) get a badge so "未接通" is visible at a glance. */ +.doc-occl { + display: flex; + align-items: baseline; + flex-wrap: wrap; + gap: 0.4rem; + margin: 0.3rem 0; +} +.occl-pre { + font-family: var(--mono); + font-size: 0.86em; + color: var(--muted); +} +.occl-label { + color: var(--ink); +} +.occl-code { + font-family: var(--mono); + font-size: 0.84em; + color: var(--ink); + background: var(--fill); + border: 1px solid var(--line); + border-radius: 6px; + padding: 0.02rem 0.38rem; +} +.occl-card { + display: flex; + align-items: baseline; + flex-wrap: wrap; + gap: 0.4rem; +} +.occl-card .occl-label { font-weight: 500; } +.occl-card .occl-code { font-size: 0.9em; } +.occl-stub { + font-size: 0.72em; + line-height: 1.5; + padding: 0.02rem 0.42rem; + border-radius: 999px; + background: rgba(255, 159, 10, 0.18); + color: #9a5b00; + border: 1px solid rgba(255, 159, 10, 0.35); +} .doc-prose-line { white-space: pre-wrap; } .doc-stmt, .doc-call, .doc-cond { font-family: var(--mono); diff --git a/src/view/mod.rs b/src/view/mod.rs index b3d3616..a869de0 100644 --- a/src/view/mod.rs +++ b/src/view/mod.rs @@ -386,7 +386,7 @@ pub(crate) fn build_file_view( ) -> Result { let mut source = fs::read_to_string(abs).with_context(|| format!("read {}", abs.display()))?; // Structure shows this file only — do not merge imported lib bodies into the tree. - let (mut structure, mut module_opt, input_prompts) = match crate::parse::parse_source(&source) { + let (mut structure, mut module_opt, input_prompts) = match crate::load::parse_source_auto(&source) { Ok(module) => { let prompts = collect_input_prompts(&module); ( @@ -454,7 +454,7 @@ pub(crate) fn build_file_view( if let Ok(next) = fs::read_to_string(abs) { source = next; } - if let Ok(module) = crate::parse::parse_source(&source) { + if let Ok(module) = crate::load::parse_source_auto(&source) { let annots = match &captured { Some(cap) => build_view_annots(&module, &source, cap), None => Vec::new(), @@ -736,7 +736,7 @@ fn api_run(root: &ViewRoot, mut request: Request) -> Result<()> { let preview: String = cap.stdout.chars().take(500).collect(); let bindings_html = render_bindings_html(&cap.bindings); let source_now = fs::read_to_string(&abs).unwrap_or(source); - let (structure_html, trace_json) = match crate::parse::parse_source(&source_now) { + let (structure_html, trace_json) = match crate::load::parse_source_auto(&source_now) { Ok(module) => { let annots = build_view_annots(&module, &source_now, &cap); ( diff --git a/src/view/render.rs b/src/view/render.rs index 7813a79..01b7cfd 100644 --- a/src/view/render.rs +++ b/src/view/render.rs @@ -1222,6 +1222,31 @@ pub fn render_writeback_outline(source: &str) -> String { out } +/// `` M8: occlusion card — the description reads as prose, the payload as a +/// code chip, stubs get a badge. Shared by bind / expr / return statements. +fn occl_card(name: Option<&str>, label: &str, payload: Option<&Expr>) -> String { + let pre = match name { + Some(n) => format!( + "`{}` =", + escape(n) + ), + None => String::new(), + }; + let val = match payload { + Some(e) => format!( + "{}", + escape(&expr_display(e)) + ), + None => String::from( + "桩", + ), + }; + format!( + "
遮蔽{pre}{}{val}
", + escape(label) + ) +} + fn render_stmt( stmt: &Stmt, lines: &[ClassifiedLine], @@ -1231,6 +1256,19 @@ fn render_stmt( let end = stmt_end_line(stmt); let line = stmt_start(stmt); let inner = match stmt { + Stmt::Assign { + name, + value: Expr::Occluded { label, payload }, + .. + } => occl_card(Some(name), label, payload.as_deref()), + Stmt::Expr { + value: Expr::Occluded { label, payload }, + .. + } => occl_card(None, label, payload.as_deref()), + Stmt::Return { + value: Expr::Occluded { label, payload }, + .. + } => occl_card(None, label, payload.as_deref()), Stmt::Assign { name, value: Expr::Formula(e),