@schalkneethling/miyagi-core 4.7.0 → 4.8.0

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/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/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/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.7.0",
+  "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)",