qa-engineer 0.10.0 → 0.11.0

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

@@ -0,0 +1,207 @@
+// Rendering evidence: screenshots, video, traces, logs — and honest absence.
+//
+// The contract for this module is one sentence: **it never emits a broken link.**
+//
+// Every path here has already been through the artifact registry, so each record
+// carries `exists` as a measured fact. A record that is present renders as a preview
+// with actions; a record that is not renders as a stated absence with the reason and
+// the path that was searched. What it must never do is emit `<img src=…>` for a file
+// nobody checked, because the browser's broken-image glyph tells the reader nothing
+// except that the report is unreliable.
+
+import { e, icon, chip, formatBytes } from './primitives.mjs';
+
+// What each evidence kind is called in the report. The contract guarantees `type` on
+// every entry but a caption only sometimes, so the type label is what a caption can
+// always fall back to.
+export const EVIDENCE_LABEL = Object.freeze({
+  screenshot: 'Screenshot',
+  video: 'Video',
+  trace: 'Playwright trace',
+  network: 'Network capture',
+  console: 'Console output',
+  dom: 'DOM snapshot',
+  har: 'HAR archive',
+  db: 'Database query',
+  performance: 'Performance metrics',
+  accessibility: 'Accessibility report',
+  security: 'Security report',
+  api: 'API report',
+  coverage: 'Coverage report',
+  log: 'Log',
+  diff: 'Diff',
+  file: 'File',
+  report: 'Report',
+  command: 'Command output',
+});
+
+export function evidenceLabel(kind) {
+  return EVIDENCE_LABEL[kind] ?? 'Evidence';
+}
+
+/**
+ * A stated absence.
+ *
+ * Named rather than silent: a missing screenshot is itself a finding about the run,
+ * and hiding it lets a reader assume the evidence exists and they simply cannot see
+ * it. The recorded path is shown because it is the one thing that makes the problem
+ * fixable — nine times in ten it is a path written relative to the wrong directory.
+ */
+export function missingArtifact(record) {
+  const name = record.label ?? evidenceLabel(record.kind);
+  const reason = record.missingReason ?? 'File not found at the recorded path';
+  const path = record.declaredPath
+    ? `<div style="margin-top:.25rem"><code>${e(record.declaredPath)}</code></div>`
+    : '';
+  return (
+    '<div class="artifact-missing" role="note">' +
+    icon('warning', 18) +
+    `<div><span class="why">Artifact missing — ${e(name)}</span>` +
+    `<span>${e(reason)}.</span>${path}</div>` +
+    '</div>'
+  );
+}
+
+/** The caption strip under a preview: what it is, how big, and where to open it. */
+function caption(record, { side = null } = {}) {
+  const name = record.label ?? evidenceLabel(record.kind);
+  const bits = [
+    `<span class="name"${side ? ` data-side="${e(side)}"` : ''}>${e(name)}</span>`,
+    record.sizeLabel ? `<span class="muted">${e(record.sizeLabel)}</span>` : '',
+    record.declaredPath ? `<code>${e(record.declaredPath)}</code>` : '',
+  ].filter(Boolean);
+
+  const actions = record.href
+    ? '<span class="shot-actions">' +
+      `<a href="${e(record.href)}" target="_blank" rel="noopener noreferrer">Open full size</a>` +
+      '</span>'
+    : '';
+  return `<figcaption>${bits.join('')}${actions}</figcaption>`;
+}
+
+/**
+ * One artifact, rendered the way its type allows.
+ *
+ * Images get a lazy-loaded preview that opens in the lightbox; video gets native
+ * controls; everything else gets a link and, when the run captured one, a text
+ * excerpt. `loading="lazy"` and explicit dimensions matter here — a report with forty
+ * screenshots that decodes all of them on open is a report nobody scrolls.
+ */
+export function artifactFigure(record, { side = null, excerpt = null } = {}) {
+  if (!record) return '';
+  if (!record.exists) return missingArtifact(record);
+
+  if (record.renderAs === 'image') {
+    // An embedded copy wins: it is the one that still shows when the report travels
+    // alone. The full-size link stays pointed at the file on disk.
+    const src = record.dataUri ?? record.thumbnailHref ?? record.href;
+    const dimensions =
+      record.width && record.height ? ` width="${record.width}" height="${record.height}"` : '';
+    return (
+      '<figure class="shot">' +
+      `<img src="${e(src)}" alt="${e(record.label ?? evidenceLabel(record.kind))}" loading="lazy" ` +
+      `decoding="async"${dimensions} data-full="${e(record.dataUri ?? record.href)}" ` +
+      `data-name="${e(record.label ?? record.declaredPath)}" class="js-zoom">` +
+      caption(record, { side }) +
+      '</figure>'
+    );
+  }
+
+  if (record.renderAs === 'video') {
+    return (
+      '<figure class="shot">' +
+      `<video controls preload="metadata" src="${e(record.href)}"></video>` +
+      caption(record, { side }) +
+      '</figure>'
+    );
+  }
+
+  // A trace, a HAR, a log. The excerpt is what makes it readable without leaving the
+  // page; the link is what makes it verifiable.
+  return (
+    '<figure class="shot">' +
+    (excerpt ? `<pre><code>${e(excerpt)}</code></pre>` : '') +
+    caption(record, { side }) +
+    '</figure>'
+  );
+}
+
+/**
+ * A before/after pair, shown side by side.
+ *
+ * Two screenshots stacked vertically are two screenshots; side by side with a shared
+ * caption they are a comparison, and the reader sees the difference without being
+ * told what to look for.
+ */
+export function comparePair(before, after) {
+  if (!before || !after) return '';
+  return (
+    '<div class="compare">' +
+    artifactFigure(before, { side: 'Before' }) +
+    artifactFigure(after, { side: 'After' }) +
+    '</div>'
+  );
+}
+
+/**
+ * Every evidence entry on a finding, resolved and rendered.
+ *
+ * Before/after pairs are pulled out first so they render together rather than as two
+ * unrelated tiles; whatever is left renders in declaration order.
+ */
+export function evidenceGrid(entries, registry) {
+  const records = (entries ?? [])
+    .map((entry) => ({ entry, record: registry.forEvidence(entry) }))
+    .filter((pair) => pair.record);
+  if (records.length === 0) return '';
+
+  const rendered = [];
+  const consumed = new Set();
+
+  for (const { entry, record } of records) {
+    if (consumed.has(record)) continue;
+    if (record.compares) {
+      const other = registry.get(record.compares);
+      if (other) {
+        consumed.add(record);
+        consumed.add(other);
+        // `compares` points at the earlier state, so the record declaring it is "after".
+        rendered.push(comparePair(other, record));
+        continue;
+      }
+    }
+    consumed.add(record);
+    rendered.push(artifactFigure(record, { excerpt: entry.excerpt ?? null }));
+  }
+
+  return `<div class="evidence">${rendered.join('')}</div>`;
+}
+
+/** The run-level evidence index: one table of every artifact and whether it is there. */
+export function artifactTable(records) {
+  if (records.length === 0) return '';
+  const rows = records
+    .map((record) => {
+      const state = record.exists
+        ? '<span class="pill st-passed">Present</span>'
+        : '<span class="pill st-failed">Missing</span>';
+      const link = record.exists && record.href
+        ? `<a href="${e(record.href)}" target="_blank" rel="noopener noreferrer"><code>${e(record.declaredPath)}</code></a>`
+        : `<code>${e(record.declaredPath || '—')}</code>`;
+      return (
+        '<tr>' +
+        `<td>${e(evidenceLabel(record.kind))}</td>` +
+        `<td>${e(record.label ?? '')}</td>` +
+        `<td>${link}</td>` +
+        `<td class="num">${e(record.exists ? formatBytes(record.bytes) : '—')}</td>` +
+        `<td>${state}${record.hashMismatch ? chip('hash mismatch') : ''}</td>` +
+        '</tr>'
+      );
+    })
+    .join('');
+  return (
+    '<div class="table-wrap"><table><thead><tr>' +
+    '<th>Kind</th><th>Shows</th><th>File</th><th class="num">Size</th><th>State</th>' +
+    `</tr></thead><tbody>${rows}</tbody></table></div>`
+  );
+}

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

@@ -0,0 +1,258 @@
+// The finding card — the unit of the report a developer actually works from.
+//
+// ## Collapsed by default, and why the summary has to carry weight
+//
+// A report with twenty findings expanded is a wall nobody reads. Collapsed, the
+// summary row is all most readers ever see, so it carries the four things needed to
+// triage without opening anything: severity, what is wrong, where, and whether it was
+// confirmed. Everything else lives inside.
+//
+// `<details>` rather than a JavaScript accordion: it opens with no script, it is
+// keyboard-operable and screen-reader-announced for free, and Ctrl-F finds text inside
+// a closed one in Chrome. The print stylesheet forces every one open, because a
+// printed report of collapsed headings is a printed table of contents.
+//
+// ## The order of the body
+//
+//   what happens now → what should happen → why it matters → how to see it
+//   → why it happens → how to fix it → what to re-test → the proof
+//
+// A reader who stops one third of the way down still has the defect, the gap, and the
+// business consequence. Root cause and fix direction come after that, because they are
+// what an engineer needs and the first three are what everyone needs.
+
+import {
+  e, slug, severityBadge, statusPill, chip, icon, plural,
+} from './primitives.mjs';
+import { evidenceGrid } from './evidence.mjs';
+import { SEVERITY } from '../theme/tokens.mjs';
+
+const DIMENSION_LABEL = Object.freeze({
+  functional: 'Functionality',
+  api: 'API',
+  performance: 'Performance',
+  security: 'Security',
+  ui: 'UI',
+  ux: 'UX',
+  data: 'Data',
+  accessibility: 'Accessibility',
+  console: 'Console',
+});
+
+const STATUS_LABEL = Object.freeze({
+  confirmed: 'Confirmed',
+  'validated-user-report': 'Validated user report',
+  'could-not-reproduce': 'Could not reproduce',
+  partial: 'Partially reproduced',
+  'fixed-in-run': 'Fixed during the run',
+});
+
+const LAYER_LABEL = Object.freeze({
+  frontend: 'Frontend',
+  backend: 'Backend',
+  network: 'Network',
+  data: 'Data',
+  infrastructure: 'Infrastructure',
+  'third-party': 'Third party',
+  unknown: 'Unknown',
+});
+
+export function dimensionLabel(dimension) {
+  return DIMENSION_LABEL[dimension] ?? dimension ?? '';
+}
+
+export function findingAnchor(id) {
+  return slug(id, 'f-');
+}
+
+/**
+ * Reproduction as steps when the run recorded steps, as prose otherwise.
+ *
+ * `steps[]` is the contract's structured form and is used when present. Failing that,
+ * numbered prose is split on its own numbering — nothing invented, nothing reordered.
+ * Unnumbered prose is left exactly as written, because guessing sentence boundaries in
+ * a repro turns "click Save. Wait 3s." into two steps that are really one.
+ */
+function reproBlock(finding) {
+  if (Array.isArray(finding.steps) && finding.steps.length > 0) {
+    return `<ol class="steps">${finding.steps.map((step) => `<li>${e(step)}</li>`).join('')}</ol>`;
+  }
+  const text = String(finding.repro ?? '').trim();
+  if (!text) return '<span class="empty">Not recorded</span>';
+
+  let lines = text.split('\n').map((line) => line.trim()).filter(Boolean);
+  if (lines.length === 1) {
+    lines = text.split(/\s+(?=\d+[.)]\s)/).map((part) => part.trim()).filter(Boolean);
+  }
+  if (lines.length < 2 || !lines.every((line) => /^\d+[.)]\s/.test(line))) {
+    return e(text);
+  }
+  const steps = lines.map((line) => line.replace(/^\d+[.)]\s*/, ''));
+  return `<ol class="steps">${steps.map((step) => `<li>${e(step)}</li>`).join('')}</ol>`;
+}
+
+/** A labelled row in the behaviour list. */
+function row(term, body, railClass = null) {
+  if (!body) return '';
+  return `<dt>${e(term)}</dt><dd${railClass ? ` class="rail ${railClass}"` : ''}>${body}</dd>`;
+}
+
+/** The metrics table that turns "slow" into a number with a budget beside it. */
+function metricsPanel(metrics) {
+  if (!metrics || metrics.length === 0) return '';
+  const rows = metrics
+    .map(
+      (metric) =>
+        '<tr>' +
+        `<td>${e(metric.label)}</td>` +
+        `<td class="num"${metric.breached ? ' style="color:var(--sev-solid);font-weight:650"' : ''}>` +
+        `${e(metric.value)}</td>` +
+        `<td class="num muted">${e(metric.budget ?? '—')}</td>` +
+        '</tr>',
+    )
+    .join('');
+  return (
+    '<div class="table-wrap" style="margin-top:1rem"><table>' +
+    '<thead><tr><th>Measurement</th><th class="num">Observed</th><th class="num">Budget</th></tr></thead>' +
+    `<tbody>${rows}</tbody></table></div>`
+  );
+}
+
+/** Root cause: the investigation, rendered as a causal chain rather than a paragraph. */
+function rootCausePanel(rootCause) {
+  if (!rootCause?.summary) return '';
+  const chain =
+    Array.isArray(rootCause.chain) && rootCause.chain.length > 0
+      ? `<ol class="chain" style="margin-top:.5rem">${rootCause.chain.map((step) => `<li>${e(step)}</li>`).join('')}</ol>`
+      : '';
+  const meta = [
+    rootCause.layer ? chip(LAYER_LABEL[rootCause.layer] ?? rootCause.layer) : '',
+    Number.isFinite(rootCause.confidence)
+      ? chip(`${Math.round(rootCause.confidence * 100)}% confidence`)
+      : '',
+  ]
+    .filter(Boolean)
+    .join('');
+  return (
+    `<div>${e(rootCause.summary)}${chain}` +
+    (meta ? `<div style="margin-top:.5rem;display:flex;gap:.375rem;flex-wrap:wrap">${meta}</div>` : '') +
+    '</div>'
+  );
+}
+
+/** What QA re-runs once the fix lands — the half of a bug report that usually goes missing. */
+function regressionPanel(regression) {
+  if (!regression?.level) return '';
+  const tone = { high: 'critical', medium: 'medium', low: 'low' }[regression.level] ?? 'low';
+  const retest =
+    Array.isArray(regression.retest) && regression.retest.length > 0
+      ? `<ul class="clean" style="margin-top:.5rem">${regression.retest.map((item) => `<li>${e(item)}</li>`).join('')}</ul>`
+      : '';
+  return (
+    `<div><span class="badge sev-${tone}">${e(regression.level)} risk</span>` +
+    (regression.note ? `<div style="margin-top:.375rem">${e(regression.note)}</div>` : '') +
+    retest +
+    '</div>'
+  );
+}
+
+/**
+ * One finding, collapsed.
+ *
+ * `data-*` attributes on the element carry everything the client-side filter needs, so
+ * search and severity filtering run without a second copy of the findings in a script
+ * block — the DOM is the index.
+ */
+export function findingCard(finding, registry, { open = false } = {}) {
+  const severity = SEVERITY[finding.severity] ? finding.severity : 'low';
+  const anchor = findingAnchor(finding.id);
+  const tags = Array.isArray(finding.tags) ? finding.tags : [];
+
+  // Everything a reader might type into the search box, flattened once at render time.
+  const haystack = [
+    finding.id, finding.title, finding.actual, finding.expected, finding.fixDirection,
+    finding.businessImpact, finding.developerNotes, finding.page,
+    finding.rootCause?.summary, dimensionLabel(finding.dimension),
+    ...tags, ...(finding.affectedApis ?? []),
+  ]
+    .filter(Boolean)
+    .join(' ')
+    .toLowerCase();
+
+  const meta = [
+    `<span class="finding-id">${e(finding.id)}</span>`,
+    chip(dimensionLabel(finding.dimension)),
+    statusPill(finding.status, STATUS_LABEL[finding.status] ?? finding.status),
+    finding.page ? chip(finding.page) : '',
+    ...tags.map((tag) => chip(tag)),
+  ]
+    .filter(Boolean)
+    .join('');
+
+  const body = [
+    '<dl class="behaviour">',
+    row('Current behaviour', e(finding.actual), 'rail-now'),
+    row('Expected behaviour', e(finding.expected), 'rail-want'),
+    row('Business impact', finding.businessImpact ? e(finding.businessImpact) : '', 'rail-impact'),
+    row('Reproduction', reproBlock(finding)),
+    row('Root cause', rootCausePanel(finding.rootCause), 'rail-cause'),
+    row('Suggested fix', e(finding.fixDirection), 'rail-fix'),
+    row('Regression risk', regressionPanel(finding.regressionRisk)),
+    row(
+      'Affected APIs',
+      (finding.affectedApis ?? []).map((api) => `<code>${e(api)}</code>`).join(' '),
+    ),
+    row('Developer notes', finding.developerNotes ? e(finding.developerNotes) : ''),
+    '</dl>',
+    metricsPanel(finding.metrics),
+    evidenceGrid(finding.evidence, registry),
+  ].join('');
+
+  return (
+    `<details class="finding sev-${severity}" id="${e(anchor)}"${open ? ' open' : ''} ` +
+    `data-severity="${e(severity)}" data-dimension="${e(finding.dimension ?? '')}" ` +
+    `data-status="${e(finding.status ?? '')}" data-page="${e(finding.page ?? '')}" ` +
+    `data-tags="${e(tags.join(' '))}" data-search="${e(haystack)}">` +
+    '<summary>' +
+    severityBadge(severity) +
+    '<span class="finding-grow">' +
+    `<span class="finding-title">${e(finding.title)}</span>` +
+    `<span class="finding-meta">${meta}</span>` +
+    '</span>' +
+    `<span class="caret">${icon('chevron', 18)}</span>` +
+    '</summary>' +
+    `<div class="finding-body">${body}</div>` +
+    '</details>'
+  );
+}
+
+/** Every finding, worst first, with a stable tie-break so reruns diff cleanly. */
+export function findingList(findings, registry) {
+  const sorted = [...findings].sort((a, b) => {
+    const rank = (SEVERITY[a.severity] ?? SEVERITY.low).rank - (SEVERITY[b.severity] ?? SEVERITY.low).rank;
+    return rank !== 0 ? rank : String(a.id).localeCompare(String(b.id), 'en', { numeric: true });
+  });
+  if (sorted.length === 0) {
+    return '<div class="card"><div class="card-body empty">No findings recorded.</div></div>';
+  }
+  return (
+    sorted.map((finding) => findingCard(finding, registry)).join('') +
+    '<div class="no-results" id="no-results">' +
+    `<p><strong>Nothing matches those filters.</strong></p><p>${e(plural(sorted.length, 'finding'))} in total — ` +
+    'clear the search box or reset the severity filters to see them.</p></div>'
+  );
+}
+
+/** The severity legend, so a reader can calibrate without asking what "high" means. */
+export function severityLegend() {
+  const rows = Object.entries(SEVERITY)
+    .sort((a, b) => a[1].rank - b[1].rank)
+    .map(([key, value]) => `<tr><td>${severityBadge(key)}</td><td>${e(value.meaning)}</td></tr>`)
+    .join('');
+  return (
+    '<div class="table-wrap"><table><thead><tr><th>Severity</th><th>What it claims</th></tr></thead>' +
+    `<tbody>${rows}</tbody></table></div>`
+  );
+}
+
+export { STATUS_LABEL, DIMENSION_LABEL };

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

@@ -0,0 +1,99 @@
+// The sticky sidebar and the findings toolbar.
+//
+// A twelve-section report needs a map, and a report shared with six audiences needs a
+// way for each of them to reach their part of it: an engineering manager wants
+// Findings, a CTO wants Overview and Security, a designer wants Screenshots.
+//
+// Both controls degrade honestly. The sidebar is a list of in-page anchors, so it
+// works with scripting disabled and it prints as nothing (deliberately hidden). The
+// toolbar's search and filters need script, so they are rendered only when the report
+// has enough findings to be worth filtering, and the findings themselves are always
+// present in the document whether or not the toolbar ever runs.
+
+import { e, icon } from './primitives.mjs';
+import { SEVERITY, SEVERITY_ORDER } from '../theme/tokens.mjs';
+
+/** The sidebar: brand, then one anchor per section that has content. */
+export function sidebar(sections, { productName, subtitle }) {
+  const links = sections
+    .filter((section) => section.body)
+    .map(
+      (section) =>
+        `<a href="#${e(section.id)}" data-target="${e(section.id)}">` +
+        `<span>${e(section.navLabel ?? section.title)}</span>` +
+        (section.count === null || section.count === undefined
+          ? ''
+          : `<span class="n">${e(section.count)}</span>`) +
+        '</a>',
+    )
+    .join('');
+
+  return (
+    '<aside class="sidebar" aria-label="Report sections">' +
+    '<div class="sidebar-brand">' +
+    '<span class="sidebar-mark" aria-hidden="true">QA</span>' +
+    `<span><span class="sidebar-name">${e(productName)}</span>` +
+    `<br><span class="sidebar-sub">${e(subtitle)}</span></span>` +
+    '</div>' +
+    `<nav class="toc" aria-label="Sections">${links}</nav>` +
+    '</aside>'
+  );
+}
+
+/**
+ * Search, severity filters, expand/collapse, theme, print.
+ *
+ * The severity buttons start pressed — the default view is everything, and a filter
+ * that hides findings before the reader asks is how a report loses a critical.
+ */
+export function toolbar(counts, { dimensions = [] } = {}) {
+  const severityFilters = SEVERITY_ORDER.filter((key) => (counts[key] ?? 0) > 0)
+    .map(
+      (key) =>
+        `<button type="button" class="filter sev-${key}" data-filter="severity" data-value="${key}" ` +
+        `aria-pressed="true"><span class="dot"></span>${e(SEVERITY[key].label)} ` +
+        `<span class="tabular">${e(counts[key] ?? 0)}</span></button>`,
+    )
+    .join('');
+
+  const dimensionFilters = dimensions
+    .map(
+      (dimension) =>
+        `<button type="button" class="filter" data-filter="dimension" data-value="${e(dimension.key)}" ` +
+        `aria-pressed="true">${e(dimension.label)} <span class="tabular">${e(dimension.count)}</span></button>`,
+    )
+    .join('');
+
+  return (
+    '<div class="toolbar" role="search">' +
+    '<label class="search">' +
+    icon('search', 16) +
+    '<input type="search" id="finding-search" placeholder="Search findings, APIs, pages, root causes…" ' +
+    'autocomplete="off" aria-label="Search findings">' +
+    '</label>' +
+    `<div class="filters">${severityFilters}${dimensionFilters}</div>` +
+    '<span class="match-count" id="match-count" aria-live="polite"></span>' +
+    '<button type="button" class="iconbtn" id="toggle-all" title="Expand or collapse every finding" ' +
+    `aria-label="Expand or collapse every finding">${icon('expand', 16)}</button>` +
+    '<button type="button" class="iconbtn" id="toggle-theme" title="Switch between light and dark" ' +
+    `aria-label="Switch between light and dark">${icon('moon', 16)}</button>` +
+    '<button type="button" class="iconbtn" id="print-report" title="Print or save as PDF" ' +
+    `aria-label="Print or save as PDF">${icon('print', 16)}</button>` +
+    '</div>'
+  );
+}
+
+/** The lightbox shell. Empty until a screenshot is clicked. */
+export function lightbox() {
+  return (
+    '<div class="lightbox" id="lightbox" role="dialog" aria-modal="true" aria-label="Screenshot viewer" hidden>' +
+    '<div class="lightbox-bar">' +
+    '<span class="grow" id="lightbox-name"></span>' +
+    '<button type="button" id="lightbox-zoom">Zoom</button>' +
+    '<a id="lightbox-open" href="#" target="_blank" rel="noopener noreferrer">Open file</a>' +
+    `<button type="button" id="lightbox-close" aria-label="Close viewer">${icon('close', 16)}</button>` +
+    '</div>' +
+    '<img id="lightbox-img" alt="">' +
+    '</div>'
+  );
+}