niceeval 0.6.1 → 0.7.0

package/src/show/index.ts

@@ -1,17 +1,18 @@
-// niceeval show —— 终端宿主(行为规范:docs-site/zh/guides/viewing-results.mdx;
-// 宿主组合语义:docs/feature/reports/architecture.md「Selection 是计算入口」)。
+// niceeval show —— 终端宿主(行为规范:docs/feature/reports/show.md 与分篇;
+// 宿主组合语义:docs/feature/reports/architecture.md「Scope 是计算入口」)。
 //
 // 位置参数 = eval id 前缀,或 `@<locator>`(精确指名单个 attempt,见 results/locator.ts):
-//   裸跑 / 多 eval 前缀  默认 ExperimentComparison 的 text 面(单 eval 前缀仍进入详情)
+//   裸跑 / 多 eval 前缀  内建报告(niceeval/report/built-in 默认导出)的 text 面(单 eval 前缀仍进入详情)
 //   恰好一个 eval     单 eval 详情(attempt / 断言明细,宿主本体)
 //   @<locator>        精确 attempt:无证据 flag → 紧凑全景;带 flag → 对应证据切面
-//   --eval / --execution / --diff[=路径]   证据切面(宿主本体):出现即走证据室,不渲染报告槽
-//   --history        跨 run 时间轴(内置趋势视图),与 --report 互斥
-//   --report <文件>  整槽换成用户报告;位置前缀 / --run / --experiment 先收窄 Selection 再注入
-//   --run <目录>     结果根换成该目录;--experiment Selection 只留该实验
+//   --source / --execution / --diff[=路径]   证据切面(宿主本体):出现即走证据室,不渲染报告槽
+//   --history        执行时间轴(逐 experimentId + evalId 分节),与 --report 互斥
+//   --report <文件>  整槽换成用户报告;位置前缀 / --results / --experiment 先收窄 Scope 再注入
+//   --page <id>      多页报告选页;未命中列出可用页 id 按用法错误退出
+//   --results <目录>  结果根换成该目录;--experiment 让 Scope 只留该实验
 //
-// 数据全部走 niceeval/results 的读取面(openResults + 合成 Selection + loadAttemptEvidence),
-// 不自己爬目录；证据可用性只由 loadAttemptEvidence 在单 Attempt 页面计算。
+// 数据全部走 niceeval/results 的读取面(openResults + 合成 Scope + loadAttemptEvidence),
+// 不自己爬目录;证据可用性只由 loadAttemptEvidence 在单 Attempt 页面计算。
 
 import { existsSync } from "node:fs";
 import { join, resolve } from "node:path";
@@ -23,51 +24,62 @@ import {
   LocatorNotFoundError,
   MalformedLocatorError,
 } from "../results/index.ts";
-// report.ts / load.ts have no JSX of their own, but ReportDefinition / ReportLoadError must
-// come from the SAME module instance ExperimentComparison (built-ins, .tsx) is built
-// against — `unique symbol` branding and `instanceof` are keyed by declaration site, so a raw
-// src copy and the compiled dist copy of "the same" ReportDefinition are, to TypeScript and to
-// `instanceof`, two different types. The package-owned report runtime ships as precompiled
-// ESM (dist/report/**, built by `pnpm run build:report`, immune to a consumer's cwd/tsconfig
-// when niceeval is linked in — see tsconfig.report-build.json); show pulls all of it from
-// there, not just the .tsx-touching pieces.
-import { renderReportToText } from "../../dist/report/report.js";
-import { ExperimentComparison } from "../../dist/report/built-ins/index.js";
-import { ReportLoadError, loadReportFile } from "../../dist/report/load.js";
+// ReportLoadError must come from the SAME module instance the report runtime is built
+// against — `instanceof` is keyed by declaration site, so a raw src copy and the compiled
+// dist copy of "the same" class are two different types. The package-owned report runtime
+// ships as precompiled ESM (dist/report/**, built by `pnpm run build:report`); all report
+// loading/rendering goes through ./report-host.ts (the single contact surface with it).
+import { ReportLoadError } from "../../dist/report/load.js";
 import { detectLocale, t } from "../i18n/index.ts";
 import { foldEvalVerdict } from "../shared/verdict.ts";
 import { selectCurrentResults, filterExperiments } from "../results/select.ts";
-import { evalHistory, experimentHistory } from "./compose.ts";
+import { evalPrefixPredicate } from "../shared/aggregate.ts";
+import { attemptHistory } from "./compose.ts";
+import {
+  HostReportError,
+  loadHostReport,
+  localizeText,
+  reportMetaFor,
+  renderHostPageText,
+  resolveReportTitle,
+  type HostCommandContext,
+} from "./report-host.ts";
 import {
   attemptArtifactsPath,
   attemptEvidenceHeader,
+  attemptHistoryText,
   attemptIndexLine,
   attemptOverviewText,
   attemptsOfEval,
   diffText,
   evalDetailText,
-  evalHistoryText,
   evalSourceText,
   executionText,
-  experimentHistoryText,
+  pageIndexText,
+  timingText,
   pickDetailAttempt,
   skippedRunsText,
   verdictReasonLine,
 } from "./render.ts";
 
 export interface ShowFlags {
-  /** 该 attempt 运行时保存的 Eval 源码,断言标回源码行(证据切面)。 */
-  eval?: boolean;
+  /** --source:该 attempt 运行时保存的 Eval 源码,断言标回源码行(证据切面)。 */
+  source?: boolean;
   /** 该 attempt 的标准执行事件流 + OTel enrichment(证据切面)。 */
   execution?: boolean;
+  /** --timing:默认有界诊断投影；full 逐节点展开。boolean 仅供库调用兼容，等价 summary。 */
+  timing?: boolean | "summary" | "full";
   /** --diff(文件级摘要)。 */
   diff?: boolean;
   /** --diff=<路径>(单个文件的完整改动;路径必须 = 连写,位置参数永远留给 eval id 前缀)。 */
   diffPath?: string;
   history?: boolean;
   experiment?: string;
-  run?: string;
+  /** --results:结果根目录(某次快照根或 `copySnapshots` 产物)。 */
+  results?: string;
   report?: string;
+  /** --page:多页报告选页;未命中按用法错误退出并列出可用页 id。 */
+  page?: string;
 }
 
 /** 注入 IO 供测试;默认写 stdout/stderr、宽度取终端列数。 */
@@ -86,8 +98,8 @@ function clampWidth(columns: number | undefined): number {
   return Math.max(40, Math.min(columns as number, 160));
 }
 
-// --report 的装载移到中性模块(两个宿主共用),show 的导出面与错误行为不变。
-export { loadReportFile } from "../../dist/report/load.js";
+// --report 的装载与规范化住在 ./report-host.ts(两个宿主共用的唯一联系面)。
+export { loadHostReport, normalizeHostReport, resolveReportTitle, localizeText } from "./report-host.ts";
 
 export async function runShow(
   cwd: string,
@@ -106,7 +118,7 @@ export async function runShow(
     });
     return 0;
   } catch (e) {
-    if (e instanceof ShowError || e instanceof ReportLoadError) {
+    if (e instanceof ShowError || e instanceof ReportLoadError || e instanceof HostReportError) {
       err(e.message.endsWith("\n") ? e.message : `${e.message}\n`);
       return 1;
     }
@@ -120,15 +132,27 @@ async function show(
   flags: ShowFlags,
   io: { out: (s: string) => void; err: (s: string) => void; width: number; now: number },
 ): Promise<void> {
-  const evidence = flags.eval === true || flags.execution === true || flags.diff === true || flags.diffPath !== undefined;
+  const evidence =
+    flags.source === true ||
+    flags.execution === true ||
+    (flags.timing !== undefined && flags.timing !== false) ||
+    flags.diff === true ||
+    flags.diffPath !== undefined;
 
   // 组合语义矩阵(docs/feature/reports/show.md「选择结果范围」):--history 与 --report 互斥,先于任何 IO 报出来。
   if (flags.history && flags.report !== undefined) {
     throw new ShowError(t("cli.show.historyReportConflict"));
   }
 
-  const root = flags.run !== undefined ? resolve(cwd, flags.run) : join(cwd, ".niceeval");
-  if (flags.run !== undefined && !existsSync(root)) {
+  // --page 只在报告槽里有意义:证据切面 / 时间轴与它组合是用法矛盾,先于任何 IO 报出来。
+  if (flags.page !== undefined && (evidence || flags.history)) {
+    throw new ShowError(
+      `--page selects a report page and cannot be combined with ${flags.history ? "--history" : "evidence flags"}.\n`,
+    );
+  }
+
+  const root = flags.results !== undefined ? resolve(cwd, flags.results) : join(cwd, ".niceeval");
+  if (flags.results !== undefined && !existsSync(root)) {
     throw new ShowError(t("cli.show.runDirMissing", { dir: root }));
   }
 
@@ -142,7 +166,7 @@ async function show(
   // (`@` 打头对 eval id 天然无歧义,见 locator.ts),必须在下面的前缀匹配逻辑之前分流掉,
   // 不然 "@1x7f3q" 会被当成一个谁都匹配不到的 eval id 前缀,报「no eval match」这种文不对题的
   // 错误。这一步只解析并渲染出「当前 show 对单个已解析 attempt 能渲染的东西」(单 eval 详情 /
-  // 三个证据切面)——真正的 `--eval`/`--execution`/`--diff` 统一 attempt 全景是后续阶段。
+  // 三个证据切面)——真正的 `--source`/`--execution`/`--diff` 统一 attempt 全景是后续阶段。
   const locatorArg = patterns.find((p) => p.startsWith(ATTEMPT_LOCATOR_PREFIX));
   if (locatorArg !== undefined) {
     if (patterns.length !== 1) {
@@ -163,8 +187,14 @@ async function show(
     const artifactPath = attemptArtifactsPath(attempt, cwd);
     if (evidence) {
       const blocks: string[] = [];
-      if (flags.eval) blocks.push(evalSourceText(attemptEvidence, { header, artifactPath, width: io.width }));
+      if (flags.source) blocks.push(evalSourceText(attemptEvidence, { header, artifactPath, width: io.width }));
       if (flags.execution) blocks.push(executionText(attemptEvidence, { header, artifactPath, width: io.width }));
+      if (flags.timing) blocks.push(timingText(attemptEvidence, {
+        header,
+        artifactPath,
+        width: io.width,
+        mode: flags.timing === "full" ? "full" : "summary",
+      }));
       if (flags.diff || flags.diffPath !== undefined) {
         blocks.push(diffText({ header, diff: attemptEvidence.diff, artifactPath, file: flags.diffPath }));
       }
@@ -226,8 +256,14 @@ async function show(
     const header = attemptEvidenceHeader(attemptEvidence);
     const artifactPath = attemptArtifactsPath(picked, cwd);
     const blocks: string[] = [];
-    if (flags.eval) blocks.push(evalSourceText(attemptEvidence, { header, artifactPath, width: io.width }));
+    if (flags.source) blocks.push(evalSourceText(attemptEvidence, { header, artifactPath, width: io.width }));
     if (flags.execution) blocks.push(executionText(attemptEvidence, { header, artifactPath, width: io.width }));
+    if (flags.timing) blocks.push(timingText(attemptEvidence, {
+      header,
+      artifactPath,
+      width: io.width,
+      mode: flags.timing === "full" ? "full" : "summary",
+    }));
     if (flags.diff || flags.diffPath !== undefined) {
       blocks.push(diffText({ header, diff: attemptEvidence.diff, artifactPath, file: flags.diffPath }));
     }
@@ -235,30 +271,30 @@ async function show(
     return;
   }
 
-  // --history:内置趋势视图。时间轴只列真实执行 —— resume 携带的复印件不占行。
+  // --history:执行时间轴(docs/feature/reports/show.md「--history:一个 eval 的执行时间轴」)。
+  // 对 Scope 中匹配的每个 experimentId + evalId 分节,逐 attempt 而非逐快照;时间轴只列
+  // 真实执行 —— resume 携带的复印件按 attempt 身份键去重后不占行。
   if (flags.history) {
     const experiments = filterExperiments(results.experiments, flags.experiment);
+    // eval 位置参数与 Scope 选择用同一个前缀谓词(单点在 shared/aggregate.ts),不另立口径。
+    const matchesPattern = patterns.length > 0 ? evalPrefixPredicate(patterns) : () => true;
     const blocks: string[] = [];
-    if (patterns.length === 0) {
-      for (const exp of experiments) blocks.push(experimentHistoryText(exp.id, experimentHistory(exp)));
-    } else {
-      const multi = matchedEvalIds.length > 1;
-      for (const evalId of matchedEvalIds) {
-        for (const exp of experiments) {
-          const rows = evalHistory(exp, evalId);
-          if (rows.length === 0) continue;
-          blocks.push(evalHistoryText({ experimentId: exp.id, ...(multi ? { evalId } : {}), rows }));
-        }
+    for (const exp of experiments) {
+      const evalIds = [...exp.evalIds].filter(matchesPattern).sort();
+      for (const evalId of evalIds) {
+        const rows = attemptHistory(exp, evalId);
+        if (rows.length === 0) continue;
+        blocks.push(attemptHistoryText({ experimentId: exp.id, evalId, rows }));
       }
     }
     io.out(blocks.join("\n\n") + "\n");
     return;
   }
 
-  // 单 eval 详情(宿主本体);--report 在场时报告槽优先,前缀只用来收窄 Selection。
+  // 单 eval 详情(宿主本体);--report / --page 在场时报告槽优先,前缀只用来收窄 Scope。
   // 挑哪个 attempt 展开明细不再收数字 --attempt——pickDetailAttempt 的默认启发式
   // (最新一次失败,没有失败挑最新一次)是唯一路径;精确选某一次走 `@<locator>`。
-  if (flags.report === undefined && patterns.length > 0 && matchedEvalIds.length === 1) {
+  if (flags.report === undefined && flags.page === undefined && patterns.length > 0 && matchedEvalIds.length === 1) {
     const evalId = matchedEvalIds[0];
     const attempts = attemptsOfEval(selection.snapshots, evalId);
     const detail = pickDetailAttempt(attempts);
@@ -275,13 +311,48 @@ async function show(
     return;
   }
 
-  // 裸 show 与裸 view 选择同一个普通默认 definition,这里只是渲染 text 面。
-  // --report 替换同一个报告槽。locale = CLI 界面语言(NICEEVAL_LANG / LC_* / LANG 检测):报告 chrome 文案跟随
-  // 终端语言(docs/feature/reports/library.md「locale:渲染面的语言」);Locale 与 ReportLocale 同为
-  // "en" | "zh-CN",直接传递。
-  const definition = flags.report === undefined ? ExperimentComparison : await loadReportFile(cwd, flags.report);
-  // attemptCommand 留给 renderReportToText 的默认值:AttemptLocator 已经是可直接 `niceeval show
-  // @<locator>` 的真实 CLI 语法,不需要再反查 eval id 拼一条近似命令(见 tree.ts 的默认实现)。
-  const text = await renderReportToText(definition, { selection, results }, { width: io.width, locale: detectLocale() });
+  // 报告槽:裸 show 装载 `niceeval/report/built-in` 的默认导出,--report 整槽替换——同一条
+  // 「装载 → 规范化(外壳 + 非空页列表)→ 逐页渲染」管线(docs/feature/reports/library/shell.md)。
+  // locale = CLI 界面语言(NICEEVAL_LANG / LC_* / LANG 检测):报告 chrome 文案跟随终端语言。
+  const report = await loadHostReport(cwd, flags.report);
+  const locale = detectLocale();
+  const commandContext: HostCommandContext = {
+    patterns,
+    ...(flags.results !== undefined ? { results: flags.results } : {}),
+    ...(flags.report !== undefined ? { report: flags.report } : {}),
+    ...(flags.experiment !== undefined ? { experiment: flags.experiment } : {}),
+  };
+  const sourceLabel = flags.report ?? "the built-in report";
+
+  let page = report.pages[0];
+  if (flags.page !== undefined) {
+    const hit = report.pages.find((p) => p.id === flags.page);
+    if (!hit) {
+      // 用法错误:列出可用页 id(docs/feature/reports/show/reports.md Case 1/2 的报错样例)。
+      throw new ShowError(
+        `error: page "${flags.page}" not found in ${sourceLabel}. Available pages: ${report.pages.map((p) => p.id).join(", ")}\n`,
+      );
+    }
+    page = hit;
+  } else if (report.pages.length > 1) {
+    // 多页未选页:只输出页索引与可复制的单页命令,不倾倒页内容(与可比组索引同一模式)。
+    // 标题行走标题回退链(终点是内置文案「Eval 运行结果 / Eval Results」,恒有值)。
+    const title = localizeText(resolveReportTitle(report.title, selection.snapshots), locale) ?? "Eval Results";
+    io.out(pageIndexText({ report, title, command: commandContext, locale }) + "\n");
+    return;
+  }
+
+  // attemptCommand 留给渲染管线的默认值:AttemptLocator 已经是可直接 `niceeval show @<locator>`
+  // 的真实 CLI 语法,不需要再反查 eval id 拼一条近似命令。
+  const meta = reportMetaFor(report, page.id, selection.snapshots);
+  const text = await renderHostPageText(
+    page,
+    { scope: selection, results, report: meta },
+    {
+      width: io.width,
+      locale,
+      commandContext: { ...commandContext, ...(flags.page !== undefined ? { page: flags.page } : {}) },
+    },
+  );
   io.out(text + "\n");
 }