@progen-labs/spectra 0.0.0-stage → 0.1.1

package/server/explore/boot.js

@@ -0,0 +1,150 @@
+/**
+ * Self-boot: start the target project's own dev server so `spectra performance`
+ * can profile it with no --url. The server's URL is read from its stdout (every
+ * common dev server — Vite, Next, CRA, Angular, Vue CLI, SvelteKit — prints a
+ * localhost URL when ready), then polled until it actually responds.
+ */
+import { spawn } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+
+const ANSI = /\x1b\[[0-9;]*m/g;
+const URL_RE =
+  /(https?:\/\/(?:localhost|127\.0\.0\.1|0\.0\.0\.0)(?::\d+)?[^\s)'"<]*)/i;
+
+const sleep = ms => new Promise(r => setTimeout(r, ms));
+
+/** Choose a dev command from the project's package.json scripts. */
+export function pickDevCommand(root) {
+  let scripts = {};
+  try {
+    scripts = JSON.parse(
+      fs.readFileSync(path.join(root, 'package.json'), 'utf8'),
+    ).scripts || {};
+  } catch {
+    // no package.json / unreadable — fall through
+  }
+  for (const name of ['dev', 'start', 'serve', 'develop']) {
+    if (scripts[name]) return { cmd: 'npm', args: ['run', name], label: `npm run ${name}` };
+  }
+  return null;
+}
+
+function normalizeUrl(u) {
+  return u.replace('://0.0.0.0', '://localhost').replace(/\/$/, '');
+}
+
+/** Poll a URL until it responds (any HTTP status) or the deadline passes. */
+async function waitForServer(url, timeoutMs) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    try {
+      const ctrl = AbortSignal.timeout(2000);
+      const res = await fetch(url, { signal: ctrl, redirect: 'manual' });
+      if (res.status > 0) return true;
+    } catch {
+      // not up yet
+    }
+    await sleep(300);
+  }
+  return false;
+}
+
+/**
+ * Start the dev server and resolve once it is reachable.
+ *
+ * @param {object} opts
+ * @param {string} [opts.root]       project directory (default cwd)
+ * @param {string} [opts.command]    explicit command, e.g. "npm run dev"
+ * @param {number} [opts.timeoutMs]  how long to wait for the URL + readiness
+ * @param {(line:string)=>void} [opts.onLog]  receives de-ANSI'd server output
+ * @returns {Promise<{ url:string, proc:import('child_process').ChildProcess, stop:()=>Promise<void> }>}
+ */
+export async function bootDevServer({
+  root = process.cwd(),
+  command,
+  timeoutMs = 60_000,
+  onLog,
+} = {}) {
+  const chosen = command
+    ? { cmd: command.split(' ')[0], args: command.split(' ').slice(1), label: command }
+    : pickDevCommand(root);
+  if (!chosen) {
+    throw new Error(
+      'no dev script found in package.json (looked for dev/start/serve/develop). ' +
+        'Pass --url to profile an already-running server, or --command "<cmd>".',
+    );
+  }
+
+  const proc = spawn(chosen.cmd, chosen.args, {
+    cwd: root,
+    env: { ...process.env },
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
+
+  let detectedUrl = null;
+  let resolveUrl;
+  const urlPromise = new Promise(r => (resolveUrl = r));
+  const scan = buf => {
+    const text = buf.toString().replace(ANSI, '');
+    if (onLog) onLog(text);
+    if (!detectedUrl) {
+      const m = text.match(URL_RE);
+      if (m) {
+        detectedUrl = normalizeUrl(m[1]);
+        resolveUrl(detectedUrl);
+      }
+    }
+  };
+  proc.stdout.on('data', scan);
+  proc.stderr.on('data', scan);
+
+  let exited = false;
+  let exitErr = null;
+  proc.on('exit', code => {
+    exited = true;
+    if (code) exitErr = new Error(`dev server (${chosen.label}) exited early with code ${code}`);
+    resolveUrl(null);
+  });
+  proc.on('error', err => {
+    exited = true;
+    exitErr = new Error(`could not start dev server (${chosen.label}): ${err.message}`);
+    resolveUrl(null);
+  });
+
+  const stop = async () => {
+    if (exited) return;
+    try {
+      proc.kill('SIGTERM');
+    } catch {
+      /* already gone */
+    }
+    for (let i = 0; i < 10 && !exited; i++) await sleep(150);
+    if (!exited) {
+      try {
+        proc.kill('SIGKILL');
+      } catch {
+        /* ignore */
+      }
+    }
+  };
+
+  const url = await Promise.race([urlPromise, sleep(timeoutMs).then(() => null)]);
+  if (exitErr) throw exitErr;
+  if (!url) {
+    await stop();
+    throw new Error(
+      'could not detect the dev server URL from its output in time. Pass --url explicitly.',
+    );
+  }
+
+  const ok = await waitForServer(url, Math.max(5000, Math.floor(timeoutMs / 2)));
+  if (!ok) {
+    await stop();
+    throw new Error(
+      `dev server reported ${url} but it never became reachable. Pass --url explicitly.`,
+    );
+  }
+
+  return { url, proc, stop };
+}

package/server/explore/classify.js

@@ -0,0 +1,169 @@
+/**
+ * Pure classification, destructive-action detection and ranking for the
+ * actionable elements discovered on a page. Kept free of any browser/puppeteer
+ * dependency so it can be unit-tested over plain descriptor objects.
+ *
+ * A "descriptor" is the raw shape produced by the in-page extractor in
+ * discover.js:
+ *   {
+ *     tag, type, role, label, href, name, id, selector,
+ *     inForm, formMethod, formAction, disabled, visible, rect: [x,y,w,h]
+ *   }
+ */
+
+/** Words that mark an action as state-changing / risky to trigger blindly. */
+const DESTRUCTIVE_LABEL =
+  /\b(delete|remove|destroy|drop|erase|clear|reset|wipe|pay|buy|purchase|checkout|order|subscribe|donate|confirm|submit order|place order|deactivate|disable|archive|unsubscribe|sign\s?out|log\s?out|close account|cancel (?:account|subscription|plan))\b/i;
+
+const DESTRUCTIVE_HREF = /(logout|signout|sign-out|log-out|\/delete|\/remove)/i;
+
+/** Labels that usually denote primary navigation / high-value entry points. */
+const PRIMARY_LABEL =
+  /\b(home|dashboard|login|log\s?in|sign\s?in|sign\s?up|register|get started|start|search|products?|pricing|settings|profile|account|cart|checkout|menu|explore|browse)\b/i;
+
+/**
+ * Map a raw descriptor to a stable `kind` and the `actionType` the runner would
+ * use to drive it.
+ */
+export function classifyElement(d) {
+  const tag = (d.tag || '').toLowerCase();
+  const type = (d.type || '').toLowerCase();
+  const role = (d.role || '').toLowerCase();
+
+  if (tag === 'a' && d.href) {
+    const internalNav = isInternalHref(d.href);
+    return {
+      kind: internalNav ? 'nav-link' : 'link',
+      actionType: 'navigate',
+    };
+  }
+  if (tag === 'select') return { kind: 'select', actionType: 'choose' };
+  if (tag === 'textarea') return { kind: 'text-input', actionType: 'fill' };
+
+  if (tag === 'input') {
+    if (type === 'submit' || type === 'image')
+      return { kind: 'submit', actionType: 'submit' };
+    if (type === 'button' || type === 'reset')
+      return { kind: 'button', actionType: 'click' };
+    if (type === 'checkbox' || type === 'radio')
+      return { kind: 'toggle', actionType: 'choose' };
+    if (['hidden'].includes(type)) return { kind: 'unknown', actionType: null };
+    // text, email, password, search, tel, url, number, date, ...
+    return { kind: 'text-input', actionType: 'fill' };
+  }
+
+  if (tag === 'button' || role === 'button') {
+    if (type === 'submit') return { kind: 'submit', actionType: 'submit' };
+    return { kind: 'button', actionType: 'click' };
+  }
+
+  if (role === 'link') return { kind: 'link', actionType: 'navigate' };
+  if (role === 'tab' || role === 'menuitem')
+    return { kind: 'button', actionType: 'click' };
+  if (['checkbox', 'switch', 'radio'].includes(role))
+    return { kind: 'toggle', actionType: 'choose' };
+
+  return { kind: 'unknown', actionType: null };
+}
+
+/** True when an href points inside the same app rather than off to the web. */
+export function isInternalHref(href) {
+  if (!href) return false;
+  const h = String(href).trim();
+  if (h.startsWith('#')) return false; // in-page anchor, not a navigation
+  if (/^(mailto:|tel:|sms:|javascript:|data:)/i.test(h)) return false;
+  if (/^https?:\/\//i.test(h)) return false; // absolute external (best-effort)
+  return true; // relative path, "/foo", "./foo", "foo"
+}
+
+/**
+ * Decide whether triggering this element could change server/app state. Used by
+ * the safe-by-default runner to skip anything not explicitly allowlisted.
+ */
+export function isDestructive(d) {
+  const label = d.label || '';
+  if (DESTRUCTIVE_LABEL.test(label)) return true;
+  if (DESTRUCTIVE_HREF.test(d.href || '')) return true;
+  // A real form submit via POST/PUT/DELETE mutates by definition.
+  const { kind } = classifyElement(d);
+  if (kind === 'submit') {
+    const method = (d.formMethod || 'get').toLowerCase();
+    if (method && method !== 'get') return true;
+  }
+  return false;
+}
+
+/** A short, human-friendly name for a descriptor, for reports and path names. */
+export function labelOf(d) {
+  const raw = (d.label || '').replace(/\s+/g, ' ').trim();
+  if (raw) return raw.length > 60 ? raw.slice(0, 57) + '…' : raw;
+  if (d.name) return d.name;
+  if (d.href) return d.href;
+  const { kind } = classifyElement(d);
+  return kind === 'unknown' ? d.tag || 'element' : kind;
+}
+
+/**
+ * Score an element for how worthwhile it is to include in a golden path.
+ * Higher is better. Invisible, disabled, unlabeled and unknown elements sink.
+ */
+export function scoreElement(d) {
+  const { kind, actionType } = classifyElement(d);
+  if (actionType === null) return -Infinity;
+  let score = 0;
+  if (d.visible) score += 10;
+  else score -= 20;
+  if (d.disabled) score -= 15;
+  if ((d.label || '').trim()) score += 4;
+  if (PRIMARY_LABEL.test(d.label || '')) score += 6;
+
+  // Prefer entry points and clicks over raw text fields in isolation.
+  score += { 'nav-link': 5, button: 4, submit: 3, select: 2, 'text-input': 1, toggle: 1, link: 1, unknown: -10 }[kind] ?? 0;
+
+  // A stable id/data-test selector is more reliable to drive.
+  if (/#|\[data-test/.test(d.selector || '')) score += 3;
+
+  // Larger, on-screen targets are usually more meaningful than tiny icons.
+  const area = d.rect ? d.rect[2] * d.rect[3] : 0;
+  if (area > 0 && area < 8) score -= 4;
+
+  return score;
+}
+
+/**
+ * Turn a raw descriptor list into ranked, classified, de-duplicated candidates.
+ * Returns objects enriched with { kind, actionType, destructive, score, name }.
+ */
+export function rankElements(descriptors, { limit = 50 } = {}) {
+  const seen = new Set();
+  const out = [];
+  for (const d of descriptors || []) {
+    const cls = classifyElement(d);
+    if (cls.actionType === null) continue;
+    const key = d.selector || `${d.tag}:${d.label}:${d.href || ''}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    out.push({
+      ...d,
+      kind: cls.kind,
+      actionType: cls.actionType,
+      destructive: isDestructive(d),
+      name: labelOf(d),
+      score: scoreElement(d),
+    });
+  }
+  out.sort((a, b) => b.score - a.score);
+  return out.slice(0, limit);
+}
+
+/** Split ranked candidates into the ones a safe run may drive, and the rest. */
+export function partitionSafe(ranked, { allow = [] } = {}) {
+  const allowSet = new Set(allow);
+  const safe = [];
+  const skipped = [];
+  for (const el of ranked) {
+    if (el.destructive && !allowSet.has(el.selector)) skipped.push(el);
+    else safe.push(el);
+  }
+  return { safe, skipped };
+}

package/server/explore/discover.js

@@ -0,0 +1,162 @@
+/**
+ * Discovery: given a live puppeteer Page, enumerate the actionable elements on
+ * the current view and return a ranked, classified inventory.
+ *
+ * The live-DOM extraction (browser-side) is deliberately separated from the
+ * classification/ranking (pure Node, see classify.js) so the latter can be
+ * unit-tested without a browser.
+ */
+import { rankElements, partitionSafe } from './classify.js';
+
+/**
+ * Runs in the page context. Returns an array of raw element descriptors. Must
+ * be self-contained — it is serialized and evaluated inside Chrome.
+ */
+function extractActionables() {
+  const SELECTOR = [
+    'a[href]',
+    'button',
+    'input',
+    'select',
+    'textarea',
+    '[role="button"]',
+    '[role="link"]',
+    '[role="tab"]',
+    '[role="menuitem"]',
+    '[role="checkbox"]',
+    '[role="switch"]',
+    '[role="radio"]',
+    '[onclick]',
+  ].join(',');
+
+  function nthOfType(n) {
+    // 1-based index among same-tag element siblings, for :nth-of-type().
+    let i = 1;
+    for (let p = n.previousElementSibling; p; p = p.previousElementSibling) {
+      if (p.tagName === n.tagName) i++;
+    }
+    return i;
+  }
+
+  function selectorOf(el) {
+    if (!el || el.nodeType !== 1) return '';
+    const parts = [];
+    for (let n = el, i = 0; n && n.nodeType === 1 && i < 5; n = n.parentElement, i++) {
+      let s = n.tagName.toLowerCase();
+      if (n.id) {
+        parts.unshift(s + '#' + CSS.escape(n.id));
+        break; // an id is unique on its own — stop climbing
+      }
+      const testId =
+        n.getAttribute && (n.getAttribute('data-test') || n.getAttribute('data-testid'));
+      if (testId) {
+        s += '[data-test' + (n.getAttribute('data-testid') ? 'id' : '') + '="' + testId + '"]';
+      } else {
+        if (n.classList && n.classList.length) {
+          s += '.' + Array.prototype.slice.call(n.classList, 0, 2).map(c => CSS.escape(c)).join('.');
+        }
+        // Disambiguate from same-tag siblings so sibling links/buttons don't
+        // collapse to one selector (and so the selector actually resolves to a
+        // single element for the runner).
+        if (n.parentElement) s += ':nth-of-type(' + nthOfType(n) + ')';
+      }
+      parts.unshift(s);
+    }
+    return parts.join(' > ');
+  }
+
+  function accessibleName(el) {
+    const aria = el.getAttribute('aria-label');
+    if (aria && aria.trim()) return aria.trim();
+    const labelledby = el.getAttribute('aria-labelledby');
+    if (labelledby) {
+      const text = labelledby
+        .split(/\s+/)
+        .map(id => {
+          const n = document.getElementById(id);
+          return n ? n.textContent : '';
+        })
+        .join(' ')
+        .trim();
+      if (text) return text;
+    }
+    const tag = el.tagName.toLowerCase();
+    if (tag === 'input' || tag === 'textarea' || tag === 'select') {
+      if (el.id) {
+        const lab = document.querySelector('label[for="' + CSS.escape(el.id) + '"]');
+        if (lab && lab.textContent.trim()) return lab.textContent.trim();
+      }
+      const wrap = el.closest('label');
+      if (wrap && wrap.textContent.trim()) return wrap.textContent.trim();
+      if (el.placeholder) return el.placeholder;
+      if (el.getAttribute('name')) return el.getAttribute('name');
+      if (el.value && el.type === 'submit') return el.value;
+    }
+    const text = (el.textContent || '').replace(/\s+/g, ' ').trim();
+    if (text) return text;
+    return el.getAttribute('title') || el.getAttribute('alt') || '';
+  }
+
+  function isVisible(el) {
+    const style = window.getComputedStyle(el);
+    if (style.display === 'none' || style.visibility === 'hidden' || Number(style.opacity) === 0)
+      return false;
+    const r = el.getBoundingClientRect();
+    return r.width > 0 && r.height > 0;
+  }
+
+  const forms = Array.from(document.querySelectorAll('form'));
+  const nodes = Array.from(document.querySelectorAll(SELECTOR));
+  const out = [];
+  for (const el of nodes) {
+    const tag = el.tagName.toLowerCase();
+    const form = el.closest ? el.closest('form') : null;
+    const r = el.getBoundingClientRect();
+    out.push({
+      tag,
+      type: el.getAttribute('type') || '',
+      role: el.getAttribute('role') || '',
+      label: accessibleName(el),
+      href: tag === 'a' ? el.getAttribute('href') || '' : '',
+      name: el.getAttribute('name') || '',
+      id: el.id || '',
+      selector: selectorOf(el),
+      inForm: !!form,
+      formIndex: form ? forms.indexOf(form) : -1,
+      formMethod: form ? (form.getAttribute('method') || 'get') : '',
+      formAction: form ? form.getAttribute('action') || '' : '',
+      disabled: !!el.disabled,
+      visible: isVisible(el),
+      rect: [Math.round(r.x), Math.round(r.y), Math.round(r.width), Math.round(r.height)],
+    });
+  }
+  return out;
+}
+
+/**
+ * Discover actionable elements on the page's current view.
+ *
+ * @param {import('puppeteer-core').Page} page
+ * @param {{ limit?: number, allow?: string[] }} [opts]
+ *   limit — max ranked elements to keep; allow — selectors of destructive
+ *   actions the caller has explicitly permitted the runner to trigger.
+ */
+export async function discoverActionables(page, opts = {}) {
+  const raw = await page.evaluate(extractActionables);
+  const ranked = rankElements(raw, { limit: opts.limit ?? 50 });
+  const { safe, skipped } = partitionSafe(ranked, { allow: opts.allow ?? [] });
+  const meta = await page.evaluate(() => ({
+    url: location.href,
+    title: document.title,
+  }));
+  return {
+    url: meta.url,
+    title: meta.title,
+    total: raw.length,
+    ranked,
+    safe,
+    skipped,
+  };
+}
+
+export { extractActionables };

package/server/explore/evaluate-cli.js

@@ -0,0 +1,101 @@
+/**
+ * CLI wrapper for the evaluation orchestrator — the default action of
+ * `spectra performance`. Runs the golden-path suite against --url, prints the
+ * performance matrix, and saves an aggregate report alongside the per-path
+ * reports (all openable in the dashboard).
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { runEvaluation } from './evaluate.js';
+import { REPORTS_DIR, TARGET_NAME } from '../config.js';
+
+const args = process.argv.slice(2);
+const opt = (name, fallback) => {
+  const i = args.indexOf(`--${name}`);
+  return i === -1 ? fallback : args[i + 1] ?? true;
+};
+const flag = name => args.includes(`--${name}`);
+
+const url = opt('url');
+if (!url) {
+  console.error('spectra: evaluate requires --url');
+  process.exit(1);
+}
+
+const pad = (s, n) => String(s ?? '').padEnd(n).slice(0, n);
+const padL = (s, n) => String(s ?? '').padStart(n);
+const ms = v => (v == null ? '—' : `${v}ms`);
+
+function printMatrix(result) {
+  const rows = [result.baseline, ...result.paths];
+  console.log(`\n${'═'.repeat(78)}`);
+  console.log(`Spectra performance evaluation — ${result.target}`);
+  console.log(`${result.url}`);
+  console.log(
+    `${result.discovered} actionable elements · ${result.paths.length} golden paths · ` +
+      `${result.skippedDestructive.length} destructive skipped (safe mode)`,
+  );
+  console.log('═'.repeat(78));
+  console.log(
+    `${pad('#', 3)}${pad('Golden path', 34)}${pad('Result', 8)}${padL('TBT', 7)}${padL('LCP', 8)}${padL('LongT', 7)}  Top finding`,
+  );
+  console.log('─'.repeat(78));
+  rows.forEach((r, i) => {
+    const num = i === 0 ? '·' : String(i);
+    const status = r.ok ? 'PASS' : 'FAIL';
+    const s = r.summary || {};
+    const top = s.topFinding ? `[${s.topFinding.severity}] ${s.topFinding.title}` : '—';
+    console.log(
+      `${pad(num, 3)}${pad(r.title, 34)}${pad(status, 8)}${padL(ms(s.tbtMs), 7)}${padL(ms(s.lcpMs), 8)}${padL(s.longTaskCount ?? '—', 7)}  ${top.slice(0, 40)}`,
+    );
+    if (!r.ok && r.error) console.log(`      ↳ ${r.error}`);
+  });
+  console.log('─'.repeat(78));
+  const passed = result.paths.filter(p => p.ok).length;
+  console.log(`Automation: ${passed}/${result.paths.length} golden paths passed.`);
+  if (result.skippedDestructive.length) {
+    console.log(
+      `Skipped (safe mode): ${result.skippedDestructive.map(s => s.name).join(', ')}`,
+    );
+  }
+}
+
+function stamp() {
+  const d = new Date();
+  const p = n => String(n).padStart(2, '0');
+  return `${d.getFullYear()}${p(d.getMonth() + 1)}${p(d.getDate())}T${p(d.getHours())}${p(d.getMinutes())}${p(d.getSeconds())}`;
+}
+
+const result = await runEvaluation({
+  url,
+  headless: !flag('headed'),
+  limit: Number(opt('paths', 12)),
+  signIn: opt('sign-in'),
+  onProgress: ev => {
+    if (ev.phase === 'baseline') console.error('spectra: recording baseline page load …');
+    else if (ev.phase === 'discover') console.error('spectra: discovering actionable elements …');
+    else if (ev.phase === 'synthesized')
+      console.error(
+        `spectra: ${ev.discovered} actionable elements (${ev.skipped} destructive skipped) → ${ev.paths} golden paths`,
+      );
+    else if (ev.phase === 'path')
+      console.error(`spectra: [${ev.index}/${ev.total}] ${ev.title}`);
+  },
+});
+
+printMatrix(result);
+
+const id = `evaluation-${stamp()}`;
+fs.mkdirSync(REPORTS_DIR, { recursive: true });
+const file = path.join(REPORTS_DIR, `${id}.json`);
+fs.writeFileSync(
+  file,
+  JSON.stringify({ id, kind: 'evaluation', createdAt: Date.now(), target: TARGET_NAME, ...result }, null, 2),
+);
+
+const installed = !!process.env.PERF_REPORTS_DIR;
+console.log(`\nSaved ${file}`);
+console.log(
+  `Per-path reports are in ${REPORTS_DIR} — view them with: ${installed ? 'spectra dashboard' : 'npm run dev'}`,
+);
+process.exit(0);