@luigisbox/luma 0.0.0-stage → 0.2.0

package/tasks/run.mjs

@@ -0,0 +1,305 @@
+#!/usr/bin/env node
+// yarn luma tasks: which main-thread tasks of ours are over a frame's budget on the
+// storefront, and what is in them. Run from the integration repository (Luma
+// as the @luigisbox/luma package, or an older luma/ submodule):
+//
+//   yarn luma tasks                         every scenario, 3 runs each, 4x CPU, budget 16 ms
+//   yarn luma tasks --only category,more    some of them
+//   yarn luma tasks --headed                show the browser
+//
+// (bin/luma.mjs; the storefront's host from luma.config.mjs `host`, or LBX_HOST.)
+//
+// Scenarios: the pages loaded (luma.config.mjs `perf.pages`, else home and
+// its fixtures' category, search and product), then on the category page (or
+// the search page) a change of the listing's state (`change`: its first
+// visible link that leads to another state, `[data-lbx-href]`, which Luma's
+// facets and sort controls carry), `more` (`[data-lbx-more]`), `back` (to the
+// state before the change), and `typing` (fixtures.query typed into
+// fixtures.input or `_global.inputSelector`, at 140 ms a key).
+//
+// Each run takes a CPU profile of the page's isolate and a trace of its tasks
+// together (tasks/model.mjs): a task's time, ours (a frame of ours on the
+// stack) and our own (the innermost frame with a script is ours: not the
+// site's code under our calls, e.g. its pushState hooks). Functions are named
+// by the integration's source (a build with source maps, into a temporary
+// folder; dist/ is left as it is). The verdict per scenario is the median of
+// each run's worst task by our own time; exit 1 when one is over the budget.
+//
+// The page is the live storefront (its host known) with Luma put in as a customer
+// installs it (the early-hold snippet, then the build: parity/hold.mjs), or
+// the integration's stub page (--origin stub, luma.config.mjs stubPage). A
+// storefront that answers with a bot challenge is never worked around: the
+// run says so and falls back to the stub page. Run it on the client's own site
+// with their knowledge, or ask them to allowlist the runner. Nothing of the site is changed.
+import { execFileSync } from 'node:child_process';
+import { existsSync, mkdtempSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { extname, join, normalize, resolve } from 'node:path';
+import { inside } from '../bin/paths.mjs';
+import { attribute, formatReport, mainThreadTasks, sampleTimes, summarize } from './model.mjs';
+
+const USAGE = `usage: yarn luma tasks [options]
+
+  --only a,b          scenarios: home, category, search, product (the pages), change, more, back, typing
+  --runs N            runs per scenario (default 3)
+  --cpu N             CPU throttling (default 4)
+  --budget MS         our own time per task (default 16: a frame)
+  --origin stub|live  the live storefront (default where its host is known: luma.config.mjs host, LBX_HOST) or the stub page
+  --headed            show the browser
+  --no-build          use dist/ as it is (no source maps: functions by their minified names)
+  --json FILE         also write the results as JSON
+  --site-dir DIR      the integration repository (default: the current directory, LBX_SITE_DIR)`;
+
+const args = process.argv.slice(2);
+const opt = { only: [], runs: 3, cpu: 4, budget: 16, origin: '', headed: false, build: true, json: '', siteDir: '' };
+const die = (msg) => {
+  console.error(msg);
+  process.exit(2);
+};
+for (let i = 0; i < args.length; i++) {
+  const a = args[i];
+  const next = () => {
+    const v = args[++i];
+    if (v === undefined || v.startsWith('--')) die(`${a} needs a value\n\n${USAGE}`);
+    return v;
+  };
+  if (a === '--help' || a === '-h') {
+    console.log(USAGE);
+    process.exit(0);
+  } else if (a === '--only') opt.only = next().split(',').map((s) => s.trim()).filter(Boolean);
+  else if (a === '--runs') opt.runs = Number(next());
+  else if (a === '--cpu') opt.cpu = Number(next());
+  else if (a === '--budget') opt.budget = Number(next());
+  else if (a === '--origin') opt.origin = next();
+  else if (a === '--headed') opt.headed = true;
+  else if (a === '--no-build') opt.build = false;
+  else if (a === '--json') opt.json = next();
+  else if (a === '--site-dir') opt.siteDir = next();
+  else die(`unknown option ${a}\n\n${USAGE}`);
+}
+const SITE_DIR = resolve(opt.siteDir || process.env.LBX_SITE_DIR || process.cwd());
+if (!existsSync(join(SITE_DIR, 'integration'))) die(`${SITE_DIR} has no integration/ folder: run it from the integration repository (or --site-dir).`);
+process.env.LBX_SITE_DIR = SITE_DIR;
+if (opt.origin && !/^(stub|live)$/.test(opt.origin)) die(`--origin must be stub or live, not "${opt.origin}"`);
+
+for (const dep of ['playwright-core', '@jridgewell/trace-mapping']) {
+  try {
+    await import(dep);
+  } catch {
+    die(`Luma's dependencies are not installed (${dep} is missing): run \`yarn install\`.`);
+  }
+}
+const { chromium } = await import('playwright-core');
+const { TraceMap, originalPositionFor } = await import('@jridgewell/trace-mapping');
+const { loadConfig } = await import('../bin/config.mjs');
+const config = await loadConfig(SITE_DIR);
+const { host: HOST, stubPage } = config;
+const { SNIPPET, holdInit } = await import('../parity/hold.mjs');
+
+const F = config.fixtures;
+const ORIGIN = `https://${HOST}`;
+const PREFIX = '/__lbx/tasks/';
+const BUNDLE = `${ORIGIN}${PREFIX}luma-integration.js`;
+// The live storefront where its host is known (LBX_HOST, luma.config.mjs `host`), else the stub page.
+let stub = (opt.origin || (config.hostKnown ? 'live' : 'stub')) === 'stub';
+
+// ------------------------------------------------------------------ build (source maps, a folder of its own)
+
+let DIST = join(SITE_DIR, 'dist');
+let temp = '';
+if (opt.build) {
+  temp = DIST = mkdtempSync(join(tmpdir(), 'lbx-tasks-'));
+  process.stderr.write('building with source maps… ');
+  try {
+    execFileSync('yarn', ['vite', 'build', '--sourcemap', '--outDir', DIST, '--emptyOutDir'], { cwd: SITE_DIR, stdio: ['ignore', 'pipe', 'pipe'] });
+    process.stderr.write('done\n');
+  } catch (e) {
+    process.stderr.write('failed\n');
+    die(`the build failed:\n${e.stdout ?? ''}${e.stderr ?? ''}`);
+  }
+}
+if (!existsSync(join(DIST, 'luma-integration.js'))) die(`${DIST}/luma-integration.js is missing: run yarn build (or drop --no-build).`);
+process.on('exit', () => temp && rmSync(temp, { recursive: true, force: true }));
+
+// Frames of ours: the build's scripts. Named by their source where the build has maps.
+const OURS = new RegExp(`${PREFIX.replace(/\//g, '\\/')}`);
+const ours = (f) => OURS.test(f.url ?? '');
+const maps = new Map();
+const nameOf = (f) => {
+  const rel = (f.url ?? '').split(PREFIX)[1];
+  if (rel !== undefined && !maps.has(rel)) {
+    const file = join(DIST, `${rel}.map`);
+    maps.set(rel, existsSync(file) ? new TraceMap(readFileSync(file, 'utf8')) : null);
+  }
+  const m = rel === undefined ? null : maps.get(rel);
+  const p = m ? originalPositionFor(m, { line: f.lineNumber + 1, column: f.columnNumber }) : null;
+  if (p?.source) return `${p.name || f.functionName || '(anonymous)'}  ${p.source.replace(/^.*?\b(src|integration|node_modules)\//, '$1/')}:${p.line}`;
+  return `${f.functionName || '(anonymous)'}  ${rel ?? f.url}:${f.lineNumber + 1}`;
+};
+
+// ------------------------------------------------------------------ browser
+
+const TYPES = { '.js': 'text/javascript', '.css': 'text/css', '.json': 'application/json', '.map': 'application/json' };
+const launch = async () => {
+  const o = { headless: !opt.headed };
+  const tries = [...(process.env.LBX_CHROMIUM_PATH ? [{ ...o, executablePath: process.env.LBX_CHROMIUM_PATH }] : []), { ...o, channel: 'chromium' }, { ...o, channel: 'chrome' }];
+  let err;
+  for (const t of tries) {
+    try {
+      return await chromium.launch(t);
+    } catch (e) {
+      err = e;
+    }
+  }
+  die(`No Chromium to run: install Chrome, or \`yarn playwright-core install chromium\`, or set LBX_CHROMIUM_PATH.\n${err?.message?.split('\n')[0] ?? ''}`);
+};
+
+const newContext = async (browser) => {
+  const ctx = await browser.newContext({ viewport: { width: 1440, height: 900 }, serviceWorkers: 'block' });
+  await ctx.route(/^https:\/\/(cdn\.luigisbox\.(com|tech)|cdn\.eu1\.luigisbox\.ai|scripts\.luigisbox\.(com|tech))\//, (r) => r.abort('blockedbyclient'));
+  await ctx.route(`${ORIGIN}/**`, async (route) => {
+    const req = route.request();
+    const url = new URL(req.url());
+    if (url.pathname.startsWith(PREFIX)) {
+      const file = normalize(join(DIST, decodeURIComponent(url.pathname.slice(PREFIX.length))));
+      if (!inside(DIST, file) || !existsSync(file) || !statSync(file).isFile()) return route.fulfill({ status: 404, body: '' });
+      return route.fulfill({ status: 200, body: readFileSync(file), headers: { 'content-type': TYPES[extname(file)] ?? 'application/octet-stream', 'cache-control': 'no-store' } });
+    }
+    if (!stub) return route.fallback();
+    if (req.resourceType() === 'document') return route.fulfill({ status: 200, contentType: 'text/html; charset=utf-8', body: await stubPage(url) });
+    return route.fulfill({ status: 404, body: '' });
+  });
+  await ctx.addInitScript(holdInit, { origin: ORIGIN, bundle: BUNDLE, snippet: SNIPPET, tag: 'tasks' });
+  return ctx;
+};
+
+const challenged = async (res, page) => {
+  if (!res) return 'no response';
+  if (res.headers()['cf-mitigated'] === 'challenge') return `a Cloudflare challenge (HTTP ${res.status()})`;
+  if (res.status() === 429) return 'HTTP 429 (rate limited)';
+  if (res.status() === 403 || res.status() === 503) {
+    const text = await page.content().catch(() => '');
+    return /challenge-platform|cf-chl|Just a moment|captcha|Attention Required/i.test(text) ? `a bot challenge (HTTP ${res.status()})` : `HTTP ${res.status()}`;
+  }
+  return '';
+};
+
+// ------------------------------------------------------------------ scenarios
+
+const pages = config.perf?.pages ?? Object.fromEntries([['home', '/'], ['category', F.category], ['search', F.query ? `/search?q=${encodeURIComponent(F.query)}` : null], ['product', F.product]].filter(([, p]) => p));
+const listingPath = pages.category ?? pages.search;
+const scenarios = [
+  ...Object.entries(pages).map(([name, path]) => ({ name, path, load: true })),
+  ...(listingPath ? ['change', 'more', 'back'].map((name) => ({ name, path: listingPath })) : []),
+  ...(F.query ? [{ name: 'typing', path: '/' }] : []),
+].filter((s) => !opt.only.length || opt.only.includes(s.name));
+if (!scenarios.length) die('no scenario to run (luma.config.mjs perf.pages or fixtures; --only)');
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+const LISTING = 'lbx-plp, lbx-search';
+/** Ours has drawn and is not busy (a listing), or the page has had its time (any other). */
+const settled = (page) =>
+  page.waitForFunction((sel) => {
+    const e = document.querySelector(sel);
+    return !e || (!!e.dataset.total && e.getAttribute('aria-busy') !== 'true');
+  }, LISTING, { timeout: 30000, polling: 100 }).catch(() => {});
+/** A click as a pointer's (detail 1: Luma tells a keyboard's "show more" by detail 0), dispatched: a consent dialog over the page does not take it. */
+const click = (page, sel) =>
+  page.evaluate(([sel, listing]) => {
+    const scope = document.querySelector(listing) ?? document;
+    const el = [...scope.querySelectorAll(sel)].find((x) => x.getBoundingClientRect().width > 0 && (!x.dataset.lbxHref || new URL(x.dataset.lbxHref, location.href).href !== location.href));
+    if (!el) return false;
+    el.dispatchEvent(new MouseEvent('pointerdown', { bubbles: true }));
+    el.dispatchEvent(new MouseEvent('click', { bubbles: true, cancelable: true, detail: 1 }));
+    return true;
+  }, [sel, LISTING]);
+
+const measure = async (browser, s) => {
+  const ctx = await newContext(browser);
+  const page = await ctx.newPage();
+  const cdp = await ctx.newCDPSession(page);
+  await cdp.send('Emulation.setCPUThrottlingRate', { rate: opt.cpu });
+  await cdp.send('Profiler.enable');
+  await cdp.send('Profiler.setSamplingInterval', { interval: 100 });
+  const trace = [];
+  cdp.on('Tracing.dataCollected', (d) => trace.push(...d.value));
+  const start = async () => {
+    await cdp.send('Tracing.start', { traceConfig: { includedCategories: ['toplevel'] }, transferMode: 'ReportEvents' });
+    await cdp.send('Profiler.start');
+  };
+  let note = '';
+  try {
+    if (s.load) await start();
+    const res = await page.goto(`${ORIGIN}${s.path}`, { waitUntil: 'load', timeout: 60000 });
+    if (!stub) {
+      const why = await challenged(res, page);
+      if (why) return { fallback: why };
+    }
+    await settled(page);
+    await sleep(2500);
+    if (!s.load) {
+      if (s.name === 'back' && !(await click(page, '[data-lbx-href]'))) note = 'no [data-lbx-href] to change the state before Back';
+      if (s.name === 'back') await settled(page), await sleep(1500);
+      if (s.name === 'typing') {
+        const sel = F.input || (await page.evaluate(() => window.__lbx?.config?._global?.inputSelector)) || 'input[name=q]';
+        await page.evaluate((sel) => document.querySelector(sel)?.focus(), sel);
+        await sleep(600);
+      }
+      const before = await page.evaluate(() => window.__lbx?.health?.timeline?.length ?? 0);
+      await start();
+      if (s.name === 'change' && !(await click(page, '[data-lbx-href]'))) note = 'no [data-lbx-href] in the listing';
+      if (s.name === 'more' && !(await click(page, '[data-lbx-more]'))) note = 'no [data-lbx-more] in the listing';
+      if (s.name === 'back') await page.goBack();
+      if (s.name === 'typing') await page.keyboard.type(F.query, { delay: 140 }), await sleep(2000);
+      await sleep(300);
+      await settled(page);
+      await sleep(1200);
+      // What the scenario did, from Luma's health timeline: a run that did nothing measures nothing.
+      const marks = await page.evaluate((n) => (window.__lbx?.health?.timeline ?? []).slice(n).map(([, w]) => w), before);
+      const want = s.name === 'typing' ? /^ac shown / : /^\S+ render \d+ hits$/;
+      if (!note && !marks.some((w) => want.test(w))) note = s.name === 'typing' ? 'no suggestions were shown (fixtures.input / _global.inputSelector, fixtures.query)' : 'the listing did not render';
+    }
+    const { profile } = await cdp.send('Profiler.stop');
+    const done = new Promise((r) => cdp.once('Tracing.tracingComplete', r));
+    await cdp.send('Tracing.end');
+    await done;
+    const errors = await page.evaluate(() => window.__lbx?.health?.errors ?? []).catch(() => []);
+    const tasks = mainThreadTasks(trace, sampleTimes(profile).at);
+    return { tasks: attribute(profile, tasks, { ours, name: nameOf }), note, errors };
+  } finally {
+    await ctx.close();
+  }
+};
+
+const browser = await launch();
+const results = [];
+const notes = [];
+for (const s of scenarios) {
+  const runs = [];
+  for (let i = 0; i < opt.runs; i++) {
+    process.stderr.write(`${s.name}: run ${i + 1}/${opt.runs}   `);
+    let r = await measure(browser, s);
+    if (r.fallback) {
+      const n = `The live storefront ${ORIGIN} answered with ${r.fallback}: not worked around; measured on the integration's stub page (luma.config.mjs stubPage) instead (run it with the client's knowledge, or ask them to allowlist the runner).`;
+      console.error(`\n${n}`);
+      notes.push(n);
+      stub = true;
+      r = await measure(browser, s);
+    }
+    if (r.note && !notes.includes(`${s.name}: ${r.note}`)) notes.push(`${s.name}: ${r.note}`);
+    for (const e of r.errors ?? []) if (!notes.includes(`${s.name}: health error ${e}`)) notes.push(`${s.name}: health error ${e}`);
+    runs.push(r.tasks ?? []);
+  }
+  results.push({ name: s.name, ...summarize(runs, opt.budget) });
+}
+await browser.close();
+process.stderr.write('\n');
+
+const meta = { integration: SITE_DIR, page: stub ? `${ORIGIN} (the integration's stub page)` : `${ORIGIN} (live)`, runs: String(opt.runs), build: opt.build ? 'yarn vite build --sourcemap (a temporary folder)' : 'dist/ as it is' };
+console.log(formatReport(results, { budget: opt.budget, cpu: opt.cpu, meta }));
+if (notes.length) console.log(`\nnotes:\n${notes.map((n) => `  ${n}`).join('\n')}`);
+if (opt.json) {
+  writeFileSync(resolve(opt.json), JSON.stringify({ meta, budget: opt.budget, cpu: opt.cpu, results: results.map((r) => ({ ...r, worst: r.worst && { ...r.worst, fns: Object.fromEntries(r.worst.fns) } })), notes }, null, 1));
+  console.log(`JSON: ${resolve(opt.json)}`);
+}
+process.exit(results.some((r) => r.over) ? 1 : 0);

package/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "types": ["vite/client"],
+    "strict": true,
+    "noEmit": true,
+    "skipLibCheck": true,
+    "paths": { "@/*": ["./src/*"] }
+  },
+  "include": ["src"]
+}