niceeval 0.9.0 → 0.10.0

package/dist/report/components/metric-views/index.js

@@ -0,0 +1,273 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { arrayProblem, cellProblem, isLocalizedText, isObject, makeDataComponent, hrefOf, } from "../shared.js";
+import { deltaTableData, metricLineData, metricMatrixData, metricScatterData, metricTableData, scoreboardData, } from "./compute.js";
+import { barsText, deltaText, lineText, matrixText, scatterText, scoreboardText, tableText } from "./faces.js";
+import { MetricTable as MetricTableWeb } from "./MetricTable.js";
+import { MetricMatrix as MetricMatrixWeb } from "./MetricMatrix.js";
+import { MetricBars as MetricBarsWeb } from "./MetricBars.js";
+import { Scoreboard as ScoreboardWeb } from "./Scoreboard.js";
+import { MetricScatter as MetricScatterWeb } from "./MetricScatter.js";
+import { MetricLine as MetricLineWeb } from "./MetricLine.js";
+import { DeltaTable as DeltaTableWeb } from "./DeltaTable.js";
+/** columns / metric / x / y 共用的 MetricColumn 形状(src/report/model/types.ts)。 */
+function metricColumnProblem(value, path) {
+    if (!isObject(value))
+        return `"${path}" must be a MetricColumn { key, label }`;
+    if (typeof value.key !== "string")
+        return `"${path}.key" must be a string`;
+    if (!isLocalizedText(value.label))
+        return `"${path}.label" must be a LocalizedText`;
+    return null;
+}
+export const validateTableData = (data) => {
+    if (!isObject(data))
+        return "expected an object";
+    if (typeof data.rowDimension !== "string")
+        return 'missing "rowDimension" (string)';
+    const columnsProblem = arrayProblem(data.columns, "columns", metricColumnProblem);
+    if (columnsProblem !== null)
+        return columnsProblem;
+    return arrayProblem(data.rows, "rows", (row, path) => {
+        if (!isObject(row))
+            return `"${path}" must be an object`;
+        if (typeof row.key !== "string")
+            return `"${path}.key" must be a string`;
+        if (!isObject(row.cells))
+            return `"${path}.cells" must be an object`;
+        for (const [metricKey, cell] of Object.entries(row.cells)) {
+            const problem = cellProblem(cell, `${path}.cells.${metricKey}`);
+            if (problem !== null)
+                return problem;
+        }
+        return null;
+    });
+};
+export const validateMatrixData = (data) => {
+    if (!isObject(data))
+        return "expected an object";
+    if (typeof data.rowDimension !== "string" || typeof data.columnDimension !== "string") {
+        return 'missing "rowDimension" / "columnDimension" (string)';
+    }
+    const metricProblem = metricColumnProblem(data.metric, "metric");
+    if (metricProblem !== null)
+        return metricProblem;
+    return arrayProblem(data.cells, "cells", (item, path) => {
+        if (!isObject(item))
+            return `"${path}" must be an object`;
+        if (typeof item.row !== "string" || typeof item.column !== "string") {
+            return `"${path}.row" / "${path}.column" must be strings`;
+        }
+        return cellProblem(item.cell, `${path}.cell`);
+    });
+};
+export const validateScatterData = (data) => {
+    if (!isObject(data))
+        return "expected an object";
+    if (typeof data.pointDimension !== "string")
+        return 'missing "pointDimension" (string)';
+    const xColumnProblem = metricColumnProblem(data.x, "x");
+    if (xColumnProblem !== null)
+        return xColumnProblem;
+    const yColumnProblem = metricColumnProblem(data.y, "y");
+    if (yColumnProblem !== null)
+        return yColumnProblem;
+    return arrayProblem(data.rows, "rows", (row, path) => {
+        if (!isObject(row) || typeof row.key !== "string")
+            return `"${path}" must be an object with a string "key"`;
+        const xProblem = cellProblem(row.x, `${path}.x`);
+        if (xProblem !== null)
+            return xProblem;
+        return cellProblem(row.y, `${path}.y`);
+    });
+};
+export const validateLineData = (data) => {
+    if (!isObject(data))
+        return "expected an object";
+    if (!isObject(data.x) || typeof data.x.key !== "string" || !isLocalizedText(data.x.label)) {
+        return '"x" must be an axis descriptor { key, label }';
+    }
+    const yColumnProblem = metricColumnProblem(data.y, "y");
+    if (yColumnProblem !== null)
+        return yColumnProblem;
+    return arrayProblem(data.rows, "rows", (row, path) => {
+        if (!isObject(row) || typeof row.key !== "string")
+            return `"${path}" must be an object with a string "key"`;
+        if (!(row.x === null || typeof row.x === "number"))
+            return `"${path}.x" must be a number or null`;
+        if (!isLocalizedText(row.xDisplay))
+            return `"${path}.xDisplay" must be a LocalizedText`;
+        return cellProblem(row.y, `${path}.y`);
+    });
+};
+function scoreTotalProblem(value, path) {
+    if (!isObject(value))
+        return `"${path}" must be an object { value, display, notRun, unscorable, refs }`;
+    if (typeof value.value !== "number")
+        return `"${path}.value" must be a number`;
+    if (!isLocalizedText(value.display))
+        return `"${path}.display" must be a LocalizedText`;
+    if (typeof value.notRun !== "number")
+        return `"${path}.notRun" must be a number`;
+    if (typeof value.unscorable !== "number")
+        return `"${path}.unscorable" must be a number`;
+    if (!Array.isArray(value.refs))
+        return `"${path}.refs" must be an array`;
+    return null;
+}
+export const validateScoreboardData = (data) => {
+    if (!isObject(data))
+        return "expected an object";
+    if (typeof data.rowDimension !== "string")
+        return 'missing "rowDimension" (string)';
+    if (!Array.isArray(data.questions))
+        return 'missing "questions" (array)';
+    if (typeof data.fullMarks !== "number")
+        return 'missing "fullMarks" (number)';
+    if (typeof data.ignoredEvals !== "number")
+        return 'missing "ignoredEvals" (number)';
+    return arrayProblem(data.rows, "rows", (row, path) => {
+        if (!isObject(row) || typeof row.key !== "string")
+            return `"${path}" must be an object with a string "key"`;
+        const totalProblem = scoreTotalProblem(row.total, `${path}.total`);
+        if (totalProblem !== null)
+            return totalProblem;
+        return arrayProblem(row.subjects, `${path}.subjects`, (subject, subjectPath) => {
+            if (!isObject(subject) || typeof subject.key !== "string") {
+                return `"${subjectPath}" must be an object with a string "key"`;
+            }
+            if (typeof subject.earned !== "number")
+                return `"${subjectPath}.earned" must be a number`;
+            if (typeof subject.possible !== "number")
+                return `"${subjectPath}.possible" must be a number`;
+            if (typeof subject.questions !== "number")
+                return `"${subjectPath}.questions" must be a number`;
+            if (typeof subject.notRun !== "number")
+                return `"${subjectPath}.notRun" must be a number`;
+            if (typeof subject.unscorable !== "number")
+                return `"${subjectPath}.unscorable" must be a number`;
+            if (!isLocalizedText(subject.display))
+                return `"${subjectPath}.display" must be a LocalizedText`;
+            if (!Array.isArray(subject.refs))
+                return `"${subjectPath}.refs" must be an array`;
+            return null;
+        });
+    });
+};
+const DELTA_OUTCOMES = ["improved", "regressed", "unchanged", "unavailable"];
+export const validateDeltaData = (data) => {
+    if (!isObject(data))
+        return "expected an object";
+    if (typeof data.byDimension !== "string")
+        return 'missing "byDimension" (string)';
+    const columnsProblem = arrayProblem(data.columns, "columns", metricColumnProblem);
+    if (columnsProblem !== null)
+        return columnsProblem;
+    return arrayProblem(data.rows, "rows", (row, path) => {
+        if (!isObject(row) || typeof row.key !== "string")
+            return `"${path}" must be an object with a string "key"`;
+        if (!isLocalizedText(row.label))
+            return `"${path}.label" must be a LocalizedText`;
+        if (!isObject(row.a) || typeof row.a.key !== "string")
+            return `"${path}.a" must be an object with a string "key"`;
+        if (!isObject(row.b) || typeof row.b.key !== "string")
+            return `"${path}.b" must be an object with a string "key"`;
+        if (!isObject(row.cells))
+            return `"${path}.cells" must be an object`;
+        for (const [metricKey, cell] of Object.entries(row.cells)) {
+            const cellPath = `${path}.cells.${metricKey}`;
+            if (!isObject(cell))
+                return `"${cellPath}" must be an object { a, b, delta, display, outcome }`;
+            const aProblem = cellProblem(cell.a, `${cellPath}.a`);
+            if (aProblem !== null)
+                return aProblem;
+            const bProblem = cellProblem(cell.b, `${cellPath}.b`);
+            if (bProblem !== null)
+                return bProblem;
+            if (!(cell.delta === null || typeof cell.delta === "number"))
+                return `"${cellPath}.delta" must be a number or null`;
+            if (!isLocalizedText(cell.display))
+                return `"${cellPath}.display" must be a LocalizedText`;
+            if (typeof cell.outcome !== "string" || !DELTA_OUTCOMES.includes(cell.outcome)) {
+                return `"${cellPath}.outcome" must be one of ${JSON.stringify(DELTA_OUTCOMES)}`;
+            }
+        }
+        return null;
+    });
+};
+/** 榜单:一行一个维度值、一列一个指标,回答「谁整体更好」。 */
+export const MetricTable = makeDataComponent({
+    name: "MetricTable",
+    dataFnName: "metricTableData",
+    shapeName: "TableData",
+    dataFn: metricTableData,
+    specKeys: ["rows", "columns", "sort", "evals"],
+    validate: validateTableData,
+    web: (props, ctx) => (_jsx(MetricTableWeb, { data: props.data, filter: props.filter, locale: props.locale ?? ctx.locale, attemptHref: hrefOf(props, ctx), className: props.className })),
+    text: (props, ctx) => tableText(props.data, ctx),
+});
+/** 逐题格子:行 × 列两个维度、格子里一个指标,回答「哪道题谁挂了」。 */
+export const MetricMatrix = makeDataComponent({
+    name: "MetricMatrix",
+    dataFnName: "metricMatrixData",
+    shapeName: "MatrixData",
+    dataFn: metricMatrixData,
+    specKeys: ["rows", "columns", "cell", "evals"],
+    validate: validateMatrixData,
+    web: (props, ctx) => (_jsx(MetricMatrixWeb, { data: props.data, locale: props.locale ?? ctx.locale, attemptHref: hrefOf(props, ctx), className: props.className })),
+    text: (props, ctx) => matrixText(props.data, ctx),
+});
+/** 分组条形:同一份矩阵数据的另一种摆法;与 MetricMatrix 写同一份 spec 时只计算一次。 */
+export const MetricBars = makeDataComponent({
+    name: "MetricBars",
+    dataFnName: "metricMatrixData",
+    shapeName: "MatrixData",
+    dataFn: metricMatrixData,
+    specKeys: ["rows", "columns", "cell", "evals"],
+    validate: validateMatrixData,
+    web: (props, ctx) => (_jsx(MetricBarsWeb, { data: props.data, locale: props.locale ?? ctx.locale, attemptHref: hrefOf(props, ctx), className: props.className })),
+    text: (props, ctx) => barsText(props.data, ctx),
+});
+/** 考试成绩单:总分 + 分科小计,固定分母、notRun / unscorable 分开如实报。 */
+export const Scoreboard = makeDataComponent({
+    name: "Scoreboard",
+    dataFnName: "scoreboardData",
+    shapeName: "ScoreboardData",
+    dataFn: scoreboardData,
+    specKeys: ["rows", "questions", "subject", "weights", "fullMarks", "score"],
+    validate: validateScoreboardData,
+    web: (props, ctx) => _jsx(ScoreboardWeb, { data: props.data, locale: props.locale ?? ctx.locale, className: props.className }),
+    text: (props, ctx) => scoreboardText(props.data, ctx),
+});
+/** 两个指标之间的取舍:每个点一个维度值,x / y 各一个指标,series 决定颜色和图例归类。 */
+export const MetricScatter = makeDataComponent({
+    name: "MetricScatter",
+    dataFnName: "metricScatterData",
+    shapeName: "ScatterData",
+    dataFn: metricScatterData,
+    specKeys: ["points", "series", "x", "y", "evals"],
+    validate: validateScatterData,
+    web: (props, ctx) => (_jsx(MetricScatterWeb, { data: props.data, connect: props.connect, pointHref: props.pointHref, locale: props.locale ?? ctx.locale, className: props.className })),
+    text: (props, ctx) => scatterText(props.data, ctx, { connect: props.connect }),
+});
+/** 趋势线:x 是 NumericAxis(参数轴),点身份 = (series, x)。 */
+export const MetricLine = makeDataComponent({
+    name: "MetricLine",
+    dataFnName: "metricLineData",
+    shapeName: "LineData",
+    dataFn: metricLineData,
+    specKeys: ["x", "series", "y", "evals"],
+    validate: validateLineData,
+    web: (props, ctx) => (_jsx(MetricLineWeb, { data: props.data, pointHref: props.pointHref, locale: props.locale ?? ctx.locale, className: props.className })),
+    text: (props, ctx) => lineText(props.data, ctx),
+});
+/** 成对对比:每行一对(字面声明或 pairsByFlag 派生),格子里 A、B、Δ 三个值。 */
+export const DeltaTable = makeDataComponent({
+    name: "DeltaTable",
+    dataFnName: "deltaTableData",
+    shapeName: "DeltaData",
+    dataFn: deltaTableData,
+    specKeys: ["by", "pairs", "metrics", "evals"],
+    validate: validateDeltaData,
+    web: (props, ctx) => _jsx(DeltaTableWeb, { data: props.data, locale: props.locale ?? ctx.locale, className: props.className }),
+    text: (props, ctx) => deltaText(props.data, ctx),
+});

package/dist/report/{text → components/metric-views}/plot.js

@@ -1,7 +1,7 @@
 // text 面的字符坐标图:MetricScatter / MetricLine 共用。
 // 形态照 docs-site/zh/reference/report-components.mdx 的示例块:y 轴刻度 + │ 边框,
 // 点用字母标注、图例列在图下;lower-better 的轴反向,「好」的角落恒在右上。
-import { padDisplay, padStartDisplay, stringWidth } from "./layout.js";
+import { padDisplay, padStartDisplay, stringWidth } from "../../model/text-layout.js";
 function makeScale(values, cells, invert) {
     const lo = Math.min(...values);
     const hi = Math.max(...values);

package/dist/report/components/shared-compute.d.ts

@@ -0,0 +1,22 @@
+import type { Snapshot } from "../../results/types.ts";
+import { type Item } from "../model/aggregate.ts";
+import type { VerdictTally } from "../model/types.ts";
+/**
+ * 每个 experiment 只保留自己 `selectedEvalIds` 内的 eval/attempt——两个 experiment 声明不同
+ * eval 集时各自只统计自己选中的那部分,未选择的 eval(即使恰好在同一次运行里跑过)不进
+ * 分母、不污染另一个 experiment。第三方快照缺该字段时 `selectedEvalIdsOf` 退化为其实际
+ * evals,过滤天然是 no-op。宿主注入的 current() Scope 在合成时已按这条规则收窄,这里对
+ * 真实 Scope 是幂等的;只对作者手工拼的 Snapshot[] 真正生效。`experimentListData` /
+ * `scopeSummaryData` / `metricScatterData` 共用同一条规则,保证经 `ExperimentComparison`
+ * 展开后收到的 spec 与直接调用同一份 input 深相等。
+ */
+export declare function selectedEvalsOnly(snapshots: readonly Snapshot[]): readonly Snapshot[];
+export declare function tallyOf(): VerdictTally;
+/** 一批 Item 的组级统计(experimentListData / scopeSummaryData 共用)。 */
+export declare function summarizeItems(items: Item[]): {
+    experiments: number;
+    evals: number;
+    attempts: number;
+    verdicts: VerdictTally;
+    lastRunAt: string | undefined;
+};

package/dist/report/components/shared-compute.js

@@ -0,0 +1,47 @@
+// 跨组件族共用的计算辅助:summaries(scopeSummaryData)、entity-lists(experimentListData)、
+// metric-views(metricScatterData)三族的 *Data 函数共用同一条 selectedEvalIds 投影规则与
+// 同一套组级统计折叠,住在这里而不是任一族自己的 compute.ts,避免三份重复实现分叉。
+import { selectedEvalIdsOf } from "../../results/select.js";
+import { evalLevelStats } from "../../shared/verdict.js";
+import { experimentIdOf, fullEvalKey } from "../model/aggregate.js";
+/**
+ * 每个 experiment 只保留自己 `selectedEvalIds` 内的 eval/attempt——两个 experiment 声明不同
+ * eval 集时各自只统计自己选中的那部分,未选择的 eval(即使恰好在同一次运行里跑过)不进
+ * 分母、不污染另一个 experiment。第三方快照缺该字段时 `selectedEvalIdsOf` 退化为其实际
+ * evals,过滤天然是 no-op。宿主注入的 current() Scope 在合成时已按这条规则收窄,这里对
+ * 真实 Scope 是幂等的;只对作者手工拼的 Snapshot[] 真正生效。`experimentListData` /
+ * `scopeSummaryData` / `metricScatterData` 共用同一条规则,保证经 `ExperimentComparison`
+ * 展开后收到的 spec 与直接调用同一份 input 深相等。
+ */
+export function selectedEvalsOnly(snapshots) {
+    return snapshots.map((snapshot) => {
+        const selected = new Set(selectedEvalIdsOf(snapshot));
+        const evals = snapshot.evals.filter((ev) => selected.has(ev.id));
+        if (evals.length === snapshot.evals.length)
+            return snapshot;
+        return { ...snapshot, evals, attempts: evals.flatMap((ev) => ev.attempts) };
+    });
+}
+export function tallyOf() {
+    return { passed: 0, failed: 0, errored: 0, skipped: 0 };
+}
+/** 一批 Item 的组级统计(experimentListData / scopeSummaryData 共用)。 */
+export function summarizeItems(items) {
+    const experimentIds = new Set();
+    for (const item of items)
+        experimentIds.add(experimentIdOf(item));
+    const stats = evalLevelStats(items.map((item) => ({ verdict: item.attempt.result.verdict, key: fullEvalKey(item) })), (r) => r.key);
+    let lastRunAt;
+    for (const item of items) {
+        const startedAt = item.snapshot.startedAt;
+        if (lastRunAt === undefined || startedAt > lastRunAt)
+            lastRunAt = startedAt;
+    }
+    return {
+        experiments: experimentIds.size,
+        evals: stats.evals,
+        attempts: items.length,
+        verdicts: { passed: stats.passed, failed: stats.failed, errored: stats.errored, skipped: stats.skipped },
+        lastRunAt,
+    };
+}

package/dist/report/components/shared-faces.d.ts

@@ -0,0 +1,9 @@
+import type { MetricCell, VerdictTally } from "../model/types.ts";
+import { type ReportLocale } from "../model/locale.ts";
+export declare const MISSING_MARK = "\u2014";
+/** 缺数据文案随 locale(en = "no data")。 */
+export declare function missingText(locale: ReportLocale): string;
+/** 格子的文本形态:缺数据 —,覆盖不全带 samples/total 角标;display 按 locale 解析。 */
+export declare function cellText(cell: MetricCell, locale: ReportLocale): string;
+/** verdict 计票的紧凑文案("3 passed · 1 failed"):非零判定逐个列,全部为零如实 —。 */
+export declare function verdictTallyText(tally: VerdictTally, locale: ReportLocale): string;

package/dist/report/components/shared-faces.js

@@ -0,0 +1,26 @@
+// 跨组件族共用的 text 面辅助:MetricCell / VerdictTally 的文本渲染在 summaries、
+// entity-lists、metric-views 三族的 text 面里都要用到,住在这里而不是任一族自己的
+// faces.ts,避免三份重复实现分叉(与 ../cell.tsx 的 MetricCellView 是同一份契约的
+// text/web 两面)。
+import { localeText, resolveLocalizedText } from "../model/locale.js";
+export const MISSING_MARK = "—";
+/** 缺数据文案随 locale(en = "no data")。 */
+export function missingText(locale) {
+    return localeText(locale, "cell.missing");
+}
+/** 格子的文本形态:缺数据 —,覆盖不全带 samples/total 角标;display 按 locale 解析。 */
+export function cellText(cell, locale) {
+    if (cell.value === null)
+        return MISSING_MARK;
+    const display = resolveLocalizedText(cell.display, locale);
+    return cell.samples < cell.total ? `${display} ${cell.samples}/${cell.total}` : display;
+}
+/** verdict 计票的紧凑文案("3 passed · 1 failed"):非零判定逐个列,全部为零如实 —。 */
+export function verdictTallyText(tally, locale) {
+    const parts = [];
+    for (const kind of ["passed", "failed", "errored", "skipped"]) {
+        if (tally[kind] > 0)
+            parts.push(`${tally[kind]} ${localeText(locale, `verdict.${kind}`)}`);
+    }
+    return parts.length > 0 ? parts.join(" · ") : MISSING_MARK;
+}

package/dist/report/components/shared.d.ts

@@ -0,0 +1,68 @@
+import type { ReactNode } from "react";
+import { type ReportComponent, type TextContext, type WebContext } from "../definition/tree.ts";
+import type { ReportInput } from "../model/types.ts";
+import type { ReportLocale } from "../model/locale.ts";
+import type { AttemptLocator } from "../../results/locator.ts";
+/** 拼 class 名:过滤空值,末尾接使用者透传的 className。 */
+export declare function cx(...parts: (string | undefined | false)[]): string;
+type Never<T> = {
+    [K in keyof T]?: never;
+};
+/**
+ * 官方数据组件的统一 props 组合(docs/feature/reports/library/metric-views.md):
+ * data 形态(接收配套 *Data 的产物)或 spec 形态(Options 平铺 + 可选 input)。
+ */
+export type DataProps<Data, Options, Presentation> = ({
+    data: Data;
+    input?: never;
+} & Never<Options> & Presentation) | ({
+    data?: never;
+    input?: ReportInput;
+} & Options & Presentation);
+export declare function isObject(value: unknown): value is Record<string, unknown>;
+/** LocalizedText = string | Record<string, string>(src/shared/types.ts)。 */
+export declare function isLocalizedText(value: unknown): boolean;
+/**
+ * 字段路径前缀的结构校验原语:通过为 `null`,否则给出带完整字段路径的具体问题
+ * (如 `"rows[2].cells.costUSD.samples" must be a number`)。每个族的 validate*Data
+ * 用这些原语递归拼自己的形状,不重新发明逐字段判断。
+ */
+export declare function cellProblem(value: unknown, path: string): string | null;
+export declare function isCell(value: unknown): boolean;
+/** 四态 tally { passed, failed, errored, skipped } 的字段路径前缀校验。 */
+export declare function tallyProblem(value: unknown, path: string): string | null;
+export declare function isTally(value: unknown): boolean;
+/** 数组的逐项校验:每项跑 `itemCheck(item, "path[i]")`,第一个非 null 问题即返回。 */
+export declare function arrayProblem(value: unknown, path: string, itemCheck: (item: unknown, itemPath: string) => string | null): string | null;
+export type Validator = (data: unknown) => string | null;
+export declare function dataShapeError(component: string, dataFnName: string, shape: string, problem: string): Error;
+export interface DataComponentDef<Data, Options, Presentation> {
+    name: string;
+    dataFnName: string;
+    shapeName: string;
+    dataFn: (input: ReportInput, options: Options) => Promise<Data>;
+    /** spec 形态的计算选项 prop 名(不含 input);未列出的 props 视为呈现选项原样保留。 */
+    specKeys: readonly string[];
+    validate: Validator;
+    web(props: {
+        data: Data;
+    } & Presentation, ctx: WebContext): ReactNode;
+    text(props: {
+        data: Data;
+    } & Presentation, ctx: TextContext): string;
+}
+export declare function makeDataComponent<Data, Options, Presentation>(def: DataComponentDef<Data, Options, Presentation>): ReportComponent<DataProps<Data, Options, Presentation>>;
+/**
+ * 缺省接证据室,显式 prop 覆盖。`ctx.attemptHref` 本身已经是「有没有」的完整信号——
+ * 宿主外直接渲染、或宿主内但当前 definition 没有 attempt-input page 时它就是 undefined,
+ * 不需要再判断是否在宿主里。
+ */
+export declare function hrefOf(props: {
+    attemptHref?: (locator: AttemptLocator) => string;
+}, ctx: WebContext): ((locator: AttemptLocator) => string) | undefined;
+export interface ChromeProps {
+    /** chrome 文案 locale;省略时随宿主上下文(宿主外默认 "en")。 */
+    locale?: ReportLocale;
+    className?: string;
+}
+export {};

package/dist/report/components/shared.js

@@ -0,0 +1,125 @@
+// 官方双面组件的共用装配机制:spec / data 双形态判别(DataProps)、data 结构校验的通用
+// 原语(isObject / isLocalizedText / isCell / isTally / cellProblem / tallyProblem /
+// arrayProblem / dataShapeError)、`makeDataComponent` 装配器与 `hrefOf` 证据室深链解析、
+// `ChromeProps` 呈现选项基类、`cx` classname 拼接——每个组件族在自己的 index.tsx 里用这些
+// 原语递归拼自己的 validate*Data(字段路径要覆盖到嵌套 MetricCell/Tally,不只顶层哨兵),
+// 具体的 validate*Data 与组件导出留在各族。
+import { defineComponent, memoFetchOf, } from "../definition/tree.js";
+/** 拼 class 名:过滤空值,末尾接使用者透传的 className。 */
+export function cx(...parts) {
+    return parts.filter(Boolean).join(" ");
+}
+// ───────────────────────── data 结构校验(版本漂移防线)─────────────────────────
+export function isObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** LocalizedText = string | Record<string, string>(src/shared/types.ts)。 */
+export function isLocalizedText(value) {
+    if (typeof value === "string")
+        return true;
+    return isObject(value) && Object.values(value).every((entry) => typeof entry === "string");
+}
+/**
+ * 字段路径前缀的结构校验原语:通过为 `null`,否则给出带完整字段路径的具体问题
+ * (如 `"rows[2].cells.costUSD.samples" must be a number`)。每个族的 validate*Data
+ * 用这些原语递归拼自己的形状,不重新发明逐字段判断。
+ */
+export function cellProblem(value, path) {
+    if (!isObject(value))
+        return `"${path}" must be a MetricCell { value, display, samples, total, refs }`;
+    if (!(value.value === null || typeof value.value === "number"))
+        return `"${path}.value" must be a number or null`;
+    if (!isLocalizedText(value.display))
+        return `"${path}.display" must be a LocalizedText`;
+    if (typeof value.samples !== "number")
+        return `"${path}.samples" must be a number`;
+    if (typeof value.total !== "number")
+        return `"${path}.total" must be a number`;
+    if (!Array.isArray(value.refs) || !value.refs.every((ref) => typeof ref === "string")) {
+        return `"${path}.refs" must be an array of locator strings`;
+    }
+    return null;
+}
+export function isCell(value) {
+    return cellProblem(value, "cell") === null;
+}
+/** 四态 tally { passed, failed, errored, skipped } 的字段路径前缀校验。 */
+export function tallyProblem(value, path) {
+    if (!isObject(value))
+        return `"${path}" must be a tally { passed, failed, errored, skipped }`;
+    for (const key of ["passed", "failed", "errored", "skipped"]) {
+        if (typeof value[key] !== "number")
+            return `"${path}.${key}" must be a number`;
+    }
+    return null;
+}
+export function isTally(value) {
+    return tallyProblem(value, "tally") === null;
+}
+/** 数组的逐项校验:每项跑 `itemCheck(item, "path[i]")`,第一个非 null 问题即返回。 */
+export function arrayProblem(value, path, itemCheck) {
+    if (!Array.isArray(value))
+        return `"${path}" must be an array`;
+    for (let i = 0; i < value.length; i++) {
+        const problem = itemCheck(value[i], `${path}[${i}]`);
+        if (problem !== null)
+            return problem;
+    }
+    return null;
+}
+export function dataShapeError(component, dataFnName, shape, problem) {
+    return new Error(`<${component}> received data that does not match the current ${shape} shape: ${problem}. ` +
+        `It may have been computed by a different niceeval version (component data carries no schemaVersion; the support window is same-version write and read). ` +
+        `Recompute it with ${dataFnName}() from this niceeval version, then re-render.`);
+}
+export function makeDataComponent(def) {
+    const assertData = (data) => {
+        const problem = def.validate(data);
+        if (problem !== null)
+            throw dataShapeError(def.name, def.dataFnName, def.shapeName, problem);
+        return data;
+    };
+    const resolve = async (props, ctx) => {
+        const givenSpec = def.specKeys.filter((key) => props[key] !== undefined);
+        if (props.data !== undefined) {
+            if (givenSpec.length > 0 || props.input !== undefined) {
+                const extras = [...givenSpec, ...(props.input !== undefined ? ["input"] : [])];
+                throw new Error(`<${def.name}> got both \`data\` and spec field${extras.length > 1 ? "s" : ""} (${extras.join(", ")}) — the two data sources are exclusive and niceeval will not silently pick one. ` +
+                    `Keep \`data\` (precomputed with ${def.dataFnName}()) and drop the spec fields, or drop \`data\` and let the pipeline compute from the spec.`);
+            }
+            assertData(props.data);
+            return props;
+        }
+        const options = {};
+        for (const key of givenSpec)
+            options[key] = props[key];
+        const input = props.input ?? ctx.input;
+        const data = await memoFetchOf(ctx)(def.dataFn, input, options, () => def.dataFn(input, options));
+        const rest = { ...props };
+        delete rest.input;
+        for (const key of def.specKeys)
+            delete rest[key];
+        return { ...rest, data };
+    };
+    const component = defineComponent({
+        resolve,
+        web: (props, ctx) => {
+            assertData(props.data);
+            return def.web(props, ctx);
+        },
+        text: (props, ctx) => {
+            assertData(props.data);
+            return def.text(props, ctx);
+        },
+    });
+    component.displayName = def.name;
+    return component;
+}
+/**
+ * 缺省接证据室,显式 prop 覆盖。`ctx.attemptHref` 本身已经是「有没有」的完整信号——
+ * 宿主外直接渲染、或宿主内但当前 definition 没有 attempt-input page 时它就是 undefined,
+ * 不需要再判断是否在宿主里。
+ */
+export function hrefOf(props, ctx) {
+    return props.attemptHref ?? ctx.attemptHref;
+}

package/dist/report/{react → components/site-components}/CopyFixPrompt.d.ts

@@ -1,6 +1,6 @@
 import type { ReactElement } from "react";
-import type { CopyFixPromptData } from "../types.ts";
-import { type ReportLocale } from "../locale.ts";
+import type { CopyFixPromptData } from "../../model/types.ts";
+import { type ReportLocale } from "../../model/locale.ts";
 /**
  * 批量修复 prompt(纯 web 渲染面):折叠块内完整 prompt 文本 + 复制按钮(增强层)。
  * 嵌入自有 React 页面时配合 `copyFixPromptData()` 使用;failures 为 0 返回 null。

package/dist/report/{react → components/site-components}/CopyFixPrompt.js

@@ -1,6 +1,6 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { DEFAULT_REPORT_LOCALE, countText, localeText } from "../locale.js";
-import { cx } from "./format.js";
+import { DEFAULT_REPORT_LOCALE, countText, localeText } from "../../model/locale.js";
+import { cx } from "../shared.js";
 /**
  * 批量修复 prompt(纯 web 渲染面):折叠块内完整 prompt 文本 + 复制按钮(增强层)。
  * 嵌入自有 React 页面时配合 `copyFixPromptData()` 使用;failures 为 0 返回 null。

package/dist/report/{react → components/site-components}/HeroCard.d.ts

@@ -1,6 +1,6 @@
 import type { ReactElement } from "react";
-import type { HeroData } from "../types.ts";
-import { type LocalizedText, type ReportLocale } from "../locale.ts";
+import type { HeroData } from "../../model/types.ts";
+import { type LocalizedText, type ReportLocale } from "../../model/locale.ts";
 /**
  * 站点标题区(纯 web 渲染面):`<h1>` 标题 + meta 行 + 品牌行。
  * 嵌入自有 React 页面时配合 `heroData()` 使用。

package/dist/report/{react → components/site-components}/HeroCard.js

@@ -1,6 +1,6 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { DEFAULT_REPORT_LOCALE, localeText, resolveLocalizedText } from "../locale.js";
-import { cx } from "./format.js";
+import { DEFAULT_REPORT_LOCALE, localeText, resolveLocalizedText } from "../../model/locale.js";
+import { cx } from "../shared.js";
 import { PoweredBy } from "./PoweredBy.js";
 /** ISO 时间 → 按 locale 的「最后运行」显示(年月日 时:分);不可解析原样返回。 */
 function formatLastRun(iso, locale) {

package/dist/report/{react → components/site-components}/ScopeWarnings.d.ts

@@ -1,6 +1,6 @@
 import type { ReactElement } from "react";
-import type { ScopeWarning } from "../types.ts";
-import { type ReportLocale } from "../locale.ts";
+import type { ScopeWarning } from "../../model/types.ts";
+import { type ReportLocale } from "../../model/locale.ts";
 /**
  * 选择警告区(纯 web 渲染面):按动作聚合的警告组。嵌入自有 React 页面时传
  * `data={scope.warnings}`;空集返回 null,不渲染空容器。

package/dist/report/{react → components/site-components}/ScopeWarnings.js

@@ -1,7 +1,7 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { DEFAULT_REPORT_LOCALE } from "../locale.js";
-import { groupScopeWarnings, warningDetailsLabel } from "../scope-warnings.js";
-import { cx } from "./format.js";
+import { DEFAULT_REPORT_LOCALE } from "../../model/locale.js";
+import { groupScopeWarnings, warningDetailsLabel } from "./scope-warnings.js";
+import { cx } from "../shared.js";
 /** 命令的可复制块:无 JS 时点击全选(user-select: all),enhance.js 在场时点击复制。 */
 function CommandBlock({ command }) {
     return (_jsx("code", { className: "nre-warning-command", "data-nre-copy": command, children: command }));