niceeval 0.5.4 → 0.6.0

package/dist/report/aggregate.js

@@ -0,0 +1,212 @@
+// 两级聚合引擎:去重 → 按维度分组 → 组内按 (eval × 快照) 折叠(perEval)→ 跨题折叠(across)→ MetricCell。
+//
+// 为什么是两级:earlyExit 默认开,失败的题天然比通过的题样本多;平铺求均值会把分数
+// 和重试策略纠缠在一起(eval A=[1]、eval B=[0,0,0] 平铺 = 0.25,两级宏平均 = 0.5)。
+// 自定义维度把同一道题的 attempt 分进不同组时,第一级折叠发生在各组内部。
+import { dedupeAttempts } from "../results/select.js";
+import { encodeAttemptLocator } from "../results/locator.js";
+import { formatMetricValue } from "./format.js";
+import { evalPrefixPredicate } from "../shared/aggregate.js";
+// 复合键分隔符:NUL 不会出现在 eval id / experimentId / ISO 时间里,拼接键不会串味
+const KEY_SEP = "\u0000";
+/** flag 未声明时的组名:不猜,如实归一组。 */
+export const FLAG_UNSET = "(unset)";
+export function resolveInput(input) {
+    if (Array.isArray(input))
+        return { snapshots: input, warnings: [] };
+    return { snapshots: input.snapshots, warnings: input.warnings };
+}
+export function experimentIdOf(item) {
+    return item.attempt.experimentId || item.snapshot.experimentId;
+}
+export function evalIdOf(item) {
+    return item.attempt.evalId || item.attempt.result.id;
+}
+/** 快照键:与 view Compare 同口径的 "<experimentId> @ <startedAt>"。 */
+export function snapshotKeyOf(snapshot) {
+    return `${snapshot.experimentId} @ ${snapshot.startedAt}`;
+}
+/**
+ * 一条 Item 的 AttemptLocator:真实读取路径(openResults() 产出的 handle)恒有
+ * `attempt.locator`;手工构造的测试 fixture 若省略它,按当前身份元组兜底算一份
+ * (与 `loadAttemptEvidence`、`open.ts` 的回填同一口径)——只服务这类场景,不改变真实
+ * 读取路径的行为。
+ */
+export function locatorOf(item) {
+    return (item.attempt.locator ??
+        encodeAttemptLocator({
+            experimentId: experimentIdOf(item),
+            snapshotStartedAt: item.snapshot.startedAt,
+            evalId: evalIdOf(item),
+            attempt: item.attempt.result.attempt,
+        }));
+}
+/**
+ * 展平 + 聚合前去重(niceeval/results 的 dedupeAttempts,身份键
+ * (experimentId, evalId, attempt, startedAt))。missing-startedAt 的警告不透出:
+ * 官方产出永不缺 startedAt,缺失只可能来自 legacy 落盘,「不去重、如实保留重复」即终稿。
+ */
+export function collectItems(snapshots) {
+    const snapshotByAttempt = new Map();
+    const flattened = [];
+    for (const snapshot of snapshots) {
+        for (const attempt of snapshot.attempts) {
+            // 同一 handle 对象出现在两个快照里时以首次归属为准(手工挑重叠快照的极端场景)
+            if (!snapshotByAttempt.has(attempt))
+                snapshotByAttempt.set(attempt, snapshot);
+            flattened.push(attempt);
+        }
+    }
+    const { attempts } = dedupeAttempts(flattened);
+    return attempts.map((attempt) => ({ attempt, snapshot: snapshotByAttempt.get(attempt) }));
+}
+export { evalPrefixPredicate };
+export function filterItems(items, evals) {
+    if (evals === undefined)
+        return items;
+    const match = evalPrefixPredicate(evals);
+    return items.filter((item) => match(evalIdOf(item)));
+}
+// ───────────────────────── 维度 ─────────────────────────
+export function dimensionName(dimension) {
+    return typeof dimension === "string" ? dimension : dimension.name;
+}
+/** eval id 的第一段:"algebra/quadratic" → "algebra";没有 "/" 时就是 id 本身。 */
+export function evalGroupOf(id) {
+    const slash = id.indexOf("/");
+    return slash === -1 ? id : id.slice(0, slash);
+}
+function isFlagRef(dimension) {
+    return typeof dimension === "object" && "kind" in dimension && dimension.kind === "flag";
+}
+/** experiment 声明的 flags(经 runner 原样透传进持久化字段 ExperimentRunInfo.flags)。 */
+function flagsOf(attempt) {
+    return attempt.result.experiment?.flags;
+}
+/** flag 声明值 → 组标签:label 函数优先,其余 String();未声明 → FLAG_UNSET。 */
+export function flagGroupKey(ref, item) {
+    const value = flagsOf(item.attempt)?.[ref.name];
+    if (value === undefined)
+        return FLAG_UNSET;
+    // 持久化字段是 Record<string, unknown>;声明侧的合法值就是这三种标量
+    if (typeof ref.label === "function")
+        return ref.label(value);
+    return String(value);
+}
+/** flag 作轴:要求数值;未声明或非数值 → null(点不画,注脚报数)。 */
+export function flagAxisValue(ref, item) {
+    const value = flagsOf(item.attempt)?.[ref.name];
+    return typeof value === "number" ? value : null;
+}
+export function dimensionKey(dimension, item) {
+    if (typeof dimension !== "string") {
+        if (isFlagRef(dimension))
+            return flagGroupKey(dimension, item);
+        return dimension.of(item.attempt);
+    }
+    const result = item.attempt.result;
+    switch (dimension) {
+        case "agent":
+            return result.agent;
+        case "model":
+            return result.model ?? item.snapshot.model ?? "(none)";
+        case "experiment":
+            return experimentIdOf(item);
+        case "eval":
+            return evalIdOf(item);
+        case "evalGroup":
+            return evalGroupOf(evalIdOf(item));
+        case "snapshot":
+            return snapshotKeyOf(item.snapshot);
+        default: {
+            // 穷尽检查:新增内置维度而漏改这里时编译期报错
+            const exhausted = dimension;
+            throw new Error(`Unknown dimension: ${String(exhausted)}`);
+        }
+    }
+}
+/** 按维度分组,保持首次出现顺序(无 sort 时表格行序即此序)。 */
+export function groupItems(items, dimension) {
+    const groups = new Map();
+    for (const item of items) {
+        const key = dimensionKey(dimension, item);
+        const list = groups.get(key);
+        if (list)
+            list.push(item);
+        else
+            groups.set(key, [item]);
+    }
+    return groups;
+}
+// ───────────────────────── 聚合 ─────────────────────────
+export function applyAggregator(aggregator, values) {
+    if (typeof aggregator === "function")
+        return aggregator(values);
+    switch (aggregator) {
+        case "mean":
+            return values.reduce((a, b) => a + b, 0) / values.length;
+        case "sum":
+            return values.reduce((a, b) => a + b, 0);
+        case "min":
+            return Math.min(...values);
+        case "max":
+            return Math.max(...values);
+    }
+}
+/** where 不满足 → null,语义等价于 value 开头 return null。 */
+export async function evaluateMetric(metric, attempt) {
+    if (metric.where && !metric.where(attempt))
+        return null;
+    return metric.value(attempt);
+}
+export function displayValue(metric, value) {
+    // null 的纯文本兜底;组件把 null 渲染成「缺数据」,绝不画 0
+    if (value === null)
+        return "—";
+    return metric.display ? metric.display(value) : formatMetricValue(value, metric.unit);
+}
+/**
+ * 一个格子:组内 attempt → 两级聚合 → 终值。
+ * null 值不进聚合但计入 total(覆盖率经 samples/total 如实暴露);全 null → value null。
+ */
+export async function computeCell(metric, items) {
+    // 第一级桶:同一 (eval × 快照) 的 attempt 折成一个题级值
+    const buckets = new Map();
+    const refs = [];
+    let samples = 0;
+    for (const item of items) {
+        const value = await evaluateMetric(metric, item.attempt);
+        if (value === null)
+            continue;
+        samples += 1;
+        refs.push(locatorOf(item)); // 证据引用由句柄直供,不反查下标
+        const bucketKey = `${evalIdOf(item)}${KEY_SEP}${snapshotKeyOf(item.snapshot)}`;
+        const bucket = buckets.get(bucketKey);
+        if (bucket)
+            bucket.push(value);
+        else
+            buckets.set(bucketKey, [value]);
+    }
+    const perEval = metric.aggregate?.perEval ?? "mean";
+    const across = metric.aggregate?.across ?? "mean";
+    const evalValues = [...buckets.values()].map((values) => applyAggregator(perEval, values));
+    const value = evalValues.length === 0 ? null : applyAggregator(across, evalValues);
+    return { value, display: displayValue(metric, value), samples, total: items.length, refs };
+}
+export function toColumn(metric) {
+    return {
+        key: metric.name,
+        label: metric.label ?? metric.name,
+        unit: metric.unit,
+        better: metric.better,
+    };
+}
+export function assertUniqueMetricNames(metrics, where) {
+    const seen = new Set();
+    for (const metric of metrics) {
+        if (seen.has(metric.name)) {
+            throw new Error(`Duplicate metric name "${metric.name}" in ${where}. Metric names must be unique within one computation; rename one via defineMetric.`);
+        }
+        seen.add(metric.name);
+    }
+}

package/dist/report/built-ins/cost-pass-rate-comparison.d.ts

@@ -0,0 +1 @@
+export declare const CostPassRateComparison: import("../report.ts").ReportDefinition;

package/dist/report/built-ins/cost-pass-rate-comparison.js

@@ -0,0 +1,17 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+// CostPassRateComparison:show / view 裸跑时的出厂报告槽。
+//
+// 它是一份普通 ReportDefinition,零特权:只声明「摆什么」——成本 × 通过率的散点(比较
+// experiments)和实验列表。散点走 selection-form(`MetricScatter` 声明了 `resolve`,宿主
+// 渲染前的 resolveReportTree 会替它调 `.data`);`ExperimentList` 没有 selection-form,
+// 报告函数体里直接 `await ExperimentList.data(selection)` 拿到普通数组再传 `items`——
+// 这正是三个实体列表统一的用法,内置默认报告不搞一套特权写法。包外用户复制这段 TSX
+// (只改 import 路径与 export 形式)会走完全相同的解析与渲染管线。
+import { Col } from "../primitives.js";
+import { ExperimentList, MetricScatter } from "../components.js";
+import { costUSD, passRate } from "../metrics.js";
+import { defineReport } from "../report.js";
+export const CostPassRateComparison = defineReport(async ({ selection }) => {
+    const experiments = await ExperimentList.data(selection);
+    return (_jsxs(Col, { children: [_jsx(MetricScatter, { selection: selection, points: "experiment", series: "agent", x: costUSD, y: passRate }), _jsx(ExperimentList, { items: experiments })] }));
+});

package/dist/report/built-ins/index.d.ts

@@ -0,0 +1 @@
+export { CostPassRateComparison } from "./cost-pass-rate-comparison.tsx";

package/dist/report/built-ins/index.js

@@ -0,0 +1,2 @@
+// 内置报告目录:一个文件一个按展示内容命名的普通 ReportDefinition,显式导出值,不建字符串 registry。
+export { CostPassRateComparison } from "./cost-pass-rate-comparison.js";

package/dist/report/components.d.ts

@@ -0,0 +1,178 @@
+import type { ReportComponent } from "./tree.ts";
+import type { ReportLocale } from "./locale.ts";
+import type { AttemptLocator } from "../results/locator.ts";
+import type { Selection } from "../results/types.ts";
+import type { AttemptListItem, DeltaData, EvalListItem, ExperimentListItem, GroupSummaryData, LineData, MatrixData, OverviewData, ScatterData, ScoreboardData, TableData } from "./types.ts";
+import { attemptListData, deltaData, evalListData, experimentListData, groupSummaryData, lineData, matrixData, overviewData, scatterData, scoreboardData, tableData } from "./compute.ts";
+import type { ScatterDataOptions } from "./compute.ts";
+export interface RunOverviewProps {
+    data: OverviewData;
+    /** chrome 文案 locale;省略时随宿主上下文(宿主外默认 "en")。 */
+    locale?: ReportLocale;
+    className?: string;
+}
+export interface GroupSummaryProps {
+    data: GroupSummaryData;
+    /** chrome 文案 locale;省略时随宿主上下文(宿主外默认 "en")。 */
+    locale?: ReportLocale;
+    className?: string;
+}
+/**
+ * 三个实体列表都只收算好的 `items`(`.data(selection)` 的产物,报告作者先 `.filter()`/
+ * `.slice()` 再传入)——没有 selection-form,组件不提供另一套过滤 DSL
+ * (docs/feature/reports/library.md「实体列表」)。
+ */
+export interface ExperimentListProps {
+    items: ExperimentListItem[];
+    /** chrome 文案 locale;省略时随宿主上下文(宿主外默认 "en")。 */
+    locale?: ReportLocale;
+    className?: string;
+}
+export interface EvalListProps {
+    items: EvalListItem[];
+    /** chrome 文案 locale;省略时随宿主上下文(宿主外默认 "en")。 */
+    locale?: ReportLocale;
+    className?: string;
+}
+export interface AttemptListProps {
+    items: AttemptListItem[];
+    /** items 被 slice 时如实显示剩余数量;省略即 items.length(未截断)。 */
+    total?: number;
+    /** chrome 文案 locale;省略时随宿主上下文(宿主外默认 "en")。 */
+    locale?: ReportLocale;
+    className?: string;
+}
+export interface MetricTableProps {
+    data: TableData;
+    /** 传了,格子可点、下钻去处你定;不传,宿主里走证据室深链,宿主外纯展示。 */
+    attemptHref?: (locator: AttemptLocator) => string;
+    /**
+     * web 面在表格前渲染一个过滤输入框(`<input class="nre-filter" data-nre-filter>`),
+     * 由渐进增强 runtime(enhance.js)接管:输入过滤行 textContent。无 JS 时输入框
+     * 静默无功能,表格内容依旧完整可读。默认 false;text 面不受影响。
+     */
+    filter?: boolean;
+    /** chrome 文案 locale;省略时随宿主上下文(宿主外默认 "en")。 */
+    locale?: ReportLocale;
+    className?: string;
+}
+export interface MetricMatrixProps {
+    data: MatrixData;
+    attemptHref?: (locator: AttemptLocator) => string;
+    /** chrome 文案 locale;省略时随宿主上下文(宿主外默认 "en")。 */
+    locale?: ReportLocale;
+    className?: string;
+}
+export interface ScoreboardProps {
+    data: ScoreboardData;
+    /** chrome 文案 locale;省略时随宿主上下文(宿主外默认 "en")。 */
+    locale?: ReportLocale;
+    className?: string;
+}
+/** MetricScatter 两臂共享的纯渲染选项(不含数据来源)。 */
+interface MetricScatterRenderProps {
+    /** 点一个点 → 该配置的下钻页。 */
+    pointHref?: (row: ScatterData["rows"][number]) => string;
+    /** chrome 文案 locale;省略时随宿主上下文(宿主外默认 "en")。 */
+    locale?: ReportLocale;
+    className?: string;
+}
+/** resolve 之后 web / text 面看到的形态:数据已备好,零 IO。 */
+export interface MetricScatterResolvedProps extends MetricScatterRenderProps {
+    data: ScatterData;
+}
+/**
+ * 互斥两臂:要么直接给算好的 `data`(用于用户自己的 React 页面 / 预计算 / 跨边界序列化),
+ * 要么给 `selection` + 计算选项让宿主在渲染前解析(见 tree.ts 的 resolveReportTree)。
+ * 同时传 `data` 与 `selection`、或两者都不传,都在 typecheck 阶段失败。计算选项复用
+ * `ScatterDataOptions`,不手写会漂移的副本。
+ */
+export type MetricScatterProps = (MetricScatterResolvedProps & {
+    selection?: never;
+    points?: never;
+    series?: never;
+    x?: never;
+    y?: never;
+}) | ({
+    data?: never;
+} & ScatterDataOptions & MetricScatterRenderProps & {
+    selection: Selection;
+});
+export interface MetricLineProps {
+    data: LineData;
+    pointHref?: (row: LineData["rows"][number]) => string;
+    /** chrome 文案 locale;省略时随宿主上下文(宿主外默认 "en")。 */
+    locale?: ReportLocale;
+    className?: string;
+}
+export interface DeltaTableProps {
+    data: DeltaData;
+    /** chrome 文案 locale;省略时随宿主上下文(宿主外默认 "en")。 */
+    locale?: ReportLocale;
+    className?: string;
+}
+/** 页头 KPI 条:何时跑的、几个配置、几道题、通过率、总成本;Selection 的警告随行显示在条内。 */
+export declare const RunOverview: ReportComponent<RunOverviewProps> & {
+    data: typeof overviewData;
+};
+/**
+ * 组摘要:一组 experiment(典型用法是同一 `<Section>` 内的全部 experiment)的紧凑统计——
+ * 通过率(旧 GroupSelector 卡片口径)、experiment/eval/attempt 数、eval 级折叠计票、
+ * 总成本、最后运行时间。
+ */
+export declare const GroupSummary: ReportComponent<GroupSummaryProps> & {
+    data: typeof groupSummaryData;
+};
+/**
+ * 实验列表:每项一个 experiment,固定展示身份、配置(flags)、Eval 判定构成和官方两级聚合
+ * 汇总指标;展开到这个 experiment 的 Eval,每道题内联该题全部 Attempt 的 locator 徽标。
+ * 没有 selection-form:`ExperimentList.data(selection)` 产出普通数组,过滤由报告作者对
+ * 数组调用 `.filter()`。
+ */
+export declare const ExperimentList: ReportComponent<ExperimentListProps> & {
+    data: typeof experimentListData;
+};
+/**
+ * Eval 列表:每项一个 `experimentId + evalId`,固定展示判定、Attempt 数、分数、成本、耗时
+ * 与失败原因;展开到这道题的 Attempt(与 AttemptList 同一份 AttemptListItem)。
+ */
+export declare const EvalList: ReportComponent<EvalListProps> & {
+    data: typeof evalListData;
+};
+/**
+ * Attempt 列表:实体列表的叶子层,每项一个 Attempt,固定展示判定、断言、error、Judge 评语
+ * (assertions 的 detail/evidence)与证据引用(locator + 证据能力标记)。它不预设只看失败;
+ * 报告作者过滤 `AttemptListItem[]`、用 `.slice()` 限量,`total` 让渲染面如实报告剩余数量。
+ */
+export declare const AttemptList: ReportComponent<AttemptListProps> & {
+    data: typeof attemptListData;
+};
+/** 榜单:一行一个维度值、一列一个指标,回答「谁整体更好」。 */
+export declare const MetricTable: ReportComponent<MetricTableProps> & {
+    data: typeof tableData;
+};
+/** 逐题格子:行 × 列两个维度、格子里一个指标,回答「哪道题谁挂了」。 */
+export declare const MetricMatrix: ReportComponent<MetricMatrixProps> & {
+    data: typeof matrixData;
+};
+/** 分组条形:同一份矩阵数据的另一种摆法;MetricBars.data 就是 MetricMatrix.data 的别名。 */
+export declare const MetricBars: ReportComponent<MetricMatrixProps> & {
+    data: typeof matrixData;
+};
+/** 考试成绩单:总分 + 分科小计,固定分母、missing 如实报。 */
+export declare const Scoreboard: ReportComponent<ScoreboardProps> & {
+    data: typeof scoreboardData;
+};
+/** 质量 × 成本 frontier:每个点一个配置、两个指标各占一轴,「好」的角落恒在右上。 */
+export declare const MetricScatter: ReportComponent<MetricScatterProps> & {
+    data: typeof scatterData;
+};
+/** 趋势线:x 是 experiment 声明的 flag(flag()),同系列按 x 排序连线。 */
+export declare const MetricLine: ReportComponent<MetricLineProps> & {
+    data: typeof lineData;
+};
+/** 成对对比:每行一对配置、格子里 A、B、Δ 三个值,涨跌好坏由 better 判定。 */
+export declare const DeltaTable: ReportComponent<DeltaTableProps> & {
+    data: typeof deltaData;
+};
+export {};

package/dist/report/components.js

@@ -0,0 +1,132 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+// 官方双面组件的装配点:web 面(./react/ 的纯 React 组件)+ text 面(./text/faces.ts)
+// + 挂在组件上的 data 计算函数。faces 两键必填 —— 配对是结构义务,不是配对表;
+// MetricBars.data 就是 MetricMatrix.data(同一份矩阵数据的另一种摆法),别名显式化。
+//
+// 官方组件在宿主里自动接上证据室:web 面的 attemptHref 缺省取 ctx.attemptHref
+// (宿主注入的证据室深链);显式传 prop 可覆盖(嵌进自己应用时自定去处)。三个实体列表
+// (ExperimentList / EvalList / AttemptList)没有这个覆盖口子——它们的 locator 徽标恒经
+// ctx.attemptHref / ctx.attemptCommand,不接受 attemptHref/attemptCommand prop(docs/feature/reports/library.md
+// 「嵌入自己的 React 页面」的函数签名没有这个参数),证据室深链在这三个组件上不是可选行为。
+import { defineComponent, isHostWebContextActive } from "./tree.js";
+import { attemptListData, deltaData, evalListData, experimentListData, groupSummaryData, lineData, matrixData, overviewData, scatterData, scoreboardData, tableData, } from "./compute.js";
+import { attemptListText, barsText, deltaText, evalListText, experimentListText, groupSummaryText, lineText, matrixText, overviewText, scatterText, scoreboardText, tableText, } from "./text/faces.js";
+import { RunOverview as RunOverviewWeb } from "./react/RunOverview.js";
+import { GroupSummary as GroupSummaryWeb } from "./react/GroupSummary.js";
+import { ExperimentList as ExperimentListWeb } from "./react/ExperimentList.js";
+import { EvalList as EvalListWeb } from "./react/EvalList.js";
+import { AttemptList as AttemptListWeb } from "./react/AttemptList.js";
+import { MetricTable as MetricTableWeb } from "./react/MetricTable.js";
+import { MetricMatrix as MetricMatrixWeb } from "./react/MetricMatrix.js";
+import { MetricBars as MetricBarsWeb } from "./react/MetricBars.js";
+import { Scoreboard as ScoreboardWeb } from "./react/Scoreboard.js";
+import { MetricScatter as MetricScatterWeb } from "./react/MetricScatter.js";
+import { MetricLine as MetricLineWeb } from "./react/MetricLine.js";
+import { DeltaTable as DeltaTableWeb } from "./react/DeltaTable.js";
+// ───────────────────────── 装配 ─────────────────────────
+const SCATTER_UNRESOLVED_MESSAGE = "MetricScatter received unresolved (selection-form) props outside the report host pipeline. " +
+    "Render through defineReport + niceeval show/view (or renderReportToText/renderReportToStaticHtml), " +
+    "or precompute with `await MetricScatter.data(selection, options)` and pass the result as `data`.";
+/** 渲染面(web / text)只吃已解析的数据形态;selection 形态漏解析时直说,而不是画一张空组件。 */
+function requireScatterData(props) {
+    if (props.data === undefined)
+        throw new Error(SCATTER_UNRESOLVED_MESSAGE);
+    return props.data;
+}
+/** 页头 KPI 条:何时跑的、几个配置、几道题、通过率、总成本;Selection 的警告随行显示在条内。 */
+export const RunOverview = Object.assign(defineComponent({
+    web: (props, ctx) => _jsx(RunOverviewWeb, { ...props, locale: props.locale ?? ctx.locale }),
+    text: ({ data }, ctx) => overviewText(data, ctx),
+}), { data: overviewData });
+RunOverview.displayName = "RunOverview";
+/**
+ * 组摘要:一组 experiment(典型用法是同一 `<Section>` 内的全部 experiment)的紧凑统计——
+ * 通过率(旧 GroupSelector 卡片口径)、experiment/eval/attempt 数、eval 级折叠计票、
+ * 总成本、最后运行时间。
+ */
+export const GroupSummary = Object.assign(defineComponent({
+    web: (props, ctx) => _jsx(GroupSummaryWeb, { ...props, locale: props.locale ?? ctx.locale }),
+    text: ({ data }, ctx) => groupSummaryText(data, ctx),
+}), { data: groupSummaryData });
+GroupSummary.displayName = "GroupSummary";
+/**
+ * 实验列表:每项一个 experiment,固定展示身份、配置(flags)、Eval 判定构成和官方两级聚合
+ * 汇总指标;展开到这个 experiment 的 Eval,每道题内联该题全部 Attempt 的 locator 徽标。
+ * 没有 selection-form:`ExperimentList.data(selection)` 产出普通数组,过滤由报告作者对
+ * 数组调用 `.filter()`。
+ */
+export const ExperimentList = Object.assign(defineComponent({
+    web: (props, ctx) => _jsx(ExperimentListWeb, { ...props, locale: props.locale ?? ctx.locale, attemptHref: ctx.attemptHref }),
+    text: ({ items }, ctx) => experimentListText(items, ctx),
+}), { data: experimentListData });
+ExperimentList.displayName = "ExperimentList";
+/**
+ * Eval 列表:每项一个 `experimentId + evalId`,固定展示判定、Attempt 数、分数、成本、耗时
+ * 与失败原因;展开到这道题的 Attempt(与 AttemptList 同一份 AttemptListItem)。
+ */
+export const EvalList = Object.assign(defineComponent({
+    web: (props, ctx) => _jsx(EvalListWeb, { ...props, locale: props.locale ?? ctx.locale, attemptHref: ctx.attemptHref }),
+    text: ({ items }, ctx) => evalListText(items, ctx),
+}), { data: evalListData });
+EvalList.displayName = "EvalList";
+/**
+ * Attempt 列表:实体列表的叶子层,每项一个 Attempt,固定展示判定、断言、error、Judge 评语
+ * (assertions 的 detail/evidence)与证据引用(locator + 证据能力标记)。它不预设只看失败;
+ * 报告作者过滤 `AttemptListItem[]`、用 `.slice()` 限量,`total` 让渲染面如实报告剩余数量。
+ */
+export const AttemptList = Object.assign(defineComponent({
+    web: (props, ctx) => _jsx(AttemptListWeb, { ...props, locale: props.locale ?? ctx.locale, attemptHref: ctx.attemptHref }),
+    text: ({ items, total }, ctx) => attemptListText(items, total, ctx),
+}), { data: attemptListData });
+AttemptList.displayName = "AttemptList";
+/** 榜单:一行一个维度值、一列一个指标,回答「谁整体更好」。 */
+export const MetricTable = Object.assign(defineComponent({
+    web: (props, ctx) => (_jsx(MetricTableWeb, { ...props, locale: props.locale ?? ctx.locale, attemptHref: props.attemptHref ?? (isHostWebContextActive() ? ctx.attemptHref : undefined) })),
+    text: ({ data }, ctx) => tableText(data, ctx),
+}), { data: tableData });
+MetricTable.displayName = "MetricTable";
+/** 逐题格子:行 × 列两个维度、格子里一个指标,回答「哪道题谁挂了」。 */
+export const MetricMatrix = Object.assign(defineComponent({
+    web: (props, ctx) => (_jsx(MetricMatrixWeb, { ...props, locale: props.locale ?? ctx.locale, attemptHref: props.attemptHref ?? (isHostWebContextActive() ? ctx.attemptHref : undefined) })),
+    text: ({ data }, ctx) => matrixText(data, ctx),
+}), { data: matrixData });
+MetricMatrix.displayName = "MetricMatrix";
+/** 分组条形:同一份矩阵数据的另一种摆法;MetricBars.data 就是 MetricMatrix.data 的别名。 */
+export const MetricBars = Object.assign(defineComponent({
+    web: (props, ctx) => (_jsx(MetricBarsWeb, { ...props, locale: props.locale ?? ctx.locale, attemptHref: props.attemptHref ?? (isHostWebContextActive() ? ctx.attemptHref : undefined) })),
+    text: ({ data }) => barsText(data),
+}), { data: matrixData });
+MetricBars.displayName = "MetricBars";
+/** 考试成绩单:总分 + 分科小计,固定分母、missing 如实报。 */
+export const Scoreboard = Object.assign(defineComponent({
+    web: (props, ctx) => _jsx(ScoreboardWeb, { ...props, locale: props.locale ?? ctx.locale }),
+    text: ({ data }, ctx) => scoreboardText(data, ctx),
+}), { data: scoreboardData });
+Scoreboard.displayName = "Scoreboard";
+/** 质量 × 成本 frontier:每个点一个配置、两个指标各占一轴,「好」的角落恒在右上。 */
+export const MetricScatter = Object.assign(defineComponent({
+    resolve: async (props) => {
+        if ("data" in props && props.data !== undefined)
+            return props;
+        const { selection, points, series, x, y, ...rest } = props;
+        return { ...rest, data: await scatterData(selection, { points, series, x, y }) };
+    },
+    web: (props, ctx) => {
+        requireScatterData(props);
+        return _jsx(MetricScatterWeb, { ...props, locale: props.locale ?? ctx.locale });
+    },
+    text: (props, ctx) => scatterText(requireScatterData(props), ctx),
+}), { data: scatterData });
+MetricScatter.displayName = "MetricScatter";
+/** 趋势线:x 是 experiment 声明的 flag(flag()),同系列按 x 排序连线。 */
+export const MetricLine = Object.assign(defineComponent({
+    web: (props, ctx) => _jsx(MetricLineWeb, { ...props, locale: props.locale ?? ctx.locale }),
+    text: ({ data }, ctx) => lineText(data, ctx),
+}), { data: lineData });
+MetricLine.displayName = "MetricLine";
+/** 成对对比:每行一对配置、格子里 A、B、Δ 三个值,涨跌好坏由 better 判定。 */
+export const DeltaTable = Object.assign(defineComponent({
+    web: (props, ctx) => _jsx(DeltaTableWeb, { ...props, locale: props.locale ?? ctx.locale }),
+    text: ({ data }, ctx) => deltaText(data, ctx),
+}), { data: deltaData });
+DeltaTable.displayName = "DeltaTable";

package/dist/report/compute.d.ts

@@ -0,0 +1,106 @@
+import type { AttemptListItem, DeltaData, DimensionInput, EvalListItem, ExperimentListItem, GroupSummaryData, LineData, MatrixData, Metric, OverviewData, FlagRef, ScatterData, ScoreboardData, TableData } from "./types.ts";
+import type { AssertionResult, EvalResult } from "../types.ts";
+import { type SnapshotsInput } from "./aggregate.ts";
+export interface TableDataOptions<M extends readonly Metric[]> {
+    /** 行维度(内置 / 自定义 / flag())。 */
+    rows: DimensionInput;
+    /** 每列一个指标;列键 = metric.name 的字面量,拼错编译不过。 */
+    columns: M;
+    /** 构建时排序,方向随 better(higher 降序,「好」的一头在上);缺数据行沉底。两面同口径,预排即终排。 */
+    sort?: Metric;
+    /** eval id 前缀过滤,同 CLI 位置参数语义。 */
+    evals?: string | string[];
+}
+/**
+ * 一次 attempt 未通过的 gate 断言,原始声明顺序不变;soft 断言不参与判定,不算「失败原因」,
+ * 只影响得分,永不出现在这份列表里。`EvalList` / `ExperimentList` 的失败诊断与 `AttemptList`
+ * 的断言列表共用这同一份材料,保证同一个 attempt 在各处给出同一个原因。
+ */
+export declare function failingGateAssertions(result: EvalResult): AssertionResult[];
+/**
+ * 一次 attempt 的失败原因文案,按优先级取第一个在场的:
+ * `error` → `skipReason` → 未通过的 gate 断言(原始声明顺序,`name`,detail 在场则
+ * `"name: detail"`,多条用「, 」连接)→ 都缺席则无原因(如某道题恰好没有失败信号)。
+ * soft 断言永不进入这份原因文案,soft 得分是独立概念,不与 reason 混用同一个字段。
+ */
+export declare function reasonFor(result: EvalResult): string | undefined;
+export declare function tableData<const M extends readonly Metric[]>(input: SnapshotsInput, opts: TableDataOptions<M>): Promise<TableData<M[number]["name"]>>;
+export interface AttemptListDataOptions {
+    /** 发布消毒:error / 断言 detail / evidence 经这个钩子;身份字段(experimentId/evalId/locator…)不经它。 */
+    redact?: (text: string) => string;
+}
+/** `AttemptList.data(selection)`:每个 Attempt 一项,顺序取自 Selection 展平顺序(不重排)。 */
+export declare function attemptListData(input: SnapshotsInput, opts?: AttemptListDataOptions): Promise<AttemptListItem[]>;
+/** `EvalList.data(selection)`:每个 `experimentId + evalId` 一项,按 evalId 再按 experimentId 升序。 */
+export declare function evalListData(input: SnapshotsInput): Promise<EvalListItem[]>;
+/** `ExperimentList.data(selection)`:每个 experiment 一项,按 experimentId 升序;展开到每道 Eval。 */
+export declare function experimentListData(input: SnapshotsInput): Promise<ExperimentListItem[]>;
+export interface MatrixDataOptions {
+    rows: DimensionInput;
+    columns: DimensionInput;
+    cell: Metric;
+    /** eval id 前缀过滤,同 CLI 位置参数语义。 */
+    evals?: string | string[];
+}
+export declare function matrixData(input: SnapshotsInput, opts: MatrixDataOptions): Promise<MatrixData>;
+export interface ScoreboardDataOptions {
+    /** 给谁打分(被打分的维度);维度槽与 MetricTable.data 统一叫 rows。 */
+    rows: DimensionInput;
+    /** 按什么分科;默认 "evalGroup"(考试里的「科目」)。 */
+    subjects?: DimensionInput;
+    /** eval id 前缀 → 每题分值;未列默认 1;前缀重叠时最长的生效。 */
+    weights?: Record<string, number>;
+    /** 折算满分;默认 100。 */
+    fullMarks?: number;
+    /** 每题得分指标;缺省即 examScore,可换自定义(如「答对但超预算扣分」)。 */
+    score?: Metric;
+    /** 选中范围:eval id 前缀过滤;题集(分母)只遍历这个范围。 */
+    evals?: string | string[];
+}
+/**
+ * 逐题分值制,分母对所有被打分者恒定:
+ *   题分值 = 命中的权重(默认 1)   题得分 = score 指标的题级值(perEval 折叠后)
+ *   总分   = fullMarks × Σ(题得分 × 题分值) / Σ(题分值)   Σ 遍历选中范围内全部题
+ * 没跑到的题挣 0 分但留在分母里,missing 如实报 —— 这是显式的考试契约,不是「null ≠ 0」的例外。
+ */
+export declare function scoreboardData(input: SnapshotsInput, opts: ScoreboardDataOptions): Promise<ScoreboardData>;
+export interface ScatterDataOptions {
+    /** 点维度:每个点 = 该组 attempt 的聚合。 */
+    points: DimensionInput;
+    /** 可选:同系列的点连成线;省略 = 纯散点。 */
+    series?: DimensionInput;
+    x: Metric;
+    y: Metric;
+}
+export declare function scatterData(input: SnapshotsInput, opts: ScatterDataOptions): Promise<ScatterData>;
+export interface LineDataOptions {
+    /** x 轴:experiment 声明的 flag(数值),不解析 experiment 命名。 */
+    x: FlagRef;
+    y: Metric;
+    /** 可选:每个系列一条线(flag 或普通维度);省略 = 单系列。 */
+    series?: DimensionInput;
+}
+/** 每个点 = 一个 experiment 的聚合;同系列的点按 x 排序连线(排序在组件面,数据保持分组序)。 */
+export declare function lineData(input: SnapshotsInput, opts: LineDataOptions): Promise<LineData>;
+/** Selection 的 warnings 随行进 OverviewData,RunOverview 直接渲染 —— 诚实不靠使用者记得接线。 */
+export declare function overviewData(input: SnapshotsInput): Promise<OverviewData>;
+/**
+ * 一组 experiment 的摘要:experiment/eval/attempt 数量、eval 级折叠计票、通过率(旧
+ * `GroupSelector` 卡片口径,见 summarizeItems)、总成本(null-safe 求和)、最后运行时间
+ * (组内快照 startedAt 最大值)。`input` 就是调用方已经收窄好的组 Selection(如自定义报告
+ * 按 experiment 组前缀 filter 出来的那份)——本函数不再自己分组。
+ */
+export declare function groupSummaryData(input: SnapshotsInput): Promise<GroupSummaryData>;
+export interface DeltaPair {
+    /** 基线侧:experiment id,或快照键 "<experimentId> @ <startedAt>"(时间轴对比用手挑的快照数组)。 */
+    a: string;
+    /** 对比侧,同上。 */
+    b: string;
+    label?: string;
+}
+export interface DeltaDataOptions<M extends readonly Metric[]> {
+    /** 每行一对:B 相对 A。 */
+    pairs: DeltaPair[];
+    metrics: M;
+}
+export declare function deltaData<const M extends readonly Metric[]>(input: SnapshotsInput, opts: DeltaDataOptions<M>): Promise<DeltaData<M[number]["name"]>>;