ultra11y 2.22.0

package/src/report.ts

@@ -0,0 +1,399 @@
+// `report` — render an AuditResult into a dated compliance report (Markdown). The
+// CANONICAL, gated report is WCAG 2.2 Level AA (renderReport). A country standards
+// pack (RGAA, …) gets a DERIVED report (renderPackReport) projected from the same
+// WCAG-keyed result. Both keep the honest structure: per-guideline/theme synthesis,
+// non-conformities, conforming + not-applicable lists, and the manual worklist
+// (never silently C).
+import { mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import type { AuditResult, Finding, Lang, Severity, Status } from "./types.js";
+import { guidelineTitle, scTitle } from "./wcag.js";
+import { prdUnits, partitionUnits } from "./prd.js";
+import { renderAuditorUnit } from "./auditor.js";
+import { resolveMessage } from "./messages.js";
+import {
+  type StandardId,
+  CORE,
+  isCore,
+  loadPack,
+  derivePackResults,
+  packCriteriaForFinding,
+  packConformancePct,
+  title as packTitle,
+  themeName,
+  type StandardPack,
+} from "./standards/index.js";
+
+const ICON: Record<Severity, string> = { bloquant: "🔴", majeur: "🟠", mineur: "🟡" };
+const SEV_ORDER: Severity[] = ["bloquant", "majeur", "mineur"];
+
+const L = {
+  fr: {
+    title: (std: string) => `Rapport d'audit d'accessibilité — ${std}`,
+    wcagStd: "WCAG 2.2 niveau AA",
+    date: "Date",
+    tool: "Outil",
+    toolNote: "moteur statique — audit préliminaire, critères de jugement à adjuger par l'agent IA (statique, gaté), rendu via `scan`",
+    scope: "Périmètre",
+    files: "fichier(s)",
+    rate: "Taux de réussite automatique (vérifications statiques)",
+    rateNote: "sous-ensemble décidable par la machine : C ÷ (C + NC)",
+    warn: "Ce rapport couvre le sous-ensemble de critères vérifiables automatiquement. Les critères « à évaluer » (rendu / jugement) sont adjugés par l'agent IA (`verify --manual`, de façon gatée) ; le rendu passe par `scan` (voir la dernière section).",
+    derived: (std: string) =>
+      `Vue dérivée du ${std} : projection des critères de succès WCAG audités sur le référentiel. La vérification d'intégrité (\`check\`/\`verify\`) opère sur le rapport WCAG canonique.`,
+    synthTitle: (by: string) => `1. Synthèse par ${by}`,
+    byGuideline: "règle WCAG",
+    byTheme: "thématique",
+    th: (head: string) => [head, "C", "NC", "NA", "À évaluer"],
+    total: "Total",
+    ncTitle: "2. Non-conformités (par priorité)",
+    recTitle: "Recommandations (non normatives)",
+    recNote:
+      "Bonnes pratiques SANS test normatif du référentiel actif — ce ne sont PAS des non-conformités et elles n'entrent pas dans le taux de réussite. Libre à l'équipe de les suivre.",
+    sev: { bloquant: "Bloquant", majeur: "Majeur", mineur: "Mineur" } as Record<Severity, string>,
+    none: "Aucune non-conformité détectée par le moteur statique.",
+    cTitle: "3. Critères conformes (C)",
+    naTitle: "4. Critères non applicables (NA)",
+    manualTitle: "5. Critères à adjuger (jugement / rendu) — non décidés par le moteur statique",
+    manualWarn:
+      "Adjugez-les avec `verify --manual` (l'agent décide depuis la source, de façon gatée) ; les critères de rendu passent par `scan`. Aucun ne doit être marqué « conforme » sans justification enregistrée et gatée.",
+    outOfScope: "Hors périmètre moteur — mappé sur des SC hors WCAG 2.2 AA ; vérification manuelle.",
+    scopedOut: "Les non-conformités WCAG relevées concernent des éléments hors du périmètre de ce critère — à évaluer séparément.",
+    nothing: "Aucun.",
+    dedup: "Dédup",
+    canonical: "fichier(s) canonique(s) audité(s)",
+    duplicate: "doublon(s) identique(s) ignoré(s)",
+    truncated: (l: number, t: number, s: number) =>
+      `Périmètre tronqué : ${l}/${t} fichiers audités (priorité d'abord), ${s} ignoré(s). Élargir avec --max-files.`,
+    rendered: (n: number, libs: string) =>
+      `Verdict source préliminaire : ${n} fichier(s) rendent des composants de bibliothèque (${libs}) dont le HTML produit n'est pas visible en analyse statique. Auditez la sortie de build (\`render\` / \`audit <dist>\`) ou \`scan\` avant de conclure.`,
+    sourceTemplate: (n: number, exts: string) =>
+      `Verdict source préliminaire : ${n} composant(s) ${exts} audité(s) en SOURCE (template). Les slots, snippets et liaisons dynamiques (:attr, {@render}) sont invisibles en analyse statique — auditez le rendu (\`render\` / \`scan\`) avant de conclure.`,
+    captures: (n: number) => `${n} fichier(s) de capture rendus audités à pleine fidélité (DOM réel) — le vrai HTML produit, pas l'appel de composant.`,
+    blindSpots: (n: number) =>
+      `${n} composant(s) sans capture rendue (angles morts) — audités sur source opaque uniquement ; auditez leur DOM rendu (\`render --setup\`).`,
+    // Task 5 — partial-audit advisory (owner decision: scan stays opt-in but strongly advised).
+    // The list names ONLY the needs-rendering criteria still untested (real coverage).
+    partialAudit: (list: string) =>
+      `Audit partiel — les critères « à restituer » (${list}) n'ont pas été testés. Lancez \`ultra11y scan --sample\` (Playwright + axe + sondes) sur l'échantillon, puis fusionnez avec \`scan --merge\`.`,
+    // Task 5 — « Constats par page » (Ara-style per-sample-page synthesis).
+    perPageTitle: "Constats par page",
+    perPageNote: "Constats regroupés par page de l'échantillon audité (rendu dynamique).",
+    transverseNote: (list: string) => `Éléments transverses audités sur chaque page : ${list}.`,
+    authYes: "🔒 authentification requise",
+    authNo: "🌐 public",
+    ncCount: "non-conformité(s)",
+    advCount: "recommandation(s)",
+  },
+  en: {
+    title: (std: string) => `Accessibility audit report — ${std}`,
+    wcagStd: "WCAG 2.2 Level AA",
+    date: "Date",
+    tool: "Tool",
+    toolNote: "static engine — preliminary audit; judgment criteria adjudicated by the AI agent (statically, gated), rendering via `scan`",
+    scope: "Scope",
+    files: "file(s)",
+    rate: "Automatic static-check pass rate",
+    rateNote: "machine-decidable subset: C ÷ (C + NC)",
+    warn: "This report covers the subset of criteria checkable automatically. The “to assess” criteria (rendering / judgment) are adjudicated by the AI agent (`verify --manual`, gated); rendering goes through `scan` (see the last section).",
+    derived: (std: string) =>
+      `Derived view of ${std}: the audited WCAG success criteria projected onto this standard. The integrity gates (\`check\`/\`verify\`) operate on the canonical WCAG report.`,
+    synthTitle: (by: string) => `1. Synthesis by ${by}`,
+    byGuideline: "WCAG guideline",
+    byTheme: "theme",
+    th: (head: string) => [head, "C", "NC", "NA", "To assess"],
+    total: "Total",
+    ncTitle: "2. Non-conformities (by priority)",
+    recTitle: "Recommendations (non-normative)",
+    recNote:
+      "Good practices with NO normative test of the active standard — these are NOT non-conformities and do not enter the pass rate. The team may adopt them at will.",
+    sev: { bloquant: "Blocking", majeur: "Major", mineur: "Minor" } as Record<Severity, string>,
+    none: "No non-conformity detected by the static engine.",
+    cTitle: "3. Conforming criteria (C)",
+    naTitle: "4. Not-applicable criteria (NA)",
+    manualTitle: "5. Criteria to adjudicate (judgment / rendering) — not decided by the static engine",
+    manualWarn:
+      "Adjudicate these with `verify --manual` (the agent decides from source, gated); rendering criteria go to `scan`. None may be marked “conforming” without a recorded, gated justification.",
+    outOfScope: "Out of engine scope — mapped to SCs outside WCAG 2.2 AA; manual verification.",
+    scopedOut: "The WCAG failures found concern elements outside this criterion's scope — assess separately.",
+    nothing: "None.",
+    dedup: "Dedup",
+    canonical: "canonical file(s) audited",
+    duplicate: "identical duplicate(s) skipped",
+    truncated: (l: number, t: number, s: number) => `Scope truncated: ${l}/${t} files audited (highest-priority first), ${s} skipped. Widen with --max-files.`,
+    rendered: (n: number, libs: string) =>
+      `Preliminary source verdict: ${n} file(s) render component-library components (${libs}) whose produced HTML is invisible to static analysis. Audit the build output (\`render\` / \`audit <dist>\`) or \`scan\` before concluding.`,
+    sourceTemplate: (n: number, exts: string) =>
+      `Preliminary source verdict: ${n} ${exts} component(s) audited as SOURCE (template). Slots, snippets and dynamic bindings (:attr, {@render}) are invisible to static analysis — audit the rendered output (\`render\` / \`scan\`) before concluding.`,
+    captures: (n: number) => `${n} rendered capture file(s) audited at full fidelity (real DOM) — the true produced HTML, not the component call.`,
+    blindSpots: (n: number) =>
+      `${n} component(s) without a rendered capture (blind spots) — audited from opaque source only; audit their rendered DOM (\`render --setup\`).`,
+    // Task 5 — partial-audit advisory (owner decision: scan stays opt-in but strongly advised).
+    // The list names ONLY the needs-rendering criteria still untested (real coverage).
+    partialAudit: (list: string) =>
+      `Partial audit — the needs-rendering criteria (${list}) were not tested. Run \`ultra11y scan --sample\` (Playwright + axe + probes) on the sample, then merge with \`scan --merge\`.`,
+    // Task 5 — « Findings per page » (Ara-style per-sample-page synthesis).
+    perPageTitle: "Findings per page",
+    perPageNote: "Findings grouped by the audited sample page (dynamic rendering).",
+    transverseNote: (list: string) => `Transverse elements audited on every page: ${list}.`,
+    authYes: "🔒 authentication required",
+    authNo: "🌐 public",
+    ncCount: "non-conformity(ies)",
+    advCount: "recommendation(s)",
+  },
+} as const;
+
+// The needs-rendering criteria the scan tier decides, with the labels the partial-audit
+// banner names them by. Coverage comes from scope.scan.testedScs (stamped by mergeDynamic:
+// Docker measures 1.4.10 only; the local runtime adds zoom / spacing / focus / hover, and
+// live regions when interactions are on) — so the banner only ever names criteria that
+// genuinely lack a dynamic verdict, and drops only when every one of them is covered.
+const NEEDS_RENDERING: readonly { sc: string; label: Record<Lang, string> }[] = [
+  { sc: "1.4.4", label: { fr: "zoom 200 %", en: "200% zoom" } },
+  { sc: "1.4.10", label: { fr: "reflow 320 px", en: "320px reflow" } },
+  { sc: "1.4.12", label: { fr: "espacement du texte", en: "text spacing" } },
+  { sc: "2.4.7", label: { fr: "visibilité du focus", en: "focus visibility" } },
+  { sc: "1.4.13", label: { fr: "contenu au survol", en: "content on hover" } },
+  { sc: "4.1.3", label: { fr: "régions live", en: "live regions" } },
+];
+
+/** The scan-tier needs-rendering SCs this audit has NO dynamic verdict for. Coverage =
+ *  scope.scan.testedScs (the merge-time stamp); back-compat: a dyn-* probe finding proves
+ *  its SC was measured even on an audit merged before the stamp existed. Non-empty ⇒ the
+ *  partial-audit advisory shows, naming exactly these criteria. */
+export function untestedNeedsRendering(r: AuditResult): string[] {
+  const tested = new Set(r.scope.scan?.testedScs ?? []);
+  for (const f of r.findings) if (f.ruleId.startsWith("dyn-")) tested.add(f.criteriaId);
+  return NEEDS_RENDERING.filter((c) => !tested.has(c.sc)).map((c) => c.sc);
+}
+
+/** The partial-audit advisory text (no leading `> `) — shared by the report banner and the
+ *  CLI warning (src/cli.ts cmdReport) so the two can never drift. Names ONLY the criteria
+ *  in `untested` (default: all of them — the no-scan-at-all case). */
+export function partialAuditBanner(lang: Lang, untested: string[] = NEEDS_RENDERING.map((c) => c.sc)): string {
+  const set = new Set(untested);
+  const labels = NEEDS_RENDERING.filter((c) => set.has(c.sc)).map((c) => c.label[lang]);
+  return L[lang].partialAudit(labels.join(", "));
+}
+
+// A normalized row the renderer is agnostic about: one labelled criterion + its status/findings.
+interface Row {
+  id: string;
+  label: string; // "1.4.3 — Contrast (Minimum)" or "RGAA 1.1 — …"
+  status: Status;
+  findings: Finding[];
+  justification?: string;
+}
+
+interface Group {
+  key: string;
+  title: string;
+  rows: Row[];
+}
+
+// Shared renderer over normalized groups/rows — keeps the WCAG and pack reports identical
+// in shape. `groupHead` labels the synthesis column ("WCAG guideline" / "theme"). `standard`
+// drives the NC section below (`prdUnits`/`renderAuditorUnit` are standard-aware).
+function render(
+  r: AuditResult,
+  lang: Lang,
+  opts: {
+    std: string;
+    groupHead: string;
+    groups: Group[];
+    standard: StandardId;
+    derivedOf?: string;
+    partialAudit?: string[];
+    headerRatePct?: number;
+  },
+): string {
+  const s = L[lang];
+  const out: string[] = [];
+  out.push(`# ${s.title(opts.std)}`, "");
+  out.push(`- **${s.date}** : ${r.date}`);
+  out.push(`- **${s.tool}** : ultra11y v${r.version} (${s.toolNote})`);
+  out.push(`- **${s.scope}** : ${r.scope.files} ${s.files} — ${r.scope.inputs.join(", ")}`);
+  out.push(`- **${s.rate}** : ${opts.headerRatePct ?? r.conformancePct}% (${s.rateNote})`);
+  if (r.scope.dedup) out.push(`- **${s.dedup}** : ${r.scope.dedup.canonicalFiles} ${s.canonical}, ${r.scope.dedup.duplicateFiles} ${s.duplicate}`);
+  out.push("", `> ⚠️ ${s.warn}`, "");
+  // Partial-audit advisory banner (owner decision) — a pack audit whose scan coverage
+  // leaves needs-rendering criteria untested. Names EXACTLY the untested ones (a Docker
+  // run — reflow only — keeps the banner for the local-only probes it never ran). Placed
+  // in the header, before the derived-view note. Labels only — no criterion-shaped token,
+  // so the `check` structural gate accepts it.
+  if (opts.partialAudit?.length) out.push(`> 🚨 ${partialAuditBanner(lang, opts.partialAudit)}`, "");
+  if (opts.derivedOf) out.push(`> ↪️ ${s.derived(opts.derivedOf)}`, "");
+  if (r.scope.truncated) out.push(`> ✂️ ${s.truncated(r.scope.truncated.limit, r.scope.truncated.total, r.scope.truncated.skipped)}`, "");
+  if (r.scope.rendered) out.push(`> 🧩 ${s.rendered(r.scope.rendered.files, r.scope.rendered.opaqueLibraries.join(", "))}`, "");
+  if (r.scope.sourceTemplate) out.push(`> 🧩 ${s.sourceTemplate(r.scope.sourceTemplate.files, r.scope.sourceTemplate.extensions.join(", "))}`, "");
+  if (r.scope.captures) out.push(`> ✅ ${s.captures(r.scope.captures.files)}`, "");
+  if (r.scope.captureCoverage?.blindSpots.length) out.push(`> ⚠️ ${s.blindSpots(r.scope.captureCoverage.blindSpots.length)}`, "");
+
+  const rows = opts.groups.flatMap((g) => g.rows);
+
+  // 1. synthesis
+  const th = s.th(opts.groupHead);
+  out.push(`## ${s.synthTitle(opts.groupHead)}`, "");
+  out.push(`| ${th.join(" | ")} |`);
+  out.push(`|${"---|".repeat(th.length)}`);
+  const tot = { c: 0, nc: 0, na: 0, manual: 0 };
+  for (const g of opts.groups) {
+    const c = g.rows.filter((x) => x.status === "C").length;
+    const nc = g.rows.filter((x) => x.status === "NC").length;
+    const na = g.rows.filter((x) => x.status === "NA").length;
+    const manual = g.rows.filter((x) => x.status === "manual").length;
+    out.push(`| ${g.key} ${g.title} | ${c} | ${nc} | ${na} | ${manual} |`);
+    tot.c += c;
+    tot.nc += nc;
+    tot.na += na;
+    tot.manual += manual;
+  }
+  out.push(`| **${s.total}** | **${tot.c}** | **${tot.nc}** | **${tot.na}** | **${tot.manual}** |`, "");
+
+  // 2. non-conformities by priority — one auditor block per NC criterion (core or
+  // pack), the SAME human language `prd`/GitHub issues use (src/auditor.ts
+  // `renderAuditorUnit`), grouped by severity like `renderAuditorBacklog`. Reuses
+  // `prdUnits` so a criterion here is EXACTLY a `prd`/`gh` backlog item — no
+  // report-local re-grouping logic, and the two stay impossible to drift apart.
+  out.push(`## ${s.ncTitle}`, "");
+  const { nc: ncUnits, advisory: advisoryUnits } = partitionUnits(prdUnits(r, opts.standard, lang));
+  if (ncUnits.length === 0) {
+    out.push(s.none, "");
+  } else {
+    for (const sev of SEV_ORDER) {
+      const group = ncUnits.filter((u) => u.severity === sev);
+      if (!group.length) continue;
+      out.push(`### ${ICON[sev]} ${s.sev[sev]} (${group.length})`, "");
+      for (const u of group) out.push(...renderAuditorUnit(u, opts.standard, lang, { heading: "####" }));
+    }
+  }
+
+  // Recommendations (non-normative) — advisory units, AFTER the non-conformities and
+  // BEFORE the numbered §3. An UNNUMBERED heading so the 1–5 section numbering `check`
+  // requires stays intact, and so the advisory blocks sit outside §2 (packReportNcIds /
+  // the NC over-under-projection gate never see them). Only emitted when present.
+  if (advisoryUnits.length) {
+    out.push(`## 💡 ${s.recTitle}`, "", `> ${s.recNote}`, "");
+    for (const u of advisoryUnits) out.push(...renderAuditorUnit(u, opts.standard, lang, { heading: "###" }));
+  }
+
+  // « Constats par page » — Ara-style per-sample-page synthesis (name + URL + auth badge +
+  // NC/advisory counts, then the page's findings). Only when a page sample was recorded
+  // (scan --sample merged in). UNNUMBERED heading so the 1–5 section numbering `check`
+  // requires stays intact and the packReportNcIds parser (section 2) never sees it.
+  if (r.scope.sample?.pages.length) {
+    out.push(`## 📄 ${s.perPageTitle}`, "", `> ${s.perPageNote}`, "");
+    if (r.scope.sample.transverse?.length) out.push(`> ${s.transverseNote(r.scope.sample.transverse.join(", "))}`, "");
+    // Standard-aware per-finding label: a pack report (RGAA, …) speaks its own criteria
+    // everywhere else, so this per-page line should too, rather than the raw WCAG SC id.
+    // `loadPack` once, outside the finding loop — never per-finding.
+    const pack = isCore(opts.standard) ? undefined : loadPack(opts.standard);
+    for (const pg of r.scope.sample.pages) {
+      const onPage = r.findings.filter((f) => f.file === pg.url || (f.sample?.page !== undefined && f.sample.page === pg.name));
+      const nc = onPage.filter((f) => !f.advisory);
+      const adv = onPage.filter((f) => f.advisory);
+      out.push(`### ${pg.name} — \`${pg.url}\` — ${pg.auth ? s.authYes : s.authNo}`, "");
+      out.push(`- ${nc.length} ${s.ncCount}${adv.length ? ` · ${adv.length} ${s.advCount}` : ""}`);
+      if (pg.notes) out.push(`- _${pg.notes}_`);
+      for (const f of nc.slice(0, 30)) {
+        const crits = pack ? packCriteriaForFinding(pack, f) : [];
+        const label = crits.length ? crits.join(", ") : f.criteriaId; // graceful fallback to the WCAG SC
+        out.push(`  - [${label}] \`${f.selectorHint}\` — ${resolveMessage(f, lang)}`);
+      }
+      out.push("");
+    }
+  }
+
+  // 3. conforming
+  out.push(`## ${s.cTitle}`, "");
+  const conform = rows.filter((x) => x.status === "C");
+  out.push(conform.length ? conform.map((x) => `- ${x.label}`).join("\n") : s.nothing, "");
+
+  // 4. not applicable
+  out.push(`## ${s.naTitle}`, "");
+  const na = rows.filter((x) => x.status === "NA");
+  out.push(na.length ? na.map((x) => `- ${x.label}${x.justification ? ` — _${x.justification}_` : ""}`).join("\n") : s.nothing, "");
+
+  // 5. manual worklist
+  out.push(`## ${s.manualTitle}`, "", `> ${s.manualWarn}`, "");
+  const manual = rows.filter((x) => x.status === "manual");
+  out.push(manual.length ? manual.map((x) => `- ${x.label}${x.justification ? ` — _${x.justification}_` : ""}`).join("\n") : s.nothing, "");
+
+  return out.join("\n");
+}
+
+/** The canonical, gated WCAG 2.2 AA report. */
+export function renderReport(r: AuditResult, lang: Lang = "en"): string {
+  const s = L[lang];
+  const byGuideline = new Map<string, Row[]>();
+  for (const c of r.criteria) {
+    const title = scTitle(c.id, lang);
+    const row: Row = { id: c.id, label: title ? `${c.id} — ${title}` : c.id, status: c.status, findings: c.findings, justification: c.justification };
+    (byGuideline.get(c.guideline) ?? byGuideline.set(c.guideline, []).get(c.guideline)!).push(row);
+  }
+  // `g.title` on the AuditResult's GuidelineTally is the baked-in English title (kept for
+  // JSON back-compat); resolve the localized label from the guideline KEY instead so
+  // `--lang fr` renders the French guideline name here too.
+  const groups: Group[] = r.guidelines.map((g) => ({ key: g.key, title: guidelineTitle(g.key, lang) ?? g.title, rows: byGuideline.get(g.key) ?? [] }));
+  return render(r, lang, { std: s.wcagStd, groupHead: s.byGuideline, groups, standard: CORE });
+}
+
+/** A derived report for a country standards pack (RGAA, …), projected from the WCAG audit. */
+export function renderPackReport(r: AuditResult, pack: StandardPack, lang: Lang = "en"): string {
+  const derived = derivePackResults(r, pack.key);
+  const std = `${pack.name} ${pack.baseVersion}`;
+  const s = L[lang];
+  const naReason =
+    lang === "fr" ? "Aucun critère de succès WCAG mappé n'est applicable dans le périmètre." : "No mapped WCAG success criterion is applicable in scope.";
+  const byTheme = new Map<number, Row[]>();
+  for (const pr of derived) {
+    const pc = pack.criteria.find((c) => c.id === pr.id)!;
+    const row: Row = {
+      id: pr.id,
+      label: `${pack.name} ${pr.id} — ${packTitle(pack, pc, lang)}`,
+      status: pr.status,
+      findings: pr.findings,
+      // outOfScope / scopedOut criteria are "manual" (not NA) with their own dedicated
+      // justification — never mixed with the ordinary NA reason (see the manual section above).
+      ...(pr.outOfScope
+        ? { justification: s.outOfScope }
+        : pr.scopedOut
+          ? { justification: s.scopedOut }
+          : pr.status === "NA"
+            ? { justification: naReason }
+            : {}),
+    };
+    (byTheme.get(pr.theme) ?? byTheme.set(pr.theme, []).get(pr.theme)!).push(row);
+  }
+  const groups: Group[] = pack.themes.map((t) => ({ key: `${t.number}.`, title: themeName(pack, t.number, lang) ?? "", rows: byTheme.get(t.number) ?? [] }));
+  // Owner decision: a pack (RGAA) report is flagged PARTIAL while any needs-rendering
+  // criterion lacks a dynamic verdict — the banner names exactly which ones (a Docker-only
+  // scan covers reflow but not the local probes). The core WCAG report carries its own §5
+  // manual worklist and is not flagged here.
+  return render(r, lang, {
+    std,
+    groupHead: L[lang].byTheme,
+    groups,
+    derivedOf: std,
+    standard: pack.key,
+    partialAudit: untestedNeedsRendering(r),
+    headerRatePct: packConformancePct(derived),
+  });
+}
+
+export interface ReportOpts {
+  out: string;
+  lang: Lang;
+  standard: StandardId;
+}
+
+/** Render and write the report; returns the written path. The WCAG report is canonical
+ *  (`wcag-<date>.md`); a pack report is a derived `<pack>-<date>.md`. */
+export function writeReport(r: AuditResult, opts: ReportOpts): string {
+  const core = isCore(opts.standard);
+  const md = core ? renderReport(r, opts.lang) : renderPackReport(r, loadPack(opts.standard), opts.lang);
+  mkdirSync(opts.out, { recursive: true });
+  const path = join(opts.out, `${core ? "wcag" : opts.standard}-${r.date}.md`);
+  writeFileSync(path, md);
+  return path;
+}

package/src/rules/colors.ts

@@ -0,0 +1,125 @@
+// Theme 3 — Colours. Computed contrast (3.2/3.3) generally needs rendering, but the
+// slice an author writes with LITERAL inline colours is decidable from the markup
+// alone: text colour vs the nearest painted background, both resolved to opaque
+// literals. Anything non-literal (var(), currentColor, external CSS, translucent)
+// is left untouched so 3.2 stays a residual risk rather than a false non-conformity.
+import type { Doc, El } from "../parse/html.js";
+import { attr } from "../parse/html.js";
+import type { Rule, RuleFinding } from "./rule.js";
+import { parseColor, parseInlineStyle, contrastRatio, type RGBA } from "../color.js";
+
+const SKIP_TAGS = new Set(["script", "style", "head", "title", "meta", "noscript", "link"]);
+
+function styleOf(el: El): Map<string, string> {
+  const s = attr(el, "style");
+  return s ? parseInlineStyle(s) : new Map();
+}
+
+/** First colour literal in a declaration value (handles the `background` shorthand). */
+function colorFromValue(v: string): RGBA | null {
+  const whole = parseColor(v);
+  if (whole) return whole;
+  for (const tok of v.split(/\s+/)) {
+    const c = parseColor(tok);
+    if (c) return c;
+  }
+  return null;
+}
+
+/** Foreground: nearest self-or-ancestor inline `color` (colour inherits). */
+function fgOf(el: El): RGBA | null {
+  for (let p: El | null = el; p; p = p.parent) {
+    const v = styleOf(p).get("color");
+    if (v) {
+      const c = colorFromValue(v);
+      if (c) return c;
+    }
+  }
+  return null;
+}
+
+/** Background: nearest self-or-ancestor inline solid background. Background does not
+ *  inherit, but text visually sits on the nearest painted ancestor. */
+function bgOf(el: El): RGBA | null {
+  for (let p: El | null = el; p; p = p.parent) {
+    const st = styleOf(p);
+    const v = st.get("background-color") ?? st.get("background");
+    if (v) {
+      const c = colorFromValue(v);
+      if (c) return c;
+    }
+  }
+  return null;
+}
+
+// Resolved px of the nearest declared font-size. Distinguishes three cases:
+//   number      — resolvable (px/pt and the 16px-root approximation for rem/em/%)
+//   "unknown"   — a font-size IS declared but in a unit we can't resolve statically
+//                 (vw/vh/calc()/clamp()…); the size could be large, so we must not
+//                 assume "normal" and apply the strict 4.5 threshold (that FP'd `200%`).
+//   null        — no font-size anywhere → browser default 16px → normal text.
+function fontPx(el: El): number | "unknown" | null {
+  for (let p: El | null = el; p; p = p.parent) {
+    const v = styleOf(p).get("font-size");
+    if (!v) continue;
+    const m = /^([\d.]+)(px|pt|rem|em|%)?$/.exec(v.trim());
+    if (!m) return "unknown"; // declared but unresolvable (vw, calc(), clamp(), …)
+    const n = parseFloat(m[1]!);
+    if (Number.isNaN(n)) return "unknown";
+    const unit = m[2] ?? "px";
+    if (unit === "pt") return (n * 4) / 3;
+    if (unit === "rem" || unit === "em") return n * 16;
+    if (unit === "%") return (n / 100) * 16;
+    return n;
+  }
+  return null;
+}
+
+function isBold(el: El): boolean {
+  for (let p: El | null = el; p; p = p.parent) {
+    const v = styleOf(p).get("font-weight");
+    if (v) return v === "bold" || Number(v) >= 700;
+  }
+  return false;
+}
+
+/** WCAG 1.4.3's "large scale text": ≥ 24px (18pt) regular, or ≥ 18.66px (14pt) bold —
+ *  the exact 14pt-bold cutoff, not the commonly-rounded 18.5px. */
+function isLarge(el: El): boolean {
+  const px = fontPx(el);
+  if (px === null) return false; // no font-size → 16px default → normal
+  if (px === "unknown") return true; // size undeterminable → treat as large (3:1) to avoid inventing an NC
+  return px >= 24 || (px >= 18.66 && isBold(el));
+}
+
+function hasDirectText(el: El): boolean {
+  return el.children.some((c) => c.type === "text" && c.data.trim() !== "");
+}
+
+const contrastLiteral: Rule = {
+  id: "contrast-literal",
+  criteria: ["1.4.3"],
+  severity: "majeur",
+  run(doc: Doc): RuleFinding[] {
+    const out: RuleFinding[] = [];
+    for (const el of doc.elements) {
+      if (SKIP_TAGS.has(el.tag) || !hasDirectText(el)) continue;
+      const fg = fgOf(el);
+      const bg = bgOf(el);
+      if (!fg || !bg || fg.a < 1 || bg.a < 1) continue; // need two opaque literals
+      const ratio = contrastRatio(fg, bg);
+      const large = isLarge(el);
+      const min = large ? 3 : 4.5;
+      if (ratio >= min) continue;
+      out.push({
+        criteriaId: "1.4.3",
+        el,
+        msgId: "contrast-literal",
+        params: { ratio: ratio.toFixed(2), min, textSize: large ? "large" : "normal" },
+      });
+    }
+    return out;
+  },
+};
+
+export const colorsRules: Rule[] = [contrastLiteral];