@schalkneethling/miyagi-core 4.8.1 → 4.9.0

package/lib/performance/routes.js

@@ -0,0 +1,72 @@
+// @ts-check
+
+import { existsSync } from "node:fs";
+import path from "node:path";
+import { CONFIG_FILE_NAME } from "./config.js";
+import { runPerformance } from "./index.js";
+
+/**
+ * Attach performance API routes to the supplied Express app. Routes are
+ * always registered; each handler returns 404 if miyagi.performance.json
+ * is absent at request time, so users can drop the file in or out without
+ * restarting the server. The runPerformance() file-size + html compression
+ * caches make repeat hits cheap.
+ *
+ * Routes:
+ *   GET /api/performance/components
+ *   GET /api/performance/pages
+ *   GET /api/performance/pages/:templatePath/:variation
+ * @param {object} app - Express app
+ * @param {{
+ *   cwd: string,
+ *   render?: (templatePath: string, variation: string) => Promise<string>,
+ * }} options
+ * @returns {boolean} true when the config file exists at registration time
+ */
+export function attachPerformanceRoutes(app, options) {
+  const handle = async (req, res, transform) => {
+    try {
+      const result = await runPerformance({
+        cwd: options.cwd,
+        render: options.render,
+      });
+      if (!result.enabled) {
+        res.status(404).json({ error: "Performance feature not configured." });
+        return;
+      }
+      const transformed = transform(result, res);
+      if (!res.headersSent) {
+        res.json(transformed);
+      }
+    } catch (error) {
+      res.status(500).json({ error: error.message });
+    }
+  };
+
+  app.get("/api/performance/components", (req, res) =>
+    handle(req, res, (result) => result.components),
+  );
+
+  app.get("/api/performance/pages", (req, res) =>
+    handle(req, res, (result) => result.pages),
+  );
+
+  app.get("/api/performance/pages/:templatePath/:variation", (req, res) =>
+    handle(req, res, (result) => {
+      // Express has already percent-decoded req.params; calling
+      // decodeURIComponent again would over-decode and throw URIError on
+      // legitimate values containing "%".
+      const { templatePath, variation } = req.params;
+      const match = result.pages.find(
+        (p) => p.templatePath === templatePath && p.variation === variation,
+      );
+      if (!match) {
+        res.status(404).json({ error: "Page not found." });
+        return undefined;
+      }
+      return match;
+    }),
+  );
+
+  return existsSync(path.join(options.cwd, CONFIG_FILE_NAME));
+}

package/lib/performance/schema.json

@@ -0,0 +1,79 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "miyagi.performance.json",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "compression": {
+      "type": "string",
+      "enum": ["raw", "gzip", "brotli"],
+      "default": "gzip"
+    },
+    "warnRatio": {
+      "type": "number",
+      "exclusiveMinimum": 0,
+      "exclusiveMaximum": 1,
+      "default": 0.8
+    },
+    "components": {
+      "type": "object",
+      "minProperties": 0,
+      "propertyNames": { "minLength": 1 },
+      "default": {},
+      "additionalProperties": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "css": { "$ref": "#/definitions/assetEntry" },
+          "js": { "$ref": "#/definitions/assetEntry" }
+        }
+      }
+    },
+    "pages": {
+      "default": {},
+      "type": "object",
+      "propertyNames": { "minLength": 1 },
+      "additionalProperties": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["variations"],
+        "properties": {
+          "variations": {
+            "type": "object",
+            "propertyNames": { "minLength": 1 },
+            "additionalProperties": {
+              "type": "object",
+              "additionalProperties": false,
+              "required": ["components"],
+              "properties": {
+                "components": {
+                  "type": "array",
+                  "items": { "type": "string", "minLength": 1 }
+                },
+                "budget": {
+                  "type": "object",
+                  "additionalProperties": false,
+                  "properties": {
+                    "css": { "type": "string" },
+                    "js": { "type": "string" },
+                    "html": { "type": "string" },
+                    "total": { "type": "string" }
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  },
+  "definitions": {
+    "assetEntry": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "budget": { "type": "string" }
+      }
+    }
+  }
+}

package/lib/performance/view-data.js

@@ -0,0 +1,86 @@
+// @ts-check
+
+import { formatSize } from "./parse-size.js";
+
+/**
+ * @param {object} metric - the metric object from runPerformance
+ * @returns {object} compact view-data shape for the Twig templates
+ */
+function metricView(metric) {
+  return {
+    bytes: metric.bytes,
+    bytesLabel: formatSize(metric.bytes),
+    budget: metric.budget,
+    budgetLabel: metric.budget == null ? null : formatSize(metric.budget),
+    status: metric.status,
+  };
+}
+
+/**
+ * Build the component-overview Performance section view-data for a given
+ * component path. Returns null when the feature is disabled or the component
+ * isn't listed in miyagi.performance.json.
+ * @param {object|null} runResult - return value of runPerformance() or null
+ * @param {string} componentPath
+ * @returns {object|null}
+ */
+export function buildComponentPerfSection(runResult, componentPath) {
+  if (!runResult || !runResult.enabled) {
+    return null;
+  }
+  const match = runResult.components.find(
+    (c) => c.componentPath === componentPath,
+  );
+  if (!match) {
+    return null;
+  }
+  return {
+    componentPath,
+    css: { ...metricView(match.css), path: match.css.path },
+    js: { ...metricView(match.js), path: match.js.path },
+  };
+}
+
+/**
+ * Build the page-banner view-data for a given template + variation. Returns
+ * null when the feature is disabled or the page isn't listed in
+ * miyagi.performance.json.
+ * @param {object|null} runResult - return value of runPerformance() or null
+ * @param {string} templatePath
+ * @param {string} variation
+ * @returns {object|null}
+ */
+export function buildPagePerfBanner(runResult, templatePath, variation) {
+  if (!runResult || !runResult.enabled) {
+    return null;
+  }
+  const match = runResult.pages.find(
+    (p) => p.templatePath === templatePath && p.variation === variation,
+  );
+  if (!match) {
+    return null;
+  }
+  const t = match.totals;
+  return {
+    templatePath,
+    variation,
+    css: metricView(t.css),
+    js: metricView(t.js),
+    html: metricView(t.html),
+    total: metricView(t.total),
+    components: variationComponents(match.totals),
+    errors: t.errors,
+  };
+}
+
+/**
+ * Surfaces undeclared / missing component paths from the totals' errors
+ * array — used as a tooltip aid in the banner so users can see which
+ * components weren't measured. Components that *were* measured aren't
+ * listed here; the banner already shows their summed bytes.
+ * @param {object} totals - the page totals object from runPerformance
+ * @returns {string[]} component paths flagged in totals.errors
+ */
+function variationComponents(totals) {
+  return (totals.errors || []).map((e) => e.componentPath);
+}

package/lib/render/index.js

@@ -15,8 +15,6 @@ 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,
@@ -30,13 +28,11 @@ 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

@@ -8,6 +8,8 @@ import { getComponentData } from "../../../mocks/index.js";
 import { getUserUiConfig, getThemeMode } from "../../helpers.js";
 import resolveAssets from "../../helpers/resolve-assets.js";
 import log from "../../../logger.js";
+import { runPerformance } from "../../../performance/index.js";
+import { buildComponentPerfSection } from "../../../performance/view-data.js";
 
 /**
  * @param {object} object - parameter object
@@ -246,9 +248,21 @@ async function renderVariations({
         componentDeclaredAssets,
       );
 
+      let perfSection;
+      try {
+        const perfResult = await runPerformance({ cwd: process.cwd() });
+        perfSection = buildComponentPerfSection(
+          perfResult,
+          component.paths.dir.short,
+        );
+      } catch {
+        perfSection = null;
+      }
+
       await res.render(
         "iframe_component.twig.miyagi",
         {
+          perfSection,
           lang: global.config.ui.lang,
           variations,
           cssFiles,

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

@@ -1,6 +1,9 @@
 import config from "../../../default-config.js";
 import * as helpers from "../../../helpers.js";
 import { getUserUiConfig, getThemeMode } from "../../helpers.js";
+import { runPerformance } from "../../../performance/index.js";
+import { buildPagePerfBanner } from "../../../performance/view-data.js";
+import { renderPageHtml } from "../../../performance/render-page.js";
 
 /**
  * @param {object} object - parameter object
@@ -27,7 +30,7 @@ export default async function renderMainComponent({
         `-variation-${helpers.normalizeString(variation)}.html`,
       );
     } else {
-      iframeSrc += `&variation=${variation}`;
+      iframeSrc += `&variation=${encodeURIComponent(variation)}`;
     }
   }
 
@@ -37,9 +40,28 @@ export default async function renderMainComponent({
     iframeSrc += "&embedded=true";
   }
 
+  let perfBanner = null;
+  if (!global.config.isBuild && variation) {
+    try {
+      const perfResult = await runPerformance({
+        cwd: process.cwd(),
+        render: renderPageHtml,
+      });
+      perfBanner = buildPagePerfBanner(
+        perfResult,
+        component.paths.dir.short,
+        variation,
+      );
+    } catch {
+      // Performance is opt-in; never let measurement errors block rendering.
+      perfBanner = null;
+    }
+  }
+
   await res.render(
     "main.twig.miyagi",
     {
+      perfBanner,
       lang: global.config.ui.lang,
       folders: global.state.menu,
       components: global.state.components,

package/lib/state/menu/index.js

@@ -221,9 +221,8 @@ export const getMenu = function (sourceTree) {
 
   const docsMenu = getDocsMenu(sourceTree.docs);
   const designTokensMenu = getDesignTokensMenu();
-  const performanceMenu = getPerformanceMenu();
 
-  if (!docsMenu && !designTokensMenu && !performanceMenu && componentsMenu) {
+  if (!docsMenu && !designTokensMenu && componentsMenu) {
     return componentsMenu.children;
   }
 
@@ -237,43 +236,10 @@ export const getMenu = function (sourceTree) {
   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.8.1",
+  "version": "4.9.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)",
@@ -41,6 +41,7 @@
     "chokidar": "^5.0.0",
     "cookie-parser": "^1.4.7",
     "deepmerge": "^4.3.1",
+    "dependency-tree": "^11.4.3",
     "directory-tree": "^3.5.2",
     "express": "^5.1.0",
     "html-validate": "^10.11.2",

package/frontend/assets/css/iframe/performance.css

@@ -1,64 +0,0 @@
-.PerformanceTable {
-  border-collapse: collapse;
-  margin-block: 1em;
-  width: 100%;
-}
-
-.PerformanceTable :is(th, td) {
-  padding: 0.35em 0.75em;
-  text-align: start;
-  vertical-align: top;
-}
-
-.PerformanceTable thead th {
-  border-block-end: 0.0625rem solid currentcolor;
-  font-weight: bold;
-  text-transform: uppercase;
-  font-size: 0.875em;
-  letter-spacing: 0.0375em;
-}
-
-.PerformanceTable tbody tr:not(:last-child) :is(td, th) {
-  border-block-end: 0.0625rem solid var(--color-Outline);
-}
-
-.PerformanceTable-totals :is(th, td) {
-  font-weight: bold;
-}
-
-.PerformanceTable tr[data-missing="true"] td {
-  color: var(--color-Iframe-text-secondary);
-}
-
-.PerformanceStatus {
-  display: inline-block;
-  padding: 0.15em 0.6em;
-  border-radius: 0.25em;
-  font-size: 0.875em;
-  font-weight: bold;
-  letter-spacing: 0.0375em;
-  text-transform: uppercase;
-}
-
-.PerformanceStatus--ok {
-  background: color-mix(in srgb, var(--color-Positive) 20%, transparent);
-  color: var(--color-Positive);
-}
-
-.PerformanceStatus--warn {
-  background: color-mix(
-    in srgb,
-    var(--color-Iframe-text-secondary) 25%,
-    transparent
-  );
-  color: var(--color-Iframe-text);
-}
-
-.PerformanceStatus--exceed {
-  background: color-mix(in srgb, var(--color-Negative) 20%, transparent);
-  color: var(--color-Negative);
-}
-
-.PerformanceStatus--unbudgeted {
-  color: var(--color-Iframe-text-secondary);
-}

package/frontend/views/performance.twig.miyagi

@@ -1,72 +0,0 @@
-{% extends "@miyagi/layouts/iframe_default.twig.miyagi" %}
-{% block body %}
-	<div class="Wrapper">
-		<div class="Documentation">
-			<h1>Performance budget</h1>
-			<p>Measured at <strong>{{ compression }}</strong>. OK: {{ summary.ok }} · Warn: {{ summary.warn }} · Exceed: {{ summary.exceed }} · Unbudgeted: {{ summary.unbudgeted }}.</p>
-
-			<h2>Evaluations</h2>
-			<table class="PerformanceTable">
-				<thead>
-					<tr>
-						<th scope="col">Category</th>
-						<th scope="col">Item</th>
-						<th scope="col">Actual</th>
-						<th scope="col">Budget</th>
-						<th scope="col">Status</th>
-					</tr>
-				</thead>
-				<tbody>
-					{% for row in evaluations %}
-						<tr data-status="{{ row.status }}">
-							<td>{{ row.category }}</td>
-							<td>{% if row.key == "total" %}Total{% else %}{{ row.label }}{% endif %}</td>
-							<td>{{ row.actualFormatted }}</td>
-							<td>{{ row.budgetFormatted }}</td>
-							<td>
-								<span class="PerformanceStatus PerformanceStatus--{{ row.status }}">
-									{% if row.status == "ok" %}OK{% elseif row.status == "warn" %}WARN{% elseif row.status == "exceed" %}EXCEED{% else %}—{% endif %}
-								</span>
-								{% if row.ratioPercent is not null %}
-									<small>({{ row.ratioPercent }}%)</small>
-								{% endif %}
-							</td>
-						</tr>
-					{% endfor %}
-				</tbody>
-			</table>
-
-			{% for cat in categories %}
-				{% if cat.files|length > 0 %}
-					<h2>{{ cat.category }}</h2>
-					<table class="PerformanceTable">
-						<thead>
-							<tr>
-								<th scope="col">File</th>
-								<th scope="col">Raw</th>
-								<th scope="col">Gzip</th>
-								<th scope="col">Brotli</th>
-							</tr>
-						</thead>
-						<tbody>
-							{% for file in cat.files %}
-								<tr{% if file.missing %} data-missing="true"{% endif %}>
-									<td>{{ file.path }}{% if file.missing %} <em>(missing)</em>{% endif %}</td>
-									<td>{{ file.raw }}</td>
-									<td>{{ file.gzip }}</td>
-									<td>{{ file.brotli }}</td>
-								</tr>
-							{% endfor %}
-							<tr class="PerformanceTable-totals">
-								<th scope="row">Total</th>
-								<td>{{ cat.totals.raw }}</td>
-								<td>{{ cat.totals.gzip }}</td>
-								<td>{{ cat.totals.brotli }}</td>
-							</tr>
-						</tbody>
-					</table>
-				{% endif %}
-			{% endfor %}
-		</div>
-	</div>
-{% endblock %}