automatica11y 0.3.2 → 0.4.0

package/src/run/audit-npm.js

@@ -2,14 +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 { 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";
@@ -23,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";
@@ -40,12 +46,28 @@ function watchErrors(errors) {
   };
 }
 
+/**
+ * Bundle, and if the library needs an optional peer dependency that npm left out, install it and bundle once more.
+ * @param {Parameters<typeof bundleEntries>[0]} options
+ * @param {string[]} warnings Gets a note when peers were installed.
+ */
+async function bundleWithPeers(options, warnings) {
+  try {
+    return await bundleEntries(options);
+  } catch (error) {
+    const added = await installOptionalPeers({ dir: options.workDir, unresolved: error.unresolved ?? [] });
+    if (added.installed.length === 0) throw error;
+    warnings.push(...added.warnings);
+    return bundleEntries(options);
+  }
+}
+
 /** 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 }) {
-  const helper = flavor === "react" ? react : wc;
+async function discover({ browser, workDir, flavor, pkg, buildDir, warnings }) {
+  const adapter = adapterFor(flavor);
   const entryFile = join(workDir, "discover.js");
-  writeFileSync(entryFile, helper.discoverEntry(pkg));
-  await bundleEntries({ entries: { discover: entryFile }, outdir: buildDir, workDir, react: flavor === "react" });
+  writeFileSync(entryFile, adapter.discoverEntry(pkg));
+  await bundleWithPeers({ entries: { discover: entryFile }, outdir: buildDir, workDir, framework: adapter }, warnings);
   const server = await serveStatic(buildDir);
   const errors = [];
   try {
@@ -57,8 +79,31 @@ async function discover({ browser, workDir, flavor, pkg, buildDir }) {
     }
     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();
   }
@@ -79,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()) {
@@ -88,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") 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 {
@@ -117,6 +167,8 @@ async function auditFixturePage({ browser, url, archetype, plan, libA11y }) {
     const hidden = notTestableEntries(await closedShadowHosts(opened.page));
     // 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();
@@ -143,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");
@@ -159,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 });
+    // 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 = {};
@@ -182,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 = {};
@@ -200,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 bundleEntries({ entries: { [archetype]: entryFile }, outdir: buildDir, workDir, react: flavor === "react" });
+        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);
@@ -235,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}`));
         }
       }
@@ -257,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: (() => {
@@ -271,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

@@ -6,6 +6,8 @@ import { launchBrowser } from "../harness/browser.js";
 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";
@@ -16,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. */
@@ -23,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. */
@@ -37,6 +40,11 @@ async function auditPage(browser, url, planTarget, plan, extraWarnings) {
         tiers.rules = await runRules(opened.page, { engines: plan.options.engines, wcag: plan.options.wcag, level: plan.options.level });
       } else if (tier === "interactions") {
         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);
       }
@@ -71,7 +79,11 @@ async function auditStory(browser, base, story, plan) {
           ? await runRules(opened.page, { engines: plan.options.engines, wcag: plan.options.wcag, level: plan.options.level, scope: "#storybook-root" })
           : tier === "interactions"
             ? NOT_APPLICABLE_FOR_PAGES
-            : await runVsr(opened.page, { scope: "#storybook-root" }).catch(failedVsr);
+            : tier === "computed"
+              ? COMPUTED_NOT_APPLICABLE_FOR_PAGES
+              : 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 };
@@ -217,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({
@@ -240,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

@@ -32,6 +32,16 @@ export function summarize(archetypes, engines, gaps = []) {
     summary.interactions = { pass: 0, fail: 0, notApplicable: 0, error: 0 };
     for (const check of checks) summary.interactions[check.result === "not-applicable" ? "notApplicable" : check.result] += 1;
   }
+  const measured = Object.values(archetypes).flatMap((a) => a.configs.flatMap((c) => c.tiers.computed?.checks ?? []));
+  if (measured.length) {
+    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) };

package/src/schema.js

@@ -2,20 +2,20 @@ import * as v from "valibot";
 
 export const WCAG_VERSIONS = ["2.0", "2.1", "2.2"];
 export const LEVELS = ["A", "AA", "AAA"];
-export const TIERS = ["rules", "interactions", "vsr"];
+export const TIERS = ["rules", "interactions", "computed", "conditions", "vsr"];
 export const ENGINES = ["axe", "ibm"];
 export const LIB_A11Y = ["on", "off"];
 export const IMPACTS = ["minor", "moderate", "serious", "critical"];
 export const TOOLKIT_LEVELS = [1, 2, 3];
 export const FAIL_MODES = ["any", "all"];
-export const ARCHETYPES = ["button", "link", "dialog", "menu", "tabs", "combobox", "form-field", "accordion", "tooltip", "chart"];
-export const FLAVORS = ["react", "wc"];
-export const MAPPING_STATUSES = ["template", "authored", "needs-fixture", "no-match"];
+export const ARCHETYPES = ["button", "link", "dialog", "menu", "tabs", "combobox", "form-field", "accordion", "tooltip", "live-region", "chart"];
+export const FLAVORS = ["react", "vue", "wc"];
+export const MAPPING_STATUSES = ["template", "authored", "generated", "needs-fixture", "no-match"];
 
 /** What a candidate mapping says about one archetype of one npm target. */
 export const MappingEntrySchema = v.object({
   flavor: v.optional(v.picklist(FLAVORS)),
-  /** Export name (React) the fixture or template uses. */
+  /** Export name (React or Vue) the fixture or template uses. */
   export: v.optional(v.string()),
   /** Custom element tag (web components) the fixture or template uses. */
   tag: v.optional(v.string()),
@@ -23,7 +23,14 @@ export const MappingEntrySchema = v.object({
   fixture: v.optional(v.nullable(v.string())),
   /** The library ships opt-in accessibility features. The fixture gets `libA11y` (true or false) and `--lib-a11y` runs it both ways. */
   libA11y: v.optional(v.boolean()),
+  /** Other packages to install beside the target, such as the token stylesheet or theme the library asks for. A fixture can then import them. */
+  install: v.optional(v.array(v.string())),
   status: v.optional(v.picklist(MAPPING_STATUSES)),
+  /** For a generated fixture: which recipe worked, what it was, which parts it used, and where its source was written. */
+  recipe: v.optional(v.string()),
+  summary: v.optional(v.string()),
+  used: v.optional(v.array(v.string())),
+  generatedFile: v.optional(v.string()),
   candidates: v.optional(v.array(v.string())),
   parts: v.optional(v.array(v.string())),
   reason: v.optional(v.string()),
@@ -42,7 +49,7 @@ export function parseMappingFile(input) {
   return result.output;
 }
 
-export const TARGET_KINDS = ["npm", "npm-react", "npm-wc", "npm-unsupported", "npm-non-ui", "storybook", "url", "html-file", "static-dir"];
+export const TARGET_KINDS = ["npm", "npm-react", "npm-vue", "npm-wc", "npm-unsupported", "npm-non-ui", "storybook", "url", "html-file", "static-dir"];
 
 const nullableString = v.nullable(v.string());
 
@@ -77,6 +84,8 @@ export const PlanSchema = v.object({
     archetypes: v.nullable(v.array(v.picklist(ARCHETYPES))),
     mapping: nullableString,
     maxStories: v.pipe(v.number(), v.integer(), v.minValue(1)),
+    /** Build fixtures from a package's parts when none is authored. A plan saved before this existed generates. */
+    generate: v.optional(v.boolean(), true),
     out: v.string(),
     fail: v.nullable(FailConfigSchema),
   }),
@@ -136,10 +145,12 @@ const TierResultSchema = v.object({
       v.object({
         name: v.string(),
         criteria: v.optional(v.array(v.string())),
-        result: v.picklist(["pass", "fail", "not-applicable", "error"]),
+        result: v.picklist(["pass", "fail", "undetermined", "not-applicable", "error"]),
         detail: v.string(),
         /** How the focus indicator was detected: computed-style or screenshot. */
         method: v.optional(v.string()),
+        /** The numbers behind a computed check, for example contrast ratios by state. */
+        measurements: v.optional(v.array(v.record(v.string(), v.unknown()))),
       }),
     ),
   ),
@@ -198,6 +209,17 @@ export const TargetResultSchema = v.object({
     v.object({
       status: v.picklist(["ran", "gap"]),
       reason: v.optional(v.nullable(v.string())),
+      /** Where the fixture came from, and for a generated one what was tried. */
+      fixture: v.optional(
+        v.object({
+          source: v.picklist(["template", "authored", "generated", "none"]),
+          recipe: v.optional(v.string()),
+          summary: v.optional(v.string()),
+          used: v.optional(v.array(v.string())),
+          file: v.optional(v.nullable(v.string())),
+          attempts: v.optional(v.array(v.object({ recipe: v.string(), summary: v.string(), ok: v.boolean(), reason: v.nullable(v.string()) }))),
+        }),
+      ),
       configs: v.array(v.object({ libA11y: v.picklist(["on", "off", "n/a"]), state: v.optional(v.string()), tiers: v.record(v.string(), TierResultSchema) })),
     }),
   ),
@@ -205,11 +227,14 @@ export const TargetResultSchema = v.object({
   npm: v.optional(
     v.object({
       name: v.string(),
+      /** The sub-path of the package that was tested, such as `button/v2`, or null for the package itself. */
+      subpath: v.optional(nullableString),
       version: nullableString,
       flavor: v.picklist(FLAVORS),
       framework: nullableString,
       react: nullableString,
       reactDom: nullableString,
+      vue: v.optional(nullableString),
       tags: v.array(v.string()),
     }),
   ),
@@ -218,6 +243,8 @@ export const TargetResultSchema = v.object({
     gaps: v.array(v.string()),
     notTestable: v.array(v.string()),
     interactions: v.optional(v.object({ pass: v.number(), fail: v.number(), notApplicable: v.number(), error: v.number() })),
+    computed: v.optional(v.object({ pass: v.number(), fail: v.number(), undetermined: v.number(), notApplicable: v.number(), error: v.number() })),
+    conditions: v.optional(v.object({ pass: v.number(), fail: v.number(), undetermined: v.number(), notApplicable: v.number(), error: v.number() })),
     vsr: v.optional(v.object({ walks: v.number(), flagged: v.number() })),
   }),
   warnings: v.array(v.string()),