qa-engineer 0.10.0 → 0.12.0

package/packages/engine/lib/analysis/report-html.mjs

@@ -1,763 +1,76 @@
 // Render a contract artifact as a presentation-grade HTML report.
 //
-// ## Why this is code
+// ## What this module is now
 //
-// The first real `/qa-explore` run on a live application produced a valid artifact
-// and a *lossy* report. Every finding in the contract carries `repro`, `actual`,
-// `expected`, and `fixDirection` — all four required fields — and the hand-written
-// HTML collapsed them into a single sentence:
+// A stable entry point. The rendering itself moved to `lib/report/`, which is split
+// into theme, components, core, and export — because a single 700-line file could not
+// hold an enterprise report and stay reviewable, and because the Markdown, SARIF,
+// JUnit, and CSV renderings all need the same view model the HTML uses.
 //
-//     EXP-1 · high — Double-click Login fires two GraphQL auth requests
-//     Two identical POSTs to /graphql. Disable Login while in flight.
+// This file stays because it is the *published* seam: `qa-tool.mjs analysis
+// report-html` is documented in nine installed skills and in every report-pipeline
+// reference. Moving code is cheap; moving a documented command out from under
+// installed copies is not.
 //
-// The reader is left to infer what was expected, how to reproduce it, and what
-// "correct" would look like. The data existed; the rendering discarded it. It also
-// omitted the attribution footer entirely.
+// ## Why the report is rendered rather than typed
 //
-// Both failures share one cause: the report was *typed* rather than *rendered*. So
-// it is rendered here. The contract is the input, every required field appears in
-// the output, and the footer is not optional. A report cannot silently drop what a
-// reader needs, because no one is retyping it.
+// The first real `/qa-explore` run on a live application produced a valid artifact and
+// a *lossy* report. Every finding in the contract carries `repro`, `actual`,
+// `expected`, and `fixDirection` — all four required — and the hand-written HTML
+// collapsed them into a single sentence:
 //
-// ## What it renders
+//     EXP-1 · high — Double-click Login fires two GraphQL auth requests
+//     Two identical POSTs to /graphql. Disable Login while in flight.
 //
-// `explore-result` and `report-result` today — the two artifacts a human reads.
-// Each finding becomes a card stating, in order: what is wrong, **what happens
-// now**, **what should happen instead**, how to reproduce it, and the fix
-// direction. That ordering is deliberate: a reader who stops after two lines still
-// knows the defect and the gap.
+// The reader is left to infer what was expected, how to reproduce it, and what
+// "correct" would look like. The data existed; the rendering discarded it.
 //
-// Ahead of the findings comes the orientation a forwarded report needs — what kind
-// of document this is, how the application was observed, what each area checked
-// means, what the severity labels claim, and what the run did *not* cover.
+// The second live run produced a beautiful report in which **every screenshot was
+// broken**, because the declared paths were relative to the project root and the
+// report was written inside the run folder. Both failures have the same cause: a human
+// or a model retyping what a renderer should own. So the renderer owns it, and
+// `lib/artifacts/manager.mjs` owns the difference between where a file is and how this
+// document links to it.
 //
-// No dependencies, single self-contained file, no external assets — a report must
+// No dependencies, one self-contained file out, no external assets — a report must
 // open from an email attachment on a plane.
 
 import fs from 'node:fs';
+import path from 'node:path';
 
-import { footerHtml } from './branding.mjs';
-
-export class ReportError extends Error {}
-
-// Severity drives colour, order, and the summary bar. Kept here rather than in the
-// template so a new severity cannot render as an unstyled surprise.
-const SEVERITY = {
-  critical: { label: "Critical", colour: "#8b0018", tint: "#fdf0f2", rank: 0 },
-  high: { label: "High", colour: "#b3261e", tint: "#fdf1f0", rank: 1 },
-  medium: { label: "Medium", colour: "#a15c00", tint: "#fdf6ec", rank: 2 },
-  low: { label: "Low", colour: "#4a5568", tint: "#f4f5f7", rank: 3 },
-};
-
-// Summary tiles for non-severity counts. Test totals are not severities, and
-// rendering "failed" in the same neutral grey as "passed" is how a reader misses
-// the number that matters.
-const COUNT_STYLE = {
-  "total": "#344054",
-  "passed": "#116149",
-  "failed": "#b3261e",
-  "blocked": "#a15c00",
-  "skipped": "#667085",
-};
-
-// What each evidence kind is called in the report. The contract guarantees `type`
-// on every entry but `description` only on the top-level index, so the type is
-// what a caption can always be built from.
-const EVIDENCE_LABEL = {
-  "screenshot": "Screenshot",
-  "network": "Network capture",
-  "console": "Console output",
-  "dom": "DOM snapshot",
-  "har": "HAR archive",
-  "db": "Database query",
-  "file": "File",
-  "report": "Report",
-  "command": "Command output",
-  "trace": "Trace",
-  "log": "Log",
-  "diff": "Diff",
-};
-
-// What each QA dimension means to someone who has never read a QA report. The
-// contract stores dimension *names*, which are jargon: "ux" tells a reader nothing.
-const DIMENSION_LABEL = {
-  "functional": "Functionality",
-  "api": "API",
-  "performance": "Performance",
-  "security": "Security (client-side)",
-  "ui": "UI",
-  "ux": "UX",
-  "data": "Data",
-};
-
-const DIMENSION_PLAIN = {
-  "functional": "Does the feature do what it is supposed to do, including when the input is wrong?",
-  "api": "The network requests the page makes — whether they are correct, and how the page handles a bad response",
-  "performance": "How much the page downloads and how quickly it becomes usable",
-  "security": "Client-side exposure only: where credentials and tokens are stored, what leaks into URLs and error messages",
-  "ui": "Layout and visual states — empty, loading, error — including a narrow mobile screen",
-  "ux": "Whether the flow makes sense to a person using it, and whether the wording helps them",
-  "data": "Whether the numbers and text on screen match the system of record behind them",
-};
-
-// What each severity is claiming, so a reader can calibrate without asking.
-const SEVERITY_MEANING = {
-  "critical": "Blocks release. Data loss, a security hole, or a core flow that cannot be completed.",
-  "high": "Fix before release. A user hits this on a normal path and the product does the wrong thing.",
-  "medium": "Fix soon. Real but survivable — a workaround exists, or the path is less common.",
-  "low": "Worth fixing. Polish, hygiene, or a measurement that needs confirming before it is acted on.",
-};
-
-// How each browser adapter observed the application, in one honest phrase. A
-// reader deciding how much to trust a finding needs to know what watched the page.
-const ADAPTER_PLAIN = {
-  "playwright-mcp": "a real browser driven by Playwright",
-  "cursor-browser": "the editor's built-in browser",
-  "cdp": "a real browser over the Chrome DevTools Protocol",
-  "cli-playwright": "a real browser driven by the Playwright CLI",
-  "cli-other": "a real browser driven from the command line",
-  "unavailable": "no browser automation — findings come from artifacts supplied to the run",
-};
-
-const STATUS_LABEL = {
-  "confirmed": "Confirmed",
-  "validated-user-report": "Validated user report",
-  "could-not-reproduce": "Could not reproduce",
-  "partial": "Partially reproduced",
-  "pass": "Passed",
-  "fail": "Failed",
-  "blocked": "Blocked",
-  "skipped": "Skipped",
-};
-
-const VERDICT = {
-  "pass": ["No defects found", "#116149", "#eaf7f1"],
-  "issues-found": ["Issues found", "#a15c00", "#fdf6ec"],
-  "blocked": ["Blocked", "#b3261e", "#fdf1f0"],
-  "insufficient-data": ["Insufficient data", "#4a5568", "#f4f5f7"],
-  "ready": ["Ready to ship", "#116149", "#eaf7f1"],
-  "ready-with-risks": ["Ready with risks", "#a15c00", "#fdf6ec"],
-  "not-ready": ["Not ready", "#b3261e", "#fdf1f0"],
-};
-
-const CSS = "\n*,*::before,*::after{box-sizing:border-box}\nbody{margin:0;background:#f7f8fa;color:#1a1d21;\n  font:16px/1.6 -apple-system,BlinkMacSystemFont,\"Segoe UI\",Roboto,Helvetica,Arial,sans-serif;\n  -webkit-font-smoothing:antialiased}\n.page{max-width:60rem;margin:0 auto;padding:2.5rem 1.5rem 3rem}\n.card{background:#fff;border:1px solid #e4e7ec;border-radius:12px;\n  box-shadow:0 1px 2px rgba(16,24,40,.04);margin-bottom:1.25rem;overflow:hidden}\n.card-body{padding:1.5rem}\nheader.masthead{margin-bottom:1.75rem}\n.eyebrow{font-size:.6875rem;font-weight:700;letter-spacing:.09em;text-transform:uppercase;color:#667085}\nh1{margin:.35rem 0 .5rem;font-size:1.875rem;line-height:1.25;letter-spacing:-.02em}\nh2{margin:2rem 0 .875rem;font-size:1.125rem;letter-spacing:-.01em}\nh3{margin:0;font-size:1.0625rem;letter-spacing:-.01em}\n.meta{color:#667085;font-size:.8125rem}\n.meta strong{color:#344054;font-weight:600}\n.lead{margin:0 0 .25rem;font-size:1.0625rem;color:#475467;max-width:52rem}\n.intro p{margin:0 0 .75rem;max-width:52rem}\n.intro p:last-child{margin-bottom:0}\n.objective{margin:0 0 .875rem;max-width:52rem}\n.objective:last-child{margin-bottom:0}\n.verdict{display:flex;flex-wrap:wrap;gap:.75rem;align-items:center;\n  padding:1rem 1.25rem;border-radius:10px;font-weight:600;margin:1.25rem 0}\n.counts{display:flex;flex-wrap:wrap;gap:.5rem;margin:1.25rem 0}\n.count{flex:1 1 7rem;background:#fff;border:1px solid #e4e7ec;border-radius:10px;\n  padding:.75rem .875rem;text-align:center}\n.count .n{display:block;font-size:1.5rem;font-weight:700;line-height:1.2}\n.count .l{font-size:.6875rem;text-transform:uppercase;letter-spacing:.07em;color:#667085}\n.badge{display:inline-block;padding:.1875rem .5rem;border-radius:6px;\n  font-size:.6875rem;font-weight:700;letter-spacing:.04em;text-transform:uppercase;\n  border:1px solid currentColor}\n.chip{display:inline-block;padding:.1875rem .5rem;border-radius:6px;background:#f2f4f7;\n  color:#475467;font-size:.75rem;font-weight:500}\n.finding-head{display:flex;gap:.75rem;align-items:flex-start;\n  padding:1.125rem 1.5rem;border-bottom:1px solid #eef0f3}\n.finding-head .grow{flex:1;min-width:0}\n.finding-id{font-family:ui-monospace,SFMono-Regular,Menlo,monospace;font-size:.75rem;color:#667085}\ndl.behaviour{margin:0;display:grid;grid-template-columns:minmax(8.5rem,auto) 1fr;gap:.625rem 1.25rem}\ndl.behaviour dt{font-size:.75rem;font-weight:700;letter-spacing:.05em;text-transform:uppercase;color:#667085;padding-top:.15rem}\ndl.behaviour dd{margin:0}\n.now{border-left:3px solid #b3261e;padding-left:.75rem}\n.want{border-left:3px solid #116149;padding-left:.75rem}\n.fix{border-left:3px solid #3538cd;padding-left:.75rem}\ntable{border-collapse:collapse;width:100%;font-size:.875rem}\nth,td{text-align:left;padding:.5625rem .75rem;border-bottom:1px solid #eef0f3;vertical-align:top}\nth{font-size:.6875rem;text-transform:uppercase;letter-spacing:.06em;color:#667085;\n  background:#fafbfc;font-weight:700}\ntbody tr:last-child td{border-bottom:0}\ncode{font-family:ui-monospace,SFMono-Regular,Menlo,monospace;font-size:.875em;\n  background:#f2f4f7;padding:.1rem .3rem;border-radius:4px}\npre{margin:0;background:#1a1d21;color:#e4e7ec;padding:1rem;border-radius:8px;\n  overflow-x:auto;font-size:.8125rem;line-height:1.55}\nfigure{margin:.875rem 0 0}\nfigure img{display:block;max-width:100%;height:auto;border:1px solid #e4e7ec;border-radius:8px}\nfigcaption{margin-top:.4rem;font-size:.75rem;color:#667085}\nul.clean{margin:0;padding-left:1.125rem}\nul.clean li{margin:.3rem 0}\nol.steps{margin:0;padding-left:1.25rem}\nol.steps li{margin:.15rem 0}\nol.order{margin:0;padding-left:1.25rem}\nol.order li{margin:.4rem 0}\n.empty{color:#667085;font-style:italic}\n@media print{body{background:#fff}.card{box-shadow:none;break-inside:avoid}.page{padding:0}}\n@media (max-width:34rem){dl.behaviour{grid-template-columns:1fr;gap:.25rem}\n  dl.behaviour dt{padding-top:.5rem}}\n";
-
-/** HTML-escape, matching Python's `html.escape(s, quote=True)`. */
-function e(value) {
-  if (value === null || value === undefined) return '';
-  return String(value)
-    .replace(/&/g, '&')
-    .replace(/</g, '&lt;')
-    .replace(/>/g, '&gt;')
-    .replace(/"/g, '&quot;')
-    .replace(/'/g, '&#x27;');
-}
-
-function severityBadge(severity) {
-  const meta = SEVERITY[severity] ?? SEVERITY.low;
-  return (
-    `<span class="badge" style="color:${meta.colour};background:${meta.tint}">` +
-    `${e(meta.label)}</span>`
-  );
-}
-
-/**
- * What the report is about, short enough to be a heading.
- *
- * The contract has no title field, and the summary is a paragraph — using it as an
- * `<h1>` produced a five-line heading. The target under test is the honest short
- * answer, the way Lighthouse titles a report by its URL.
- */
-function subject(result) {
-  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);
-}
-
-/**
- * Reproduction as steps when it is written as steps, as prose otherwise.
- *
- * Numbered steps are the part of a report a reader retypes into a browser, so they
- * are rendered as a list rather than one dense line. The split is on the text's own
- * numbering — nothing is invented, reordered, or dropped.
- */
-function reproSteps(repro) {
-  const text = String(repro ?? '').trim();
-  if (!text) return '<dd class="empty">Not recorded</dd>';
-  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);
-  }
-  const steps = lines.map((line) => line.replace(/^\d+[.)]\s*/, ''));
-  if (steps.length < 2 || !lines.every((line) => /^\d+[.)]\s/.test(line))) {
-    return `<dd>${e(text)}</dd>`;
-  }
-  return `<dd><ol class="steps">${steps.map((step) => `<li>${e(step)}</li>`).join('')}</ol></dd>`;
-}
-
-/** Sort TC-2 before TC-10, the way a reader expects a case list to run. */
-function naturalKey(identifier) {
-  return String(identifier ?? '')
-    .split(/(\d+)/)
-    .map((part) => (/^\d+$/.test(part) ? Number.parseInt(part, 10) : part.toLowerCase()));
-}
-
-function compareNatural(a, b) {
-  const left = naturalKey(a);
-  const right = naturalKey(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;
-    // Python compares int to int and str to str; a mixed pair cannot occur here
-    // because the split alternates text and digits from position 0 in both.
-    if (x === y) continue;
-    return x < y ? -1 : 1;
-  }
-  return 0;
-}
-
-/** A stable in-document id, so a failing test case can link to its finding. */
-function anchor(findingId) {
-  const safe = [...String(findingId ?? '')]
-    .map((char) => (/[\p{L}\p{N}]/u.test(char) || char === '-' || char === '_' ? char : '-'))
-    .join('');
-  return safe ? `f-${safe}` : '';
-}
-
-function isImage(item) {
-  const source = String(item.source ?? '').toLowerCase();
-  return (
-    item.type === 'screenshot' ||
-    ['.png', '.jpg', '.jpeg', '.webp', '.gif', '.avif'].some((ext) => source.endsWith(ext))
-  );
-}
-
-/**
- * A caption that is always meaningful.
- *
- * Finding-level evidence carries only `type` and `source` — `description` is
- * required on the top-level index, not here — so the type label is the fallback
- * rather than repeating the filename twice.
- */
-function evidenceCaption(item) {
-  const described = item.description;
-  const label = EVIDENCE_LABEL[item.type] ?? item.type ?? 'Evidence';
-  return described ? `${e(described)} — ${e(label)}` : e(label);
-}
-
-function evidenceFigures(items, indent = '    ') {
-  const parts = [];
-  for (const item of items ?? []) {
-    const source = item.source ?? '';
-    const caption = evidenceCaption(item);
-    parts.push(`${indent}<figure>`);
-    if (isImage(item)) {
-      parts.push(`${indent}  <img src="${e(source)}" alt="${caption}"/>`);
-    } else if (item.excerpt) {
-      parts.push(`${indent}  <pre>${e(item.excerpt)}</pre>`);
-    }
-    parts.push(`${indent}  <figcaption>${caption} · <code>${e(source)}</code></figcaption>`);
-    parts.push(`${indent}</figure>`);
-  }
-  return parts;
-}
-
-/**
- * One finding: the defect, then what happens now, then what should happen.
- *
- * Ordering is the point. `actual` and `expected` are required by the contract and
- * are the two things a reader cannot reconstruct for themselves, so they come
- * before reproduction and fix direction.
- */
-function findingCard(finding) {
-  const parts = [
-    `<article class="card" id="${anchor(finding.id)}">`,
-    '  <div class="finding-head">',
-    `    ${severityBadge(finding.severity)}`,
-    '    <div class="grow">',
-    `      <h3>${e(finding.title)}</h3>`,
-    `      <div class="finding-id">${e(finding.id)}</div>`,
-    '    </div>',
-    `    <span class="chip">${e(finding.dimension ?? '')}</span>`,
-    `    <span class="chip">${e(STATUS_LABEL[finding.status] ?? finding.status ?? '')}</span>`,
-    '  </div>',
-    '  <div class="card-body">',
-    '    <dl class="behaviour">',
-    '      <dt>Current behaviour</dt>',
-    `      <dd class="now">${e(finding.actual)}</dd>`,
-    '      <dt>Expected behaviour</dt>',
-    `      <dd class="want">${e(finding.expected)}</dd>`,
-    '      <dt>Reproduction</dt>',
-    `      ${reproSteps(finding.repro)}`,
-    '      <dt>Fix direction</dt>',
-    `      <dd class="fix">${e(finding.fixDirection)}</dd>`,
-    '    </dl>',
-  ];
-  parts.push(...evidenceFigures(finding.evidence));
-  parts.push('  </div>', '</article>');
-  return parts.join('\n');
-}
-
-function titleCase(key) {
-  return key
-    .replace(/-/g, ' ')
-    .split(' ')
-    .map((word) => (word ? word[0].toUpperCase() + word.slice(1).toLowerCase() : word))
-    .join(' ');
-}
-
-function countsBlock(counts, order) {
-  const cells = [];
-  for (const key of order) {
-    if (!(key in counts)) continue;
-    const label = SEVERITY[key]?.label ?? titleCase(key);
-    const colour = SEVERITY[key]?.colour ?? COUNT_STYLE[key] ?? '#1a1d21';
-    cells.push(
-      `<div class="count"><span class="n" style="color:${colour}">${e(counts[key])}</span>` +
-        `<span class="l">${e(label)}</span></div>`,
-    );
-  }
-  return cells.length > 0 ? `<div class="counts">${cells.join('')}</div>` : '';
-}
-
-/**
- * Executed cases, worst first, each failure linked to the finding it raised.
- *
- * A reader who starts from "which case failed?" should reach the explanation in one
- * click, so `findingId` becomes a link into the finding card rather than a bare
- * string they have to search for.
- */
-function testCaseTable(testCases, findingIds = new Set()) {
-  const cases = testCases.cases ?? [];
-  if (cases.length === 0) return '';
-  const order = { fail: 0, blocked: 1, skipped: 2, pass: 3 };
-  const rank = (status) => order[status] ?? 4;
-  const sorted = [...cases].sort(
-    (a, b) => rank(a.status) - rank(b.status) || compareNatural(a.id, b.id),
-  );
-  const rows = sorted.map((testCase) => {
-    const status = testCase.status ?? '';
-    const styleKey = { fail: 'failed', pass: 'passed' }[status] ?? status;
-    const colour = COUNT_STYLE[styleKey] ?? '#475467';
-    const findingId = testCase.findingId;
-    let link;
-    if (findingId && findingIds.has(findingId)) {
-      link = `<a href="#${anchor(findingId)}"><code>${e(findingId)}</code></a>`;
-    } else if (findingId) {
-      link = `<code>${e(findingId)}</code>`;
-    } else {
-      link = '<span class="empty">—</span>';
-    }
-    return (
-      '<tr>' +
-      `<td><code>${e(testCase.id)}</code></td>` +
-      `<td>${e(testCase.title)}</td>` +
-      `<td style="color:${colour};font-weight:600">` +
-      `${e(STATUS_LABEL[status] ?? status)}</td>` +
-      `<td>${link}</td>` +
-      '</tr>'
-    );
-  });
-  return (
-    '<div class="card"><table><thead><tr><th>ID</th><th>Test case</th>' +
-    '<th>Result</th><th>Finding</th></tr></thead><tbody>' +
-    rows.join('') +
-    '</tbody></table></div>'
-  );
-}
-
-/**
- * Open the report for a reader who has never seen this product.
- *
- * A QA report is forwarded to people who were not in the room: a founder, a
- * designer, the developer who owns one of the six findings. Landing straight on
- * "EXP-1 · high" asks them to work out what kind of document this is, who produced
- * it, how it was produced, and how much to trust it. So it says so. Everything here
- * is derived from the artifact — nothing is asserted about work that was not
- * recorded.
- */
-function orientation(result) {
-  const cases = result.testCases ?? {};
-  const executed = cases.total;
-  const adapter = ADAPTER_PLAIN[result.browserAdapter];
-
-  let how = ['opened the application'];
-  if (adapter) how = [`opened the application in ${adapter}`];
-  if (executed) how.push(`worked through ${executed} test case${executed !== 1 ? 's' : ''}`);
-  how.push('captured proof for every defect it reports');
-
-  const sentences = [
-    'This is an <strong>exploratory QA report</strong>. An AI QA engineer ' +
-      how.slice(0, -1).join(', ') +
-      `, and ${how[how.length - 1]}.`,
-    'Each finding below says what happens today, what should happen instead, ' +
-      'and how to see it for yourself — so nothing here has to be taken on trust.',
-  ];
-  return (
-    '<div class="card intro"><div class="card-body">' +
-    sentences.map((sentence) => `<p>${sentence}</p>`).join('') +
-    '</div></div>'
-  );
-}
-
-/**
- * What was tested and what was not, in plain language.
- *
- * Dimension names are jargon and coverage counts are not scope: "18 cases" does not
- * tell a reader whether sign-up was looked at. The model supplies the feature-level
- * prose in `scope`; the dimension table and the not-covered derivations are
- * computed, so a run that omits `scope` still explains itself.
- */
-function scopeBlock(result) {
-  const scope = result.scope ?? {};
-  const dimensions = result.dimensionsRun ?? [];
-  const parts = [];
+import {
+  render as renderDocument, ReportError, supportedContracts, supportedModes,
+  versionStamp, versionLine,
+} from '../report/export/html.mjs';
 
-  if (scope.objective) parts.push(`<p class="objective">${e(scope.objective)}</p>`);
-  if (scope.covered && scope.covered.length > 0) {
-    parts.push(`<ul class="clean">${scope.covered.map((x) => `<li>${e(x)}</li>`).join('')}</ul>`);
-  }
-  if (parts.length === 0 && dimensions.length === 0) return '';
-
-  let body = parts.length > 0
-    ? `<div class="card"><div class="card-body">${parts.join('')}</div></div>`
-    : '';
-
-  if (dimensions.length > 0) {
-    const rows = dimensions
-      .map(
-        (d) =>
-          `<tr><td><strong>${e(DIMENSION_LABEL[d] ?? d)}</strong></td>` +
-          `<td>${e(DIMENSION_PLAIN[d] ?? '')}</td></tr>`,
-      )
-      .join('');
-    body +=
-      '<div class="card"><table><thead><tr><th>Area checked</th>' +
-      `<th>What that means</th></tr></thead><tbody>${rows}</tbody></table></div>`;
-  }
-  return body;
-}
+export { ReportError, supportedContracts, supportedModes, versionStamp, versionLine };
 
 /**
- * The boundary of the run, stated rather than left to inference.
+ * Render a full standalone HTML document for a supported artifact.
  *
- * An unstated boundary reads as "everything was checked". Blocked cases and skipped
- * dimensions are the two boundaries the artifact already knows about, so they are
- * added to whatever the run declared.
+ * `resultPath` and `outPath` are how evidence links come out correct: the first says
+ * what declared paths are relative to, the second says what hrefs must be relative to.
+ * Both are optional and both should be supplied — without them every artifact resolves
+ * against the process working directory, which is right only by luck.
  */
-function notCoveredBlock(result) {
-  const scope = result.scope ?? {};
-  const items = (scope.notCovered ?? []).map((x) => String(x));
-
-  const ran = new Set(result.dimensionsRun ?? []);
-  if (ran.size > 0) {
-    for (const dimension of Object.keys(DIMENSION_PLAIN)) {
-      if (ran.has(dimension)) continue;
-      // Named with its plain-language meaning: "Data" alone tells a reader who does
-      // not work in QA nothing about what went unchecked.
-      const plain = DIMENSION_PLAIN[dimension];
-      items.push(
-        `${DIMENSION_LABEL[dimension] ?? dimension} was not examined — ` +
-          `${plain[0].toLowerCase()}${plain.slice(1)}`,
-      );
-    }
-  }
-
-  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((c) => c.status === 'blocked');
-  if (blocked.length > 0) {
-    const listed = blocked.map((c) => `${c.id} (${c.title})`).join(', ');
-    items.push(`Could not be run: ${listed}`);
-  }
-
-  if (items.length === 0) return '';
-  const listing = items.map((x) => `<li>${e(x)}</li>`).join('');
-  return (
-    '<h2>Not covered in this run</h2>' +
-    `<div class="card"><div class="card-body"><ul class="clean">${listing}</ul></div></div>`
-  );
-}
-
-/** What the severity labels mean, so nobody has to ask. */
-function legendBlock() {
-  const rows = Object.entries(SEVERITY_MEANING)
-    .map(([key, meaning]) => `<tr><td>${severityBadge(key)}</td><td>${e(meaning)}</td></tr>`)
-    .join('');
-  return (
-    '<div class="card"><table><thead><tr><th>Severity</th><th>What it means</th></tr>' +
-    `</thead><tbody>${rows}</tbody></table></div>`
-  );
-}
-
-/**
- * The run's evidence, listed once with its descriptions.
- *
- * The contract requires this array and the hand-written report reduced it to a line
- * of prose, so a reader could not tell what proof the run actually holds.
- */
-function evidenceIndex(evidence) {
-  if (!evidence || evidence.length === 0) return '';
-  const rows = evidence
-    .map(
-      (item) =>
-        '<tr>' +
-        `<td>${e(EVIDENCE_LABEL[item.type] ?? item.type ?? '')}</td>` +
-        `<td>${e(item.description ?? '')}</td>` +
-        `<td><code>${e(item.source)}</code></td>` +
-        '</tr>',
-    )
-    .join('');
-  return (
-    '<div class="card"><table><thead><tr><th>Kind</th><th>Shows</th>' +
-    `<th>File</th></tr></thead><tbody>${rows}</tbody></table></div>`
-  );
-}
-
-/** Render an explore-result artifact. */
-export function renderExplore(result) {
-  const findings = [...(result.findings ?? [])].sort(
-    (a, b) =>
-      (SEVERITY[a.severity] ?? SEVERITY.low).rank - (SEVERITY[b.severity] ?? SEVERITY.low).rank,
-  );
-  const [verdictLabel, verdictColour, verdictTint] =
-    VERDICT[result.classification] ?? ['Reported', '#4a5568', '#f4f5f7'];
-
-  const metaBits = [];
-  if (result.url) metaBits.push(`<strong>Target</strong> <code>${e(result.url)}</code>`);
-  if (result.generatedAt) metaBits.push(`<strong>Generated</strong> ${e(result.generatedAt)}`);
-  if (result.browserAdapter) metaBits.push(`<strong>Browser</strong> ${e(result.browserAdapter)}`);
-  if (result.reportVersion) metaBits.push(`<strong>Report</strong> v${e(result.reportVersion)}`);
-
-  const body = [
-    '<header class="masthead">',
-    '  <div class="eyebrow">Exploratory QA report</div>',
-    `  <h1>${e(subject(result))}</h1>`,
-    `  <p class="meta">${metaBits.join(' &middot; ')}</p>`,
-    '</header>',
-    `<p class="lead">${e(result.summary ?? '')}</p>`,
-    `<div class="verdict" style="color:${verdictColour};background:${verdictTint}">` +
-      `${e(verdictLabel)}</div>`,
-  ];
-
-  body.push(countsBlock(result.severityCounts ?? {}, ['critical', 'high', 'medium', 'low']));
-
-  const tests = result.testCases ?? {};
-  if (Object.keys(tests).length > 0) {
-    const picked = {};
-    for (const key of ['total', 'passed', 'failed', 'blocked', 'skipped']) {
-      if (key in tests) picked[key] = tests[key];
-    }
-    body.push(countsBlock(picked, ['total', 'passed', 'failed', 'blocked', 'skipped']));
-  }
-
-  // Orientation before detail. A reader who has never seen this product needs to
-  // know what the document is, what was looked at, what was not, and what the
-  // labels mean — before the first finding, not in an appendix.
-  body.push('<h2>About this report</h2>');
-  body.push(orientation(result));
-
-  const scope = scopeBlock(result);
-  if (scope) {
-    body.push('<h2>What was tested</h2>');
-    body.push(scope);
-  }
-
-  const notCovered = notCoveredBlock(result);
-  if (notCovered) body.push(notCovered);
-
-  body.push('<h2>How to read the findings</h2>');
-  body.push(legendBlock());
-
-  body.push('<h2>Findings</h2>');
-  if (findings.length > 0) {
-    body.push(...findings.map((finding) => findingCard(finding)));
-  } else {
-    body.push('<div class="card"><div class="card-body empty">No findings recorded.</div></div>');
-  }
-
-  if ((tests.cases ?? []).length > 0) {
-    body.push('<h2>Test case coverage</h2>');
-    body.push(testCaseTable(tests, new Set(findings.map((f) => f.id))));
-  }
-
-  const db = result.dbValidation ?? {};
-  const dbHeaded = Boolean(db.summary) || db.inScope !== undefined;
-  if (dbHeaded) {
-    body.push('<h2>Data validation</h2>');
-    const note = db.summary || (db.inScope ? 'In scope.' : 'Not in scope for this run.');
-    body.push(`<div class="card"><div class="card-body">${e(note)}</div></div>`);
-  }
-  if (db.comparisons && db.comparisons.length > 0) {
-    if (!dbHeaded) body.push('<h2>Data validation</h2>');
-    const rows = db.comparisons
-      .map(
-        (c) =>
-          '<tr>' +
-          `<td>${e(c.metric)}</td><td><code>${e(c.uiValue)}</code></td>` +
-          `<td><code>${e(c.sourceValue)}</code></td>` +
-          `<td style="color:${c.match ? '#116149' : '#b3261e'};font-weight:600">` +
-          `${c.match ? 'Match' : 'Mismatch'}</td></tr>`,
-      )
-      .join('');
-    body.push(
-      '<div class="card"><table><thead><tr><th>Metric</th><th>Shown in UI</th>' +
-        `<th>Source of truth</th><th>Result</th></tr></thead><tbody>${rows}</tbody></table></div>`,
-    );
-  }
-
-  if (result.fixOrder && result.fixOrder.length > 0) {
-    body.push('<h2>Suggested fix order</h2>');
-    const items = result.fixOrder.map((x) => `<li>${e(x)}</li>`).join('');
-    body.push(`<div class="card"><div class="card-body"><ol class="order">${items}</ol></div></div>`);
-  }
-
-  if (result.recommendations && result.recommendations.length > 0) {
-    body.push('<h2>Recommendations</h2>');
-    const rows = result.recommendations
-      .map((r) => `<tr><td>${e(r.action)}</td><td>${e(r.priority)}</td></tr>`)
-      .join('');
-    body.push(
-      '<div class="card"><table><thead><tr><th>Action</th><th>Priority</th></tr>' +
-        `</thead><tbody>${rows}</tbody></table></div>`,
-    );
-  }
-
-  if (result.whatWorksWell && result.whatWorksWell.length > 0) {
-    body.push('<h2>Verified working</h2>');
-    const items = result.whatWorksWell.map((x) => `<li>${e(x)}</li>`).join('');
-    body.push(`<div class="card"><div class="card-body"><ul class="clean">${items}</ul></div></div>`);
-  }
-
-  if (result.evidence && result.evidence.length > 0) {
-    body.push('<h2>Evidence index</h2>');
-    body.push(evidenceIndex(result.evidence));
-  }
-
-  return body.join('\n');
-}
-
-/** Render a report-result artifact (qa-report's release rollup). */
-export function renderReport(result) {
-  const readiness = result.releaseReadiness ?? {};
-  const verdict = 'verdict' in readiness ? readiness.verdict : result.classification;
-  const [label, colour, tint] = VERDICT[verdict] ?? ['Reported', '#4a5568', '#f4f5f7'];
-  const summaries = result.summaries ?? {};
-
-  const body = [
-    '<header class="masthead">',
-    '  <div class="eyebrow">Release readiness report</div>',
-    `  <h1>${e(subject(result))}</h1>`,
-    `  <p class="meta"><strong>Generated</strong> ${e(result.generatedAt ?? '')}</p>`,
-    '</header>',
-    `<p class="lead">${e(result.summary ?? '')}</p>`,
-    `<div class="verdict" style="color:${colour};background:${tint}">${e(label)}</div>`,
-  ];
-  if (readiness.rationale) {
-    body.push(`<div class="card"><div class="card-body">${e(readiness.rationale)}</div></div>`);
-  }
-
-  const tests = result.testSummary ?? {};
-  const picked = {};
-  for (const key of ['total', 'passed', 'failed', 'skipped']) {
-    if (key in tests) picked[key] = tests[key];
-  }
-  body.push(countsBlock(picked, ['total', 'passed', 'failed', 'skipped']));
-
-  for (const [key, heading] of [
-    ['executive', 'Executive summary'],
-    ['engineering', 'Engineering summary'],
-  ]) {
-    if (summaries[key]) {
-      body.push(`<h2>${heading}</h2>`);
-      body.push(`<div class="card"><div class="card-body">${e(summaries[key])}</div></div>`);
-    }
-  }
-
-  if (result.failureSummary && result.failureSummary.length > 0) {
-    body.push('<h2>Failures</h2>');
-    const rows = result.failureSummary
-      .map(
-        (f) =>
-          `<tr><td>${e(f.test)}</td><td>${e(f.classification)}</td>` +
-          `<td>${e(f.reason)}</td></tr>`,
-      )
-      .join('');
-    body.push(
-      '<div class="card"><table><thead><tr><th>Test</th><th>Classification</th>' +
-        `<th>Reason</th></tr></thead><tbody>${rows}</tbody></table></div>`,
-    );
-  }
-
-  if (result.recommendations && result.recommendations.length > 0) {
-    body.push('<h2>Recommendations</h2>');
-    const rows = result.recommendations
-      .map((r) => `<tr><td>${e(r.action)}</td><td>${e(r.priority)}</td></tr>`)
-      .join('');
-    body.push(
-      '<div class="card"><table><thead><tr><th>Action</th><th>Priority</th></tr>' +
-        `</thead><tbody>${rows}</tbody></table></div>`,
-    );
-  }
-
-  return body.join('\n');
-}
-
-const RENDERERS = {
-  'qa-explore/explore-result': renderExplore,
-  'qa-report/report-result': renderReport,
-};
-
-/** Render a full standalone HTML document for a supported artifact. */
-export function render(result, { title = null } = {}) {
-  const contract = result.contract?.name;
-  const renderer = RENDERERS[contract];
-  if (!renderer) {
-    throw new ReportError(
-      `no HTML renderer for contract ${contract === undefined ? 'None' : `'${contract}'`}; supported: ` +
-        Object.keys(RENDERERS).sort().join(', '),
-    );
-  }
-
-  const heading = title ?? `QA report — ${subject(result)}`;
-  return (
-    '<!DOCTYPE html>\n' +
-    '<html lang="en">\n<head>\n' +
-    '<meta charset="utf-8"/>\n' +
-    '<meta name="viewport" content="width=device-width,initial-scale=1"/>\n' +
-    `<title>${e(heading)}</title>\n` +
-    `<style>${CSS}</style>\n` +
-    '</head>\n<body>\n' +
-    '<div class="page">\n' +
-    `${renderer(result)}\n` +
-    // Attribution is part of the document, not an optional flourish.
-    `${footerHtml()}` +
-    '</div>\n</body>\n</html>\n'
-  );
+export function render(result, options = {}) {
+  return renderDocument(result, options);
 }
 
 /** Read an artifact from disk and render it. */
-export function renderFile(path, { title = null } = {}) {
+export function renderFile(file, options = {}) {
   let result;
   try {
-    result = JSON.parse(fs.readFileSync(path, 'utf8'));
+    result = JSON.parse(fs.readFileSync(file, 'utf8'));
   } catch (error) {
-    throw new ReportError(`could not read artifact at ${path}: ${error.message}`);
+    throw new ReportError(`could not read artifact at ${file}: ${error.message}`);
   }
   if (result === null || typeof result !== 'object' || Array.isArray(result)) {
-    throw new ReportError(`artifact at ${path} is not a JSON object`);
+    throw new ReportError(`artifact at ${file} is not a JSON object`);
   }
-  return render(result, { title });
-}
-
-export function supportedContracts() {
-  return Object.keys(RENDERERS).sort();
+  return renderDocument(result, {
+    ...options,
+    resultPath: path.resolve(file),
+    outPath: options.outPath ?? null,
+  });
 }