niceeval 0.9.1 → 0.10.2

package/src/report/web.ts

@@ -1,77 +0,0 @@
-// web 宿主(view --report)的装载入口:同一棵树走 web 面,renderToStaticMarkup 吐静态
-// HTML 烘进查看器的报告槽。只有这一侧真正 import react-dom(import 边界即运行时边界),
-// 所以本文件不从 niceeval/report 的入口 re-export —— 宿主与测试按源路径 import。
-
-import type { ReactNode } from "react";
-import { renderToStaticMarkup } from "react-dom/server";
-import type { AttemptLocator } from "../results/locator.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 { 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"。 */
-  locale?: ReportLocale;
-}
-
-/**
- * web 宿主的装载语义:选页 → resolve(组合展开 + spec 取数,唯一的 await 边界)→
- * 树校验(与 text 宿主同一遍)→ 静态渲染 web 面。宿主不在报告树外另设警告通道——
- * 挑选警告的呈现件是 `ScopeWarnings` 组件,内建报告每页都放它,自定义报告放不放是
- * 作者义务(docs/feature/reports/architecture.md「Scope 是计算入口」)。
- */
-export async function renderReportToStaticHtml(
-  definition: ReportDefinition,
-  ctx: ReportHostContext,
-  options?: StaticHtmlOptions,
-): Promise<string> {
-  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,
-  };
-  return runWithWebContext(webCtx, () => renderToStaticMarkup(resolved as ReactNode));
-}
-
-/**
- * 渲染一页报告树的 web 面(宿主逐页调用;页选择归宿主):resolve → validate → 静态渲染。
- * 挑选警告由页内的 `ScopeWarnings` 组件呈现,宿主不前置任何树外块。
- * 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(),
-  });
-  validateReportTree(resolved);
-  const webCtx: WebContext = {
-    attemptHref: options?.attemptHref ?? ((locator) => `#/attempt/${locator}`),
-    locale: options?.locale ?? DEFAULT_REPORT_LOCALE,
-  };
-  return runWithWebContext(webCtx, () => renderToStaticMarkup(resolved as ReactNode));
-}

package/src/show/report-host.test.ts

@@ -1,205 +0,0 @@
-// cases: docs/engineering/unit-tests/reports/cases.md
-// 「外壳、页面与 Tabs」——宿主装载规范化、页索引命令上下文与标题回退链
-// (契约:docs/feature/reports/library/shell.md)。
-// 页内树的 resolve / render 归报告库测试;这里只测宿主侧的规范化与选择逻辑(纯函数)。
-
-import { describe, expect, it } from "vitest";
-import {
-  BUILT_IN_PAGE_TITLE,
-  BUILT_IN_REPORT_TITLE,
-  HostReportError,
-  loadHostReport,
-  localizeText,
-  localizedTextEquals,
-  normalizeHostReport,
-  resolveReportTitle,
-  showCommand,
-} from "./report-host.ts";
-import { otherPagesText } from "./render.ts";
-// dist-sourced:裸宿主装载的就是这份预编译产物的默认导出(show 与 view 同一条路),
-// raw-src import 会是另一份模块实例,引用等同断言必须对着 dist。
-import distBuiltInReport from "../../dist/report/built-in/index.js";
-
-const tree = { kind: "node" }; // 页 content 对宿主是不透明值,规范化不解析树
-
-describe("裸宿主装载内建报告", () => {
-  it("缺省(无 --report)装载 niceeval/report/built-in 的默认导出:三页与其 content 同引用", async () => {
-    const host = await loadHostReport(process.cwd(), undefined);
-    const builtIn = distBuiltInReport as { pages: readonly { id: string; content: unknown }[] };
-    expect(host.pages.map((p) => p.id)).toEqual(["report", "attempts", "traces"]);
-    expect(builtIn.pages.map((p) => p.id)).toEqual(["report", "attempts", "traces"]);
-    for (let i = 0; i < host.pages.length; i++) {
-      expect(host.pages[i]!.content).toBe(builtIn.pages[i]!.content); // 同一份默认导出,不是复制品
-    }
-  });
-});
-
-describe("装载规范化:外壳 + 非空页列表", () => {
-  it("content 缩写展开为唯一页 id `report`,页名是内置页名「报告 / Report」", () => {
-    const report = normalizeHostReport({ kind: "report", content: tree }, "reports/frontier.tsx");
-    expect(report.pages).toHaveLength(1);
-    expect(report.pages[0]).toMatchObject({ id: "report", title: BUILT_IN_PAGE_TITLE, content: tree });
-    expect(report.links).toEqual([]);
-  });
-
-  it("pages 形态按声明序保留页列表与外壳字段", () => {
-    const report = normalizeHostReport(
-      {
-        kind: "report",
-        title: { en: "Memory Evals", "zh-CN": "记忆能力评测" },
-        links: [{ label: "GitHub", href: "https://example.com" }],
-        footer: "Published nightly.",
-        pages: [
-          { id: "overview", title: { en: "Overview", "zh-CN": "总览" }, content: tree },
-          { id: "exam", title: { en: "Exam", "zh-CN": "成绩单" }, content: tree },
-        ],
-      },
-      "reports/site.tsx",
-    );
-    expect(report.pages.map((p) => p.id)).toEqual(["overview", "exam"]);
-    expect(report.title).toEqual({ en: "Memory Evals", "zh-CN": "记忆能力评测" });
-    expect(report.footer).toBe("Published nightly.");
-  });
-
-  it("content 与 pages 恰好声明一个:同给 / 同缺都报错,文案给出 extends: standard 下一步", () => {
-    for (const bad of [
-      { kind: "report", content: tree, pages: [{ id: "a", title: "A", content: tree }] },
-      { kind: "report", title: "T" },
-    ]) {
-      expect(() => normalizeHostReport(bad, "reports/site.tsx")).toThrow(HostReportError);
-      expect(() => normalizeHostReport(bad, "reports/site.tsx")).toThrow(/niceeval\/report\/built-in/);
-    }
-  });
-
-  it("空 pages 列表 / 重复 page id / 非法 page id 在装载期报错", () => {
-    expect(() => normalizeHostReport({ kind: "report", pages: [] }, "r.tsx")).toThrow(/non-empty/);
-    expect(() =>
-      normalizeHostReport(
-        { kind: "report", pages: [{ id: "exam", title: "A", content: tree }, { id: "exam", title: "B", content: tree }] },
-        "r.tsx",
-      ),
-    ).toThrow(/duplicate page id "exam"/);
-    for (const id of ["Exam", "a/b"]) {
-      expect(() =>
-        normalizeHostReport({ kind: "report", pages: [{ id, title: "A", content: tree }] }, "r.tsx"),
-      ).toThrow(/invalid/);
-    }
-  });
-
-  it("默认导出不是 defineReport 产物:完整用户反馈", () => {
-    expect(() => normalizeHostReport({ some: "object" }, "reports/bad.tsx")).toThrow(
-      /does not default-export a report/,
-    );
-  });
-
-  it("ReportLink.icon 是 { svg: string }:合法形状原样透传;无类型 JS 传其它形状装载报错", () => {
-    const svg = '<svg viewBox="0 0 16 16"><path d="M0 0h16v16z"/></svg>';
-    const report = normalizeHostReport(
-      { kind: "report", content: tree, links: [{ label: "GitHub", href: "https://example.com", icon: { svg } }] },
-      "reports/site.tsx",
-    );
-    expect(report.links[0]!.icon).toEqual({ svg });
-
-    // ReactNode / 组件 / 裸字符串都不是 { svg: string },装载期以完整用户反馈拒绝。
-    const reactNode = { $$typeof: Symbol.for("react.transitional.element"), type: "svg", props: {} };
-    for (const icon of [reactNode, "<svg/>", { svg: 42 }, { svg: "" }]) {
-      expect(() =>
-        normalizeHostReport(
-          { kind: "report", content: tree, links: [{ label: "GitHub", href: "https://example.com", icon }] },
-          "reports/site.tsx",
-        ),
-      ).toThrow(/icon" must be \{ svg: string \}/);
-    }
-  });
-
-  it("旧 build 函数形态(集成前桥接)恒为单页 report", () => {
-    const legacy = { build: () => tree };
-    const report = normalizeHostReport(legacy, "the built-in report");
-    expect(report.pages.map((p) => p.id)).toEqual(["report"]);
-    expect(report.pages[0]!.content).toBe(legacy);
-  });
-});
-
-describe("标题回退链:def.title → 唯一且相同的快照 name → 内置文案「Eval 运行结果 / Eval Results」", () => {
-  it("def.title 优先", () => {
-    expect(resolveReportTitle({ en: "T" }, [{ name: "S" }])).toEqual({ en: "T" });
-  });
-
-  it("无 def.title 时取 Scope 中唯一且相同(深相等,键顺序无关)的非空快照 name", () => {
-    expect(resolveReportTitle(undefined, [{ name: { en: "S", "zh-CN": "斯" } }, { name: { "zh-CN": "斯", en: "S" } }]))
-      .toEqual({ en: "S", "zh-CN": "斯" });
-    expect(resolveReportTitle(undefined, [{}, { name: "Only" }])).toBe("Only");
-  });
-
-  it("多个不同 name(en 相同、zh-CN 不同也算不同)不随机挑,落内置文案;全无 name 亦然", () => {
-    expect(
-      resolveReportTitle(undefined, [{ name: { en: "S", "zh-CN": "甲" } }, { name: { en: "S", "zh-CN": "乙" } }]),
-    ).toEqual(BUILT_IN_REPORT_TITLE);
-    expect(resolveReportTitle(undefined, [{}, {}])).toEqual(BUILT_IN_REPORT_TITLE);
-    expect(resolveReportTitle("", [])).toEqual(BUILT_IN_REPORT_TITLE); // 空串标题不算声明
-    // 链终点是内置文案(shell.md),不是产品名——品牌位固定 NiceEval,不吃标题。
-    expect(BUILT_IN_REPORT_TITLE).toEqual({ en: "Eval Results", "zh-CN": "Eval 运行结果" });
-  });
-
-  it("LocalizedText 深相等按字段值,不看键顺序", () => {
-    expect(localizedTextEquals({ a: "1", b: "2" }, { b: "2", a: "1" })).toBe(true);
-    expect(localizedTextEquals({ a: "1" }, { a: "1", b: "2" })).toBe(false);
-  });
-});
-
-describe("LocalizedText 回退:locale → en → 键字典序第一个非空值", () => {
-  it("三级回退各自命中", () => {
-    expect(localizeText({ "zh-CN": "中", en: "E" }, "zh-CN")).toBe("中");
-    expect(localizeText({ "zh-CN": "中", en: "E" }, "fr")).toBe("E");
-    expect(localizeText({ "zh-TW": "繁", ja: "日" }, "en")).toBe("日"); // ja < zh-TW 字典序
-    expect(localizeText("plain", "en")).toBe("plain");
-    expect(localizeText({}, "en")).toBeUndefined();
-  });
-});
-
-describe("其余页索引与索引命令上下文", () => {
-  const report = normalizeHostReport(
-    {
-      kind: "report",
-      title: { en: "Memory Evals", "zh-CN": "记忆能力评测" },
-      links: [{ label: "GitHub", href: "https://example.com", icon: { svg: "<svg data-mark></svg>" } }],
-      pages: [
-        { id: "overview", title: { en: "Overview", "zh-CN": "总览" }, content: tree },
-        { id: "exam", title: { en: "Exam", "zh-CN": "成绩单" }, content: tree },
-      ],
-    },
-    "reports/site.tsx",
-  );
-
-  it("只列未渲染的页,索引命令保留当前 --results / --report 与位置参数,复制即可复现下一层视图", () => {
-    // 渲染的是 overview,其余页索引只含 exam 一行——与「渲染初始页 + 尾部附其余页索引」
-    // 的新行为一致(docs/feature/reports/show/reports.md Case 2)。
-    const text = otherPagesText({
-      otherPages: report.pages.filter((p) => p.id !== "overview").map((p) => ({ id: p.id, title: p.title })),
-      command: { patterns: [], results: "tmp/published-results", report: "reports/site.tsx" },
-      locale: "zh-CN",
-    });
-    expect(text).toContain("其余页：");
-    expect(text).toContain("niceeval show --results tmp/published-results --report reports/site.tsx --page exam");
-    expect(text).toContain("成绩单");
-    expect(text).not.toContain("总览");
-    expect(text).not.toContain("--page overview");
-  });
-
-  it("show 不消费 links:其余页索引不含 icon svg 与 href(icon 是 web 面属性)", () => {
-    const text = otherPagesText({
-      otherPages: report.pages.filter((p) => p.id !== "overview").map((p) => ({ id: p.id, title: p.title })),
-      command: { patterns: [] },
-      locale: "en",
-    });
-    expect(text).toContain("Other pages:");
-    expect(text).not.toContain("<svg");
-    expect(text).not.toContain("https://example.com");
-  });
-
-  it("showCommand 按序携带位置参数与 --exp / --results / --report / --page", () => {
-    expect(
-      showCommand({ patterns: ["memory/swelancer"], experiment: "dev-e2b", report: "reports/site.tsx", page: "exam" }),
-    ).toBe("niceeval show memory/swelancer --exp dev-e2b --report reports/site.tsx --page exam");
-  });
-});

package/src/show/report-host.ts

@@ -1,389 +0,0 @@
-// 报告装载的宿主联系面:show 与 view 共用(view 从这里 import;两个宿主对同一份
-// defineReport 产物必须得到同一个规范化结果,见 docs/feature/reports/library/shell.md)。
-//
-// 契约(docs/feature/reports/library/shell.md「行为约束」/ architecture.md「外壳与页:装载规范化」):
-// - `--report` 文件默认导出恒为 defineReport 产物;裸宿主装载 `niceeval/report/built-in` 的默认导出,
-//   走同一条「装载 → resolve → validate → render」管线。
-// - 装载规范化唯一产物是「外壳 + 非空页列表」:`defineReport(树)` ≡ `{ content: 树 }` ≡
-//   `pages: [{ id: "report", title: 内置页名, content: 树 }]`。
-// - 标题回退单点:def.title → Scope 中唯一且相同(LocalizedText 深相等)的非空快照 name →
-//   内置文案「Eval 运行结果 / Eval Results」。宿主落点是浏览器标题与 show 页索引标题行;
-//   页内 hero 标题由 Hero 组件消费同一取值链(ctx.report.title),宿主页头无品牌位。
-// - LocalizedText 回退:当前 locale → en → 按 locale 键字典序的第一个非空值。
-//
-// ⚠ 集成状态:src/report/** 正被并行重写(plan/reports-redesign-implementation.md)。这里把宿主
-// 需要的新报告 runtime API 收敛成唯一联系面,并对「新 dist 尚未产出」提供旧 API 桥接
-// (旧 ReportDefinition 是 build 函数形态,恒为单页)。集成阶段的对接点(搜索 INTEGRATION):
-//   1. `dist/report/built-in/index.js` 默认导出(内建报告入口;恒为新格式,无桥接——
-//      它随本包源码一起构建,不存在旧产物)。
-//   2. `normalizeReport(definition)`:装载规范化(外壳 + 非空页列表);旧桥接对 build 形态自行包单页。
-//   3. `renderReportTreeToText(tree, ctx, options)` / `renderReportTreeToStaticHtml(tree, ctx, options)`:
-//      逐页渲染入口(ctx = { scope, results, report });旧桥接调 renderReportToText /
-//      renderReportToStaticHtml(definition 整体)。
-
-import type { Results } from "../results/index.ts";
-import type { LocalizedText } from "../types.ts";
-
-/** 页:宿主寻址单位(`--page <id>` / `#/page/<id>`)。content 是报告树(旧桥接下是整个旧 definition)。 */
-export interface HostReportPage {
-  id: string;
-  title: LocalizedText;
-  content: unknown;
-}
-
-export interface HostReportLink {
-  label: LocalizedText;
-  href: string;
-  /**
-   * 可选内联 SVG 字标(shell.md「字段穷尽」):web 面渲染在 label 前,静态导出原样内联;
-   * 不收组件(外壳声明经 viewData 序列化边界);show 不消费。
-   */
-  icon?: { svg: string };
-}
-
-/** `{src}` 与 `{inline}` 两种形态不可同时出现(shell.md「字段穷尽」)。 */
-export type HostReportAsset = { src: string; inline?: never } | { inline: string; src?: never };
-
-/**
- * 结构化 head 标签(shell.md「字段穷尽」):白名单闭集(meta/link/script/style),
- * attrs 值 true 渲染裸布尔属性、字符串转义后渲染 `key="value"`;script/style 的
- * children 原样落进标签。形状与闭合序列在 defineReport 装载期已校验。
- */
-export type HostHeadTag =
-  | { tag: "meta" | "link"; attrs: Record<string, string | true>; children?: never }
-  | { tag: "script" | "style"; attrs?: Record<string, string | true>; children?: string };
-
-/** 装载规范化产物:外壳 + 非空页列表。show 只消费 title / pages;其余是 web 面属性。 */
-export interface HostReport {
-  title?: LocalizedText;
-  links: HostReportLink[];
-  footer?: LocalizedText;
-  head: HostHeadTag[];
-  scripts: HostReportAsset[];
-  styles: HostReportAsset[];
-  pages: HostReportPage[];
-}
-
-/** 单页缩写展开出的唯一页使用内置页名(shell.md:「报告 / Report」)。 */
-export const BUILT_IN_PAGE_TITLE: LocalizedText = { en: "Report", "zh-CN": "报告" };
-export const SINGLE_PAGE_ID = "report";
-
-/** 标题回退链的终点:内置文案「Eval 运行结果 / Eval Results」(shell.md「行为约束」)。 */
-export const BUILT_IN_REPORT_TITLE: LocalizedText = { en: "Eval Results", "zh-CN": "Eval 运行结果" };
-
-/** 规范化报告声明的只读注入(组合组件 ctx.report;ReportMeta,见 library/layout.md)。 */
-export interface HostReportMeta {
-  title: LocalizedText;
-  links: HostReportLink[];
-  footer?: LocalizedText;
-  pages: { id: string; title: LocalizedText }[];
-  pageId: string;
-}
-
-/** 可预期的装载用户错误(与 ReportLoadError 同待遇:打一句直说问题与下一步,不抛堆栈)。 */
-export class HostReportError extends Error {}
-
-// ───────────────────────── LocalizedText ─────────────────────────
-
-/**
- * LocalizedText 的确定回退(shell.md「行为约束」):当前 locale → en → 按 locale 键字典序的
- * 第一个非空值。对象没有任何非空值时返回 undefined(装载期应当已报错,渲染兜底不再抛)。
- */
-export function localizeText(text: LocalizedText | undefined, locale: string): string | undefined {
-  if (text === undefined) return undefined;
-  if (typeof text === "string") return text || undefined;
-  const exact = text[locale];
-  if (exact) return exact;
-  if (text.en) return text.en;
-  for (const key of Object.keys(text).sort()) {
-    if (text[key]) return text[key];
-  }
-  return undefined;
-}
-
-/** LocalizedText 深相等:按字段值比较,对象键顺序不影响结果(shell.md「标题回退必须确定」)。 */
-export function localizedTextEquals(a: LocalizedText, b: LocalizedText): boolean {
-  if (typeof a === "string" || typeof b === "string") return a === b;
-  const keysA = Object.keys(a).sort();
-  const keysB = Object.keys(b).sort();
-  if (keysA.length !== keysB.length) return false;
-  return keysA.every((key, i) => key === keysB[i] && a[key] === b[key]);
-}
-
-/** LocalizedText 是否有任何非空值(空串 / 全空对象都算空)。 */
-function hasText(text: LocalizedText | undefined): text is LocalizedText {
-  if (text === undefined) return false;
-  if (typeof text === "string") return text.length > 0;
-  return Object.values(text).some((v) => typeof v === "string" && v.length > 0);
-}
-
-/**
- * 标题回退单点(show 页索引标题与 view hero / 浏览器标题共用):def.title → Scope 中唯一且相同
- * (深相等)的非空快照 name → 内置文案「Eval 运行结果 / Eval Results」。多个不同 name 时
- * 不随机挑一个,直接落到内置文案。
- */
-export function resolveReportTitle(
-  defTitle: LocalizedText | undefined,
-  snapshots: readonly { name?: LocalizedText }[],
-): LocalizedText {
-  if (hasText(defTitle)) return defTitle;
-  let unique: LocalizedText | undefined;
-  for (const snapshot of snapshots) {
-    if (!hasText(snapshot.name)) continue;
-    if (unique === undefined) {
-      unique = snapshot.name;
-    } else if (!localizedTextEquals(unique, snapshot.name)) {
-      return BUILT_IN_REPORT_TITLE;
-    }
-  }
-  return unique ?? BUILT_IN_REPORT_TITLE;
-}
-
-/** 组合组件 ctx.report 的形状(走完回退链的 title;scripts / styles 不进)。 */
-export function reportMetaFor(
-  report: HostReport,
-  pageId: string,
-  snapshots: readonly { name?: LocalizedText }[],
-): HostReportMeta {
-  return {
-    title: resolveReportTitle(report.title, snapshots),
-    links: report.links,
-    ...(report.footer !== undefined ? { footer: report.footer } : {}),
-    pages: report.pages.map((p) => ({ id: p.id, title: p.title })),
-    pageId,
-  };
-}
-
-// ───────────────────────── 装载与规范化 ─────────────────────────
-
-/** 旧(集成前)ReportDefinition:build 函数形态,恒为单页。集成阶段删除。 */
-interface LegacyReportDefinition {
-  build: (ctx: unknown) => unknown;
-}
-
-function isLegacyDefinition(value: unknown): value is LegacyReportDefinition {
-  return (
-    (typeof value === "object" || typeof value === "function") &&
-    value !== null &&
-    typeof (value as Partial<LegacyReportDefinition>).build === "function"
-  );
-}
-
-const PAGE_ID_PATTERN = /^[a-z0-9-]+$/;
-
-/**
- * 装载期校验 `ReportLink.icon`(shell.md「字段穷尽」):唯一合法形状是 `{ svg: string }`。
- * 无类型 JS 传组件 / ReactNode / 裸字符串都在这里被完整用户反馈拒绝——外壳声明要过
- * viewData 的序列化边界,ReactNode 过不去,可序列化是外壳契约的一部分。
- */
-function assertLinkIcon(link: unknown, sourceLabel: string): void {
-  const icon = (link as { icon?: unknown })?.icon;
-  if (icon === undefined) return;
-  const svg = (icon as { svg?: unknown })?.svg;
-  if (typeof icon !== "object" || icon === null || typeof svg !== "string" || svg.length === 0) {
-    throw new HostReportError(
-      `${sourceLabel}: a link "icon" must be { svg: string } — an inline SVG string rendered before the label. ` +
-        "Components and React nodes are not accepted: the shell declaration crosses a serialization boundary. " +
-        'Write e.g. icon: { svg: "<svg …>…</svg>" }.',
-    );
-  }
-}
-
-/**
- * 装载规范化:把 defineReport 产物折成「外壳 + 非空页列表」。三种入参写法
- * (树 / `content:` / `pages:`)展开成同一形状;page id 的唯一性与字符纪律在这里校验
- * (shell.md「校验分两期」的装载期部分)。
- */
-export function normalizeHostReport(definition: unknown, sourceLabel: string): HostReport {
-  // INTEGRATION(2):新 defineReport 产物(kind === "report")。规范化后的外壳与页列表
-  // 若由新报告 runtime 导出的 normalizeReport 承担,这里改为直接调它;当前按 docs 的
-  // 字段穷尽读取产物自带的声明。
-  if (typeof definition === "object" && definition !== null && (definition as { kind?: unknown }).kind === "report") {
-    const def = definition as {
-      title?: LocalizedText;
-      links?: HostReportLink[];
-      footer?: LocalizedText;
-      head?: HostHeadTag[];
-      scripts?: HostReportAsset[];
-      styles?: HostReportAsset[];
-      content?: unknown;
-      pages?: { id: string; title: LocalizedText; content: unknown }[];
-    };
-    const hasContent = def.content !== undefined;
-    const hasPages = def.pages !== undefined;
-    if (hasContent === hasPages) {
-      // content / pages 同缺或同给:装载期完整用户反馈(defineReport 产物恒已折叠,这里只拦
-      // 手搓 kind:"report" 的无类型输入),下一步指向内建视图的 extends 复用。
-      throw new HostReportError(
-        `${sourceLabel}: a report declares exactly one of "content" or "pages" — ` +
-          (hasContent ? "it declares both. " : "it declares neither. ") +
-          `To render the built-in report, write extends: standard (import { standard } from "niceeval/report/built-in").`,
-      );
-    }
-    const pages: HostReportPage[] = hasPages
-      ? def.pages!.map((p) => ({ id: p.id, title: p.title, content: p.content }))
-      : [{ id: SINGLE_PAGE_ID, title: BUILT_IN_PAGE_TITLE, content: def.content }];
-    if (pages.length === 0) {
-      throw new HostReportError(`${sourceLabel}: "pages" must be a non-empty list of report pages.`);
-    }
-    const seen = new Set<string>();
-    for (const page of pages) {
-      if (!PAGE_ID_PATTERN.test(page.id)) {
-        throw new HostReportError(
-          `${sourceLabel}: page id "${page.id}" is invalid. Page ids use lowercase letters, digits and hyphens.`,
-        );
-      }
-      if (seen.has(page.id)) {
-        throw new HostReportError(`${sourceLabel}: duplicate page id "${page.id}". Page ids must be unique per file.`);
-      }
-      seen.add(page.id);
-    }
-    for (const link of def.links ?? []) assertLinkIcon(link, sourceLabel);
-    return {
-      ...(def.title !== undefined ? { title: def.title } : {}),
-      links: def.links ?? [],
-      ...(def.footer !== undefined ? { footer: def.footer } : {}),
-      head: def.head ?? [],
-      scripts: def.scripts ?? [],
-      styles: def.styles ?? [],
-      pages,
-    };
-  }
-
-  // INTEGRATION(2) 桥接:旧 build 函数形态(集成前的 dist);恒为单页,无外壳字段。
-  if (isLegacyDefinition(definition)) {
-    return {
-      links: [],
-      head: [],
-      scripts: [],
-      styles: [],
-      pages: [{ id: SINGLE_PAGE_ID, title: BUILT_IN_PAGE_TITLE, content: definition }],
-    };
-  }
-
-  throw new HostReportError(
-    `${sourceLabel} does not default-export a report. Export default defineReport(<ExperimentComparison />) (or defineReport({ title, content })) from "niceeval/report".`,
-  );
-}
-
-/**
- * 装载宿主报告:`--report <file>` 走 loadReportFile;缺省(裸 show / 裸 view)装载内建报告的
- * 默认导出。两条路都进 normalizeHostReport,同一条装载管线。
- */
-export async function loadHostReport(
-  cwd: string,
-  reportPath: string | undefined,
-  options?: { freshImport?: boolean },
-): Promise<HostReport> {
-  if (reportPath !== undefined) {
-    const { loadReportFile } = await import("../../dist/report/load.js");
-    const definition = await loadReportFile(cwd, reportPath, options);
-    return normalizeHostReport(definition, reportPath);
-  }
-  return normalizeHostReport(await loadBuiltInDefinition(), "the built-in report");
-}
-
-/** 内建报告即 `niceeval/report/built-in` 的默认导出(dist 预编译产物,`prepare` 时构建)。 */
-async function loadBuiltInDefinition(): Promise<unknown> {
-  const mod = await import("../../dist/report/built-in/index.js");
-  return mod.default;
-}
-
-// ───────────────────────── 逐页渲染 ─────────────────────────
-
-export interface HostRenderContext {
-  /** 宿主按官方现刻水位挑好的 Scope(集成前类型名仍是 Selection;两者同物)。 */
-  scope: unknown;
-  results: Results;
-  report: HostReportMeta;
-}
-
-export interface HostTextRenderOptions {
-  width?: number;
-  locale?: string;
-  /**
-   * 索引命令的完整上下文(docs/feature/reports/show/reports.md:「索引命令携带完整上下文」):
-   * 组索引 / 页索引输出的每一条可复制命令都保留当前 --results / --report / --page 与位置参数。
-   * INTEGRATION(3):由新 text 面消费;旧桥接的 renderReportToText 不认识该字段,原样忽略。
-   */
-  commandContext?: HostCommandContext;
-}
-
-export interface HostCommandContext {
-  patterns: string[];
-  results?: string;
-  experiment?: string;
-  report?: string;
-  page?: string;
-}
-
-/** 按上下文拼一条可复制的 show 命令(页索引 / 组索引共用的携带规则)。 */
-export function showCommand(ctx: HostCommandContext, extra: string[] = []): string {
-  const parts = ["niceeval show", ...ctx.patterns];
-  if (ctx.experiment !== undefined) parts.push(`--exp ${ctx.experiment}`);
-  if (ctx.results !== undefined) parts.push(`--results ${ctx.results}`);
-  if (ctx.report !== undefined) parts.push(`--report ${ctx.report}`);
-  if (ctx.page !== undefined) parts.push(`--page ${ctx.page}`);
-  parts.push(...extra);
-  return parts.join(" ");
-}
-
-/**
- * 渲染一页的 text 面。INTEGRATION(3):新 runtime 的入口是
- * `renderReportTreeToText(tree, { scope, results, report }, options)`;旧桥接下 content 是
- * 整个旧 definition,调 renderReportToText(definition, { selection, results }, options)。
- */
-export async function renderHostPageText(
-  page: HostReportPage,
-  ctx: HostRenderContext,
-  options: HostTextRenderOptions,
-): Promise<string> {
-  const mod = (await import("../../dist/report/report.js")) as Record<string, unknown>;
-  const renderTree = mod.renderReportTreeToText as
-    | ((tree: unknown, ctx: HostRenderContext, options: HostTextRenderOptions) => Promise<string>)
-    | undefined;
-  if (typeof renderTree === "function" && !isLegacyDefinition(page.content)) {
-    return renderTree(page.content, ctx, options);
-  }
-  if (isLegacyDefinition(page.content)) {
-    const renderLegacy = mod.renderReportToText as (
-      definition: unknown,
-      ctx: { selection: unknown; results: Results },
-      options: { width?: number; locale?: string },
-    ) => Promise<string>;
-    return renderLegacy(
-      page.content,
-      { selection: ctx.scope, results: ctx.results },
-      { ...(options.width !== undefined ? { width: options.width } : {}), ...(options.locale !== undefined ? { locale: options.locale } : {}) },
-    );
-  }
-  throw new HostReportError(
-    "The installed report runtime cannot render this report page yet (renderReportTreeToText is missing). Rebuild dist/report with `pnpm run build:report`.",
-  );
-}
-
-/** 渲染一页的 web 面(静态 HTML)。INTEGRATION(3) 同上,web 侧入口在 dist/report/web.js。 */
-export async function renderHostPageHtml(
-  page: HostReportPage,
-  ctx: HostRenderContext,
-  options: { locale: string },
-): Promise<string> {
-  const mod = (await import("../../dist/report/web.js")) as Record<string, unknown>;
-  const renderTree = mod.renderReportTreeToStaticHtml as
-    | ((tree: unknown, ctx: HostRenderContext, options: { locale: string }) => Promise<string>)
-    | undefined;
-  if (typeof renderTree === "function" && !isLegacyDefinition(page.content)) {
-    return renderTree(page.content, ctx, options);
-  }
-  if (isLegacyDefinition(page.content)) {
-    const renderLegacy = mod.renderReportToStaticHtml as (
-      definition: unknown,
-      ctx: { selection: unknown; results: Results },
-      options: { locale: string },
-    ) => Promise<string>;
-    return renderLegacy(page.content, { selection: ctx.scope, results: ctx.results }, options);
-  }
-  throw new HostReportError(
-    "The installed report runtime cannot render this report page yet (renderReportTreeToStaticHtml is missing). Rebuild dist/report with `pnpm run build:report`.",
-  );
-}