niceeval 0.6.1 → 0.7.0

package/dist/report/flag.d.ts

@@ -1,6 +1,32 @@
-import type { FlagRef } from "./types.ts";
-export declare function flag(name: string, opts?: {
-    /** 组标签 / 轴标签;函数形态把声明值折成组名(如 `(v) => \`${v} agents\``)。 */
-    label?: string | ((value: string | number | boolean) => string);
-    unit?: string;
-}): FlagRef;
+import type { AttemptHandle } from "../results/types.ts";
+import type { DimensionOptions, DimensionRef, NumericAxis, NumericAxisOptions, NumericRunConfigAxisOptions, RunConfigKey } from "./types.ts";
+/** experiment 声明的 flags(快照级投影优先;第三方落盘只拼在条目上时回退 result.experiment)。 */
+export declare function flagValueOf(attempt: AttemptHandle, name: string): unknown;
+/**
+ * runConfig() 的取值:读快照的 `ExperimentRunInfo` 投影,外加桥接到快照顶层权威字段的
+ * `model` / `agent` 两个键(与 "model" / "agent" 内置维度同一读法,不另造第二套口径)。
+ * 未投影 → undefined。
+ */
+export declare function runConfigValueOf(attempt: AttemptHandle, name: RunConfigKey): unknown;
+/**
+ * 把 experiment 声明的一个 flag 当分组维度(rows / columns / points / series / by 槽)。
+ * 分组显示键按稳定 JSON 规则生成(字符串直接显示,其它值用键递归排序后的 JSON),
+ * 缺失值显示内置文案 `(missing)`;显示键冲突时计算报错并要求改用 CustomDimension。
+ */
+export declare function flag(name: string, options?: DimensionOptions): DimensionRef;
+/**
+ * 把一项顶层运行配置当分组维度,与 {@link flag} 同一套用法。读快照的 `ExperimentRunInfo`
+ * 投影;可用键由 RunConfigKey 在类型层穷尽(那张接口的字段全集,外加桥接到快照顶层权威
+ * 字段的 `model` / `agent`),拼错键在编译期就被拒绝。
+ */
+export declare function runConfig(name: RunConfigKey, options?: DimensionOptions): DimensionRef;
+/**
+ * MetricLine 的 x 轴:只接受落盘值为 number 的 flag。未声明或非数值的 attempt 返回 null
+ * (折线不绘该点并报告缺失),不猜 `low < medium < high`。
+ */
+export declare function numericFlag(name: string, options?: NumericAxisOptions): NumericAxis;
+/**
+ * 顶层运行配置作数值轴:数值配置直接返回该值;字符串配置必须显式给 `map`
+ * (如 { low: 1, medium: 2, high: 3 })。未声明、未投影、非数值或未命中 map 的值返回 null。
+ */
+export declare function numericRunConfig(name: RunConfigKey, options?: NumericRunConfigAxisOptions): NumericAxis;

package/dist/report/flag.js

@@ -1,8 +1,96 @@
-// flag():把 experiment 声明的 flags 当维度或轴(docs/feature/reports/library.md「维度与 flags」)。
+// flag() / runConfig() / numericFlag() / numericRunConfig():把 experiment 声明的变量当
+// 分组维度或数值轴(docs/feature/reports/library/metrics.md「维度与数值轴」)。
 // 变量来自配置,不来自命名 —— 报告不解析 experiment id 字符串抠变量。
-export function flag(name, opts) {
+// flag() 只读 `ExperimentDef.flags` 里显式声明的 KV;model / reasoningEffort / budget / runs
+// 这类顶层运行配置不在 flags 里,用 runConfig() 读快照的 ExperimentRunInfo 投影。
+/** experiment 声明的 flags(快照级投影优先;第三方落盘只拼在条目上时回退 result.experiment)。 */
+export function flagValueOf(attempt, name) {
+    const info = attempt.snapshot?.experiment ?? attempt.result.experiment;
+    return info?.flags?.[name];
+}
+/**
+ * runConfig() 的取值:读快照的 `ExperimentRunInfo` 投影,外加桥接到快照顶层权威字段的
+ * `model` / `agent` 两个键(与 "model" / "agent" 内置维度同一读法,不另造第二套口径)。
+ * 未投影 → undefined。
+ */
+export function runConfigValueOf(attempt, name) {
+    if (name === "model")
+        return attempt.result.model ?? attempt.snapshot?.model;
+    if (name === "agent")
+        return attempt.result.agent || attempt.snapshot?.agent;
+    const info = attempt.snapshot?.experiment ?? attempt.result.experiment;
+    // ExperimentRunInfo 是穷尽可序列化投影;按字段名取值,新增投影字段无需改这里
+    return info?.[name];
+}
+function assertName(name, fn, hint) {
     if (typeof name !== "string" || name.length === 0) {
-        throw new Error("flag: name must be a non-empty string (the key declared in the experiment's flags).");
+        throw new Error(`${fn}: name must be a non-empty string (${hint}).`);
     }
-    return { kind: "flag", name, label: opts?.label, unit: opts?.unit };
+}
+/**
+ * 把 experiment 声明的一个 flag 当分组维度(rows / columns / points / series / by 槽)。
+ * 分组显示键按稳定 JSON 规则生成(字符串直接显示,其它值用键递归排序后的 JSON),
+ * 缺失值显示内置文案 `(missing)`;显示键冲突时计算报错并要求改用 CustomDimension。
+ */
+export function flag(name, options) {
+    assertName(name, "flag", "the key declared in the experiment's flags");
+    return {
+        kind: "flag",
+        name,
+        ...(options?.label !== undefined ? { label: options.label } : {}),
+        ...(options?.unit !== undefined ? { unit: options.unit } : {}),
+    };
+}
+/**
+ * 把一项顶层运行配置当分组维度,与 {@link flag} 同一套用法。读快照的 `ExperimentRunInfo`
+ * 投影;可用键由 RunConfigKey 在类型层穷尽(那张接口的字段全集,外加桥接到快照顶层权威
+ * 字段的 `model` / `agent`),拼错键在编译期就被拒绝。
+ */
+export function runConfig(name, options) {
+    assertName(name, "runConfig", 'an ExperimentRunInfo field, or the bridged "model" / "agent" keys');
+    return {
+        kind: "runConfig",
+        name,
+        ...(options?.label !== undefined ? { label: options.label } : {}),
+        ...(options?.unit !== undefined ? { unit: options.unit } : {}),
+    };
+}
+/**
+ * MetricLine 的 x 轴:只接受落盘值为 number 的 flag。未声明或非数值的 attempt 返回 null
+ * (折线不绘该点并报告缺失),不猜 `low < medium < high`。
+ */
+export function numericFlag(name, options) {
+    assertName(name, "numericFlag", "the key declared in the experiment's flags");
+    return {
+        name,
+        ...(options?.label !== undefined ? { label: options.label } : {}),
+        ...(options?.unit !== undefined ? { unit: options.unit } : {}),
+        of(attempt) {
+            const value = flagValueOf(attempt, name);
+            return typeof value === "number" && Number.isFinite(value) ? value : null;
+        },
+    };
+}
+/**
+ * 顶层运行配置作数值轴:数值配置直接返回该值;字符串配置必须显式给 `map`
+ * (如 { low: 1, medium: 2, high: 3 })。未声明、未投影、非数值或未命中 map 的值返回 null。
+ */
+export function numericRunConfig(name, options) {
+    assertName(name, "numericRunConfig", 'an ExperimentRunInfo field, or the bridged "model" / "agent" keys');
+    const map = options?.map;
+    return {
+        name,
+        ...(options?.label !== undefined ? { label: options.label } : {}),
+        ...(options?.unit !== undefined ? { unit: options.unit } : {}),
+        of(attempt) {
+            const value = runConfigValueOf(attempt, name);
+            if (typeof value === "number" && Number.isFinite(value))
+                return value;
+            if (typeof value === "string" && map !== undefined) {
+                const mapped = map[value];
+                return typeof mapped === "number" && Number.isFinite(mapped) ? mapped : null;
+            }
+            return null;
+        },
+    };
 }

package/dist/report/format.d.ts

@@ -1,5 +1,20 @@
-import type { AssertionResult, Verdict } from "../types.ts";
+import type { Verdict } from "../types.ts";
+import { type LocalizedText, type ReportLocale } from "./locale.ts";
+/**
+ * experiment 行的显示名：给了父路径 `relativeTo` 且它确是前缀，就去掉 `relativeTo + "/"`，
+ * 只留 id 末段——用在已经以组为标题的上下文（如默认 `ExperimentComparison` 的每组面板）里，
+ * 避免每行重复文件夹名。组键就是 experiment id 的父目录，因此这里的末段与 `MetricScatter`
+ * 点标签取的末段同源。不给 `relativeTo`、或它不是前缀（如根目录单例组）时原样返回完整 id。
+ * 完整 id 仍是排序 / 着色 / 折叠的键，调用方不要拿这个显示名当身份用。
+ */
+export declare function experimentDisplayName(experimentId: string, relativeTo?: string): string;
 export declare function formatMetricValue(value: number, unit?: string): string;
+/**
+ * MetricCell.display 的生成:为官方生成面覆盖的每个 locale(DISPLAY_LOCALES)各生成一份;
+ * 全部相同(内置 unit 格式化都是 locale 无关的)时折叠成单个字符串,renderer 按
+ * LocalizedText 回退规则选择。`make` 抛错由调用方(computeCell)带 metric 上下文包装。
+ */
+export declare function localizedDisplay(make: (locale: ReportLocale) => string): LocalizedText;
 /** 无单位纯数字(scoreboard 总分等):一位小数,去尾零。 */
 export declare function formatPlainNumber(value: number): string;
 /** 全 null / 无样本的统一文案。绝不画 0(docs/feature/reports/architecture.md「指标聚合不变量」)。 */
@@ -13,14 +28,7 @@ export declare function formatPercent(ratio: number): string;
 /** passed / failed / errored / skipped 的判定符。 */
 export declare function verdictMark(verdict: Verdict): string;
 /**
- * 一个 AttemptListItem 的失败原因摘要,按优先级取第一个在场的:`error` → 未通过的 gate 断言
- * (原始声明顺序,`name`,detail 在场则 `"name: detail"`,多条用「, 」连接)→ 缺席。与
- * compute.ts 的 `reasonFor(EvalResult)` 同一口径,只是输入换成瘦身后的 AttemptListItem——
- * 没有 `skipReason` 字段(AttemptListItem 不携带),skipped 的 attempt 因此没有原因摘要,
- * 这与它们本来就不该出现在「为什么失败」列表里的事实一致。EvalList / ExperimentList 的
- * 逐 attempt 徽标行用它给每个 attempt 自己的原因(而不是复用整道题的代表原因)。
+ * `AttemptListItem.failureSummary` 的宽度收口:摘要已在计算侧按 Scoring display 契约折好,
+ * 渲染面只做尾截,不重算摘要。maxChars 是渲染面的宽度预算(如两行单元格 = 2 × 列宽)。
  */
-export declare function attemptItemReason(item: {
-    error?: string;
-    assertions: AssertionResult[];
-}): string | undefined;
+export declare function fitFailureSummary(summary: string, maxChars: number): string;

package/dist/report/format.js

@@ -1,6 +1,20 @@
 // unit 驱动的内置格式化(docs/feature/reports/library.md「指标」):
 //   "%" → 87%    "ms" → 1.2s    "$" → $0.31    其余 → 1.2k 缩写(带 unit 后缀)
 // metric.display 可整体覆盖;这里只负责默认。
+import { DISPLAY_LOCALES } from "./locale.js";
+/**
+ * experiment 行的显示名：给了父路径 `relativeTo` 且它确是前缀，就去掉 `relativeTo + "/"`，
+ * 只留 id 末段——用在已经以组为标题的上下文（如默认 `ExperimentComparison` 的每组面板）里，
+ * 避免每行重复文件夹名。组键就是 experiment id 的父目录，因此这里的末段与 `MetricScatter`
+ * 点标签取的末段同源。不给 `relativeTo`、或它不是前缀（如根目录单例组）时原样返回完整 id。
+ * 完整 id 仍是排序 / 着色 / 折叠的键，调用方不要拿这个显示名当身份用。
+ */
+export function experimentDisplayName(experimentId, relativeTo) {
+    if (relativeTo && experimentId.startsWith(`${relativeTo}/`)) {
+        return experimentId.slice(relativeTo.length + 1);
+    }
+    return experimentId;
+}
 /** 一位小数、去掉无意义的 ".0" 尾巴。 */
 function trimmed(n) {
     const s = n.toFixed(1);
@@ -44,6 +58,18 @@ export function formatMetricValue(value, unit) {
     const n = abbreviate(abs);
     return unit ? `${sign}${n} ${unit}` : `${sign}${n}`;
 }
+/**
+ * MetricCell.display 的生成:为官方生成面覆盖的每个 locale(DISPLAY_LOCALES)各生成一份;
+ * 全部相同(内置 unit 格式化都是 locale 无关的)时折叠成单个字符串,renderer 按
+ * LocalizedText 回退规则选择。`make` 抛错由调用方(computeCell)带 metric 上下文包装。
+ */
+export function localizedDisplay(make) {
+    const entries = DISPLAY_LOCALES.map((locale) => [locale, make(locale)]);
+    const first = entries[0][1];
+    if (entries.every(([, text]) => text === first))
+        return first;
+    return Object.fromEntries(entries);
+}
 /** 无单位纯数字(scoreboard 总分等):一位小数,去尾零。 */
 export function formatPlainNumber(value) {
     const sign = value < 0 ? "-" : "";
@@ -92,18 +118,9 @@ export function verdictMark(verdict) {
     }
 }
 /**
- * 一个 AttemptListItem 的失败原因摘要,按优先级取第一个在场的:`error` → 未通过的 gate 断言
- * (原始声明顺序,`name`,detail 在场则 `"name: detail"`,多条用「, 」连接)→ 缺席。与
- * compute.ts 的 `reasonFor(EvalResult)` 同一口径,只是输入换成瘦身后的 AttemptListItem——
- * 没有 `skipReason` 字段(AttemptListItem 不携带),skipped 的 attempt 因此没有原因摘要,
- * 这与它们本来就不该出现在「为什么失败」列表里的事实一致。EvalList / ExperimentList 的
- * 逐 attempt 徽标行用它给每个 attempt 自己的原因(而不是复用整道题的代表原因)。
+ * `AttemptListItem.failureSummary` 的宽度收口:摘要已在计算侧按 Scoring display 契约折好,
+ * 渲染面只做尾截,不重算摘要。maxChars 是渲染面的宽度预算(如两行单元格 = 2 × 列宽)。
  */
-export function attemptItemReason(item) {
-    if (item.error !== undefined)
-        return item.error;
-    const gates = item.assertions.filter((a) => !a.passed && a.severity === "gate");
-    if (gates.length === 0)
-        return undefined;
-    return gates.map((a) => (a.detail ? `${a.name}: ${a.detail}` : a.name)).join(", ");
+export function fitFailureSummary(summary, maxChars) {
+    return summary.length <= maxChars ? summary : `${summary.slice(0, Math.max(0, maxChars - 1))}…`;
 }

package/dist/report/index.d.ts

@@ -1,19 +1,19 @@
-export { defineMetric, passRate, examScore, durationMs, tokens, costUSD, turns } from "./metrics.ts";
-export { flag } from "./flag.ts";
-export { defineReport, isReportDefinition, renderReportToText } from "./report.ts";
-export type { ReportContext, ReportDefinition } from "./report.ts";
-export { defineComponent } from "./tree.ts";
-export type { ComponentFaces, ReportComponent, ReportElement, ReportNode, TextContext, TextRenderOptions, WebContext, } from "./tree.ts";
-export { Row, Col, Section, Text, Style, Table } from "./primitives.tsx";
-export type { LayoutProps, SectionProps, StyleProps, TableColumn, TableProps, TableRow } from "./primitives.tsx";
+export { assistantTurns, costUSD, defineMetric, durationMs, endToEndPassRate, examScore, executionReliability, repeatedFailedCommands, taskPassRate, tokens, } from "./metrics.ts";
+export { flag, numericFlag, numericRunConfig, runConfig } from "./flag.ts";
+export { buildReportMeta, defineReport, isReportDefinition, pickReportPage, renderReportToText, renderReportTreeToText, reportTitleText, resolveReportTitle, ReportPageNotFoundError, DEFAULT_PAGE_ID, } from "./report.ts";
+export type { HostCommandContext, NonEmptyArray, RenderReportTextOptions, RenderTreeTextOptions, ReportTreeHostContext, ReportAsset, ReportDef, ReportDefinition, ReportHostContext, ReportLink, ReportMeta, ReportPage, ReportShell, } from "./report.ts";
+export { defineComponent, createTextContext, renderNodeToText, resolveReportTree, validateReportTree, ResolveMemo } from "./tree.ts";
+export type { ComponentFaces, ComposeContext, ReportComponent, ReportElement, ReportNode, ResolveContext, ResolveEnv, TextContext, TextRenderOptions, WebContext, } from "./tree.ts";
+export { Col, Row, Section, Style, Tab, Table, Tabs, Text } from "./primitives.tsx";
+export type { ColProps, LayoutProps, RowProps, SectionProps, StyleProps, TabProps, TableColumn, TableProps, TableRow, TabsProps, TextProps, } from "./primitives.tsx";
 export { stringWidth, padDisplay as padEnd, padStartDisplay as padStart, wrapDisplay as wrapText, indentBlock as indent, textBar as bar, joinColumns as columns, } from "./text/layout.ts";
 export type { ColumnAlign } from "./text/layout.ts";
-export { ExperimentComparison } from "./built-ins/index.ts";
-export { DEFAULT_REPORT_LOCALE, resolveMetricLabel } from "./locale.ts";
-export type { LocalizedLabel, ReportLocale } from "./locale.ts";
-export { AttemptList, DeltaTable, EvalList, ExperimentList, GroupSummary, MetricBars, MetricLine, MetricMatrix, MetricScatter, MetricTable, RunOverview, Scoreboard, } from "./components.tsx";
-export type { AttemptListProps, DeltaTableProps, EvalListProps, ExperimentListProps, GroupSummaryProps, MetricLineProps, MetricMatrixProps, MetricScatterProps, MetricTableProps, RunOverviewProps, ScoreboardProps, } from "./components.tsx";
-export type { AttemptListDataOptions, DeltaDataOptions, DeltaPair, LineDataOptions, MatrixDataOptions, ScatterDataOptions, ScoreboardDataOptions, TableDataOptions, } from "./compute.ts";
-export type { Aggregator, AttemptListItem, AttemptLocator, DeltaData, Dimension, DimensionInput, EvalListItem, ExperimentListEvalRow, ExperimentListItem, GroupSummaryData, LineAxis, LineData, MatrixData, Metric, MetricAggregate, MetricCell, MetricColumn, OverviewData, FlagRef, ScatterData, ScoreboardData, SelectionWarning, TableData, TableRowMeta, } from "./types.ts";
-export type { AttemptHandle, Results, Selection, Snapshot } from "../results/types.ts";
+export { DEFAULT_REPORT_LOCALE, localizedTextEquals, resolveLocalizedText, resolveMetricLabel } from "./locale.ts";
+export type { LocalizedText, ReportLocale } from "./locale.ts";
+export { AttemptList, DeltaTable, EvalList, ExperimentComparison, ExperimentList, FailureList, MetricBars, MetricLine, MetricMatrix, MetricScatter, MetricTable, Scoreboard, ScopeSummary, } from "./components.tsx";
+export type { AttemptListProps, DataProps, DeltaTableProps, EvalListProps, ExperimentComparisonProps, ExperimentListProps, FailureListProps, MetricBarsProps, MetricLineProps, MetricMatrixProps, MetricScatterProps, MetricTableProps, ScoreboardProps, ScopeSummaryProps, } from "./components.tsx";
+export { attemptListData, deltaTableData, evalListData, experimentComparisonData, experimentListData, metricLineData, metricMatrixData, metricScatterData, metricTableData, pairsByFlag, scopeSummaryData, scoreboardData, } from "./compute.ts";
+export type { DeltaTableOptions, MetricLineOptions, MetricMatrixOptions, MetricScatterOptions, MetricTableOptions, ScoreboardOptions, } from "./compute.ts";
+export type { Aggregator, AttemptListItem, AttemptLocator, BuiltInDimension, CustomDimension, DeltaData, DeltaPair, DimensionInput, DimensionOptions, DimensionRef, EntityListDataOptions, EvalListItem, ExperimentComparisonData, ExperimentComparisonGroupData, ExperimentListEvalRow, ExperimentListItem, FlagPairs, LineData, MatrixData, Metric, MetricAggregate, MetricCell, MetricColumn, NumericAxis, NumericAxisOptions, NumericRunConfigAxisOptions, ReportInput, RunConfigKey, ScatterData, ScopeSummaryData, ScopeWarning, ScoreboardData, TableData, VerdictTally, } from "./types.ts";
+export type { AttemptHandle, Results, Scope, Snapshot } from "../results/types.ts";
 export { experimentGroupOf } from "../shared/aggregate.ts";

package/dist/report/index.js

@@ -1,30 +1,29 @@
 // niceeval/report —— 报告积木:指标 × 计算函数 × 双面组件 × defineReport。
-// 契约见 docs/feature/reports/README.md;公开叙事的准绳是 docs-site/zh/guides/custom-reports.mdx
-// 与 report-components.mdx。
+// 契约见 docs/feature/reports/README.md 与 docs/feature/reports/library/ 分篇。
 //
-// import 边界即运行时边界:计算函数(挂在组件上的 .data)会经句柄触碰文件系统
-// (懒加载 artifact),只能进服务端 / 脚本;组件的渲染面纯同步零 IO。text 宿主遍历渲染
-// 不需要 react-dom(renderReportToText);web 宿主的 renderReportToStaticHtml 在
-// ./web.ts,只有那一侧 import react-dom。写报告文件的项目要装 react(.tsx 编译产物
-// import react/jsx-runtime)。
-// 指标与 flag
-export { defineMetric, passRate, examScore, durationMs, tokens, costUSD, turns } from "./metrics.js";
-export { flag } from "./flag.js";
-// 报告基座与双面组件基座
-export { defineReport, isReportDefinition, renderReportToText } from "./report.js";
-export { defineComponent } from "./tree.js";
-// 排版原语(六个内置双面组件)
-export { Row, Col, Section, Text, Style, Table } from "./primitives.js";
+// import 边界即运行时边界:计算函数(*Data)会经句柄触碰文件系统(懒加载 artifact),
+// 只能进服务端 / 脚本;组件的渲染面纯同步零 IO。text 宿主遍历渲染不需要 react-dom
+// (renderReportToText);web 宿主的 renderReportToStaticHtml 在 ./web.ts,只有那一侧
+// import react-dom。写报告文件的项目要装 react(.tsx 编译产物 import react/jsx-runtime)。
+// 指标与维度读取器
+export { assistantTurns, costUSD, defineMetric, durationMs, endToEndPassRate, examScore, executionReliability, repeatedFailedCommands, taskPassRate, tokens, } from "./metrics.js";
+export { flag, numericFlag, numericRunConfig, runConfig } from "./flag.js";
+// 报告定义与组件基座
+export { buildReportMeta, defineReport, isReportDefinition, pickReportPage, renderReportToText, renderReportTreeToText, reportTitleText, resolveReportTitle, ReportPageNotFoundError, DEFAULT_PAGE_ID, } from "./report.js";
+export { defineComponent, createTextContext, renderNodeToText, resolveReportTree, validateReportTree, ResolveMemo } from "./tree.js";
+// 排版原语(八个内置双面组件)
+export { Col, Row, Section, Style, Tab, Table, Tabs, Text } from "./primitives.js";
 // 文本排版工具箱:自定义组件的 text 面用的就是官方组件那把尺子。
 // 表格有 <Table> 承担,这里只给表以外的形态用 —— 尤其别拿 String.prototype.padEnd 对齐:
 // 它数 UTF-16 码元不数显示列宽,一带中文列就撕歪。renderAlignedRows 刻意不导出。
 export { stringWidth, padDisplay as padEnd, padStartDisplay as padStart, wrapDisplay as wrapText, indentBlock as indent, textBar as bar, joinColumns as columns, } from "./text/layout.js";
-// 内置报告(show / view 裸跑时报告槽的出厂填充,一份普通 ReportDefinition,无 renderer 特权)
-export { ExperimentComparison } from "./built-ins/index.js";
-// locale:官方组件 chrome 文案的语言(en / zh-CN);指标 label 可按 locale 给字典
-export { DEFAULT_REPORT_LOCALE, resolveMetricLabel } from "./locale.js";
-// 官方双面组件(各自带 data 计算函数;MetricBars.data = MetricMatrix.data)
-export { AttemptList, DeltaTable, EvalList, ExperimentList, GroupSummary, MetricBars, MetricLine, MetricMatrix, MetricScatter, MetricTable, RunOverview, Scoreboard, } from "./components.js";
+// locale:官方组件 chrome 文案的语言(内置词典覆盖 en / zh-CN,其它 locale 走回退)
+export { DEFAULT_REPORT_LOCALE, localizedTextEquals, resolveLocalizedText, resolveMetricLabel } from "./locale.js";
+// 官方双面组件(spec / data 双形态;配套 *Data 计算函数在下面成对导出)
+export { AttemptList, DeltaTable, EvalList, ExperimentComparison, ExperimentList, FailureList, MetricBars, MetricLine, MetricMatrix, MetricScatter, MetricTable, Scoreboard, ScopeSummary, } from "./components.js";
+// 计算函数(组件解析面的具名形式,与组件成对;spec 形态下由管线代调,data 形态与
+// 嵌入场景下由作者手工调)
+export { attemptListData, deltaTableData, evalListData, experimentComparisonData, experimentListData, metricLineData, metricMatrixData, metricScatterData, metricTableData, pairsByFlag, scopeSummaryData, scoreboardData, } from "./compute.js";
 // experiment id 的组键推导(id 的目录前缀,如 `compare/bub-low` 的 `compare`)。
 // 重新导出,让自定义报告能按同一份口径把 experiment 分组,不必自己重写这两行逻辑。
 export { experimentGroupOf } from "../shared/aggregate.js";

package/dist/report/load.js

@@ -21,7 +21,7 @@ export class ReportLoadError extends Error {
 export async function loadReportFile(cwd, path, options) {
     const abs = resolve(cwd, path);
     if (!existsSync(abs)) {
-        throw new ReportLoadError(`Report file not found: ${abs}. Pass --report an explicit path to a module whose default export is defineReport(...).`);
+        throw new ReportLoadError(`Report file not found: ${abs}. Pass --report an explicit path to a module whose default export is a defineReport(...) product.`);
     }
     const plain = pathToFileURL(abs);
     const url = new URL(plain.href);
@@ -50,7 +50,8 @@ export async function loadReportFile(cwd, path, options) {
         }
     }
     if (!isReportDefinition(mod.default)) {
-        throw new ReportLoadError(`${path} does not default-export a report. Export default defineReport(async ({ selection, results }) => ...) from "niceeval/report".`);
+        throw new ReportLoadError(`${path} does not default-export a report. Export the product of defineReport(...) from "niceeval/report" as the default export — ` +
+            `a tree (defineReport(<ExperimentComparison />)) or a config object (defineReport({ title, content | pages, … })).`);
     }
     return mod.default;
 }

package/dist/report/locale.d.ts

@@ -1,6 +1,18 @@
-/** 报告渲染的 locale;默认 "en"(text 面缺省即 en,`niceeval show` 输出不变)。 */
-export type ReportLocale = "en" | "zh-CN";
+import type { LocalizedText } from "../types.ts";
+export type { LocalizedText };
+/** 报告渲染的 locale(BCP 47 标签,开放);默认 "en"(`niceeval show` 缺省输出不变)。 */
+export type ReportLocale = string;
 export declare const DEFAULT_REPORT_LOCALE: ReportLocale;
+/** MetricCell.display 生成面覆盖的 locale 全集;其它 locale 按 LocalizedText 回退取 en。 */
+export declare const DISPLAY_LOCALES: readonly ReportLocale[];
+/**
+ * LocalizedText 的确定回退:取当前 locale;缺失时取 en;仍缺失时取按 locale 键字典序的
+ * 第一个非空值。对象没有任何非空值时报错,不渲染空文案
+ * (docs/feature/reports/library/shell.md「行为约束」)。
+ */
+export declare function resolveLocalizedText(text: LocalizedText, locale: ReportLocale): string;
+/** LocalizedText 按字段值深相等(键顺序无关;标题回退链的「唯一且相同」判定用)。 */
+export declare function localizedTextEquals(a: LocalizedText, b: LocalizedText): boolean;
 declare const en: {
     readonly "verdict.passed": "passed";
     readonly "verdict.failed": "failed";
@@ -11,6 +23,7 @@ declare const en: {
     readonly "cell.measuredTitle": "{samples}/{total} attempts measured";
     readonly "cell.noneMeasurableTitle": "0/{total} attempts measurable";
     readonly "cell.coverageTitle": "coverage {samples}/{total}: this metric is null for the remaining attempts";
+    readonly "cell.missingValue": "(missing)";
     readonly "table.higherBetter": "higher is better";
     readonly "table.lowerBetter": "lower is better";
     readonly "table.model": "Model";
@@ -24,39 +37,47 @@ declare const en: {
     readonly "table.attempt": "attempt";
     readonly "experimentList.experiment": "Experiment";
     readonly "experimentList.avgDuration": "Avg duration";
-    readonly "experimentList.passRate": "Pass rate";
+    readonly "experimentList.passRate": "End-to-end pass rate";
     readonly "experimentList.tokens": "Tokens";
-    readonly "experimentList.estimatedCost": "Est. cost";
+    readonly "experimentList.cost": "Cost";
     readonly "experimentList.result": "Result";
     readonly "experimentList.status": "Status";
     readonly "experimentList.evalAttempt": "Eval / Attempt";
     readonly "experimentList.duration": "Duration";
-    readonly "experimentList.cost": "Cost";
     readonly "experimentList.filterPlaceholder": "Filter experiments…";
     readonly "experimentList.defaultModel": "default";
     readonly "experimentList.flags": "Flags";
+    readonly "entityList.average": "{value} avg";
+    readonly "entityList.moreFailures.one": "+{n} more failure";
+    readonly "entityList.moreFailures.other": "+{n} more failures";
     /** <Table> 压到下限仍放不下时,从右侧丢列并如实报数。 */
     readonly "table.columnsHidden.one": "({n} more column not shown)";
     readonly "table.columnsHidden.other": "({n} more columns not shown)";
-    readonly "overview.snapshots": "Snapshots";
-    readonly "overview.evals": "Evals";
-    readonly "overview.attempts": "attempts";
-    readonly "overview.passRate": "Pass rate";
-    readonly "overview.totalCost": "Total cost";
-    readonly "overview.totalDuration": "Total duration";
-    readonly "overview.source": "Source: {n} snapshots";
+    /** ScopeSummary 的 KPI 标签。 */
+    readonly "scopeSummary.experiments": "Experiments";
+    readonly "scopeSummary.evals": "Evals";
+    readonly "scopeSummary.attempts": "attempts";
+    readonly "scopeSummary.passRate": "End-to-end pass rate";
+    readonly "scopeSummary.totalCost": "Total cost";
+    readonly "scopeSummary.range": "{from} – {to}";
+    readonly "scopeSummary.votesEval": "eval verdicts";
+    readonly "scopeSummary.votesAttempt": "attempt verdicts";
     readonly "overview.experiments.one": "{n} experiment";
     readonly "overview.experiments.other": "{n} experiments";
     readonly "overview.evalsCount": "{n} evals";
     readonly "overview.attemptsCount": "{n} attempts";
-    /** GroupSummary 的 KPI dt 标签(其余字段复用 verdict.* / overview.* 已有 key)。 */
-    readonly "groupSummary.experiments": "Experiments";
-    readonly "composedFrom.one": "composed from {n} run";
-    readonly "composedFrom.other": "composed from {n} runs";
-    readonly latestRun: "latest {run}";
-    readonly "scatter.betterHint": "better ↗";
+    readonly "overview.evals": "Evals";
+    readonly "overview.passRate": "End-to-end pass rate";
+    readonly "overview.totalCost": "Cost";
+    readonly "experimentComparison.groups": "Experiment groups";
+    readonly "experimentComparison.group": "Experiment group";
+    readonly "experimentComparison.results": "Eval results";
+    readonly "experimentComparison.lastRun": "Last run";
+    readonly "experimentComparison.selectGroup": "Select experiment group {group}";
+    readonly "experimentComparison.commandsHead": "Group details:";
+    readonly "experimentComparison.empty": "No experiment groups";
+    /** 方向提示唯一文案:轴向已随 better 反正,「更好」恒指向右上(两轴都声明 better 时才显示)。 */
     readonly "scatter.betterUpperRight": "better → upper right";
-    readonly "scatter.axisReversed": "(axis reversed: right = better)";
     /** 0 个可画点:x/y 指标没有可用数据。 */
     readonly "scatter.noData": "No data to plot {x} × {y}";
     readonly "pointsMissing.one": "{n} point missing data";
@@ -65,30 +86,33 @@ declare const en: {
     readonly "attemptList.truncated": "and {n} more not shown";
     readonly "attemptList.truncatedText": "({n} more not shown)";
     readonly "attemptList.score": "score {score}";
+    readonly "attemptList.unavailable": "unavailable";
     readonly "attemptList.details": "details";
     readonly "scoreboard.total": "Total";
     readonly "scoreboard.totalText": "total";
-    readonly "scoreboard.missing.one": "{n} eval missing, scored 0";
-    readonly "scoreboard.missing.other": "{n} evals missing, scored 0";
-    readonly "scoreboard.missingText": "({n} missing)";
+    readonly "scoreboard.notRun.one": "{n} eval not run, scored 0";
+    readonly "scoreboard.notRun.other": "{n} evals not run, scored 0";
+    readonly "scoreboard.unscorable.one": "{n} eval unscorable, scored 0";
+    readonly "scoreboard.unscorable.other": "{n} evals unscorable, scored 0";
+    readonly "scoreboard.notRunText": "({n} not run)";
+    readonly "scoreboard.unscorableText": "({n} unscorable)";
+    readonly "scoreboard.ignored.one": "{n} eval outside the question set ignored";
+    readonly "scoreboard.ignored.other": "{n} evals outside the question set ignored";
     readonly "scoreboard.weights": "weights:";
     readonly "scoreboard.allWeights": "all evals ×1";
     readonly "scoreboard.othersWeight": "others ×1";
-    readonly "scoreboard.subjectTitle": "{evals} evals, weighted {earned} of {possible}";
+    readonly "scoreboard.subjectTitle": "{questions} evals, weighted {earned} of {possible}";
     readonly "delta.pairHeader": "pair (A → B)";
-    readonly "board.currentVerdicts": "Current verdicts";
-    readonly "board.failing": "Failing:";
+    readonly "delta.empty": "{experiments} experiments, 0 comparable pairs";
+    readonly "tabs.tab": "Tab";
 };
 export type ReportMessageKey = keyof typeof en;
-/** 查字典 + 简单插值({name} 占位符)。缺 locale 回退 en。 */
+/** 查字典 + 简单插值({name} 占位符)。内置词典未覆盖的 locale 回退 en。 */
 export declare function localeText(locale: ReportLocale, key: ReportMessageKey, vars?: Record<string, string | number>): string;
 /** 带单复数的计数文案:n === 1 用 `<base>.one`,其余 `<base>.other`(zh-CN 两键同值)。 */
-export declare function countText(locale: ReportLocale, base: "overview.experiments" | "composedFrom" | "pointsMissing" | "scoreboard.missing" | "table.columnsHidden", n: number): string;
-/** 指标 label 的可本地化形态:字符串,或按 locale 给的字典(缺项回退 en,再回退任一非空值)。 */
-export type LocalizedLabel = string | Partial<Record<ReportLocale, string>>;
+export declare function countText(locale: ReportLocale, base: "overview.experiments" | "pointsMissing" | "scoreboard.notRun" | "scoreboard.unscorable" | "scoreboard.ignored" | "entityList.moreFailures" | "table.columnsHidden", n: number): string;
 /**
- * 按 locale 解析指标 label:字符串原样;字典取当前 locale,缺项回退 en,
- * 再回退字典里任一值;全空回退 fallback(= metric.name)。渲染面(web / text)共用。
+ * 按 locale 解析指标 / 列 label:字符串原样;字典按 LocalizedText 回退规则取值;
+ * undefined 回退 fallback(= metric.name)。渲染面(web / text)共用。
  */
-export declare function resolveMetricLabel(label: LocalizedLabel | undefined, locale: ReportLocale, fallback: string): string;
-export {};
+export declare function resolveMetricLabel(label: LocalizedText | undefined, locale: ReportLocale, fallback: string): string;