niceeval 0.5.3 → 0.6.0

package/src/report/text/layout.ts

@@ -1,5 +1,10 @@
 // text 面的排版工具:显示宽度(CJK 记 2 列)、填充、折行、对齐列、字符条形。
 // 全部纯函数、零依赖;niceeval show 的终端输出与 Row 分栏都建立在这几样上。
+//
+// 其中七个是公开面(`niceeval/report` 以 stringWidth / padEnd / padStart / wrapText /
+// indent / bar / columns 的名字导出,见 ../index.ts):自定义组件的 text 面必须拿到与
+// 官方组件同一把尺子,否则「用户组件与官方组件对等」是假的。它们的 TSDoc 就是公开文档,
+// 改签名即破坏公开面。renderAlignedRows 不导出 —— 表格的能力由 <Table> 原语承担。
 
 /** 终端显示宽度:CJK / 全角记 2 列,其余记 1。启发式覆盖常用区段,够对齐表格用。 */
 export function charDisplayWidth(codePoint: number): number {
@@ -22,27 +27,55 @@ export function charDisplayWidth(codePoint: number): number {
   return 1;
 }
 
+/**
+ * 一段文本在终端里占几列:CJK / 全角字符记 2 列,其余记 1 列。
+ *
+ * 对齐终端输出用它,不要用 `String.prototype.length`——`length` 数的是 UTF-16 码元,
+ * 一个汉字占 2 个显示列却只算 1 个码元,中文一进来列就错位。
+ *
+ * @param text 任意文本。
+ * @returns 显示列数。
+ */
 export function stringWidth(text: string): number {
   let width = 0;
   for (const ch of text) width += charDisplayWidth(ch.codePointAt(0)!);
   return width;
 }
 
-/** 右侧补空格到目标显示宽度(超宽不截断,如实溢出)。 */
+/**
+ * 按显示宽度在右侧补空格(左对齐)。超宽不截断,如实溢出。
+ *
+ * `String.prototype.padEnd` 的显示宽度版:内容含中文时才对得齐。
+ *
+ * @param text 要补齐的文本。
+ * @param width 目标显示宽度。
+ * @returns 补齐后的文本。
+ */
 export function padDisplay(text: string, width: number): string {
   const gap = width - stringWidth(text);
   return gap > 0 ? text + " ".repeat(gap) : text;
 }
 
-/** 左侧补空格(数字右对齐用)。 */
+/**
+ * 按显示宽度在左侧补空格(右对齐)。超宽不截断,如实溢出。
+ *
+ * 数字列靠它对齐小数点。
+ *
+ * @param text 要补齐的文本。
+ * @param width 目标显示宽度。
+ * @returns 补齐后的文本。
+ */
 export function padStartDisplay(text: string, width: number): string {
   const gap = width - stringWidth(text);
   return gap > 0 ? " ".repeat(gap) + text : text;
 }
 
 /**
- * 按显示宽度折行:优先在空格处断,连续超宽(如中文)按列宽硬断。
- * 返回至少一行(空串输入 → [""])。
+ * 按显示宽度折行:优先在空格处断,单个词超宽(URL / 中文长句)按列宽硬断。
+ *
+ * @param text 要折行的文本(`\n` 分段)。
+ * @param width 每行的最大显示宽度。
+ * @returns 折好的行;至少一行(空串输入 → `[""]`)。
  */
 export function wrapDisplay(text: string, width: number): string[] {
   const max = Math.max(4, width);
@@ -80,7 +113,13 @@ export function wrapDisplay(text: string, width: number): string[] {
   return lines.length > 0 ? lines : [""];
 }
 
-/** 每行前加缩进。 */
+/**
+ * 给一整块文本的每行加同一段前缀(嵌套块缩进)。空行不加,不留尾随空格。
+ *
+ * @param block 多行文本。
+ * @param indent 每行的前缀,通常是若干空格。
+ * @returns 缩进后的文本块。
+ */
 export function indentBlock(block: string, indent: string): string {
   return block
     .split("\n")
@@ -88,8 +127,21 @@ export function indentBlock(block: string, indent: string): string {
     .join("\n");
 }
 
-/** 对齐列渲染:每列宽 = 该列最宽格,列间 3 空格。首行是表头。 */
-export function renderAlignedRows(rows: string[][]): string {
+/** 列对齐方向:`"left"` 是默认,`"right"` 按显示宽度右对齐(数字列用)。 */
+export type ColumnAlign = "left" | "right";
+
+/**
+ * 对齐列渲染:每列宽 = 该列最宽格的显示宽度,列间 3 空格,行尾不留空白。首行是表头。
+ * `align[c]` 给第 c 列的对齐方向,缺省 `"left"`。
+ *
+ * 内部件:公开面是 <Table> 原语(见 ./table.ts 的 renderTableText,它先按 ctx.width
+ * 定好列宽再调这里)。不导出到 `niceeval/report` —— 两条并行的建表路径只会让作者选错。
+ */
+export function renderAlignedRows(
+  rows: string[][],
+  align: readonly ColumnAlign[] = [],
+  separator = "   ",
+): string {
   const columnCount = Math.max(...rows.map((r) => r.length), 0);
   const widths: number[] = [];
   for (let c = 0; c < columnCount; c++) {
@@ -98,21 +150,34 @@ export function renderAlignedRows(rows: string[][]): string {
   return rows
     .map((row) =>
       row
-        .map((cell, c) => (c === row.length - 1 ? cell : padDisplay(cell, widths[c])))
-        .join("   ")
+        .map((cell, c) => (align[c] === "right" ? padStartDisplay(cell, widths[c]) : padDisplay(cell, widths[c])))
+        .join(separator)
         .replace(/\s+$/, ""),
     )
     .join("\n");
 }
 
-/** 字符条形:filled 比例 → █ 填充、░ 补齐到 barWidth。 */
+/**
+ * 字符条形:比例 → `█` 填充、`░` 补齐到 `barWidth` 显示列。比例超出 [0, 1] 时钳住。
+ *
+ * @param ratio 填充比例,0 到 1。
+ * @param barWidth 整条的显示宽度。
+ * @returns 定宽的字符条。
+ */
 export function textBar(ratio: number, barWidth: number): string {
   const clamped = Math.max(0, Math.min(1, ratio));
   const filled = Math.round(clamped * barWidth);
   return "█".repeat(filled) + "░".repeat(barWidth - filled);
 }
 
-/** 多块并排(Row 的 text 面):逐行拼接,各栏折到自己的宽度,短栏补齐。 */
+/**
+ * 多块文本并排成栏(`Row` 的 text 面):逐行拼接,各栏按显示宽度补齐,短栏补空行。
+ *
+ * @param blocks 每栏一块多行文本。
+ * @param columnWidths 每栏的显示宽度,与 `blocks` 一一对应。
+ * @param separator 栏间分隔符,默认 `" │ "`。
+ * @returns 并排后的文本块。
+ */
 export function joinColumns(blocks: string[], columnWidths: number[], separator = " │ "): string {
   const columns = blocks.map((block) => block.split("\n"));
   const height = Math.max(...columns.map((lines) => lines.length), 0);

package/src/report/text/table.ts

@@ -0,0 +1,98 @@
+// <Table> 原语的 text 面(../primitives.tsx 的 Table.text 就是它)。
+// 官方的表状组件(MetricTable / MetricMatrix / Scoreboard / DeltaTable)的 text 面也直接
+// 调它 —— 官方与自定义表共用同一个渲染器,是「用户组件与官方组件对等」的构造证明:
+// 官方用不上的能力用户就拿不到,官方绕过它手搓它就一定会长歪。
+//
+// 列宽按显示宽度算(CJK 记 2 列);null 渲染 —,不补 0;超宽先折最宽的左对齐列,
+// 压到下限仍放不下就从右侧丢列并如实报数(「截断报剩余」是既有契约,不在这里破例)。
+
+import type { TableProps, TableRow } from "../primitives.tsx";
+import type { TextContext } from "../tree.ts";
+import { countText, localeText } from "../locale.ts";
+import { renderAlignedRows, stringWidth, wrapDisplay, type ColumnAlign } from "./layout.ts";
+
+const MISSING_MARK = "—";
+/** 列间距,与 renderAlignedRows 的 join("   ") 一致。 */
+const COLUMN_GAP = 3;
+/** 左对齐列的压缩下限:再窄就读不成句,宁可丢列。 */
+const MIN_TEXT_COLUMN = 8;
+
+/** 格子的文本形态:缺这个键、或值是 null,都渲染 —(与 web 面同源)。 */
+function cellText(row: TableRow, key: string): string {
+  const value = row.cells[key];
+  return value === null || value === undefined ? MISSING_MARK : value;
+}
+
+function totalWidth(widths: readonly number[]): number {
+  return widths.reduce((sum, w) => sum + w, 0) + COLUMN_GAP * Math.max(0, widths.length - 1);
+}
+
+/**
+ * 自然列宽 → 放得进 available 的列宽。两步,顺序即优先级:
+ * 1. 压最宽的左对齐列(文本列)到下限 —— 右对齐列是数字,折行读不了,不压;
+ * 2. 仍放不下就从右侧丢列(至少留一列),丢了几列如实返回。
+ */
+function fitWidths(
+  natural: readonly number[],
+  align: readonly ColumnAlign[],
+  available: number,
+): { widths: number[]; hidden: number } {
+  const widths = [...natural];
+  while (totalWidth(widths) > available) {
+    let widest = -1;
+    for (let c = 0; c < widths.length; c++) {
+      if (align[c] === "right" || widths[c] <= MIN_TEXT_COLUMN) continue;
+      if (widest === -1 || widths[c] > widths[widest]) widest = c;
+    }
+    if (widest === -1) break;
+    const over = totalWidth(widths) - available;
+    widths[widest] = Math.max(MIN_TEXT_COLUMN, widths[widest] - over);
+  }
+  let hidden = 0;
+  while (widths.length > 1 && totalWidth(widths) > available) {
+    widths.pop();
+    hidden += 1;
+  }
+  return { widths, hidden };
+}
+
+/** 逻辑行 → 物理行:每格折到自己的列宽,行高取最高的那格,矮格补空串。 */
+function toPhysicalRows(cells: readonly string[], widths: readonly number[]): string[][] {
+  const wrapped = cells.map((cell, c) =>
+    // 放得下就原样保留:wrapDisplay 会把连续空格折成一个,而 DeltaTable 的
+    // "50% → 62%   +12pp" 这类格子内含固定间距 —— 不折行时一个字节都不能动。
+    !cell.includes("\n") && stringWidth(cell) <= widths[c] ? [cell] : wrapDisplay(cell, widths[c]),
+  );
+  const height = Math.max(...wrapped.map((lines) => lines.length), 1);
+  const out: string[][] = [];
+  for (let i = 0; i < height; i++) out.push(wrapped.map((lines) => lines[i] ?? ""));
+  return out;
+}
+
+/**
+ * <Table> 的 text 面:columns × rows → 对齐的字符表。
+ * 有任一行带 locator 时追加一列 attempt(locator 本身就是 `niceeval show <locator>`
+ * 的位置参数;逐行重复整条命令会把表撑宽,与三个实体列表 text 面的既有取舍一致)。
+ */
+export function renderTableText(props: TableProps, ctx: TextContext): string {
+  const locale = props.locale ?? ctx.locale;
+  const hasLocator = props.rows.some((row) => row.locator !== undefined);
+  if (props.columns.length === 0 && !hasLocator) return "";
+
+  const header = props.columns.map((column) => column.header);
+  const align: ColumnAlign[] = props.columns.map((column) => column.align ?? "left");
+  const body = props.rows.map((row) => props.columns.map((column) => cellText(row, column.key)));
+  if (hasLocator) {
+    header.push(localeText(locale, "table.attempt"));
+    align.push("left");
+    props.rows.forEach((row, i) => body[i].push(row.locator ?? MISSING_MARK));
+  }
+
+  const matrix = [header, ...body];
+  const natural = header.map((_, c) => Math.max(...matrix.map((row) => stringWidth(row[c] ?? ""))));
+  const { widths, hidden } = fitWidths(natural, align, ctx.width);
+
+  const physical = matrix.flatMap((row) => toPhysicalRows(row.slice(0, widths.length), widths));
+  const table = renderAlignedRows(physical, align);
+  return hidden > 0 ? `${table}\n${countText(locale, "table.columnsHidden", hidden)}` : table;
+}

package/src/report/tree.ts

@@ -1,13 +1,14 @@
-// 报告的元素树与双面组件基座(docs/reports.md「元素树与两个宿主」「双面组件」)。
+// 报告的元素树与双面组件基座(docs/feature/reports/architecture.md「报告树与两个宿主」)。
 //
 // 报告函数返回的树不是「React 树」,只是 { type, props } 节点 —— 标准 react
 // jsx-runtime 产的元素恰好就是这个形状。本文件是基础实现:零 react 运行时依赖
 // (只有类型层的 `import type`,编译后擦除);text 宿主遍历渲染不需要 react-dom,
 // web 宿主(web.ts)才真正 import react。渲染面是纯同步函数:零 IO、零 await ——
-// 计算全部发生在报告函数体里,可达百 MB 的工件永远不进渲染路径。
+// 计算全部发生在报告函数体里,可达百 MB 的 artifact 永远不进渲染路径。
 
 import type { ReactNode } from "react";
-import type { AttemptRef } from "../results/index.ts";
+import type { AttemptLocator } from "../results/locator.ts";
+import { DEFAULT_REPORT_LOCALE, type ReportLocale } from "./locale.ts";
 
 // ───────────────────────── 节点形状 ─────────────────────────
 
@@ -43,29 +44,42 @@ export const COMPONENT_FACES: unique symbol = Symbol.for("niceeval.report.faces"
 export interface TextContext {
   /** 可用列宽;Row 分栏后变窄。 */
   width: number;
+  /** chrome 文案的 locale(verdict 词、注脚、占位符);默认 "en",show 输出不变。 */
+  locale: ReportLocale;
   /** 容器组件渲染 children 用,宽度显式传递。 */
   render(node: ReportNode, width?: number): string;
-  /** 下钻命令,通证据室。 */
-  attemptCommand(ref: AttemptRef): string;
+  /** 下钻命令,通证据室:`niceeval show @<locator>`。 */
+  attemptCommand(locator: AttemptLocator): string;
 }
 
 export interface WebContext {
-  /** 证据室深链,同 view 的 attempt 路由。 */
-  attemptHref(ref: AttemptRef): string;
+  /** 证据室深链,同 view 的 attempt 路由(`#/attempt/@<locator>`,单段、不透明)。 */
+  attemptHref(locator: AttemptLocator): string;
+  /** chrome 文案的 locale;官方组件渲染面经上下文读取,宿主外默认 "en"。 */
+  locale: ReportLocale;
 }
 
-export interface ComponentFaces<P> {
-  /** 真 React JSX 在这个面里;返回静态可渲染的 ReactNode。 */
-  web(props: P, ctx: WebContext): ReactNode;
-  text(props: P, ctx: TextContext): string;
+export interface ComponentFaces<P, R = P> {
+  /**
+   * 可选的数据解析面:把声明式 props(selection + 计算选项)在渲染前解析成纯数据 props(R)。
+   * 宿主的 {@link resolveReportTree} 在 build 之后、validate / render 之前调用它——这是整条
+   * 管线里唯一允许 await / IO 的组件级步骤;渲染面(web / text)只看已解析的 R,保持同步、零 IO。
+   * 不实现 resolve 时 R = P,组件被当作纯数据组件直接渲染。
+   */
+  resolve?(props: P): Promise<R>;
+  /** 真 React JSX 在这个面里;返回静态可渲染的 ReactNode。只看已解析的 R。 */
+  web(props: R, ctx: WebContext): ReactNode;
+  text(props: R, ctx: TextContext): string;
 }
 
 /**
  * 双面组件的产物:可直接用于 JSX(React 把它当函数组件调用,走 web 面),
- * text 宿主经 COMPONENT_FACES 调 text 面。
+ * text 宿主经 COMPONENT_FACES 调 text 面。R(解析后 props 形态)在存储边界抹成 any——
+ * 树遍历只按 ComponentFaces 的结构调用 resolve / web / text,不需要在类型层追踪 R。
  */
 export type ReportComponent<P> = ((props: P) => ReactNode) & {
-  [COMPONENT_FACES]: ComponentFaces<P>;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  [COMPONENT_FACES]: ComponentFaces<P, any>;
   displayName?: string;
 };
 
@@ -73,8 +87,13 @@ export type ReportComponent<P> = ((props: P) => ReactNode) & {
 // 用默认值 —— attemptHref 默认 view 的 attempt 路由格式(自定义组件显式调 ctx.attemptHref
 // 时总有去处);官方组件的「宿主里自动接证据室」只在宿主上下文激活时发生,
 // 宿主外不传 attemptHref 就是纯展示,不发明断链。
+//
+// URL 格式取 `#/attempt/${locator}`:AttemptLocator 本身已经是 `@` 前缀的不透明短串
+// (如 "@1x7f3q9"),原样嵌进路径段就得到 `#/attempt/@1x7f3q9`——与 docs/feature/reports/view.md「用
+// Reports 积木重建 view」定稿的单段路由逐字一致,不额外拆分或去掉 `@`。
 const DEFAULT_WEB_CONTEXT: WebContext = {
-  attemptHref: (ref) => `#/attempt/${ref.run}/${ref.result}`,
+  attemptHref: (locator) => `#/attempt/${locator}`,
+  locale: DEFAULT_REPORT_LOCALE,
 };
 let activeWebContext: WebContext | null = null;
 
@@ -98,14 +117,18 @@ export function isHostWebContextActive(): boolean {
  * 定义一个双面组件:faces 两键必填 —— 少实现一个面编译不过,配对是结构义务。
  * 基础实现不 import react;产物以可调用组件的形状兼容 React 渲染。
  */
-export function defineComponent<P>(faces: ComponentFaces<P>): ReportComponent<P> {
+export function defineComponent<P, R = P>(faces: ComponentFaces<P, R>): ReportComponent<P> {
   if (typeof faces?.web !== "function" || typeof faces?.text !== "function") {
     throw new Error(
       "defineComponent requires both faces: { web(props, ctx), text(props, ctx) }. " +
         "Every report component must render in both hosts (niceeval view and niceeval show).",
     );
   }
-  const component = ((props: P) => faces.web(props, activeWebContext ?? DEFAULT_WEB_CONTEXT)) as ReportComponent<P>;
+  // 直接调用路径:把组件当普通 React 组件嵌进用户自己的页面时走这里,web 面只接收数据形态
+  // props(R)。带 resolve 的组件若拿 selection 形态 props 走这条裸路径,web 面会缺 data ——
+  // 这类组件只有经宿主的 resolveReportTree 解析后才安全渲染;纯数据 props 一直可以裸嵌。
+  const component = ((props: P) =>
+    faces.web(props as unknown as R, activeWebContext ?? DEFAULT_WEB_CONTEXT)) as ReportComponent<P>;
   component[COMPONENT_FACES] = faces;
   return component;
 }
@@ -115,6 +138,60 @@ export function facesOf(type: unknown): ComponentFaces<unknown> | undefined {
   return (type as Partial<ReportComponent<unknown>>)[COMPONENT_FACES] as ComponentFaces<unknown> | undefined;
 }
 
+// ───────────────────────── 数据解析(渲染前唯一的 await 边界)─────────────────────────
+
+/**
+ * 报告 build 之后、树校验与 text/web 渲染之前的解析遍历:把声明式数据组件(实现了
+ * `faces.resolve` 的双面组件,如 selection 形态的 MetricScatter)的 props
+ * 就地换成算好的数据形态 props(三个实体列表没有 `resolve` 面,不经这一步——它们的 `items`
+ * 由报告作者在 `build()` 里直接 `await .data(selection)` 备好)。计算发生在这里(唯一允许
+ * await 的组件级步骤,连同报告函数体自己的 `build()`),两个渲染面
+ * 之后都只看已解析的树、保持同步零 IO。遍历形状与 {@link validateReportTree} /
+ * {@link renderNodeToText} 一致:
+ *
+ * - 同层数组兄弟并行解析(`Promise.all`),保持原始顺序 / keys;
+ * - 双面组件带 resolve 的:调 `faces.resolve(props)` 换 props(有 children 再递归解析);
+ * - 双面组件无 resolve 的(Row / Col / Section / RunOverview…):只递归 children,自身 props
+ *   原样保留(title / className 等不能动);
+ * - 普通函数组件:同步调用展开,展开结果继续解析(与 validate / render 对函数组件的处理一致);
+ * - 字符串 intrinsic(<div>):原样返回,交给随后的 validateReportTree 报同一条错误。
+ *
+ * resolver 跑完后,树里已没有函数组件 / 未解析 props;validate / render 里对这两者的分支在
+ * 正常管线下是 no-op,但保留着——手搭树直接调 validate / render(不过 resolver)的低层用法仍需要。
+ */
+export async function resolveReportTree(node: ReportNode): Promise<ReportNode> {
+  if (node === null || node === undefined || typeof node === "boolean") return node;
+  if (typeof node === "string" || typeof node === "number") return node;
+  if (Array.isArray(node)) return Promise.all(node.map(resolveReportTree));
+  if (!isReportElement(node)) return node;
+  const { type, props } = node;
+  // 字符串 intrinsic:不在这里报错,让 resolve 后的 validateReportTree 抛统一的那条。
+  if (typeof type === "string") return node;
+  if (type === REACT_FRAGMENT) {
+    const children = await resolveReportTree(props.children as ReportNode);
+    return { ...node, props: { ...props, children } };
+  }
+  const faces = facesOf(type);
+  if (faces) {
+    if (typeof faces.resolve === "function") {
+      const resolvedProps = { ...((await faces.resolve(props)) as Record<string, unknown>) };
+      if (resolvedProps.children !== undefined) {
+        resolvedProps.children = await resolveReportTree(resolvedProps.children as ReportNode);
+      }
+      return { ...node, props: resolvedProps };
+    }
+    // 无 resolve 的容器 / 数据组件:只解析 children,自身 props 原样保留。
+    const children = await resolveReportTree(props.children as ReportNode);
+    return { ...node, props: { ...props, children } };
+  }
+  if (typeof type === "function") {
+    // 普通函数组件:调用展开,展开结果整体替换本节点后继续解析。
+    const expanded = (type as (p: unknown) => ReportNode)(props);
+    return resolveReportTree(expanded);
+  }
+  return node;
+}
+
 // ───────────────────────── 树校验 ─────────────────────────
 
 function componentLabel(type: unknown): string {
@@ -174,16 +251,22 @@ export function validateReportTree(node: ReportNode, path: string[] = []): void
 export interface TextRenderOptions {
   /** 终端可用列宽;默认 80。 */
   width?: number;
-  /** 下钻命令的生成;宿主注入,默认指向 view 的 attempt 路由。 */
-  attemptCommand?: (ref: AttemptRef) => string;
+  /** 下钻命令的生成;宿主注入,默认 `niceeval show @<locator>`(真实可跑的 CLI 语法)。 */
+  attemptCommand?: (locator: AttemptLocator) => string;
+  /** chrome 文案的 locale;默认 "en"(`niceeval show` 现有输出不变)。 */
+  locale?: ReportLocale;
 }
 
 export function createTextContext(options?: TextRenderOptions): TextContext {
   const width = Math.max(20, options?.width ?? 80);
-  const attemptCommand =
-    options?.attemptCommand ?? ((ref: AttemptRef) => `niceeval view "#/attempt/${ref.run}/${ref.result}"`);
+  const locale = options?.locale ?? DEFAULT_REPORT_LOCALE;
+  // 默认下钻命令:AttemptLocator 是 `@` 前缀的不透明短串,`niceeval show @<locator>` 是
+  // show/index.ts 已实现的真实 CLI 语法(见该文件 `@<locator>` 位置参数解析),不需要
+  // 反查 eval id 再拼一条近似命令。
+  const attemptCommand = options?.attemptCommand ?? ((locator: AttemptLocator) => `niceeval show ${locator}`);
   const make = (w: number): TextContext => ({
     width: w,
+    locale,
     attemptCommand,
     render(node, childWidth) {
       return renderNodeToText(node, childWidth === undefined ? this : make(Math.max(10, childWidth)));