Skip to content

armgit / mso

Public Imported from GitHub
0

Browser-based graphical shell and control plane for a Linux server you own — real terminal, file manager, live metrics and BYOK AI in one mobile-first workspace. Next.js 16 · React 19 · node-pty · Tailwind v4 · shadcn/ui. Public alpha, self-hosted.

8.7 KB
Raw Blame
// ESM only. Pure functions for parsing, summarizing, checking, and formatting perf reports.
// Shapes live in perf-report.d.ts; this file stays implementation-only.


const REQUIRED_TIMING_FIELDS = [
  "fcpMs",
  "lcpMs",
  "tbtMs",
  "cls",
  "maxLongTaskMs",
  "firstLoadJsBytes",
];

/**
 * Validates and parses a performance report JSON or object.
 * Requires schemaVersion === 1, non-empty runs array, and every run to have
 * a valid string label and numeric-or-null timing fields.
 * Fails closed on missing fields instead of silently coercing to zero.
 *
 * @param {unknown} json - Raw JSON string or parsed object
 * @returns {PerfReport} Validated report object
 */
export function parsePerfReport(json) {
  let report = json;
  if (typeof json === "string") {
    try {
      report = JSON.parse(json);
    } catch (err) {
      throw new Error(`Invalid JSON for perf report: ${err instanceof Error ? err.message : String(err)}`);
    }
  }

  if (!report || typeof report !== "object" || Array.isArray(report)) {
    throw new Error("Report must be a non-null object");
  }

  if (report.schemaVersion !== 1) {
    throw new Error(`Invalid or missing schemaVersion: expected 1, received ${report.schemaVersion}`);
  }

  if (!Array.isArray(report.runs) || report.runs.length === 0) {
    throw new Error("Report missing valid runs: expected non-empty array");
  }

  for (let index = 0; index < report.runs.length; index++) {
    const run = report.runs[index];
    if (!run || typeof run !== "object" || Array.isArray(run)) {
      throw new Error(`Run at index ${index} must be a non-null object`);
    }

    if (!("label" in run) || typeof run.label !== "string" || !run.label.trim()) {
      throw new Error(`Run at index ${index} missing valid string label`);
    }

    for (const field of REQUIRED_TIMING_FIELDS) {
      if (!(field in run) || run[field] === undefined) {
        throw new Error(`Run "${run.label}" missing required field: ${field}`);
      }
      const val = run[field];
      if (val !== null && (typeof val !== "number" || !Number.isFinite(val))) {
        throw new Error(`Run "${run.label}" field "${field}" must be a finite number or null`);
      }
    }
  }

  return report;
}

/**
 * Returns a compact summary projection of all runs in the report.
 *
 * @param {{ runs?: Array<Record<string, unknown>> }|string} report - The performance report
 * @returns {PerfSummary[]}
 */
export function summarize(report) {
  const data = typeof report === "string" ? JSON.parse(report) : report;
  if (!data?.runs || !Array.isArray(data.runs)) {
    return [];
  }
  return data.runs.map((run) => ({
    label: run.label,
    fcpMs: run.fcpMs,
    lcpMs: run.lcpMs,
    tbtMs: run.tbtMs,
    cls: run.cls,
    firstLoadJsBytes: run.firstLoadJsBytes,
    maxLongTaskMs: run.maxLongTaskMs,
  }));
}

/**
 * Helper to resolve baseline tbtMs for a run label.
 * Supports map keyed by label { [label]: { tbtMs } } or { [label]: number },
 * as well as report shape { runs: [{ label, tbtMs }] }.
 */
function getBaselineTbt(baseline, label) {
  if (!baseline || typeof baseline !== "object") return null;
  const direct = baseline[label];
  if (typeof direct === "number" && Number.isFinite(direct)) {
    return direct;
  }
  if (direct && typeof direct.tbtMs === "number" && Number.isFinite(direct.tbtMs)) {
    return direct.tbtMs;
  }
  if (Array.isArray(baseline.runs)) {
    const run = baseline.runs.find((r) => r?.label === label);
    if (run && typeof run.tbtMs === "number" && Number.isFinite(run.tbtMs)) {
      return run.tbtMs;
    }
  }
  return null;
}

/**
 * Evaluates performance violations against budget and optional baseline.
 *
 * Note: Contract text in Phase 0 specifies two arguments (report, budget), but
 * baseline is accepted as the third argument to keep the function pure and
 * dependency-free as specified in the contract ownership rules.
 *
 * @param {{ runs?: Array<Record<string, unknown>>, host?: { loadAvg1?: number } }|string} report - The performance report (partial reports are valid input: the point is to report what is missing)
 * @param {any} budget - The performance budget
 * @param {any|null} [baseline] - Optional baseline measurements
 * @returns {string[]} List of human-readable violation messages
 */
export function perfViolations(report, budget, baseline = null) {
  const failures = [];
  const data = typeof report === "string" ? JSON.parse(report) : report;
  const runs = Array.isArray(data?.runs) ? data.runs : [];
  const runByLabel = new Map(runs.map((r) => [r?.label, r]));

  // 1. Enforce firstLoadJsBytes caps per label
  const enforcedBytes = budget?.enforce?.firstLoadJsBytes;
  if (enforcedBytes && typeof enforcedBytes === "object") {
    for (const [label, cap] of Object.entries(enforcedBytes)) {
      const run = runByLabel.get(label);
      const actual = run?.firstLoadJsBytes;
      if (actual === null || actual === undefined || !Number.isFinite(actual)) {
        failures.push(`${label}: missing measurement`);
      } else if (Number.isFinite(cap) && actual > cap) {
        failures.push(`${label}: firstLoadJsBytes ${actual} > ${cap}`);
      }
    }
  }

  // 2. Enforce TBT blowup factor against baseline
  // Baseline absent or null skips the check entirely (no baseline is not a violation).
  //
  // Load gate: TBT is wall-clock inside a browser, so it tracks host load, not just the
  // bundle. On this box the same commit measured 138 ms at load ~1 and 794 ms at load ~13,
  // a 6x swing that no blowup factor can attribute honestly. The baseline was taken on an
  // idle host, so a run above the ceiling below is comparing apples to a different machine
  // and the TBT comparison is skipped with an explicit note instead of failing or silently
  // passing. A real regression at idle still fails.
  const maxLoad = Number(budget?.enforce?.maxLoadAvg1ForTiming);
  const reportLoad = data?.host?.loadAvg1;
  const loadComparable =
    !Number.isFinite(maxLoad) || !Number.isFinite(reportLoad) || reportLoad <= maxLoad;
  // Same instrument check: a different core count is a different machine, and TBT is
  // wall-clock. Comparing across it produces a failure that says nothing about the commit.
  const baseCpus = Number(baseline?.host?.cpus);
  const runCpus = Number(data?.host?.cpus);
  const hostComparable =
    !Number.isFinite(baseCpus) || !Number.isFinite(runCpus) || baseCpus === runCpus;
  const blowupFactor = budget?.enforce?.tbtMsBlowupFactor;
  if (loadComparable && hostComparable && baseline && blowupFactor !== null && blowupFactor !== undefined && Number.isFinite(blowupFactor)) {
    for (const run of runs) {
      if (!run?.label) continue;
      const baseTbt = getBaselineTbt(baseline, run.label);
      if (baseTbt !== null && Number.isFinite(baseTbt)) {
        if (run.tbtMs === null || run.tbtMs === undefined || !Number.isFinite(run.tbtMs)) {
          // A null tbtMs means the probe never attributed a long task, which on a
          // shell that has already painted is a measurement bug, not a fast page.
          // Passing it would turn the gate off precisely when instrumentation
          // breaks, so it is a violation rather than a skip.
          failures.push(`${run.label}: missing tbtMs measurement`);
        } else if (run.tbtMs > baseTbt * blowupFactor) {
          failures.push(`${run.label}: tbtMs ${run.tbtMs}ms > ${blowupFactor}x baseline ${baseTbt}ms`);
        }
      }
    }
  }

  // Targets (budget.targets) are advisory and never produce violations
  return failures;
}

/**
 * Formats report runs into a table with stable fixed-width aligned columns.
 * Produces pure string output without ANSI color escapes.
 *
 * @param {{ runs?: Array<Record<string, unknown>> }|string} report - The performance report
 * @returns {string} Fixed-width aligned table text
 */
export function formatTable(report) {
  const data = typeof report === "string" ? JSON.parse(report) : report;
  const runs = Array.isArray(data?.runs) ? data.runs : [];
  if (runs.length === 0) return "";

  const headers = ["label", "fcp", "lcp", "tbt", "cls", "maxTask", "jsKB"];
  const rows = runs.map((run) => [
    String(run.label ?? "n/a"),
    run.fcpMs != null ? `${run.fcpMs}ms` : "n/a",
    run.lcpMs != null ? `${run.lcpMs}ms` : "n/a",
    run.tbtMs != null ? `${run.tbtMs}ms` : "n/a",
    typeof run.cls === "number" ? run.cls.toFixed(3) : "n/a",
    run.maxLongTaskMs != null ? `${run.maxLongTaskMs}ms` : "n/a",
    run.firstLoadJsBytes != null ? `${(run.firstLoadJsBytes / 1024).toFixed(1)}KB` : "n/a",
  ]);

  const allRows = [headers, ...rows];
  const colWidths = headers.map((_, colIdx) =>
    Math.max(...allRows.map((row) => row[colIdx].length))
  );

  return allRows
    .map((row) =>
      row
        .map((cell, colIdx) => (colIdx === row.length - 1 ? cell : cell.padEnd(colWidths[colIdx])))
        .join("  ")
    )
    .join("\n");
}