@progen-labs/spectra 0.1.2 → 0.2.0

package/server/probe.browser.js

@@ -721,6 +721,118 @@
     probe.frameworkName = 'vue';
   }
 
+  // ------------------------------------------------ Angular adapter
+  // Uses Angular's dev-mode framework profiler (window.ng.ɵsetProfiler, present
+  // when ngDevMode is on). Component change-detection fires paired start/end
+  // events (2/3) carrying the component instance; a nesting stack turns those
+  // into per-component render counts and self time (dur minus children), just
+  // like React/Vue. The ng global appears only after bootstrap, so we poll.
+  function installAngularAdapter() {
+    var ngIds = new Map();
+    var nextId = 100000; // keep clear of other adapters' id space
+    var stack = [];
+
+    function clean(n) {
+      return (n || '').replace(/^_+/, '');
+    }
+    function isComponent(instance) {
+      try {
+        var ctor = instance && instance.constructor;
+        if (!ctor) return false;
+        return !!ctor['ɵcmp'] || /Component$/.test(ctor.name || '');
+      } catch (e) {
+        return false;
+      }
+    }
+    function getStat(ctor, name) {
+      var id = ngIds.get(ctor);
+      if (id === undefined) {
+        id = nextId++;
+        ngIds.set(ctor, id);
+      }
+      var stat = probe.stats[id];
+      if (!stat) {
+        stat = probe.stats[id] = {
+          id: id,
+          name: name,
+          kind: 'angular',
+          renders: 0,
+          mounts: 0,
+          wasted: 0,
+          selfMs: 0,
+          totalMs: 0,
+          maxMs: 0,
+          reasons: { props: 0, state: 0, hooks: 0, context: 0, parent: 0 },
+          props: {},
+          parents: {},
+          file: '',
+        };
+      }
+      return stat;
+    }
+    function onEvent(event, instance) {
+      if (!probe.active) return;
+      if (event === 2) {
+        // Component change-detection start. Push a frame (null for non-component
+        // instances like structural-directive contexts) to keep the stack balanced.
+        if (!isComponent(instance)) {
+          stack.push(null);
+          return;
+        }
+        if (stack.length === 0) probe.commitCount = (probe.commitCount || 0) + 1;
+        stack.push({
+          ctor: instance.constructor,
+          name: clean(instance.constructor.name),
+          start: performance.now(),
+          child: 0,
+        });
+      } else if (event === 3) {
+        var f = stack.pop();
+        if (!f) return;
+        var dur = performance.now() - f.start;
+        var self = dur - f.child;
+        if (self < 0) self = 0;
+        for (var i = stack.length - 1; i >= 0; i--) {
+          if (stack[i]) {
+            stack[i].child += dur;
+            break;
+          }
+        }
+        var stat = getStat(f.ctor, f.name);
+        stat.renders++;
+        stat.selfMs += self;
+        stat.totalMs += dur;
+        if (self > stat.maxMs) stat.maxMs = self;
+        probe.sawTimings = true;
+      }
+    }
+    function register() {
+      try {
+        var ng = window.ng;
+        if (ng && typeof ng['ɵsetProfiler'] === 'function') {
+          ng['ɵsetProfiler'](function (event, instance) {
+            try {
+              onEvent(event, instance);
+            } catch (e) {}
+          });
+          probe.frameworkName = 'angular';
+          probe.frameworkDetected = true;
+          probe.frameworkVersion =
+            (window.ng && window.ng.ɵgetInjectorMetadata ? '' : '') || probe.frameworkVersion;
+          return true;
+        }
+      } catch (e) {}
+      return false;
+    }
+    if (!register()) {
+      var tries = 0;
+      var iv = setInterval(function () {
+        tries++;
+        if (register() || tries > 200) clearInterval(iv); // poll up to ~8s
+      }, 40);
+    }
+  }
+
   // ------------------------------------------------ Framework fallbacks
   // Provide lightweight probes for Vue, Svelte and Angular when React is not detected.
   function installFrameworkProbes() {
@@ -822,7 +934,8 @@
   try {
     var fwHint = SPECTRA_FRAMEWORK && SPECTRA_FRAMEWORK.framework;
     if (fwHint === 'vue') installVueAdapter();
-    else if (!WANT_REACT) installFrameworkProbes(); // svelte/angular: heuristic for now
+    else if (fwHint === 'angular') installAngularAdapter();
+    else if (!WANT_REACT) installFrameworkProbes(); // svelte: heuristic for now
   } catch (e) {}
   installObservers();
 })();

package/server/project-config.js

@@ -0,0 +1,30 @@
+/**
+ * Per-project settings: spectra.config.json in the profiled project's root
+ * (or the file passed with --config). Today it holds performance budgets:
+ *
+ *   { "budgets": { "tbtMs": 200, "lcpMs": 2500, "cls": 0.1, "criticalFindings": 0 } }
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { FRONTEND_ROOT } from './config.js';
+import { validateBudgets } from '../shared/result.js';
+
+export const CONFIG_FILE = 'spectra.config.json';
+
+/** @returns {{file: string|null, budgets: object}} — throws a readable Error on bad config */
+export function loadProjectConfig(explicitFile) {
+  const file = explicitFile ? path.resolve(explicitFile) : path.join(FRONTEND_ROOT, CONFIG_FILE);
+  if (!fs.existsSync(file)) {
+    if (explicitFile) throw new Error(`config file not found: ${file}`);
+    return { file: null, budgets: {} };
+  }
+  let raw;
+  try {
+    raw = JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch (err) {
+    throw new Error(`${file} is not valid JSON (${err.message}).`);
+  }
+  const checked = validateBudgets(raw?.budgets);
+  if (!checked.ok) throw new Error(`${path.basename(file)}: ${checked.error}`);
+  return { file, budgets: checked.budgets };
+}

package/server/recorder.js

@@ -18,6 +18,7 @@ import { attachChrome, launchChrome } from './chrome.js';
 import { FRONTEND_ROOT, REPORTS_DIR, SOURCE_ROOTS, FRAMEWORK } from './config.js';
 import { SourceIndex } from './analysis/locate.js';
 import { gitInfo } from './git.js';
+import { REPORT_SCHEMA_VERSION } from '../shared/result.js';
 import { buildSignInUrl, looksSignedOut } from './signin.js';
 
 const here = path.dirname(fileURLToPath(import.meta.url));
@@ -417,7 +418,7 @@ export class PerfSession extends EventEmitter {
           .toISOString()
           .replace(/[-:]/g, '')
           .replace(/\..+/, '') + `-${rec.mode}`;
-      const report = await buildReport({
+      const built = await buildReport({
         events,
         probe,
         metrics: { before: rec.metricsBefore, after: metricsAfter, dom },
@@ -438,6 +439,8 @@ export class PerfSession extends EventEmitter {
           navUrl: this.navigation?.url ?? '',
         },
       });
+      // versioned so editors, CI and agents can tell which format they read
+      const report = { schemaVersion: REPORT_SCHEMA_VERSION, ...built };
       this.lastTrace = { id: report.id, text: traceText };
       report.pageView = pageView
         ? { ...pageView.layout, hasImage: true }

package/server/reports-cli.js

@@ -0,0 +1,31 @@
+/**
+ * spectra reports [--json] [--limit n] — the saved reports, newest first, so
+ * their ids can be passed to `spectra compare` or opened in the dashboard.
+ */
+import { listReports } from './recorder.js';
+import { REPORTS_DIR } from './config.js';
+import { intOption, parseArgs } from './args.js';
+import { EXIT, SPECTRA_VERSION, exitAfterFlush, writeResult } from './output.js';
+import { buildReportsResult } from '../shared/result.js';
+
+const { opt, flag } = parseArgs(process.argv.slice(2));
+let limit;
+try {
+  limit = intOption(opt('limit'), 'limit', { max: 10_000, fallback: 20 });
+} catch (err) {
+  console.error(`spectra: ${err.message}`);
+  process.exit(EXIT.ERROR);
+}
+
+const reports = listReports().slice(0, limit);
+if (flag('json')) {
+  writeResult(buildReportsResult({ reports, dir: REPORTS_DIR, spectraVersion: SPECTRA_VERSION }), { json: true });
+} else if (!reports.length) {
+  console.log(`No reports yet in ${REPORTS_DIR}. Create one with: spectra performance --quick`);
+} else {
+  console.log(`${'Report id'.padEnd(26)}${'Mode'.padEnd(7)}${'Findings'.padStart(9)}${'Critical'.padStart(10)}  URL`);
+  for (const r of reports)
+    console.log(`${r.id.padEnd(26)}${String(r.mode).padEnd(7)}${String(r.findings).padStart(9)}${String(r.critical).padStart(10)}  ${r.url}`);
+  console.log(`\n${reports.length} shown · ${REPORTS_DIR}`);
+}
+exitAfterFlush(EXIT.OK);

package/server/test-result.js

@@ -0,0 +1,226 @@
+// Named test-*.js (not *.test.js): the repo's jest testRegex covers tools/.
+import assert from 'node:assert/strict';
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { test } from 'node:test';
+import { fileURLToPath } from 'node:url';
+import {
+  BUDGET_KEYS,
+  REPORT_SCHEMA_VERSION,
+  RESULT_SCHEMA_VERSION,
+  SUMMARY_METRICS,
+  briefFinding,
+  buildCompareResult,
+  buildEvaluationResult,
+  buildProfileResult,
+  checkBudgets,
+  isRegression,
+  representativeRun,
+  summarize,
+  summarizeRuns,
+  validateBudgets,
+} from '../shared/result.js';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const readSchema = name => JSON.parse(fs.readFileSync(path.join(ROOT, 'schema', name), 'utf8'));
+
+const finding = (over = {}) => ({
+  id: 'slow-component-Row-src/Row.jsx',
+  severity: 'critical',
+  category: 'React',
+  title: 'Row is slow to render',
+  detail: 'src/Row.jsx:3.',
+  impactMs: 1442.94,
+  file: 'src/Row.jsx',
+  fix: 'Memoise it.',
+  culprits: [{ fn: 'Row', file: 'src/Row.jsx', line: 3, lineKind: 'exact', abs: '/p/src/Row.jsx', ms: 1442.94, note: 'slow render' }],
+  ...over,
+});
+
+/** A report with just enough in it for summaries, budgets and compare. */
+function report(id, { tbt = 0, lcp = 100, scripting = 1000, findings = [finding()] } = {}) {
+  return {
+    schemaVersion: REPORT_SCHEMA_VERSION,
+    id,
+    createdAt: '2026-10-17T10:00:00.000Z',
+    meta: { url: 'http://localhost:5188/', title: 'Demo', mode: 'load', durationMs: 4000, cpuThrottle: 1, attribution: 'sourcemap', git: null, label: '' },
+    vitals: { tbtMs: tbt, lcpMs: lcp, fcpMs: lcp, cls: 0.0015, inpMs: null, ttfbMs: 2.4, longTaskCount: 0, maxLongTaskMs: 0 },
+    totals: { activeMs: scripting + 100, scriptingMs: scripting, layoutMs: 10, styleMs: 10, paintMs: 5, gcMs: 5, compileMs: 5, layoutCount: 4, styleRecalcCount: 4, forcedLayoutCount: 0, forcedStyleCount: 0, forcedMs: 0 },
+    memory: { domNodes: 800, listeners: 20, heapUsedMb: 9.4, heapGrowthMb: 0 },
+    network: { count: 10, totalEncoded: 2048 * 1024 },
+    react: { detected: true, hasTimings: true, version: '18.3.1', components: [], commits: { count: 60, totalMs: 100, maxMs: 10 } },
+    files: [],
+    findings,
+  };
+}
+
+test('summarize reads the headline numbers, rounded, with null where unmeasured', () => {
+  const s = summarize(report('a', { tbt: 212.96 }));
+  assert.equal(s.tbtMs, 213);
+  assert.equal(s.cls, 0.002);
+  assert.equal(s.inpMs, null);
+  assert.equal(s.transferKb, 2048);
+  assert.equal(s.criticalFindings, 1);
+  assert.deepEqual(Object.keys(s), SUMMARY_METRICS.map(m => m.key));
+});
+
+test('several runs reduce to medians with a min / max spread; the typical run supplies the findings', () => {
+  const runs = [report('r1', { scripting: 900 }), report('r2', { scripting: 1000 }), report('r3', { scripting: 2000 })];
+  const { summary, spread } = summarizeRuns(runs);
+  assert.equal(summary.runs, 3);
+  assert.equal(summary.scriptingMs, 1000);
+  assert.deepEqual(spread.scriptingMs, { min: 900, max: 2000 });
+  assert.equal(representativeRun(runs).id, 'r2');
+  // one run: no spread to speak of
+  assert.deepEqual(summarizeRuns([runs[0]]).spread, {});
+});
+
+test('briefFinding keeps what a reader acts on', () => {
+  const b = briefFinding(finding());
+  assert.equal(b.impactMs, 1442.9);
+  assert.equal(b.line, 3);
+  assert.equal(b.culprits[0].abs, '/p/src/Row.jsx');
+  assert.equal(b.fix, 'Memoise it.');
+});
+
+test('budgets: unknown keys and bad limits are rejected, unmeasured metrics are skipped', () => {
+  assert.equal(validateBudgets({ tbt: 200 }).ok, false);
+  assert.match(validateBudgets({ tbt: 200 }).error, /Unknown budget "tbt"/);
+  assert.equal(validateBudgets({ tbtMs: -1 }).ok, false);
+  assert.equal(validateBudgets(undefined).ok, true);
+  const res = checkBudgets({ tbtMs: 200, inpMs: 100, criticalFindings: 0 }, [{ name: 'median', summary: summarize(report('a', { tbt: 250 })) }]);
+  assert.equal(res.ok, false);
+  assert.equal(res.failed, 2);
+  assert.deepEqual(res.checks.map(c => c.status), ['fail', 'skipped', 'fail']);
+  assert.equal(checkBudgets({}, []), null);
+});
+
+test('profile result: versioned envelope, per-run summaries, findings marked with how many runs saw them', () => {
+  const runs = [report('r1'), report('r2', { findings: [] }), report('r3')];
+  const result = buildProfileResult({ reports: runs, fileOf: id => `/reports/${id}.json`, target: 'demo', spectraVersion: '9.9.9', budgets: { tbtMs: 200 } });
+  assert.equal(result.schemaVersion, RESULT_SCHEMA_VERSION);
+  assert.equal(result.kind, 'profile');
+  assert.equal(result.runs[1].file, '/reports/r2.json');
+  assert.equal(result.findings[0].seenIn, 2);
+  assert.equal(result.budgets.ok, true);
+});
+
+test('evaluation result: one summary per journey, budgets name the journey that broke them', () => {
+  const reports = { base: report('base'), p1: report('p1', { tbt: 400 }) };
+  const evaluation = {
+    url: 'http://localhost:5188/',
+    target: 'demo',
+    discovered: 3,
+    skippedDestructive: [],
+    baseline: { id: 'base', title: 'Initial page load', kind: 'load', ok: true },
+    paths: [{ id: 'p1', title: 'Click "Long task"', kind: 'interaction', ok: true }],
+  };
+  const result = buildEvaluationResult({ evaluation, readReport: id => reports[id], budgets: { tbtMs: 200 } });
+  assert.equal(result.journeys.length, 2);
+  assert.equal(result.passed, 1);
+  const failed = result.budgets.checks.filter(c => c.status === 'fail');
+  assert.deepEqual(failed.map(c => c.where), ['Click "Long task"']);
+});
+
+test('compare result wraps the shared comparison and flags regressions', () => {
+  const slow = [report('b1', { scripting: 1500 }), report('b2', { scripting: 1520 })];
+  const fast = [report('a1', { scripting: 90, findings: [] }), report('a2', { scripting: 95, findings: [] })];
+  const better = buildCompareResult({ before: slow, after: fast });
+  assert.equal(better.kind, 'compare');
+  assert.equal(better.comparison.verdict, 'improved');
+  assert.equal(better.comparison.findings.resolved.length, 1);
+  assert.equal(isRegression(better), false);
+  assert.equal(isRegression(buildCompareResult({ before: fast, after: slow })), true);
+});
+
+test('the published schemas list exactly the metrics and budgets the code produces', () => {
+  const result = readSchema('result.schema.json');
+  assert.deepEqual(Object.keys(result.$defs.summary.properties), SUMMARY_METRICS.map(m => m.key));
+  assert.equal(result.properties.schemaVersion.const, RESULT_SCHEMA_VERSION);
+  const config = readSchema('config.schema.json');
+  assert.deepEqual(Object.keys(config.properties.budgets.properties), BUDGET_KEYS);
+  // every key the schema requires is present in what the builders return
+  const profile = buildProfileResult({ reports: [report('r1')], budgets: {} });
+  for (const key of [...result.required, ...result.$defs.profile.required]) assert.ok(key in profile, `profile result lacks ${key}`);
+  const finding0 = profile.findings[0];
+  for (const key of result.$defs.finding.required) assert.ok(key in finding0, `finding lacks ${key}`);
+});
+
+// ------------------------------------------------------------------ CLI (no Chrome needed)
+
+function workspace() {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'spectra-cli-'));
+  const reports = path.join(dir, '.spectra', 'reports');
+  fs.mkdirSync(reports, { recursive: true });
+  const save = r => fs.writeFileSync(path.join(reports, `${r.id}.json`), JSON.stringify(r));
+  save(report('20261017T100000-load', { scripting: 1500 }));
+  save(report('20261017T100010-load', { scripting: 1510 }));
+  save(report('20261017T100100-load', { scripting: 90, findings: [] }));
+  save(report('20261017T100110-load', { scripting: 92, findings: [] }));
+  return { dir, reports };
+}
+
+const run = (script, args, ws) =>
+  spawnSync(process.execPath, [path.join(ROOT, script), ...args], {
+    cwd: ws.dir,
+    encoding: 'utf8',
+    env: { ...process.env, PERF_FRONTEND_DIR: ws.dir, PERF_REPORTS_DIR: ws.reports },
+  });
+
+test('cli: compare by ids prints a verdict, emits JSON, and exits 2 on a regression when asked', () => {
+  const ws = workspace();
+  const before = '20261017T100000-load,20261017T100010-load';
+  const after = '20261017T100100-load,20261017T100110-load';
+  const ok = run('bin/spectra.js', ['compare', before, after, '--json'], ws);
+  assert.equal(ok.status, 0, ok.stderr);
+  const result = JSON.parse(ok.stdout);
+  assert.equal(result.comparison.verdict, 'improved');
+  assert.match(ok.stderr, /Spectra compare — IMPROVED/);
+
+  const worse = run('bin/spectra.js', ['compare', after, before, '--fail-on-regression'], ws);
+  assert.equal(worse.status, 2);
+  assert.match(worse.stdout, /REGRESSED/);
+  fs.rmSync(ws.dir, { recursive: true, force: true });
+});
+
+test('cli: a saved profile result works as a compare side, from any directory', () => {
+  const ws = workspace();
+  const profile = buildProfileResult({
+    reports: ['20261017T100000-load', '20261017T100010-load'].map(id => JSON.parse(fs.readFileSync(path.join(ws.reports, `${id}.json`), 'utf8'))),
+    fileOf: id => path.join(ws.reports, `${id}.json`),
+  });
+  fs.writeFileSync(path.join(ws.dir, 'before.json'), JSON.stringify(profile));
+  const res = run('bin/spectra.js', ['compare', 'before.json', '20261017T100100-load', '--out', 'cmp.json'], ws);
+  assert.equal(res.status, 0, res.stderr);
+  const written = JSON.parse(fs.readFileSync(path.join(ws.dir, 'cmp.json'), 'utf8'));
+  assert.equal(written.comparison.before.runs.length, 2);
+  fs.rmSync(ws.dir, { recursive: true, force: true });
+});
+
+test('cli: reports lists newest first; bad input fails fast with exit 1 and no browser', () => {
+  const ws = workspace();
+  const list = run('bin/spectra.js', ['reports', '--json'], ws);
+  assert.equal(list.status, 0, list.stderr);
+  const parsed = JSON.parse(list.stdout);
+  assert.equal(parsed.kind, 'reports');
+  assert.equal(parsed.reports[0].id, '20261017T100110-load');
+
+  const missing = run('bin/spectra.js', ['compare', 'nope', '20261017T100100-load'], ws);
+  assert.equal(missing.status, 1);
+  assert.match(missing.stderr, /no report "nope"/);
+
+  fs.writeFileSync(path.join(ws.dir, 'spectra.config.json'), JSON.stringify({ budgets: { tbt: 200 } }));
+  const badConfig = run('server/cli.js', ['--url', 'http://localhost:9/', '--mode', 'load'], ws);
+  assert.equal(badConfig.status, 1);
+  assert.match(badConfig.stderr, /Unknown budget "tbt"/);
+
+  const runsOnSuite = run('bin/spectra.js', ['performance', '--runs', '3', '--url', 'http://localhost:9/'], ws);
+  assert.equal(runsOnSuite.status, 1);
+  assert.match(runsOnSuite.stderr, /--runs works with single-page profiles/);
+
+  const quickLive = run('bin/spectra.js', ['performance', '--quick', '--mode', 'live', '--url', 'http://localhost:9/'], ws);
+  assert.equal(quickLive.status, 1);
+  fs.rmSync(ws.dir, { recursive: true, force: true });
+});

package/shared/compare.js

@@ -84,6 +84,7 @@ export function formatValue(unit, v) {
   if (!finite(v)) return '–';
   switch (unit) {
     case 'ms':
+      if (v === 0) return '0 ms';
       if (v >= 1000) return `${(v / 1000).toFixed(2)} s`;
       if (v >= 100) return `${Math.round(v)} ms`;
       if (v >= 1) return `${v.toFixed(1)} ms`;