niceeval 0.9.0 → 0.10.0

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

@@ -0,0 +1,381 @@
+// 指标图形族(MetricTable / MetricMatrix / MetricBars / Scoreboard / MetricScatter /
+// MetricLine / DeltaTable)的 text 面:同一份算好的数据,渲染成终端字符
+// (niceeval show 的形态)。与 web 面共守诚实契约:排序随 better、samples < total 角标、
+// 缺数据 — 不补 0、截断报剩余。零 react、零 IO、纯同步。
+import { formatMetricValue, formatPlainNumber } from "../../model/format.js";
+import { countText, localeText, resolveLocalizedText, resolveMetricLabel } from "../../model/locale.js";
+import { padDisplay, stringWidth, textBar } from "../../model/text-layout.js";
+import { renderTableText } from "../../definition/table-text.js";
+import { renderCharPlot, renderCoordinateTable } from "./plot.js";
+import { cellText, missingText, MISSING_MARK } from "../shared-faces.js";
+// ───────────────────────── MetricTable ─────────────────────────
+export function tableText(data, ctx) {
+    const locale = ctx.locale;
+    const columns = [
+        { key: "dimension", header: data.rowDimension },
+        // 指标列的键用序号,不用 metric name —— 维度名和指标名在同一个命名空间里,可能撞键。
+        ...data.columns.map((c, i) => ({ key: `metric${i}`, header: resolveMetricLabel(c.label, locale, c.key) })),
+    ];
+    const rows = data.rows.map((row) => {
+        const cells = { dimension: row.key };
+        data.columns.forEach((col, i) => {
+            const cell = row.cells[col.key];
+            cells[`metric${i}`] = cell ? cellText(cell, locale) : null;
+        });
+        return { key: row.key, cells };
+    });
+    return renderTableText({ columns: columns, rows, locale }, ctx);
+}
+// ───────────────────────── MetricMatrix ─────────────────────────
+export function matrixText(data, ctx) {
+    // 表体全是维度键与 display,没有 chrome 文案;"next:" 是命令提示,不本地化。
+    const locale = ctx.locale;
+    const rowKeys = [];
+    const columnKeys = [];
+    const byPosition = new Map();
+    for (const entry of data.cells) {
+        if (!rowKeys.includes(entry.row))
+            rowKeys.push(entry.row);
+        if (!columnKeys.includes(entry.column))
+            columnKeys.push(entry.column);
+        byPosition.set(JSON.stringify([entry.row, entry.column]), entry.cell);
+    }
+    const columns = [
+        { key: "dimension", header: data.rowDimension },
+        ...columnKeys.map((column, i) => ({ key: `column${i}`, header: column })),
+    ];
+    const rows = rowKeys.map((row) => {
+        const cells = { dimension: row };
+        columnKeys.forEach((column, i) => {
+            const cell = byPosition.get(JSON.stringify([row, column]));
+            cells[`column${i}`] = cell ? cellText(cell, locale) : null; // 稀疏格子在文本里以 — 呈现,不编数
+        });
+        return { key: row, cells };
+    });
+    const table = renderTableText({ columns: columns, rows, locale }, ctx);
+    // 下钻命令:行维度是 eval 时,指向最值得看的一行(先挑有缺格的,再挑按 better 最差的)
+    if (data.rowDimension !== "eval" || rowKeys.length === 0)
+        return table;
+    const better = data.metric.better ?? "higher";
+    let next;
+    let worst;
+    for (const row of rowKeys) {
+        let sum = 0;
+        let count = 0;
+        for (const column of columnKeys) {
+            const cell = byPosition.get(JSON.stringify([row, column]));
+            if (!cell || cell.value === null) {
+                next ??= row;
+                continue;
+            }
+            sum += cell.value;
+            count += 1;
+        }
+        if (count > 0) {
+            const value = sum / count;
+            const isWorse = worst === undefined || (better === "higher" ? value < worst.value : value > worst.value);
+            if (isWorse)
+                worst = { key: row, value };
+        }
+    }
+    next ??= worst?.key;
+    return next === undefined ? table : `${table}\n\nnext: niceeval show ${next}`;
+}
+// ───────────────────────── MetricBars(矩阵数据的另一种摆法)─────────────────────────
+const BAR_WIDTH = 20;
+export function barsText(data, ctx) {
+    const locale = ctx.locale;
+    const groupKeys = [];
+    const seriesKeys = [];
+    const byPosition = new Map();
+    for (const entry of data.cells) {
+        if (!groupKeys.includes(entry.row))
+            groupKeys.push(entry.row);
+        if (!seriesKeys.includes(entry.column))
+            seriesKeys.push(entry.column);
+        byPosition.set(JSON.stringify([entry.row, entry.column]), entry.cell);
+    }
+    const better = data.metric.better ?? "higher";
+    // 条长刻度:% 的天然域是 [0,1],其余以全图最大值为满条
+    const values = data.cells.map((c) => c.cell.value).filter((v) => v !== null);
+    const maxValue = values.length > 0 ? Math.max(...values) : 0;
+    const ratioOf = (value) => (data.metric.unit === "%" ? value : maxValue === 0 ? 0 : value / maxValue);
+    const seriesWidth = Math.max(...seriesKeys.map((k) => stringWidth(k)), 0);
+    const lines = [];
+    for (const group of groupKeys) {
+        lines.push(group);
+        const entries = seriesKeys.map((series) => ({
+            series,
+            cell: byPosition.get(JSON.stringify([group, series])),
+        }));
+        // 组内按值排序,方向随 better(缺数据沉底)
+        entries.sort((a, b) => {
+            const va = a.cell?.value ?? null;
+            const vb = b.cell?.value ?? null;
+            if (va === null && vb === null)
+                return 0;
+            if (va === null)
+                return 1;
+            if (vb === null)
+                return -1;
+            return better === "lower" ? va - vb : vb - va;
+        });
+        for (const { series, cell } of entries) {
+            const label = padDisplay(series, seriesWidth);
+            if (!cell || cell.value === null) {
+                lines.push(`  ${label}   ${MISSING_MARK}`);
+                continue;
+            }
+            lines.push(`  ${label}   ${textBar(ratioOf(cell.value), BAR_WIDTH)}  ${cellText(cell, locale)}`);
+        }
+    }
+    return lines.join("\n");
+}
+// ───────────────────────── Scoreboard ─────────────────────────
+export function scoreboardText(data, ctx) {
+    const locale = ctx.locale;
+    const subjectKeys = [];
+    for (const row of data.rows) {
+        for (const subject of row.subjects) {
+            if (!subjectKeys.includes(subject.key))
+                subjectKeys.push(subject.key);
+        }
+    }
+    const columns = [
+        { key: "dimension", header: data.rowDimension },
+        { key: "total", header: localeText(locale, "scoreboard.totalText") },
+        ...subjectKeys.map((key, i) => ({ key: `subject${i}`, header: key })),
+    ];
+    const rows = data.rows.map((row) => {
+        const totalNotes = [
+            ...(row.total.notRun > 0 ? [localeText(locale, "scoreboard.notRunText", { n: row.total.notRun })] : []),
+            ...(row.total.unscorable > 0 ? [localeText(locale, "scoreboard.unscorableText", { n: row.total.unscorable })] : []),
+        ];
+        const cells = {
+            dimension: row.key,
+            total: `${resolveLocalizedText(row.total.display, locale)}/${data.fullMarks}${totalNotes.length > 0 ? ` ${totalNotes.join(" ")}` : ""}`,
+        };
+        subjectKeys.forEach((key, i) => {
+            const subject = row.subjects.find((s) => s.key === key);
+            if (!subject) {
+                cells[`subject${i}`] = null;
+                return;
+            }
+            const score = `${formatPlainNumber(subject.earned)}/${formatPlainNumber(subject.possible)}`;
+            const notes = [
+                ...(subject.notRun > 0 ? [localeText(locale, "scoreboard.notRunText", { n: subject.notRun })] : []),
+                ...(subject.unscorable > 0 ? [localeText(locale, "scoreboard.unscorableText", { n: subject.unscorable })] : []),
+            ];
+            cells[`subject${i}`] = notes.length > 0 ? `${score} ${notes.join(" ")}` : score;
+        });
+        return { key: row.key, cells };
+    });
+    const table = renderTableText({ columns: columns, rows, locale }, ctx);
+    const footnotes = [];
+    if (data.weights.length > 0) {
+        const weights = data.weights.map((w) => `${w.prefix} ×${w.weight}`).join(" · ");
+        footnotes.push(`${localeText(locale, "scoreboard.weights")} ${weights} · ${localeText(locale, "scoreboard.othersWeight")}`);
+    }
+    if (data.ignoredEvals > 0)
+        footnotes.push(countText(locale, "scoreboard.ignored", data.ignoredEvals));
+    return footnotes.length > 0 ? `${table}\n${footnotes.join("\n")}` : table;
+}
+// ───────────────────────── MetricScatter ─────────────────────────
+const POINT_MARKS = "ABCDEFGHIJKLMNOPQRSTUVWXYZ";
+function axisLabel(col, locale) {
+    return resolveMetricLabel(col.label, locale, col.key);
+}
+/**
+ * 方向提示:轴向已随 better 反正(lower 反向),「更好」恒指向右上,文案恒为
+ * 「越靠右上越好」;仅当 x、y 都声明 better 时显示——任一轴未声明,组件不猜
+ * 「更好」朝哪边,整图无提示(返回 undefined)。
+ */
+function betterCornerText(x, y, locale) {
+    if (x.better === undefined || y.better === undefined)
+        return undefined;
+    return localeText(locale, "scatter.betterUpperRight");
+}
+/** 轴标题行:"<x label>(越低越好) × <y label>"——better 方向如实标注,不虚构轴向。 */
+function scatterHeading(data, locale) {
+    const withBetter = (col) => {
+        const label = axisLabel(col, locale);
+        if (col.better === undefined)
+            return label;
+        return `${label}(${localeText(locale, col.better === "lower" ? "table.lowerBetter" : "table.higherBetter")})`;
+    };
+    return `${withBetter(data.x)} × ${withBetter(data.y)}`;
+}
+/** 位移摘要里的带符号差值;`%` 的差是百分点,单位写 pt(docs/feature/reports/show/default-report.md)。 */
+function signedDelta(value, unit) {
+    const text = formatMetricValue(value, unit);
+    const signed = value >= 0 ? `+${text}` : text;
+    return unit === "%" ? signed.replace("%", "pt") : signed;
+}
+export function scatterText(data, ctx, opts) {
+    const locale = ctx.locale;
+    const connect = opts?.connect === true && data.seriesDimension !== undefined;
+    const drawable = data.rows.filter((r) => r.x.value !== null && r.y.value !== null);
+    const missing = data.rows.length - drawable.length;
+    const footnotes = [];
+    if (missing > 0)
+        footnotes.push(countText(locale, "pointsMissing", missing));
+    const axes = { x: axisLabel(data.x, locale), y: axisLabel(data.y, locale) };
+    // 0 个可画点:x/y 指标没有可用数据(与 web 面同一事实)。
+    if (drawable.length === 0) {
+        return [localeText(locale, "scatter.noData", axes), ...footnotes].join("\n");
+    }
+    // 标题行尾标注归类维度(· 按 <series> 归类)。
+    const heading = data.seriesDimension !== undefined
+        ? `${scatterHeading(data, locale)} · ${localeText(locale, "scatter.groupedBy", { dim: data.seriesDimension })}`
+        : scatterHeading(data, locale);
+    // 标记分配顺序即图例顺序:series 按显示键字典序、series 内按 x 原始值升序;
+    // 无 series 时保持点键字典序(rows 本身已按维度 key 排序)。
+    const ordered = data.seriesDimension === undefined
+        ? drawable
+        : [...drawable].sort((a, b) => {
+            const sa = a.series ?? "";
+            const sb = b.series ?? "";
+            if (sa !== sb)
+                return sa < sb ? -1 : 1;
+            return a.x.value - b.x.value;
+        });
+    // 点太密排不下时降级为坐标表,不硬挤
+    if (ordered.length > POINT_MARKS.length || ctx.width < 44) {
+        const table = renderCoordinateTable(ordered.map((r) => ({
+            key: r.key,
+            x: resolveLocalizedText(r.x.display, locale),
+            y: resolveLocalizedText(r.y.display, locale),
+        })), { key: data.pointDimension, x: axes.x, y: axes.y });
+        return [heading, "", table, ...footnotes].join("\n");
+    }
+    const points = ordered.map((r, i) => ({
+        mark: POINT_MARKS[i],
+        x: r.x.value,
+        y: r.y.value,
+    }));
+    // series 分组(ordered 已按 series、x 排好序);connect 的折线只进 web 面,
+    // text 面用图例的 → 串联 + 位移摘要表达同一条线,坐标图内不画折线。
+    const rowsBySeries = new Map();
+    for (const r of ordered) {
+        if (r.series === undefined)
+            continue;
+        const list = rowsBySeries.get(r.series) ?? [];
+        list.push(r);
+        rowsBySeries.set(r.series, list);
+    }
+    const plot = renderCharPlot({
+        width: ctx.width,
+        points,
+        lines: [],
+        xLabel: axes.x,
+        yLabel: axes.y,
+        formatX: (v) => formatMetricValue(v, data.x.unit),
+        formatY: (v) => formatMetricValue(v, data.y.unit),
+        // 轴方向跟随 better(与 web 面同规则):lower 反向,higher 与未声明正向。
+        invertX: data.x.better === "lower",
+        invertY: data.y.better === "lower",
+    });
+    const markByKey = new Map(ordered.map((r, i) => [r.key, POINT_MARKS[i]]));
+    let legend;
+    if (data.seriesDimension === undefined) {
+        legend = ordered.map((r) => `${markByKey.get(r.key)} ${r.key}`).join("   ");
+    }
+    else {
+        // 图例一行一个 series:行首 series 显示键,后接线上各点;connect 用 → 串联并给逐段位移摘要。
+        const seriesWidth = Math.max(...[...rowsBySeries.keys()].map(stringWidth));
+        const lines = [];
+        for (const [series, list] of rowsBySeries) {
+            const parts = list.map((r) => `${markByKey.get(r.key)} ${r.key}`);
+            lines.push(`${padDisplay(series, seriesWidth)}  ${parts.join(connect ? " → " : "   ")}`);
+            if (connect) {
+                for (let i = 1; i < list.length; i++) {
+                    const a = list[i - 1];
+                    const b = list[i];
+                    const dy = signedDelta(b.y.value - a.y.value, data.y.unit);
+                    const dx = signedDelta(b.x.value - a.x.value, data.x.unit);
+                    lines.push(`${" ".repeat(seriesWidth + 2)}└ ${axes.y} ${dy} · ${axes.x} ${dx}`);
+                }
+            }
+        }
+        legend = lines.join("\n");
+    }
+    const hint = betterCornerText(data.x, data.y, locale);
+    return [heading, plot, "", ...(hint !== undefined ? [hint] : []), legend, ...footnotes].join("\n");
+}
+// ───────────────────────── MetricLine ─────────────────────────
+export function lineText(data, ctx) {
+    const locale = ctx.locale;
+    const drawable = data.rows.filter((r) => r.x !== null && r.y.value !== null);
+    const missing = data.rows.length - drawable.length;
+    const footnotes = [];
+    if (missing > 0)
+        footnotes.push(countText(locale, "pointsMissing", missing));
+    if (drawable.length === 0)
+        return [missingText(locale), ...footnotes].join("\n");
+    const xLabel = resolveMetricLabel(data.x.label, locale, data.x.key);
+    // 系列 → 字母;无系列 = 单系列
+    const seriesKeys = [];
+    for (const r of drawable) {
+        const key = r.series ?? "";
+        if (!seriesKeys.includes(key))
+            seriesKeys.push(key);
+    }
+    if (seriesKeys.length > POINT_MARKS.length || ctx.width < 44) {
+        const table = renderCoordinateTable(drawable.map((r) => ({
+            key: r.series !== undefined ? `${r.series} (${r.key})` : r.key,
+            x: resolveLocalizedText(r.xDisplay, locale),
+            y: resolveLocalizedText(r.y.display, locale),
+        })), { key: data.seriesDimension ?? xLabel, x: xLabel, y: axisLabel(data.y, locale) });
+        return [table, ...footnotes].join("\n");
+    }
+    const markOf = (r) => POINT_MARKS[seriesKeys.indexOf(r.series ?? "")];
+    const points = drawable.map((r) => ({
+        mark: markOf(r),
+        x: r.x,
+        y: r.y.value,
+    }));
+    const lines = seriesKeys.map((key) => drawable
+        .filter((r) => (r.series ?? "") === key)
+        .map((r) => ({ x: r.x, y: r.y.value }))
+        .sort((a, b) => a.x - b.x));
+    const plot = renderCharPlot({
+        width: ctx.width,
+        points,
+        lines: lines.filter((l) => l.length > 1),
+        xLabel,
+        yLabel: axisLabel(data.y, locale),
+        formatX: (v) => formatMetricValue(v, data.x.unit),
+        formatY: (v) => formatMetricValue(v, data.y.unit),
+    });
+    const legend = seriesKeys
+        .map((key, i) => `${POINT_MARKS[i]} ${key === "" ? axisLabel(data.y, locale) : key}`)
+        .join("   ");
+    return [plot, "", legend, ...footnotes].join("\n");
+}
+// ───────────────────────── DeltaTable ─────────────────────────
+export function deltaText(data, ctx) {
+    const locale = ctx.locale;
+    // 0 对不是错误:明确空态并报告配对域实验数(派生形态携带;字面形态缺省按 0)。
+    if (data.rows.length === 0) {
+        return localeText(locale, "delta.empty", { experiments: data.experiments ?? 0 });
+    }
+    const columns = [
+        { key: "pair", header: localeText(locale, "delta.pairHeader") },
+        ...data.columns.map((c, i) => ({ key: `metric${i}`, header: resolveMetricLabel(c.label, locale, c.key) })),
+    ];
+    const rows = data.rows.map((row) => {
+        const cells = { pair: resolveLocalizedText(row.label, locale) };
+        data.columns.forEach((col, i) => {
+            const cell = row.cells[col.key];
+            if (!cell) {
+                cells[`metric${i}`] = null;
+                return;
+            }
+            const a = cell.a.value === null ? MISSING_MARK : resolveLocalizedText(cell.a.display, locale);
+            const b = cell.b.value === null ? MISSING_MARK : resolveLocalizedText(cell.b.display, locale);
+            cells[`metric${i}`] = `${a} → ${b}   ${resolveLocalizedText(cell.display, locale)}`;
+        });
+        return { key: row.key, cells };
+    });
+    return renderTableText({ columns: columns, rows, locale }, ctx);
+}

package/dist/report/components/metric-views/index.d.ts

@@ -0,0 +1,50 @@
+import type { ReportComponent } from "../../definition/tree.ts";
+import type { DeltaData, LineData, MatrixData, ScatterData, ScoreboardData, TableData } from "../../model/types.ts";
+import type { AttemptLocator } from "../../../results/locator.ts";
+import { type ChromeProps, type DataProps, type Validator } from "../shared.ts";
+import { type DeltaTableOptions, type MetricLineOptions, type MetricMatrixOptions, type MetricScatterOptions, type MetricTableOptions, type ScoreboardOptions } from "./compute.ts";
+export declare const validateTableData: Validator;
+export declare const validateMatrixData: Validator;
+export declare const validateScatterData: Validator;
+export declare const validateLineData: Validator;
+export declare const validateScoreboardData: Validator;
+export declare const validateDeltaData: Validator;
+export type MetricTableProps = DataProps<TableData, MetricTableOptions, ChromeProps & {
+    /** web 面在表格前渲染过滤输入框(enhance.js 接管);无 JS 时表格内容依旧完整。 */
+    filter?: boolean;
+    attemptHref?: (locator: AttemptLocator) => string;
+}>;
+/** 榜单:一行一个维度值、一列一个指标,回答「谁整体更好」。 */
+export declare const MetricTable: ReportComponent<MetricTableProps>;
+export type MetricMatrixProps = DataProps<MatrixData, MetricMatrixOptions, ChromeProps & {
+    attemptHref?: (locator: AttemptLocator) => string;
+}>;
+export type MetricBarsProps = MetricMatrixProps;
+/** 逐题格子:行 × 列两个维度、格子里一个指标,回答「哪道题谁挂了」。 */
+export declare const MetricMatrix: ReportComponent<MetricMatrixProps>;
+/** 分组条形:同一份矩阵数据的另一种摆法;与 MetricMatrix 写同一份 spec 时只计算一次。 */
+export declare const MetricBars: ReportComponent<MetricBarsProps>;
+export type ScoreboardProps = DataProps<ScoreboardData, ScoreboardOptions, ChromeProps & {
+    attemptHref?: (locator: AttemptLocator) => string;
+}>;
+/** 考试成绩单:总分 + 分科小计,固定分母、notRun / unscorable 分开如实报。 */
+export declare const Scoreboard: ReportComponent<ScoreboardProps>;
+type ScatterChrome = ChromeProps & {
+    /** series 内按 x 升序成线(呈现,不改变 ScatterData):web 面画折线,text 面在图例给逐段位移摘要;默认 false。 */
+    connect?: boolean;
+    pointHref?: (row: ScatterData["rows"][number]) => string;
+};
+export type MetricScatterProps = DataProps<ScatterData, MetricScatterOptions, ScatterChrome>;
+/** 两个指标之间的取舍:每个点一个维度值,x / y 各一个指标,series 决定颜色和图例归类。 */
+export declare const MetricScatter: ReportComponent<MetricScatterProps>;
+export type MetricLineProps = DataProps<LineData, MetricLineOptions, ChromeProps & {
+    pointHref?: (row: LineData["rows"][number]) => string;
+}>;
+/** 趋势线:x 是 NumericAxis(参数轴),点身份 = (series, x)。 */
+export declare const MetricLine: ReportComponent<MetricLineProps>;
+export type DeltaTableProps = DataProps<DeltaData, DeltaTableOptions, ChromeProps & {
+    attemptHref?: (locator: AttemptLocator) => string;
+}>;
+/** 成对对比:每行一对(字面声明或 pairsByFlag 派生),格子里 A、B、Δ 三个值。 */
+export declare const DeltaTable: ReportComponent<DeltaTableProps>;
+export {};