niceeval 0.9.1 → 0.10.2

package/src/report/components/site-components/validate.test.ts

@@ -0,0 +1,89 @@
+// cases: docs/engineering/unit-tests/reports/cases.md
+// "validate*Data 递归覆盖到嵌套字段" 行:site-components 四个 validate*Data 的表驱动字段突变覆盖,重点是 ScopeWarning 的四个已登记
+// kind 各自的必填字段,以及未登记 kind 的前向兼容放行路径(与 ScopeWarnings 组件的「未知 kind
+// 单独成组」渲染回退是同一条契约,结构校验不能比渲染逻辑更严)。
+
+import { describe, expect, it } from "vitest";
+import { validateCopyFixPromptData, validateHeroData, validateScopeWarningsData, validateTraceWaterfallData } from "./index.tsx";
+
+describe("validateHeroData", () => {
+  it("合规 literal 通过,latestStartedAt 为 null 合法(空范围不编造当前时间)", () => {
+    expect(validateHeroData({ latestStartedAt: null, snapshots: 0 })).toBeNull();
+  });
+
+  it("snapshots 非数字报错", () => {
+    expect(validateHeroData({ latestStartedAt: null, snapshots: "0" })).toMatch(/"snapshots"/);
+  });
+});
+
+describe("validateScopeWarningsData — ScopeWarning 判别联合", () => {
+  it("partial-coverage 缺 covered 报错", () => {
+    const bad = [{ kind: "partial-coverage", experimentId: "exp/a", total: 6, message: "m", command: "niceeval exp exp/a" }];
+    expect(validateScopeWarningsData(bad)).toMatch(/"data\[0\]\.covered"/);
+  });
+
+  it("stale-snapshot 缺 latestStartedAt 报错", () => {
+    const bad = [{ kind: "stale-snapshot", experimentId: "exp/a", startedAt: "t1", message: "m", command: "c" }];
+    expect(validateScopeWarningsData(bad)).toMatch(/"data\[0\]\.latestStartedAt"/);
+  });
+
+  it("unfinished-snapshot 缺 dir 报错", () => {
+    const bad = [{ kind: "unfinished-snapshot", experimentId: "exp/a", startedAt: "t1", message: "m", command: "c" }];
+    expect(validateScopeWarningsData(bad)).toMatch(/"data\[0\]\.dir"/);
+  });
+
+  it("unreadable-snapshot 的 reason 不在三态枚举内报错;没有 experimentId 字段本身合法(非实验作用域)", () => {
+    const bad = [{ kind: "unreadable-snapshot", dir: "/r/snap", reason: "corrupted", message: "m" }];
+    expect(validateScopeWarningsData(bad)).toMatch(/"data\[0\]\.reason"/);
+    const ok = [{ kind: "unreadable-snapshot", dir: "/r/snap", reason: "malformed", message: "m" }];
+    expect(validateScopeWarningsData(ok)).toBeNull();
+  });
+
+  it("unreadable-snapshot 省略 command 合法(不是每个 reason 都有单条命令)", () => {
+    const ok = [{ kind: "unreadable-snapshot", dir: "/r/snap", reason: "incomplete", message: "m" }];
+    expect(validateScopeWarningsData(ok)).toBeNull();
+  });
+
+  it("未登记的 kind 只要有 kind/message 就放行——前向兼容,不拒绝未来版本产出的新 kind", () => {
+    const future = [{ kind: "future-kind", message: "something new happened" }];
+    expect(validateScopeWarningsData(future)).toBeNull();
+  });
+
+  it("未登记的 kind 缺 message 仍报错(两族共用的最小形状)", () => {
+    const bad = [{ kind: "future-kind" }];
+    expect(validateScopeWarningsData(bad)).toMatch(/"data\[0\]\.message"/);
+  });
+});
+
+describe("validateCopyFixPromptData", () => {
+  it("合规 literal 通过", () => {
+    expect(validateCopyFixPromptData({ prompt: "fix it", failures: 1 })).toBeNull();
+  });
+
+  it("failures 非数字报错", () => {
+    expect(validateCopyFixPromptData({ prompt: "x", failures: "1" })).toMatch(/"failures"/);
+  });
+});
+
+describe("validateTraceWaterfallData", () => {
+  const validSpan = { name: "turn", kind: "agent", startOffsetMs: 0, durationMs: 100, failed: false };
+  const valid = [{ experimentId: "exp/a", evalId: "q1", locator: "@1abcdef2", durationMs: 100, spans: [validSpan] }];
+
+  it("合规 literal 通过", () => {
+    expect(validateTraceWaterfallData(valid)).toBeNull();
+  });
+
+  it("durationMs 为 null 合法(trace 缺失时如实显示缺失)", () => {
+    expect(validateTraceWaterfallData([{ ...valid[0], durationMs: null }])).toBeNull();
+  });
+
+  it("spans[i].kind 不在四态枚举内报错", () => {
+    const bad = [{ ...valid[0], spans: [{ ...validSpan, kind: "runner" }] }];
+    expect(validateTraceWaterfallData(bad)).toMatch(/"data\[0\]\.spans\[0\]\.kind"/);
+  });
+
+  it("spans[i].failed 非布尔报错", () => {
+    const bad = [{ ...valid[0], spans: [{ ...validSpan, failed: "true" }] }];
+    expect(validateTraceWaterfallData(bad)).toMatch(/"data\[0\]\.spans\[0\]\.failed"/);
+  });
+});

package/src/report/{react → components/summaries}/ScopeSummary.tsx

@@ -1,13 +1,14 @@
 // ScopeSummary:一个范围的摘要卡——快照时间窗、experiment / eval / attempt 数、判定计票、
-// 端到端成功率与总成本。data 恒携带 eval 级与 attempt 级两份计票;呈现 prop `votes`
-// 只选择显示哪一级(默认 "eval"),不改变 data。成功率与总成本只渲染算好的 MetricCell,
+// 端到端通过率与总成本。data 恒携带 eval 级与 attempt 级两份计票;呈现 prop `votes`
+// 只选择显示哪一级(默认 "eval"),不改变 data。通过率与总成本只渲染算好的 MetricCell,
 // 不现场重算(docs/feature/reports/library/summaries.md「ScopeSummary」)。
 
 import type { ReactElement } from "react";
-import type { ScopeSummaryData, VerdictTally } from "../types.ts";
-import { DEFAULT_REPORT_LOCALE, localeText, type ReportLocale } from "../locale.ts";
-import { MetricCellView } from "./cell.tsx";
-import { cx } from "./format.ts";
+import type { ScopeSummaryData, VerdictTally } from "../../model/types.ts";
+import { DEFAULT_REPORT_LOCALE, localeText, type ReportLocale } from "../../model/locale.ts";
+import { formatReportDateTime, formatReportDateTimeRange } from "../../model/format.ts";
+import { MetricCellView } from "../cell.tsx";
+import { cx } from "../shared.ts";
 
 function VerdictTallyView({ tally, locale }: { tally: VerdictTally; locale: ReportLocale }): ReactElement {
   const kinds = (["passed", "failed", "errored", "skipped"] as const).filter((k) => tally[k] > 0);
@@ -36,6 +37,10 @@ export function ScopeSummary({
   locale?: ReportLocale;
 }): ReactElement {
   const tally = votes === "attempt" ? data.attemptVerdicts : data.evalVerdicts;
+  const formattedRange =
+    data.range.earliestStartedAt !== null && data.range.latestStartedAt !== null
+      ? formatReportDateTimeRange(data.range.earliestStartedAt, data.range.latestStartedAt, locale)
+      : null;
   return (
     <div className={cx("nre", "nre-scope-summary", className)} data-votes={votes}>
       <dl className="nre-scope-kpis">
@@ -66,7 +71,15 @@ export function ScopeSummary({
         <div className="nre-scope-kpi">
           <dt>{localeText(locale, "scopeSummary.totalCost")}</dt>
           <dd>
-            <MetricCellView cell={data.totalCostUSD} locale={locale} />
+            <MetricCellView cell={data.totalCostUSD} locale={locale} showCoverage={false} />
+            {data.totalCostUSD.samples < data.totalCostUSD.total && (
+              <small className="nre-scope-kpi-note">
+                {localeText(locale, "scopeSummary.costCoverage", {
+                  samples: data.totalCostUSD.samples,
+                  total: data.totalCostUSD.total,
+                })}
+              </small>
+            )}
           </dd>
         </div>
       </dl>
@@ -74,11 +87,13 @@ export function ScopeSummary({
       {data.range.latestStartedAt !== null && (
         <p className="nre-scope-summary-range">
           {data.range.earliestStartedAt !== null && data.range.earliestStartedAt !== data.range.latestStartedAt
-            ? localeText(locale, "scopeSummary.range", {
-                from: data.range.earliestStartedAt,
-                to: data.range.latestStartedAt,
+            ? localeText(locale, "scopeSummary.runRange", {
+                from: formattedRange!.from,
+                to: formattedRange!.to,
               })
-            : data.range.latestStartedAt}
+            : localeText(locale, "scopeSummary.lastRun", {
+                time: formatReportDateTime(data.range.latestStartedAt, locale),
+              })}
         </p>
       )}
     </div>

package/src/report/components/summaries/compute.ts

@@ -0,0 +1,56 @@
+// 计算函数(*Data):ReportInput → 一份组件数据。ScopeSummary 的 scopeSummaryData 住在这里
+// (docs/feature/reports/library/summaries.md)。ExperimentComparison 是纯组合组件,不产生
+// 独立的 data,没有对应的计算函数。
+//
+// 共同约定(docs/feature/reports/architecture.md「指标聚合不变量」):
+// - 第一参收 ReportInput = Scope | readonly Snapshot[];warnings 不进组件数据(宿主统一显示);
+// - 聚合前按身份键去重(dedupeAttempts;missing-startedAt 不去重、如实保留、不透出警告);
+// - null ≠ 0:缺数据不编数,覆盖率经 samples/total 如实暴露。
+
+import type { ReportInput, ScopeSummaryData } from "../../model/types.ts";
+import { collectItems, computeCell, resolveInput } from "../../model/aggregate.ts";
+import { costUSD, defineMetric, endToEndPassRate } from "../../model/metrics.ts";
+import { selectedEvalsOnly, summarizeItems, tallyOf } from "../shared-compute.ts";
+
+// ───────────────────────── scopeSummaryData ─────────────────────────
+
+/** costUSD 的求和投影:两级都 sum(题内多轮求和 + 跨题求和 = 全量求和),display 走 $。 */
+const totalCostMetric = defineMetric({
+  name: "total-cost",
+  label: costUSD.label,
+  unit: "$",
+  value: costUSD.value,
+  aggregate: { perEval: "sum", acrossEvals: "sum" },
+});
+
+/**
+ * `scopeSummaryData(input)`:范围摘要——快照时间窗、experiment / eval / attempt 数、
+ * 两级判定计票、端到端通过率与总成本(docs/feature/reports/library/summaries.md)。
+ * data 恒携带两级计票;通过率来自官方两级指标引擎,不从任一计票重算。
+ */
+export async function scopeSummaryData(input: ReportInput): Promise<ScopeSummaryData> {
+  const snapshots = selectedEvalsOnly(resolveInput(input).snapshots);
+  const items = collectItems(snapshots);
+
+  let earliest: string | null = null;
+  let latest: string | null = null;
+  for (const snapshot of snapshots) {
+    if (earliest === null || snapshot.startedAt < earliest) earliest = snapshot.startedAt;
+    if (latest === null || snapshot.startedAt > latest) latest = snapshot.startedAt;
+  }
+
+  const stats = summarizeItems(items);
+  const attemptVerdicts = tallyOf();
+  for (const item of items) attemptVerdicts[item.attempt.result.verdict] += 1;
+
+  return {
+    range: { earliestStartedAt: earliest, latestStartedAt: latest },
+    experiments: stats.experiments,
+    evals: stats.evals,
+    attempts: stats.attempts,
+    evalVerdicts: stats.verdicts,
+    attemptVerdicts,
+    endToEndPassRate: await computeCell(endToEndPassRate, items),
+    totalCostUSD: await computeCell(totalCostMetric, items),
+  };
+}

package/src/report/components/summaries/faces.ts

@@ -0,0 +1,48 @@
+// ScopeSummary 的 text 面:同一份算好的数据,渲染成终端字符(niceeval show 的形态)。
+// 与 web 面共守诚实契约:排序随 better、samples < total 角标、缺数据 — 不补 0。
+// 零 react、零 IO、纯同步。
+
+import type { ScopeSummaryData } from "../../model/types.ts";
+import type { TextContext } from "../../definition/tree.ts";
+import { countText, localeText, resolveLocalizedText } from "../../model/locale.ts";
+import { formatReportDateTime, formatReportDateTimeRange } from "../../model/format.ts";
+import { wrapDisplay } from "../../model/text-layout.ts";
+import { cellText, verdictTallyText, MISSING_MARK } from "../shared-faces.ts";
+
+/**
+ * 一至两行:头行是端到端通过率(官方 MetricCell,不重算)+ experiment/eval/attempt 数 +
+ * `votes` 选中的那级计票 + 总成本;第二行(有则加)是快照时间窗。
+ */
+export function scopeSummaryText(data: ScopeSummaryData, votes: "eval" | "attempt", ctx: TextContext): string {
+  const locale = ctx.locale;
+  const tally = votes === "attempt" ? data.attemptVerdicts : data.evalVerdicts;
+  const head = [
+    `${localeText(locale, "scopeSummary.passRate")} ${cellText(data.endToEndPassRate, locale)}`,
+    countText(locale, "overview.experiments", data.experiments),
+    localeText(locale, "overview.evalsCount", { n: data.evals }),
+    localeText(locale, "overview.attemptsCount", { n: data.attempts }),
+    verdictTallyText(tally, locale),
+    `${localeText(locale, "scopeSummary.totalCost")} ${
+      data.totalCostUSD.value === null ? MISSING_MARK : resolveLocalizedText(data.totalCostUSD.display, locale)
+    }${
+      data.totalCostUSD.samples < data.totalCostUSD.total
+        ? ` (${localeText(locale, "scopeSummary.costCoverage", {
+            samples: data.totalCostUSD.samples,
+            total: data.totalCostUSD.total,
+          })})`
+        : ""
+    }`,
+  ].join(" · ");
+  // 头行拼接的字段较多,窄终端下按显示宽度折行(不截断内容)。
+  const lines = wrapDisplay(head, ctx.width);
+  if (data.range.latestStartedAt !== null) {
+    const from = data.range.earliestStartedAt;
+    const to = data.range.latestStartedAt;
+    lines.push(
+      from !== null && from !== to
+        ? localeText(locale, "scopeSummary.runRange", formatReportDateTimeRange(from, to, locale))
+        : localeText(locale, "scopeSummary.lastRun", { time: formatReportDateTime(to, locale) }),
+    );
+  }
+  return lines.join("\n");
+}

package/src/report/components/summaries/index.tsx

@@ -0,0 +1,127 @@
+// 官方双面组件的装配点:web 面(./ScopeSummary.tsx 的纯 React 组件)+ text 面(./faces.ts)
+// + resolve 解析面(spec 形态由管线代调配套 ./compute.ts)。ScopeSummary 与 ExperimentComparison
+// 同属汇总族——前者是范围摘要卡,后者是内建报告默认使用的组合件(装配 ScopeSummary +
+// MetricScatter + ExperimentList,不产生自己的 data)。
+
+import { defineComponent, type ReportComponent } from "../../definition/tree.ts";
+import { Col } from "../../definition/primitives.tsx";
+import type { ReportInput, ScopeSummaryData, SeriesInput } from "../../model/types.ts";
+import { resolveInput, seriesName } from "../../model/aggregate.ts";
+import { label } from "../../model/flag.ts";
+import { costUSD, endToEndPassRate } from "../../model/metrics.ts";
+import {
+  cellProblem,
+  isObject,
+  makeDataComponent,
+  tallyProblem,
+  type ChromeProps,
+  type DataProps,
+  type Validator,
+} from "../shared.ts";
+import { scopeSummaryData } from "./compute.ts";
+import { scopeSummaryText } from "./faces.ts";
+import { ScopeSummary as ScopeSummaryWeb } from "./ScopeSummary.tsx";
+import { MetricScatter } from "../metric-views/index.tsx";
+import { ExperimentList } from "../entity-lists/index.tsx";
+
+export const validateScopeSummaryData: Validator = (data) => {
+  if (!isObject(data)) return "expected an object";
+  if (!isObject(data.range)) return 'missing "range" ({ earliestStartedAt, latestStartedAt })';
+  if (!(data.range.earliestStartedAt === null || typeof data.range.earliestStartedAt === "string")) {
+    return '"range.earliestStartedAt" must be a string or null';
+  }
+  if (!(data.range.latestStartedAt === null || typeof data.range.latestStartedAt === "string")) {
+    return '"range.latestStartedAt" must be a string or null';
+  }
+  if (typeof data.experiments !== "number") return '"experiments" must be a number';
+  if (typeof data.evals !== "number") return '"evals" must be a number';
+  if (typeof data.attempts !== "number") return '"attempts" must be a number';
+  const evalVerdictsProblem = tallyProblem(data.evalVerdicts, "evalVerdicts");
+  if (evalVerdictsProblem !== null) return evalVerdictsProblem;
+  const attemptVerdictsProblem = tallyProblem(data.attemptVerdicts, "attemptVerdicts");
+  if (attemptVerdictsProblem !== null) return attemptVerdictsProblem;
+  const passRateProblem = cellProblem(data.endToEndPassRate, "endToEndPassRate");
+  if (passRateProblem !== null) return passRateProblem;
+  return cellProblem(data.totalCostUSD, "totalCostUSD");
+};
+
+// ───────────────────────── 概览组件 ─────────────────────────
+
+export type ScopeSummaryProps = DataProps<
+  ScopeSummaryData,
+  Record<never, never>,
+  ChromeProps & {
+    /** 显示哪一级计票;默认 "eval"。data 恒携带两级,votes 只选择呈现。 */
+    votes?: "eval" | "attempt";
+  }
+>;
+
+/** 范围摘要卡:时间窗、数量、两级计票、端到端通过率与总成本。 */
+export const ScopeSummary = makeDataComponent<
+  ScopeSummaryData,
+  Record<never, never>,
+  ChromeProps & { votes?: "eval" | "attempt" }
+>({
+  name: "ScopeSummary",
+  dataFnName: "scopeSummaryData",
+  shapeName: "ScopeSummaryData",
+  dataFn: (input) => scopeSummaryData(input),
+  specKeys: [],
+  validate: validateScopeSummaryData,
+  web: (props, ctx) => <ScopeSummaryWeb {...props} locale={props.locale ?? ctx.locale} />,
+  text: (props, ctx) => scopeSummaryText(props.data, props.votes ?? "eval", ctx),
+}) as unknown as ReportComponent<ScopeSummaryProps>;
+
+type ComparisonChrome = ChromeProps & {
+  /** 透传给散点;缺省跟随缺省 series 解析——按 line 归类时连线(声明了线就画线)。 */
+  connect?: boolean;
+};
+
+export type ExperimentComparisonProps = ComparisonChrome & {
+  input?: ReportInput;
+  /** 散点的 series 维度。缺省解析:Scope 内任一实验声明了 label `line` → `label("line")` 并连线;否则 `"agent"`、不连线。 */
+  series?: SeriesInput;
+};
+
+/** 默认报告识别的归类键:声明了它的实验按线归类并连线(docs/feature/experiments/library.md「labels」)。 */
+const LINE_LABEL_KEY = "line";
+
+/**
+ * 缺省 series:Scope 内任一快照声明了 labels.line 用 line 维度,否则 agent;显式传入覆盖。
+ * connect 缺省跟随最终 series 是否解析为 line(即便是显式传入的)。
+ */
+function resolveComparisonSeries(
+  input: ReportInput,
+  props: { series?: SeriesInput; connect?: boolean },
+): { series: SeriesInput; connect: boolean } {
+  const hasLine = resolveInput(input).snapshots.some((s) => s.experiment?.labels?.[LINE_LABEL_KEY] !== undefined);
+  const series = props.series ?? (hasLine ? label(LINE_LABEL_KEY) : "agent");
+  return { series, connect: props.connect ?? seriesName(series) === LINE_LABEL_KEY };
+}
+
+/**
+ * 内建报告的默认组合件:把同一个 input(缺省 ctx.scope)原样透传给 ScopeSummary、
+ * 成本 × 端到端通过率的 MetricScatter 与 ExperimentList——组合本身不二次计算或过滤,
+ * 也不导出自己的 data 形态;每个叶子组件按自己的公开契约取数,共享计算由 resolve 的
+ * 「同引用 input + 深相等 spec」记忆化保证。
+ */
+export const ExperimentComparison = defineComponent<ExperimentComparisonProps>((props, ctx) => {
+  const input = props.input ?? ctx.scope;
+  const { series, connect } = resolveComparisonSeries(input, props);
+  return (
+    <Col className={props.className}>
+      <ScopeSummary input={input} locale={props.locale} />
+      <MetricScatter
+        input={input}
+        points="experiment"
+        series={series}
+        connect={connect}
+        x={costUSD}
+        y={endToEndPassRate}
+        locale={props.locale}
+      />
+      <ExperimentList input={input} filter locale={props.locale} />
+    </Col>
+  );
+});
+ExperimentComparison.displayName = "ExperimentComparison";

package/src/report/components/summaries/validate.test.ts

@@ -0,0 +1,49 @@
+// cases: docs/engineering/unit-tests/reports/cases.md
+// "validate*Data 递归覆盖到嵌套字段" 行:summaries 的 validateScopeSummaryData 表驱动字段突变覆盖,range 的 null 边界、两级 tally、
+// 两个 MetricCell 字段各自的嵌套校验。
+
+import { describe, expect, it } from "vitest";
+import { validateScopeSummaryData } 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 valid = {
+  range: { earliestStartedAt: "2026-07-01T00:00:00Z", latestStartedAt: "2026-07-02T00:00:00Z" },
+  experiments: 1,
+  evals: 6,
+  attempts: 6,
+  evalVerdicts: validTally,
+  attemptVerdicts: validTally,
+  endToEndPassRate: validCell,
+  totalCostUSD: validCell,
+};
+
+describe("validateScopeSummaryData", () => {
+  it("合规 literal 通过", () => {
+    expect(validateScopeSummaryData(valid)).toBeNull();
+  });
+
+  it("range 两端为 null 合法(空范围不编造当前时间)", () => {
+    expect(validateScopeSummaryData({ ...valid, range: { earliestStartedAt: null, latestStartedAt: null } })).toBeNull();
+  });
+
+  it("range.earliestStartedAt 非法类型报错", () => {
+    const bad = { ...valid, range: { earliestStartedAt: 123, latestStartedAt: null } };
+    expect(validateScopeSummaryData(bad)).toMatch(/"range\.earliestStartedAt"/);
+  });
+
+  it("evalVerdicts 与 attemptVerdicts 分别校验:错的那个才报错", () => {
+    const bad = { ...valid, attemptVerdicts: { passed: 1, failed: 0, errored: 0, skipped: "0" } };
+    expect(validateScopeSummaryData(bad)).toMatch(/"attemptVerdicts\.skipped"/);
+  });
+
+  it("endToEndPassRate 结构错误定位到嵌套 MetricCell", () => {
+    const bad = { ...valid, endToEndPassRate: { value: 1, display: "1", samples: 1, total: 1, refs: "x" } };
+    expect(validateScopeSummaryData(bad)).toMatch(/"endToEndPassRate\.refs"/);
+  });
+
+  it("experiments 非数字报错", () => {
+    expect(validateScopeSummaryData({ ...valid, experiments: "1" })).toMatch(/"experiments"/);
+  });
+});

package/src/report/definition/grid-layout.test.ts

@@ -0,0 +1,124 @@
+// cases: docs/engineering/unit-tests/reports/cases.md
+// 分区「Table 与文本排版原语」:Grid 展平规则、columns 校验与 TextGridPlan 的宽度算术
+// 直接对 normalizeGrid / planTextGrid 断言,不经渲染面或 HTML。
+
+import { describe, expect, it } from "vitest";
+import { normalizeGrid, planTextGrid, validateGridColumns } from "./grid-layout.ts";
+import type { ReportElement } from "./tree.ts";
+
+const FRAGMENT = Symbol.for("react.fragment");
+
+function el(type: string, props: Record<string, unknown> = {}): ReportElement {
+  return { type, props };
+}
+
+describe("validateGridColumns", () => {
+  it("接受有限正整数", () => {
+    expect(validateGridColumns(1)).toBe(1);
+    expect(validateGridColumns(9)).toBe(9);
+  });
+
+  for (const bad of [0, -1, 1.5, NaN, Infinity, -Infinity]) {
+    it(`拒绝 ${bad} 并给出完整用户反馈`, () => {
+      expect(() => validateGridColumns(bad)).toThrowError(/columns/i);
+      try {
+        validateGridColumns(bad);
+      } catch (err) {
+        const message = (err as Error).message;
+        expect(message).toContain(JSON.stringify(bad));
+        expect(message).toContain("columns={N}");
+      }
+    });
+  }
+});
+
+describe("normalizeGrid", () => {
+  it("展平数组与 Fragment、跳过空分支,任意 ReportNode 各占一格", () => {
+    const a = el("Stat", { label: "a" });
+    const b = el("Stat", { label: "b" });
+    const c = el("Col", { children: [el("Stat", { label: "c1" }), el("Stat", { label: "c2" })] });
+    const children = [
+      a,
+      null,
+      undefined,
+      false,
+      { type: FRAGMENT, props: { children: [b, null] } },
+      c,
+    ];
+    const normalized = normalizeGrid({ children, columns: 3 });
+    expect(normalized.cells.map((cell) => cell.node)).toEqual([a, b, c]);
+    // Col 归拢的两个 Stat 仍是同一格,不下钻展开成两格
+    expect(normalized.cells).toHaveLength(3);
+  });
+
+  it("全部子节点为空分支时 0 格", () => {
+    const normalized = normalizeGrid({ children: [null, undefined, false], columns: 3 });
+    expect(normalized.cells).toHaveLength(0);
+  });
+
+  it("variant / density 默认 plain / regular", () => {
+    const normalized = normalizeGrid({ children: el("Stat"), columns: 1 });
+    expect(normalized.variant).toBe("plain");
+    expect(normalized.density).toBe("regular");
+  });
+
+  it("单个裸元素(非数组)也能展平为一格并生成稳定 key", () => {
+    const normalized = normalizeGrid({ children: el("Stat", { label: "solo" }), columns: 1 });
+    expect(normalized.cells).toHaveLength(1);
+    expect(normalized.cells[0].key).toBe("nre-grid-cell-0");
+  });
+});
+
+describe("planTextGrid", () => {
+  // 与 docs/feature/reports/library/layout.md 的运行总览示例逐字核对:Section 缩进后
+  // Grid 收到 98 显示列可用宽度,两个 Grid 都必须恰好降到三列且逐行不超过 100(=98+2 缩进)。
+  it("目标示例 Grid(columns=6, 6 cell, regular)在 98 可用宽度降为三列,内容宽 28/27/27", () => {
+    const plan = planTextGrid({ availableWidth: 98, cellCount: 6, columns: 6, density: "regular" });
+    expect(plan.columns).toBe(3);
+    expect(plan.contentWidths).toEqual([28, 27, 27]);
+    expect(plan.gutter).toBe(2);
+    const rowWidth = plan.contentWidths.reduce((sum, w) => sum + w + 4, 0) + plan.gutter * (plan.columns - 1);
+    expect(rowWidth).toBe(98);
+  });
+
+  it("目标示例 Grid(columns=9, 9 cell, compact)在 98 可用宽度降为三列,内容宽 28/28/28", () => {
+    const plan = planTextGrid({ availableWidth: 98, cellCount: 9, columns: 9, density: "compact" });
+    expect(plan.columns).toBe(3);
+    expect(plan.contentWidths).toEqual([28, 28, 28]);
+    expect(plan.gutter).toBe(1);
+    const rowWidth = plan.contentWidths.reduce((sum, w) => sum + w + 4, 0) + plan.gutter * (plan.columns - 1);
+    expect(rowWidth).toBe(98);
+  });
+
+  it("继续收窄宽度时降为一列(无条件 fallback,即使内容宽度小于 24)", () => {
+    const plan = planTextGrid({ availableWidth: 20, cellCount: 6, columns: 6, density: "regular" });
+    expect(plan.columns).toBe(1);
+    expect(plan.contentWidths).toEqual([16]); // 20 - BOXED_OVERHEAD_PER_CELL(4)
+  });
+
+  it("columns=1 时无条件单列,不因宽度充裕而尝试更多列", () => {
+    const plan = planTextGrid({ availableWidth: 200, cellCount: 6, columns: 1, density: "regular" });
+    expect(plan.columns).toBe(1);
+  });
+
+  it("列数不超过 min(declared columns, cellCount)", () => {
+    const plan = planTextGrid({ availableWidth: 400, cellCount: 2, columns: 9, density: "regular" });
+    expect(plan.columns).toBeLessThanOrEqual(2);
+  });
+
+  it("plain 与 boxed 复用同一份 plan:规划不吃 variant,列数与内容宽只随 columns/density/availableWidth 变化", () => {
+    const a = planTextGrid({ availableWidth: 98, cellCount: 6, columns: 6, density: "regular" });
+    const b = planTextGrid({ availableWidth: 98, cellCount: 6, columns: 6, density: "regular" });
+    expect(a).toEqual(b);
+  });
+
+  it("整除余数从左向右各补一列,行宽不超过 availableWidth", () => {
+    const plan = planTextGrid({ availableWidth: 100, cellCount: 4, columns: 4, density: "regular" });
+    const rowWidth = plan.contentWidths.reduce((sum, w) => sum + w + 4, 0) + plan.gutter * (plan.columns - 1);
+    expect(rowWidth).toBeLessThanOrEqual(100);
+    // 余数只补到最左侧若干列,不累积到行尾
+    for (let i = 1; i < plan.contentWidths.length; i++) {
+      expect(plan.contentWidths[i]).toBeLessThanOrEqual(plan.contentWidths[i - 1]);
+    }
+  });
+});