niceeval 0.9.0 → 0.10.0

package/src/report/components/entity-lists/validate.test.ts

@@ -0,0 +1,114 @@
+// cases: docs/engineering/unit-tests/reports/cases.md
+// "validate*Data 递归覆盖到嵌套字段" 行:entity-lists 三个 validate*Data 的表驱动字段突变覆盖,AttemptListItem 的形状在三个组件族
+// 共用(独立 data 或嵌套在 evalRows/attempts 里),重点覆盖嵌套 MetricCell/tally 字段与
+// 深层嵌套(ExperimentListItem.evalRows[i].attempts[j])的路径定位。
+
+import { describe, expect, it } from "vitest";
+import { validateAttemptListData, validateEvalListData, validateExperimentListData } from "./index.tsx";
+
+const validCell = { value: 1, display: "1", samples: 1, total: 1, refs: [] };
+const validTally = { passed: 1, failed: 0, errored: 0, skipped: 0 };
+
+const validAttemptItem = {
+  experimentId: "compare/codex",
+  evalId: "q1",
+  attempt: 0,
+  agent: "codex",
+  verdict: "passed",
+  failureSummary: null,
+  moreFailures: 0,
+  examScore: validCell,
+  durationMs: 1000,
+  costUSD: 0.01,
+  locator: "@1abcdef2",
+};
+
+describe("validateAttemptListData", () => {
+  it("合规 literal 通过,costUSD 为 null 与 failureSummary 为 null 合法", () => {
+    expect(validateAttemptListData([{ ...validAttemptItem, costUSD: null }])).toBeNull();
+  });
+
+  it("非数组整体报错", () => {
+    expect(validateAttemptListData({})).toMatch(/"data" must be an array/);
+  });
+
+  it("[i].examScore 结构错误定位到嵌套 MetricCell 字段", () => {
+    const bad = [{ ...validAttemptItem, examScore: { value: 1 } }];
+    expect(validateAttemptListData(bad)).toMatch(/"data\[0\]\.examScore\.display"/);
+  });
+
+  it("[i].verdict 非字符串报错", () => {
+    const bad = [{ ...validAttemptItem, verdict: 1 }];
+    expect(validateAttemptListData(bad)).toMatch(/"data\[0\]\.verdict"/);
+  });
+});
+
+describe("validateEvalListData", () => {
+  const valid = [
+    {
+      experimentId: "compare/codex",
+      evalId: "q1",
+      verdict: "passed",
+      examScore: validCell,
+      durationMs: validCell,
+      costUSD: validCell,
+      attempts: [validAttemptItem],
+    },
+  ];
+
+  it("合规 literal 通过", () => {
+    expect(validateEvalListData(valid)).toBeNull();
+  });
+
+  it("[i].durationMs(MetricCell)结构错误报错", () => {
+    const bad = [{ ...valid[0], durationMs: { value: 1, display: "1", samples: 1, total: 1 } }];
+    expect(validateEvalListData(bad)).toMatch(/"data\[0\]\.durationMs\.refs"/);
+  });
+
+  it("[i].attempts[j] 嵌套 AttemptListItem 结构错误定位到深层下标", () => {
+    const bad = [{ ...valid[0], attempts: [{ ...validAttemptItem, locator: 1 }] }];
+    expect(validateEvalListData(bad)).toMatch(/"data\[0\]\.attempts\[0\]\.locator"/);
+  });
+});
+
+describe("validateExperimentListData", () => {
+  const validEvalRow = { evalId: "q1", verdict: "passed", durationMs: validCell, costUSD: validCell, attempts: [validAttemptItem] };
+  const valid = [
+    {
+      experimentId: "compare/codex",
+      agent: "codex",
+      evalVerdicts: validTally,
+      endToEndPassRate: validCell,
+      costUSD: validCell,
+      durationMs: validCell,
+      tokens: validCell,
+      evals: 1,
+      attempts: 1,
+      lastRunAt: "2026-07-01T00:00:00Z",
+      evalRows: [validEvalRow],
+    },
+  ];
+
+  it("合规 literal 通过", () => {
+    expect(validateExperimentListData(valid)).toBeNull();
+  });
+
+  it("[i].evalVerdicts(四态 tally)缺字段报错", () => {
+    const bad = [{ ...valid[0], evalVerdicts: { passed: 1, failed: 0, errored: 0 } }];
+    expect(validateExperimentListData(bad)).toMatch(/"data\[0\]\.evalVerdicts\.skipped"/);
+  });
+
+  it("[i].evalRows[j].attempts[k] 三层嵌套报错精确定位", () => {
+    const bad = [
+      {
+        ...valid[0],
+        evalRows: [{ ...validEvalRow, attempts: [{ ...validAttemptItem, examScore: null }] }],
+      },
+    ];
+    expect(validateExperimentListData(bad)).toMatch(/"data\[0\]\.evalRows\[0\]\.attempts\[0\]\.examScore"/);
+  });
+
+  it("model / flags 可选字段省略仍合法", () => {
+    expect(validateExperimentListData(valid)).toBeNull();
+  });
+});

package/src/report/{react → components}/fixtures.ts

@@ -15,7 +15,7 @@ import type {
   ScopeSummaryData,
   ScoreboardData,
   TableData,
-} from "../types.ts";
+} from "../model/types.ts";
 import type { AttemptLocator } from "../../results/locator.ts";
 
 const locator = (s: string): AttemptLocator => s as AttemptLocator;
@@ -24,7 +24,7 @@ export const passRateColumn: MetricColumn = { key: "task-pass-rate", label: "pas
 export const codeLinesColumn: MetricColumn = { key: "code-lines", label: "code lines", unit: "lines", better: "lower" };
 export const costColumn: MetricColumn = { key: "cost", label: "cost", unit: "$", better: "lower" };
 
-/** scopeSummaryData 的产物形态:两级计票恒随行,成功率与总成本是官方 MetricCell。 */
+/** scopeSummaryData 的产物形态:两级计票恒随行,通过率与总成本是官方 MetricCell。 */
 export const scopeSummaryData: ScopeSummaryData = {
   range: { earliestStartedAt: "2026-07-01T10:00:00Z", latestStartedAt: "2026-07-01T11:30:00Z" },
   experiments: 2,

package/src/report/{react → components/metric-views}/DeltaTable.tsx

@@ -4,11 +4,11 @@
 // 0 对不是错误:派生形态(pairsByFlag)配不出对时显示明确空态并报告配对域实验数。
 
 import type { ReactElement } from "react";
-import type { DeltaData } from "../types.ts";
-import { DEFAULT_REPORT_LOCALE, localeText, resolveLocalizedText, resolveMetricLabel, type ReportLocale } from "../locale.ts";
-import { MetricCellView } from "./cell.tsx";
-import { colorClassForKey } from "./colors.ts";
-import { cx } from "./format.ts";
+import type { DeltaData } from "../../model/types.ts";
+import { DEFAULT_REPORT_LOCALE, localeText, resolveLocalizedText, resolveMetricLabel, type ReportLocale } from "../../model/locale.ts";
+import { MetricCellView } from "../cell.tsx";
+import { colorClassForKey } from "../../assets/colors.ts";
+import { cx } from "../shared.ts";
 
 const OUTCOME_CLASS: Record<string, string> = {
   improved: "nre-delta-good",

package/src/report/{react → components/metric-views}/MetricBars.tsx

@@ -4,11 +4,11 @@
 // 组内按值排序,方向随 better;缺数据的系列不画柱、不编 0(与 text 面的 — 同口径)。
 
 import type { ReactElement } from "react";
-import type { MatrixData, MetricCell } from "../types.ts";
-import type { AttemptLocator } from "../../results/locator.ts";
-import { DEFAULT_REPORT_LOCALE, resolveLocalizedText, resolveMetricLabel, type ReportLocale } from "../locale.ts";
-import { colorClassForKey, seriesClassForKey } from "./colors.ts";
-import { cx } from "./format.ts";
+import type { MatrixData, MetricCell } from "../../model/types.ts";
+import type { AttemptLocator } from "../../../results/locator.ts";
+import { DEFAULT_REPORT_LOCALE, resolveLocalizedText, resolveMetricLabel, type ReportLocale } from "../../model/locale.ts";
+import { colorClassForKey, seriesClassForKey } from "../../assets/colors.ts";
+import { cx } from "../shared.ts";
 
 const WIDTH = 640;
 const HEIGHT = 320;

package/src/report/{react → components/metric-views}/MetricLine.tsx

@@ -6,10 +6,10 @@
 // 上色,深色主题跟随,不留内联 hex。
 
 import type { ReactElement } from "react";
-import type { LineData } from "../types.ts";
-import { DEFAULT_REPORT_LOCALE, countText, localeText, resolveLocalizedText, resolveMetricLabel, type ReportLocale } from "../locale.ts";
-import { seriesClassForKey } from "./colors.ts";
-import { cx } from "./format.ts";
+import type { LineData } from "../../model/types.ts";
+import { DEFAULT_REPORT_LOCALE, countText, localeText, resolveLocalizedText, resolveMetricLabel, type ReportLocale } from "../../model/locale.ts";
+import { colorIndicesForKeys } from "../../assets/colors.ts";
+import { cx } from "../shared.ts";
 
 const WIDTH = 640;
 const HEIGHT = 360;
@@ -101,6 +101,9 @@ export function MetricLine({
     bySeries.get(key)!.push(p);
   }
   for (const list of bySeries.values()) list.sort((a, b) => a.xValue - b.xValue);
+  // 同图撞色消解:散列格作起点,按图例顺序线性探测空格(colors.ts 的契约注释)
+  const colorIdx = colorIndicesForKeys(seriesOrder.filter((s) => s !== ""));
+  const seriesClassOf = (series: string) => (series === "" ? "nre-series-none" : `nre-series-c${colorIdx.get(series) ?? 0}`);
 
   const xTicks = xScale.lo === xScale.hi ? [xScale.lo] : [xScale.lo, xScale.hi];
   const yTicks = yScale.lo === yScale.hi ? [yScale.lo] : [yScale.lo, yScale.hi];
@@ -157,7 +160,7 @@ export function MetricLine({
 
         {seriesOrder.map((series) => {
           const list = bySeries.get(series)!;
-          const seriesClass = series === "" ? "nre-series-none" : seriesClassForKey(series);
+          const seriesClass = seriesClassOf(series);
           const labelAt = list.reduce((a, b) => (b.px > a.px ? b : a));
           return (
             <g key={series || "(single)"} className={cx("nre-line-series", seriesClass)} data-series={series || undefined}>
@@ -180,7 +183,7 @@ export function MetricLine({
         {points.map((p, i) => {
           const circle = (
             <circle
-              className={cx("nre-line-point", p.series !== undefined ? seriesClassForKey(p.series) : "nre-series-none")}
+              className={cx("nre-line-point", p.series !== undefined ? seriesClassOf(p.series) : "nre-series-none")}
               data-key={p.key}
               cx={p.px}
               cy={p.py}

package/src/report/{react → components/metric-views}/MetricMatrix.tsx

@@ -5,12 +5,12 @@
 // 是格子里的普通 <a>,不 hydrate 也能点。
 
 import type { ReactElement } from "react";
-import type { MatrixData } from "../types.ts";
-import type { AttemptLocator } from "../../results/locator.ts";
-import { DEFAULT_REPORT_LOCALE, resolveMetricLabel, type ReportLocale } from "../locale.ts";
-import { MetricCellView } from "./cell.tsx";
-import { colorClassForKey } from "./colors.ts";
-import { cx } from "./format.ts";
+import type { MatrixData } from "../../model/types.ts";
+import type { AttemptLocator } from "../../../results/locator.ts";
+import { DEFAULT_REPORT_LOCALE, resolveMetricLabel, type ReportLocale } from "../../model/locale.ts";
+import { MetricCellView } from "../cell.tsx";
+import { colorClassForKey } from "../../assets/colors.ts";
+import { cx } from "../shared.ts";
 
 export function MetricMatrix({
   data,

package/src/report/{react → components/metric-views}/MetricScatter.tsx

@@ -3,22 +3,24 @@
 // 「越靠右上越好」且仅当两轴都声明 better 时显示;刻度显示真实值。
 // niceTicks 刻度 + 网格线;每个点直接标注(placePointLabels 候选位择优:避开其它标签、
 // 数据点与画布边界,离开左右紧邻位时补 leader line);
-// 同系列的点按 x 值排序连线,系列图例列在图下。x 或 y 为 null 的点不画,
+// 默认不连线,`connect` 显式开启时同系列的点按 x 升序连折线(lineage series),
+// 系列图例按显示键字典序列在图下。x 或 y 为 null 的点不画,
 // 底部注脚如实报「n 个点缺数据」;hover 信息退化为 SVG <title>,不 hydrate 也在
 // (enhance.js 在场时升级为样式化 tooltip)。配色走类名(nre-series-cN)由 CSS 上色,
-// 深色主题下图表随令牌切换,不留内联 hex。
+// 深色主题下图表随令牌切换,不留内联 hex;同图 series 撞色按图例顺序线性探测消解
+// (colorIndicesForKeys),跨图稳定让位给图内可辨。
 
 import type { ReactElement } from "react";
-import type { MetricColumn, ScatterData } from "../types.ts";
-import { formatMetricValue } from "../format.ts";
-import { DEFAULT_REPORT_LOCALE, countText, localeText, resolveLocalizedText, resolveMetricLabel, type ReportLocale } from "../locale.ts";
+import type { MetricColumn, ScatterData } from "../../model/types.ts";
+import { formatMetricValue } from "../../model/format.ts";
+import { DEFAULT_REPORT_LOCALE, countText, localeText, resolveLocalizedText, resolveMetricLabel, type ReportLocale } from "../../model/locale.ts";
 import { niceTicks, placePointLabels } from "./chart-math.ts";
-import { colorClassForKey, seriesClassForKey } from "./colors.ts";
-import { cx } from "./format.ts";
+import { colorIndicesForKeys } from "../../assets/colors.ts";
+import { cx } from "../shared.ts";
 
-const WIDTH = 640;
-const HEIGHT = 360;
-const MARGIN = { top: 26, right: 24, bottom: 46, left: 62 };
+const WIDTH = 760;
+const HEIGHT = 400;
+const MARGIN = { top: 28, right: 32, bottom: 48, left: 64 };
 const PLOT_W = WIDTH - MARGIN.left - MARGIN.right;
 const PLOT_H = HEIGHT - MARGIN.top - MARGIN.bottom;
 
@@ -89,11 +91,14 @@ function axisScale(values: number[], pixelLo: number, pixelHi: number, invert: b
 
 export function MetricScatter({
   data,
+  connect = false,
   pointHref,
   className,
   locale = DEFAULT_REPORT_LOCALE,
 }: {
   data: ScatterData;
+  /** series 内按 x 升序连折线;默认 false,只给「线 = 同族变体」的 lineage series 用。 */
+  connect?: boolean;
   pointHref?: (row: ScatterData["rows"][number]) => string;
   className?: string;
   locale?: ReportLocale;
@@ -159,18 +164,20 @@ export function MetricScatter({
     };
   });
 
-  // 同系列的点按 x 值排序连线;无系列的点只画点不连线
-  const seriesOrder: string[] = [];
+  // 系列分组:图例与配色按显示键字典序;connect 时 series 内按 x 升序连折线
   const bySeries = new Map<string, DrawablePoint[]>();
   for (const p of points) {
     if (p.series === undefined) continue;
-    if (!bySeries.has(p.series)) {
-      bySeries.set(p.series, []);
-      seriesOrder.push(p.series);
-    }
-    bySeries.get(p.series)!.push(p);
+    const list = bySeries.get(p.series) ?? [];
+    list.push(p);
+    bySeries.set(p.series, list);
   }
+  const seriesOrder = [...bySeries.keys()].sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
   for (const list of bySeries.values()) list.sort((a, b) => a.xValue - b.xValue);
+  // 同图撞色消解:散列格作起点,按图例顺序线性探测空格(colors.ts 的契约注释)
+  const colorIdx = colorIndicesForKeys(seriesOrder);
+  const seriesClassOf = (series: string) => `nre-series-c${colorIdx.get(series) ?? 0}`;
+  const keyClassOf = (series: string) => `nre-c${colorIdx.get(series) ?? 0}`;
 
   // 直接标签的候选位择优布局:锚向、避让方向都由布局按空间决定,画布边界含边距
   const labels = placePointLabels(
@@ -238,20 +245,21 @@ export function MetricScatter({
           {axisLabel(yLabel, data.y)}
         </text>
 
-        {/* 系列连线:类名上色(nre-series-cN),深色主题跟随 */}
-        {seriesOrder.map((series) => {
-          const list = bySeries.get(series)!;
-          if (list.length < 2) return null;
-          return (
-            <polyline
-              key={series}
-              className={cx("nre-scatter-line", seriesClassForKey(series))}
-              data-series={series}
-              points={list.map((p) => `${p.px},${p.py}`).join(" ")}
-              fill="none"
-            />
-          );
-        })}
+        {/* 系列折线:仅 connect 显式开启时画(lineage series 的位移),按 x 升序;类名上色,深色主题跟随 */}
+        {connect &&
+          seriesOrder.map((series) => {
+            const list = bySeries.get(series)!;
+            if (list.length < 2) return null;
+            return (
+              <polyline
+                key={series}
+                className={cx("nre-scatter-line", seriesClassOf(series))}
+                data-series={series}
+                points={list.map((p) => `${p.px},${p.py}`).join(" ")}
+                fill="none"
+              />
+            );
+          })}
 
         {/* 点:g 内带 <title>(无 JS 的原生 hover)、直接标签与 leader line;
             pointHref 时包普通 <a>,静态导出也能下钻 */}
@@ -259,7 +267,7 @@ export function MetricScatter({
           const label = labels[i];
           const group = (
             <g
-              className={cx("nre-scatter-point", p.series !== undefined ? seriesClassForKey(p.series) : "nre-series-none")}
+              className={cx("nre-scatter-point", p.series !== undefined ? seriesClassOf(p.series) : "nre-series-none")}
               data-key={p.key}
             >
               <title>{p.title}</title>
@@ -287,7 +295,7 @@ export function MetricScatter({
       {seriesOrder.length > 0 && (
         <figcaption className="nre-scatter-legend">
           {seriesOrder.map((series) => (
-            <span key={series} className={cx("nre-legend-key", "nre-key", colorClassForKey(series))}>
+            <span key={series} className={cx("nre-legend-key", "nre-key", keyClassOf(series))}>
               {series}
             </span>
           ))}

package/src/report/{react → components/metric-views}/MetricTable.tsx

@@ -8,12 +8,12 @@
 // 一组全 null 渲染成「缺数据」,绝不画 0(逻辑在 MetricCellView)。
 
 import type { ReactElement } from "react";
-import type { TableData } from "../types.ts";
-import type { AttemptLocator } from "../../results/locator.ts";
-import { DEFAULT_REPORT_LOCALE, localeText, resolveMetricLabel, type ReportLocale } from "../locale.ts";
-import { MetricCellView } from "./cell.tsx";
-import { colorClassForKey } from "./colors.ts";
-import { cx } from "./format.ts";
+import type { TableData } from "../../model/types.ts";
+import type { AttemptLocator } from "../../../results/locator.ts";
+import { DEFAULT_REPORT_LOCALE, localeText, resolveMetricLabel, type ReportLocale } from "../../model/locale.ts";
+import { MetricCellView } from "../cell.tsx";
+import { colorClassForKey } from "../../assets/colors.ts";
+import { cx } from "../shared.ts";
 
 export function MetricTable({
   data,

package/src/report/{react → components/metric-views}/Scoreboard.tsx

@@ -4,10 +4,10 @@
 // weights 是「实际生效的权重表」,渲染出来让成绩单可审计;题集之外被忽略的 eval 数在注脚。
 
 import type { ReactElement } from "react";
-import type { ScoreboardData } from "../types.ts";
-import { DEFAULT_REPORT_LOCALE, countText, localeText, resolveLocalizedText, type ReportLocale } from "../locale.ts";
-import { colorClassForKey } from "./colors.ts";
-import { cx } from "./format.ts";
+import type { ScoreboardData } from "../../model/types.ts";
+import { DEFAULT_REPORT_LOCALE, countText, localeText, resolveLocalizedText, type ReportLocale } from "../../model/locale.ts";
+import { colorClassForKey } from "../../assets/colors.ts";
+import { cx } from "../shared.ts";
 
 export function Scoreboard({
   data,