ultra11y 4.1.0 → 4.2.0

package/src/evidence.ts

@@ -20,10 +20,18 @@
 // engine refuses. Deriving re-runs the same verified join every time, and refuses wholesale
 // when it does not hold, exactly as `align()` already does for styles and boxes.
 //
-// WHAT IT REFUSES. Most findings get no crop, and each reason is recorded and reported rather
-// than left as a gap: a source finding has no pixels, a component capture was rendered by
-// jsdom which paints nothing, a page-scope rule points at `<html>` and would "highlight" the
-// whole screenshot, and — the one that surprises people — an element below the fold is simply
+// WHAT IT REFUSES, AND WHAT IT NEVER COUNTED. Two different things, and conflating them is
+// how a report starts lying about its own coverage.
+//
+// NOT COUNTED: a finding raised on source code. It is not an occurrence this tier failed to
+// draw, it is an occurrence outside the tier — so it never enters `located`, and a repository
+// audited from source alone gets NO notice rather than one line per finding saying pixels
+// were never involved. The filter is the snapshot PATH (`byPage` below).
+//
+// REFUSED: a finding that IS on a captured page and still gets no crop. Each of those has a
+// reason, recorded and reported rather than left as a gap — a page-scope rule points at
+// `<html>` and would "highlight" the whole screenshot, a component capture rendered by jsdom
+// paints nothing, and — the one that surprises people — an element below the fold is simply
 // not in the image, because every producer captures the VIEWPORT on purpose so the screenshot
 // shares boxes.json's coordinate system (src/integrations/playwright.ts). None of these is a
 // bug to work around; each is a fact to state.
@@ -39,20 +47,28 @@ import type { SnapshotMeta, SnapshotViewport } from "./snapshot.js";
 import type { AuditResult, BoxDigest, BoxEntry, Finding, Lang } from "./types.js";
 
 /** Why a finding got no picture. Every one of these is REPORTED, never swallowed: a reader
- *  who sees fewer images than non-conformities must be told which, and why. */
-export type EvidenceSkip =
-  | "no-snapshot" // not raised on a page snapshot's dom.html (source finding, component capture)
-  | "no-screenshot" // the producer captured no image for this page
-  | "unreadable-image" // screen.png is not 8-bit truecolour, or is corrupt
-  | "no-boxes" // no boxes.json, or it did not verify against this dom.html
-  | "truncated" // the collector hit its element cap; this element has no box
-  | "no-offsets" // the finding carries no sourceStart (cannot be joined)
-  | "unjoinable" // sourceStart matches no element in dom.html
-  | "page-scope" // anchored at the document element: the page screenshot IS the illustration
-  | "zero-area" // the element has no painted box (display:contents, empty inline)
-  | "below-the-fold" // outside a viewport-only capture
-  | "unknown-scale" // image-pixels-per-CSS-pixel is indeterminate
-  | "capped"; // de-duplicated away by the caps below
+ *  who sees fewer images than non-conformities must be told which, and why.
+ *
+ *  A VALUE, not only a type, so the documentation can be held against it: `references/pages.md`
+ *  publishes this list to auditors, and a reason added here without a row there is a refusal
+ *  the reader meets in a report and cannot look up (tests/skill-md.test.ts). */
+export const EVIDENCE_SKIPS = [
+  "no-snapshot", // the snapshot this finding's own path names is not on disk (audit rendered elsewhere, `.ultra11y/` cleaned)
+  "no-screenshot", // the producer captured no image for this page
+  "unreadable-image", // screen.png is not 8-bit truecolour, or is corrupt
+  "no-boxes", // no boxes.json, or it did not verify against this dom.html
+  "truncated", // the collector hit its element cap; this element has no box
+  "no-offsets", // the finding carries no sourceStart (cannot be joined)
+  "unjoinable", // sourceStart matches no element in dom.html
+  "page-scope", // anchored at the document element: the page screenshot IS the illustration
+  "zero-area", // the element has no painted box (display:contents, empty inline)
+  "below-the-fold", // outside a viewport-only capture
+  "unknown-scale", // image-pixels-per-CSS-pixel is indeterminate
+  "deduplicated", // the same (rule, element) is already illustrated — one picture, every occurrence
+  "capped", // a numeric limit ran out (DEFAULT_CAPS below) — a DISTINCT defect went undrawn
+] as const;
+
+export type EvidenceSkip = (typeof EVIDENCE_SKIPS)[number];
 
 export interface EvidenceGeometry {
   /** Context kept around the element, in CSS pixels. */
@@ -323,7 +339,7 @@ const S: Record<Lang, { alt: (sel: string, page: string) => string; notImaged: (
     alt: (sel, page) => `Capture recadrée de l'élément ${sel} sur la page ${page}, entouré d'un cadre`,
     notImaged: (n) => `${n} occurrence(s) ne sont pas illustrées :`,
     reasons: {
-      "no-snapshot": "constat levé sur le code source, pas sur une page capturée — il n'y a pas de pixels à montrer",
+      "no-snapshot": "la capture de page que ce constat désigne n'est pas sur ce disque — sa référence fichier:ligne reste valable",
       "no-screenshot": "le producteur n'a pas fourni de capture pour cette page, donc le niveau pixel est inactif ici",
       "unreadable-image": "la capture n'est pas décodable (le moteur lit le truecolour 8 bits uniquement) — mieux vaut aucune image qu'une fausse",
       "no-boxes":
@@ -335,14 +351,15 @@ const S: Record<Lang, { alt: (sel: string, page: string) => string; notImaged: (
       "zero-area": "l'élément n'occupe aucune surface peinte",
       "below-the-fold": "l'élément est hors de la capture (la capture couvre la fenêtre, pas la page entière) — sa référence fichier:ligne reste valable",
       "unknown-scale": "le rapport pixels/CSS est indéterminé pour cette page ; un rapport deviné encadrerait le mauvais endroit",
-      capped: "occurrences regroupées : une illustration par élément distinct, dans la limite fixée",
+      deduplicated: "même défaut sur le même élément : il est montré par l'illustration d'une autre occurrence, rien n'a été perdu",
+      capped: "défaut distinct laissé sans image : le plafond de vignettes de ce lot est atteint — relevez `--evidence-max` pour les obtenir",
     },
   },
   en: {
     alt: (sel, page) => `Cropped screenshot of the ${sel} element on the ${page} page, outlined`,
     notImaged: (n) => `${n} occurrence(s) are not illustrated:`,
     reasons: {
-      "no-snapshot": "raised on source code, not on a captured page — there are no pixels to show",
+      "no-snapshot": "the page snapshot this finding names is not on this disk — its file:line reference still holds",
       "no-screenshot": "the producer supplied no screenshot for this page, so the pixel tier is inactive here",
       "unreadable-image": "the screenshot does not decode (the engine reads 8-bit truecolour only) — no image beats a wrong one",
       "no-boxes": "the element positions do not verify against the serialized DOM, so they were refused wholesale rather than outlining the wrong element",
@@ -353,25 +370,36 @@ const S: Record<Lang, { alt: (sel: string, page: string) => string; notImaged: (
       "zero-area": "the element paints no box",
       "below-the-fold": "the element sits outside the capture (the screenshot covers the viewport, not the whole page) — its file:line reference still holds",
       "unknown-scale": "the image-pixel to CSS-pixel ratio is indeterminate for this page; a guessed ratio would outline the wrong place",
-      capped: "occurrences grouped: one illustration per distinct element, up to the cap",
+      deduplicated: "the same defect on the same element: it is shown by the illustration of another occurrence, nothing was lost",
+      capped: "a distinct defect left undrawn: this run's crop limit was reached — raise `--evidence-max` to get them",
     },
   },
 };
 
-/** What the report says about what it did NOT draw — per page, or overall when `pageId` is
- *  null. Empty when everything located was imaged. */
-export function evidenceNotice(m: EvidenceManifest, pageId: string | null, lang: Lang): string[] {
+/** The refusals themselves — per page, or overall when `pageId` is null. Undefined when
+ *  everything located was imaged.
+ *
+ *  This is the DECISION (which refusals, with what counts, in what order); the bullet
+ *  characters belong to whoever renders it. Markdown gets `- `, the HTML tier gets `<li>`,
+ *  and neither can drift from the other because there is only one list here. */
+export function evidenceRefusals(m: EvidenceManifest, pageId: string | null, lang: Lang): { headline: string; reasons: string[] } | undefined {
   const t = pageId === null ? m.totals : m.perPage.get(pageId);
-  if (!t) return [];
+  if (!t) return undefined;
   const missing = t.located - t.imaged;
-  if (missing <= 0) return [];
+  if (missing <= 0) return undefined;
+  const entries = Object.entries(t.skipped).filter(([, n]) => n) as [EvidenceSkip, number][];
   const s = S[lang];
-  const out = [s.notImaged(missing)];
-  for (const [reason, n] of Object.entries(t.skipped).sort((a, b) => (b[1] ?? 0) - (a[1] ?? 0))) {
-    if (!n) continue;
-    out.push(`- ${n} — ${s.reasons[reason as EvidenceSkip]}`);
-  }
-  return out;
+  return {
+    headline: s.notImaged(missing),
+    reasons: entries.sort((a, b) => b[1] - a[1]).map(([reason, n]) => `${n} — ${s.reasons[reason]}`),
+  };
+}
+
+/** What the report says about what it did NOT draw, as Markdown. Empty when there is
+ *  nothing to say. */
+export function evidenceNotice(m: EvidenceManifest, pageId: string | null, lang: Lang): string[] {
+  const r = evidenceRefusals(m, pageId, lang);
+  return r ? [r.headline, ...r.reasons.map((x) => `- ${x}`)] : [];
 }
 
 // ---- the run -----------------------------------------------------------------------------
@@ -441,10 +469,17 @@ export function writeEvidence(result: AuditResult, opts: EvidenceOptions): Evide
       // handful of DIFFERENT things actually wrong.
       const key = `${f.ruleId}\u0000${f.selectorHint}`;
       const ruleCount = perRule.get(f.ruleId) ?? 0;
-      if (seen.has(key) || ruleCount >= caps.perRule || onPage >= caps.perPage || manifest.crops.size >= caps.total) {
-        manifest.skipped.set(id, "capped");
-        bump(tally, "capped");
-        bump(manifest.totals, "capped");
+      // TWO FACTS, never one label. `deduplicated` means the reader IS looking at this defect,
+      // in another occurrence's picture — nothing was lost. `capped` means a DISTINCT defect
+      // has no picture at all because a limit ran out. Only the second costs the reader
+      // something, and only the second is worth a setting; folding them together hid the one
+      // sentence that could tell someone their artifact is incomplete.
+      const overLimit = ruleCount >= caps.perRule || onPage >= caps.perPage || manifest.crops.size >= caps.total;
+      const refusal = seen.has(key) ? "deduplicated" : overLimit ? "capped" : null;
+      if (refusal) {
+        manifest.skipped.set(id, refusal);
+        bump(tally, refusal);
+        bump(manifest.totals, refusal);
         continue;
       }
 

package/src/html-emit.ts

@@ -12,9 +12,9 @@
 import { mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { findingId } from "./baseline.js";
-import type { EvidenceManifest } from "./evidence.js";
+import { evidenceRefusals, type EvidenceManifest } from "./evidence.js";
 import { renderHtmlDocument, type Doc, type Run } from "./html.js";
-import { compositeDoc, indexDoc, pageDoc, pagesIndexDoc, type CropLookup } from "./html-report.js";
+import { compositeDoc, indexDoc, pageDoc, pagesIndexDoc, type CropLookup, type RefusalLookup } from "./html-report.js";
 import { derivePages, pagesOf } from "./pages.js";
 import { CORE, type StandardId, isCore, loadPack } from "./standards/index.js";
 import type { AuditResult, Finding, Lang } from "./types.js";
@@ -122,6 +122,15 @@ function cropLookup(m: EvidenceManifest | undefined, lang: Lang, hrefOf: (path:
   };
 }
 
+/** What the tier refused to draw, keyed the way the report tier wants it. Independent of the
+ *  budget ladder on purpose: the ladder's own notices say which pictures were dropped FOR
+ *  SIZE, this says which occurrences have no picture AT ALL. Both belong in the document, and
+ *  neither substitutes for the other. */
+function refusalLookup(m: EvidenceManifest | undefined, lang: Lang): RefusalLookup | undefined {
+  if (!m) return undefined;
+  return (pageId) => evidenceRefusals(m, pageId, lang);
+}
+
 /** Which rung the evidence lands on for a given budget. Pure — the sizes are measured once
  *  and the decision is taken before a single byte is encoded. */
 export function pickRung(cropBytes: number[], shotBytes: number[], budget: number): { steps: DegradeStep[]; cropsPerCriterion: number; shots: boolean } {
@@ -202,9 +211,16 @@ export function writeHtml(result: AuditResult, opts: EmitOpts): EmitResult {
   // ONE composite per artifact. `report --html` owns it; `pages --html` writes the index and
   // its sheets beside the Markdown they mirror. Emitting one from both would put two copies of
   // every inlined crop into the same upload.
+  const refusals = refusalLookup(opts.evidence, lang);
   let compositePath: string | undefined;
   if (!flat) {
-    const composite = compositeDoc(result, { standard, lang, crops: budgetedCrops, nav: nav.map((n) => ({ ...n, current: n.href === `./${compositeName}` })) });
+    const composite = compositeDoc(result, {
+      standard,
+      lang,
+      crops: budgetedCrops,
+      ...(refusals ? { refusals } : {}),
+      nav: nav.map((n) => ({ ...n, current: n.href === `./${compositeName}` })),
+    });
     if (notices.length) composite.blocks.unshift({ kind: "note", tone: "warn", runs: noticeRuns(notices) });
     compositePath = join(opts.outDir, compositeName);
     writeFileSync(compositePath, renderHtmlDocument(composite));
@@ -253,6 +269,7 @@ export function writeHtml(result: AuditResult, opts: EmitOpts): EmitResult {
         standard,
         lang,
         crops: fileCrops,
+        ...(refusals ? { refusals } : {}),
         nav: sheetNav,
         // Where `cmdPages`' screenshot copier already put the capture: `assets/<id>.png`,
         // beside the entry point, seen from wherever this sheet sits.

package/src/html-report.ts

@@ -32,14 +32,32 @@ import type { AuditResult, Finding, Lang, PageResult, Status } from "./types.js"
  *  `cropFor`, and for the same reason: this module never learns how a finding is keyed. */
 export type CropLookup = (f: Finding) => { href: string; alt: string } | undefined;
 
+/** What the evidence tier REFUSED to draw, for one page or — with `null` — for the whole
+ *  run. Same shape as the crop lookup and for the same reason: this module never learns how
+ *  the evidence tier works, only what it decided (src/evidence.ts `evidenceRefusals`). */
+export type RefusalLookup = (pageId: string | null) => { headline: string; reasons: string[] } | undefined;
+
 export interface HtmlReportOpts {
   standard?: StandardId;
   lang?: Lang;
   crops?: CropLookup;
+  /** An occurrence with no picture must never read as an occurrence with no defect, so the
+   *  document states what it did not draw. Without this, the HTML — the deliverable that
+   *  actually reaches the client — is the one surface that keeps the omission to itself. */
+  refusals?: RefusalLookup;
   /** Sibling documents, for the nav. */
   nav?: Doc["nav"];
 }
 
+/** The refusal list as blocks: the sentence, then one item per reason. */
+function refusalBlocks(r: { headline: string; reasons: string[] } | undefined): Block[] {
+  if (!r) return [];
+  return [
+    { kind: "note", tone: "warn", runs: [{ text: r.headline }] },
+    { kind: "list", items: r.reasons.map((text) => [{ text }]) },
+  ];
+}
+
 const T = {
   fr: {
     reportTitle: "Rapport de conformité",
@@ -91,7 +109,6 @@ const T = {
     openPages: "Rapport page par page",
     noScreenshot: "Aucune capture d'écran pour cette page.",
     screenshotAlt: (n: string) => `Capture d'écran de la page ${n}`,
-    notImaged: (n: number) => `${n} occurrence(s) n'ont pas pu être illustrées.`,
   },
   en: {
     reportTitle: "Conformance report",
@@ -143,7 +160,6 @@ const T = {
     openPages: "Page-by-page report",
     noScreenshot: "No screenshot for this page.",
     screenshotAlt: (n: string) => `Screenshot of the ${n} page`,
-    notImaged: (n: number) => `${n} occurrence(s) could not be illustrated.`,
   },
 } as const;
 
@@ -262,10 +278,13 @@ function resolveOccurrence(f: Finding, lang: Lang): string {
 }
 
 /** §2 + §Recommendations — every non-conformity, then the advisory units. */
-function findingsBlocks(result: AuditResult, standard: StandardId, lang: Lang, level: 2 | 3, crops?: CropLookup): Block[] {
+function findingsBlocks(result: AuditResult, standard: StandardId, lang: Lang, level: 2 | 3, crops?: CropLookup, refusals?: RefusalLookup): Block[] {
   const t = T[lang];
   const { nc, advisory } = partitionUnits(prdUnits(result, standard, lang));
   const out: Block[] = [{ kind: "heading", level: 2, text: t.ncTitle, id: "nc" }];
+  // Before the first figure, not after the last: a reader who stops scrolling must already
+  // know that the pictures below are a subset of the occurrences listed beside them.
+  out.push(...refusalBlocks(refusals?.(null)));
   if (!nc.length) out.push({ kind: "para", runs: [{ text: t.noNc }] });
   for (const u of nc) out.push(...criterionBlocks(u, standard, lang, level === 2 ? 3 : 4, crops));
   if (advisory.length) {
@@ -391,7 +410,7 @@ export function compositeDoc(result: AuditResult, opts: HtmlReportOpts = {}): Do
   const h = headline(result, standard, lang);
   const blocks: Block[] = [...synthesisBlocks(result, standard, lang)];
   if (h.agentRuled) blocks.push({ kind: "note", tone: "warn", runs: ticks(agentMarkNote(lang)) });
-  blocks.push(...findingsBlocks(result, standard, lang, 2, opts.crops));
+  blocks.push(...findingsBlocks(result, standard, lang, 2, opts.crops, opts.refusals));
   blocks.push(...scoreboardBlocks(result, standard, lang));
   const scope = pagesOf(result);
   if (scope.length) blocks.push(...crossGridBlocks(result, derivePages(result, scope), standard, lang));
@@ -435,6 +454,10 @@ export function pageDoc(result: AuditResult, page: PageResult, opts: HtmlReportO
   blocks.push(
     opts.screenshot ? { kind: "figure", src: opts.screenshot, alt: t.screenshotAlt(page.name) } : { kind: "para", runs: [{ text: t.noScreenshot, em: true }] },
   );
+  // Right after the capture and before the grid — the same place the Markdown sheet puts it
+  // (src/pages-report.ts), so a reader moving between the two documents finds it twice in
+  // the same spot rather than once in one of them.
+  blocks.push(...refusalBlocks(opts.refusals?.(page.id)));
   blocks.push(...pageGridBlocks(result, page, standard, lang));
 
   // The page's OWN findings, through the same view the Markdown sheet uses — so a criterion

package/src/pages-report.ts

@@ -155,10 +155,15 @@ export interface PageReportOpts {
   /** The annotated crop illustrating one occurrence, when the evidence tier drew one. Passed
    *  straight through to the auditor block, which owns the one place a crop is emitted. */
   cropFor?: AuditorCropLookup;
-  /** What the evidence tier could NOT draw on this page, and why — already localized. Printed
+  /** What the evidence tier could NOT draw on a page, and why — already localized. Printed
    *  under the screenshot so a reader is never left to infer that an absent image means an
-   *  absent defect. */
-  evidenceNotice?: string[];
+   *  absent defect.
+   *
+   *  A LOOKUP, not a list, because `renderPagesDocument` renders every page from one opts
+   *  object: a list would print one page's refusals under all of them, and the caller that
+   *  wanted to avoid that instead passed nothing at all — which is how the combined document
+   *  came to carry the crops without the refusals. */
+  evidenceNotice?: (pageId: string) => string[];
 }
 
 /** One criterion's line on one page's sheet. Exported because the HTML renderer and the CI
@@ -270,7 +275,8 @@ export function renderPageReport(result: AuditResult, page: PageResult, opts: Pa
 
   // What the evidence tier refused to draw, and why. An unillustrated occurrence must never
   // read as an absent one — the whole posture of this engine is that nothing is cut silently.
-  if (opts.evidenceNotice?.length) out.push(...opts.evidenceNotice, "");
+  const refused = opts.evidenceNotice?.(page.id) ?? [];
+  if (refused.length) out.push(...refused, "");
 
   // The grid carries the criterion's own numbered TESTS, not just its title and status:
   // those tests are what has to be checked, and listing them only inside the

package/src/report.ts

@@ -9,7 +9,7 @@ import { join, relative } 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 { renderAuditorUnit, type AuditorCropLookup } from "./auditor.js";
 import { resolveMessage } from "./messages.js";
 import { attributePages, derivePages, pagesOf, renderPageGrid } from "./pages.js";
 import { PAGES_DIR } from "./snapshot.js";
@@ -280,6 +280,9 @@ function render(
     // Where this report will be WRITTEN. Only used to resolve the per-page screenshots
     // relatively; absent ⇒ paths relative to the CWD, which is what stdout wants.
     outDir?: string;
+    // The annotated crop for an occurrence, when the evidence tier drew one. Absent ⇒ every
+    // byte below is what it was before the tier existed (tests/__snapshots__/auditor).
+    cropFor?: AuditorCropLookup;
   },
 ): string {
   const s = L[lang];
@@ -332,7 +335,7 @@ function render(
       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: "####" }));
+      for (const u of group) out.push(...renderAuditorUnit(u, opts.standard, lang, { heading: "####", ...(opts.cropFor ? { cropFor: opts.cropFor } : {}) }));
     }
   }
 
@@ -342,7 +345,8 @@ function render(
   // 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: "###" }));
+    for (const u of advisoryUnits)
+      out.push(...renderAuditorUnit(u, opts.standard, lang, { heading: "###", ...(opts.cropFor ? { cropFor: opts.cropFor } : {}) }));
   }
 
   // « Grille par page » — the per-page criterion matrix. RGAA is a per-page norm, so this is
@@ -485,9 +489,9 @@ export function reportGroups(r: AuditResult, lang: Lang = "en"): ReportGroup[] {
   return r.guidelines.map((g) => ({ key: g.key, title: guidelineTitle(g.key, lang) ?? g.title, rows: byGuideline.get(g.key) ?? [] }));
 }
 
-export function renderReport(r: AuditResult, lang: Lang = "en", outDir?: string): string {
+export function renderReport(r: AuditResult, lang: Lang = "en", outDir?: string, cropFor?: AuditorCropLookup): string {
   const s = L[lang];
-  return render(r, lang, { std: s.wcagStd, groupHead: s.byGuideline, groups: reportGroups(r, lang), standard: CORE, outDir });
+  return render(r, lang, { std: s.wcagStd, groupHead: s.byGuideline, groups: reportGroups(r, lang), standard: CORE, outDir, ...(cropFor ? { cropFor } : {}) });
 }
 
 /** A PACK report's criterion rows, grouped by theme. The pack twin of `reportGroups`, and
@@ -524,7 +528,7 @@ export function packReportGroups(r: AuditResult, pack: StandardPack, lang: Lang
 }
 
 /** A derived report for a country standards pack (RGAA, …), projected from the WCAG audit. */
-export function renderPackReport(r: AuditResult, pack: StandardPack, lang: Lang = "en", outDir?: string): string {
+export function renderPackReport(r: AuditResult, pack: StandardPack, lang: Lang = "en", outDir?: string, cropFor?: AuditorCropLookup): string {
   const derived = derivePackResults(r, pack.key);
   const std = `${pack.name} ${pack.baseVersion}`;
   // Owner decision: a pack (RGAA) report is flagged PARTIAL while any needs-rendering
@@ -543,6 +547,7 @@ export function renderPackReport(r: AuditResult, pack: StandardPack, lang: Lang
     // CWD instead of the report's own directory, so a pack report written to `audits/`
     // carried links that only worked when read from the repo root.
     outDir,
+    ...(cropFor ? { cropFor } : {}),
   });
 }
 
@@ -550,13 +555,17 @@ export interface ReportOpts {
   out: string;
   lang: Lang;
   standard: StandardId;
+  /** The evidence tier's crops, when `--evidence` asked for them. The hrefs are relative to
+   *  `out`, which is where this report is written — so the Markdown REFERENCES the same files
+   *  the composite inlines, instead of the run writing images no document points at. */
+  cropFor?: AuditorCropLookup;
 }
 
 /** 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, opts.out) : renderPackReport(r, loadPack(opts.standard), opts.lang, opts.out);
+  const md = core ? renderReport(r, opts.lang, opts.out, opts.cropFor) : renderPackReport(r, loadPack(opts.standard), opts.lang, opts.out, opts.cropFor);
   mkdirSync(opts.out, { recursive: true });
   const path = join(opts.out, `${core ? "wcag" : opts.standard}-${r.date}.md`);
   writeFileSync(path, md);

package/src/tickets/providers/github.ts

@@ -34,21 +34,26 @@ function resolve(opts: GithubOptions): Resolved {
   const mode = opts.transport ?? "auto";
   const api = (env.GITHUB_API_URL || "https://api.github.com").replace(/\/+$/, "");
   const token = env.GH_TOKEN || env.GITHUB_TOKEN;
-  const cliOk = (opts.cliAvailable ?? ghAvailable)();
+  // LAZY, because the probe is `gh auth status` — a subprocess that calls github.com. REST is
+  // the transport for the runners where `gh` is absent or useless, so a caller who already
+  // named REST must not pay for a network round trip whose answer is then discarded.
+  const probe = opts.cliAvailable ?? ghAvailable;
+  let cached: boolean | undefined;
+  const cliOk = (): boolean => (cached ??= probe());
 
   if (mode === "cli") {
-    return cliOk ? { transport: "cli", api } : { transport: "cli", api, reason: "`gh` is not installed or not authenticated (run `gh auth login`)" };
+    return cliOk() ? { transport: "cli", api } : { transport: "cli", api, reason: "`gh` is not installed or not authenticated (run `gh auth login`)" };
   }
   // Only REST needs the repo slug, and only REST should pay for a `git` subprocess to find
   // it — the CLI transport already knows which checkout it is standing in.
-  const repo = env.ULTRA11Y_GITHUB_REPO || env.GITHUB_REPOSITORY || (mode === "rest" || !cliOk ? gitRemoteSlug("github.com") : undefined);
+  const repo = env.ULTRA11Y_GITHUB_REPO || env.GITHUB_REPOSITORY || (mode === "rest" || !cliOk() ? gitRemoteSlug("github.com") : undefined);
   if (mode === "rest") {
     if (!token) return { transport: "rest", api, reason: "no GitHub token — set GH_TOKEN or GITHUB_TOKEN" };
     if (!repo) return { transport: "rest", api, token, reason: "no repository — set GITHUB_REPOSITORY (owner/name) or ULTRA11Y_GITHUB_REPO" };
     return { transport: "rest", api, token, repo };
   }
   // auto: the CLI first (it owns its auth), then REST, then say what BOTH were missing.
-  if (cliOk) return { transport: "cli", api };
+  if (cliOk()) return { transport: "cli", api };
   if (token && repo) return { transport: "rest", api, token, repo };
   const missing = [!token ? "a token (GH_TOKEN/GITHUB_TOKEN)" : "", !repo ? "a repository (GITHUB_REPOSITORY)" : ""].filter(Boolean);
   return {

package/src/types.ts

@@ -1,6 +1,6 @@
 // Single source of truth for shared types + the embedded version. sync-version.mjs
 // rewrites VERSION at release time (kept in lockstep with package.json + SKILL.md).
-export const VERSION = "4.1.0";
+export const VERSION = "4.2.0";
 export const SCHEMA_VERSION = 2;
 
 // Lang = the UI FRAME's language — the `L` localization tables each module (report,