automatica11y 0.3.3 → 0.4.0

package/src/report/parts.js

@@ -1,3 +1,4 @@
+import { adapterFor } from "../frameworks/index.js";
 import { criterion, criterionName, wcagAttribution } from "../wcag/index.js";
 import { cap, num, plural } from "../text.js";
 
@@ -9,7 +10,7 @@ export const sentence = (text) => String(text).replace(/\.+$/, "");
 /** Escape angle brackets so rule text like <input> doesn't turn into HTML. */
 export const esc = (text) => String(text ?? "").replace(/</g, "\\<");
 export const ENGINE_NAMES = { axe: "axe-core", ibm: "IBM Equal Access" };
-export const TIER_NAMES = { rules: "Rules", interactions: "Interactions", computed: "Computed checks", vsr: "Virtual screen reader" };
+export const TIER_NAMES = { rules: "Rules", interactions: "Interactions", computed: "Computed checks", conditions: "Conditions", vsr: "Virtual screen reader" };
 
 export function toolLines(tools) {
   return Object.entries(tools)
@@ -28,8 +29,8 @@ export function engineCell(summary, engine) {
 export function tierCell(target, tier) {
   const counts = target.summary?.interactions;
   const vsr = target.summary?.vsr;
-  const measured = target.summary?.computed;
-  if (tier === "computed" && measured) {
+  const measured = target.summary?.[tier];
+  if ((tier === "computed" || tier === "conditions") && measured) {
     const parts = [measured.fail && `${num(measured.fail)} failed`, measured.undetermined && `${num(measured.undetermined)} undetermined`, measured.error && plural(measured.error, "error"), measured.pass && `${num(measured.pass)} passed`, measured.notApplicable && `${num(measured.notApplicable)} not applicable`].filter(Boolean);
     return `ran, ${parts.join(", ")}`;
   }
@@ -220,8 +221,14 @@ export function criteriaCell(list) {
   }).join(", ");
 }
 
-export function computedSection(result, nested) {
-  const lines = [`${nested ? "#####" : "####"} Computed checks.`, "", "automatica11y's own measurements from resolved styles in the browser, with the numbers WCAG gives. They're reported on their own and never added to the axe-core or IBM Equal Access counts. A check that can't reduce the page to colors (a gradient, an image, transparency) is undetermined, which counts as a gap and never as a pass.", ""];
+const MEASURED_INTRO = {
+  computed: ["Computed checks", "automatica11y's own measurements from resolved styles in the browser, with the numbers WCAG gives. They're reported on their own and never added to the axe-core or IBM Equal Access counts. A check that can't reduce the page to colors (a gradient, an image, transparency) is undetermined, which counts as a gap and never as a pass."],
+  conditions: ["Conditions", "automatica11y's own checks of how the page holds up under a user's settings (reduced motion, dark mode, more or less contrast, reduced transparency, forced colors) and environment (a 320 pixel window, wider text spacing). Each check opens fresh copies of the page. They're reported on their own and never added to the axe-core or IBM Equal Access counts. A check that can't tell is undetermined, which counts as a gap and never as a pass. \"Not applicable\" means the page doesn't use the feature, which isn't a failure."],
+};
+
+export function measuredSection(tier, result, nested) {
+  const [title, intro] = MEASURED_INTRO[tier];
+  const lines = [`${nested ? "#####" : "####"} ${title}.`, "", intro, ""];
   lines.push("| Check | Result | WCAG | Detail |", "| --- | --- | --- | --- |");
   for (const check of result.checks) {
     lines.push(`| ${code(check.name)} | ${check.result} | ${cell(criteriaCell(check.criteria))} | ${cell(check.detail)}${check.method ? cell(` (method: ${check.method})`) : ""} |`);
@@ -235,17 +242,33 @@ export function configLabel(config) {
   return parts.length ? ` (${parts.join(", ")})` : "";
 }
 
+/** What the Fixture column says about where a fixture came from. */
+function fixtureLabel(archetype) {
+  const f = archetype.fixture;
+  if (!f || f.source === "none") return "-";
+  return f.source === "generated" ? `generated (${f.recipe})` : f.source;
+}
+
 export function archetypeTable(target) {
   const rows = Object.entries(target.archetypes).map(([name, archetype]) => {
-    if (archetype.status === "gap") return `| ${name} | gap | - | ${cell(sentence(archetype.reason ?? "No fixture."))} |`;
+    if (archetype.status === "gap") return `| ${name} | gap | ${fixtureLabel(archetype)} | - | ${cell(sentence(archetype.reason ?? "No fixture."))} |`;
     const states = [...new Set(archetype.configs.map((c) => c.state).filter(Boolean))].join(", ") || "-";
     const libs = [...new Set(archetype.configs.map((c) => c.libA11y).filter((l) => l && l !== "n/a"))];
-    return `| ${name} | ran | ${states} | ${libs.length ? `library accessibility ${libs.join(" and ")}` : ""} |`;
+    const notes = [libs.length ? `library accessibility ${libs.join(" and ")}` : "", archetype.fixture?.source === "generated" ? `${sentence(archetype.fixture.summary ?? "")}, from ${(archetype.fixture.used ?? []).join(", ")}. Source: ${archetype.fixture.file}` : ""].filter(Boolean);
+    return `| ${name} | ran | ${fixtureLabel(archetype)} | ${states} | ${cell(notes.join(". "))} |`;
   });
-  return ["| Archetype | Status | States | Note |", "| --- | --- | --- | --- |", ...rows];
+  return ["| Archetype | Status | Fixture | States | Note |", "| --- | --- | --- | --- | --- |", ...rows];
 }
 
-export function targetSection(planTarget, target) {
+/** True when any archetype in the results ran from a fixture the tool generated. */
+export function hasGenerated(results) {
+  return results.targets.some((t) => Object.values(t.archetypes ?? {}).some((a) => a.fixture?.source === "generated"));
+}
+
+/** What "generated" means, for any report that has one. */
+export const GENERATED_NOTE = "**Generated fixtures.** Where no fixture was written, the tool built one from the parts the package exports (or from what a custom element says about itself) and ran it only after it checked that the trigger and root behaved. A generated fixture is a guess about how the library is meant to be assembled, so a failure may come from how it was wired and not from the library. Treat generated results as lower evidence than an authored fixture. The source of each is in the `generated` folder beside this report. Copy one to `fixtures/<target id>/<archetype>.jsx` (`.js` for web components) and edit it to make it an authored fixture.";
+
+export function targetSection(planTarget, target, { generatedNote = true } = {}) {
   if (target.status === "ran" && target.storybook) return storybookSection(planTarget, target);
   const lines = [`### ${planTarget.label}.`, ""];
   lines.push(`Target ${code(planTarget.input)}, ${planTarget.kind ?? "unclassified"}${planTarget.evidenceLevel ? `, ${planTarget.evidenceLevel} evidence` : ""}.`, "");
@@ -255,13 +278,14 @@ export function targetSection(planTarget, target) {
   }
   if (target.npm) {
     const n = target.npm;
-    lines.push(`Installed ${code(`${n.name}@${n.version}`)} on its own, as ${n.flavor === "react" ? `React${n.react ? ` (react ${n.react})` : ""}` : `web components (${n.tags.length ? n.tags.slice(0, 6).join(", ") : "no tags found"})`}.`, "");
+    lines.push(`Installed ${code(`${n.name}@${n.version}`)} on its own${n.subpath ? ` and tested its ${code(`${n.name}/${n.subpath}`)} entry` : ""}, as ${adapterFor(n.flavor).describe(n)}.`, "");
   }
   for (const warning of target.warnings) lines.push(`Warning: ${warning}`, "");
   if (target.status === "failed") {
     lines.push(`This target failed: ${sentence(target.reason)}. A failed target is a gap in coverage. It isn't a pass.`, "");
   }
   if (target.npm) lines.push("**Archetypes.** A gap means the archetype wasn't tested, so it counts against coverage and never as a pass.", "", ...archetypeTable(target), "");
+  if (generatedNote && target.npm && hasGenerated({ targets: [target] })) lines.push(GENERATED_NOTE, "");
   /** @type {Set<string>} */
   const skipped = new Set();
   for (const [name, archetype] of Object.entries(target.archetypes)) {
@@ -274,8 +298,8 @@ export function targetSection(planTarget, target) {
           lines.push(vsrSection(result, name !== "page"), "");
         } else if (tier === "interactions" && result.status === "ran") {
           lines.push(interactionsSection(result, name !== "page"), "");
-        } else if (tier === "computed" && result.status === "ran") {
-          lines.push(computedSection(result, name !== "page"), "");
+        } else if ((tier === "computed" || tier === "conditions") && result.status === "ran") {
+          lines.push(measuredSection(tier, result, name !== "page"), "");
         } else if (result.status !== "ran") {
           skipped.add(`${TIER_NAMES[tier] ?? tier}: ${sentence(result.reason ?? result.status)}.`);
         }

package/src/run/audit-npm.js

@@ -2,15 +2,19 @@ import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { bundleEntries } from "../harness/bundle.js";
-import { installOptionalPeers, installPackage } from "../harness/npm-install.js";
-import * as react from "../harness/npm-react.js";
-import * as wc from "../harness/npm-wc.js";
+import { GENERATABLE } from "../harness/generate/index.js";
+import { generateFixture } from "./generate-fixture.js";
+import { settleAnimations } from "../harness/settle.js";
+import { installExtraPackages, installOptionalPeers, installPackage } from "../harness/npm-install.js";
+import { adapterFor, adapterForKind } from "../frameworks/index.js";
+import { subpathProblem } from "../plan/subpath.js";
 import { closedShadowHosts, notTestableEntries } from "../harness/shadow.js";
 import { serveStatic } from "../harness/static-serve.js";
 import { openPage } from "../harness/url.js";
 import { candidateMapping, findAuthoredFixture } from "../plan/mapping.js";
 import { ARCHETYPES } from "../schema.js";
 import { runComputed } from "../tiers/computed/index.js";
+import { runConditions } from "../tiers/conditions/index.js";
 import { runInteractions } from "../tiers/interactions/index.js";
 import { runRules } from "../tiers/rules/index.js";
 import { failedVsr, runVsr } from "../tiers/vsr.js";
@@ -24,6 +28,7 @@ const STATES = {
   tooltip: ["closed", "open"],
   combobox: ["closed", "open"],
   accordion: ["collapsed", "expanded"],
+  "live-region": ["before message", "message shown"],
 };
 
 const firstLine = (error) => (error instanceof Error ? error.message : String(error)).split("\n").find((l) => l.trim()) ?? "unknown error";
@@ -59,10 +64,10 @@ async function bundleWithPeers(options, warnings) {
 
 /** Load the whole package in a page to list its exports and the custom elements it defines. */
 async function discover({ browser, workDir, flavor, pkg, buildDir, warnings }) {
-  const helper = flavor === "react" ? react : wc;
+  const adapter = adapterFor(flavor);
   const entryFile = join(workDir, "discover.js");
-  writeFileSync(entryFile, helper.discoverEntry(pkg));
-  await bundleWithPeers({ entries: { discover: entryFile }, outdir: buildDir, workDir, react: flavor === "react" }, warnings);
+  writeFileSync(entryFile, adapter.discoverEntry(pkg));
+  await bundleWithPeers({ entries: { discover: entryFile }, outdir: buildDir, workDir, framework: adapter }, warnings);
   const server = await serveStatic(buildDir);
   const errors = [];
   try {
@@ -74,8 +79,31 @@ async function discover({ browser, workDir, flavor, pkg, buildDir, warnings }) {
     }
     const exportsList = await opened.page.evaluate(() => /** @type {any} */ (window).__a11yExports);
     const tags = await opened.page.evaluate(() => [.../** @type {any} */ (window).__a11yDefined ?? []]);
+    // What each element says about itself, so a fixture can be built around it: observed attributes, class members, slots.
+    const facts = await opened.page.evaluate((names) => {
+      const out = {};
+      for (const name of names.slice(0, 80)) {
+        const Element = customElements.get(name);
+        if (!Element) continue;
+        const members = new Set();
+        for (let proto = Element.prototype; proto && proto !== HTMLElement.prototype && proto !== Object.prototype; proto = Object.getPrototypeOf(proto)) {
+          for (const key of Object.getOwnPropertyNames(proto)) if (!key.startsWith("_") && key !== "constructor") members.add(key);
+        }
+        let slots = [];
+        try {
+          const el = document.createElement(name);
+          document.body.append(el);
+          slots = [...(el.shadowRoot?.querySelectorAll("slot") ?? [])].map((slot) => slot.getAttribute("name") ?? "");
+          el.remove();
+        } catch {
+          // An element that can't be created on its own has no slots to report.
+        }
+        out[name] = { attributes: [.../** @type {any} */ (Element).observedAttributes ?? []], members: [...members], slots: slots.filter(Boolean) };
+      }
+      return out;
+    }, tags);
     await opened.close();
-    return { exports: exportsList, tags };
+    return { exports: exportsList, tags, facts };
   } finally {
     await server.close();
   }
@@ -96,6 +124,9 @@ async function auditFixturePage({ browser, url, archetype, plan, libA11y }) {
     if (count !== 1) return { gap: `The fixture must mark exactly one data-a11y-trigger. It marked ${num(count)}.` };
     if (errors.length) return { gap: `The fixture logged errors when it mounted: ${errors[0]}` };
 
+    if (archetype === "live-region" && (await trigger.first().evaluate((el) => el.matches("[data-a11y-root]")))) {
+      return { gap: "The fixture marks the same element as the trigger and the message. A live-region fixture needs a control that makes the message appear (data-a11y-trigger) and the message itself (data-a11y-root)." };
+    }
     const states = STATES[archetype] ?? ["initial"];
     const configs = [];
     for (const [index, state] of states.entries()) {
@@ -105,23 +136,25 @@ async function auditFixturePage({ browser, url, archetype, plan, libA11y }) {
           if (archetype === "tooltip") await trigger.first().focus();
           else await trigger.first().click();
           await opened.page.waitForFunction(
-            () => {
+            (needsText) => {
               const root = document.querySelector("[data-a11y-root]");
               const shown = root && /** @type {HTMLElement} */ (root).getClientRects().length > 0;
+              // A live region can be on the page and empty until the trigger fills it, so wait for the message itself.
+              if (needsText) return Boolean(shown && ((root.textContent ?? "").trim() || root.getAttribute("aria-label") || root.getAttribute("aria-labelledby")));
               return shown || document.querySelector('[data-a11y-trigger][aria-expanded="true"]') !== null;
             },
-            undefined,
+            archetype === "live-region",
             { timeout: 3000 },
           );
         } catch {
           failure = `The ${state} state never appeared after activating the trigger. A fixture's data-a11y-root has to show up when the ${archetype} opens.`;
         }
       }
-      await opened.page.evaluate(() => new Promise((done) => requestAnimationFrame(() => requestAnimationFrame(done))));
+      await settleAnimations(opened.page);
       /** @type {Record<string, any>} */
       const tiers = {};
       for (const tier of plan.options.tiers) {
-        if (tier === "interactions" || tier === "computed") continue;
+        if (tier === "interactions" || tier === "computed" || tier === "conditions") continue;
         if (tier === "vsr") tiers.vsr = failure ? { status: "skipped", simulated: true, reason: failure } : await runVsr(opened.page, { scope: "body", state }).catch(failedVsr);
         else if (failure) tiers.rules = { status: "failed", reason: failure, engines: Object.fromEntries(plan.options.engines.map((e) => [e, { status: "failed", reason: failure }])) };
         else {
@@ -135,6 +168,7 @@ async function auditFixturePage({ browser, url, archetype, plan, libA11y }) {
     // The checks open their own fresh pages, so run them after this page's rules results are in.
     if (plan.options.tiers.includes("interactions")) configs[0].tiers.interactions = await runInteractions(browser, libA11y === "n/a" ? url : `${url}?libA11y=${libA11y}`, archetype);
     if (plan.options.tiers.includes("computed")) configs[0].tiers.computed = await runComputed(browser, libA11y === "n/a" ? url : `${url}?libA11y=${libA11y}`, archetype);
+    if (plan.options.tiers.includes("conditions")) configs[0].tiers.conditions = await runConditions(browser, libA11y === "n/a" ? url : `${url}?libA11y=${libA11y}`, archetype);
     return { configs, hidden };
   } finally {
     await opened.close();
@@ -161,14 +195,14 @@ async function auditFixture({ browser, url, archetype, plan, toggle }) {
 /**
  * Audit an npm package: install it on its own, find what it exports, and audit each archetype that has a fixture.
  * An archetype without a usable fixture is a gap with a reason, never a pass.
- * @returns {Promise<{ result: any, mapping: Record<string, any> | null }>}
+ * @returns {Promise<{ result: any, mapping: Record<string, any> | null, files?: Record<string, string> }>}
  */
 export async function auditNpm({ browser, planTarget, plan, cwd, install = installPackage }) {
   install ??= installPackage;
   const base = { id: planTarget.id, reason: null, archetypes: {}, summary: { engines: {}, gaps: [], notTestable: [] }, warnings: [] };
   const resolved = planTarget.resolved ?? {};
   if (planTarget.kind === "npm-unsupported") {
-    return { result: { ...base, status: "unsupported", reason: `${resolved.framework ?? "This framework"} packages aren't supported. v1 covers React and web components.` }, mapping: null };
+    return { result: { ...base, status: "unsupported", reason: `${resolved.framework ?? "This framework"} packages aren't supported. This version covers React, Vue 3, and web components.` }, mapping: null };
   }
   const tmp = mkdtempSync(join(tmpdir(), "automatica11y-npm-"));
   const workDir = join(tmp, "install");
@@ -177,22 +211,33 @@ export async function auditNpm({ browser, planTarget, plan, cwd, install = insta
   mkdirSync(fixtureDir, { recursive: true });
   const servers = [];
   try {
-    /** @type {"react" | "wc" | "unknown"} */
-    let flavor = planTarget.kind === "npm-react" ? "react" : planTarget.kind === "npm-wc" ? "wc" : "unknown";
+    /** The framework's id (react, vue, or wc), or "unknown" when the metadata couldn't say. */
+    /** @type {any} */
+    let flavor = adapterForKind(planTarget.kind)?.id ?? "unknown";
     const installed = await install({ dir: workDir, name: resolved.name, version: resolved.version, flavor });
     const warnings = [...installed.warnings];
+    // What fixtures and templates import: the package, or the sub-path of it that was asked for.
+    const importSpec = resolved.subpath ? `${resolved.name}/${resolved.subpath}` : resolved.name;
+    if (resolved.subpath) {
+      const problem = subpathProblem(workDir, resolved.name, resolved.subpath, installed.version ?? resolved.version);
+      if (problem) throw new Error(problem);
+    }
 
-    const found = await discover({ browser, workDir, flavor: flavor === "react" ? "react" : "wc", pkg: resolved.name, buildDir, warnings });
+    // Packages the mapping names (a token stylesheet, a theme) go in beside the library, so a fixture can import them.
+    const extras = await installExtraPackages({ dir: workDir, specs: Object.values(planTarget.mapping ?? {}).flatMap((entry) => entry.install ?? []) });
+    warnings.push(...extras.warnings);
+
+    const found = await discover({ browser, workDir, flavor: flavor === "unknown" ? "wc" : flavor, pkg: importSpec, buildDir, warnings });
     if (flavor === "unknown") {
       if (found.tags.length > 0) flavor = "wc";
       else if (installed.react && found.exports.some((e) => /^[A-Z]/.test(e.name))) flavor = "react";
     }
     if (flavor === "unknown" || (flavor === "wc" && found.tags.length === 0)) {
-      return { result: { ...base, status: "not-applicable", reason: "The package has no rendering surface. It exports no React components and defines no custom elements.", warnings }, mapping: null };
+      return { result: { ...base, status: "not-applicable", reason: "The package has no rendering surface. It exports no components for a supported framework and defines no custom elements.", warnings }, mapping: null };
     }
 
     const candidates = candidateMapping({ flavor, exports: found.exports, tags: found.tags });
-    const kindFlavor = /** @type {"react" | "wc"} */ (flavor);
+    const adapter = adapterFor(flavor);
     const wanted = plan.options.archetypes ?? ARCHETYPES;
     /** @type {Record<string, any>} */
     const mapping = {};
@@ -200,7 +245,20 @@ export async function auditNpm({ browser, planTarget, plan, cwd, install = insta
     const archetypes = {};
     const gaps = [];
     const hidden = [];
-    const helper = flavor === "react" ? react : wc;
+    /** Files to write beside the report: the fixtures the tool generated, so they can be reviewed and adopted. */
+    const files = {};
+    /** Where each archetype's fixture came from, for the results. */
+    const sources = {};
+    /** One server for the probes, started when the first one is needed. */
+    let probeServer = null;
+    const getServer = async () => {
+      if (!probeServer) {
+        mkdirSync(buildDir, { recursive: true });
+        probeServer = await serveStatic(buildDir);
+        servers.push(probeServer);
+      }
+      return probeServer;
+    };
 
     // Decide where each archetype's fixture comes from, then bundle each one on its own so one bad fixture can't break the rest.
     const runnable = {};
@@ -218,29 +276,57 @@ export async function auditNpm({ browser, planTarget, plan, cwd, install = insta
         entry.status = "needs-fixture";
         entry.reason = `The mapping names ${user.fixture}, but that file doesn't exist.`;
       } else if (entry.status === "template" || (user.export || user.tag) && ["button", "link"].includes(archetype)) {
-        const source = flavor === "react" ? react.template(archetype, resolved.name, entry.export) : wc.template(archetype, entry.tag);
+        const source = adapter.template(archetype, importSpec, flavor === "wc" ? entry.tag : entry.export);
         if (source) {
           entry.status = "template";
           delete entry.reason;
-          fixture = join(fixtureDir, `${archetype}.${flavor === "react" ? "jsx" : "js"}`);
+          fixture = join(fixtureDir, `${archetype}.${adapter.extension}`);
           writeFileSync(fixture, source);
         }
       }
+      /** @type {any} */
+      let source = fixture ? { source: entry.status === "authored" ? "authored" : "template" } : null;
+      let attempts = [];
+      let generationTried = false;
+      // Nothing authored and no template: build candidates from what the package exports, and keep one only if it works.
+      if (!fixture && !user.fixture && plan.options.generate !== false && GENERATABLE.has(archetype) && !(entry.status === "no-match" && flavor === "wc")) {
+        const generated = await generateFixture({ browser, adapter, archetype, entry, found, explicit: Boolean(user.export), pkg: importSpec, tmp, workDir, buildDir, getServer, bundle: (options) => bundleWithPeers(options, warnings) });
+        attempts = generated.attempts;
+        generationTried = attempts.length > 0;
+        if (generated.ok && generated.winner) {
+          const { winner } = generated;
+          const relative = `generated/${planTarget.id}/${archetype}.${winner.extension}`;
+          files[relative] = winner.source;
+          fixture = winner.file;
+          entry.status = "generated";
+          entry.recipe = winner.recipe;
+          entry.summary = winner.summary;
+          entry.used = winner.used;
+          entry.generatedFile = relative;
+          delete entry.reason;
+          source = { source: "generated", recipe: winner.recipe, summary: winner.summary, used: winner.used, file: relative, attempts };
+        } else if (generated.reason && (generationTried || entry.status !== "no-match")) {
+          entry.reason = `${entry.status === "no-match" ? "" : `${entry.reason ?? `The ${archetype} archetype needs a fixture someone writes.`} `}Generating one didn't work. ${generated.reason}`.trim();
+        }
+      }
       mapping[archetype] = entry;
       if (!fixture) {
-        const reason = entry.status === "no-match" ? entry.reason : entry.reason ?? `The ${archetype} archetype needs a fixture someone writes.`;
-        archetypes[archetype] = { status: "gap", reason: archetype && entry.status !== "no-match" ? `${reason} Write fixtures/${planTarget.id}/${archetype}.${flavor === "react" ? "jsx" : "js"}.` : reason, configs: [] };
+        // A no-match archetype has no component to write a fixture for, unless a generator looked and said why it couldn't build one.
+        const writable = entry.status !== "no-match" || generationTried;
+        const reason = entry.reason ?? `The ${archetype} archetype needs a fixture someone writes.`;
+        archetypes[archetype] = { status: "gap", reason: writable ? `${reason} Write fixtures/${planTarget.id}/${archetype}.${adapter.extension}.` : reason, configs: [], ...(attempts.length ? { fixture: { source: "none", attempts } } : {}) };
         gaps.push(`archetype:${archetype}`);
         continue;
       }
       const entryFile = join(tmp, "entries", `${archetype}-entry.js`);
       mkdirSync(join(tmp, "entries"), { recursive: true });
-      writeFileSync(entryFile, helper.entry(fixture, resolved.name));
+      writeFileSync(entryFile, adapter.entry(fixture, importSpec));
       try {
-        await bundleWithPeers({ entries: { [archetype]: entryFile }, outdir: buildDir, workDir, react: flavor === "react" }, warnings);
+        await bundleWithPeers({ entries: { [archetype]: entryFile }, outdir: buildDir, workDir, framework: adapter }, warnings);
         runnable[archetype] = `/${archetype}.html`;
+        sources[archetype] = source;
       } catch (error) {
-        archetypes[archetype] = { status: "gap", reason: `The fixture didn't bundle. ${firstLine(error)}`, configs: [] };
+        archetypes[archetype] = { status: "gap", reason: `The fixture didn't bundle. ${firstLine(error)}`, configs: [], ...(attempts.length ? { fixture: { source: "none", attempts } } : {}) };
         gaps.push(`archetype:${archetype}`);
         entry.status = "needs-fixture";
         entry.reason = firstLine(error);
@@ -253,13 +339,14 @@ export async function auditNpm({ browser, planTarget, plan, cwd, install = insta
       for (const [archetype, path] of Object.entries(runnable)) {
         /** @type {any} */
         const outcome = await auditFixture({ browser, url: `${live.origin}${path}`, archetype, plan, toggle: mapping[archetype].libA11y === true }).catch((error) => ({ gap: firstLine(error) }));
+        const fixtureInfo = sources[archetype];
         if (outcome.gap) {
-          archetypes[archetype] = { status: "gap", reason: outcome.gap, configs: [] };
+          archetypes[archetype] = { status: "gap", reason: outcome.gap, configs: [], ...(fixtureInfo?.attempts?.length ? { fixture: { source: "none", attempts: fixtureInfo.attempts } } : {}) };
           gaps.push(`archetype:${archetype}`);
           mapping[archetype].status = "needs-fixture";
           mapping[archetype].reason = outcome.gap;
         } else {
-          archetypes[archetype] = { status: "ran", configs: outcome.configs };
+          archetypes[archetype] = { status: "ran", configs: outcome.configs, ...(fixtureInfo ? { fixture: fixtureInfo } : {}) };
           hidden.push(...outcome.hidden.map((h) => `${archetype}: ${h}`));
         }
       }
@@ -275,11 +362,13 @@ export async function auditNpm({ browser, planTarget, plan, cwd, install = insta
         archetypes: ordered,
         npm: {
           name: resolved.name,
+          subpath: resolved.subpath ?? null,
           version: installed.version ?? resolved.version,
           flavor,
           framework: resolved.framework ?? null,
           react: installed.react,
           reactDom: installed.reactDom,
+          vue: installed.vue ?? null,
           tags: flavor === "wc" ? found.tags : [],
         },
         summary: (() => {
@@ -289,6 +378,7 @@ export async function auditNpm({ browser, planTarget, plan, cwd, install = insta
         warnings,
       },
       mapping: Object.fromEntries(Object.entries(mapping).map(([k, v]) => [k, { ...v, fixture: v.fixture ?? null }])),
+      files,
     };
   } finally {
     for (const s of servers) await s.close();

package/src/run/generate-fixture.js

@@ -0,0 +1,74 @@
+import { mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { probeFixture } from "../harness/generate/probe.js";
+
+const firstLine = (error) => (error instanceof Error ? error.message : String(error)).split("\n").find((l) => l.trim()) ?? "unknown error";
+
+/**
+ * Build a fixture for an archetype from what discovery found, and keep it only if it works.
+ * Candidates are bundled (all at once, or one by one if that fails), then probed in the browser in order. The first that
+ * passes wins. Every attempt is recorded, whether or not one wins, so a report can say what was tried.
+ *
+ * @param {{
+ *   browser: import("playwright-core").Browser,
+ *   adapter: import("../frameworks/index.js").Adapter,
+ *   archetype: string,
+ *   entry: { export?: string, tag?: string },
+ *   found: { exports: any[], tags: string[], facts: Record<string, any> },
+ *   pkg: string,
+ *   explicit?: boolean,
+ *   tmp: string,
+ *   workDir: string,
+ *   buildDir: string,
+ *   getServer: () => Promise<{ origin: string }>,
+ *   bundle: (options: any) => Promise<unknown>,
+ * }} input
+ * @returns {Promise<{ ok: boolean, reason: string | null, attempts: Array<{ recipe: string, summary: string, ok: boolean, reason: string | null }>, winner?: { recipe: string, summary: string, used: string[], source: string, file: string, extension: string } }>}
+ */
+export async function generateFixture({ browser, adapter, archetype, entry, found, explicit = false, pkg, tmp, workDir, buildDir, getServer, bundle }) {
+  const { candidates, reason } = adapter.generate({ archetype, pkg, entry, exports: found.exports, facts: found.facts, explicit });
+  if (candidates.length === 0) return { ok: false, reason, attempts: [] };
+
+  const extension = adapter.extension;
+  mkdirSync(join(tmp, "generated"), { recursive: true });
+  mkdirSync(join(tmp, "entries"), { recursive: true });
+  const prepared = candidates.map((candidate, index) => {
+    const name = `gen-${archetype}-${index}`;
+    const file = join(tmp, "generated", `${archetype}-${index}.${extension}`);
+    writeFileSync(file, candidate.source);
+    const entryFile = join(tmp, "entries", `${name}.js`);
+    writeFileSync(entryFile, adapter.entry(file, pkg));
+    return { candidate, name, file, entryFile, bundled: null };
+  });
+
+  // One build for every candidate. If a single bad one breaks it, build them one by one so the rest still get a chance.
+  try {
+    await bundle({ entries: Object.fromEntries(prepared.map((p) => [p.name, p.entryFile])), outdir: buildDir, workDir, framework: adapter });
+    for (const p of prepared) p.bundled = true;
+  } catch {
+    for (const p of prepared) {
+      try {
+        await bundle({ entries: { [p.name]: p.entryFile }, outdir: buildDir, workDir, framework: adapter });
+        p.bundled = true;
+      } catch (error) {
+        p.bundled = firstLine(error);
+      }
+    }
+  }
+
+  const server = await getServer();
+  const attempts = [];
+  for (const p of prepared) {
+    const base = { recipe: p.candidate.id, summary: p.candidate.summary };
+    if (p.bundled !== true) {
+      attempts.push({ ...base, ok: false, reason: `it didn't bundle: ${p.bundled}` });
+      continue;
+    }
+    const probe = await probeFixture(browser, `${server.origin}/${p.name}.html`, archetype);
+    attempts.push({ ...base, ok: probe.ok, reason: probe.reason });
+    if (probe.ok) {
+      return { ok: true, reason: null, attempts, winner: { ...base, used: p.candidate.used, source: p.candidate.source, file: p.file, extension } };
+    }
+  }
+  return { ok: false, reason: `${attempts.length === 1 ? "The one generated fixture didn't work" : `None of the ${attempts.length} generated fixtures worked`}. ${attempts.slice(0, 2).map((a) => `${a.summary}: ${a.reason}`).join("; ")}${attempts.length > 2 ? `; and ${attempts.length - 2} more` : ""}.`, attempts };
+}

package/src/run/run-plan.js

@@ -7,6 +7,7 @@ import { serveStatic } from "../harness/static-serve.js";
 import { listStories, readIndex, selectStories, storyUrl, waitForStory } from "../harness/storybook.js";
 import { closedShadowHosts, notTestableEntries } from "../harness/shadow.js";
 import { COMPUTED_NOT_APPLICABLE_FOR_PAGES } from "../tiers/computed/index.js";
+import { CONDITIONS_NOT_APPLICABLE_FOR_STORIES, runConditions } from "../tiers/conditions/index.js";
 import { NOT_APPLICABLE_FOR_PAGES } from "../tiers/interactions/index.js";
 import { failedVsr, runVsr } from "../tiers/vsr.js";
 import { openPage } from "../harness/url.js";
@@ -17,6 +18,7 @@ import { runRules, selfTest } from "../tiers/rules/index.js";
 import { evaluateFailCheck } from "./fail-check.js";
 import { mapPool } from "./pool.js";
 import { auditNpm } from "./audit-npm.js";
+import { adapterFor } from "../frameworks/index.js";
 import { failedTarget, summarize } from "./summary.js";
 
 /** How many stories to audit at once. */
@@ -24,7 +26,7 @@ const STORY_CONCURRENCY = 4;
 
 const EXIT = { OK: 0, FAIL_THRESHOLD: 1, ENVIRONMENT: 3, ALL_TARGETS_FAILED: 4 };
 
-const NPM_KINDS = new Set(["npm", "npm-react", "npm-wc", "npm-unsupported"]);
+const NPM_KINDS = new Set(["npm", "npm-react", "npm-vue", "npm-wc", "npm-unsupported"]);
 const UNSUPPORTED_KIND = (kind) => `${kind} targets aren't supported.`;
 
 /** Audit one page and return its target result. */
@@ -40,6 +42,9 @@ async function auditPage(browser, url, planTarget, plan, extraWarnings) {
         tiers.interactions = NOT_APPLICABLE_FOR_PAGES;
       } else if (tier === "computed") {
         tiers.computed = COMPUTED_NOT_APPLICABLE_FOR_PAGES;
+      } else if (tier === "conditions") {
+        // Each check opens its own copies of the page, so this runs while the first page is still open.
+        tiers.conditions = await runConditions(browser, url, "page");
       } else {
         tiers.vsr = await runVsr(opened.page, { scope: "body" }).catch(failedVsr);
       }
@@ -76,7 +81,9 @@ async function auditStory(browser, base, story, plan) {
             ? NOT_APPLICABLE_FOR_PAGES
             : tier === "computed"
               ? COMPUTED_NOT_APPLICABLE_FOR_PAGES
-              : await runVsr(opened.page, { scope: "#storybook-root" }).catch(failedVsr);
+              : tier === "conditions"
+                ? CONDITIONS_NOT_APPLICABLE_FOR_STORIES
+                : await runVsr(opened.page, { scope: "#storybook-root" }).catch(failedVsr);
     }
     const hidden = notTestableEntries(await closedShadowHosts(opened.page));
     return { id: story.id, ok: true, archetype: { status: "ran", configs: [{ libA11y: "n/a", tiers }] }, hidden };
@@ -222,14 +229,17 @@ export async function runPlan(plan, io) {
     }
     const targets = [];
     const mappings = {};
+    /** Fixtures the tool generated, by path under the output folder. */
+    const generatedFiles = {};
     for (const planTarget of plan.targets) {
-      const { result, mapping } = await runTarget(browser, planTarget, plan, io);
+      const { result, mapping, files } = await runTarget(browser, planTarget, plan, io);
       targets.push(result);
+      if (files) Object.assign(generatedFiles, files);
       if (mapping) {
         mappings[planTarget.id] = mapping;
         planTarget.mapping = mapping;
       }
-      if (result.npm) planTarget.kind = result.npm.flavor === "react" ? "npm-react" : "npm-wc";
+      if (result.npm) planTarget.kind = adapterFor(result.npm.flavor).kind;
     }
 
     const results = parseResults({
@@ -245,6 +255,11 @@ export async function runPlan(plan, io) {
     mkdirSync(outDir, { recursive: true });
     writeFileSync(resolve(outDir, "results.json"), `${JSON.stringify(results, null, 2)}\n`);
     writeFileSync(resolve(outDir, "report.md"), renderReport({ plan, results }));
+    for (const [relative, text] of Object.entries(generatedFiles)) {
+      const file = resolve(outDir, relative);
+      mkdirSync(dirname(file), { recursive: true });
+      writeFileSync(file, text);
+    }
     if (Object.keys(mappings).length > 0) {
       // The candidate mapping, in the shape --mapping reads, so it can be edited and passed back in.
       writeFileSync(resolve(outDir, "mapping.json"), `${JSON.stringify(mappings, null, 2)}\n`);

package/src/run/summary.js

@@ -37,6 +37,11 @@ export function summarize(archetypes, engines, gaps = []) {
     summary.computed = { pass: 0, fail: 0, undetermined: 0, notApplicable: 0, error: 0 };
     for (const check of measured) summary.computed[check.result === "not-applicable" ? "notApplicable" : check.result] += 1;
   }
+  const adapted = Object.values(archetypes).flatMap((a) => a.configs.flatMap((c) => c.tiers.conditions?.checks ?? []));
+  if (adapted.length) {
+    summary.conditions = { pass: 0, fail: 0, undetermined: 0, notApplicable: 0, error: 0 };
+    for (const check of adapted) summary.conditions[check.result === "not-applicable" ? "notApplicable" : check.result] += 1;
+  }
   const walks = Object.entries(archetypes).flatMap(([name, a]) => a.configs.map((c) => ({ name, vsr: c.tiers.vsr })).filter((x) => x.vsr?.status === "ran"));
   if (walks.length) {
     summary.vsr = { walks: walks.length, flagged: walks.reduce((n, w) => n + w.vsr.flags.length, 0) };