@progen-labs/spectra 0.0.0-stage → 0.1.0

package/server/analysis/sources.js

@@ -0,0 +1,249 @@
+/**
+ * Maps a position inside a running script to a file in the repo.
+ *
+ * Strategies, tried per script in order of precision:
+ *   1. source map        exact original file, line and function name
+ *   2. webpack markers   dev bundles built with `devtool: false` (this repo's
+ *                        default) keep a `/***\/ "./src/x.tsx":` line in front of
+ *                        every module, so a bundle line maps to its module
+ *   3. script URL        Vite/ESM dev servers serve one script per file;
+ *                        `webpack://` and `webpack-internal://` URLs embed the path
+ *   4. bundle            anything else is reported as the bundle it came from
+ */
+import path from 'node:path';
+import { TraceMap, originalPositionFor } from '@jridgewell/trace-mapping';
+
+const posix = path.posix;
+const MARKER = /^\/\*{3,}\/ "([^"]+)":\s*$/;
+// The banner webpack prints above every module, including the inlined entry module
+// (which has no quoted marker):   !*** ./src/main.jsx ***!
+const BANNER = /^\s*!\*{3} (\S.*?) \*{3}!\s*$/;
+const NATIVE = new Set([
+  '(root)',
+  '(program)',
+  '(idle)',
+  '(garbage collector)',
+]);
+
+export function isNativeFrame(functionName) {
+  return NATIVE.has(functionName);
+}
+
+/** 'node_modules/@a/b/c.js' -> '@a/b', 'node_modules/x/y.js' -> 'x' */
+export function packageOf(file) {
+  const i = file.lastIndexOf('node_modules/');
+  if (i === -1) return null;
+  const rest = file.slice(i + 'node_modules/'.length).split('/');
+  if (rest[0] === '.vite') {
+    // Vite pre-bundles dependencies: .vite/deps/react-dom_client.js -> react-dom
+    const name = (rest[rest.length - 1] || '')
+      .replace(/\.js$/, '')
+      .replace(/_.*$/, '');
+    return name.startsWith('chunk-') ? 'vite-deps' : name;
+  }
+  return rest[0].startsWith('@') ? rest.slice(0, 2).join('/') : rest[0];
+}
+
+/**
+ * Normalises any of the path spellings bundlers produce to a repo-relative
+ * posix path ('src/a/b.tsx', 'node_modules/react/index.js').
+ */
+export function normalizePath(raw, root) {
+  let p = raw;
+  p = p
+    .replace(/^webpack-internal:\/\/\/?/, '')
+    .replace(/^webpack:\/\/[^/]*\//, '');
+  p = p.replace(/^file:\/\//, '');
+  p = p.replace(/[?#].*$/, '').split(' + ')[0];
+  if (p.startsWith('/@fs/')) p = p.slice(4);
+  const nm = p.lastIndexOf('node_modules/');
+  if (nm !== -1) return p.slice(nm);
+  if (root && posix.isAbsolute(p) && p.startsWith(`${root}/`))
+    p = p.slice(root.length + 1);
+  p = posix
+    .normalize(p)
+    .replace(/^(\.\.\/)+/, '')
+    .replace(/^\.\//, '')
+    .replace(/^\//, '');
+  return p;
+}
+
+function pathFromUrl(url, root) {
+  try {
+    const u = new URL(url);
+    if (u.protocol === 'http:' || u.protocol === 'https:') {
+      return normalizePath(decodeURIComponent(u.pathname), root);
+    }
+  } catch {
+    /* not an absolute URL */
+  }
+  return normalizePath(url, root);
+}
+
+function looksLikeBundle(p) {
+  return (
+    /\.(?:chunk|bundle)\.js$|(?:^|\/)(?:static\/assets|assets|dist)\//.test(
+      p,
+    ) || /\.[0-9a-f]{8,}\.js$/.test(p)
+  );
+}
+
+function decodeDataUrl(url) {
+  const m = /^data:[^,]*?(;base64)?,(.*)$/s.exec(url);
+  if (!m) return null;
+  return m[1]
+    ? Buffer.from(m[2], 'base64').toString('utf8')
+    : decodeURIComponent(m[2]);
+}
+
+export class SourceResolver {
+  /**
+   * @param {object} options
+   * @param {string} options.root        absolute path of the frontend project root
+   * @param {Map<string, {url: string, sourceMapURL?: string}>} options.scripts  by scriptId
+   * @param {(scriptId: string) => Promise<string>} options.getSource  Debugger.getScriptSource
+   * @param {(url: string) => Promise<string>} [options.fetchText]
+   */
+  constructor({ root, scripts, getSource, fetchText }) {
+    this.root = root;
+    this.scripts = scripts;
+    this.getSource = getSource;
+    this.fetchText = fetchText || (async url => (await fetch(url)).text());
+    this.strategies = new Map(); // scriptId -> {kind, ...}
+    this.cache = new Map();
+    this.kinds = new Set();
+  }
+
+  /** Load maps / marker indexes for every script that is about to be resolved. */
+  async prepare(scriptIds) {
+    await Promise.all([...new Set(scriptIds)].map(id => this.prepareOne(id)));
+  }
+
+  async prepareOne(scriptId) {
+    if (this.strategies.has(scriptId)) return;
+    const script = this.scripts.get(scriptId);
+    if (!script || !script.url) {
+      this.strategies.set(scriptId, { kind: 'none' });
+      return;
+    }
+    const { url, sourceMapURL } = script;
+
+    if (/^(?:webpack|webpack-internal):/.test(url)) {
+      this.strategies.set(scriptId, { kind: 'url' });
+      return;
+    }
+    if (sourceMapURL) {
+      try {
+        const text = sourceMapURL.startsWith('data:')
+          ? decodeDataUrl(sourceMapURL)
+          : await this.fetchText(new URL(sourceMapURL, url).href);
+        // Resolving against the script URL turns 'heavy.js' or '../src/x.ts' into a full URL.
+        this.strategies.set(scriptId, {
+          kind: 'map',
+          map: new TraceMap(JSON.parse(text), url),
+        });
+        this.kinds.add('sourcemap');
+        return;
+      } catch {
+        /* unreachable or malformed map: fall through */
+      }
+    }
+    try {
+      const source = await this.getSource(scriptId);
+      const markers = indexWebpackModules(source);
+      if (markers.length) {
+        this.strategies.set(scriptId, { kind: 'markers', markers });
+        this.kinds.add('webpack-markers');
+        return;
+      }
+    } catch {
+      /* script gone */
+    }
+    this.strategies.set(scriptId, { kind: 'url' });
+    this.kinds.add('urls');
+  }
+
+  /**
+   * @returns {{file: string, vendor: boolean, pkg: string|null, line: number|null, name: string|null, exact: boolean}}
+   */
+  resolve(scriptId, url, line, column, functionName) {
+    const key = `${scriptId}:${line}:${column}`;
+    let hit = this.cache.get(key);
+    if (hit) return hit;
+    hit = this.resolveUncached(scriptId, url, line, column, functionName);
+    this.cache.set(key, hit);
+    return hit;
+  }
+
+  resolveUncached(scriptId, url, line, column) {
+    const strategy = this.strategies.get(scriptId) || { kind: 'url' };
+    if (strategy.kind === 'map' && line >= 0) {
+      const pos = originalPositionFor(strategy.map, {
+        line: line + 1,
+        column: Math.max(column, 0),
+      });
+      if (pos.source) {
+        return this.finish(
+          pathFromUrl(pos.source, this.root),
+          pos.line,
+          pos.name,
+          true,
+        );
+      }
+    }
+    if (strategy.kind === 'markers' && line >= 0) {
+      const id = moduleAt(strategy.markers, line);
+      if (id)
+        return this.finish(normalizePath(id, this.root), null, null, false);
+    }
+    if (!url) return this.finish('(native)', null, null, false);
+    if (/^(?:pptr:|chrome-extension:|extensions::|devtools:)/.test(url))
+      return this.finish('(injected)', null, null, false);
+    const p = pathFromUrl(url, this.root);
+    return this.finish(
+      looksLikeBundle(p) ? `bundle:${posix.basename(p)}` : p.replace(/^\//, ''),
+      null,
+      null,
+      false,
+    );
+  }
+
+  finish(file, line, name, exact) {
+    const pkg = packageOf(file);
+    return { file, vendor: Boolean(pkg), pkg, line, name, exact };
+  }
+}
+
+const MODULE_ID = /^(?:\.{1,2}\/|webpack\/)/;
+
+/** [{line, id}] sorted by line (0-based) for every webpack module start marker. */
+export function indexWebpackModules(source) {
+  const markers = [];
+  const lines = source.split('\n');
+  for (let i = 0; i < lines.length; i += 1) {
+    const l = lines[i];
+    const c = l.charCodeAt(0);
+    // markers start with '/*' ; banners with optional spaces then '!*'
+    const m = c === 47 ? MARKER.exec(l) : BANNER.exec(l);
+    // a module's quoted marker and its banner name the same module: keep the first
+    if (m && MODULE_ID.test(m[1]) && markers[markers.length - 1]?.id !== m[1])
+      markers.push({ line: i, id: m[1] });
+  }
+  return markers;
+}
+
+export function moduleAt(markers, line) {
+  let lo = 0;
+  let hi = markers.length - 1;
+  let found = -1;
+  while (lo <= hi) {
+    const mid = (lo + hi) >> 1;
+    if (markers[mid].line <= line) {
+      found = mid;
+      lo = mid + 1;
+    } else hi = mid - 1;
+  }
+  if (found === -1) return null;
+  const id = markers[found].id;
+  return id.startsWith('webpack/') ? null : id;
+}

package/server/analysis/trace.js

@@ -0,0 +1,314 @@
+/**
+ * Main-thread analysis of a Chrome trace: what kind of work filled each task,
+ * which tasks were long, and which layout/style work was forced by script.
+ * Timestamps are microseconds (trace clock) throughout.
+ */
+
+export const LONG_TASK_US = 50_000;
+export const THRASH_THRESHOLD = 3;
+
+const SCRIPTING = new Set([
+  'FunctionCall',
+  'EvaluateScript',
+  'v8.evaluateModule',
+  'v8.callFunction',
+  'v8.run',
+  'EventDispatch',
+  'TimerFire',
+  'FireAnimationFrame',
+  'FireIdleCallback',
+  'RunMicrotasks',
+  'XHRReadyStateChange',
+  'XHRLoad',
+  'HandlePostMessage',
+  'FireAnimationFrame',
+]);
+const COMPILE = new Set([
+  'v8.compile',
+  'V8.CompileCode',
+  'CompileScript',
+  'v8.produceCache',
+  'v8.compileModule',
+  'V8.CompileScript',
+]);
+const STYLE = new Set(['UpdateLayoutTree', 'RecalculateStyles']);
+const LAYOUT = new Set(['Layout']);
+const PAINT = new Set([
+  'Paint',
+  'PrePaint',
+  'Layerize',
+  'UpdateLayer',
+  'CompositeLayers',
+  'Commit',
+  'HitTest',
+]);
+const PARSE = new Set(['ParseHTML', 'ParseAuthorStyleSheet']);
+
+export const CATEGORIES = [
+  'scripting',
+  'compile',
+  'style',
+  'layout',
+  'paint',
+  'gc',
+  'parse',
+  'other',
+];
+
+export function categoryOf(name) {
+  if (SCRIPTING.has(name)) return 'scripting';
+  if (COMPILE.has(name)) return 'compile';
+  if (STYLE.has(name)) return 'style';
+  if (LAYOUT.has(name)) return 'layout';
+  if (PAINT.has(name)) return 'paint';
+  if (PARSE.has(name)) return 'parse';
+  if (
+    /GC|Scavenge|MajorGC|MinorGC/.test(name) &&
+    !/^(?:RunTask|ThreadControllerImpl)/.test(name)
+  )
+    return 'gc';
+  return 'other';
+}
+
+const ENTRY_EVENTS = new Set([
+  'EventDispatch',
+  'TimerFire',
+  'FireAnimationFrame',
+  'FireIdleCallback',
+  'XHRReadyStateChange',
+  'XHRLoad',
+  'EvaluateScript',
+  'v8.evaluateModule',
+  'RunMicrotasks',
+  'HandlePostMessage',
+  'FunctionCall',
+  'ParseHTML',
+]);
+const SCRIPT_PARENTS = new Set([...SCRIPTING]);
+
+/** Picks the renderer main thread: the CrRendererMain with the most task time. */
+export function findMainThread(events) {
+  const names = new Map();
+  for (const e of events) {
+    if (
+      e.ph === 'M' &&
+      e.name === 'thread_name' &&
+      e.args?.name === 'CrRendererMain'
+    ) {
+      names.set(`${e.pid}:${e.tid}`, { pid: e.pid, tid: e.tid });
+    }
+  }
+  const busy = new Map();
+  for (const e of events) {
+    if (e.name !== 'RunTask' || e.ph !== 'X') continue;
+    const k = `${e.pid}:${e.tid}`;
+    if (names.has(k)) busy.set(k, (busy.get(k) || 0) + (e.dur || 0));
+  }
+  let best = null;
+  let bestBusy = -1;
+  for (const [k, v] of busy) {
+    if (v > bestBusy) {
+      best = names.get(k);
+      bestBusy = v;
+    }
+  }
+  return best || [...names.values()][0] || null;
+}
+
+/** Complete ('X') events of one thread, with B/E pairs folded in, sorted for nesting. */
+function threadEvents(events, pid, tid) {
+  const out = [];
+  const open = [];
+  for (const e of events) {
+    if (e.pid !== pid || e.tid !== tid) continue;
+    if (e.ph === 'X') out.push(e);
+    else if (e.ph === 'B') open.push(e);
+    else if (e.ph === 'E') {
+      const b = open.pop();
+      if (b) out.push({ ...b, ph: 'X', dur: e.ts - b.ts });
+    }
+  }
+  out.sort((a, b) => a.ts - b.ts || (b.dur || 0) - (a.dur || 0));
+  return out;
+}
+
+function buildTree(list) {
+  const roots = [];
+  const stack = [];
+  for (const e of list) {
+    const node = {
+      e,
+      start: e.ts,
+      end: e.ts + (e.dur || 0),
+      children: [],
+      parent: null,
+      self: e.dur || 0,
+    };
+    while (stack.length && stack[stack.length - 1].end <= node.start)
+      stack.pop();
+    const parent = stack[stack.length - 1] || null;
+    node.parent = parent;
+    if (parent) {
+      parent.children.push(node);
+      parent.self -= node.end - node.start;
+    } else roots.push(node);
+    stack.push(node);
+  }
+  return roots;
+}
+
+function* descendants(node) {
+  const stack = [...node.children];
+  while (stack.length) {
+    const n = stack.pop();
+    yield n;
+    for (const c of n.children) stack.push(c);
+  }
+}
+
+function frameOf(cf) {
+  return {
+    functionName: cf.functionName || '(anonymous)',
+    url: cf.url || '',
+    scriptId: cf.scriptId,
+    lineNumber: cf.lineNumber,
+    columnNumber: cf.columnNumber,
+  };
+}
+
+function describeTrigger(node) {
+  // The outermost entry point (event, timer, script…) with the longest duration.
+  let best = null;
+  const stack = [...node.children].reverse();
+  while (stack.length) {
+    const n = stack.pop();
+    if (
+      ENTRY_EVENTS.has(n.e.name) &&
+      (!best || n.end - n.start > best.end - best.start)
+    )
+      best = n;
+    for (let i = n.children.length - 1; i >= 0; i -= 1)
+      stack.push(n.children[i]);
+  }
+  if (!best) return { type: 'task', detail: '' };
+  const data = best.e.args?.data || {};
+  switch (best.e.name) {
+    case 'EventDispatch':
+      return {
+        type: `${data.type || 'event'} handler`,
+        detail: data.type || '',
+      };
+    case 'TimerFire':
+      return { type: 'timer', detail: `timer #${data.timerId ?? ''}` };
+    case 'FireAnimationFrame':
+      return { type: 'requestAnimationFrame', detail: '' };
+    case 'EvaluateScript':
+    case 'v8.evaluateModule':
+      return { type: 'script evaluation', detail: data.url || '' };
+    case 'FunctionCall':
+      return {
+        type: 'function call',
+        detail: data.functionName
+          ? `${data.functionName} (${data.url || ''}:${data.lineNumber ?? ''})`
+          : data.url || '',
+      };
+    case 'ParseHTML':
+      return { type: 'HTML parsing', detail: '' };
+    default:
+      return { type: best.e.name, detail: data.url || '' };
+  }
+}
+
+/**
+ * @param {object[]} events  raw trace events
+ * @param {{pid: number, tid: number}} thread
+ */
+export function analyzeTrace(events, thread) {
+  const list = threadEvents(events, thread.pid, thread.tid);
+  const roots = buildTree(list);
+
+  const totals = Object.fromEntries(CATEGORIES.map(c => [c, 0]));
+  const counts = { layout: 0, style: 0, paint: 0, gc: 0, majorGc: 0 };
+  let maxLayoutObjects = 0;
+  const tasks = [];
+  const forced = [];
+
+  const visit = (node, forcedAncestor) => {
+    const name = node.e.name;
+    const cat = categoryOf(name);
+    const isTask = name === 'RunTask';
+    if (!isTask || node.children.length === 0)
+      totals[isTask ? 'other' : cat] += Math.max(node.self, 0);
+    if (cat === 'layout') {
+      counts.layout += 1;
+      maxLayoutObjects = Math.max(
+        maxLayoutObjects,
+        node.e.args?.beginData?.totalObjects || 0,
+      );
+    } else if (cat === 'style') counts.style += 1;
+    else if (cat === 'paint' && name === 'Paint') counts.paint += 1;
+    else if (cat === 'gc') {
+      counts.gc += 1;
+      if (/Major/.test(name)) counts.majorGc += 1;
+    }
+    let scripted = forcedAncestor;
+    if (SCRIPT_PARENTS.has(name)) scripted = node;
+    if ((cat === 'layout' || cat === 'style') && forcedAncestor) {
+      const stack =
+        node.e.args?.beginData?.stackTrace || node.e.args?.data?.stackTrace;
+      forced.push({
+        kind: cat,
+        ts: node.start,
+        durUs: node.end - node.start,
+        stack: stack ? stack.map(frameOf) : null,
+        scriptParent: forcedAncestor.e.name,
+        dirtyObjects: node.e.args?.beginData?.dirtyObjects ?? null,
+        totalObjects: node.e.args?.beginData?.totalObjects ?? null,
+      });
+    }
+    for (const c of node.children) visit(c, scripted);
+  };
+
+  for (const r of roots) {
+    if (r.e.name === 'RunTask') {
+      const breakdown = Object.fromEntries(CATEGORIES.map(c => [c, 0]));
+      const before = forced.length;
+      breakdown.other += Math.max(r.self, 0);
+      for (const d of descendants(r))
+        breakdown[categoryOf(d.e.name)] += Math.max(d.self, 0);
+      visit(r, null);
+      const taskForced = forced.slice(before);
+      tasks.push({
+        ts: r.start,
+        durUs: r.end - r.start,
+        breakdown,
+        trigger: describeTrigger(r),
+        forcedCount: taskForced.length,
+        thrash:
+          taskForced.filter(f => f.kind === 'layout').length >=
+          THRASH_THRESHOLD,
+      });
+    } else {
+      visit(r, null);
+    }
+  }
+
+  // RunTask self time is scheduler overhead, not work: fold it into 'other'.
+  const busyUs = tasks.reduce((s, t) => s + t.durUs, 0);
+  const first = list.length ? list[0].ts : 0;
+  const last = list.reduce((m, e) => Math.max(m, e.ts + (e.dur || 0)), 0);
+
+  return {
+    tasks,
+    longTasks: tasks
+      .filter(t => t.durUs >= LONG_TASK_US)
+      .sort((a, b) => b.durUs - a.durUs),
+    forced,
+    totals,
+    counts,
+    maxLayoutObjects,
+    busyUs,
+    firstTs: first,
+    lastTs: last,
+  };
+}