//! 统一报告输出:`--report json` 下所有结构化结果走同一套 schema。 //! //! # 为什么要有这一层 //! //! 之前每个子命令自己拼 `println!`,结果是「人看还行、机器没法吃」—— //! 想把 `mpc fl` 的逐轮 loss 画条曲线,得正则去扒终端输出。 //! SecretFlow 那边把结果塞进 protobuf 的 `REPORT` 域(`spec` 仓定义的 //! `Table` / `Histogram` 几种),mpc 没有 IDL,就用最小 JSON 表达同一件事。 //! //! # 约定 //! //! - **进度/诊断**一律 [`note`]:文本模式打 stdout,`--report json` 模式改打 stderr。 //! 这样 stdout 是纯 JSON 流,一行一个对象(NDJSON),`jq .` 能直接消费; //! 一次命令产出多张表(如 `mpc fl` 的逐轮曲线 + 最终权重)也合法。 //! - **结构化结果**一律 [`table`] / [`kv`],schema 固定: //! //! ```json //! {"kind":"table","title":"…","header":["a","b"],"rows":[[1,2.5]]} //! {"kind":"kv","title":"…","rows":[["k","v"]]} //! ``` //! //! 两者都是「行列」,`kv` 只是 `header` 恒为 `["key","value"]` 的简写, //! 单独留一个 `kind` 是为了让消费方(看板、`jq` 过滤)不必猜。 //! //! # 不做什么 //! //! 不引 `serde`。JSON 的产出面就这么点(表、键值、字符串转义), //! 自己写 40 行比带一棵依赖树便宜,也和「单二进制、零依赖」的调子一致。 use std::fmt; use std::io::Write; use std::sync::atomic::{AtomicBool, Ordering}; /// `--report json` 是否生效。 static JSON: AtomicBool = AtomicBool::new(false); /// 由 `main` 在分发子命令前设定一次。 pub fn set_json(on: bool) { JSON.store(on, Ordering::Relaxed); } /// 当前是否 JSON 模式。 pub fn is_json() -> bool { JSON.load(Ordering::Relaxed) } /// 打一行进度/诊断。 /// /// 文本模式进 stdout(保持原有观感),JSON 模式进 stderr(不污染数据流)。 /// 写失败一律忽略 —— `mpc fl | head -5` 会触发 EPIPE,此时该安静退出而不是 panic。 pub fn note(args: fmt::Arguments<'_>) { if is_json() { let _ = writeln!(std::io::stderr(), "{args}"); } else { let _ = writeln!(std::io::stdout().lock(), "{args}"); } } /// 同 [`note`],但不换行(`print!` 的对应物)。 #[allow(dead_code)] pub fn note_inline(args: fmt::Arguments<'_>) { if is_json() { let _ = write!(std::io::stderr(), "{args}"); let _ = std::io::stderr().flush(); } else { let mut out = std::io::stdout().lock(); let _ = write!(out, "{args}"); let _ = out.flush(); } } // --------------------------------------------------------------------------- // 单元格 // --------------------------------------------------------------------------- /// 表格里的一个格子。 /// /// 数字单独成类(而不是先格式化成字符串)是为了照顾两边: /// 文本模式要按人习惯截到固定小数位,JSON 模式要能被 `jq` 当数字算。 #[derive(Debug, Clone)] pub enum Cell { /// 字符串。 Text(String), /// 浮点:`prec` 只在文本模式生效,JSON 走最短往返表示。 Num { v: f64, prec: usize }, /// 整数。 Int(i64), /// 布尔。 Bool(bool), /// 空值:文本模式显示括号里的说明(如 `(空集)`),JSON 出 `null`。 Null(String), } impl Cell { /// 字符串格。 pub fn txt(s: impl Into) -> Self { Self::Text(s.into()) } /// 浮点格,指定文本精度(JSON 一律走最短往返表示,不受 `prec` 影响)。 pub fn nump(v: f64, prec: usize) -> Self { Self::Num { v, prec } } /// 整数格。 pub fn int(v: impl Into) -> Self { Self::Int(v.into()) } /// 布尔格。 pub fn flag(b: bool) -> Self { Self::Bool(b) } /// 空值格,文本模式显示 `(说明)`。 pub fn empty(why: impl Into) -> Self { Self::Null(why.into()) } fn as_text(&self) -> String { match self { Self::Text(s) => s.clone(), Self::Num { v, prec } => { if v.is_finite() { format!("{v:.prec$}") } else { // 文本模式给个可读的记号;JSON 那边会变成 null format!("{v}") } } Self::Int(i) => i.to_string(), Self::Bool(b) => b.to_string(), Self::Null(why) => format!("({why})"), } } fn is_numeric(&self) -> bool { matches!(self, Self::Num { .. } | Self::Int(_)) } fn write_json(&self, out: &mut String) { match self { Self::Text(s) => write_str_json(s, out), Self::Num { v, .. } => { if v.is_finite() { // Display for f64 给的是最短且能往返的表示,正好是合法 JSON 数字 out.push_str(&format!("{v}")); } else { // JSON 没有 NaN/Infinity,降级成 null 比编个字符串诚实 out.push_str("null"); } } Self::Int(i) => out.push_str(&i.to_string()), Self::Bool(b) => out.push_str(if *b { "true" } else { "false" }), Self::Null(_) => out.push_str("null"), } } } impl From<&str> for Cell { fn from(s: &str) -> Self { Self::Text(s.to_string()) } } impl From for Cell { fn from(s: String) -> Self { Self::Text(s) } } // --------------------------------------------------------------------------- // JSON 拼装 // --------------------------------------------------------------------------- /// 写一个 JSON 字符串字面量(含两边的引号)。 fn write_str_json(s: &str, out: &mut String) { out.push('"'); for c in s.chars() { match c { '"' => out.push_str("\\\""), '\\' => out.push_str("\\\\"), '\n' => out.push_str("\\n"), '\r' => out.push_str("\\r"), '\t' => out.push_str("\\t"), c if (c as u32) < 0x20 => { out.push_str(&format!("\\u{:04x}", c as u32)); } c => out.push(c), } } out.push('"'); } fn write_rows_json(header: &[&str], rows: &[Vec], out: &mut String) { out.push_str("\"header\":["); for (i, h) in header.iter().enumerate() { if i > 0 { out.push(','); } write_str_json(h, out); } out.push_str("],\"rows\":["); for (i, row) in rows.iter().enumerate() { if i > 0 { out.push(','); } out.push('['); for (j, cell) in row.iter().enumerate() { if j > 0 { out.push(','); } cell.write_json(out); } out.push(']'); } out.push_str("]}"); } fn emit(line: &str) { let mut out = std::io::stdout().lock(); let _ = writeln!(out, "{line}"); let _ = out.flush(); } /// 输出一张表。文本模式画对齐的表格,JSON 模式输出一个 `kind:"table"` 对象。 /// /// 列对齐按内容决定:整列都是数字就右对齐、否则左对齐。 /// 宽度按**显示宽度**算(CJK 记 2),否则中文表头下面那行会歪。 pub fn table(title: &str, header: &[&str], rows: &[Vec]) { if is_json() { emit(&table_json(title, header, rows)); return; } let mut text: Vec> = rows.iter().map(|r| r.iter().map(Cell::as_text).collect()).collect(); // 行宽不足时补空串,避免下面按下标取越界 for r in text.iter_mut() { while r.len() < header.len() { r.push(String::new()); } } let mut widths: Vec = header.iter().map(|h| disp_width(h)).collect(); for r in &text { for (i, c) in r.iter().enumerate().take(widths.len()) { widths[i] = widths[i].max(disp_width(c)); } } let right: Vec = (0..header.len()) .map(|i| { let non_empty: Vec<&Cell> = rows.iter().filter_map(|r| r.get(i)).collect(); !non_empty.is_empty() && non_empty.iter().all(|c| c.is_numeric()) }) .collect(); let mut out = String::new(); if !title.is_empty() { out.push_str(title); out.push('\n'); } // 表头 let head: Vec = header .iter() .enumerate() .map(|(i, h)| pad(h, widths[i], right[i])) .collect(); out.push_str(head.join(" | ").trim_end()); out.push('\n'); let sep: Vec = widths.iter().map(|w| "-".repeat(*w)).collect(); out.push_str(&sep.join("-+-")); out.push('\n'); for r in &text { let cells: Vec = r .iter() .enumerate() .take(header.len()) .map(|(i, c)| pad(c, widths[i], right[i])) .collect(); // 末列右侧补的空格没人要,还会让复制出来的内容带尾巴 out.push_str(cells.join(" | ").trim_end()); out.push('\n'); } let _ = std::io::stdout().lock().write_all(out.as_bytes()); } /// 输出键值对(`header` 固定为 `key`/`value`)。 pub fn kv(title: &str, rows: &[(&str, Cell)]) { let owned: Vec> = rows .iter() .map(|(k, v)| vec![Cell::txt(*k), v.clone()]) .collect(); table(title, &["key", "value"], &owned); } // --------------------------------------------------------------------------- // 对齐辅助 // --------------------------------------------------------------------------- /// 终端显示宽度:CJK / 全角按 2 列算。 /// /// 只覆盖常见区间。不做完整的 East Asian Width 表 —— 表格里出现的 /// 非 ASCII 字符基本就是中文和全角标点,够用。 fn disp_width(s: &str) -> usize { s.chars() .map(|c| { let u = c as u32; let wide = matches!(u, 0x1100..=0x115F | 0x2E80..=0x303E | 0x3041..=0x33FF | 0x3400..=0x4DBF | 0x4E00..=0x9FFF | 0xA000..=0xA4CF | 0xAC00..=0xD7A3 | 0xF900..=0xFAFF | 0xFE30..=0xFE6F | 0xFF00..=0xFF60 | 0xFFE0..=0xFFE6); if wide { 2 } else { 1 } }) .sum() } fn pad(s: &str, width: usize, right: bool) -> String { let w = disp_width(s); if w >= width { return s.to_string(); } let fill = " ".repeat(width - w); if right { format!("{fill}{s}") } else { format!("{s}{fill}") } } // --------------------------------------------------------------------------- // 把表的 JSON 拼出来(给测试用,也给将来写文件留口子) // --------------------------------------------------------------------------- /// 返回 `table` 在 JSON 模式下会输出的那一行,不打印。 pub fn table_json(title: &str, header: &[&str], rows: &[Vec]) -> String { let mut s = String::from("{\"kind\":\"table\",\"title\":"); write_str_json(title, &mut s); s.push(','); write_rows_json(header, rows, &mut s); s } #[cfg(test)] mod tests { use super::*; #[test] fn escapes_quotes_backslash_and_controls() { let mut s = String::new(); write_str_json("a\"b\\c\nd\te\u{1}", &mut s); assert_eq!(s, r#""a\"b\\c\nd\te\u0001""#); } #[test] fn non_finite_becomes_null_in_json() { let mut s = String::new(); Cell::nump(f64::NAN, 4).write_json(&mut s); assert_eq!(s, "null"); s.clear(); Cell::nump(f64::INFINITY, 4).write_json(&mut s); assert_eq!(s, "null"); // 文本模式仍要给个记号,否则用户只看到空白 assert_eq!(Cell::nump(f64::NAN, 4).as_text(), "NaN"); } #[test] fn null_cell_shows_reason_in_text_only() { let c = Cell::empty("空集"); assert_eq!(c.as_text(), "(空集)"); let mut s = String::new(); c.write_json(&mut s); assert_eq!(s, "null"); } #[test] fn table_json_has_planned_shape() { let rows = vec![ vec![Cell::int(1), Cell::nump(0.5, 4), Cell::txt("ok")], vec![Cell::int(2), Cell::nump(0.75, 4), Cell::flag(true)], ]; let got = table_json("训练", &["轮", "loss", "状态"], &rows); assert_eq!( got, r#"{"kind":"table","title":"训练","header":["轮","loss","状态"],"rows":[[1,0.5,"ok"],[2,0.75,true]]}"# ); } #[test] fn cjk_counts_as_two_columns() { assert_eq!(disp_width("abc"), 3); assert_eq!(disp_width("轮次"), 4); assert_eq!(disp_width("w[0]"), 4); } #[test] fn pad_respects_display_width() { assert_eq!(pad("轮次", 6, false), "轮次 "); assert_eq!(pad("1.5", 5, true), " 1.5"); // 已经超宽就不截断(宁可歪,不要丢信息) assert_eq!(pad("12345", 3, true), "12345"); } #[test] fn numeric_column_detected_for_alignment() { let rows = vec![ vec![Cell::int(1), Cell::txt("x")], vec![Cell::int(22), Cell::txt("y")], ]; let right: Vec = (0..2) .map(|i| rows.iter().filter_map(|r| r.get(i)).all(|c| c.is_numeric())) .collect(); assert_eq!(right, vec![true, false]); } }