@schalkneethling/miyagi-core 4.6.2 → 4.8.0

package/lib/performance/measure.js

@@ -0,0 +1,124 @@
+/**
+ * Measure on-disk, gzip-compressed, and brotli-compressed sizes of files.
+ * Transfer size is what a user actually downloads, which is almost never the raw
+ * on-disk size — gzip and brotli are reported alongside raw so users can see all
+ * three and pick the metric their hosting actually serves.
+ * We measure whichever files the user has configured in their assets — source
+ * files, bundled output from esbuild/rollup/webpack, or anything else. Point
+ * `config.assets` at the files you actually ship and the budget reflects reality.
+ * Results are cached by absolute path + mtime. In dev the file watcher changes
+ * the mtime on every save, naturally invalidating the cache.
+ * @module performance/measure
+ */
+
+import fs from "node:fs";
+import zlib from "node:zlib";
+
+const cache = new Map();
+
+/**
+ * @typedef {object} FileMeasurement
+ * @property {string} path - absolute path
+ * @property {number} raw - on-disk byte length
+ * @property {number} gzip - gzip-compressed byte length
+ * @property {number} brotli - brotli-compressed byte length
+ * @property {boolean} [missing] - true when the file could not be read
+ */
+
+/**
+ * @typedef {object} CategoryMeasurement
+ * @property {FileMeasurement[]} files - per-file measurements in this category
+ * @property {{raw: number, gzip: number, brotli: number}} totals - sum across files
+ */
+
+/**
+ * @typedef {object} Measurement
+ * @property {Record<string, CategoryMeasurement>} categories - keyed by category name
+ * @property {{raw: number, gzip: number, brotli: number}} totals - sum across categories
+ */
+
+/**
+ * Clear the cached results. Intended for tests and for watcher-driven
+ * whole-state refreshes.
+ * @returns {void}
+ */
+export function clearMeasureCache() {
+  cache.clear();
+}
+
+/**
+ * @param {string} absPath
+ * @returns {FileMeasurement}
+ */
+function measureFile(absPath) {
+  // Open a file descriptor first, then stat and read through it. This avoids
+  // a race where the file is modified between stat and read — both operations
+  // now refer to the same version of the file.
+  let fd;
+  try {
+    fd = fs.openSync(absPath, "r");
+  } catch {
+    return { path: absPath, raw: 0, gzip: 0, brotli: 0, missing: true };
+  }
+
+  let stat;
+  let buffer;
+  try {
+    stat = fs.fstatSync(fd);
+    buffer = Buffer.alloc(stat.size);
+    fs.readSync(fd, buffer, 0, stat.size, 0);
+  } catch {
+    fs.closeSync(fd);
+    return { path: absPath, raw: 0, gzip: 0, brotli: 0, missing: true };
+  }
+  fs.closeSync(fd);
+
+  const cacheKey = `${absPath}:${stat.mtimeMs}:${stat.size}`;
+  const cached = cache.get(cacheKey);
+  if (cached) {
+    return cached;
+  }
+  const measurement = {
+    path: absPath,
+    raw: buffer.byteLength,
+    gzip: zlib.gzipSync(buffer).byteLength,
+    // Brotli default is text mode with maximum quality which is _very_ slow on
+    // large files; use quality 6 to approximate what a CDN typically serves.
+    brotli: zlib.brotliCompressSync(buffer, {
+      params: { [zlib.constants.BROTLI_PARAM_QUALITY]: 6 },
+    }).byteLength,
+  };
+
+  cache.set(cacheKey, measurement);
+  return measurement;
+}
+
+/**
+ * Measure a set of categorised file lists.
+ * @param {{category: string, files: string[]}[]} categorised
+ * @returns {Measurement}
+ */
+export function measure(categorised) {
+  /** @type {Record<string, CategoryMeasurement>} */
+  const categories = {};
+  const grand = { raw: 0, gzip: 0, brotli: 0 };
+
+  for (const { category, files } of categorised) {
+    const measured = files.map((absPath) => measureFile(absPath));
+    const totals = measured.reduce(
+      (acc, file) => ({
+        raw: acc.raw + file.raw,
+        gzip: acc.gzip + file.gzip,
+        brotli: acc.brotli + file.brotli,
+      }),
+      { raw: 0, gzip: 0, brotli: 0 },
+    );
+
+    categories[category] = { files: measured, totals };
+    grand.raw += totals.raw;
+    grand.gzip += totals.gzip;
+    grand.brotli += totals.brotli;
+  }
+
+  return { categories, totals: grand };
+}

package/lib/performance/parse-size.js

@@ -0,0 +1,86 @@
+/**
+ * Human-friendly size parser for performance budgets.
+ * Accepts either a bare number (bytes) or a string with a SI-ish unit suffix.
+ * Recognised units (case-insensitive): B, kB, KB, MB, GB. The number may be
+ * a decimal (e.g. "1.5 MB") and whitespace between number and unit is optional.
+ * Uses the decimal convention (1 kB = 1000 B) because that is what web performance
+ * budgets are traditionally expressed in — it matches the web.dev budget guidance
+ * and the way transfer sizes are reported in browser devtools.
+ * @module performance/parse-size
+ */
+
+const ONE_KILOBYTE = 1000;
+const ONE_MEGABYTE = 1000 * 1000;
+const ONE_GIGABYTE = 1000 * 1000 * 1000;
+
+const UNIT_MULTIPLIERS = {
+  b: 1,
+  kb: ONE_KILOBYTE,
+  mb: ONE_MEGABYTE,
+  gb: ONE_GIGABYTE,
+};
+
+/**
+ * Parse a size value into bytes.
+ * @param {string|number|null|undefined} value
+ * @returns {number|null} bytes, or null when value is null/undefined
+ * @throws {TypeError} if value cannot be parsed
+ */
+export default function parseSize(value) {
+  if (value == null) {
+    return null;
+  }
+
+  if (typeof value === "number") {
+    if (!Number.isFinite(value) || value < 0) {
+      throw new TypeError(`Invalid size value: ${value}`);
+    }
+
+    return Math.round(value);
+  }
+
+  if (typeof value !== "string") {
+    throw new TypeError(`Invalid size value: ${value}`);
+  }
+
+  const trimmed = value.trim();
+  // Match a number (integer or decimal) optionally followed by a unit suffix.
+  // Examples: "50", "1.5 kB", "200MB", "2048 B"
+  //   Group 1: the numeric part (e.g. "1.5")
+  //   Group 2: the unit part, may be empty (e.g. "kB", "MB", or "")
+  const match = trimmed.match(/^(\d+(?:\.\d+)?)\s*([a-zA-Z]*)$/);
+
+  if (!match) {
+    throw new TypeError(`Invalid size value: ${value}`);
+  }
+
+  const amount = Number.parseFloat(match[1]);
+  const unit = (match[2] || "b").toLowerCase();
+
+  if (!(unit in UNIT_MULTIPLIERS)) {
+    throw new TypeError(`Unknown size unit "${match[2]}" in "${value}"`);
+  }
+
+  return Math.round(amount * UNIT_MULTIPLIERS[unit]);
+}
+
+/**
+ * Format a number of bytes as a human-friendly string (for display / reports).
+ * @param {number|null} bytes
+ * @returns {string}
+ */
+export function formatSize(bytes) {
+  if (bytes == null) {
+    return "—";
+  }
+
+  if (bytes < ONE_KILOBYTE) {
+    return `${bytes} B`;
+  }
+
+  if (bytes < ONE_MEGABYTE) {
+    return `${(bytes / ONE_KILOBYTE).toFixed(2)} kB`;
+  }
+
+  return `${(bytes / ONE_MEGABYTE).toFixed(2)} MB`;
+}

package/lib/performance/report.js

@@ -0,0 +1,102 @@
+/**
+ * Generate a Markdown performance-budget report.
+ * Mirrors the shape of lib/validator/html-report.js so the two read the same at
+ * a glance: one summary table, then per-category detail tables. The report is
+ * a stable artefact that can be committed by CI or linked from PRs.
+ * @module performance/report
+ */
+
+import path from "node:path";
+import { formatSize } from "./parse-size.js";
+
+const STATUS_LABEL = {
+  ok: "OK",
+  warn: "WARN",
+  exceed: "EXCEED",
+  unbudgeted: "—",
+};
+
+/**
+ * @param {"raw"|"gzip"|"brotli"} compression
+ * @returns {string}
+ */
+function compressionLabel(compression) {
+  return compression.charAt(0).toUpperCase() + compression.slice(1);
+}
+
+/**
+ * @param {import("./index.js").PerformanceResult} result
+ * @param {object} [options]
+ * @param {string} [options.cwd] - used to relativize reported file paths
+ * @returns {string} Markdown
+ */
+export function generatePerformanceReport(result, options = {}) {
+  const cwd = options.cwd || process.cwd();
+  const { measurement, evaluations, compression, summary } = result;
+  const lines = [];
+
+  lines.push("# Performance Budget Report");
+  lines.push("");
+  lines.push(`**Date:** ${new Date().toISOString().split("T")[0]}`);
+  lines.push(`**Compression:** ${compressionLabel(compression)}`);
+  lines.push(
+    `**OK:** ${summary.ok} | **Warn:** ${summary.warn} | **Exceed:** ${summary.exceed} | **Unbudgeted:** ${summary.unbudgeted}`,
+  );
+  lines.push("");
+
+  // Evaluation summary
+  lines.push("## Evaluations");
+  lines.push("");
+  lines.push("| Category | Item | Actual | Budget | Status |");
+  lines.push("|----------|------|--------|--------|--------|");
+
+  for (const row of evaluations) {
+    let itemLabel;
+    if (row.key === "total") {
+      itemLabel = "Total";
+    } else if (row.key === "perPage") {
+      itemLabel = "Per page";
+    } else {
+      itemLabel = escapePipe(row.label);
+    }
+
+    lines.push(
+      `| ${escapePipe(row.category)} | ${itemLabel} | ${formatSize(row.actual)} | ${formatSize(row.budget)} | ${STATUS_LABEL[row.status]} |`,
+    );
+  }
+  lines.push("");
+
+  // Per-category file breakdown
+  for (const [category, data] of Object.entries(measurement.categories)) {
+    if (data.files.length === 0) {
+      continue;
+    }
+
+    lines.push(`## ${escapePipe(category)}`);
+    lines.push("");
+    lines.push("| File | Raw | Gzip | Brotli |");
+    lines.push("|------|-----|------|--------|");
+
+    for (const file of data.files) {
+      const rel = path.relative(cwd, file.path);
+      const label = file.missing ? `${rel} (missing)` : rel;
+      lines.push(
+        `| ${escapePipe(label)} | ${formatSize(file.raw)} | ${formatSize(file.gzip)} | ${formatSize(file.brotli)} |`,
+      );
+    }
+    lines.push(
+      `| **Total** | ${formatSize(data.totals.raw)} | ${formatSize(data.totals.gzip)} | ${formatSize(data.totals.brotli)} |`,
+    );
+    lines.push("");
+  }
+
+  return lines.join("\n");
+}
+
+/**
+ * @param {string} text
+ * @returns {string}
+ */
+function escapePipe(text) {
+  return String(text).replace(/\\/g, "\\\\").replace(/\|/g, "\\|");
+}

package/lib/render/index.js

@@ -15,6 +15,8 @@ import renderMainDocs from "./views/main/docs.js";
 import renderMainIndex from "./views/main/index.js";
 import iframeDesignTokens from "./views/iframe/design-tokens/index.js";
 import renderMainDesignTokens from "./views/main/design-tokens.js";
+import renderMainPerformance from "./views/main/performance.js";
+import renderIframePerformance from "./views/iframe/performance.js";
 
 export default {
   renderMainIndex,
@@ -28,11 +30,13 @@ export default {
   renderIframeDocs,
   renderIframeIndex,
   renderMainDesignTokens,
+  renderMainPerformance,
   iframe: {
     designTokens: {
       colors: iframeDesignTokens.colors,
       sizes: iframeDesignTokens.sizes,
       typography: iframeDesignTokens.typography,
     },
+    performance: renderIframePerformance,
   },
 };

package/lib/render/views/iframe/component.js

@@ -32,6 +32,8 @@ export default async function renderIframeComponent({
     global.state.fileContents[path.join(component.paths.dir.full, "README.md")];
   const componentSchema =
     global.state.fileContents[component.paths.schema.full];
+  const componentDataJson =
+    global.state.fileContents[component.paths.data.full] ?? null;
   const componentTemplate = hasTemplate
     ? global.state.fileContents[component.paths.tpl.full]
     : null;
@@ -103,6 +105,16 @@ export default async function renderIframeComponent({
           ),
         }
       : null,
+    data: componentDataJson
+      ? {
+          string: JSON.stringify(componentDataJson, null, 2),
+          type: "json",
+          file: path.join(
+            global.config.components.folder,
+            component.paths.data.short,
+          ),
+        }
+      : null,
   };
 
   await renderVariations({
@@ -205,13 +217,24 @@ async function renderVariations({
     }
   }
 
+  let dataJson;
+
+  if (fileContents?.data?.string) {
+    try {
+      dataJson = JSON.stringify(JSON.parse(fileContents.data.string));
+    } catch (err) {
+      log("error", null, err);
+    }
+  }
+
   return Promise.all(promises)
     .then(async () => {
       const themeMode = getThemeMode(cookies);
       const renderFileTabs = !!(
         fileContents.schema ||
         fileContents.mocks ||
-        fileContents.template
+        fileContents.template ||
+        fileContents.data
       );
       const componentsEntry = global.state.components.find(
         ({ shortPath }) => shortPath === component.paths.dir.short,
@@ -259,6 +282,7 @@ async function renderVariations({
               ? validatedMocks[0].data.map((error) => error.message).join("\n")
               : null,
           mocks: mocksJson,
+          dataJson,
           template: fileContents.template,
           renderInformation: renderFileTabs || variations.length > 0,
           renderFileTabs,

package/lib/render/views/iframe/performance.js

@@ -0,0 +1,74 @@
+import config from "../../../default-config.js";
+import { getUserUiConfig, getThemeMode } from "../../helpers.js";
+import { runPerformance } from "../../../performance/index.js";
+import { formatSize } from "../../../performance/parse-size.js";
+
+/**
+ * Renders the iframe-side Performance panel. Computed on-request so the
+ * numbers reflect the current on-disk state without any extra cache plumbing;
+ * `measure.js` has an mtime cache so repeat renders are cheap.
+ * @param {object} o
+ * @param {object} o.res
+ * @param {Function} [o.cb]
+ * @param {object} o.cookies
+ * @returns {Promise<void>}
+ */
+export default async function renderIframePerformance({ res, cb, cookies }) {
+  const themeMode = getThemeMode(cookies);
+
+  const result = runPerformance({ config: global.config });
+
+  const viewData = {
+    compression: result.compression,
+    evaluations: result.evaluations.map((row) => ({
+      ...row,
+      actualFormatted: formatSize(row.actual),
+      budgetFormatted: formatSize(row.budget),
+      ratioPercent:
+        row.ratio == null ? null : Math.round(row.ratio * 100),
+    })),
+    categories: Object.entries(result.measurement.categories).map(
+      ([category, data]) => ({
+        category,
+        files: data.files.map((file) => ({
+          path: file.path,
+          raw: formatSize(file.raw),
+          gzip: formatSize(file.gzip),
+          brotli: formatSize(file.brotli),
+          missing: !!file.missing,
+        })),
+        totals: {
+          raw: formatSize(data.totals.raw),
+          gzip: formatSize(data.totals.gzip),
+          brotli: formatSize(data.totals.brotli),
+        },
+      }),
+    ),
+    summary: result.summary,
+  };
+
+  await res.render(
+    "performance.twig.miyagi",
+    {
+      ...viewData,
+      isBuild: global.config.isBuild,
+      lang: global.config.ui.lang,
+      miyagiDev: !!process.env.MIYAGI_DEVELOPMENT,
+      projectName: config.projectName,
+      userUiConfig: getUserUiConfig(cookies),
+      theme: themeMode
+        ? Object.assign(global.config.ui.theme, { mode: themeMode })
+        : global.config.ui.theme,
+      uiTextDirection: global.config.ui.textDirection,
+    },
+    (html) => {
+      if (res.send) {
+        res.send(html);
+      }
+
+      if (cb) {
+        cb(null, html);
+      }
+    },
+  );
+}

package/lib/render/views/iframe/variation.standalone.js

@@ -1,5 +1,6 @@
 import path from "path";
 import config from "../../../default-config.js";
+import { resolveDataJson } from "../../../data-json/index.js";
 import { getUserUiConfig } from "../../helpers.js";
 import resolveAssets from "../../helpers/resolve-assets.js";
 import applyOverrides from "../../helpers/apply-overrides.js";
@@ -13,6 +14,7 @@ import applyOverrides from "../../helpers/apply-overrides.js";
  * @param {Function} [object.cb] - callback function
  * @param {object} [object.cookies]
  * @param {object} [object.overrides] - query-param override values
+ * @param {string} [object.variation] - the variation name
  * @returns {Promise} gets resolved when the variation has been rendered
  */
 export default async function renderIframeVariationStandalone({
@@ -23,6 +25,7 @@ export default async function renderIframeVariationStandalone({
   cb,
   cookies,
   overrides,
+  variation,
 }) {
   if (overrides) {
     const schema =
@@ -31,6 +34,9 @@ export default async function renderIframeVariationStandalone({
   }
 
   const directoryPath = component.paths.dir.short;
+  const { json: dataJson, id: dataJsonId } = await resolveDataJson(component, {
+    variation,
+  });
 
   return new Promise((resolve, reject) => {
     global.app.render(
@@ -58,7 +64,8 @@ export default async function renderIframeVariationStandalone({
             "component_variation.twig.miyagi",
             {
               html: result,
-              mockDataResolved: JSON.stringify(componentData ?? {}),
+              dataJson,
+              dataJsonId,
               cssFiles,
               jsFilesHead,
               jsFilesBody,

package/lib/render/views/main/performance.js

@@ -0,0 +1,51 @@
+import config from "../../../default-config.js";
+import { getUserUiConfig, getThemeMode } from "../../helpers.js";
+
+/**
+ * Renders the main Performance page — the standard chrome (menu etc.) with
+ * the iframe pointed at the Performance panel view.
+ * @param {object} object
+ * @param {object} object.res
+ * @param {Function} [object.cb]
+ * @param {object} [object.cookies]
+ * @returns {void}
+ */
+export default function renderMainPerformance({ res, cb, cookies }) {
+  const themeMode = getThemeMode(cookies);
+
+  res.render(
+    "main.twig.miyagi",
+    {
+      lang: global.config.ui.lang,
+      folders: global.state.menu,
+      components: global.state.components,
+      flatUrlPattern: global.config.isBuild
+        ? "/show-{{component}}.html"
+        : "/show?file={{component}}",
+      iframeSrc: "/iframe/performance",
+      showAll: true,
+      projectName: config.projectName,
+      userProjectName: global.config.projectName,
+      indexPath: global.config.indexPath.embedded,
+      miyagiDev: !!process.env.MIYAGI_DEVELOPMENT,
+      isBuild: global.config.isBuild,
+      userUiConfig: getUserUiConfig(cookies),
+      theme: themeMode
+        ? Object.assign(global.config.ui.theme, { mode: themeMode })
+        : global.config.ui.theme,
+      basePath: global.config.isBuild ? global.config.build.basePath : "/",
+      uiTextDirection: global.config.ui.textDirection,
+      requestedComponent: "performance",
+      requestedVariation: null,
+    },
+    (html) => {
+      if (res.send) {
+        res.send(html);
+      }
+
+      if (cb) {
+        cb(null, html);
+      }
+    },
+  );
+}

package/lib/state/components.js

@@ -116,6 +116,10 @@ function addToRoutes({ name, shortPath, fullPath }, partials = []) {
           full: path.join(fullPath, "README.md"),
           short: path.join(shortPath, "README.md"),
         },
+        data: {
+          full: path.join(fullPath, "data.json"),
+          short: path.join(shortPath, "data.json"),
+        },
       },
       type: "components",
     };

package/lib/state/file-contents.js

@@ -69,6 +69,7 @@ async function getFilePaths(sourceTree) {
               `${files.mocks.name}.${files.mocks.extension[0]}`,
               `${files.mocks.name}.${files.mocks.extension[1]}`,
               `${files.schema.name}.${files.schema.extension}`,
+              "data.json",
             ]) ||
             helpers.fileIsDocumentationFile(entry.path)
           ) {

package/lib/state/menu/index.js

@@ -221,18 +221,59 @@ export const getMenu = function (sourceTree) {
 
   const docsMenu = getDocsMenu(sourceTree.docs);
   const designTokensMenu = getDesignTokensMenu();
+  const performanceMenu = getPerformanceMenu();
 
-  if (!docsMenu && !designTokensMenu && componentsMenu)
+  if (!docsMenu && !designTokensMenu && !performanceMenu && componentsMenu) {
     return componentsMenu.children;
+  }
 
   const menus = [];
-  if (designTokensMenu) menus.push(designTokensMenu);
-  if (componentsMenu) menus.push(componentsMenu);
-  if (docsMenu) menus.push(docsMenu);
+  if (designTokensMenu) {
+    menus.push(designTokensMenu);
+  }
+  if (componentsMenu) {
+    menus.push(componentsMenu);
+  }
+  if (docsMenu) {
+    menus.push(docsMenu);
+  }
+  if (performanceMenu) {
+    menus.push(performanceMenu);
+  }
 
   return menus;
 };
 
+/**
+ * @returns {object|null}
+ */
+function getPerformanceMenu() {
+  // Dev-mode only. In build output there is no live dev-server to compute
+  // perf against, so the entry would dead-link.
+  if (global.config.isBuild) {
+    return null;
+  }
+  if (!global.config.performance?.enabled) {
+    return null;
+  }
+
+  return {
+    topLevel: true,
+    name: "Performance",
+    id: "performance",
+    type: "directory",
+    shortPath: "performance",
+    children: [
+      {
+        section: "performance",
+        type: "file",
+        name: "budget",
+        url: "/iframe/performance",
+      },
+    ],
+  };
+}
+
 /**
  * @returns {object}
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@schalkneethling/miyagi-core",
-  "version": "4.6.2",
+  "version": "4.8.0",
   "description": "miyagi is a component development tool for JavaScript template engines.",
   "main": "index.js",
   "author": "Schalk Neethling <schalkneethling@duck.com>, Michael Großklaus <mail@mgrossklaus.de> (https://www.mgrossklaus.de)",