ultra11y 4.0.1 → 4.2.0

package/src/annotate.ts

@@ -4,18 +4,25 @@
 //    renders these inline on the diff, so this is the fallback when SARIF upload is
 //    unavailable (a private repo without Advanced Security).
 //  • `stepSummary()` — the Markdown written to `$GITHUB_STEP_SUMMARY`: the run's headline,
-//    a severity table, and — once the audit carries a page sample — the per-page synthesis.
+//    a grouped severity table, and — once the audit carries a page sample — the per-page
+//    synthesis. Long and complete; the step summary has a 1 MiB budget and no reader who
+//    reached it arrived by accident.
+//  • `prComment()` — the DIGEST posted on the pull request. A different document, not a
+//    truncation of the one above: a reviewer scanning a PR needs the verdict, the coverage
+//    and the handful of distinct defects, then a link. Posting the full summary there is how
+//    a real audit (472 findings over 7 distinct selectors) became a wall nobody read.
 //
-// Both are pure string builders. Nothing here decides anything: a finding that is not
+// All are pure string builders. Nothing here decides anything: a finding that is not
 // anchorable in the repo tree (a URL-keyed dynamic result) is skipped rather than pinned
-// to an invented line.
+// to an invented line, and every status comes from the shared projections.
 import { findingsAtOrAbove } from "./baseline.js";
 import { resolveMessage, resolveRemediation } from "./messages.js";
 import { findingsForStandard, packCriteriaForFinding } from "./standards/derive.js";
 import { CORE, type StandardId, isCore, loadPack } from "./standards/index.js";
+import { packReportGroups, reportCoverage, reportGroups } from "./report.js";
 import type { AuditResult, Finding, Lang, Severity } from "./types.js";
 import { isUrlPath, repoRelative } from "./util.js";
-import { attributePages, basisLabel, derivePages, formatRate, pageBasisWarning, pagesOf, unattributedFindings } from "./pages.js";
+import { agentMarkNote, attributePages, basisLabel, derivePages, formatRate, pageBasisWarning, pagesOf, unattributedFindings } from "./pages.js";
 
 export interface AnnotateOptions {
   standard?: StandardId;
@@ -81,6 +88,7 @@ const S = {
     where: "Emplacement",
     what: "Constat",
     more: (n: number) => `… et ${n} autre(s).`,
+    moreGroups: (n: number) => `… et ${n} autre(s) groupe(s) — voir le résumé de job.`,
     perPage: "Bilan page par page",
     page: "Page",
     count: "Constats",
@@ -88,6 +96,17 @@ const S = {
     pageRate: "Taux",
     snapshot: "instantané",
     source: "source",
+    occurrences: "Occ.",
+    pagesCol: "Pages",
+    grouped: (groups: number, occ: number) => `${groups} défaut(s) distinct(s) · ${occ} occurrence(s)`,
+    groupNote:
+      "Une ligne par (critère, règle, sélecteur) : un même défaut de design system répété sur toutes les routes compte pour un. Les colonnes Occ. et Pages disent l'ampleur réelle.",
+    verdictFail: (n: number) => `🔴 ${n} non-conformité(s) bloquante(s) — la porte est rouge.`,
+    verdictWarn: "🟠 Aucune non-conformité bloquante ; des constats majeurs ou mineurs restent à traiter.",
+    verdictPass: "✅ Aucune non-conformité relevée par le moteur statique.",
+    artifact: (name: string) => `Rapport complet (HTML, captures annotées) : artefact **${name}** du run.`,
+    runLink: (url: string) => `[Voir le run et son résumé de job](${url})`,
+    clamped: (n: number) => `_${n} groupe(s) retiré(s) de ce commentaire pour tenir dans la limite de GitHub — le résumé de job les porte tous._`,
     unanchored: (n: number) => `${n} constat(s) rattaché(s) à une URL, sans ligne de code à annoter — voir le rapport.`,
     unattributed: (n: number) =>
       `${n} constat(s) ne sont rattachés à aucune page (code partagé, fichier hors routes) — comptés dans l'audit global, jamais répartis d'office.`,
@@ -105,6 +124,7 @@ const S = {
     where: "Location",
     what: "Finding",
     more: (n: number) => `… and ${n} more.`,
+    moreGroups: (n: number) => `… and ${n} more group(s) — see the job summary.`,
     perPage: "Page-by-page scoreboard",
     page: "Page",
     count: "Findings",
@@ -112,6 +132,17 @@ const S = {
     pageRate: "Rate",
     snapshot: "snapshot",
     source: "source",
+    occurrences: "Occ.",
+    pagesCol: "Pages",
+    grouped: (groups: number, occ: number) => `${groups} distinct defect(s) · ${occ} occurrence(s)`,
+    groupNote:
+      "One row per (criterion, rule, selector): one design-system defect repeated across every route counts once. The Occ. and Pages columns carry the real scale.",
+    verdictFail: (n: number) => `🔴 ${n} blocking non-conformity(ies) — the gate is red.`,
+    verdictWarn: "🟠 No blocking non-conformity; major or minor findings remain.",
+    verdictPass: "✅ No non-conformity found by the static engine.",
+    artifact: (name: string) => `Full report (HTML, annotated crops): artifact **${name}** of this run.`,
+    runLink: (url: string) => `[See the run and its job summary](${url})`,
+    clamped: (n: number) => `_${n} group(s) dropped from this comment to fit GitHub's limit — the job summary carries them all._`,
     unanchored: (n: number) => `${n} finding(s) keyed to a URL, with no code line to annotate — see the report.`,
     unattributed: (n: number) =>
       `${n} finding(s) are attributed to no page (shared code, file outside any route) — counted in the overall audit, never spread across pages.`,
@@ -120,7 +151,89 @@ const S = {
   },
 } as const;
 
+/** Group rows kept on the job summary. Groups, not findings — 472 occurrences of one
+ *  design-system defect are one row, so this ceiling is reached by real variety only. */
 const MAX_ROWS = 50;
+/** Group rows kept in the pull-request digest, before the size clamp gets a say. */
+const COMMENT_ROWS = 10;
+/** GitHub refuses an issue-comment body past this. Documented for tickets at
+ *  src/tickets/providers/github.ts; the report surface was never clamped at all, so a wide
+ *  audit posted a body the API rejected with a 422 and the run reported "comment failed". */
+const COMMENT_LIMIT = 65_536;
+
+/** One (criterion, rule, selector) defect, however many times it occurs. */
+export interface FindingGroup {
+  criterion: string;
+  ruleId: string;
+  selectorHint: string;
+  severity: Severity;
+  message: string;
+  /** A representative location — the first occurrence. The count says how many follow. */
+  where: string;
+  occurrences: number;
+  /** Distinct pages the defect was raised on. 0 when nothing is page-attributed. */
+  pages: number;
+}
+
+/** Fold findings by what is actually WRONG rather than by where it shows up.
+ *
+ *  The audit that motivated this had 472 findings of one rule across 38 routes, for SEVEN
+ *  distinct selectors: a single design-system defect, multiplied. Listing the occurrences
+ *  produced a table nobody could read, and cutting it at 50 rows produced a table that lied
+ *  about the shape of the problem. Grouping shows seven defects and says, in its own columns,
+ *  that they occur 472 times over 38 pages. */
+export function groupFindings(findings: Finding[], standard: StandardId, lang: Lang, baseDir: string): FindingGroup[] {
+  const groups = new Map<string, FindingGroup & { pageSet: Set<string> }>();
+  for (const f of findings) {
+    const criterion = criterionLabel(f, standard);
+    const key = `${criterion}${f.ruleId}${f.selectorHint}`;
+    const g = groups.get(key);
+    if (g) {
+      g.occurrences++;
+      if (f.page) g.pageSet.add(f.page);
+      continue;
+    }
+    groups.set(key, {
+      criterion,
+      ruleId: f.ruleId,
+      selectorHint: f.selectorHint,
+      severity: f.severity,
+      message: resolveMessage(f, lang),
+      where: isUrl(f.file) ? f.file : `${repoRelative(f.file, baseDir)}:${Math.max(1, f.line)}`,
+      occurrences: 1,
+      pages: 0,
+      pageSet: new Set(f.page ? [f.page] : []),
+    });
+  }
+  return [...groups.values()]
+    .map(({ pageSet, ...g }) => ({ ...g, pages: pageSet.size }))
+    .sort((a, b) => SEV_ORDER.indexOf(a.severity) - SEV_ORDER.indexOf(b.severity) || b.occurrences - a.occurrences || a.criterion.localeCompare(b.criterion));
+}
+
+/** The run-wide rate, WITH the denominator it never carried, and the `*` when an agent ruled
+ *  a conformity the engine did not prove. `conformancePct` is computed over the decided set
+ *  (src/audit.ts) and then discarded; the count comes back from the shared report model, so
+ *  this number and the Markdown report's §1 total cannot disagree. */
+export function runRate(result: AuditResult, standard: StandardId, lang: Lang): { text: string; agentRuled: boolean } {
+  const groups = isCore(standard) ? reportGroups(result, lang) : packReportGroups(result, loadPack(standard), lang);
+  const { decided, total } = reportCoverage(groups);
+  const agentRuled = groups.some((g) => g.rows.some((r) => r.decidedBy === "agent" && r.status === "C"));
+  return { text: `${formatRate(decided === 0 ? null : result.conformancePct, decided, total)}${agentRuled ? "*" : ""}`, agentRuled };
+}
+
+function groupTableHead(s: (typeof S)[Lang]): string[] {
+  return [`| ${s.severity} | ${s.criterion} | ${s.where} | ${s.what} | ${s.occurrences} | ${s.pagesCol} |`, "| --- | --- | --- | --- | ---: | ---: |"];
+}
+
+function groupRow(g: FindingGroup): string {
+  // Pipes inside a cell would break the table.
+  const cell = (v: string): string => v.replace(/\|/g, "\\|");
+  return `| ${ICON[g.severity]} ${g.severity} | ${cell(g.criterion)} | \`${cell(g.where)}\` (\`${cell(g.selectorHint)}\`) | ${cell(g.message)} | ${g.occurrences} | ${g.pages || "—"} |`;
+}
+
+function groupTable(rows: FindingGroup[], s: (typeof S)[Lang]): string[] {
+  return [...groupTableHead(s), ...rows.map(groupRow)];
+}
 
 /** Markdown for `$GITHUB_STEP_SUMMARY`. */
 export function stepSummary(result: AuditResult, opts: AnnotateOptions = {}): string {
@@ -128,10 +241,12 @@ export function stepSummary(result: AuditResult, opts: AnnotateOptions = {}): st
   const lang = opts.lang ?? "en";
   const s = S[lang];
   const stdLabel = isCore(standard) ? "WCAG 2.2 AA" : loadPack(standard).name;
+  const rate = runRate(result, standard, lang);
 
   const out: string[] = [];
   out.push(`## ${s.title} — ${stdLabel}`, "");
-  out.push(`\`${result.date}\` · ${result.scope.files} ${s.files} · **${result.conformancePct}%** ${s.rate}`, "");
+  out.push(`\`${result.date}\` · ${result.scope.files} ${s.files} · **${rate.text}** ${s.rate}`, "");
+  if (rate.agentRuled) out.push(`> ${agentMarkNote(lang)}`, "");
 
   // Resolve the standard's findings BEFORE the empty check: a page whose only defect comes
   // from a declarative pack rule has an empty `result.findings` and would otherwise be
@@ -147,16 +262,11 @@ export function stepSummary(result: AuditResult, opts: AnnotateOptions = {}): st
     return out.join("\n");
   }
 
-  const sorted = [...all].sort((a, b) => SEV_ORDER.indexOf(a.severity) - SEV_ORDER.indexOf(b.severity));
-  out.push(`### ${s.findings} (${sorted.length})`, "");
-  out.push(`| ${s.severity} | ${s.criterion} | ${s.where} | ${s.what} |`, "| --- | --- | --- | --- |");
-  for (const f of sorted.slice(0, MAX_ROWS)) {
-    const where = isUrl(f.file) ? f.file : `${repoRelative(f.file, baseDir)}:${Math.max(1, f.line)}`;
-    // Pipes inside a cell would break the table.
-    const msg = resolveMessage(f, lang).replace(/\|/g, "\\|");
-    out.push(`| ${ICON[f.severity]} ${f.severity} | ${criterionLabel(f, standard)} | \`${where}\` | ${msg} |`);
-  }
-  if (sorted.length > MAX_ROWS) out.push("", s.more(sorted.length - MAX_ROWS));
+  const grouped = groupFindings(all, standard, lang, baseDir);
+  out.push(`### ${s.findings} — ${s.grouped(grouped.length, all.length)}`, "");
+  out.push(`> ${s.groupNote}`, "");
+  out.push(...groupTable(grouped.slice(0, MAX_ROWS), s));
+  if (grouped.length > MAX_ROWS) out.push("", s.more(grouped.length - MAX_ROWS));
   out.push("");
 
   const unanchored = all.filter((f) => isUrl(f.file)).length;
@@ -166,6 +276,61 @@ export function stepSummary(result: AuditResult, opts: AnnotateOptions = {}): st
   return out.join("\n");
 }
 
+/** The pull-request digest.
+ *
+ *  Deliberately NOT the job summary. A reviewer wants the verdict, how much of the standard
+ *  was actually decided, the distinct defects, and a way to reach the rest — in a comment
+ *  short enough to read without collapsing. It LINKS to the artifact rather than embedding
+ *  crops: an artifact is not addressable by URL while its run is in flight, so an inline
+ *  image would render as a broken box on every pull request.
+ *
+ *  `runUrl` / `artifactName` come from the caller (the action's env), never from this module. */
+export function prComment(result: AuditResult, opts: AnnotateOptions & { runUrl?: string; artifactName?: string } = {}): string {
+  const standard = opts.standard ?? CORE;
+  const lang = opts.lang ?? "en";
+  const s = S[lang];
+  const baseDir = opts.baseDir ?? process.cwd();
+  const stdLabel = isCore(standard) ? "WCAG 2.2 AA" : loadPack(standard).name;
+  const all = findingsForStandard(result, standard);
+  const normative = all.filter((f) => !f.advisory);
+  const blocking = normative.filter((f) => f.severity === "bloquant").length;
+  const rate = runRate(result, standard, lang);
+  const grouped = groupFindings(all, standard, lang, baseDir);
+  const orphans = unattributedFindings(result).filter((f) => !f.advisory).length;
+
+  const head: string[] = [];
+  head.push(`### ${s.title} — ${stdLabel}`, "");
+  head.push(blocking ? s.verdictFail(blocking) : normative.length ? s.verdictWarn : s.verdictPass, "");
+  head.push(`\`${result.date}\` · ${result.scope.files} ${s.files} · **${rate.text}** ${s.rate}`, "");
+  if (rate.agentRuled) head.push(`> ${agentMarkNote(lang)}`, "");
+  if (orphans) head.push(`> ${s.unattributed(orphans)}`, "");
+
+  const tail: string[] = [];
+  if (opts.artifactName) tail.push(s.artifact(opts.artifactName), "");
+  if (opts.runUrl) tail.push(s.runLink(opts.runUrl), "");
+
+  // WHOLE ROWS, never a slice of the finished string. Cutting a rendered document at a byte
+  // offset can land mid-row — GFM then renders a broken table — or inside an unterminated
+  // fence, where it swallows everything after it. So the body is assembled from a row count
+  // that comes down until the whole document fits, and the verdict, the rate and the link are
+  // never candidates: a comment that fits but says nothing about where to look is worse than
+  // no comment at all.
+  const assemble = (rows: number): string => {
+    const body: string[] = [];
+    if (grouped.length) {
+      body.push(s.grouped(grouped.length, all.length), "");
+      body.push(...groupTable(grouped.slice(0, rows), s), "");
+      const omitted = grouped.length - rows;
+      if (omitted > 0) body.push(rows < COMMENT_ROWS ? s.clamped(omitted) : s.moreGroups(omitted), "");
+    }
+    return [...head, ...body, ...tail].join("\n").trimEnd();
+  };
+
+  let rows = Math.min(COMMENT_ROWS, grouped.length);
+  while (rows > 0 && assemble(rows).length > COMMENT_LIMIT) rows--;
+  return assemble(rows);
+}
+
 /** The per-page scoreboard — the surface a reviewer actually scans on a PR, one row per page
  *  with its rate and its findings by severity.
  *

package/src/auditor.ts

@@ -106,6 +106,12 @@ const L = {
 
 const uniq = (xs: string[]): string[] => [...new Set(xs.filter(Boolean))];
 
+/** Resolves the annotated crop illustrating one occurrence, or nothing when the evidence tier
+ *  could not draw it. A LOOKUP rather than a manifest so this module stays ignorant of how a
+ *  finding is keyed (src/baseline.ts `findingId`) and of the evidence tier entirely — passing a
+ *  manifest would couple the auditor block to a key format it has no business knowing. */
+export type AuditorCropLookup = (f: Finding) => { href: string; alt: string } | undefined;
+
 export interface AuditorUnitOpts {
   heading?: string; // "###"/"##" → emit a criterion heading; omit for a bare issue body
   // Emit the technical ticket sections (Partie technique + Contexte de reproduction).
@@ -116,6 +122,9 @@ export interface AuditorUnitOpts {
   // only the per-page sheet turns it on, because that is where one design-system defect
   // multiplied by every route using it produces a page of near-identical lines.
   collapse?: boolean;
+  // Hang the annotated crop under each occurrence that has one. Absent ⇒ the block is
+  // byte-identical to what it was before evidence existed.
+  cropFor?: AuditorCropLookup;
 }
 
 /** Repeated occurrences of ONE (rule, selector) on one file, folded into groups.
@@ -146,10 +155,16 @@ function groupOccurrences(findings: Finding[], collapse: boolean): Finding[][] {
 /** The inert sub-bullets that hang off one occurrence: the crosswalk deviation note, the related
  *  occurrence, the capture provenance. Extracted so the grouped and ungrouped paths cannot drift,
  *  and so the indent is applied in exactly one place. */
-function renderOccurrenceDetails(out: string[], f: Finding, lang: Lang, s: (typeof L)[Lang], indent: string): void {
+function renderOccurrenceDetails(out: string[], f: Finding, lang: Lang, s: (typeof L)[Lang], indent: string, cropFor?: AuditorCropLookup): void {
   // A finding projected via an opt-in secondary crosswalk mapping carries a note explaining the
   // deviation from the SC-faithful projection — an inert (worklist-ignored) sub-bullet.
   if (f.secondary?.note) out.push(`${indent}  - ↳ ${f.secondary.note}`);
+  // THE ONLY PLACE a crop is hung off an occurrence. `report §2`, `prd`, every tracker issue
+  // body and every per-page sheet inherit it here, at once. The bullet carries no `[ ]`, which
+  // is what keeps it out of verify.ts's worklist — indentation alone would NOT, since
+  // AUDITOR_OCCURRENCE is anchored `^\s*-\s\[ \]` and tolerates leading space.
+  const crop = cropFor?.(f);
+  if (crop) out.push(`${indent}  - ![${crop.alt}](${crop.href})`);
   if (f.related) out.push(indent + relatedLine(f.related, lang, { selector: true }));
   if (f.origin) {
     const comp = f.origin.component ?? f.origin.sourceFile ?? f.file;
@@ -216,80 +231,137 @@ export function relatedLine(related: NonNullable<Finding["related"]>, lang: Lang
 export function renderAuditorUnit(unit: PrdUnit, standard: StandardId, lang: Lang, opts: AuditorUnitOpts = {}): string[] {
   const s = L[lang];
   if (unit.advisory) return renderAdvisoryUnit(unit, standard, lang, opts);
-  const v = vocabularyFor(standard, lang);
-  const technical = opts.technical ?? true;
+  const m = auditorUnitModel(unit, standard, lang, opts);
   const out: string[] = [];
-  if (opts.heading) out.push(`${opts.heading} ${ICON[unit.severity]} ${unit.label}`, "");
-  out.push(`> ${v.normativeNote ?? `${s.lead} — ${standardLabel(standard)}. ${s.tail}`}`, "");
+  if (opts.heading) out.push(`${opts.heading} ${m.icon} ${m.label}`, "");
+  out.push(`> ${m.normativeNote}`, "");
 
   // ---- 1. criterion block (unchanged) + the explicit Priorité line ----
-  if (isCore(standard)) {
-    const sc = getSC(unit.criteriaId);
-    if (sc) {
-      const pr = `${sc.principle} ${principleTitle(sc.principle, lang) ?? ""}`.trim();
-      const gl = `${sc.guideline} ${guidelineTitle(sc.guideline, lang) ?? ""}`.trim();
-      out.push(`**${v.theme}** : ${[pr, gl].filter(Boolean).join(" · ")}`);
-    }
-    out.push(`**${v.criterion}** : ${unit.criteriaId}${sc ? ` — ${unit.title}` : ""}`);
-    const techs = scTechniques(unit.criteriaId);
-    if (techs.length) out.push(`**${v.test}** : ${techs.join(", ")}`);
-    out.push(`**WCAG** : ${unit.criteriaId}${sc ? ` (${sc.level})` : ""}`);
-  } else {
-    const pack = loadPack(standard);
-    const pc = pack.criteria.find((c) => c.id === unit.criteriaId);
-    if (pc) out.push(`**${v.theme}** : ${pc.theme}. ${themeName(pack, pc.theme, lang) ?? ""}`.trimEnd());
-    out.push(`**${v.criterion}** : ${unit.criteriaId} — ${unit.title}`);
-    const testNums = packTestIds(pack, unit.criteriaId);
-    if (testNums.length) out.push(`**${v.test}(s)** : ${testNums.join(" · ")}`);
-    if (unit.refs.length) out.push(`**WCAG** : ${unit.refs.map((sc) => `${sc}${scLevel(sc)}`).join(" · ")}`);
-  }
-  out.push(`**${s.priority}** : ${ICON[unit.severity]} ${SEV_LABEL[lang][unit.severity]}`);
+  for (const f of m.fields) out.push(`**${f.label}** : ${f.value}`);
 
   // ---- 2. finding / expected / verification + the PARSEABLE occurrence checklist ----
   // Advisory findings riding along in a MIXED unit are excluded from the checklist (they are
   // recommendations, never non-conformities) and rendered below in a distinct, NON-parseable
   // sub-list — so verify.ts's worklist never captures a recommendation as an NC claim. Its
   // POSITION (before any newly-introduced heading) is load-bearing for the parser.
-  const normative = unit.findings.filter((f) => !f.advisory);
-  const advisories = unit.findings.filter((f) => f.advisory);
-  const ncView: PrdUnit = { ...unit, findings: normative };
-  const messages = uniq(normative.map((f) => resolveMessage(f, lang)));
-  const fixes = uniq(normative.map((f) => resolveRemediation(f, lang)));
   out.push("");
-  out.push(`**${s.finding} (${v.nonConformant})** : ${normative.length} ${s.occ} — ${messages.join(" ; ")}`);
-  if (fixes.length) out.push(`**${s.expected} (${v.conformant})** : ${fixes.join(" ; ")}`);
+  out.push(`**${s.finding} (${m.conformanceTerms.nonConformant})** : ${m.occurrences} ${s.occ} — ${m.messages.join(" ; ")}`);
+  if (m.fixes.length) out.push(`**${s.expected} (${m.conformanceTerms.conformant})** : ${m.fixes.join(" ; ")}`);
   out.push(`**${s.verification}** : ${s.verify}`, "");
-  for (const group of groupOccurrences(normative, opts.collapse === true)) {
+  for (const group of m.groups) {
     // A GROUP HEADER, when several occurrences share a rule and a selector. It is deliberately
     // NOT checkbox-shaped: `verify` must see one item per claimed non-conformity, not one per
     // group, so the fold changes what the reader scans and never what the gate adjudicates.
-    if (group.length > 1) out.push(`- **\`${group[0]!.selectorHint}\`** — ${resolveMessage(group[0]!, lang)} · ×${group.length}`);
-    for (const f of group) {
+    if (group.count > 1) out.push(`- **\`${group.lead.selectorHint}\`** — ${resolveMessage(group.lead, lang)} · ×${group.count}`);
+    for (const f of group.findings) {
       // Members of a real group are indented under it; a lone occurrence stays flush, so an
       // ungrouped block is byte-identical to what it was before collapsing existed.
-      const indent = group.length > 1 ? "  " : "";
+      const indent = group.count > 1 ? "  " : "";
       out.push(indent + occurrenceLine(f, lang, { marker: "checkbox" }));
-      renderOccurrenceDetails(out, f, lang, s, indent);
+      renderOccurrenceDetails(out, f, lang, s, indent, opts.cropFor);
     }
   }
   out.push("");
 
   // Associated recommendations (mixed unit only): a visually distinct, NON-parseable list —
   // the `- 💡` bullet deliberately avoids the `- [ ] \`file:line\`` checklist grammar.
-  if (advisories.length) {
+  if (m.advisories.length) {
     out.push(`_${s.associatedRec}_`, "");
-    for (const f of advisories) out.push(occurrenceLine(f, lang, { marker: "advisory" }));
+    for (const f of m.advisories) out.push(occurrenceLine(f, lang, { marker: "advisory" }));
     out.push("");
   }
 
   // ---- 3 + 4. technical ticket sections (opt-out via prd --no-technical) ----
-  if (technical) {
-    out.push(...renderTechnicalSection(ncView, unit, standard, lang, opts));
-    out.push(...renderReproductionContext(normative, lang));
+  if (opts.technical ?? true) {
+    out.push(...renderTechnicalSection({ ...unit, findings: m.normative }, unit, standard, lang, opts));
+    out.push(...renderReproductionContext(m.normative, lang));
   }
   return out;
 }
 
+/** One `**label** : value` line of the criterion block, before it is serialized. */
+export interface AuditorField {
+  label: string;
+  value: string;
+}
+
+/** Occurrences of one (file, rule, selector), as the block will present them. `count > 1` is
+ *  what earns a group header; a lone occurrence renders flush. */
+export interface AuditorOccurrenceGroup {
+  lead: Finding;
+  count: number;
+  findings: Finding[];
+}
+
+/** Everything `renderAuditorUnit` DECIDES, before anything is turned into Markdown.
+ *
+ *  The split exists so a second surface — the HTML report — can present the same criterion
+ *  without re-resolving the active standard's vocabulary, re-picking the theme line, or
+ *  re-deciding which findings are normative. `renderAuditorUnit` is now the Markdown
+ *  serializer of this model, and `tests/__snapshots__/auditor.test.ts.snap` pins that the
+ *  serialization did not move a byte. */
+export interface AuditorUnitModel {
+  severity: Severity;
+  icon: string;
+  label: string;
+  normativeNote: string;
+  fields: AuditorField[];
+  conformanceTerms: { conformant: string; nonConformant: string };
+  /** Normative findings only — an advisory can never be counted as a non-conformity. */
+  normative: Finding[];
+  advisories: Finding[];
+  occurrences: number;
+  messages: string[];
+  fixes: string[];
+  groups: AuditorOccurrenceGroup[];
+}
+
+export function auditorUnitModel(unit: PrdUnit, standard: StandardId, lang: Lang, opts: AuditorUnitOpts = {}): AuditorUnitModel {
+  const s = L[lang];
+  const v = vocabularyFor(standard, lang);
+  const fields: AuditorField[] = [];
+
+  if (isCore(standard)) {
+    const sc = getSC(unit.criteriaId);
+    if (sc) {
+      const pr = `${sc.principle} ${principleTitle(sc.principle, lang) ?? ""}`.trim();
+      const gl = `${sc.guideline} ${guidelineTitle(sc.guideline, lang) ?? ""}`.trim();
+      fields.push({ label: v.theme, value: [pr, gl].filter(Boolean).join(" · ") });
+    }
+    fields.push({ label: v.criterion, value: `${unit.criteriaId}${sc ? ` — ${unit.title}` : ""}` });
+    const techs = scTechniques(unit.criteriaId);
+    if (techs.length) fields.push({ label: v.test, value: techs.join(", ") });
+    fields.push({ label: "WCAG", value: `${unit.criteriaId}${sc ? ` (${sc.level})` : ""}` });
+  } else {
+    const pack = loadPack(standard);
+    const pc = pack.criteria.find((c) => c.id === unit.criteriaId);
+    // `.trimEnd()` on the VALUE, not on the rendered line: a pack whose theme has no localized
+    // name must not leave a trailing space behind the colon.
+    if (pc) fields.push({ label: v.theme, value: `${pc.theme}. ${themeName(pack, pc.theme, lang) ?? ""}`.trimEnd() });
+    fields.push({ label: v.criterion, value: `${unit.criteriaId} — ${unit.title}` });
+    const testNums = packTestIds(pack, unit.criteriaId);
+    if (testNums.length) fields.push({ label: `${v.test}(s)`, value: testNums.join(" · ") });
+    if (unit.refs.length) fields.push({ label: "WCAG", value: unit.refs.map((sc) => `${sc}${scLevel(sc)}`).join(" · ") });
+  }
+  fields.push({ label: s.priority, value: `${ICON[unit.severity]} ${SEV_LABEL[lang][unit.severity]}` });
+
+  const normative = unit.findings.filter((f) => !f.advisory);
+  return {
+    severity: unit.severity,
+    icon: ICON[unit.severity],
+    label: unit.label,
+    normativeNote: v.normativeNote ?? `${s.lead} — ${standardLabel(standard)}. ${s.tail}`,
+    fields,
+    conformanceTerms: { conformant: v.conformant, nonConformant: v.nonConformant },
+    normative,
+    advisories: unit.findings.filter((f) => f.advisory),
+    occurrences: normative.length,
+    messages: uniq(normative.map((f) => resolveMessage(f, lang))),
+    fixes: uniq(normative.map((f) => resolveRemediation(f, lang))),
+    groups: groupOccurrences(normative, opts.collapse === true).map((g) => ({ lead: g[0]!, count: g.length, findings: g })),
+  };
+}
+
 /** Section 3 — Partie technique: impacted files, impacted pages/URLs (with Task-5 sample
  *  provenance when present), the expected change + guidance example, Given/When/Then
  *  acceptance criteria, and the deterministic complexity. All lines here are worklist-inert: