@schalkneethling/miyagi-core 4.8.0 → 4.9.0

package/lib/performance/index.js

@@ -1,400 +1,156 @@
-/**
- * Performance-budget orchestrator.
- * Turns the Miyagi config + filesystem state into a set of measurements and
- * evaluations against the configured budgets. The output shape is shared by the
- * CLI, the markdown report, and the dev-UI panel so each consumer renders the
- * same data differently rather than re-deriving it.
- * @module performance
- */
+// @ts-check
 
-import fs from "node:fs";
-import path from "node:path";
-import { measure } from "./measure.js";
-import parseSize from "./parse-size.js";
+import { loadPerformanceConfig } from "./config.js";
+import { measureComponent } from "./component.js";
+import { measureHtml } from "./html-size.js";
+import { computePageTotals } from "./page.js";
 
-/**
- * @typedef {object} EvaluationRow
- * @property {string} category - "global-css" | "global-js" | "folder:<name>" | "html"
- * @property {string} key - stable identifier inside the category ("total", "perPage", or a file path)
- * @property {string} label - human-readable label
- * @property {number} actual - measured bytes (at the configured compression)
- * @property {number|null} budget - configured budget in bytes, or null if unset
- * @property {"ok"|"warn"|"exceed"|"unbudgeted"} status - classification against budget
- * @property {number|null} ratio - actual / budget when budget is set
- */
+const STATUS_RANK = {
+  exceed: 4,
+  missing: 3,
+  warn: 2,
+  ok: 1,
+  unbudgeted: 0,
+};
 
 /**
- * @typedef {object} PerformanceResult
- * @property {import("./measure.js").Measurement} measurement - raw per-file and per-category bytes
- * @property {EvaluationRow[]} evaluations - budget comparison rows
- * @property {"raw"|"gzip"|"brotli"} compression - which metric evaluations use
- * @property {{ok: number, warn: number, exceed: number, unbudgeted: number}} summary - counts per status
+ * @param {string[]} statuses
+ * @returns {string} the worst-ranked status, or "unbudgeted" if empty
  */
-
-const WARN_RATIO = 0.8;
-
-/**
- * Expand a css-string or js-object asset entry to a filesystem path.
- * @param {string|{src: string}} entry
- * @param {string} root
- * @returns {string|null} absolute path, or null if the entry points at a remote URL
- */
-function resolveAssetPath(entry, root) {
-  const rel = typeof entry === "string" ? entry : entry?.src;
-
-  if (!rel || URL.canParse(rel)) {
-    return null;
-  }
-
-  return path.resolve(root || "", rel);
-}
-
-/**
- * Walk a directory, collecting absolute paths of all non-directory entries.
- * Hidden files (starting with a dot) are skipped — they are almost never shipped.
- * @param {string} dir
- * @returns {string[]}
- */
-function walkFolder(dir) {
-  if (!fs.existsSync(dir)) {
-    return [];
-  }
-
-  const entries = fs.readdirSync(dir, { withFileTypes: true, recursive: true });
-  const files = [];
-
-  for (const entry of entries) {
-    if (!entry.isFile()) {
-      continue;
-    }
-
-    if (entry.name.startsWith(".")) {
-      continue;
+function worstStatus(statuses) {
+  let worst = "unbudgeted";
+  for (const s of statuses) {
+    if ((STATUS_RANK[s] ?? -1) > (STATUS_RANK[worst] ?? -1)) {
+      worst = s;
     }
-
-    // entry.parentPath on Node 20+ gives the containing directory as an absolute
-    // path when `dir` was absolute — which it always is at our call sites.
-    files.push(path.join(entry.parentPath, entry.name));
   }
-
-  return files;
+  return worst;
 }
 
 /**
- * Build the list of categorised file sets for the "always-on" (dev + CLI) scope:
- * global CSS, global JS, and each configured asset folder.
- * @param {object} config - global.config (or a spy equivalent in tests)
- * @returns {{category: string, label: string, files: string[]}[]}
+ * @param {string[]} statuses
+ * @returns {{ok: number, warn: number, exceed: number, unbudgeted: number, missing: number}}
  */
-export function collectGlobalCategories(config) {
-  const assets = config?.assets ?? {};
-  const root = assets.root || "";
-
-  const globalCss = [
-    ...(assets.css || []),
-    ...(assets.shared?.css || []),
-  ]
-    .map((entry) => resolveAssetPath(entry, root))
-    .filter(Boolean);
-
-  const globalJs = [...(assets.js || []), ...(assets.shared?.js || [])]
-    .map((entry) => resolveAssetPath(entry, root))
-    .filter(Boolean);
-
-  const categories = [
-    { category: "global-css", label: "Global CSS", files: globalCss },
-    { category: "global-js", label: "Global JS", files: globalJs },
-  ];
-
-  for (const folder of assets.folder || []) {
-    const abs = path.resolve(root, folder);
-    categories.push({
-      category: `folder:${folder}`,
-      label: `Folder — ${folder}`,
-      files: walkFolder(abs),
-    });
-  }
-
-  return categories;
-}
-
-/**
- * Build the list of categorised file sets for post-build HTML pages.
- * @param {string} buildFolder
- * @returns {{category: string, label: string, files: string[]}[]}
- */
-export function collectHtmlCategory(buildFolder) {
-  const manifestPath = path.resolve(buildFolder, "output.json");
-
-  if (!fs.existsSync(manifestPath)) {
-    return [];
-  }
-
-  /** @type {Array<string|{path: string}>} */
-  let manifest;
-  try {
-    manifest = JSON.parse(fs.readFileSync(manifestPath, "utf8"));
-  } catch {
-    return [];
-  }
-
-  const files = manifest
-    .map((entry) => (typeof entry === "string" ? entry : entry?.path))
-    .filter((rel) => typeof rel === "string" && rel.endsWith(".html"))
-    .map((rel) => path.resolve(buildFolder, rel));
-
-  return [{ category: "html", label: "Rendered HTML pages", files }];
-}
-
-/**
- * @param {number|null} actual
- * @param {number|null} budget
- * @returns {{status: "ok"|"warn"|"exceed"|"unbudgeted", ratio: number|null}}
- */
-function classify(actual, budget) {
-  if (budget == null) {
-    return { status: "unbudgeted", ratio: null };
-  }
-
-  if (budget <= 0) {
-    return { status: "unbudgeted", ratio: null };
-  }
-
-  const ratio = actual / budget;
-
-  if (actual > budget) {
-    return { status: "exceed", ratio };
-  }
-
-  if (ratio >= WARN_RATIO) {
-    return { status: "warn", ratio };
+function tally(statuses) {
+  const counts = { ok: 0, warn: 0, exceed: 0, unbudgeted: 0, missing: 0 };
+  for (const s of statuses) {
+    if (s in counts) {
+      counts[s] += 1;
+    }
   }
-
-  return { status: "ok", ratio };
+  return counts;
 }
 
 /**
- * Produce evaluation rows given a measurement and a budgets object.
- * The shape of `budgets` is the `performance.budgets` config key; see
- * lib/default-config.js for the canonical definition.
- * @param {import("./measure.js").Measurement} measurement
- * @param {object} budgets - performance.budgets config
- * @param {"raw"|"gzip"|"brotli"} compression
- * @param {{label: Record<string,string>}} meta - map category key -> human label
- * @param {object} options
- * @param {boolean} [options.listAllPages] - include every HTML page, not just those that exceed or warn
- * @returns {EvaluationRow[]}
+ * Run the opt-in performance feature: load miyagi.performance.json, measure
+ * declared components, and (when a render function is supplied) measure each
+ * declared page variation.
+ * @param {{
+ *   cwd?: string,
+ *   compression?: "raw"|"gzip"|"brotli",
+ *   warnRatio?: number,
+ *   render?: (templatePath: string, variation: string) => Promise<string>,
+ * }} [options]
+ * @returns {Promise<object>}
  */
-export function evaluate(measurement, budgets = {}, compression = "gzip", meta = { label: {} }, options = {}) {
-  const rows = [];
-  const labelFor = (category) => meta.label[category] || category;
-
-  const globalBudgets = budgets.global || {};
-  const htmlBudgets = budgets.html || {};
-  const folderBudgets = budgets.folders || {};
-
-  // Global CSS / JS
-  for (const [category, budgetKey] of [
-    ["global-css", "css"],
-    ["global-js", "js"],
-  ]) {
-    const categoryMeasurement = measurement.categories[category];
-    if (!categoryMeasurement) {
-      continue;
-    }
-
-    const budget = parseSize(globalBudgets[budgetKey] ?? null);
-    const actual = categoryMeasurement.totals[compression];
-    const { status, ratio } = classify(actual, budget);
-
-    rows.push({
-      category,
-      key: "total",
-      label: labelFor(category),
-      actual,
-      budget,
-      status,
-      ratio,
-    });
-  }
-
-  // Global umbrella (CSS + JS) if set
-  if (globalBudgets.total != null) {
-    const cssTotal = measurement.categories["global-css"]?.totals[compression] ?? 0;
-    const jsTotal = measurement.categories["global-js"]?.totals[compression] ?? 0;
-    const actual = cssTotal + jsTotal;
-    const budget = parseSize(globalBudgets.total);
-    const { status, ratio } = classify(actual, budget);
-    rows.push({
-      category: "global",
-      key: "total",
-      label: "Global total (CSS + JS)",
-      actual,
-      budget,
-      status,
-      ratio,
+export async function runPerformance(options = {}) {
+  const config = loadPerformanceConfig({ cwd: options.cwd });
+  if (!config) {
+    return { enabled: false };
+  }
+
+  const cwd = options.cwd ?? process.cwd();
+  const compression = options.compression ?? config.compression;
+  const warnRatio = options.warnRatio ?? config.warnRatio;
+
+  const componentMeasurements = new Map();
+  const components = [];
+  for (const [componentPath, entry] of Object.entries(config.components)) {
+    const measurement = measureComponent({
+      cwd,
+      componentPath,
+      entry,
+      compression,
+      warnRatio,
     });
-  }
-
-  // Folders
-  for (const [category, categoryMeasurement] of Object.entries(measurement.categories)) {
-    if (!category.startsWith("folder:")) {
-      continue;
-    }
-    const name = category.slice("folder:".length);
-    const folderBudget = folderBudgets[name];
-    const budget = parseSize(folderBudget?.total ?? null);
-    const actual = categoryMeasurement.totals[compression];
-    const { status, ratio } = classify(actual, budget);
-    rows.push({
-      category,
-      key: "total",
-      label: labelFor(category),
-      actual,
-      budget,
-      status,
-      ratio,
-    });
-  }
-
-  if (folderBudgets.total != null) {
-    let actual = 0;
-    for (const [category, categoryMeasurement] of Object.entries(measurement.categories)) {
-      if (category.startsWith("folder:")) {
-        actual += categoryMeasurement.totals[compression];
-      }
-    }
-    const budget = parseSize(folderBudgets.total);
-    const { status, ratio } = classify(actual, budget);
-    rows.push({
-      category: "folders",
-      key: "total",
-      label: "All folders total",
-      actual,
-      budget,
-      status,
-      ratio,
-    });
-  }
-
-  // HTML: one row per page for perPage, one row for the total.
-  // By default only pages that exceed or warn are listed — a project with many
-  // component variants can produce hundreds of pages and the table becomes noise.
-  // Pass options.listAllPages to include every page.
-  const htmlMeasurement = measurement.categories.html;
-  if (htmlMeasurement) {
-    const perPageBudget = parseSize(htmlBudgets.perPage ?? null);
-
-    if (perPageBudget != null) {
-      let pagesChecked = 0;
-      let pagesPassed = 0;
-
-      for (const file of htmlMeasurement.files) {
-        const actual = file[compression];
-        const { status, ratio } = classify(actual, perPageBudget);
-        pagesChecked++;
-
-        if (status === "ok") {
-          pagesPassed++;
-          if (!options.listAllPages) {
-            continue;
-          }
-        }
-
-        rows.push({
-          category: "html",
-          key: file.path,
-          label: path.basename(file.path),
-          actual,
-          budget: perPageBudget,
-          status,
-          ratio,
+    components.push(measurement);
+    componentMeasurements.set(componentPath, measurement);
+  }
+
+  const pages = [];
+  if (options.render) {
+    for (const [templatePath, pageEntry] of Object.entries(config.pages)) {
+      const variations = pageEntry.variations ?? {};
+      for (const [variation, variationConfig] of Object.entries(variations)) {
+        const enrichedErrors = [];
+        // Pre-flight: components that the page references but that aren't
+        // declared at the top level can't be measured. Surface them as a
+        // separate, clearer error than the page module's "not measured".
+        const declaredComponents = variationConfig.components.filter(
+          (componentPath) => {
+            if (componentMeasurements.has(componentPath)) {
+              return true;
+            }
+            enrichedErrors.push({
+              componentPath,
+              reason: "not declared in config",
+            });
+            return false;
+          },
+        );
+
+        const { bytes: htmlBytes } = await measureHtml({
+          templatePath,
+          variation,
+          render: options.render,
+          compression,
         });
-      }
 
-      // When filtering, add a summary row so the reader knows pages were checked
-      if (!options.listAllPages && pagesPassed > 0) {
-        rows.push({
-          category: "html",
-          key: "pages-ok",
-          label: `${pagesPassed} of ${pagesChecked} pages within budget`,
-          actual: 0,
-          budget: null,
-          status: "ok",
-          ratio: null,
+        const totals = computePageTotals({
+          variationConfig: {
+            components: declaredComponents,
+            budget: variationConfig.budget,
+          },
+          componentMeasurements,
+          htmlBytes,
+          warnRatio,
         });
+        // Replace the inner errors with our enriched ones (they're never both
+        // populated because we filtered the inputs).
+        totals.errors = enrichedErrors;
+        pages.push({ templatePath, variation, totals });
       }
     }
-
-    if (htmlBudgets.total != null) {
-      const actual = htmlMeasurement.totals[compression];
-      const budget = parseSize(htmlBudgets.total);
-      const { status, ratio } = classify(actual, budget);
-      rows.push({
-        category: "html",
-        key: "total",
-        label: "All pages total",
-        actual,
-        budget,
-        status,
-        ratio,
-      });
-    }
-  }
-
-  return rows;
-}
-
-/**
- * Summarise evaluation rows into bucket counts.
- * @param {EvaluationRow[]} rows
- * @returns {{ok: number, warn: number, exceed: number, unbudgeted: number}}
- */
-export function summarise(rows) {
-  const summary = { ok: 0, warn: 0, exceed: 0, unbudgeted: 0 };
-
-  for (const row of rows) {
-    summary[row.status] += 1;
-  }
-
-  return summary;
-}
-
-/**
- * Run the full pipeline: collect → measure → evaluate → summarise.
- * @param {object} [options]
- * @param {object} [options.config] - override global.config, for tests
- * @param {boolean} [options.html] - include post-build HTML measurement
- * @param {string} [options.buildFolder] - required when html is true
- * @param {boolean} [options.listAllPages] - list every HTML page, not just those that exceed or warn
- * @returns {PerformanceResult}
- */
-export function runPerformance(options = {}) {
-  const config = options.config ?? global.config;
-  const perfConfig = config?.performance ?? {};
-  const compression = perfConfig.compression || "gzip";
-  const budgets = perfConfig.budgets || {};
-
-  const categories = collectGlobalCategories(config);
-
-  if (options.html && options.buildFolder) {
-    categories.push(...collectHtmlCategory(options.buildFolder));
-  }
-
-  /** @type {Record<string, string>} */
-  const labelMap = {};
-  for (const category of categories) {
-    labelMap[category.category] = category.label;
   }
 
-  const measurement = measure(
-    categories.map(({ category, files }) => ({ category, files })),
+  const componentStatuses = components.map((c) =>
+    worstStatus([c.css.status, c.js.status]),
   );
-
-  const evaluations = evaluate(measurement, budgets, compression, {
-    label: labelMap,
-  }, { listAllPages: options.listAllPages });
-  const summary = summarise(evaluations);
-
-  return { measurement, evaluations, compression, summary };
+  const pageStatuses = pages.map((p) => {
+    const statuses = [
+      p.totals.css.status,
+      p.totals.js.status,
+      p.totals.html.status,
+      p.totals.total.status,
+    ];
+    // Pages whose declared components couldn't be measured produce
+    // numerically-incomplete totals; surface that as "missing" so the
+    // summary can't claim the page is ok/unbudgeted.
+    if (p.totals.errors && p.totals.errors.length > 0) {
+      statuses.push("missing");
+    }
+    return worstStatus(statuses);
+  });
+
+  return {
+    enabled: true,
+    compression,
+    warnRatio,
+    components,
+    pages,
+    summary: {
+      components: tally(componentStatuses),
+      pages: tally(pageStatuses),
+    },
+  };
 }

package/lib/performance/page.js

@@ -0,0 +1,105 @@
+// @ts-check
+
+import parseSize from "./parse-size.js";
+import { classify } from "./classify.js";
+
+/**
+ * @typedef {object} PageMetric
+ * @property {number} bytes - measured size in bytes for this metric
+ * @property {number|null} budget - parsed budget bytes, or null when unset
+ * @property {"ok"|"warn"|"exceed"|"unbudgeted"} status - classification
+ */
+
+/**
+ * @typedef {object} PageError
+ * @property {string} componentPath - path of the missing/unknown component
+ * @property {string} reason - human-readable cause
+ */
+
+/**
+ * @typedef {object} PageTotals
+ * @property {PageMetric} css - summed CSS bytes across declared components
+ * @property {PageMetric} js - summed JS bytes across declared components
+ * @property {PageMetric} html - measured HTML bytes for this variation
+ * @property {PageMetric} total - sum of css + js + html
+ * @property {PageError[]} errors - per-component issues that didn't abort the run
+ */
+
+/**
+ * Sum CSS / JS / HTML byte sizes for a single page variation and classify
+ * each metric (and the grand total) against the optional budget keys
+ * declared in miyagi.performance.json.
+ * @param {{
+ *   variationConfig: {
+ *     components: string[],
+ *     budget?: { css?: string, js?: string, html?: string, total?: string },
+ *   },
+ *   componentMeasurements: Map<string, {
+ *     css: { bytes: number },
+ *     js: { bytes: number },
+ *   }>,
+ *   htmlBytes: number,
+ *   warnRatio: number,
+ * }} options
+ * @returns {PageTotals}
+ */
+export function computePageTotals({
+  variationConfig,
+  componentMeasurements,
+  htmlBytes,
+  warnRatio,
+}) {
+  const errors = [];
+  const seen = new Set();
+  let cssBytes = 0;
+  let jsBytes = 0;
+
+  for (const componentPath of variationConfig.components) {
+    if (seen.has(componentPath)) {
+      continue;
+    }
+    seen.add(componentPath);
+    const measurement = componentMeasurements.get(componentPath);
+    if (!measurement) {
+      errors.push({ componentPath, reason: "not measured" });
+      continue;
+    }
+    cssBytes += measurement.css.bytes;
+    jsBytes += measurement.js.bytes;
+  }
+
+  const totalBytes = cssBytes + jsBytes + htmlBytes;
+  const budget = variationConfig.budget ?? {};
+  const cssBudget = parseSize(budget.css ?? null);
+  const jsBudget = parseSize(budget.js ?? null);
+  const htmlBudget = parseSize(budget.html ?? null);
+  const totalBudget = parseSize(budget.total ?? null);
+
+  return {
+    css: {
+      bytes: cssBytes,
+      budget: cssBudget,
+      status: classify({ bytes: cssBytes, budgetBytes: cssBudget, warnRatio }),
+    },
+    js: {
+      bytes: jsBytes,
+      budget: jsBudget,
+      status: classify({ bytes: jsBytes, budgetBytes: jsBudget, warnRatio }),
+    },
+    html: {
+      bytes: htmlBytes,
+      budget: htmlBudget,
+      status: classify({ bytes: htmlBytes, budgetBytes: htmlBudget, warnRatio }),
+    },
+    total: {
+      bytes: totalBytes,
+      budget: totalBudget,
+      status: classify({
+        bytes: totalBytes,
+        budgetBytes: totalBudget,
+        warnRatio,
+      }),
+    },
+    errors,
+  };
+}

package/lib/performance/render-page.js

@@ -0,0 +1,34 @@
+// @ts-check
+
+import { getVariationData } from "../mocks/index.js";
+
+/**
+ * Render a configured page (a component-shaped entry under templates/...)
+ * to its raw HTML for performance measurement. Looks up the entry in
+ * global.state.routes by its shortPath, resolves the variation's mock data,
+ * and runs the template engine. Returns the rendered HTML string.
+ * @param {string} templatePath
+ * @param {string} variation
+ * @returns {Promise<string>}
+ */
+export async function renderPageHtml(templatePath, variation) {
+  const route = global.state?.routes?.find(
+    (r) => r.paths?.dir?.short === templatePath,
+  );
+  if (!route || !route.paths?.tpl?.full) {
+    throw new Error(
+      `Performance: no template found for "${templatePath}". ` +
+        `Make sure the path matches a component's library-relative folder.`,
+    );
+  }
+  const data = (await getVariationData(route, variation)) ?? {};
+  return new Promise((resolve, reject) => {
+    global.app.render(route.paths.tpl.full, data, (error, html) => {
+      if (error) {
+        reject(error);
+        return;
+      }
+      resolve(html);
+    });
+  });
+}