niceeval 0.9.1 → 0.10.2

package/src/report/index.ts

@@ -3,7 +3,7 @@
 //
 // import 边界即运行时边界:计算函数(*Data)会经句柄触碰文件系统(懒加载 artifact),
 // 只能进服务端 / 脚本;组件的渲染面纯同步零 IO。text 宿主遍历渲染不需要 react-dom
-// (renderReportToText);web 宿主的 renderReportToStaticHtml 在 ./web.ts,只有那一侧
+// (renderReportToText);web 宿主的 renderReportToStaticHtml 在 ./runtime/web.ts,只有那一侧
 // import react-dom。写报告文件的项目要装 react(.tsx 编译产物 import react/jsx-runtime)。
 
 // 指标与维度读取器
@@ -18,59 +18,73 @@ export {
   repeatedFailedCommands,
   taskPassRate,
   tokens,
-} from "./metrics.ts";
-export { flag, numericFlag, numericRunConfig, runConfig } from "./flag.ts";
+} from "./model/metrics.ts";
+export { flag, label, numericFlag, numericLabel, numericRunConfig, runConfig } from "./model/flag.ts";
 
 // 报告定义与组件基座
 export {
   buildReportMeta,
   defineReport,
   isReportDefinition,
-  pickReportPage,
-  renderReportToText,
-  renderReportTreeToText,
-  reportTitleText,
   resolveReportTitle,
-  ReportPageNotFoundError,
   DEFAULT_PAGE_ID,
-} from "./report.ts";
+} from "./definition/report.ts";
 export type {
-  HostCommandContext,
   NonEmptyArray,
-  RenderReportTextOptions,
-  RenderTreeTextOptions,
-  ReportTreeHostContext,
   HeadTag,
   ReportAsset,
   ReportDef,
   ReportDefinition,
-  ReportHostContext,
   ReportLink,
   ReportMeta,
+  ReportMetaPage,
   ReportPage,
+  ReportPageBase,
   ReportShell,
-} from "./report.ts";
-export { defineComponent, createTextContext, renderNodeToText, resolveReportTree, validateReportTree, ResolveMemo } from "./tree.ts";
+} from "./definition/report.ts";
+export {
+  pickReportPage,
+  renderReportToText,
+  renderReportTreeToText,
+  reportTitleText,
+  ReportPageNotFoundError,
+  ReportPageNeedsLocatorError,
+} from "./runtime/text.ts";
+export type {
+  HostCommandContext,
+  RenderReportTextOptions,
+  RenderTreeTextOptions,
+  ReportTreeHostContext,
+  ReportHostContext,
+} from "./runtime/text.ts";
+export { defineComponent, createTextContext, renderNodeToText, resolveReportTree, validateReportTree, ResolveMemo } from "./definition/tree.ts";
+export type { AttemptEvidence, AttemptEvidenceCapabilities } from "../results/attempt-evidence.ts";
 export type {
+  AttemptPageContext,
   ComponentFaces,
   ComposeContext,
+  PageContext,
   ReportComponent,
   ReportElement,
   ReportNode,
   ResolveContext,
   ResolveEnv,
+  ScopePageContext,
   TextContext,
   TextRenderOptions,
   WebContext,
-} from "./tree.ts";
+} from "./definition/tree.ts";
 
-// 排版原语(八个内置双面组件)
-export { Col, Row, Section, Style, Tab, Table, Tabs, Text } from "./primitives.tsx";
+// 排版原语(十个内置双面组件)
+export { Col, Grid, Row, Section, Stat, Style, Tab, Table, Tabs, Text } from "./definition/primitives.tsx";
 export type {
   ColProps,
+  GridProps,
   LayoutProps,
   RowProps,
   SectionProps,
+  StatProps,
+  StatTone,
   StyleProps,
   TabProps,
   TableColumn,
@@ -78,7 +92,7 @@ export type {
   TableRow,
   TabsProps,
   TextProps,
-} from "./primitives.tsx";
+} from "./definition/primitives.tsx";
 
 // 文本排版工具箱:自定义组件的 text 面用的就是官方组件那把尺子。
 // 表格有 <Table> 承担,这里只给表以外的形态用 —— 尤其别拿 String.prototype.padEnd 对齐:
@@ -91,78 +105,90 @@ export {
   indentBlock as indent,
   textBar as bar,
   joinColumns as columns,
-} from "./text/layout.ts";
-export type { ColumnAlign } from "./text/layout.ts";
+} from "./model/text-layout.ts";
+export type { ColumnAlign } from "./model/text-layout.ts";
 
 // locale:官方组件 chrome 文案的语言(内置词典覆盖 en / zh-CN,其它 locale 走回退)
-export { DEFAULT_REPORT_LOCALE, localizedTextEquals, resolveLocalizedText, resolveMetricLabel } from "./locale.ts";
-export type { LocalizedText, ReportLocale } from "./locale.ts";
+export { DEFAULT_REPORT_LOCALE, localizedTextEquals, resolveLocalizedText, resolveMetricLabel } from "./model/locale.ts";
+export type { LocalizedText, ReportLocale } from "./model/locale.ts";
 
 // 官方双面组件(spec / data 双形态;配套 *Data 计算函数在下面成对导出)
 // 与站点组件(Hero / HeroCard / PoweredBy / ScopeWarnings / CopyFixPrompt / TraceWaterfall)
+export { ScopeSummary, ExperimentComparison } from "./components/summaries/index.tsx";
+export type { ScopeSummaryProps, ExperimentComparisonProps } from "./components/summaries/index.tsx";
+export { AttemptList, EvalList, ExperimentList, FailureList } from "./components/entity-lists/index.tsx";
+export type {
+  AttemptListProps,
+  EvalListProps,
+  ExperimentListProps,
+  FailureListProps,
+} from "./components/entity-lists/index.tsx";
 export {
-  AttemptList,
-  CopyFixPrompt,
   DeltaTable,
-  EvalList,
-  ExperimentComparison,
-  ExperimentList,
-  FailureList,
-  Hero,
-  HeroCard,
   MetricBars,
   MetricLine,
   MetricMatrix,
   MetricScatter,
   MetricTable,
-  PoweredBy,
   Scoreboard,
-  ScopeSummary,
-  ScopeWarnings,
-  TraceWaterfall,
-} from "./components.tsx";
+} from "./components/metric-views/index.tsx";
 export type {
-  AttemptListProps,
-  CopyFixPromptProps,
-  DataProps,
   DeltaTableProps,
-  EvalListProps,
-  ExperimentComparisonProps,
-  ExperimentListProps,
-  FailureListProps,
-  HeroCardProps,
-  HeroProps,
   MetricBarsProps,
   MetricLineProps,
   MetricMatrixProps,
   MetricScatterProps,
   MetricTableProps,
   ScoreboardProps,
-  ScopeSummaryProps,
+} from "./components/metric-views/index.tsx";
+export {
+  CopyFixPrompt,
+  Hero,
+  HeroCard,
+  PoweredBy,
+  ScopeWarnings,
+  TraceWaterfall,
+} from "./components/site-components/index.tsx";
+export type {
+  CopyFixPromptProps,
+  HeroCardProps,
+  HeroProps,
   ScopeWarningsProps,
   TraceWaterfallProps,
-} from "./components.tsx";
+} from "./components/site-components/index.tsx";
+
+// Attempt 详情组件族(docs/feature/reports/library/attempt-detail.md):11 个叶子 + 2 个
+// 只装配叶子的组合组件(AttemptAssessment / AttemptDetail),都从 niceeval/report 导出。
+export {
+  AttemptAssertions,
+  AttemptAssessment,
+  AttemptConversation,
+  AttemptDetail,
+  AttemptDiagnostics,
+  AttemptDiff,
+  AttemptError,
+  AttemptFixPrompt,
+  AttemptSource,
+  AttemptSummary,
+  AttemptTimeline,
+  AttemptTrace,
+  AttemptUsage,
+} from "./components/attempt-detail/index.tsx";
+export type { AttemptSectionProps } from "./components/attempt-detail/index.tsx";
 
 // 计算函数(组件解析面的具名形式,与组件成对;spec 形态下由管线代调,data 形态与
 // 嵌入场景下由作者手工调)
+export { scopeSummaryData } from "./components/summaries/compute.ts";
+export { attemptListData, evalListData, experimentListData } from "./components/entity-lists/compute.ts";
 export {
-  attemptListData,
-  copyFixPromptData,
   deltaTableData,
-  evalListData,
-  experimentComparisonData,
-  experimentListData,
-  heroData,
   metricLineData,
   metricMatrixData,
   metricScatterData,
   metricTableData,
   pairsByFlag,
-  scopeSummaryData,
-  scopeWarningsData,
   scoreboardData,
-  traceWaterfallData,
-} from "./compute.ts";
+} from "./components/metric-views/compute.ts";
 export type {
   DeltaTableOptions,
   MetricLineOptions,
@@ -170,7 +196,28 @@ export type {
   MetricScatterOptions,
   MetricTableOptions,
   ScoreboardOptions,
-} from "./compute.ts";
+} from "./components/metric-views/compute.ts";
+export {
+  copyFixPromptData,
+  heroData,
+  scopeWarningsData,
+  traceWaterfallData,
+} from "./components/site-components/compute.ts";
+
+// Attempt 详情组件族的计算函数:输入恒为单个 AttemptEvidence,同步纯派生(不读文件、不 fetch)。
+export {
+  attemptAssertionsData,
+  attemptConversationData,
+  attemptDiagnosticsData,
+  attemptDiffData,
+  attemptErrorData,
+  attemptFixPromptData,
+  attemptSourceData,
+  attemptSummaryData,
+  attemptTimelineData,
+  attemptTraceData,
+  attemptUsageData,
+} from "./components/attempt-detail/compute.ts";
 
 // 数据契约(组件的 data)
 export type {
@@ -186,8 +233,6 @@ export type {
   DimensionOptions,
   DimensionRef,
   EvalListItem,
-  ExperimentComparisonData,
-  ExperimentComparisonGroupData,
   ExperimentListEvalRow,
   ExperimentListItem,
   FlagPairs,
@@ -207,15 +252,32 @@ export type {
   ScopeSummaryData,
   ScopeWarning,
   ScoreboardData,
+  SeriesInput,
   TableData,
   TraceSpanSummary,
   TraceWaterfallRow,
   VerdictTally,
-} from "./types.ts";
+} from "./model/types.ts";
+
+// Attempt 详情组件族的数据契约
+export type {
+  AttemptAssertionsData,
+  AttemptConversationData,
+  AttemptConversationReply,
+  AttemptConversationRound,
+  AttemptDiagnosticsData,
+  AttemptDiffData,
+  AttemptDiffFileEntry,
+  AttemptErrorData,
+  AttemptFixPromptData,
+  AttemptSourceData,
+  AttemptSourceLineData,
+  AttemptSourceTurn,
+  AttemptSummaryData,
+  AttemptTimelineData,
+  AttemptTraceData,
+  AttemptUsageData,
+} from "./model/types.ts";
 
 // 数据层输入的类型(家在 niceeval/results,这里 re-export 方便写指标 / 报告)
 export type { AttemptHandle, Results, Scope, Snapshot } from "../results/types.ts";
-
-// experiment id 的组键推导(id 的目录前缀,如 `compare/bub-low` 的 `compare`)。
-// 重新导出,让自定义报告能按同一份口径把 experiment 分组,不必自己重写这两行逻辑。
-export { experimentGroupOf } from "../shared/aggregate.ts";

package/src/report/{aggregate.ts → model/aggregate.ts}

@@ -6,9 +6,9 @@
 // 和重试策略纠缠在一起(eval A=[1]、eval B=[0,0,0] 平铺 = 0.25,两级宏平均 = 0.5)。
 // 自定义维度把同一道题的 attempt 分进不同组时,第一级折叠发生在各组内部。
 
-import { dedupeAttempts } from "../results/select.ts";
-import type { AttemptHandle, Scope, ScopeWarning, Snapshot } from "../results/types.ts";
-import { encodeAttemptLocator, type AttemptLocator } from "../results/locator.ts";
+import { dedupeAttempts } from "../../results/select.ts";
+import type { AttemptHandle, Scope, ScopeWarning, Snapshot } from "../../results/types.ts";
+import { encodeAttemptLocator, type AttemptLocator } from "../../results/locator.ts";
 import type {
   Aggregator,
   DimensionInput,
@@ -18,11 +18,12 @@ import type {
   MetricColumn,
   NumericAxis,
   ReportInput,
+  SeriesInput,
 } from "./types.ts";
-import { flagValueOf, runConfigValueOf } from "./flag.ts";
+import { flagValueOf, labelValueOf, runConfigValueOf } from "./flag.ts";
 import { formatMetricValue, localizedDisplay } from "./format.ts";
 import { localeText, type LocalizedText } from "./locale.ts";
-import { evalPrefixPredicate } from "../shared/aggregate.ts";
+import { evalPrefixPredicate } from "../../shared/aggregate.ts";
 
 // 复合键分隔符:NUL 不会出现在 eval id / experimentId / ISO 时间里,拼接键不会串味
 const KEY_SEP = "\u0000";
@@ -119,7 +120,9 @@ function isDimensionRef(dimension: DimensionInput): dimension is DimensionRef {
   return (
     typeof dimension === "object" &&
     "kind" in dimension &&
-    ((dimension as DimensionRef).kind === "flag" || (dimension as DimensionRef).kind === "runConfig")
+    ((dimension as DimensionRef).kind === "flag" ||
+      (dimension as DimensionRef).kind === "runConfig" ||
+      (dimension as DimensionRef).kind === "label")
   );
 }
 
@@ -147,9 +150,9 @@ export function refDisplayKey(value: unknown): [display: string, canonical: stri
 }
 
 function refValueOf(ref: DimensionRef, item: Item): unknown {
-  return ref.kind === "flag"
-    ? flagValueOf(item.attempt, ref.name)
-    : runConfigValueOf(item.attempt, ref.name as Parameters<typeof runConfigValueOf>[1]);
+  if (ref.kind === "flag") return flagValueOf(item.attempt, ref.name);
+  if (ref.kind === "label") return labelValueOf(item.attempt, ref.name);
+  return runConfigValueOf(item.attempt, ref.name as Parameters<typeof runConfigValueOf>[1]);
 }
 
 export function dimensionKey(dimension: DimensionInput, item: Item): string {
@@ -179,6 +182,25 @@ export function dimensionKey(dimension: DimensionInput, item: Item): string {
   }
 }
 
+/**
+ * series 类选项(SeriesInput)的复合维度解析:数组形态的维度 name 依声明顺序以 ` × ` 连接,
+ * 每个 attempt 的维度值为各成员显示键以 ` · ` 连接(缺失成员沿用 `(missing)` 显示键参与
+ * 连接,与单维度缺失同一条规则)。单维度形态与 dimensionName / dimensionKey 严格等价。
+ */
+export function seriesMembers(series: SeriesInput): readonly DimensionInput[] {
+  return Array.isArray(series) ? (series as readonly DimensionInput[]) : [series as DimensionInput];
+}
+
+export function seriesName(series: SeriesInput): string {
+  return seriesMembers(series).map(dimensionName).join(" × ");
+}
+
+export function seriesKey(series: SeriesInput, item: Item): string {
+  return seriesMembers(series)
+    .map((member) => dimensionKey(member, item))
+    .join(" · ");
+}
+
 /**
  * 按维度分组;维度 domain 按稳定 key 字典序(Unicode)排列,不让文件扫描顺序渗进报告。
  * flag / runConfig 维度做显示键冲突检测:不同原始值生成同一显示键时报错并要求改用

package/src/report/{flag.ts → model/flag.ts}

@@ -4,7 +4,7 @@
 // flag() 只读 `ExperimentDef.flags` 里显式声明的 KV;model / reasoningEffort / budget / runs
 // 这类顶层运行配置不在 flags 里,用 runConfig() 读快照的 ExperimentRunInfo 投影。
 
-import type { AttemptHandle } from "../results/types.ts";
+import type { AttemptHandle } from "../../results/types.ts";
 import type {
   DimensionOptions,
   DimensionRef,
@@ -20,6 +20,12 @@ export function flagValueOf(attempt: AttemptHandle, name: string): unknown {
   return info?.flags?.[name];
 }
 
+/** experiment 声明的报告归类标注 labels(同 flags 的读取回退链;值域 string | number)。 */
+export function labelValueOf(attempt: AttemptHandle, name: string): unknown {
+  const info = attempt.snapshot?.experiment ?? attempt.result.experiment;
+  return info?.labels?.[name];
+}
+
 /**
  * runConfig() 的取值:读快照的 `ExperimentRunInfo` 投影,外加桥接到快照顶层权威字段的
  * `model` / `agent` 两个键(与 "model" / "agent" 内置维度同一读法,不另造第二套口径)。
@@ -54,6 +60,21 @@ export function flag(name: string, options?: DimensionOptions): DimensionRef {
   };
 }
 
+/**
+ * 把 experiment 声明的一个报告标注(`ExperimentDef.labels` 的键)当分组维度,与 {@link flag}
+ * 同一套用法。labels 是纯报告侧的归类坐标:不透传运行时、不参与可比性配置;报告不从
+ * experiment id 字符串猜语义,归类只认声明(docs/feature/experiments/library.md「labels」)。
+ */
+export function label(name: string, options?: DimensionOptions): DimensionRef {
+  assertName(name, "label", "the key declared in the experiment's labels");
+  return {
+    kind: "label",
+    name,
+    ...(options?.label !== undefined ? { label: options.label } : {}),
+    ...(options?.unit !== undefined ? { unit: options.unit } : {}),
+  };
+}
+
 /**
  * 把一项顶层运行配置当分组维度,与 {@link flag} 同一套用法。读快照的 `ExperimentRunInfo`
  * 投影;可用键由 RunConfigKey 在类型层穷尽(那张接口的字段全集,外加桥接到快照顶层权威
@@ -86,6 +107,23 @@ export function numericFlag(name: string, options?: NumericAxisOptions): Numeric
   };
 }
 
+/**
+ * MetricLine 的 x 轴:只接受 number 值的 label。labels 由作者亲手声明,要数值轴就直接
+ * 声明成 number,不设 map;字符串值返回 null(折线不绘该点并报告缺失)。
+ */
+export function numericLabel(name: string, options?: NumericAxisOptions): NumericAxis {
+  assertName(name, "numericLabel", "the key declared in the experiment's labels");
+  return {
+    name,
+    ...(options?.label !== undefined ? { label: options.label } : {}),
+    ...(options?.unit !== undefined ? { unit: options.unit } : {}),
+    of(attempt) {
+      const value = labelValueOf(attempt, name);
+      return typeof value === "number" && Number.isFinite(value) ? value : null;
+    },
+  };
+}
+
 /**
  * 顶层运行配置作数值轴:数值配置直接返回该值;字符串配置必须显式给 `map`
  * (如 { low: 1, medium: 2, high: 3 })。未声明、未投影、非数值或未命中 map 的值返回 null。

package/src/report/{format.ts → model/format.ts}

@@ -2,21 +2,45 @@
 //   "%" → 87%    "ms" → 1.2s    "$" → $0.31    其余 → 1.2k 缩写(带 unit 后缀)
 // metric.display 可整体覆盖;这里只负责默认。
 
-import type { Verdict } from "../types.ts";
+import type { Verdict } from "../../types.ts";
 import { DISPLAY_LOCALES, type LocalizedText, type ReportLocale } from "./locale.ts";
 
 /**
- * experiment 行的显示名：给了父路径 `relativeTo` 且它确是前缀，就去掉 `relativeTo + "/"`，
- * 只留 id 末段——用在已经以组为标题的上下文（如默认 `ExperimentComparison` 的每组面板）里，
- * 避免每行重复文件夹名。组键就是 experiment id 的父目录，因此这里的末段与 `MetricScatter`
- * 点标签取的末段同源。不给 `relativeTo`、或它不是前缀（如根目录单例组）时原样返回完整 id。
- * 完整 id 仍是排序 / 着色 / 折叠的键，调用方不要拿这个显示名当身份用。
+ * 一组 id 的显示名：每个 id 缩成在这组里唯一的最短路径后缀，重名逐步加长到能区分为止
+ * （与 `MetricScatter` 点标签同一算法，两处共用本函数以保证同一份 experiment id 在散点和
+ * 列表里缩成同一个显示名）。单个 id、或所有 id 深度不同时也照常缩到各自的最短唯一后缀。
+ * 完整 id 不受影响，调用方仍用它做排序 / 过滤 / 折叠的身份键，这里只产出显示名。
  */
-export function experimentDisplayName(experimentId: string, relativeTo?: string): string {
-  if (relativeTo && experimentId.startsWith(`${relativeTo}/`)) {
-    return experimentId.slice(relativeTo.length + 1);
+export function shortestUniqueLabels(ids: readonly string[]): Map<string, string> {
+  const segsOf = (id: string) => id.split("/").filter(Boolean);
+  const depth = new Map<string, number>(ids.map((id) => [id, 1]));
+  for (;;) {
+    const byLabel = new Map<string, string[]>();
+    for (const id of ids) {
+      const segs = segsOf(id);
+      const label = segs.slice(-Math.min(depth.get(id)!, segs.length)).join("/") || id;
+      byLabel.set(label, [...(byLabel.get(label) ?? []), id]);
+    }
+    let grew = false;
+    for (const group of byLabel.values()) {
+      if (group.length < 2) continue;
+      for (const id of group) {
+        const segs = segsOf(id);
+        if (depth.get(id)! < segs.length) {
+          depth.set(id, depth.get(id)! + 1);
+          grew = true;
+        }
+      }
+    }
+    if (!grew) {
+      const out = new Map<string, string>();
+      for (const id of ids) {
+        const segs = segsOf(id);
+        out.set(id, segs.slice(-Math.min(depth.get(id)!, segs.length)).join("/") || id);
+      }
+      return out;
+    }
   }
-  return experimentId;
 }
 
 /** 一位小数、去掉无意义的 ".0" 尾巴。 */
@@ -104,6 +128,61 @@ export function formatPercent(ratio: number): string {
   return `${Math.round(ratio * 100)}%`;
 }
 
+type ReportDateTimeOptions = Intl.DateTimeFormatOptions;
+
+function formatReportDate(date: Date, locale: ReportLocale, options: ReportDateTimeOptions): string {
+  try {
+    return new Intl.DateTimeFormat(locale, options).format(date);
+  } catch {
+    return new Intl.DateTimeFormat("en", options).format(date);
+  }
+}
+
+const FULL_REPORT_DATE_TIME: ReportDateTimeOptions = {
+  year: "numeric",
+  month: "short",
+  day: "numeric",
+  hour: "2-digit",
+  minute: "2-digit",
+  hourCycle: "h23",
+};
+
+/** ISO 时间 → 本地化到分钟的短日期时间；不可解析时原样返回。 */
+export function formatReportDateTime(iso: string, locale: ReportLocale): string {
+  const date = new Date(iso);
+  return Number.isNaN(date.valueOf()) ? iso : formatReportDate(date, locale, FULL_REPORT_DATE_TIME);
+}
+
+/** 时间范围的两端；同日省略右侧日期，同年省略右侧年份，减少卡片中的重复噪音。 */
+export function formatReportDateTimeRange(
+  fromIso: string,
+  toIso: string,
+  locale: ReportLocale,
+): { from: string; to: string } {
+  const fromDate = new Date(fromIso);
+  const toDate = new Date(toIso);
+  if (Number.isNaN(fromDate.valueOf()) || Number.isNaN(toDate.valueOf())) {
+    return { from: formatReportDateTime(fromIso, locale), to: formatReportDateTime(toIso, locale) };
+  }
+  const sameYear = fromDate.getFullYear() === toDate.getFullYear();
+  const sameDay =
+    sameYear && fromDate.getMonth() === toDate.getMonth() && fromDate.getDate() === toDate.getDate();
+  const toOptions: ReportDateTimeOptions = sameDay
+    ? { hour: "2-digit", minute: "2-digit", hourCycle: "h23" }
+    : {
+        month: "short",
+        day: "numeric",
+        hour: "2-digit",
+        minute: "2-digit",
+        hourCycle: "h23",
+        ...(!sameYear && { year: "numeric" }),
+      };
+  return {
+    from: formatReportDate(fromDate, locale, FULL_REPORT_DATE_TIME),
+    to: formatReportDate(toDate, locale, toOptions),
+  };
+}
+
 // ── 实体列表(ExperimentList / EvalList / AttemptList)共用的判定符 ──
 
 /** passed / failed / errored / skipped 的判定符。 */