qa-engineer 0.9.2 → 0.11.0

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>'
+  );
+}

package/packages/engine/lib/report/core/model.mjs

@@ -0,0 +1,270 @@
+// Contract artifact → view model.
+//
+// Every renderer reads this shape, never the raw artifact. One place therefore owns
+// the questions that would otherwise be answered slightly differently in eight
+// sections: which verdict applies when `executive` is absent, what counts as a
+// "covered" dimension, what the subject line of the report is, and — the one that
+// matters most — what may be *derived* versus what must be *measured*.
+//
+// ## Derivation discipline
+//
+// A report is trusted because its numbers came from somewhere. So:
+//
+//   derived  — the overall score (a fixed function of severity counts), dimension
+//              filter counts, page/finding association, totals, the fallback verdict
+//   measured — every performance number, every score the producer supplied,
+//              artifact existence, request timings
+//
+// Nothing here invents a measurement. If a run never checked accessibility there is
+// no accessibility score, and the report says the area was not examined rather than
+// printing a plausible number. A fabricated 87 is worse than a blank, because the
+// blank prompts a question and the 87 ends one.
+
+import path from 'node:path';
+
+import { createRegistry } from '../../artifacts/manager.mjs';
+import { VERDICT, SEVERITY_ORDER } from '../theme/tokens.mjs';
+import { DIMENSION_LABEL } from '../components/findings.mjs';
+import { normalize } from './normalize.mjs';
+import { versionStamp } from '../version.mjs';
+
+/**
+ * What the report is *about*, short enough to be a heading.
+ *
+ * The contract has no title field on a 1.0 result and the summary is a paragraph —
+ * using it as an `<h1>` produced a five-line heading. The host is the honest short
+ * answer, the way Lighthouse titles a report by its URL.
+ */
+export function subjectOf(result) {
+  if (result.title) return String(result.title);
+  const url = String(result.url ?? '').trim();
+  if (url) {
+    const withoutScheme = url.includes('://') ? url.slice(url.indexOf('://') + 3) : url;
+    return withoutScheme.replace(/\/+$/, '') || url;
+  }
+  return String(result.summary ?? 'QA report').split('.')[0].slice(0, 80);
+}
+
+/**
+ * The release decision.
+ *
+ * `executive.verdict` is authoritative when the run supplied one. Otherwise the
+ * classification maps onto the same surface, so a 1.0 result still renders a verdict
+ * banner instead of an empty strip. The severity counts are the last resort and the
+ * safest one: any critical means do-not-ship, whatever the prose says.
+ */
+export function verdictOf(result) {
+  const executive = result.executive ?? {};
+  let key = executive.verdict;
+
+  if (!key) {
+    const counts = result.severityCounts ?? {};
+    if (result.classification === 'blocked') key = 'blocked';
+    else if (result.classification === 'insufficient-data') key = 'insufficient-data';
+    else if ((counts.critical ?? 0) > 0) key = 'do-not-ship';
+    else if ((counts.high ?? 0) > 0) key = 'ship-with-risks';
+    else key = result.classification === 'pass' ? 'pass' : 'issues-found';
+  }
+
+  const spec = VERDICT[key] ?? VERDICT['insufficient-data'];
+  return {
+    key,
+    label: spec.label,
+    tone: spec.tone,
+    blurb: executive.headline ?? spec.blurb,
+    headline: executive.headline ?? null,
+    health: executive.health ?? null,
+    risks: executive.risks ?? [],
+    recommendedAction: executive.recommendedAction ?? null,
+    estimatedFixHours: executive.estimatedFixHours ?? null,
+    confidence: Number.isFinite(executive.confidence) ? executive.confidence : null,
+    // True when nothing in the artifact stated a verdict and this one was inferred.
+    inferred: !executive.verdict,
+  };
+}
+
+/**
+ * An overall score from severity counts.
+ *
+ * Deliberately a fixed, published function rather than a judgement: a critical costs
+ * 35 points, a high 12, a medium 4, a low 1, floored at zero. Two runs of the same
+ * application produce the same number, and a reader can check the arithmetic. It is
+ * shown as "derived" precisely so nobody mistakes it for a measurement.
+ */
+export function deriveOverall(counts) {
+  const penalty =
+    (counts.critical ?? 0) * 35 + (counts.high ?? 0) * 12 + (counts.medium ?? 0) * 4 + (counts.low ?? 0) * 1;
+  return Math.max(0, 100 - penalty);
+}
+
+/** Dimension facets for the filter bar, counted from the findings themselves. */
+function dimensionFacets(findings) {
+  const counts = new Map();
+  for (const finding of findings) {
+    const key = finding.dimension;
+    if (!key) continue;
+    counts.set(key, (counts.get(key) ?? 0) + 1);
+  }
+  return [...counts.entries()]
+    .sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]))
+    .map(([key, count]) => ({ key, label: DIMENSION_LABEL[key] ?? key, count }));
+}
+
+/**
+ * The boundary of the run, assembled from what was declared and what is derivable.
+ *
+ * An unstated boundary reads as "everything was checked". Blocked cases and unrun
+ * dimensions are boundaries the artifact already knows about, so they are added to
+ * whatever the run declared rather than left to the producer to remember.
+ */
+function notCovered(result) {
+  const items = [...(result.scope?.notCovered ?? []).map(String)];
+  const ran = new Set(result.dimensionsRun ?? []);
+
+  if (ran.size > 0) {
+    for (const [key, label] of Object.entries(DIMENSION_LABEL)) {
+      if (ran.has(key)) continue;
+      items.push(`${label} was not examined in this run.`);
+    }
+  }
+
+  const db = result.dbValidation ?? {};
+  if (db.inScope === false && !db.summary) {
+    items.push('Data was not compared against the system of record — no access was provided.');
+  }
+
+  const blocked = (result.testCases?.cases ?? []).filter((testCase) => testCase.status === 'blocked');
+  if (blocked.length > 0) {
+    items.push(`Could not be run: ${blocked.map((c) => `${c.id} (${c.title})`).join(', ')}`);
+  }
+
+  return items;
+}
+
+/**
+ * Requests worth showing, ranked by how much trouble they represent.
+ *
+ * A raw endpoint list sorted by URL buries the 4-second call among ninety static
+ * assets. Failures first, then slow, then everything flagged with any issue.
+ */
+function rankEndpoints(endpoints) {
+  const weight = (endpoint) => {
+    if (endpoint.issue === 'failed' || Number(endpoint.status) >= 500) return 0;
+    if (Number(endpoint.status) >= 400) return 1;
+    if (endpoint.issue === 'slow') return 2;
+    if (endpoint.issue) return 3;
+    return 4;
+  };
+  return [...endpoints].sort(
+    (a, b) => weight(a) - weight(b) || (Number(b.durationMs) || 0) - (Number(a.durationMs) || 0),
+  );
+}
+
+/**
+ * Build the view model.
+ *
+ * `resultPath` locates the artifact on disk so evidence paths resolve against the
+ * right directory; `outPath` is where the document will be written, which is what
+ * every href is made relative to. They are usually the same directory and must never
+ * be assumed to be.
+ */
+export function buildModel(input, options = {}) {
+  // Whatever the producer's contract, it becomes one shape here — and it is refused by
+  // name if this renderer has never been tested against it.
+  const result = normalize(input);
+
+  const resultPath = options.resultPath ? path.resolve(options.resultPath) : null;
+  const baseDir = options.baseDir
+    ? path.resolve(options.baseDir)
+    : resultPath
+      ? path.dirname(resultPath)
+      : process.cwd();
+  const outDir = options.outPath ? path.dirname(path.resolve(options.outPath)) : baseDir;
+
+  const registry = createRegistry(result, {
+    baseDir,
+    outDir,
+    hash: options.hash !== false,
+    embed: options.embed === true,
+    embedLimit: options.embedLimit,
+    // Set by the bundler, which copies evidence into its own tree and needs every link
+    // pointed at the copy rather than at wherever the file was found.
+    hrefMap: options.hrefMap ?? null,
+  });
+
+  const findings = [...(result.findings ?? [])];
+  const counts = result.severityCounts ?? { critical: 0, high: 0, medium: 0, low: 0 };
+  const testCases = result.testCases ?? null;
+  const suppliedScores = result.scores ?? {};
+
+  const scores = { ...suppliedScores };
+  const overallDerived = !Number.isFinite(suppliedScores.overall);
+  if (overallDerived) scores.overall = deriveOverall(counts);
+
+  const network = result.network ?? null;
+  const endpoints = rankEndpoints(network?.endpoints ?? []);
+
+  return {
+    // Identity
+    title: result.title ?? null,
+    subject: subjectOf(result),
+    url: result.url ?? null,
+    summary: result.summary ?? '',
+    generatedAt: result.generatedAt ?? null,
+    environment: result.environment ?? null,
+    reportVersion: result.reportVersion ?? null,
+    browserAdapter: result.browserAdapter ?? null,
+    durationMs: Number.isFinite(result.durationMs) ? result.durationMs : null,
+    contract: result.contract ?? null,
+    skill: result.skill ?? null,
+
+    // Decision
+    classification: result.classification ?? null,
+    verdict: verdictOf(result),
+    scores,
+    overallDerived,
+
+    // Findings
+    findings,
+    severityCounts: counts,
+    totalFindings: SEVERITY_ORDER.reduce((sum, key) => sum + (counts[key] ?? 0), 0),
+    dimensions: dimensionFacets(findings),
+
+    // Coverage
+    scope: result.scope ?? null,
+    dimensionsRun: result.dimensionsRun ?? [],
+    notCovered: notCovered(result),
+    testCases,
+    pages: result.pages ?? [],
+    authentication: result.authentication ?? null,
+
+    // Analysis
+    timeline: result.timeline ?? [],
+    network: network ? { ...network, endpoints } : null,
+    performance: result.performance ?? null,
+    accessibility: result.accessibility ?? null,
+    security: result.security ?? null,
+    console: result.console ?? null,
+    dbValidation: result.dbValidation ?? null,
+
+    // Release rollup only: the per-test failure list and the two written summaries.
+    failures: result.failureSummary ?? [],
+    summaries: result.summaries ?? null,
+
+    // Guidance
+    whatWorksWell: result.whatWorksWell ?? [],
+    fixOrder: result.fixOrder ?? [],
+    recommendations: result.recommendations ?? [],
+
+    // Evidence
+    registry,
+    evidence: result.evidence ?? [],
+    artifactStats: registry.stats(),
+
+    // Provenance, for the appendix. `producer` is displayed and never branched on:
+    // the renderer must behave identically whoever made the report.
+    producer: result.producer ?? null,
+    versions: versionStamp(),
+    paths: { resultPath, baseDir, outDir },
+  };
+}