@schalkneethling/miyagi-core 4.8.0 → 4.9.0

package/lib/default-config.js

@@ -89,39 +89,6 @@ export default {
       },
     },
     namespaces: {},
-    // Performance budget feature — tracks asset byte size against configured
-    // limits and surfaces the state via `miyagi budget`, the build-time report,
-    // and the dev-server UI. Defaults mirror the "Slow 4G / Moto G4" tier from
-    // web.dev's "Your First Performance Budget" (see docs).
-    performance: {
-      enabled: true,
-      compression: "gzip",
-      report: {
-        failOnExceed: false,
-        output: "performance-report.md",
-      },
-      budgets: {
-        global: {
-          css: "35 kB",
-          js: "200 kB",
-          total: null,
-        },
-        html: {
-          perPage: "30 kB",
-          total: null,
-        },
-        folders: {
-          fonts: { total: "30 kB" },
-          images: { total: "50 kB" },
-          total: null,
-        },
-        perComponent: {
-          css: null,
-          js: null,
-          total: null,
-        },
-      },
-    },
     projectName: "miyagi",
     ui: {
       mode: "light",

package/lib/init/args.js

@@ -169,43 +169,30 @@ export default function createCli(handlers, argv = process.argv) {
       commandHandler(handlers.doctor),
     )
     .command(
-      "budget",
-      "Checks asset byte sizes against your performance budget",
+      "perf",
+      "Reports component and page bundle sizes against miyagi.performance.json",
       (builder) =>
         builder
           .option("compression", {
-            description: "Which compression to compare against the budget",
+            description: "Compression to compare against the budget",
             type: "string",
             choices: ["raw", "gzip", "brotli"],
           })
+          .option("warn-ratio", {
+            description: "Override warnRatio (must be in (0, 1))",
+            type: "number",
+          })
           .option("fail", {
-            description: "Exit with a non-zero code if any budget is exceeded",
+            description: "Exit non-zero if any component or page is exceed",
             type: "boolean",
             default: false,
           })
           .option("json", {
-            description:
-              "Emit the full evaluation as JSON on stdout (for CI / automation)",
-            type: "boolean",
-            default: false,
-          })
-          .option("output", {
-            alias: "o",
-            description: "Also write a markdown report to this path",
-            type: "string",
-          })
-          .option("build-folder", {
-            description:
-              "Include post-build HTML pages from this folder (reads output.json)",
-            type: "string",
-          })
-          .option("list-all-pages", {
-            description:
-              "List every HTML page in the evaluation, not just those that exceed or warn",
+            description: "Emit the full result as JSON on stdout",
             type: "boolean",
             default: false,
           }),
-      commandHandler(handlers.budget),
+      commandHandler(handlers.perf),
     )
     .help()
     .version(pkgJson.version)

package/lib/init/router.js

@@ -8,7 +8,8 @@ import config from "../default-config.js";
 import render from "../render/index.js";
 import { getVariationData } from "../mocks/index.js";
 import log from "../logger.js";
-import { runPerformance } from "../performance/index.js";
+import { attachPerformanceRoutes } from "../performance/routes.js";
+import { renderPageHtml } from "../performance/render-page.js";
 
 /**
  * @param {object} component
@@ -64,6 +65,13 @@ function checkIfRequestedVariationIsValid(component, variation) {
  * @returns {void}
  */
 export default function Router() {
+  if (!global.config.isBuild) {
+    attachPerformanceRoutes(global.app, {
+      cwd: process.cwd(),
+      render: renderPageHtml,
+    });
+  }
+
   global.app.get("/design-tokens/colors", async (req, res) => {
     return render.renderMainDesignTokens({
       res,
@@ -103,32 +111,6 @@ export default function Router() {
     });
   });
 
-  // Performance budget — dev-mode only.
-  if (!global.config.isBuild && global.config.performance?.enabled) {
-    global.app.get("/performance", async (req, res) => {
-      return render.renderMainPerformance({
-        res,
-        cookies: req.cookies,
-      });
-    });
-
-    global.app.get("/iframe/performance", async (req, res) => {
-      return render.iframe.performance({
-        res,
-        cookies: req.cookies,
-      });
-    });
-
-    global.app.get("/api/performance", (req, res) => {
-      try {
-        const result = runPerformance({ config: global.config });
-        res.json(result);
-      } catch (error) {
-        res.status(500).json({ error: error.message });
-      }
-    });
-  }
-
   global.app.get("/show", async (req, res) => {
     const { file, variation } = req.query;
 

package/lib/performance/classify.js

@@ -0,0 +1,33 @@
+// @ts-check
+
+/**
+ * Classify a measured byte size against an optional budget. Shared by the
+ * component and page measurement modules so the priority order (missing >
+ * unbudgeted > exceed > warn > ok) stays consistent everywhere.
+ * @param {{
+ *   bytes: number,
+ *   budgetBytes: number|null,
+ *   warnRatio: number,
+ *   missing?: boolean,
+ * }} input
+ * @returns {"ok"|"warn"|"exceed"|"unbudgeted"|"missing"}
+ */
+export function classify({ bytes, budgetBytes, warnRatio, missing = false }) {
+  if (missing) {
+    return "missing";
+  }
+  if (budgetBytes == null) {
+    return "unbudgeted";
+  }
+  if (bytes > budgetBytes) {
+    return "exceed";
+  }
+  // Guard against budgetBytes === 0: with bytes also 0, the warn check
+  // (bytes >= budgetBytes * warnRatio → 0 >= 0) would otherwise flip to
+  // "warn", which isn't a useful answer when nothing is shipped against
+  // a zero budget.
+  if (bytes > 0 && bytes >= budgetBytes * warnRatio) {
+    return "warn";
+  }
+  return "ok";
+}

package/lib/performance/component.js

@@ -0,0 +1,122 @@
+// @ts-check
+
+import path from "node:path";
+import { existsSync } from "node:fs";
+import dependencyTree from "dependency-tree";
+import { measure } from "./measure.js";
+import parseSize from "./parse-size.js";
+import { classify } from "./classify.js";
+
+/**
+ * @typedef {object} AssetMeasurement
+ * @property {string} path - absolute path to the asset
+ * @property {number} bytes - measured bytes for the chosen compression
+ * @property {number|null} budget - budget in bytes, or null when unset
+ * @property {"ok"|"warn"|"exceed"|"unbudgeted"|"missing"} status - classification
+ */
+
+/**
+ * @typedef {object} ComponentMeasurement
+ * @property {string} componentPath - library-relative path to the component folder
+ * @property {AssetMeasurement} css - the CSS asset measurement
+ * @property {AssetMeasurement} js - the JS asset measurement
+ */
+
+/**
+ * Resolve all files reachable from `entryPath` via static `import` (JS/TS) or
+ * `@import` (CSS) statements. Returns just the entry path when the file is
+ * missing, has no imports, or the walker fails for any reason. The walker
+ * sees what's reachable in source — it cannot tree-shake, dedup runtime-only
+ * branches, or follow dynamic imports, so the resulting number is an
+ * upper-bound proxy for what a bundler would emit.
+ * @param {string} entryPath - absolute path to the entry file
+ * @returns {string[]} absolute paths of every file in the import graph
+ */
+function resolveImportGraph(entryPath) {
+  if (!existsSync(entryPath)) {
+    return [entryPath];
+  }
+  try {
+    const list = dependencyTree.toList({
+      filename: entryPath,
+      directory: path.dirname(entryPath),
+      filter: (filePath) => !filePath.includes("node_modules"),
+    });
+    return list && list.length > 0 ? list : [entryPath];
+  } catch {
+    return [entryPath];
+  }
+}
+
+/**
+ * Measure the CSS and JS bundle sizes for a single component and classify
+ * each against the (optional) budget set in miyagi.performance.json. Walks
+ * static imports from the entry file so a 2 kB component that imports a
+ * 50 kB util shows the real reachable size, not just the entry file.
+ * @param {{
+ *   cwd: string,
+ *   componentPath: string,
+ *   entry: { css?: { budget?: string }, js?: { budget?: string } },
+ *   compression: "raw"|"gzip"|"brotli",
+ *   warnRatio: number,
+ * }} options
+ * @returns {ComponentMeasurement}
+ */
+export function measureComponent({
+  cwd,
+  componentPath,
+  entry,
+  compression,
+  warnRatio,
+}) {
+  const folder = path.join(cwd, componentPath);
+  const componentName = path.basename(componentPath);
+  const cssPath = path.join(folder, `${componentName}.css`);
+  const jsPath = path.join(folder, `${componentName}.js`);
+
+  const cssFiles = resolveImportGraph(cssPath);
+  const jsFiles = resolveImportGraph(jsPath);
+
+  const measurement = measure([
+    { category: "css", files: cssFiles },
+    { category: "js", files: jsFiles },
+  ]);
+  const cssEntry = measurement.categories.css.files[0];
+  const jsEntry = measurement.categories.js.files[0];
+  const cssTotals = measurement.categories.css.totals;
+  const jsTotals = measurement.categories.js.totals;
+
+  const cssBudget = parseSize(entry?.css?.budget ?? null);
+  const jsBudget = parseSize(entry?.js?.budget ?? null);
+
+  const cssMissing = Boolean(cssEntry.missing);
+  const jsMissing = Boolean(jsEntry.missing);
+  const cssBytes = cssMissing ? 0 : cssTotals[compression];
+  const jsBytes = jsMissing ? 0 : jsTotals[compression];
+
+  return {
+    componentPath,
+    css: {
+      path: cssPath,
+      bytes: cssBytes,
+      budget: cssBudget,
+      status: classify({
+        bytes: cssBytes,
+        budgetBytes: cssBudget,
+        warnRatio,
+        missing: cssMissing,
+      }),
+    },
+    js: {
+      path: jsPath,
+      bytes: jsBytes,
+      budget: jsBudget,
+      status: classify({
+        bytes: jsBytes,
+        budgetBytes: jsBudget,
+        warnRatio,
+        missing: jsMissing,
+      }),
+    },
+  };
+}

package/lib/performance/config.js

@@ -0,0 +1,65 @@
+// @ts-check
+
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import Ajv from "ajv";
+import schema from "./schema.json" with { type: "json" };
+
+export const CONFIG_FILE_NAME = "miyagi.performance.json";
+
+let validator = null;
+
+/**
+ * @returns {Function} compiled AJV validator (cached across calls)
+ */
+function getValidator() {
+  if (!validator) {
+    // useDefaults mutates the validated object so schema-declared `default`
+    // values land on the parsed config — keeps schema.json the single source
+    // of truth for default compression / warnRatio / etc.
+    const ajv = new Ajv({ allErrors: true, useDefaults: true });
+    validator = ajv.compile(schema);
+  }
+  return validator;
+}
+
+/**
+ * @param {{cwd?: string}} [options]
+ * @returns {object|null}
+ */
+export function loadPerformanceConfig({ cwd } = {}) {
+  const baseDir = cwd ?? process.cwd();
+  const file = path.join(baseDir, CONFIG_FILE_NAME);
+
+  let raw;
+  try {
+    raw = readFileSync(file, "utf-8");
+  } catch (error) {
+    if (error && error.code === "ENOENT") {
+      return null;
+    }
+    throw error;
+  }
+
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (error) {
+    throw new Error(
+      `Failed to parse ${CONFIG_FILE_NAME}: invalid JSON (${error.message}).`,
+      { cause: error },
+    );
+  }
+
+  const validate = getValidator();
+  if (!validate(parsed)) {
+    const message = (validate.errors || [])
+      .map((err) => `${err.instancePath || "/"} ${err.message}`)
+      .join("; ");
+    throw new Error(`Invalid ${CONFIG_FILE_NAME}: ${message}.`);
+  }
+
+  // AJV's useDefaults has already populated compression / warnRatio /
+  // components / pages from the schema's default values.
+  return parsed;
+}

package/lib/performance/html-size.js

@@ -0,0 +1,55 @@
+// @ts-check
+
+import zlib from "node:zlib";
+
+/**
+ * @param {string} html - the rendered HTML string
+ * @param {"raw"|"gzip"|"brotli"} compression - which size to report
+ * @returns {number} byte length under the chosen compression
+ */
+export function measureHtmlBytes(html, compression) {
+  const buffer = Buffer.from(html);
+  if (compression === "raw") {
+    return buffer.byteLength;
+  }
+  if (compression === "gzip") {
+    return zlib.gzipSync(buffer).byteLength;
+  }
+  if (compression === "brotli") {
+    return zlib.brotliCompressSync(buffer, {
+      params: { [zlib.constants.BROTLI_PARAM_QUALITY]: 6 },
+    }).byteLength;
+  }
+  throw new Error(`Unknown compression "${compression}".`);
+}
+
+/**
+ * Render a page variation through the supplied render function and report
+ * its compressed byte size. The render function is injected so this module
+ * stays pure for tests; in production the caller wires it to the existing
+ * Miyagi render pipeline.
+ * @param {{
+ *   templatePath: string,
+ *   variation: string,
+ *   render: (templatePath: string, variation: string) => Promise<string>,
+ *   compression: "raw"|"gzip"|"brotli",
+ * }} options
+ * @returns {Promise<{ html: string, bytes: number }>}
+ */
+export async function measureHtml({
+  templatePath,
+  variation,
+  render,
+  compression,
+}) {
+  let html;
+  try {
+    html = await render(templatePath, variation);
+  } catch (error) {
+    throw new Error(
+      `Failed to render ${templatePath} (${variation}): ${error.message}`,
+      { cause: error },
+    );
+  }
+  return { html, bytes: measureHtmlBytes(html, compression) };
+}