@inflexa-ai/harness 0.19.0 → 0.19.2

package/dist/report-model/reference-resolver.d.ts

@@ -71,9 +71,15 @@ export type ResolvedValue = {
  * The `Ok` channel carries the resolved value. The `Err` channel carries the `UnresolvedReference`,
  * which names the reason and the detail that a reference did not bind. The validator collects each such
  * `Err` into its report, thus a caller reads the reason as data and resolution never throws.
+ *
+ * `prepare` is an optional batch step that runs one time before the per-reference loop. A realization
+ * that reads storage groups the references by artifact, reads each file one time, and fills a cache.
+ * `resolve` then answers from the cache. The method is optional, thus a realization without it keeps the
+ * per-reference behavior and the extension breaks no caller.
  */
 export interface ReferenceResolver {
     resolve(reference: Reference, snapshot: ReportSnapshot): Promise<Result<ResolvedValue, UnresolvedReference>>;
+    prepare?(references: readonly Reference[], snapshot: ReportSnapshot): Promise<void>;
 }
 /**
  * Give back each name in `columns` that no row holds, in the order of `columns`.

package/dist/report-model/validate.js

@@ -54,6 +54,11 @@ export function checkChartEncoding(entry, value) {
  */
 export async function resolveDocumentReferences(sections, snapshot, resolver) {
     const { references } = walkBlocks(sections);
+    // A realization that reads storage batches its reads here, one time before the loop. It fills a cache
+    // that each `resolve` then answers from. A realization without `prepare` keeps the per-reference read.
+    if (resolver.prepare !== undefined) {
+        await resolver.prepare(references.map((entry) => entry.reference), snapshot);
+    }
     const resolved = await allWithConcurrency(references.map((entry) => () => resolver.resolve(entry.reference, snapshot).then((result) => ({ entry, result }))), RESOLUTION_CONCURRENCY);
     const failures = [];
     const resolvedByBlock = new Map();

package/dist/report-render/assets.d.ts

@@ -0,0 +1,42 @@
+/**
+ * The asset manifest of the page.
+ *
+ * The page loads its chart runtime and its fonts from the sibling `assets/` directory. Thus each entry
+ * names the staged file and the module specifier of its source. The caller resolves each specifier against
+ * its own installation, and it copies the bytes beside the page.
+ *
+ * The module holds data alone. The renderer reads no file, thus the page stays a pure function of its
+ * inputs.
+ */
+/** The directory of the staged assets, relative to the page. */
+export declare const ASSETS_DIR = "assets";
+/**
+ * One staged asset. `file` is the basename under the assets directory, and `specifier` is the module
+ * specifier of the source file inside the installed package.
+ */
+export interface PageAsset {
+    readonly file: string;
+    readonly specifier: string;
+}
+/** The relative source of a staged asset. The page directory is self-contained, thus the source is `assets/<file>`. */
+export declare function assetSource(asset: PageAsset): string;
+/** The chart runtime. The page-side bootstrap reads the `echarts` global that this file declares. */
+export declare const ECHARTS_ASSET: PageAsset;
+/** The sans font. The file is the latin subset of the variable font, thus one file carries each weight. */
+export declare const SANS_FONT_ASSET: PageAsset;
+/**
+ * The mono font at weight 400, for the body of a data cell.
+ *
+ * Fontsource publishes no variable IBM Plex Mono, thus each weight is a separate file and a separate entry.
+ * The identity uses four weights: 400 for a data cell, 500 for a tag, 600 for a table header and a badge,
+ * and 700 for a metric value.
+ */
+export declare const MONO_FONT_400_ASSET: PageAsset;
+/** The mono font at weight 500, for a tag and a stat-card label. */
+export declare const MONO_FONT_500_ASSET: PageAsset;
+/** The mono font at weight 600, for a table header, a section label, and the panel badge. */
+export declare const MONO_FONT_600_ASSET: PageAsset;
+/** The mono font at weight 700, for a metric value. */
+export declare const MONO_FONT_700_ASSET: PageAsset;
+/** Each asset that the caller stages beside the page. */
+export declare const PAGE_ASSETS: readonly PageAsset[];

package/dist/report-render/assets.js

@@ -0,0 +1,61 @@
+/**
+ * The asset manifest of the page.
+ *
+ * The page loads its chart runtime and its fonts from the sibling `assets/` directory. Thus each entry
+ * names the staged file and the module specifier of its source. The caller resolves each specifier against
+ * its own installation, and it copies the bytes beside the page.
+ *
+ * The module holds data alone. The renderer reads no file, thus the page stays a pure function of its
+ * inputs.
+ */
+/** The directory of the staged assets, relative to the page. */
+export const ASSETS_DIR = "assets";
+/** The relative source of a staged asset. The page directory is self-contained, thus the source is `assets/<file>`. */
+export function assetSource(asset) {
+    return `${ASSETS_DIR}/${asset.file}`;
+}
+/** The chart runtime. The page-side bootstrap reads the `echarts` global that this file declares. */
+export const ECHARTS_ASSET = {
+    file: "echarts.min.js",
+    specifier: "echarts/dist/echarts.min.js",
+};
+/** The sans font. The file is the latin subset of the variable font, thus one file carries each weight. */
+export const SANS_FONT_ASSET = {
+    file: "space-grotesk-latin-wght-normal.woff2",
+    specifier: "@fontsource-variable/space-grotesk/files/space-grotesk-latin-wght-normal.woff2",
+};
+/**
+ * The mono font at weight 400, for the body of a data cell.
+ *
+ * Fontsource publishes no variable IBM Plex Mono, thus each weight is a separate file and a separate entry.
+ * The identity uses four weights: 400 for a data cell, 500 for a tag, 600 for a table header and a badge,
+ * and 700 for a metric value.
+ */
+export const MONO_FONT_400_ASSET = {
+    file: "ibm-plex-mono-latin-400-normal.woff2",
+    specifier: "@fontsource/ibm-plex-mono/files/ibm-plex-mono-latin-400-normal.woff2",
+};
+/** The mono font at weight 500, for a tag and a stat-card label. */
+export const MONO_FONT_500_ASSET = {
+    file: "ibm-plex-mono-latin-500-normal.woff2",
+    specifier: "@fontsource/ibm-plex-mono/files/ibm-plex-mono-latin-500-normal.woff2",
+};
+/** The mono font at weight 600, for a table header, a section label, and the panel badge. */
+export const MONO_FONT_600_ASSET = {
+    file: "ibm-plex-mono-latin-600-normal.woff2",
+    specifier: "@fontsource/ibm-plex-mono/files/ibm-plex-mono-latin-600-normal.woff2",
+};
+/** The mono font at weight 700, for a metric value. */
+export const MONO_FONT_700_ASSET = {
+    file: "ibm-plex-mono-latin-700-normal.woff2",
+    specifier: "@fontsource/ibm-plex-mono/files/ibm-plex-mono-latin-700-normal.woff2",
+};
+/** Each asset that the caller stages beside the page. */
+export const PAGE_ASSETS = [
+    ECHARTS_ASSET,
+    SANS_FONT_ASSET,
+    MONO_FONT_400_ASSET,
+    MONO_FONT_500_ASSET,
+    MONO_FONT_600_ASSET,
+    MONO_FONT_700_ASSET,
+];

package/dist/report-render/chart.js

@@ -20,6 +20,23 @@ import { normalizeEchartSpec } from "../tools/display/normalize-echart-spec.js";
  * scale maps the low value to `#440154` and the high value to `#fde725`.
  */
 const VIRIDIS = ["#440154", "#482777", "#3e4989", "#31688e", "#26828e", "#1f9e89", "#35b779", "#6ece58", "#b5de2b", "#fde725"];
+/**
+ * The distance in pixels between the x axis line and its name.
+ *
+ * The name sits under the middle of the axis, thus the gap must clear the axis labels below the line. The
+ * value is a fixed constant, thus the derivation stays deterministic.
+ */
+const X_AXIS_NAME_GAP = 34;
+/**
+ * The name fields of an x axis.
+ *
+ * `normalizeEchartSpec` holds the grid to a right margin of 5 percent. The ECharts default `nameLocation`
+ * of `"end"` puts the name at the right end of the axis, thus the name runs past that margin and the panel
+ * clips it. A centered name sits under the middle of the axis, and no margin can cut it.
+ */
+function xAxisName(column) {
+    return { name: column, nameLocation: "middle", nameGap: X_AXIS_NAME_GAP };
+}
 /**
  * Derive the ECharts option for a chart block, then pass it through `normalizeEchartSpec`.
  *
@@ -68,7 +85,7 @@ function deriveBar(block, rows, columns) {
         data: groupRows.map((row) => [row[x], row[y]]),
     }));
     return ok({
-        xAxis: { type: "category", data: categories, name: x },
+        xAxis: { type: "category", data: categories, ...xAxisName(x) },
         yAxis: { type: "value", name: y },
         series,
     });
@@ -90,8 +107,8 @@ function deriveLine(block, rows, columns) {
         data: sortByX(groupRows.map((row) => [row[x], row[y]])),
     }));
     return ok({
-        xAxis: inferAxis(rows, x),
-        yAxis: inferAxis(rows, y),
+        xAxis: inferAxis(rows, x, "x"),
+        yAxis: inferAxis(rows, y, "y"),
         series,
     });
 }
@@ -113,8 +130,8 @@ function deriveScatter(block, rows, columns) {
         data: groupRows.map((row) => [row[x], row[y]]),
     }));
     return ok({
-        xAxis: inferAxis(rows, x),
-        yAxis: inferAxis(rows, y),
+        xAxis: inferAxis(rows, x, "x"),
+        yAxis: inferAxis(rows, y, "y"),
         series,
     });
 }
@@ -199,7 +216,7 @@ function deriveBox(block, rows, columns) {
         }
     }
     return ok({
-        xAxis: { type: "category", data: categories, name: x },
+        xAxis: { type: "category", data: categories, ...xAxisName(x) },
         yAxis: { type: "value", name: y },
         series,
     });
@@ -242,7 +259,7 @@ function deriveHeatmap(block, rows, columns) {
     const min = finite.length > 0 ? Math.min(...finite) : 0;
     const max = finite.length > 0 ? Math.max(...finite) : 1;
     return ok({
-        xAxis: { type: "category", data: xCategories.map(String), name: x, splitArea: { show: true } },
+        xAxis: { type: "category", data: xCategories.map(String), ...xAxisName(x), splitArea: { show: true } },
         yAxis: { type: "category", data: yCategories.map(String), name: y, splitArea: { show: true } },
         visualMap: {
             type: "continuous",
@@ -355,12 +372,16 @@ function numericColumn(rows, column) {
 /**
  * The axis for a line or a scatter column. A column with any non-numeric string cell is a category axis
  * with its distinct values as strings. Any other column is a value axis with `scale: true`.
+ *
+ * The `axis` argument names the channel that the column feeds. An x column takes the centered name, and a
+ * y column keeps the default name placement.
  */
-function inferAxis(rows, column) {
+function inferAxis(rows, column, axis) {
+    const nameFields = axis === "x" ? xAxisName(column) : { name: column };
     if (rows.some((row) => isNonNumericString(row[column]))) {
-        return { type: "category", data: firstAppearance(rows.map((row) => row[column])).map(String), name: column };
+        return { type: "category", data: firstAppearance(rows.map((row) => row[column])).map(String), ...nameFields };
     }
-    return { type: "value", scale: true, name: column };
+    return { type: "value", scale: true, ...nameFields };
 }
 /**
  * Build one series per group, in first-appearance order of the group values. A chart with no group

package/dist/report-render/design.d.ts

@@ -0,0 +1,120 @@
+/**
+ * The design sheet of the report page, and the ECharts theme.
+ *
+ * The page carries no external stylesheet and no CSS framework. Thus this module holds the whole identity:
+ * the tokens, the font faces, the typography, the components, the textures, the motion rules, and the print
+ * rules. The identity source is the Inflexa design system.
+ *
+ * Two invariants bind an edit of the sheet:
+ *
+ * - Each class rule matches a class that one view emits. A rule with no emitter is dead, and a dead rule is
+ *   a cost with no visible effect.
+ * - Each font URL comes from the asset manifest. Thus the sheet and the stage step of the caller cannot
+ *   disagree over a file name.
+ *
+ * The token block is the exception to the first invariant. The token set is the contract of the identity,
+ * thus it stays complete even where no current rule reads a token.
+ */
+/** The style rules of the page. The renderer inlines them in one `<style>` block. */
+export declare const DESIGN_CSS: string;
+/**
+ * The registered name of the ECharts theme. The registration script writes this name, and the bootstrap
+ * reads it. One source prevents a silent mismatch between the two sites.
+ */
+export declare const ECHARTS_THEME_NAME = "inflexa";
+/**
+ * The ECharts theme as a plain object. The renderer serializes this object and registers it, thus the theme
+ * never rides a JSON file and no run-time read is necessary. The palette and the axis styles mirror the
+ * light design tokens above.
+ */
+export declare const ECHARTS_THEME: {
+    color: string[];
+    backgroundColor: string;
+    textStyle: {
+        fontFamily: string;
+        fontSize: number;
+        color: string;
+    };
+    title: {
+        show: boolean;
+    };
+    legend: {
+        bottom: number;
+        textStyle: {
+            fontSize: number;
+            color: string;
+        };
+        itemGap: number;
+        itemWidth: number;
+        itemHeight: number;
+    };
+    grid: {
+        left: number;
+        right: number;
+        top: number;
+        bottom: number;
+        containLabel: boolean;
+    };
+    tooltip: {
+        backgroundColor: string;
+        borderColor: string;
+        textStyle: {
+            color: string;
+            fontSize: number;
+        };
+        extraCssText: string;
+    };
+    toolbox: {
+        feature: {
+            saveAsImage: {
+                title: string;
+                pixelRatio: number;
+            };
+        };
+        iconStyle: {
+            borderColor: string;
+        };
+        right: number;
+        top: number;
+    };
+    xAxis: {
+        axisLine: {
+            lineStyle: {
+                color: string;
+            };
+        };
+        axisTick: {
+            lineStyle: {
+                color: string;
+            };
+        };
+        axisLabel: {
+            color: string;
+            fontSize: number;
+        };
+        splitLine: {
+            lineStyle: {
+                color: string;
+                type: string;
+            };
+        };
+    };
+    yAxis: {
+        axisLine: {
+            show: boolean;
+        };
+        axisTick: {
+            show: boolean;
+        };
+        axisLabel: {
+            color: string;
+            fontSize: number;
+        };
+        splitLine: {
+            lineStyle: {
+                color: string;
+                type: string;
+            };
+        };
+    };
+};