qa-engineer 0.10.0 → 0.11.0

package/packages/engine/lib/report/components/primitives.mjs

@@ -0,0 +1,246 @@
+// The small pieces every section is built from: escaping, formatting, badges, icons.
+//
+// Escaping lives here and is used everywhere, because a report renders text the run
+// did not author — page titles, console messages, response bodies, DOM excerpts. That
+// content is untrusted the same way a log line is untrusted, and a `<script>` in a
+// console error must reach the reader as characters, never as markup.
+
+import { SEVERITY, STATUS, VITALS, vitalBand, scoreBand } from '../theme/tokens.mjs';
+import { formatBytes } from '../../artifacts/mime.mjs';
+
+/** HTML-escape text for element content and quoted attribute values alike. */
+export function e(value) {
+  if (value === null || value === undefined) return '';
+  return String(value)
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#x27;');
+}
+
+/**
+ * Escape for a JSON literal embedded in a `<script>` block.
+ *
+ * `JSON.stringify` alone is not enough: the string `</script>` inside any value ends
+ * the block early and drops the rest of the page into the document as markup. The
+ * `<` and `
`/`
` escapes close that off.
+ */
+export function jsonScript(value) {
+  return JSON.stringify(value)
+    .replace(/</g, '\\u003c')
+    .replace(/\u2028/g, '\\u2028')
+    .replace(/\u2029/g, '\\u2029');
+}
+
+/** Join class names, dropping the falsy ones. */
+export function cx(...names) {
+  return names.filter(Boolean).join(' ');
+}
+
+/** An id safe to use as an anchor, derived from a finding or section key. */
+export function slug(value, prefix = '') {
+  const safe = [...String(value ?? '')]
+    .map((ch) => (/[\p{L}\p{N}]/u.test(ch) || ch === '-' || ch === '_' ? ch : '-'))
+    .join('')
+    .replace(/-+/g, '-')
+    .replace(/^-|-$/g, '');
+  return safe ? `${prefix}${safe}` : '';
+}
+
+/** Sort TC-2 before TC-10, the way a reader expects a case list to run. */
+export function compareNatural(a, b) {
+  const key = (v) =>
+    String(v ?? '')
+      .split(/(\d+)/)
+      .map((part) => (/^\d+$/.test(part) ? Number.parseInt(part, 10) : part.toLowerCase()));
+  const left = key(a);
+  const right = key(b);
+  for (let i = 0; i < Math.max(left.length, right.length); i += 1) {
+    const x = left[i];
+    const y = right[i];
+    if (x === undefined) return -1;
+    if (y === undefined) return 1;
+    if (x === y) continue;
+    return x < y ? -1 : 1;
+  }
+  return 0;
+}
+
+/** A severity badge. */
+export function severityBadge(severity) {
+  const key = SEVERITY[severity] ? severity : 'low';
+  return `<span class="badge sev-${key}">${e(SEVERITY[key].label)}</span>`;
+}
+
+/** A status pill — pass, fail, blocked, skipped, or a free-form label. */
+export function statusPill(status, label = null) {
+  const map = {
+    pass: 'passed', passed: 'passed', ok: 'passed', confirmed: 'failed',
+    fail: 'failed', failed: 'failed', issues: 'failed',
+    blocked: 'blocked', warn: 'blocked', warned: 'blocked',
+    skipped: 'skipped', 'not-checked': 'skipped',
+  };
+  const key = map[status] ?? 'neutral';
+  const text = label ?? STATUS[key]?.label ?? status;
+  return `<span class="pill st-${key}">${e(text)}</span>`;
+}
+
+/** A neutral chip for dimensions, tags, owners. */
+export function chip(text, title = null) {
+  if (!text) return '';
+  const attr = title ? ` title="${e(title)}"` : '';
+  return `<span class="chip"${attr}>${e(text)}</span>`;
+}
+
+/**
+ * A KPI tile.
+ *
+ * `variant` picks the accent: `sev-<key>` colours it by severity, `st-<key>` by test
+ * status. A zero gets muted deliberately — a wall of tiles where "0 critical" shouts
+ * as loudly as "3 critical" trains the reader to skip all of them.
+ */
+export function kpi({ value, label, sub = null, variant = null, zeroMuted = true }) {
+  const numeric = Number(value);
+  const isZero = zeroMuted && Number.isFinite(numeric) && numeric === 0;
+  const kind = variant?.startsWith('sev-') ? 'sev' : variant?.startsWith('st-') ? 'st' : '';
+  return (
+    `<div class="${cx('kpi', kind, variant, isZero && 'kpi-zero')}">` +
+    `<span class="kpi-n">${e(value)}</span>` +
+    `<span class="kpi-l">${e(label)}</span>` +
+    (sub ? `<span class="kpi-sub">${e(sub)}</span>` : '') +
+    '</div>'
+  );
+}
+
+/** A ring gauge for a 0–100 score, drawn as SVG so it survives print and PDF. */
+export function scoreGauge(score, label) {
+  const value = Math.max(0, Math.min(100, Math.round(Number(score))));
+  const band = scoreBand(value);
+  const radius = 20;
+  const circumference = 2 * Math.PI * radius;
+  const filled = (value / 100) * circumference;
+  return (
+    `<div class="score tone-${band}">` +
+    `<svg width="48" height="48" viewBox="0 0 48 48" role="img" ` +
+    `aria-label="${e(label)} score ${value} out of 100">` +
+    `<circle cx="24" cy="24" r="${radius}" fill="none" stroke="var(--border)" stroke-width="4"/>` +
+    `<circle cx="24" cy="24" r="${radius}" fill="none" stroke="var(--tone)" stroke-width="4" ` +
+    `stroke-linecap="round" stroke-dasharray="${filled.toFixed(2)} ${circumference.toFixed(2)}" ` +
+    'transform="rotate(-90 24 24)"/>' +
+    `<text x="24" y="24" text-anchor="middle" dominant-baseline="central" ` +
+    `font-size="14" font-weight="700" fill="var(--tone)">${value}</text>` +
+    '</svg>' +
+    `<div><div class="score-l">${e(label)}</div>` +
+    `<div class="score-b">${band === 'good' ? 'Good' : band === 'warn' ? 'Needs work' : 'Poor'}</div></div>` +
+    '</div>'
+  );
+}
+
+/** A duration in the largest unit that stays readable. */
+export function formatDuration(ms) {
+  const value = Number(ms);
+  if (!Number.isFinite(value) || value < 0) return '';
+  if (value < 1000) return `${Math.round(value)} ms`;
+  if (value < 60_000) return `${(value / 1000).toFixed(value < 10_000 ? 2 : 1)} s`;
+  const minutes = Math.floor(value / 60_000);
+  const seconds = Math.round((value % 60_000) / 1000);
+  return seconds ? `${minutes} m ${seconds} s` : `${minutes} m`;
+}
+
+/** A count with its noun, pluralised. */
+export function plural(count, singular, pluralForm = null) {
+  const n = Number(count) || 0;
+  return `${n} ${n === 1 ? singular : pluralForm ?? `${singular}s`}`;
+}
+
+export { formatBytes };
+
+/** Render one Core Web Vital as a tile whose colour states whether it is acceptable. */
+export function vitalTile(key, value) {
+  const spec = VITALS[key];
+  if (!spec || value === null || value === undefined) return '';
+  const band = vitalBand(key, value);
+  const shown =
+    spec.unit === 'bytes'
+      ? formatBytes(value)
+      : spec.unit === 'ms'
+        ? formatDuration(value)
+        : String(Number(value).toFixed(key === 'cls' ? 3 : 0));
+  return (
+    `<div class="kpi tone-${band}" style="--kpi-accent:var(--tone)" title="${e(spec.full)} — ${e(spec.plain)}">` +
+    `<span class="kpi-n" style="color:var(--tone)">${e(shown)}</span>` +
+    `<span class="kpi-l">${e(spec.label)}</span>` +
+    `<span class="kpi-sub">${e(spec.plain)}</span>` +
+    '</div>'
+  );
+}
+
+/**
+ * Inline SVG icons.
+ *
+ * Inline because the report has no second file to fetch, and an icon font would be a
+ * remote asset. Every one is 16×16 on a 24-unit grid, stroked with `currentColor` so
+ * it inherits the surrounding text colour in both themes.
+ */
+const ICON_PATHS = {
+  search: '<circle cx="11" cy="11" r="7"/><path d="m20 20-3.5-3.5"/>',
+  chevron: '<path d="m9 6 6 6-6 6"/>',
+  sun: '<circle cx="12" cy="12" r="4"/><path d="M12 2v2m0 16v2M2 12h2m16 0h2M4.9 4.9l1.4 1.4m11.4 11.4 1.4 1.4M19.1 4.9l-1.4 1.4M6.3 17.7l-1.4 1.4"/>',
+  moon: '<path d="M20 14.5A8.5 8.5 0 0 1 9.5 4a8.5 8.5 0 1 0 10.5 10.5Z"/>',
+  expand: '<path d="M4 9V4h5M20 15v5h-5M15 4h5v5M9 20H4v-5"/>',
+  print: '<path d="M6 9V3h12v6M6 18H4v-6h16v6h-2M8 14h8v7H8z"/>',
+  warning: '<path d="M12 3 2 20h20L12 3Z"/><path d="M12 9v5m0 3v.5"/>',
+  file: '<path d="M14 3H7a2 2 0 0 0-2 2v14a2 2 0 0 0 2 2h10a2 2 0 0 0 2-2V8Z"/><path d="M14 3v5h5"/>',
+  close: '<path d="M6 6 18 18M18 6 6 18"/>',
+  zoom: '<circle cx="11" cy="11" r="7"/><path d="m20 20-3.5-3.5M11 8v6M8 11h6"/>',
+};
+
+export function icon(name, size = 16) {
+  const body = ICON_PATHS[name];
+  if (!body) return '';
+  return (
+    `<svg width="${size}" height="${size}" viewBox="0 0 24 24" fill="none" ` +
+    'stroke="currentColor" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round" ' +
+    `aria-hidden="true" focusable="false">${body}</svg>`
+  );
+}
+
+/** A `<section>` with a heading, an anchor, and an optional count badge. */
+export function section({ id, title, count = null, note = null, body }) {
+  if (!body) return '';
+  const badge = count === null ? '' : `<span class="count">${e(count)}</span>`;
+  return (
+    `<section class="section" id="${e(id)}" aria-labelledby="${e(id)}-h">` +
+    `<h2 id="${e(id)}-h">${e(title)}${badge}</h2>` +
+    (note ? `<p class="section-note">${e(note)}</p>` : '') +
+    body +
+    '</section>'
+  );
+}
+
+/** A table wrapped so wide content scrolls inside its own box, never the page. */
+export function table(headers, rows, { className = '' } = {}) {
+  if (rows.length === 0) return '';
+  const head = headers
+    .map((header) => {
+      const label = typeof header === 'string' ? header : header.label;
+      const numeric = typeof header === 'object' && header.numeric;
+      return `<th${numeric ? ' class="num"' : ''}>${e(label)}</th>`;
+    })
+    .join('');
+  return (
+    `<div class="table-wrap ${e(className)}"><table><thead><tr>${head}</tr></thead>` +
+    `<tbody>${rows.join('')}</tbody></table></div>`
+  );
+}
+
+/** A proportional bar for a table cell — payload size, duration, request share. */
+export function barCell(value, max, { colour = null, label = null } = {}) {
+  const ratio = max > 0 ? Math.max(0, Math.min(1, Number(value) / max)) : 0;
+  const style = colour ? ` style="--bar:${colour}"` : '';
+  return (
+    `<td class="bar-cell">${label === null ? '' : `<div class="tabular" style="margin-bottom:.25rem">${e(label)}</div>`}` +
+    `<div class="bar"${style}><span style="width:${(ratio * 100).toFixed(1)}%"></span></div></td>`
+  );
+}

package/packages/engine/lib/report/components/runtime.mjs

@@ -0,0 +1,246 @@
+// The report's client-side behaviour, emitted as one inline <script>.
+//
+// ## Rules this script lives by
+//
+// 1. **The report works without it.** Findings are real `<details>`, navigation is
+//    real anchors, every image is a real `<img>`. This adds search, filtering, the
+//    lightbox, and the theme toggle — it is not what makes the document readable.
+// 2. **It never throws.** A report that logs an error to the console is a report the
+//    reader stops trusting, and one uncaught exception stops every later listener from
+//    binding. Every entry point is guarded and every optional element is null-checked.
+// 3. **No storage assumptions.** A report opened from `file://` may have `localStorage`
+//    blocked outright, so persistence is best-effort and its absence changes nothing.
+//
+// It is written as plain ES5-compatible ES2017 — no modules, no optional chaining in
+// the emitted source — because a report gets opened in whatever browser the recipient
+// has, including the embedded one in a mail client.
+
+/** The inline script, as source text. */
+export function runtimeScript() {
+  return `
+(function () {
+  'use strict';
+
+  function $(id) { return document.getElementById(id); }
+  function all(selector, root) { return Array.prototype.slice.call((root || document).querySelectorAll(selector)); }
+
+  /* ── Theme ──────────────────────────────────────────────────────────────
+    The OS preference is the default; an explicit choice overrides it and is
+    remembered when storage allows. */
+  var THEME_KEY = 'qa-report-theme';
+  function storedTheme() {
+    try { return window.localStorage.getItem(THEME_KEY); } catch (err) { return null; }
+  }
+  function storeTheme(value) {
+    try { window.localStorage.setItem(THEME_KEY, value); } catch (err) { /* private mode, file:// */ }
+  }
+  function systemTheme() {
+    return window.matchMedia && window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light';
+  }
+  function applyTheme(value) {
+    document.documentElement.setAttribute('data-theme', value);
+    var button = $('toggle-theme');
+    if (button) {
+      button.setAttribute('aria-label', value === 'dark' ? 'Switch to light theme' : 'Switch to dark theme');
+      button.setAttribute('title', value === 'dark' ? 'Switch to light theme' : 'Switch to dark theme');
+    }
+  }
+  var initial = storedTheme();
+  if (initial === 'dark' || initial === 'light') applyTheme(initial);
+  var themeButton = $('toggle-theme');
+  if (themeButton) {
+    themeButton.addEventListener('click', function () {
+      var current = document.documentElement.getAttribute('data-theme') || systemTheme();
+      var next = current === 'dark' ? 'light' : 'dark';
+      applyTheme(next);
+      storeTheme(next);
+    });
+  }
+
+  var printButton = $('print-report');
+  if (printButton) printButton.addEventListener('click', function () { window.print(); });
+
+  /* ── Search and filtering ───────────────────────────────────────────────
+    The DOM is the index: every finding carries its searchable text and its facets
+    as data attributes, so there is no second copy to fall out of step. */
+  var findings = all('.finding');
+  var searchBox = $('finding-search');
+  var matchCount = $('match-count');
+  var noResults = $('no-results');
+  var filterButtons = all('.filter');
+  var query = '';
+
+  function activeValues(kind) {
+    var pressed = [];
+    var any = false;
+    filterButtons.forEach(function (button) {
+      if (button.getAttribute('data-filter') !== kind) return;
+      any = true;
+      if (button.getAttribute('aria-pressed') === 'true') pressed.push(button.getAttribute('data-value'));
+    });
+    return any ? pressed : null;
+  }
+
+  function apply() {
+    var severities = activeValues('severity');
+    var dimensions = activeValues('dimension');
+    var shown = 0;
+
+    findings.forEach(function (finding) {
+      var text = finding.getAttribute('data-search') || '';
+      var matchesQuery = !query || text.indexOf(query) !== -1;
+      var matchesSeverity = !severities || severities.indexOf(finding.getAttribute('data-severity')) !== -1;
+      var matchesDimension = !dimensions || dimensions.indexOf(finding.getAttribute('data-dimension')) !== -1;
+      var visible = matchesQuery && matchesSeverity && matchesDimension;
+      finding.hidden = !visible;
+      if (visible) shown++;
+      /* A search that matches text inside a collapsed card should show that text. */
+      if (visible && query && !finding.open) finding.open = true;
+    });
+
+    if (matchCount) {
+      matchCount.textContent = shown === findings.length
+        ? ''
+        : shown + ' of ' + findings.length + ' shown';
+    }
+    if (noResults) noResults.className = shown === 0 && findings.length > 0 ? 'no-results on' : 'no-results';
+  }
+
+  if (searchBox) {
+    var debounce = null;
+    searchBox.addEventListener('input', function () {
+      window.clearTimeout(debounce);
+      debounce = window.setTimeout(function () {
+        query = searchBox.value.trim().toLowerCase();
+        apply();
+      }, 120);
+    });
+    /* Escape clears, which is what every search box a reader has ever used does. */
+    searchBox.addEventListener('keydown', function (event) {
+      if (event.key === 'Escape') { searchBox.value = ''; query = ''; apply(); }
+    });
+  }
+
+  filterButtons.forEach(function (button) {
+    button.addEventListener('click', function () {
+      var pressed = button.getAttribute('aria-pressed') === 'true';
+      button.setAttribute('aria-pressed', pressed ? 'false' : 'true');
+      apply();
+    });
+  });
+
+  var toggleAll = $('toggle-all');
+  if (toggleAll && findings.length) {
+    toggleAll.addEventListener('click', function () {
+      var anyClosed = findings.some(function (finding) { return !finding.open && !finding.hidden; });
+      findings.forEach(function (finding) { if (!finding.hidden) finding.open = anyClosed; });
+    });
+  }
+
+  /* ── Lightbox ───────────────────────────────────────────────────────────
+    Screenshots are the evidence most often examined closely, and a report that
+    makes the reader open a file manager to see one at full size is not evidence
+    they will check. */
+  var box = $('lightbox');
+  var boxImage = $('lightbox-img');
+  var boxName = $('lightbox-name');
+  var boxOpen = $('lightbox-open');
+  var boxZoom = $('lightbox-zoom');
+  var lastFocus = null;
+
+  function closeBox() {
+    if (!box) return;
+    box.classList.remove('on', 'zoomed');
+    box.hidden = true;
+    if (boxImage) boxImage.removeAttribute('src');
+    if (lastFocus && lastFocus.focus) lastFocus.focus();
+  }
+
+  function openBox(image) {
+    if (!box || !boxImage) return;
+    lastFocus = image;
+    boxImage.src = image.getAttribute('data-full') || image.src;
+    boxImage.alt = image.alt || '';
+    if (boxName) boxName.textContent = image.getAttribute('data-name') || image.alt || '';
+    if (boxOpen) boxOpen.href = image.getAttribute('data-full') || image.src;
+    box.hidden = false;
+    box.classList.add('on');
+    box.classList.remove('zoomed');
+    var close = $('lightbox-close');
+    if (close && close.focus) close.focus();
+  }
+
+  all('img.js-zoom').forEach(function (image) {
+    image.addEventListener('click', function () { openBox(image); });
+    /* Keyboard parity: an image that only opens on click is evidence a keyboard user
+      cannot examine. */
+    image.setAttribute('tabindex', '0');
+    image.setAttribute('role', 'button');
+    image.addEventListener('keydown', function (event) {
+      if (event.key === 'Enter' || event.key === ' ') { event.preventDefault(); openBox(image); }
+    });
+  });
+
+  if (box) {
+    box.addEventListener('click', function (event) {
+      if (event.target === box || event.target === boxImage) {
+        if (event.target === boxImage && !box.classList.contains('zoomed')) return closeBox();
+        closeBox();
+      }
+    });
+    var closeButton = $('lightbox-close');
+    if (closeButton) closeButton.addEventListener('click', closeBox);
+    if (boxZoom) {
+      boxZoom.addEventListener('click', function (event) {
+        event.stopPropagation();
+        box.classList.toggle('zoomed');
+        boxZoom.textContent = box.classList.contains('zoomed') ? 'Fit' : 'Zoom';
+      });
+    }
+    document.addEventListener('keydown', function (event) {
+      if (event.key === 'Escape' && !box.hidden) closeBox();
+    });
+  }
+
+  /* ── Scroll spy ─────────────────────────────────────────────────────────
+    Which section the reader is in, reflected in the sidebar. IntersectionObserver
+    rather than a scroll listener: no layout thrash, and it degrades to "no active
+    highlight" on a browser that lacks it rather than to a broken page. */
+  var links = all('nav.toc a');
+  if (links.length && 'IntersectionObserver' in window) {
+    var byId = {};
+    links.forEach(function (link) { byId[link.getAttribute('data-target')] = link; });
+    var visible = {};
+    var spy = new IntersectionObserver(function (entries) {
+      entries.forEach(function (entry) { visible[entry.target.id] = entry.isIntersecting; });
+      var current = null;
+      all('section.section').forEach(function (section) {
+        if (!current && visible[section.id]) current = section.id;
+      });
+      links.forEach(function (link) {
+        link.classList.toggle('active', link.getAttribute('data-target') === current);
+      });
+    }, { rootMargin: '-72px 0px -60% 0px', threshold: 0 });
+    all('section.section').forEach(function (section) { spy.observe(section); });
+  }
+
+  /* ── Entrance ───────────────────────────────────────────────────────────
+    Staggered only on first paint, capped so a long report does not spend two
+    seconds animating content the reader is already scrolling past. */
+  if (window.matchMedia && !window.matchMedia('(prefers-reduced-motion: reduce)').matches) {
+    all('.reveal').forEach(function (element, index) {
+      element.style.animationDelay = Math.min(index * 40, 320) + 'ms';
+    });
+  }
+
+  /* A deep link to a finding must land on it open, not on a collapsed row. */
+  function openHashTarget() {
+    if (!window.location.hash) return;
+    var target = document.getElementById(window.location.hash.slice(1));
+    if (target && target.tagName === 'DETAILS') target.open = true;
+  }
+  openHashTarget();
+  window.addEventListener('hashchange', openHashTarget);
+})();
+`.trim();
+}

package/packages/engine/lib/report/components/timeline.mjs

@@ -0,0 +1,65 @@
+// The execution timeline: what the run did, in order, and how long each phase took.
+//
+// This answers a question every reader of an automated QA report eventually asks —
+// "what did this thing actually do?" — and it answers a sharper one for whoever has
+// to trust the result: a run that spent four seconds on "security" did not check
+// security, and the timeline is where that becomes visible instead of inferable.
+
+import { e, formatDuration, icon } from './primitives.mjs';
+
+const PHASE_LABEL = Object.freeze({
+  launch: 'Browser launched',
+  authentication: 'Authentication',
+  navigation: 'Navigation',
+  functional: 'Functional testing',
+  api: 'API analysis',
+  performance: 'Performance measurement',
+  security: 'Security checks',
+  accessibility: 'Accessibility checks',
+  ui: 'UI and layout',
+  data: 'Data validation',
+  analysis: 'Analysis',
+  reporting: 'Report generation',
+});
+
+export function phaseLabel(phase) {
+  return PHASE_LABEL[phase] ?? phase ?? '';
+}
+
+/** The timeline as an ordered list, with a rail and a state dot per phase. */
+export function timelineList(entries) {
+  if (!entries || entries.length === 0) return '';
+  const total = entries.reduce((sum, entry) => sum + (Number(entry.durationMs) || 0), 0);
+
+  const items = entries
+    .map((entry) => {
+      const status = entry.status ?? 'ok';
+      const duration = Number(entry.durationMs);
+      const share =
+        total > 0 && Number.isFinite(duration)
+          ? ` · ${Math.round((duration / total) * 100)}% of the run`
+          : '';
+      return (
+        `<li class="tl-${e(status)}">` +
+        '<div class="tl-head">' +
+        `<span class="tl-label">${e(entry.label || phaseLabel(entry.phase))}</span>` +
+        (Number.isFinite(duration)
+          ? `<span class="tl-dur">${e(formatDuration(duration))}${e(share)}</span>`
+          : '') +
+        '</div>' +
+        (entry.detail ? `<div class="tl-detail">${e(entry.detail)}</div>` : '') +
+        '</li>'
+      );
+    })
+    .join('');
+
+  return (
+    '<div class="card"><div class="card-body">' +
+    `<ol class="timeline">${items}</ol>` +
+    (total > 0
+      ? `<p class="muted" style="margin-top:1rem;font-size:.8125rem">${icon('file', 14)} ` +
+        `Total measured time ${e(formatDuration(total))}.</p>`
+      : '') +
+    '</div></div>'
+  );
+}