@progen-labs/spectra 0.0.0-stage → 0.1.1

package/src/heat.js

@@ -0,0 +1,177 @@
+import { fmtMs, fmtNumber } from './format.js';
+
+export const FILE_METRICS = [
+  {
+    id: 'selfMs',
+    label: 'CPU self time',
+    unit: 'ms',
+    hint: 'JavaScript executed by functions in this file (excluding callees).',
+  },
+  {
+    id: 'blockMs',
+    label: 'Main-thread blocking',
+    unit: 'ms',
+    hint: 'Self time inside long tasks (>50 ms): what made the page unresponsive.',
+  },
+  {
+    id: 'reactMs',
+    label: 'React render time',
+    unit: 'ms',
+    hint: 'Time React spent rendering components defined in this file (self time).',
+  },
+  {
+    id: 'wasted',
+    label: 'Wasted re-renders',
+    unit: '',
+    hint: 'Renders where props, state and context were identical.',
+  },
+  {
+    id: 'renders',
+    label: 'React renders',
+    unit: '',
+    hint: 'How many times components in this file rendered.',
+  },
+  {
+    id: 'forcedCount',
+    label: 'Forced reflows',
+    unit: '',
+    hint: 'Synchronous layouts/style recalcs triggered by code in this file.',
+  },
+];
+
+export const formatMetric = (metric, value) =>
+  metric.unit === 'ms' ? fmtMs(value) : fmtNumber(Math.round(value));
+
+/**
+ * Directory tree of the profiled files, aggregated by `metric` and sorted
+ * hottest first. Single-child directory chains are merged.
+ */
+export function buildFileTree(files, metric, { hideVendor, rootName = 'target-frontend' } = {}) {
+  const root = {
+    id: '',
+    name: rootName,
+    isDir: true,
+    children: [],
+    parent: null,
+    value: 0,
+  };
+  const dirs = new Map([['', root]]);
+  const dirFor = dirPath => {
+    let node = dirs.get(dirPath);
+    if (node) return node;
+    const slash = dirPath.lastIndexOf('/');
+    const parent = dirFor(slash < 0 ? '' : dirPath.slice(0, slash));
+    node = {
+      id: dirPath,
+      name: dirPath.slice(slash + 1),
+      isDir: true,
+      children: [],
+      parent,
+      value: 0,
+    };
+    parent.children.push(node);
+    dirs.set(dirPath, node);
+    return node;
+  };
+  for (const file of files) {
+    if (hideVendor && file.vendor) continue;
+    const value = file[metric.id] || 0;
+    if (value <= 0) continue;
+    const slash = file.path.lastIndexOf('/');
+    const parent = dirFor(slash < 0 ? '' : file.path.slice(0, slash));
+    parent.children.push({
+      id: file.path,
+      name: file.path.slice(slash + 1),
+      isDir: false,
+      file,
+      vendor: file.vendor,
+      value,
+      parent,
+      children: [],
+    });
+  }
+  const finish = node => {
+    if (!node.isDir) return node.value;
+    node.value = node.children.reduce((sum, c) => sum + finish(c), 0);
+    node.children.sort((a, b) => b.value - a.value);
+    while (
+      node.parent &&
+      node.children.length === 1 &&
+      node.children[0].isDir
+    ) {
+      const only = node.children[0];
+      node.id = only.id;
+      node.name = `${node.name}/${only.name}`;
+      node.children = only.children;
+      node.children.forEach(c => {
+        c.parent = node;
+      });
+    }
+    return node.value;
+  };
+  finish(root);
+  const byId = new Map();
+  const index = node => {
+    byId.set(node.id, node);
+    node.children.forEach(index);
+  };
+  index(root);
+  return { root, byId, total: root.value };
+}
+
+/** Expand the root and the paths leading to the hottest leaves. */
+export function defaultExpanded(tree, topLeaves = 6) {
+  const leaves = [...tree.byId.values()]
+    .filter(n => !n.isDir)
+    .sort((a, b) => b.value - a.value)
+    .slice(0, topLeaves);
+  const set = new Set([tree.root.id]);
+  for (const leaf of leaves)
+    for (let n = leaf.parent; n; n = n.parent) set.add(n.id);
+  return set;
+}
+
+export function ancestorIds(tree, path) {
+  const ids = [];
+  for (let n = tree.byId.get(path)?.parent; n; n = n.parent) ids.push(n.id);
+  return ids;
+}
+
+/** Turn an aggregated node into the shape TreeView renders. */
+export function decorateFileNode(node, tree, metric) {
+  const heat = tree.total ? Math.sqrt(node.value / tree.total) : 0;
+  return {
+    isDir: node.isDir,
+    vendor: node.vendor,
+    expandable: node.isDir && node.children.length > 0,
+    heat,
+    r: 4 + heat * 7,
+    tooltip: `${node.id || tree.root.name}\n${metric.label}: ${formatMetric(metric, node.value)} (${tree.total ? Math.round((node.value / tree.total) * 100) : 0}% of total)`,
+  };
+}
+
+/** Heat + label data for the top-down call tree. */
+export function decorateCallNode(node, total) {
+  const share = total ? node.totalMs / total : 0;
+  const selfShare = total ? node.selfMs / total : 0;
+  return {
+    isDir: false,
+    vendor: node.vendor,
+    expandable: node.children.length > 0,
+    heat: Math.min(1, Math.sqrt(selfShare) * 1.6),
+    r: 4 + Math.sqrt(share) * 6,
+    tooltip: `${node.name}\n${node.file}${node.line ? `:${node.line}` : ''}\nself ${fmtMs(node.selfMs)} · total ${fmtMs(node.totalMs)}`,
+  };
+}
+
+export function defaultCallExpanded(root) {
+  const set = new Set();
+  const limit = root.totalMs * 0.08;
+  const walk = node => {
+    if (node.totalMs < limit || !node.children.length) return;
+    set.add(node.id);
+    node.children.forEach(walk);
+  };
+  walk(root);
+  return set;
+}

package/src/highlight.js

@@ -0,0 +1,45 @@
+import hljs from 'highlight.js/lib/core';
+import css from 'highlight.js/lib/languages/css';
+import javascript from 'highlight.js/lib/languages/javascript';
+import json from 'highlight.js/lib/languages/json';
+import less from 'highlight.js/lib/languages/less';
+import scss from 'highlight.js/lib/languages/scss';
+import typescript from 'highlight.js/lib/languages/typescript';
+import xml from 'highlight.js/lib/languages/xml';
+
+const LANGUAGES = { css, javascript, json, less, scss, typescript, xml };
+Object.entries(LANGUAGES).forEach(([name, def]) =>
+  hljs.registerLanguage(name, def),
+);
+
+const EXT_TO_LANGUAGE = {
+  ts: 'typescript',
+  tsx: 'typescript',
+  mts: 'typescript',
+  js: 'javascript',
+  jsx: 'javascript',
+  mjs: 'javascript',
+  cjs: 'javascript',
+  json: 'json',
+  css: 'css',
+  less: 'less',
+  scss: 'scss',
+  html: 'xml',
+  svg: 'xml',
+};
+const MAX_HIGHLIGHT_CHARS = 400_000;
+
+const escapeHtml = text =>
+  text.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+
+/** Returns HTML that is always escaped (highlight.js escapes its output). */
+export function highlightSource(path, content) {
+  const language = EXT_TO_LANGUAGE[path.split('.').pop().toLowerCase()];
+  if (!language || content.length > MAX_HIGHLIGHT_CHARS)
+    return escapeHtml(content);
+  try {
+    return hljs.highlight(content, { language, ignoreIllegals: true }).value;
+  } catch {
+    return escapeHtml(content);
+  }
+}

package/src/hooks/useCompare.js

@@ -0,0 +1,187 @@
+import { useCallback, useMemo, useState } from 'react';
+import { compareSides } from '../../shared/compare.js';
+import { hashFromFileName, validateReport } from '../../shared/snapshot.js';
+import { api } from '../api.js';
+
+const MAX_FILE_BYTES = 60 * 1024 * 1024;
+
+const emptySide = () => ({
+  runs: [],
+  git: null,
+  hashInput: '',
+  label: '',
+  lookup: { status: 'idle', message: '' },
+  problems: [],
+});
+const initial = () => ({ before: emptySide(), after: emptySide() });
+
+async function readSnapshot(file) {
+  if (/\.trace\.json$/i.test(file.name) || file.size > MAX_FILE_BYTES) {
+    return {
+      ok: false,
+      fileName: file.name,
+      reason:
+        'This looks like a raw Chrome trace (or is too large). Comparison needs the profiler report: use “Snapshot for comparison”.',
+    };
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(await file.text());
+  } catch {
+    return { ok: false, fileName: file.name, reason: 'Not valid JSON.' };
+  }
+  const check = validateReport(parsed);
+  return check.ok
+    ? { ok: true, fileName: file.name, report: parsed }
+    : { ok: false, fileName: file.name, reason: check.reason };
+}
+
+/**
+ * Which two groups of snapshots are being compared ("before" = base commit,
+ * "after" = the commit under review), plus the derived comparison.
+ */
+export function useCompare() {
+  const [sides, setSides] = useState(initial);
+
+  const patch = useCallback(
+    (name, change) =>
+      setSides(prev => ({
+        ...prev,
+        [name]: {
+          ...prev[name],
+          ...(typeof change === 'function' ? change(prev[name]) : change),
+        },
+      })),
+    [],
+  );
+
+  const lookupCommit = useCallback(
+    async (name, hash) => {
+      const rev = hash.trim();
+      if (!rev)
+        return patch(name, {
+          git: null,
+          lookup: { status: 'idle', message: '' },
+        });
+      patch(name, {
+        hashInput: rev,
+        lookup: { status: 'working', message: '' },
+      });
+      try {
+        const git = await api.gitCommit(rev);
+        patch(name, {
+          git,
+          hashInput: git.shortHash,
+          lookup: { status: 'ok', message: '' },
+        });
+      } catch (err) {
+        // Keep the typed hash so the PDF still shows it, with the author unknown.
+        patch(name, {
+          git: {
+            hash: rev,
+            shortHash: rev.slice(0, 10),
+            author: '',
+            subject: '',
+            date: '',
+          },
+          lookup: { status: 'error', message: err.message },
+        });
+      }
+    },
+    [patch],
+  );
+
+  const addFiles = useCallback(
+    async (name, files) => {
+      const results = await Promise.all([...files].map(readSnapshot));
+      const good = results.filter(r => r.ok);
+      patch(name, side => {
+        const known = new Set(side.runs.map(r => r.report.id));
+        const fresh = good
+          .filter(r => !known.has(r.report.id))
+          .map(r => ({ fileName: r.fileName, report: r.report }));
+        return {
+          runs: [...side.runs, ...fresh],
+          problems: results
+            .filter(r => !r.ok)
+            .map(r => `${r.fileName}: ${r.reason}`),
+        };
+      });
+      // The file name carries the commit when the report itself does not.
+      const first = good[0];
+      if (first && !first.report.meta.git) {
+        const hash = hashFromFileName(first.fileName);
+        if (hash) await lookupCommit(name, hash);
+      }
+    },
+    [patch, lookupCommit],
+  );
+
+  const addSaved = useCallback(
+    async (name, id) => {
+      try {
+        const report = await api.report(id);
+        patch(name, side =>
+          side.runs.some(r => r.report.id === report.id)
+            ? {}
+            : {
+                runs: [
+                  ...side.runs,
+                  { fileName: `reports/${id}.json`, report },
+                ],
+                problems: [],
+              },
+        );
+      } catch (err) {
+        patch(name, { problems: [err.message] });
+      }
+    },
+    [patch],
+  );
+
+  const removeRun = useCallback(
+    (name, id) =>
+      patch(name, side => ({
+        runs: side.runs.filter(r => r.report.id !== id),
+      })),
+    [patch],
+  );
+  const setLabel = useCallback(
+    (name, label) => patch(name, { label }),
+    [patch],
+  );
+  const swap = useCallback(
+    () => setSides(prev => ({ before: prev.after, after: prev.before })),
+    [],
+  );
+  const reset = useCallback(() => setSides(initial()), []);
+
+  const comparison = useMemo(
+    () =>
+      compareSides(
+        {
+          runs: sides.before.runs.map(r => r.report),
+          git: sides.before.git,
+          label: sides.before.label,
+        },
+        {
+          runs: sides.after.runs.map(r => r.report),
+          git: sides.after.git,
+          label: sides.after.label,
+        },
+      ),
+    [sides],
+  );
+
+  return {
+    sides,
+    comparison,
+    addFiles,
+    addSaved,
+    removeRun,
+    setLabel,
+    lookupCommit,
+    swap,
+    reset,
+  };
+}

package/src/hooks/useSession.js

@@ -0,0 +1,73 @@
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { api } from '../api.js';
+
+/**
+ * Connection / recording state of the Chrome session, kept fresh by
+ * Server-Sent Events plus a slow poll (for the tab list and probe status).
+ */
+export function useSession({ onReport }) {
+  const [status, setStatus] = useState(null);
+  const [reports, setReports] = useState([]);
+  const [error, setError] = useState('');
+  const onReportRef = useRef(onReport);
+  onReportRef.current = onReport;
+
+  const refresh = useCallback(async () => {
+    try {
+      setStatus(await api.status());
+    } catch (err) {
+      setError(err.message);
+    }
+  }, []);
+  const refreshReports = useCallback(
+    async () => setReports(await api.reports().catch(() => [])),
+    [],
+  );
+
+  useEffect(() => {
+    refresh();
+    refreshReports();
+    const source = new EventSource('/api/events');
+    source.addEventListener('state', e => {
+      const data = JSON.parse(e.data);
+      if (data.error) setError(data.error);
+      refresh();
+    });
+    source.addEventListener('report', e => {
+      refreshReports();
+      onReportRef.current(JSON.parse(e.data).id);
+    });
+    // Tabs and probe status change without any server event.
+    const poll = setInterval(refresh, 4000);
+    return () => {
+      source.close();
+      clearInterval(poll);
+    };
+  }, [refresh, refreshReports]);
+
+  const run = useCallback(
+    async action => {
+      setError('');
+      try {
+        const result = await action();
+        await refresh();
+        return result;
+      } catch (err) {
+        setError(err.message);
+        await refresh();
+        return null;
+      }
+    },
+    [refresh],
+  );
+
+  return {
+    status,
+    reports,
+    error,
+    clearError: () => setError(''),
+    run,
+    refresh,
+    refreshReports,
+  };
+}

package/src/layout.js

@@ -0,0 +1,55 @@
+import { hierarchy, tree } from 'd3';
+
+export const ROW_HEIGHT = 24;
+const CHAR_WIDTH = 6.7;
+const LABEL_PAD = 30;
+const COLUMN_GAP = 40;
+const MAX_LABEL_CHARS = 64;
+
+export function truncate(text) {
+  return text.length > MAX_LABEL_CHARS
+    ? `${text.slice(0, MAX_LABEL_CHARS - 1)}…`
+    : text;
+}
+
+/**
+ * Left-to-right tree layout with one column per depth, each as wide as its
+ * longest label so text never overlaps. `decorate(data)` supplies what the view
+ * needs beyond the label: {heat, r, isDir, expandable, vendor, tooltip}.
+ */
+export function layoutTree(
+  rootData,
+  childrenOf,
+  labelOf,
+  decorate = () => ({}),
+) {
+  const root = hierarchy(rootData, childrenOf);
+  tree()
+    .nodeSize([ROW_HEIGHT, 1])
+    .separation(() => 1)(root);
+  const nodes = root.descendants();
+  const columnWidth = [];
+  for (const node of nodes) {
+    node.label = truncate(labelOf(node.data));
+    node.view = decorate(node.data);
+    node.labelWidth = node.label.length * CHAR_WIDTH + LABEL_PAD;
+    columnWidth[node.depth] = Math.max(
+      columnWidth[node.depth] || 0,
+      node.labelWidth,
+    );
+  }
+  const columnX = [0];
+  for (let d = 1; d < columnWidth.length; d += 1) {
+    columnX[d] = columnX[d - 1] + columnWidth[d - 1] + COLUMN_GAP;
+  }
+  for (const node of nodes) {
+    node.px = columnX[node.depth];
+    node.py = node.x;
+  }
+  return {
+    root,
+    nodes,
+    links: root.links(),
+    byKey: new Map(nodes.map(n => [n.data.id, n])),
+  };
+}

package/src/main.jsx

@@ -0,0 +1,15 @@
+import { StrictMode } from 'react';
+import { createRoot } from 'react-dom/client';
+import App from './App.jsx';
+import { applyAppearance, readAppearance } from './theme.js';
+import './themes.css';
+import './styles.css';
+
+// Before first paint, so the page never flashes the wrong theme.
+applyAppearance(readAppearance());
+
+createRoot(document.getElementById('root')).render(
+  <StrictMode>
+    <App />
+  </StrictMode>,
+);