niceeval 0.6.2 → 0.7.1

package/src/report/web.ts

@@ -6,12 +6,20 @@ import * as React from "react";
 import type { ReactNode } from "react";
 import { renderToStaticMarkup } from "react-dom/server";
 import type { AttemptLocator } from "../results/locator.ts";
-import type { SelectionWarning } from "../results/types.ts";
-import { resolveReportTree, runWithWebContext, validateReportTree, type WebContext } from "./tree.ts";
+import type { Scope } from "../results/types.ts";
+import {
+  resolveReportTree,
+  runWithWebContext,
+  validateReportTree,
+  ResolveMemo,
+  type WebContext,
+} from "./tree.ts";
 import { DEFAULT_REPORT_LOCALE, type ReportLocale } from "./locale.ts";
-import type { ReportContext, ReportDefinition } from "./report.ts";
+import { buildReportMeta, pickReportPage, type ReportDefinition, type ReportHostContext } from "./report.ts";
 
 export interface StaticHtmlOptions {
+  /** 渲染哪一页;缺省第一页。未命中抛 ReportPageNotFoundError。 */
+  pageId?: string;
   /** 证据室深链;缺省用 view 的 attempt 路由 `#/attempt/@<locator>`(单段、不透明)。 */
   attemptHref?: (locator: AttemptLocator) => string;
   /** 官方组件 chrome 文案的 locale;默认 "en"。 */
@@ -19,12 +27,12 @@ export interface StaticHtmlOptions {
 }
 
 /**
- * 挑选警告的 HTML 形态:宿主级前置块,与 RunOverview 里的警告用同一套结构和类名
- * (`.nre nre-report-warnings` 外壳内一个 `ul.nre-warnings` + `li.nre-warning[data-kind]`,
- * 复用 styles.css 已有的 `.nre .nre-warnings` 样式)。经 renderToStaticMarkup 走 React,
- * message 文本自动转义,不裸拼 HTML。裸跑 / --report 都在报告顶上如实报残缺,不静默。
+ * 挑选警告的 HTML 形态:宿主级前置块(`.nre nre-report-warnings` 外壳内一个
+ * `ul.nre-warnings` + `li.nre-warning[data-kind]`,复用 styles.css 已有样式)。
+ * 带 `command` 的警告把命令渲染为可复制块(`.nre-warning-command`);无 command 的
+ * 只显示 message,不硬造动作。经 renderToStaticMarkup 走 React,文本自动转义。
  */
-function renderSelectionWarningsHtml(warnings: SelectionWarning[]): string {
+function renderScopeWarningsHtml(scope: Scope): string {
   return renderToStaticMarkup(
     React.createElement(
       "div",
@@ -32,8 +40,15 @@ function renderSelectionWarningsHtml(warnings: SelectionWarning[]): string {
       React.createElement(
         "ul",
         { className: "nre-warnings" },
-        warnings.map((w, i) =>
-          React.createElement("li", { key: i, className: "nre-warning", "data-kind": w.kind }, w.message),
+        scope.warnings.map((w, i) =>
+          React.createElement(
+            "li",
+            { key: i, className: "nre-warning", "data-kind": w.kind },
+            w.message,
+            "command" in w && w.command
+              ? React.createElement("code", { className: "nre-warning-command", "data-nre-copy": w.command }, w.command)
+              : null,
+          ),
         ),
       ),
     ),
@@ -41,27 +56,55 @@ function renderSelectionWarningsHtml(warnings: SelectionWarning[]): string {
 }
 
 /**
- * build → 渲染前解析数据组件(唯一的 await 边界)→ 树校验(与 text 宿主同一遍)→ 静态渲染
- * web 面;Selection 有挑选警告时在报告顶部前置一块警告 HTML；报告树里的 RunOverview
- * 已经渲染同一条时不重复。
+ * web 宿主的装载语义:选页 → resolve(组合展开 + spec 取数,唯一的 await 边界)→
+ * 树校验(与 text 宿主同一遍)→ 静态渲染 web 面;Scope 有挑选警告时在报告顶部前置
+ * 一块警告 HTML(宿主是 warning 的唯一呈现者,组件数据不复制 warning)。
  */
 export async function renderReportToStaticHtml(
   definition: ReportDefinition,
-  ctx: ReportContext,
+  ctx: ReportHostContext,
   options?: StaticHtmlOptions,
 ): Promise<string> {
-  const node = await definition.build(ctx);
-  const resolved = await resolveReportTree(node);
+  const page = pickReportPage(definition, options?.pageId);
+  const meta = buildReportMeta(definition, ctx.scope, page.id);
+  const resolved = await resolveReportTree(page.content, {
+    scope: ctx.scope,
+    results: ctx.results,
+    report: meta,
+    memo: new ResolveMemo(),
+  });
   validateReportTree(resolved);
   const webCtx: WebContext = {
     attemptHref: options?.attemptHref ?? ((locator) => `#/attempt/${locator}`),
     locale: options?.locale ?? DEFAULT_REPORT_LOCALE,
   };
   const body = runWithWebContext(webCtx, () => renderToStaticMarkup(resolved as ReactNode));
-  const missingWarnings = ctx.selection.warnings.filter((warning) => {
-    const escapedMessage = renderToStaticMarkup(React.createElement(React.Fragment, null, warning.message));
-    return !body.includes(escapedMessage);
+  const warnings = ctx.scope.warnings.length > 0 ? renderScopeWarningsHtml(ctx.scope) : "";
+  return warnings + body;
+}
+
+/**
+ * 渲染一页报告树的 web 面(宿主逐页调用;页选择归宿主):resolve → validate → 静态渲染。
+ * Scope 有挑选警告时在页顶前置警告块(带 command 的警告渲染为可复制命令)——宿主是
+ * warning 的唯一呈现者,组件数据不复制 warning。ctx.report 是宿主规范化后的声明。
+ */
+export async function renderReportTreeToStaticHtml(
+  tree: import("./tree.ts").ReportNode,
+  ctx: { scope: Scope; results: import("../results/types.ts").Results; report: import("./report.ts").ReportMeta },
+  options?: { attemptHref?: (locator: AttemptLocator) => string; locale?: ReportLocale },
+): Promise<string> {
+  const resolved = await resolveReportTree(tree, {
+    scope: ctx.scope,
+    results: ctx.results,
+    report: ctx.report,
+    memo: new ResolveMemo(),
   });
-  const warnings = missingWarnings.length > 0 ? renderSelectionWarningsHtml(missingWarnings) : "";
+  validateReportTree(resolved);
+  const webCtx: WebContext = {
+    attemptHref: options?.attemptHref ?? ((locator) => `#/attempt/${locator}`),
+    locale: options?.locale ?? DEFAULT_REPORT_LOCALE,
+  };
+  const body = runWithWebContext(webCtx, () => renderToStaticMarkup(resolved as ReactNode));
+  const warnings = ctx.scope.warnings.length > 0 ? renderScopeWarningsHtml(ctx.scope) : "";
   return warnings + body;
 }

package/src/results/attempt-evidence.test.ts

@@ -70,7 +70,7 @@ async function seedAttempt(
 }
 
 describe("loadAttemptEvidence", () => {
-  it("四个 capability 全部具备:eval / execution / timing / diff", async () => {
+  it("四个 capability 全部具备:source / execution / timing / diff", async () => {
     const root = await makeRoot();
     const attempt = await seedAttempt(
       root,
@@ -90,10 +90,10 @@ describe("loadAttemptEvidence", () => {
     expect((actionNode as { span?: TraceSpan }).span).toBeDefined();
     expect(evidence.diff?.windows).toEqual(NONEMPTY_DIFF);
 
-    expect(evidence.capabilities).toEqual({ eval: true, execution: true, timing: true, diff: true });
+    expect(evidence.capabilities).toEqual({ source: true, execution: true, timing: true, diff: true });
   });
 
-  it("四个 capability 全部缺失:没有 source / events / trace / diff,不崩溃", async () => {
+  it("四个 capability 全部缺失:没有 sources / events / trace / diff,不崩溃", async () => {
     const root = await makeRoot();
     const attempt = await seedAttempt(root, { id: "weather/queens" });
 
@@ -102,7 +102,7 @@ describe("loadAttemptEvidence", () => {
     expect(evidence.evalSource).toBeNull();
     expect(evidence.execution).toBeNull();
     expect(evidence.diff).toBeNull();
-    expect(evidence.capabilities).toEqual({ eval: false, execution: false, timing: false, diff: false });
+    expect(evidence.capabilities).toEqual({ source: false, execution: false, timing: false, diff: false });
   });
 
   it("有 events 没有 phases(旧 runner 产出):execution 为真、timing 为假", async () => {

package/src/results/attempt-evidence.ts

@@ -12,7 +12,7 @@
 // "有什么可看"这件事产生同一个答案(没有),只是原因不同,原因留给 unavailable 文案区分,
 // 不留给 capability 位区分(capability 位只回答"要不要显示这个证据切面")。
 //
-//   eval      —— evalSource 非空 AND (至少有一行源码 或 至少有一条断言);理论上
+//   source    —— evalSource 非空 AND (至少有一行源码 或 至少有一条断言);理论上
 //                buildAnnotatedEvalSource 对空文件也会产出一行 ""(split("\n") 的自然结果),
 //                所以这条件实践中约等于"evalSource 非空",按文档口径原样写出两个子句,
 //                不依赖这个实现细节。
@@ -59,8 +59,8 @@ export interface EvidencePaths {
  * 对应的证据切面,不自己重新判断"这个 attempt 有没有 X"。
  */
 export interface AttemptEvidenceCapabilities {
-  /** evalSource 非空且有内容(源码行或断言二选一非空)。 */
-  eval: boolean;
+  /** evalSource 非空且有内容(源码行或断言二选一非空);对应 CLI 的 `--source` 证据切面。 */
+  source: boolean;
   /** events 非空数组——有骨架可看。 */
   execution: boolean;
   /** result.json 带 phases(阶段计时)——`--timing` 时间树可渲染。 */
@@ -79,7 +79,7 @@ export interface AttemptEvidence {
    * 的调用方直接读结构化字段(如按 experimentId 分组、按时间排序)。 */
   identity: AttemptIdentity;
   result: EvalResult;
-  /** 运行时保存的 Eval 源码标注(`--eval` 切面);没有 sources() 就是 null,不伪造空文档。 */
+  /** 运行时保存的 Eval 源码标注(`--source` 切面);没有 sources() 就是 null,不伪造空文档。 */
   evalSource: AnnotatedEvalSource | null;
   /** 标准事件流 + OTel enrichment(`--execution` 切面);没有非空 events 就是 null,
    * 不产出一棵只剩 telemetry-only 节点、没有真实骨架的误导性树(见头注 execution 门槛)。 */
@@ -144,7 +144,7 @@ export async function loadAttemptEvidence(attempt: AttemptHandle): Promise<Attem
     trace,
     artifactPaths: { dir: attemptArtifactDir(attempt) },
     capabilities: {
-      eval: evalCapable,
+      source: evalCapable,
       execution: execution !== null,
       timing: (attempt.result.phases?.length ?? 0) > 0,
       diff: diffCapable,

package/src/results/copy.ts

@@ -24,7 +24,7 @@ import {
   redactSpans,
   type Redactor,
 } from "./publish.ts";
-import type { ArtifactKind, AttemptHandle, Selection, Snapshot, SnapshotMeta } from "./types.ts";
+import type { ArtifactKind, AttemptHandle, Scope, Snapshot, SnapshotMeta } from "./types.ts";
 
 /** 缺省携带的 artifact:events / trace / o11y / agentSetup / sources;diff 不截断、可达百 MB,缺省不带。 */
 const DEFAULT_PUBLISH_ARTIFACTS: ArtifactKind[] = ["events", "trace", "o11y", "agentSetup", "sources"];
@@ -50,15 +50,15 @@ export interface CopySnapshotsResult {
 
 /**
  * 把选中快照复制成 `destDir` 下的一个标准结果根目录(`<experiment-dir>/<源快照目录名>/`,
- * 快照目录名原样保留,身份不变)。输入收 Selection 或手工挑的 Snapshot[]
+ * 快照目录名原样保留,身份不变)。输入收 Scope 或手工挑的 Snapshot[]
  * (与 Reports 计算函数同一输入约定)。目标目录非空即报错,不静默覆盖、不合并。
  */
 export async function copySnapshots(
-  selection: Selection | Snapshot[],
+  scope: Scope | readonly Snapshot[],
   destDir: string,
   opts: CopySnapshotsOptions,
 ): Promise<CopySnapshotsResult> {
-  const selected = Array.isArray(selection) ? selection : selection.snapshots;
+  const selected = Array.isArray(scope) ? (scope as readonly Snapshot[]) : (scope as Scope).snapshots;
   if (selected.length === 0) {
     throw new Error(
       "copySnapshots got no snapshots to copy. Check the experiments filter, or pass snapshots from openResults().latest().",
@@ -92,7 +92,7 @@ export async function copySnapshots(
       continue;
     }
     warnings.push(
-      `warning: multiple snapshots selected for experiment "${snapshot.experimentId}"; kept the newest one, dropped the rest. Dedupe with Selection.filter() or pick a single snapshot per experiment before copySnapshots to avoid this.`,
+      `warning: multiple snapshots selected for experiment "${snapshot.experimentId}"; kept the newest one, dropped the rest. Dedupe with Scope.filter() or pick a single snapshot per experiment before copySnapshots to avoid this.`,
     );
     if (isNewerSnapshot(snapshot, existing)) byExperiment.set(snapshot.experimentId, snapshot);
   }
@@ -101,7 +101,7 @@ export async function copySnapshots(
   // 超过 PUBLISH_FILE_MAX_BYTES 就整体失败,不留半成品目标目录。
   const planned: PlannedFile[] = [];
   for (const snapshot of byExperiment.values()) {
-    planned.push(...(await planOneSnapshot(snapshot, selected, dest, kinds, redactor)));
+    planned.push(...(await planOneSnapshot(snapshot, [...selected], dest, kinds, redactor)));
   }
   const oversized = planned.filter((f) => f.bytes.byteLength > PUBLISH_FILE_MAX_BYTES);
   if (oversized.length > 0) {

package/src/results/host-equivalence.test.ts

@@ -24,7 +24,7 @@ import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { openResults } from "./index.ts";
-import type { Selection, SelectionWarning } from "./index.ts";
+import type { Scope, ScopeWarning } from "./index.ts";
 import { selectCurrentResults, type ResultScope } from "./select.ts";
 import { RESULTS_FORMAT, RESULTS_SCHEMA_VERSION, type EvalResult, type Verdict } from "../types.ts";
 import { runShow, type ShowFlags } from "../show/index.ts";
@@ -132,7 +132,7 @@ interface NormSelection {
   experiments: NormExperiment[];
 }
 
-function normalizeWarning(w: SelectionWarning): NormWarning {
+function normalizeWarning(w: ScopeWarning): NormWarning {
   switch (w.kind) {
     case "partial-coverage":
       return { kind: w.kind, experimentId: w.experimentId, covered: w.covered, total: w.total };
@@ -144,7 +144,7 @@ function normalizeWarning(w: SelectionWarning): NormWarning {
   }
 }
 
-function normalizeSelection(selection: Selection): NormSelection {
+function normalizeSelection(selection: Scope): NormSelection {
   return {
     warnings: selection.warnings.map(normalizeWarning),
     experiments: selection.snapshots.map((snapshot) => ({
@@ -167,7 +167,7 @@ function normalizeSelection(selection: Selection): NormSelection {
 async function showText(root: string, patterns: string[], flags: ShowFlags = {}): Promise<string> {
   let out = "";
   let err = "";
-  const code = await runShow(root, patterns, { run: root, ...flags }, {
+  const code = await runShow(root, patterns, { results: root, ...flags }, {
     out: (s) => (out += s),
     err: (s) => (err += s),
     width: 120,
@@ -179,8 +179,8 @@ async function showText(root: string, patterns: string[], flags: ShowFlags = {})
 
 /** view 的 web 面:loadViewScan → 报告槽 HTML(en)。 */
 async function viewHtml(root: string, opts: ViewScanOptions = {}): Promise<string> {
-  const { reportHtml } = await loadViewScan(root, opts);
-  return reportHtml.en;
+  const { reportPages } = await loadViewScan(root, opts);
+  return reportPages.map((page) => page.html.en).join("\n");
 }
 
 /** 两个宿主构造给选择器的 scope 完全同形:验证读源无误,避免"我以为它们一样"。 */
@@ -453,20 +453,32 @@ describe("宿主接线 · show text 面与 view web 面反映同一批事实", (
     await writeFile(
       reportPath,
       [
+        "// 手搭新 defineReport 产物(kind + brand + 规范化页列表);组合组件从 ctx.scope 读注入范围。",
         'const FACES = Symbol.for("niceeval.report.faces");',
-        "const Echo = (props) => Echo[FACES].web(props);",
-        "Echo[FACES] = {",
+        'const COMPOSE = Symbol.for("niceeval.report.compose");',
+        "const Leaf = (props) => Leaf[FACES].web(props);",
+        "Leaf[FACES] = {",
         '  web: (props) => "EVALS[" + props.ids + "]",',
         '  text: (props) => "EVALS[" + props.ids + "]",',
         "};",
+        "const Echo = () => { throw new Error(\"compose only\"); };",
+        "Echo[COMPOSE] = (_props, ctx) => ({",
+        '  $$typeof: Symbol.for("react.transitional.element"),',
+        "  type: Leaf,",
+        '  props: { ids: ctx.scope.snapshots.flatMap((s) => s.evals.map((e) => e.id)).sort().join(",") },',
+        "  key: null,",
+        "});",
         "export default {",
+        '  kind: "report",',
         '  [Symbol.for("niceeval.report.definition")]: true,',
-        "  build: (ctx) => ({",
-        '    $$typeof: Symbol.for("react.transitional.element"),',
-        "    type: Echo,",
-        '    props: { ids: ctx.selection.snapshots.flatMap((s) => s.evals.map((e) => e.id)).sort().join(",") },',
-        "    key: null,",
-        "  }),",
+        "  links: [],",
+        "  scripts: [],",
+        "  styles: [],",
+        "  pages: [{",
+        '    id: "report",',
+        '    title: "Report",',
+        '    content: { $$typeof: Symbol.for("react.transitional.element"), type: Echo, props: {}, key: null },',
+        "  }],",
         "};",
         "",
       ].join("\n"),

package/src/results/index.ts

@@ -1,6 +1,6 @@
 // niceeval/results —— 实验结果数据的读写库(定稿见 docs/feature/results/library.md、docs/feature/results/architecture.md)。
 //
-// 读:openResults(实验 → 快照 → eval → attempt 分层、skipped、latest() Selection);
+// 读:openResults(实验 → 快照 → eval → attempt 分层、skipped、latest() / current() Scope);
 // 写:createResultsWriter(快照声明 + attempt 增量落盘 + finish 补 completedAt);
 // 发布:copySnapshots(格式感知复制 + knownEvalIds 补记);
 // 身份:dedupeAttempts(跨快照聚合前按 (experimentId, evalId, attempt, startedAt) 去重)、isNewerSnapshot。
@@ -44,7 +44,13 @@ export {
 } from "./attempt-evidence.ts";
 export { hashEvalSource, normalizeEvalSource } from "./source-hash.ts";
 export { groupIncompatibleVersionSkips, type SkippedVersionGroup } from "./skipped-notice.ts";
-export { dedupeAttempts, isNewerSnapshot } from "./select.ts";
+export {
+  comparabilityConfigOf,
+  dedupeAttempts,
+  deepEqualJson,
+  isNewerSnapshot,
+  type ComparabilityConfig,
+} from "./select.ts";
 export { copySnapshots, type CopySnapshotsOptions, type CopySnapshotsResult } from "./copy.ts";
 export {
   createResultsWriter,
@@ -73,8 +79,8 @@ export {
   type Eval,
   type Experiment,
   type Results,
-  type Selection,
-  type SelectionWarning,
+  type Scope,
+  type ScopeWarning,
   type SkippedDir,
   type Snapshot,
   type SnapshotMeta,

package/src/results/open.ts

@@ -13,7 +13,7 @@ import type { O11ySummary, StreamEvent, TraceSpan } from "../types.ts";
 import type { AgentSetupManifest, DiffData, SourceArtifact } from "../types.ts";
 import { deriveDiffData } from "../scoring/diff.ts";
 import { RESULT_FILE, SNAPSHOT_FILE, artifactFileOf, classifySnapshot } from "./format.ts";
-import { isNewerSnapshot, selectLatest } from "./select.ts";
+import { isNewerSnapshot, selectCurrentResults, selectLatest } from "./select.ts";
 import {
   encodeAttemptLocator,
   resolveAttemptLocator,
@@ -27,7 +27,7 @@ import type {
   Eval,
   Experiment,
   Results,
-  Selection,
+  Scope,
   SkippedDir,
   Snapshot,
   SnapshotMeta,
@@ -171,13 +171,17 @@ export async function openResults(dir: string): Promise<Results> {
 }
 
 function makeResults(experiments: Experiment[], skipped: SkippedDir[]): Results {
-  return {
+  const results: Results = {
     experiments,
     skipped,
-    latest(opts?: { experiments?: string | string[] }): Selection {
+    latest(opts?: { experiments?: string | string[] }): Scope {
       return selectLatest(experiments, opts);
     },
+    current(opts?: { experiments?: string | string[] }): Scope {
+      return selectCurrentResults(results, { experiment: opts?.experiments });
+    },
   };
+  return results;
 }
 
 // ───────────────────────── 目录扫描 ─────────────────────────

package/src/results/results.test.ts

@@ -343,7 +343,7 @@ describe("results.latest() · Selection", () => {
     const stale = latest.warnings.filter((w) => w.kind === "stale-snapshot");
     expect(stale).toHaveLength(1);
     expect(stale[0]).toMatchObject({ experimentId: "mid/a", startedAt: "2026-07-01T08:00:00.000Z", latestStartedAt: "2026-07-05T08:00:00.000Z" });
-    expect(stale[0].message).toContain("predates the latest run in this selection by 4 days");
+    expect(stale[0].message).toContain("predates the latest run in this scope by 4 days");
   });
 
   it("unfinished-snapshot:选中快照缺 completedAt", async () => {
@@ -976,8 +976,9 @@ describe("AttemptLocator · 落盘 / 读取 / 携带 / 撞车", () => {
     const handMadeResults: Results = {
       experiments: [{ id: "e", snapshots: [snapshot], latest: snapshot, evalIds: ["q1"] }],
       skipped: [],
-      // filter() 本测试不调用,用不到,给个占位实现即可满足 Selection 接口。
-      latest: () => ({ snapshots: [snapshot], warnings: [], filter: () => { throw new Error("not implemented"); } }),
+      // filter() 本测试不调用,用不到,给个占位实现即可满足 Scope 接口。
+      latest: () => ({ mode: "latest-snapshots" as const, snapshots: [snapshot], attempts: snapshot.attempts, warnings: [], filter: () => { throw new Error("not implemented"); } }),
+      current: () => { throw new Error("not implemented"); },
     };
     // 这份 locator 语法合法、甚至真的对应 handMadeResults 里那个 attempt 的身份,
     // 但 handMadeResults 没经过 openResults(),locatorIndexByResults 里查不到它 —— 空索引,not-found。